RFC-0002：Aira Interface 与能力发现协议

字段	值
状态	Proposed
文档版本	`0.3.0`
创建日期	2026-08-29
最后更新	2026-09-17
兼容性	Proposed 阶段可变；Accepted 后破坏性接口变化需要新主版本或后续 RFC
决策范围	AI 能力发现、模型上下文、计划、事务入口、结构化反馈、MCP/SDK 投影与评估
上游原则	AI 原生工业 CAD 产品宪法
系统边界	RFC-0001
模型规范	AMIR v0.1
研究依据	能力发现、工具调用与可编辑建模论文调研、外部先例扫描
当前实施	Aira Core MVP 实施计划
当前进度	Aira Core MVP 工作进度
长期路线	Aira 长期架构计划

摘要

本 RFC 定义 Aira Interface：面向 AI、人类 UI、CLI、SDK 与插件的统一语义控制面。它解决的核心问题不是“怎样把所有 CAD API 塞给一个模型”，而是：

当能力数从几十增长到几千，并随领域包、几何内核和组织策略持续变化时，任何 AI 如何按需发现能力、判断当前是否适用、形成可检查计划、执行最小事务，并依据结构化证据修正？

本 RFC 提议：

AI 只需稳定理解少量 Aira 元操作和公共能力本体，不需要记住全部 CAD operation；
Aira Interface 由两类互不混写的契约组成：描述 CAD 能力语义的 Capability Contract（第 4–6 节），与描述控制操作前置状态、effect class、幂等性、合法后继和终态的 Meta-operation Contract（第 12 节）；
具体能力通过层级 capability graph、hybrid retrieval 和当前状态 applicability 动态发现；
AMIR Operation Descriptor、AI Capability Profile、Runtime Capability Snapshot 与 Session Grant 分离版本和职责；
每次任务构造有界 Task Capsule，不向模型倾倒整个项目或全部工具；计划步骤采用紧凑 TypeScript 签名（COMPACT_STEP_SIGNATURES）代替巨型 JSON Schema AST；
实行单管线复合计划（Single Pipeline Composite Plan）：首轮由模型直接规划原子复合计划，消除双轨分支，局部失败由宿主精准点名修补；
计划与执行分离，计划引用版本锁定的 capability，写操作只能形成 AMIR Patch；
compiler、solver、kernel、assertion 与 transaction engine 返回统一结构化 observation；
MCP、HTTP、TypeScript SDK 和 .aira 都是 Aira Interface 的投影，不是规范语义本身；
Aira 原生协议直接暴露机器可查询的 capability，不发布、不安装、不加载 Agent Skills 或 Markdown prompt 包来注册、路由、解释或授权建模能力；
自然语言和多模态模型只负责解释意图与提出候选，不拥有最终几何语义和提交权。

1. 决策

1.1 Aira Interface 的定义

Aira Interface 是位于 AI/GUI/CLI 与 AMIR/Model Service 之间的语义控制面，包含：

能力发现与描述；
Revision 绑定的模型读取与查询；
任务上下文裁剪与引用解析；
版本锁定的计划表示与静态检查；
Patch propose/preview/validate/commit/revert；
结构化诊断、修复建议和执行证据；
权限、预算、风险和运行时能力协商；
MCP/SDK/CLI 等 transport projection。

这些职责按两类契约划分，禁止混写：

Capability Contract：四层能力模型与 Capability Descriptor（第 4–6 节），描述 CAD 能力的语义、输入输出、适用条件、表示、风险和 lowering；
Meta-operation Contract：控制面契约（第 12 节），描述每个稳定元操作的前置任务状态、 effectClass、幂等性、可逆性、合法后继与可达终态。

effectClass 与任务状态机属于 Meta-operation Contract 和运行时协议；几何 Operation Descriptor 继续记录 purity、representation effect 和语义后置条件。只有会改变 AMIR 解释、规范化结果或执行语义的字段进入 authoringLockHash；纯控制策略由 interface protocol version、Task Protocol 与 task trace 绑定，一次调度策略升级不得改写任何已提交 Revision 的解释。

它不是：

自然语言到 OCCT/Manifold API 的字符串转义器；
任意代码执行沙箱；
第二套模型事实源；
Three.js scene command API；
将矩阵、向量或 embedding 作为几何语义的“矩阵层”；
要求某个特定 LLM 记忆 Aira 全部能力的 prompt 技巧；
通过安装 Skills、system prompt、Markdown 手册或模型专用工具包构造能力控制面。

1.2 核心判断

AI 不需要“知道所有能力的完整说明”。AI 必须知道：

能力如何分类和搜索；
如何取得一个候选能力的完整契约；
如何读取当前模型和选择上下文；
如何判断信息不足或能力不适用；
如何构造、预检、预览和提交 typed Patch；
如何使用 diagnostic 和 certificate 修正方案。

具体能力由系统在任务时提供。这使 Aira 可以新增内核、feature、制造规则或领域包，而不等待基础模型重新训练。

2. 设计目标与非目标

2.1 目标

可发现：新模型和未见过的新 capability 能通过协议完成任务。
有界上下文：能力和模型规模增长时，单任务上下文保持与相关子图近似成比例。
状态感知：搜索结果反映当前 Revision、选择、表示、后端、权限和预算。
类型安全：所有计划和 Patch 在调用 kernel 前完成 schema、类型、单位、引用和前置条件检查。
可组合：单个 capability 可以组成 plan/workflow，但组合仍受显式状态转移约束。
可证伪：接口质量由 retrieval、planning、execution、editability 和 transaction benchmark 衡量。
供应商中立：协议不依赖某个模型、tool calling 方言或云服务。
工业可审计：保存用户可见 intent、锁定能力、公开计划、调用、diff、diagnostic 和 certificate，不依赖隐藏思维链。
协议原生：任何兼容客户端只凭版本化协议和当前 runtime snapshot 即可发现并调用能力，无需在模型侧预安装 Aira Skills、提示词包或供应商专用知识。

2.2 非目标

v0.1 不建立完整的跨行业 CAD 本体；
不承诺任意图片、文件或自然语言能唯一恢复真实设计意图；
不让 AI 直接管理 kernel object 生命周期；
不定义新的通用 AI agent framework；
不要求所有操作都自动提交；
不用自然语言描述替代形式化 precondition/postcondition；
不把 capability search 排名当作执行授权。

3. 不变量

AMIR Revision 仍是唯一模型真相；Aira Interface 不创建平行状态。
所有写入都必须变成针对明确 baseRevision 的 AMIR Patch。
search/describe/plan 不得修改模型。
搜索返回能力不代表当前 session 获得执行权限。
每个 plan、Patch、preview 和 validation 必须绑定明确的 catalog/runtime/grant snapshot。
自然语言说明、example 和 embedding 不得改变 Operation 的规范语义。
AI/GUI/CLI 对等操作必须走相同 Patch schema 和事务生命周期。
kernel/solver 的实际结果优先于模型对效果的预测；失败必须结构化返回。
不确定、信息不足、引用歧义和能力缺失必须显式状态化，不得猜测后静默提交。
MCP 或其他 transport 断开、升级或替换时，不得改变 AMIR 的解释结果。
Agent Skills、prompt 文件和 Markdown 操作手册不进入 capability 注册、检索、applicability、 plan、authorization 或 execution authority chain。Aira 官方客户端、SDK 与 Agent adapter 不得把安装或加载此类文件作为正确工作的前提；第三方模型自行携带的提示内容一律视为非权威输入，并接受与普通自然语言相同的 schema、权限和事务校验。