RFC-0002：Aira Interface 与能力发现协议：任务上下文、计划与执行

主文档与完整目录。本分篇与主文档共同构成同一规范，版本、状态与权威以主文档为准；仅拆分阅读结构，条款编号和正文语义不变。

9. Task Capsule：给 AI 的最小充分上下文

9.1 内容

Task Capsule 是绑定 Revision 的只读上下文包：

User Intent Frame
Revision / branch / selection snapshot
Relevant parameters and feature subgraph
Constraints, requirements and active assertions
Resolved semantic references and cardinality
Affected downstream summary
Applicable capability hits and selected contracts
Runtime / grant / budget snapshot
Known ambiguity and missing information
Recent diagnostics and relevant certificates

9.2 Context selection

服务端根据 intent、selection、dependency graph 和 capability types 选择相关子图。默认不包含：

全部 Document JSON；
全部 feature history；
全部 kernel artifacts；
原始 BREP/mesh 大数据；
全量 catalog；
与任务无关的对话；
隐藏 chain-of-thought。

AI 可以通过 model.query 请求扩展 Capsule。扩展必须记录 query 和返回的 Revision binding，避免“看过旧状态却修改新 head”。

9.3 Intent Frame

自然语言、图片和文件先被整理为可见的 Intent Frame：

goal：希望得到什么；
hardRequirements：尺寸、材料、工艺、接口、标准；
softPreferences：外观、成本、简洁性；
scope：允许影响哪些对象；
prohibitedEffects：不得删除、降级或改变的内容；
assumptions：系统暂定但可被用户纠正的解释；
unknowns：阻止安全执行的信息；
acceptanceAssertions：可执行成功条件。

Intent Frame 是任务输入和审计资料，不是 AMIR Revision；其中需要长期保留的设计要求必须显式转成 Parameter、Constraint、Assertion 或 project policy。

9.4 Task Protocol

需要强制执行特定证据链的任务必须同时提供机器可读 Task Protocol，而不是只把顺序写进 system prompt：

requiredDiscoverySequence：事务 effect 前必须成功完成的稳定元操作序列；
requiredCompletionSequence：任务完成前必须存在的 discovery、transaction 与 read-back 证据；
completionAuthority：由 runtime 还是 model 判定结束。

Task Protocol 同时对模型可见并由客户端 authority 执行。若模型在 discovery 未完成时提出事务 effect，客户端不得调用 CAD；应返回 recoverable DISCOVERY_REQUIRED，包含已完成前缀和 nextOperation，让模型在同一 task branch 继续。当 requiredDiscoverySequence 生效时，catalog.describe 只有选择了较早 catalog.search 返回的 capability 才能满足该序列；未收紧时按第 7.1 节自适应通道判定。 completionAuthority=runtime 时，模型 completion 文本不能替代本地 verifier。

Task Protocol 是一次任务的执行约束，不是新几何语义；它引用稳定元操作，不复制 Operation Catalog、AMIR Patch 或 kernel 规则。它只能在第 12 节全局状态机之内收紧要求（如强制显式 discovery 序列），不得放松状态机边界、effect 准入或终态判定；第 7.1 节的自适应 discovery 通道在未被 Task Protocol 收紧时默认可用。

9.5 冻结 compatibility line 的附加 context binding

若一个已冻结 compatibility line 的 Task Capsule 无法完整表达同一 line 后续发现的 runtime/discovery/ response 绑定，禁止原地修改旧 schema，也禁止客户端靠隐式约定补齐。允许发布一个独立、版本化、可哈希的 context envelope，前提是它：

明示旧 Task Capsule 的真实字面量，不把它伪装成新版本；
绑定 interface、AMIR、Operation Catalog、discovery catalog、selected capability contracts、Runtime Snapshot、Session Grant、Task Capsule 和当前 Revision authority；
只补充控制面上下文，不新增 Patch/Operation 语义，不进入 modelHash、RevisionId 或 authoringLockHash；
由所有 authority 端消费同一篡改 corpus，并在任何 effect/provider dispatch 前验证。

Phase 1 Exact 0.2 是首个实例：冻结 Core 0.2 的 Task Capsule literal 为 0.1.0，因此使用 aira.interface.exact-context/0.2.0 显式承认并锁定该事实；未来统一该字段必须发布新 Core line。

10. Plan Protocol

10.1 Plan 与 Patch 分离

Plan 描述“准备怎样完成任务”，Patch 描述“规范模型将发生什么变化”。Plan 可以包含 query、branch、comparison 和 preview 策略；只有 authoring step lower 为 AMIR Patch。

