RFC-0002：Aira Interface 与能力发现协议：能力模型、描述与发现

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

4. 四层能力模型

Aira 必须把“一个操作是什么”“AI 怎样找到它”“当前运行时是否能执行”“本会话是否被允许”拆开。

4.1 Semantic Operation Descriptor

由 AMIR Operation Catalog 定义，属于 authoring semantics，至少包含：

stable operation ID 与 semantic version；
inputs/outputs、类型规则、单位和 cardinality；
规范默认值；
对 required structured input，如果存在语义中立的规范值，提供由同一 AMIR Value Schema 验证、可直接复制的 defaultBinding；required/optional 标记必须与 compiler/Core validator 一致；
preconditions/postconditions；
purity、表示和 field-kind 传播规则；
required kernel capabilities；
stable diagnostic codes。

会改变模型解释、规范化结果或执行语义的字段进入 authoringLockHash。

4.2 AI Capability Profile

Capability Profile 是对一个 operation、query、workflow、validator、converter 或 repair action 的 AI 可发现投影。它可以增加：

人类可读标题、短摘要和术语别名；
intent examples 与 counterexamples；
对 required structured input 的完整可复制 input examples；每个示例值必须通过对应 canonical Schema 验证，且不得与 Descriptor 的 defaultBinding 冲突；
taxonomy path 与 graph relations；
适用场景和常见误用；
风险、可逆性、资源/延迟等级；
失败模式、诊断解释和允许的修复；
plan composition hints；
progressive disclosure 的 compact/full/example views。

纯 discoverability metadata 的更新不改变 AMIR authoring semantics，因此默认不进入 authoringLockHash；但每次 AI 任务必须记录实际 discoveryCatalogHash，以便复现“为什么发现了这些能力”。若 profile 字段参与规范编译或默认值决定，它必须移入 Semantic Operation Descriptor 并按 AMIR 规则版本化。

Capability Profile 可以解释何时复制规范 defaultBinding，但不得在 profile prose 中另造 input object shape 或隐藏默认值。模型看到的 binding 必须来自 Semantic Operation Descriptor/canonical Schema 的投影。

分层规则：规范默认值与 defaultBinding 属于 Semantic Operation Descriptor 并进入 authoringLockHash；纯示例属于 Capability Profile 并进入 discoveryCatalogHash。 examples 与 defaultBinding 改善模型成功率，但不承担合法性：非法调用由状态机、schema 与 grant 强制拒绝（第 12 节），不得以“只在 discovery 路径暴露信息”替代运行时强制。

4.3 Runtime Capability Snapshot

Runtime Snapshot 描述当前 environment 的实际能力：

已安装 adapter/kernel/solver/exporter 及 build hash；
browser/native/server execution location；
supported operation versions 与 quality profiles；
exact/approximate/preview-only；
当前负载、预算上限和预计成本；
暂时不可用、degraded 或 maintenance 状态。

它不改变 Revision 身份，但进入 plan applicability、ExecutionManifest 和证书。

4.4 Session Grant

Session Grant 描述当前 actor 的授权边界：

可读 project/document/branch；
允许的 query 和 write capability classes；
destructive、export、network、external asset 权限；
自动 commit 的风险等级；
token/time/compute/cost budget；
需要用户确认的 action；
到期时间和撤销状态。

Search 可以显示“语义上存在但未授权”的能力，但必须明确 authorization=denied|approvalRequired；执行端再次强制校验，不相信客户端或模型自报。

4.5 四层对象的绑定

flowchart LR
    S[Semantic Operation Descriptor] --> P[AI Capability Profile]
    S --> R[Runtime Capability Snapshot]
    G[Session Grant] --> A[Applicable Capability View]
    P --> A
    R --> A
    M[Revision + Selection + Policy] --> A
    A --> T[Locked Plan / Patch]
    T --> E[Execution + Certificate]

Applicable Capability View 是派生视图，可重新计算，不是模型事实源。

5. Capability 本体与关系图

5.1 Capability kind

v0.1 定义以下顶层 kind：

Kind	含义	例子
`authoring.operation`	产生 AMIR Node/Parameter/Constraint/Body/Patch 变化	extrude、fillet、add constraint
`model.query`	读取模型或派生几何，不写 Revision	measure、topology、lineage、impact
`workflow`	可展开为多个 plan step 的受限组合	mounting-hole pattern、DFM repair loop
`validator`	产生 assertion/check 结果	solid validity、wall thickness、interference
`converter`	在几何表示或交换格式间转换	Exact→DisplayMesh、Mesh→Field
`repair`	生成受限候选 Patch，不直接修改模型	reduce fillet radius、repair profile
`importer` / `exporter`	处理外部数据边界	STEP import、3MF export