{
  "planId": "plan:sha256:...",
  "baseRevision": "rev:sha256:...",
  "intentFrameHash": "intent:sha256:...",
  "bindings": {
    "operationCatalog": "amir.ops/0.1.0",
    "discoveryCatalogHash": "disc:sha256:...",
    "runtimeSnapshot": "runtime:sha256:...",
    "grantId": "grant:..."
  },
  "steps": [
    {
      "id": "step:resolve-edges",
      "capability": "cap:model.resolveSemanticRef@1",
      "mode": "query",
      "args": {}
    },
    {
      "id": "step:fillet",
      "capability": "cap:exact.fillet@1",
      "mode": "authoring",
      "dependsOn": ["step:resolve-edges"],
      "args": {}
    }
  ],
  "acceptanceAssertions": [],
  "estimatedEffects": [],
  "estimatedRisk": "medium"
}

10.2 静态检查

plan.check 必须验证：

capability/version 存在且未被 snapshot 替换；
输入输出 type flow 与 cardinality；
所有已知 precondition；
read/write scope；
Session Grant 和 approval requirements；
dependency acyclic；
budget upper bound；
representation conversion 和 loss 显式；
expected effects 未超出 Intent Frame scope；
acceptance assertions 可被当前 validator 支持。

静态检查不能证明 kernel 一定成功，但必须在昂贵执行前拒绝所有可判定错误。

10.3 不确定性

Plan 不得使用一个无定义的总置信度掩盖问题。需要分别报告：

intent ambiguity；
reference resolution status；
capability sufficiency；
runtime applicability；
estimated geometric risk；
validation coverage。

任何 blocking unknown 都必须请求信息、增加 query/preview，或返回明确失败。

10.4 单管线紧凑接口与复合计划（Single Pipeline & Composite Plan）

为了彻底解决向模型倾倒巨型 JSON Schema AST 导致的上下文膨胀（此前单次 144 KB）以及繁琐的长回路多步握手：

紧凑步骤签名（Compact Step Signatures）：在 Task Capsule 中，宿主通过轻量 TypeScript 接口声明（COMPACT_STEP_SIGNATURES，约 1.5 KB）暴露所有支持的计划步骤类型签名与参数，替代庞大的 JSON Schema AST，将模型接口前缀体积压缩 99%。
复合计划协议（Composite Plan Protocol）：确立单一管线原则（Single Pipeline）——不维护“简单/复杂”两套系统，不靠猜测几何复杂度做分支路由。系统引导模型首轮直接输出整组原子复合计划（包含程序实体创建、参数绑定、装配放置、基准与几何公差声明、关联图纸等）。
精准局部修补（Targeted Repair）：若复合计划中的某一步骤执行或静态检查失败，宿主事务自动回退，并在拒绝反馈中精准点名失败步骤（failedStep）以及受影响的字段错误，局部按需返回该特定步骤的完整 schema 供单步靶向微调，模型无需回退至漫长的单步长回路。

11. 执行与 observation 闭环

11.1 标准循环

stateDiagram-v2
    [*] --> Observe
    Observe --> Discover
    Discover --> Describe
    Describe --> Plan
    Plan --> Clarify: blocking unknown
    Clarify --> Observe
    Plan --> Propose: static check passes
    Propose --> Preview
    Preview --> Repair: diagnostic / assertion fail
    Repair --> Discover
    Preview --> Validate
    Validate --> Repair: authoritative fail
    Validate --> Commit: pass + policy allows
    Commit --> ReadBack
    ReadBack --> [*]: runtime completion
    Plan --> CannotProceed: no legal action toward goal
    Repair --> CannotProceed: repair cap reached
    CannotProceed --> [*]

一次任务允许多轮 search/query/preview，但每轮都必须绑定 observed Revision。branch head 变化时，旧计划进入 stale，必须显式 rebase 和重新检查。

该循环的每次状态迁移由客户端运行时按第 12 节 Meta-operation Contract 强制，不由模型自证。任务只能以显式终态之一结束：completed（runtime 依据 requiredCompletionSequence 与 final read-back 判定）、 cannotProceed（显式弃权：无合法动作可达目标，或修复轮上限已达）、budgetExhausted、cancelled、 failed。终态由 runtime 判定并写入 trace；模型 completion 文本不是终态依据。

11.2 Observation envelope

所有工具响应使用共同 envelope：

{
  "requestId": "req:...",
  "observedRevision": "rev:sha256:...",
  "status": "success|partial|blocked|failed|stale",
  "data": {},
  "diagnostics": [],
  "effectsObserved": [],
  "artifacts": [],
  "certificateSummary": null,
  "budgets": {
    "consumed": {},
    "remaining": {}
  },
  "nextActions": []
}

nextActions 只能引用 catalog 中注册的 query/repair/approval action，并带完整 precondition；它不是让客户端直接执行任意文本建议。

11.3 Diagnostic repair

每个可修复 diagnostic 应提供：

stable code、phase 和 severity；
affected IDs/refs；
expected/actual typed value；
cause category；
zero or more registered repair capability IDs；
repair 可能扩大/缩小的 scope；
是否需要用户批准。