workflow 不是隐藏脚本。它必须展开为可审计 plan 或引用经过签名、版本锁定的确定性 workflow definition。

5.2 Taxonomy

建议首版层级：

authoring
  datum
  sketch
    primitive
    constraint
    profile
  exact
    primitive
    feature
    boolean
    finishing
  mesh
  field
  assembly
query
  identity-lineage
  geometric
  topology
  constraint
  dependency-impact
validation
  geometric
  requirements
  manufacturing
  exchange
io
  import
  export

Taxonomy 用于 coarse routing，不承担唯一语义。一个 capability 可以有一个 primary path 和多个 secondary facets。

5.3 Graph relation

v0.1 支持：

requires：计划中必须先满足的 capability/state；
produces / accepts：类型化数据流；
composesWith：常见但非强制组合；
alternativeTo：相同意图的不同表示/精度路径；
convertsTo：表示转换；
validates：验证某类产物或要求；
repairsDiagnostic：可处理指定 diagnostic code；
supersedes：版本替代；
conflictsWith：不可同时使用的语义或 policy。

Graph relation 只能缩小或解释搜索空间，不能绕过类型和运行时校验。

6. Capability Descriptor

6.1 最小结构

每个 Capability Descriptor 必须声明且只声明一个规范执行目标：

operationRef：创建或重连 AMIR Node 的版本化 Operation；
patchTemplateRef：产生一个或多个允许的 AMIR Patch op，例如 parameter.setValue；
queryRef、validatorRef、workflowRef 或 ioRef：对应各自版本化 contract。

Capability ID 只用于发现和产品兼容性，不能直接写入 Node 的 op，也不能被执行器当作 Patch op。目标 contract、lowering 和规范默认值必须版本锁定；例如 cap:parameter.set@1 使用 patchTemplateRef，而不是伪造一个 parameter.set Operation。

{
  "capabilityId": "cap:exact.fillet@1",
  "kind": "authoring.operation",
  "operationRef": "exact.fillet@1.0.0",
  "profileVersion": "1.2.0",
  "title": "Fillet selected exact edges",
  "summary": "Round an explicitly resolved set of edges on an ExactSolid.",
  "taxonomy": {
    "primary": "authoring.exact.finishing",
    "facets": ["edge-treatment", "radius-driven"]
  },
  "intentExamples": [
    "round the four outer vertical edges by 2 mm"
  ],
  "counterExamples": [
    "smooth a triangle mesh visually"
  ],
  "inputs": {
    "schemaRef": "amir://ops/exact.fillet/1.0.0/input",
    "semanticTypes": ["ExactSolid", "EntitySet<Edge>", "Length"]
  },
  "outputs": {
    "schemaRef": "amir://ops/exact.fillet/1.0.0/output",
    "semanticTypes": ["ExactSolid"]
  },
  "applicability": {
    "requiresRepresentation": ["ExactSolid"],
    "selection": { "entityKind": "Edge", "cardinality": "oneOrMore" },
    "predicates": ["radius > tolerance"]
  },
  "effects": ["createsFeature", "changesTopology"],
  "risk": {
    "level": "medium",
    "destructive": false,
    "reversibleByRevision": true,
    "mayInvalidateRefs": true
  },
  "execution": {
    "quality": ["preview", "authoritative"],
    "requiredCapabilities": ["exact.brep.fillet"],
    "costClass": "interactive-to-heavy",
    "cancellable": true
  },
  "diagnostics": [
    "FILLET_RADIUS_TOO_LARGE",
    "SELECTION_CARDINALITY_MISMATCH"
  ],
  "relations": {
    "repairsDiagnostic": [],
    "alternativeTo": ["cap:mesh.edgeBevel@1"]
  },
  "trust": {
    "package": "aira.core.exact",
    "signature": "sig:..."
  }
}

6.2 字段规则

summary 和 examples 只帮助发现，不定义 operation 语义。
operationRef 必须精确到兼容版本范围；形成 plan 时必须解析成 exact version。
所有输入/输出 schema 必须由同一规范 descriptor 生成或引用，禁止为 AI 另写一份漂移 schema。
applicability.predicates 必须使用注册 predicate ID/typed AST；示例中的字符串仅为简写。
effects 至少区分 read-only、additive、topology-changing、authority-changing、external side effect。
risk 是 policy 输入，不是提示性文案；执行端必须独立强制。
插件提供的描述、example 和 relation 均视为不受信任数据，必须通过签名、lint 和 conformance test 后才进入 production catalog。