AI 可以基于 diagnostic 重新发现 capability，但 adapter 禁止私自修改 AMIR 以“自动修好”。

12. 稳定的元操作面与 Meta-operation Contract

Aira Interface v0.1 对模型暴露少量稳定 service operation：

元操作	作用
`interface.manifest`	返回协议版本、taxonomy root、snapshot 与 limits
`catalog.search`	按意图、类型、状态、质量、风险和预算发现能力
`catalog.describe`	获取选中 capability 的完整 contract/guidance
`model.read`	读取 Revision、参数、feature/constraint/certificate 摘要
`model.query`	执行类型化几何、拓扑、lineage、reference 和 impact query；SemanticRef 当前/跨 Revision 解析分别投影为 `resolve` / `resolveAcross` query
`plan.check`	验证 capability composition、权限、预算与 effect scope
`model.proposePatch`	lower 并静态检查 AMIR Patch，不提交
`model.preview`	运行 candidate preview 并返回 diff/diagnostics/artifacts
`model.validate`	authoritative evaluation 与 assertions
`model.commit`	CAS 提交完全绑定的 validated candidate
`model.revert`	创建恢复 Revision 的新事务

实现可以把 read/query 或 transaction 阶段组合成较少 transport tools，但不得合并语义状态或绕过 token/binding。 Core v1 transport projection 继续只暴露已经过 M3 验证的九个元操作：model.query 由类型化 selector 投影到有界 model.read，plan.check 位于受信的 model.proposePatch 入口内。二者仍保留为协议语义，但在独立 Query Compiler / Plan contract 交付前不得为了“表面完整”扩成第十、十一个顶层工具。

12.1 Meta-operation Contract v1

每个元操作在接口协议中携带机器可读契约：前置任务状态、effectClass、幂等性、可逆性、合法后继与可达终态。Core v1 九元操作的 effectClass 分类如下；尚未独立投影的 model.query / plan.check 按 read 语义治理，但不计入当前 transport operation 数量：

元操作	effectClass	幂等性	说明
`interface.manifest`、`catalog.search`、`catalog.describe`、`model.read`	`read`	是	不产生模型或任务分支状态
`model.proposePatch`、`model.preview`	`bufferable`	按 idempotency key	只产生任务本地 Candidate/preview 工件；任务放弃时零写入
`model.validate`	`bufferable`	按完整 binding	产生 validationToken 与证据，不写模型
`model.commit`（task branch）	`reversible`	CAS	写任务分支不可变 Revision；可由新 revert Revision 恢复，不改写历史
`model.commit`（publish 到用户 head）、exporter	`irreversible`	CAS / 一次	越过任务隔离或系统边界；调度上视为不可逆
`model.revert`	`reversible`	按 request	创建恢复 Revision，不删除历史

effectClass 属于本契约与运行时协议，进入 interface protocol version 与 task trace 绑定；它不进入 authoringLockHash、ExecutionManifest 或 Certificate。几何 Operation 的 purity、representation effect 与语义后置条件仍由 Capability Contract（第 4.1、6 节）承载，两者不得互相替代。

12.2 运行时状态机

任务运行时是浏览器/受信 worker 强制执行的有限状态机（第 11.1 节）。模型只能请求操作；是否越过 discovery、授权、Candidate、validation 或 CAS 边界由运行时判定。规范规则：

准入：一个元操作只有位于当前任务状态的合法后继集合内才会被执行；否则返回结构化的可恢复拒绝（如 DISCOVERY_REQUIRED、VALIDATION_REQUIRED），包含已完成前缀与 nextOperation，不调用 CAD authority。
批次归约：provider 单轮返回多个调用时，read 调用可以并行执行；每轮至多执行一个非 read effect，取批内首个，其余作为候选延后并在真实 response 后重规划；含 irreversible effect 的调用永远单步执行并排在任何批次最后。重复 request ID 拒绝。
修复上限：Repair 状态只能由实际 Diagnostic 进入；模型自撰的批评不带对应 Diagnostic 对象不得开启修复轮。运行时强制一个声明的有限修复轮上限（MVP 默认 3），达到上限进入 cannotProceed。
终态显式：第 11.1 节五个终态由 runtime 判定并写入 trace；completed 要求 requiredCompletionSequence 与 final read-back 证据齐备；cannotProceed 是显式弃权，不是失败的委婉写法，二者分开统计。
绑定：Meta-operation Contract 版本、状态迁移序列与批次归约决策进入 task/runtime trace 绑定；一次调度策略升级产生新的 interface protocol/contract 版本，不改写任何已提交 Revision。

12.3 Core v1 实施状态（2026-08-31）

Core projection 已实现 Meta-operation Contract 1.0.0，agent protocol 与 native trace 升至 0.5.0。权威 descriptor 覆盖九个 runtime state × 九个元操作的 81-cell 全矩阵；共享 corpus 含 4 条合法序列、 6 条非法序列、3 条批次归约和 9 个 terminal 判例，并由 contracts、gateway、browser 三端共同消费。非法后继在 CAD authority 前返回结构化拒绝，browser trace 记录实际 scheduled/deferred request 与 operation。机器证据见 Meta-operation Contract v1 验证。

该实现关闭第 22 节第 11 条在 Core 九元操作范围内的工程前置项，但不使本 RFC 整体转为 Accepted； Capability Schema、40–80 capability discovery benchmark、200-task corpus、独立 Query Compiler/ Plan contract 等其余条件仍未完成。历史 M3 0.4.0 trace 保持原样，provider 调用为 0。

13. MCP、SDK 与 `.aira` 的边界

13.1 MCP projection

MCP 适合作为模型客户端 transport，因为它支持 tool discovery、JSON Schema 输入/输出和结构化结果。但 Aira 不应把数千个 CAD operation 平铺为数千个 MCP tools。

默认 MCP server 暴露第 12 节的稳定元操作。具体 operation 是 catalog.search/describe 返回的数据，并通过 plan.check/model.proposePatch 进入事务。这样：

catalog 增长不会让 MCP tools/list 无界扩张；
operation version 与 model session 可以精确绑定；
不依赖模型是否能一次看到完整 tool list；
相同协议可投影到 HTTP/SDK/CLI。

可选的 scoped binding 可以把当前任务选中的 5–20 个 capability 暂时投影为强类型便捷工具，但必须：

绑定 session、Revision、catalog/runtime/grant snapshot；
有 TTL 和数量上限；
不改变 operation semantics；
调用仍产生 plan/Patch，不直接调用 raw kernel；
失效时返回 BOUND_CAPABILITY_STALE，不得静默切换 latest。

13.2 Provider projection binding【已废弃】

本节原本解决一个具体问题：模型供应商能接受的 JSON Schema 子集比 canonical contract 窄。当时给模型的是单个通用工具 aira_invoke，其参数是依赖闭包生成的完整 Core/AMIR 请求 schema，无法直接发给 provider，因此需要一层机械投影，并用 projection binding 记录“发给模型的 schema”与“用于校验的 canonical schema” 之间的对应关系。

该前提已不成立。 当前模型接口是两个专用 AI SDK 工具——aira_compile_exact_plan 与 aira_library_reference——它们的参数 schema 由工具定义直接拥有，本身就是为模型设计的小 schema，不是 canonical AMIR 的投影；provider 格式转换由 AI SDK 承担。因此不存在投影层，也不记录 projection binding。aira_invoke canonical schema 与其 provider-projection 实现（从未被任何调用方消费）已于 2026-09-08 删除。

原规则中仍然成立、且已由现行架构承担的部分：

canonical source 之外不得有手写的第二份合同——现在由“工具定义即唯一 schema 源”满足；
权威校验始终在 Core，模型侧 schema 只是前置过滤——aira_compile_exact_plan 的计划仍须经浏览器编译、静态校验、守恒检查与事务校验才能提交；
exact-byte 信任边界——gateway 只解释一次 provider payload，转发已验证的原字节与 content hash，浏览器 authority 基于同一字节执行权威校验；
provider 身份不进入权威结论——换供应商不得改变任何已提交 Revision 或已签发证书的含义。

13.2.1 未被取代的能力：把合法论域物化进工具 schema【未实现】

原规则 2 有一条能力没有被现行架构取代，只是被绕过了：投影可以逐轮收窄——把当前 Revision 下合法的 Candidate 句柄、body root、参数论域物化为 enum/const，让模型在生成时就被 schema 约束，而不是生成后由宿主拒绝。

当前 ExactCadPlan 的 nodeId、parameterId 等仍是自由字符串（^[A-Za-z0-9._:-]+$），模型可以写出不存在的标识符，只能事后诊断。这与 AMIR §6.1 记录的“可变符号参数” 缺口同源：系统没有把“合法集合”这一信息表达给模型的手段。两者应一并解决，收窄必须满足原规则 2 的约束—— 只能收窄不能放宽，通过收窄后的 schema 不构成语义有效性证据。

13.3 SDK

Rust/TypeScript/Python SDK 类型必须由相同 interface schema 和 AMIR descriptor 生成。SDK convenience method 不得拥有服务端不存在的隐藏写能力。

13.4 `.aira` 和 builder

.aira、TypeScript builder 或 AI 生成的结构化代码是 authoring projection。它们必须 lower 为 canonical AMIR，并通过同一 plan/Patch/transaction 管线。源码可以帮助人和 AI 组合逻辑，但不获得任意文件、网络或 kernel 权限。