7. Progressive Capability Disclosure

AI 不一次接收全部 descriptor。Aira Interface 使用五级披露：

Level	内容	目的
L0 Manifest	接口版本、顶层 taxonomy、可用 meta-operations、snapshot IDs	教会 AI 如何发现
L1 Search Hit	capability ID、标题、短摘要、主要类型、applicability/risk/cost 摘要	选择少量候选
L2 Contract	完整 input/output schema、preconditions/effects、diagnostics	构造合法 plan
L3 Guidance	examples、counterexamples、组合方式、常见失败	降低误用
L4 Applicability	针对具体 Revision/selection 的可行性、缺失信息、cost estimate	决定是否执行

客户端必须能限制 topK、最大 token/byte、允许 kind、风险和 cost。服务端不得因 catalog 增长而静默返回无界结果。

7.1 自适应 discovery

强制 search → describe 的顺序不是目的；写入前拥有完整锁定契约才是。规则：

任何写路径（model.proposePatch 及之后）引用的每个 capability，必须在本任务 trace 中存在其完整 L2 契约与精确版本绑定；缺失时运行时返回 recoverable DISCOVERY_REQUIRED，不调用 CAD authority。
完整契约可以经三条合法通道取得，均计入 discoveryCatalogHash 绑定：
- 本任务内的 catalog.describe；
- Task Capsule 内嵌的完整契约——capsule-provided contract 视同 discovery 完成；
- small-catalog 模式：当前 applicable catalog 的全量 L1+L2 体积低于 manifest 声明的上限时， interface.manifest 可以直接内联全部契约，catalog.search 可省略。
catalog.describe 引用的 capabilityId 必须来自 trace 中可见的合法通道（search hit、capsule 内嵌、 manifest 内联）；不再全局强制先 search。
Task Protocol（第 9.4 节）可以为特定 Gate 收紧为显式 requiredDiscoverySequence，但不得放松第 1 条。
已在同一任务中锁定契约的 capability，后续轮次可直接使用，无需重复 describe；catalog/runtime snapshot 变化后旧契约进入 stale，必须重新取得。

8. Capability Search

8.1 Search request

{
  "intent": "round the four selected outer edges by 2 mm",
  "revision": "rev:sha256:...",
  "selectionRefs": ["sel:..."],
  "knownInputs": [
    { "type": "ExactSolid", "ref": "body:bracket" }
  ],
  "desiredOutputs": ["ExactSolid"],
  "constraints": {
    "preserveEditability": true,
    "precision": "authoritative",
    "maxRisk": "medium",
    "executionLocations": ["native", "server"]
  },
  "includeKinds": ["authoring.operation", "workflow"],
  "topK": 8,
  "catalogSnapshot": "disc:sha256:...",
  "runtimeSnapshot": "runtime:sha256:...",
  "grantId": "grant:..."
}

8.2 Retrieval pipeline

首版必须是 hybrid，而不是单一 embedding：

Intent normalization：提取目标、对象、单位、要求和禁止项，不丢弃原始 intent。
Hierarchical routing：选择若干 taxonomy branch。
Candidate generation：BM25/keyword、semantic embedding、alias 与 example retrieval 并行生成候选。
Typed filtering：按 known input/output type、representation、cardinality 过滤不可能候选。
State applicability：对 Revision、selection、backend、policy 计算 applicable|conditionallyApplicable|notApplicable|unknown。
Reranking：组合语义相关性、完整 tool-set coverage、风险、质量、成本和多样性。
Sufficiency check：判断 top-k 是否足以形成完整 plan；不足时扩大检索、分解任务或返回 missing capability/information。

不得把 embedding score 暴露成“成功概率”。返回的 score 必须有名称和校准语义，至少区分 retrieval relevance 与 runtime applicability。

8.3 Search response

每个 hit 至少返回：

exact capabilityId/profileVersion/operationVersion；
whyMatched 的公开特征摘要；
current applicability 与 unmet preconditions；
input/output semantic types；
risk/cost/quality 摘要；
required permission/approval；
full descriptor handle。

whyMatched 不得伪造模型隐藏推理；它只描述系统可观察的匹配信号，如 taxonomy、type match、selection match、intent term 和 policy filter。