RFC-0001：AI 原生 CAD 系统架构：架构、服务与执行

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

6. 总体架构

flowchart TB
    Human[Human UI] --> API
    Agent[AI Agent] --> API
    CLI[CLI / SDK] --> API
    Plugin[Capability-limited Plugin] --> API

    API[Domain Transaction API] --> MS[Model Service]
    MS --> TX[Transaction Engine]
    TX --> COMP[AMIR Compiler]
    COMP --> PLAN[Typed Incremental Execution Plan]
    TX --> SCHED[Kernel Scheduler]
    PLAN --> SCHED

    SCHED --> OCCT[OCCT Adapter\nExact Worker]
    SCHED --> MANI[Manifold Adapter\nMesh Worker]
    SCHED --> FIELD[Field Adapter\nWASM / GPU Worker]
    SCHED --> CONS[Constraint Adapter\nSolver Worker]

    OCCT --> AG[ArtifactGraph + Source Map]
    MANI --> AG
    FIELD --> AG
    CONS --> AG
    AG --> CERT[Geometry Certificate Service]
    CERT --> TX

    AG --> RB[Render Bridge]
    RB --> VIEW[Three.js Viewer]
    VIEW --> API

    TX --> REV[(Revision / Event Store)]
    AG --> CAS[(Content-addressed Artifact Store)]
    CERT --> CAS
    COMP --> CACHE[(Compilation / Evaluation Cache)]

    TX --> IO[Import / Export Service]
    IO --> CAS

6.1 控制面与数据面

• 控制面：Domain Transaction API、Model Service、AMIR compiler、transaction engine、scheduler、capability catalog。
• 数据面：kernel workers、ArtifactGraph、Geometry Certificate、Render Bridge、import/export、blob/CAS。
• 控制面传递结构化命令、hash、handle 和预算；大几何数据通过 transferable typed arrays、共享内存或进程间 blob handle 传输。
• kernel object 只能存在于所属 worker/进程；跨边界 handle 必须带 worker generation，worker 重启后旧 handle 自动失效。

7. 服务与模块边界

模块	拥有的数据与职责	明确禁止
Domain Transaction API	对外 schema、认证、限流、版本协商	暴露 kernel 类或任意代码执行
Model Service	revision 读取、查询、会话、能力目录、事务编排	直接执行几何算法或写派生缓存
AMIR Compiler	parse/lower/type/unit check、规范化、依赖 DAG、执行计划、source map	调用几何内核、访问网络、修改 revision
Transaction Engine	MVCC、预条件、幂等、preview/validate/commit/revert、审计	猜测歧义选择、绕过证书提交
Kernel Scheduler	capability 路由、预算、取消、隔离、worker 生命周期	改写 AMIR 语义或静默换表示
Kernel Adapter SDK	统一 capability、plan、artifact、diagnostic ABI	规定第三方内核内部对象模型
OCCT Adapter	ExactSolid、精确特征、STEP/IGES、tessellation、history	向上暴露 TopoDS 对象或枚举序号身份
Manifold Adapter	MeshSolid、网格 CSG、分割、测量、Field bake	冒充 NURBS/feature history 内核
Field Adapter	Field IR 验证、CPU/WASM 计算、GPU 预览、bake plan	接受无界任意回调或未声明 sign 的场
Constraint Adapter	Sketch2D 求解、DOF、conflict/residual	把 solver 私有索引持久化到 AMIR
ArtifactGraph	工件身份、谱系、subshape 映射、source/render map	成为 authoring source
Certificate Service	结构化有效性、精度、误差、来源和资源证据	宣称提供形式化几何证明
Render Bridge	Artifact → RenderPacket、拾取映射、LOD	把 Three.js 对象反写为 CAD 历史
Three.js Viewer	视口、交互、材质、相机、gizmo、辅助显示	直接提交几何或保存规范模型
Import/Export Service	格式识别、隔离解析、显式转换、导出报告	把交换格式默认为无损设计历史
Revision Store	AMIR revision、patch、manifest、审计事件	保存可变 kernel object
Artifact Store / Cache	不可变 blobs、证书、派生几何、索引	成为不可删除的唯一副本

依赖方向必须从上层语义指向下层 capability；任何下层模块不得反向依赖 Three.js UI 或 AI agent。

8. AMIR 规范模型

8.1 文档组成

AMIR 至少包含：

• schema version、document ID、project policy；
• 量纲化参数、范围、表达式和显示单位；
• 以稳定 ID 为键的不可变 feature DAG；
• BodyId registry，把稳定逻辑 body 身份显式绑定到当前唯一 authority output；
• Sketch2D、Profile2D、ExactSolid、MeshSolid、Field3D、Assembly 等 authoring 类型；DisplayMesh/RenderPacket 属于 runtime artifact 类型，不可作为 Feature DAG 权威输出；
• constraints、assertions、SemanticRef 和命名输出；
• 显式 import、权威表示 conversion 和 assertion；tessellation/LOD/export 默认是绑定 Revision 的派生 job，需持久化时使用独立 view/delivery profile，而不是几何 Feature Node；
• tolerance profile、quality policy、seed 与所需 capabilities；
• plugin package 的内容 hash、版本和授权声明。

canonical serialization 必须规定：

• map key 排序、Unicode 规范化、数值/单位规范形式；
• 不允许 NaN、Infinity、隐式默认时区或依赖 locale 的解析；
• stable ID 不受格式化、注释和 node 展示顺序影响；
• hash 覆盖全部语义字段，不覆盖注释布局、UI 面板和缓存路径；
• 当前 schema/catalog 内容绑定必须匹配；旧输入明确拒绝，不执行 schema migration。

8.2 类型和单位

至少区分：

• Length、Angle、Area、Volume、Ratio、Count；
• Sketch2D、Profile2D、Curve3D；
• ExactSolid、MeshSolid、Field3D、DisplayMesh；
• TrueSDF、ConservativeDistance 与 GeneralImplicit；
• SemanticRef<EntityKind, Cardinality>；
• AuthoritativeArtifact 与 DerivedArtifact。

编译器把用户单位转换为执行清单声明的 adapter base unit，但 AMIR 保留原始量纲与显示单位。无量纲数字不得隐式进入长度或角度参数。

8.3 Operation Catalog

每个 AMIR operation 都有机器可读 descriptor：

• operation ID 与 semantic version；
• 输入/输出类型和 cardinality；
• 参数、单位、默认值、范围和互斥条件；
• 支持的 adapter capabilities；
• exact / approximate / voxelized 语义；
• 确定性等级、可取消点和成本估算器；
• 可能的稳定错误 code 与 recovery action；
• provenance/history 保留等级；
• preview 与 authoritative execution 的差异。

AI 通过 catalog.search 发现能力，不通过枚举一千个 OCCT 方法学习系统。

Operation Catalog 的规范语义、AI discoverability metadata、当前运行时可用性与会话授权必须分层。前者由 AMIR authoring lock 固定；后三者分别形成可审计的 discovery catalog、Runtime Capability Snapshot 与 Session Grant。具体搜索、Task Capsule、typed plan 和 MCP projection 由 RFC-0002 定义。

9. Model Service

Model Service 是所有调用者的统一领域门面。首版 API：

方法	语义
interface.manifest	返回协议版本、taxonomy root、snapshot、grant 与 limits
catalog.search	按意图、输入/输出类型、精度、成本和失败模式发现 operation
catalog.describe	返回选定 capability 的完整 schema、适用条件、effects、diagnostics 与 operationRef
model.read	读取 revision、参数、feature DAG、选择、证书摘要
model.query	测量、拓扑、来源、约束、候选引用和空间查询
plan.check	检查 capability composition、权限、预算、前置条件与 effect scope
model.proposePatch	对 baseRevision 生成并静态检查 AMIR patch，不执行写入
model.preview	在明确 quality/resource budget 下执行候选 revision
model.validate	运行语义、几何、约束、制造和出口前验证
model.commit	原子提交已验证 patch 或与其完全一致的重执行结果
model.revert	生成回到目标 revision 的新提交，不删除历史
model.export	选择格式和质量策略，生成工件、证书及有损报告

9.1 API 规则

1. 每个写请求包含 projectId、documentId、branchId、transactionId、patchId、baseRevision、idempotencyKey、intent、operations、preconditions 和 versioned policyId。
2. 每个响应包含 requestId、transactionId、observedRevision、diagnostics、artifact handles 和 certificate summary。
3. model.query 必须声明 revision；“当前模型”只可作为 UI convenience，在服务内部立即解析为具体 hash。
4. query 不得改变 kernel 或 cache 可见语义；必要的惰性计算以派生工件记录。
5. API 支持 capability negotiation。缺少精确后端时返回 CAPABILITY_UNAVAILABLE，不得自动退化为网格近似。
6. AI 与 GUI 权限相同的操作必须产生相同 patch schema；GUI 没有旁路写权限。
7. 长任务返回 job handle 和事件流，支持 cancel；取消后的 late result 不得进入已提交图。

10. AMIR Compiler

AMIR compiler 以 Rust 实现并编译到 WASM 与原生；Phase 0A 的 TypeScript 只承担浏览器产品层与 adapter，不复制 canonicalization、单位、Patch、Revision 或 hash 语义。

10.1 编译流水线

1. Decode：解析 canonical AMIR JSON，或解析 .aira CST 后编译为 AMIR；CST/trivia 只作非语义附件，限制深度、节点数和文本大小。
2. Contract check：核对当前 schema/catalog 内容绑定；不支持的旧输入明确拒绝，不执行迁移。
3. Canonicalize：规范单位、数值、顺序、默认值和 stable ID。
4. Resolve：解析 node/port/parameter/package 引用，不解析运行时 subshape。
5. Type and unit check：拒绝表示、量纲和 cardinality 不匹配。
6. Static cost check：估算 bounded pattern、Field evaluationClip/meshingBounds、采样、网格和 solver 规模。
7. Dependency analysis：构建并验证完整 Document Dependency Graph，再派生 Feature DAG、constraint 子图和 dirty set。
8. Lowering：把高层 operation 降为版本化、类型化的 KernelPlan；不包含 raw kernel API 名称。
9. Emit source map：建立 OriginAnchor ⇄ node/port 的双向映射；存在 .aira 文本时才包含 SourceSpan。
10. Hash：产生 revision hash、subgraph hash 和 compiler manifest。

10.2 编译器输出

CompiledRevision {
  modelHash
  authoringLockHash
  schemaVersion
  compilerBuildHash
  documentDependencyGraph
  featureDag
  dirtySet
  kernelPlans[]
  staticDiagnostics[]
  sourceMap
  requiredCapabilities[]
  estimatedCost
}

编译器必须是无网络、无时钟依赖、无随机副作用的纯语义组件。它不加载 Three.js，不创建 OCCT/Manifold 对象，也不决定是否接受近似降级。

11. Transaction Engine

11.1 状态机

stateDiagram-v2
    state "proposed" as Proposed
    state "planned" as Planned
    state "previewed" as Previewed
    state "validating" as Validating
    state "validated" as Validated
    state "committing" as Committing
    state "committed" as Committed
    state "rejected" as Rejected
    state "cancelled" as Cancelled
    state "expired" as Expired
    [*] --> Proposed
    Proposed --> Rejected: parse/type/unit/precondition error
    Proposed --> Planned: static checks pass
    Planned --> Previewed: optional preview succeeds
    Planned --> Validating: authoritative validation requested
    Previewed --> Validating: same candidate revision
    Validating --> Validated: validation succeeds
    Validating --> Rejected: validation fails
    Previewed --> Rejected: geometry/resource/selection error
    Validated --> Committing: commit requested
    Committing --> Committed: preconditions rechecked and CAS succeeds
    Committing --> Rejected: conflict or policy failure
    Committing --> Cancelled: cancel wins before CAS linearization
    Proposed --> Cancelled
    Planned --> Cancelled
    Previewed --> Cancelled
    Validating --> Cancelled
    Validated --> Cancelled
    Previewed --> Expired: token expires
    Validated --> Expired: token expires
    Committed --> [*]
    Rejected --> [*]
    Cancelled --> [*]
    Expired --> [*]

状态名称与生命周期以 AMIR v0.1 第 10 节 为唯一协议。previewed、validated 和 committed 是事务状态，不是可编辑 revision。只有 committed 产生新的 branch head。Commit linearization point 是持久化事务中的 branch-head CAS：取消在此之前胜出则为 cancelled，在此之后只能返回真实的 committed 与 CANCEL_TOO_LATE，再通过新 revert transaction 恢复。

11.2 一致性与并发

• revision store 使用不可变 revision + optimistic MVCC。
• commit 前重新检查 baseRevision 和全部 domain preconditions。
• 冲突返回 REVISION_CONFLICT，并包含最小 changed-node set；transaction engine 不自动合并几何意图。
• patch 的非冲突重放可以由上层显式发起，并产生新的 preview/validation。
• 单个 commit 原子地写入 revision、patch、execution manifest、certificate references 和审计事件。
• CAS 工件可以先写后引用；未被提交引用的临时工件通过 TTL/GC 清理。
• revert 创建反向 patch 或恢复 snapshot 的新 revision，保留被回退历史。

11.3 Preview 与 Commit

preview 和 commit 必须绑定同一个 candidate AMIR hash。ExecutionManifest 至少包括：

• compiler、adapter、kernel 和 plugin 的精确版本/构建 hash；
• platform/architecture、线程策略和浮点模式；
• unit normalization 与完整 tolerance profile；
• random seed；
• input blob hashes；
• capability resolution；
• preview/authoritative quality profile；
• resource budgets。

若 commit 复用已有执行，只有在 candidate modelHash、authoringLockHash、manifest hash、execution class、authoritative quality、输入 artifacts 和所有 preconditions 完全一致时才能复用同一 EvaluationId；否则必须重执行。Validation 先写 candidate binding/provisional Certificate，commit 再原子写 Revision binding 和新的 committed Certificate，不能修改旧证书。重执行结果超出证书容差即拒绝，不允许以“预览看起来正确”为理由提交。

11.4 审计

每个事务保存：

• actor、intent、prompt/reference（按隐私策略可脱敏）；
• request body hash、idempotency key；
• base/candidate/result revision；
• patch 与 preconditions；
• compiler/adapter manifests；
• diagnostics、recovery attempts 和最终状态；
• certificate/artifact hashes；
• duration、resource use、cache hit 和取消原因。

12. Kernel Adapter 架构

12.1 统一 ABI

adapter 对 scheduler 提供版本化协议，而不是类库对象：

Adapter {
  describeCapabilities() -> CapabilityDescriptor[]
  openExecution(manifest, budgets) -> ExecutionHandle
  execute(plan, inputArtifactHandles[]) -> ArtifactDelta
  query(queryPlan, artifactHandles[]) -> QueryResult
  validate(validationPlan, artifactHandles[]) -> ValidationResult
  tessellate(tessellationPlan, artifactHandle) -> RenderPacket
  import(importPlan, blobHandle) -> ImportResult
  export(exportPlan, artifactHandles[]) -> ExportResult
  cancel(executionHandle)
  close(executionHandle)
}

协议要求：

• 只传 canonical plan、不可变 artifact handle、typed arrays 和结构化 diagnostics；
• adapter 返回 generated/modified/split/merged/deleted history；
• adapter 声明是否 exact、approximate、deterministic-within-tolerance 或 preview-only；
• 所有调用可取消、有 deadline、有内存和输出规模上限；
• worker 崩溃返回 WORKER_CRASHED，并使该 generation 的 handle 全部失效；
• adapter 不能自行访问 revision store、用户文件系统或网络。

12.2 Capability 路由

操作族	默认 adapter	输出权威类型	备注
sketch profile → extrude/revolve/loft/sweep	OCCT	ExactSolid	constraints 先产出求解后的 Sketch2D/Profile2D
B-Rep boolean、fillet、chamfer、shell、draft	OCCT	ExactSolid	需要 history、tolerance 和 validity 证书
STEP/IGES import/export、shape healing	OCCT	ExactSolid	交换不等于 feature history
manifold mesh import、mesh boolean、split、printing cleanup	Manifold	MeshSolid	输入前置条件和 repair 范围必须明确
smooth union、lattice、gyroid、warp	Field	Field3D	必须声明 bounds、sign、质量与距离性质
Field bake	Manifold LevelSet（首版）	MeshSolid	显式记录 edge length、tolerance 和采样误差
2D constraint solve	Constraints	Sketch2D solve result	返回 DOF、residual、conflict set
viewport tessellation	当前 authority 对应 adapter	DisplayMesh	仅派生

12.3 OCCT Adapter

职责：

• 构造和验证 ExactSolid；
• 封装 primitives、extrude、revolve、pipe/sweep、loft、boolean、fillet、chamfer、shell/draft；
• 提供解析 curve/surface、质量属性、拓扑邻接和 subshape history 查询；
• STEP AP242/IGES 导入导出、XDE 属性和 shape healing；
• 以 chordal/angular deflection 生成 DisplayMesh。

边界：

• 原型期允许在 adapter 内使用 Replicad/opencascade.js；AMIR 不依赖其 API 或 selector 语法；
• 产品构建维护最小 custom WASM symbol set，并锁定 OCCT、Emscripten、绑定清单和构建 hash；opencascade.js 官方提供 custom build 工作流。opencascade.js Custom Builds
• TopoDS、Handle、pointer、HashCode、枚举顺序和异常文本不跨 adapter；
• OCCT history 是 SemanticRef 的证据之一，不是稳定身份的全部；
• OCAF/topological naming 的经验用于 adapter 和 ArtifactGraph，但产品 ID 不直接等同于 OCAF label 或内核 UID。OCAF / Topological Naming
• OCCT 使用浮点与 tolerance；“ExactSolid”表示精确 B-Rep/解析语义，不表示形式化精确算术。OCCT Precision

12.4 Manifold Adapter

职责：

• MeshSolid primitives、boolean、batch boolean、split、trim、hull、simplify 和测量；
• 保留 originalID/faceID 等可用来源信息；
• 生成 MeshGL/DisplayMesh；
• 通过 LevelSet 把有界 Field3D 烘焙为 MeshSolid。

边界：

• 输入必须满足声明的 manifold/geometry preconditions；Merge 不是通用修复；
• manifold 拓扑不等于尺寸、无自重叠或设计意图正确；
• Field adapter 在调用 LevelSet 前显式转换 inside-sign；Manifold JS API 的约定必须封装在 adapter 内。Manifold JS API
• bounds、edgeLength、tolerance、maxCells 和 maxTriangles 全部进入 plan、证书和缓存键；
• 不从输出三角形推导 NURBS 或 CAD feature history。

12.5 Field Adapter

Field3D 是有限、纯数据、可编译的表达式图，不是任意 JS callback；“有限”约束表达式图和执行计划，不要求数学定义域必然有界。节点至少声明：

• value kind：TrueSDF、ConservativeDistance 或 GeneralImplicit；
• inside-sign；
• mathematicalDomain：allSpace 或显式有界 domain；
• surfaceBounds：可证明时给出有限 Box3D，否则为 null；
• distance-preserving / Lipschitz 信息；
• gradient 来源；
• 最小可分辨特征尺度；
• material/feature provenance；
• preview 和 bake quality policy。

同一 Field IR 可以编译为：

1. CPU/WASM 批量 evaluator，作为规范验证基线；
2. TSL/WGSL/GLSL 预览程序；
3. Manifold LevelSet 或后续自适应 mesher 的采样计划。

GPU 路径可以近似和渐进增强，但提交用 bake/validation 不能只依赖某个 GPU 驱动的像素结果。数学上无界的场是合法的；预览/测量必须提供有限 evaluationClip，Field → Mesh 必须提供有限 meshingBounds。缺少这些有限执行边界、无法证明有限成本的 repeat、超预算采样和未声明 sign 必须在执行前拒绝。

12.6 Constraint Adapter

AMIR 自有 SketchEntity、Constraint、DOF、Residual 和 ConflictSet 类型。首版对 PlaneGCS WASM 做独立 spike；PlaneGCS 是 FreeCAD Sketcher 中的二维约束求解组件。FreeCAD PlaneGCS

adapter 必须：

• 把 stable entity/constraint ID 映射到临时 solver index；
• 支持 initial guess、drag hint 和 driving/reference constraint；
• 返回 remaining DOF、residual、redundant candidates、conflict candidates；
• 把数值失败转换为稳定 diagnostics；
• 不把 solver 私有序号或内存布局持久化；
• 用尺度归一化与容差 profile 处理大尺度差异。

若某求解能力缺失，必须显式返回 capability error；不得把未完全约束的草图静默标为 fully constrained。

12.7 显式转换

允许的默认转换：

从	到	operation	必须记录
ExactSolid	DisplayMesh	tessellate	chordal/angular deflection、triangle count、来源映射
ExactSolid	MeshSolid	bakeMesh	deflection、sewing/welding policy、误差界
MeshSolid	DisplayMesh	renderMesh	attribute mapping、LOD、简化误差
Field3D	DisplayMesh	previewField	bounds、steps、screen error；仅预览
Field3D	MeshSolid	bakeField	bounds、edgeLength、iso/tolerance、sampling method
MeshSolid	Field3D	voxelize/distance	bounds、resolution、sign method、误差

任何未列出的转换都需要显式 capability 和 ADR。转换 node 只产生新的表示候选；只有显式 body.setAuthority Patch 指向该输出时，权威表示才发生切换。root.put 只发布 BodyId 或 Assembly output，不承担权威切换；原输入仍保留在 ArtifactGraph，不被覆盖。

表中输出 DisplayMesh 的 tessellate/render/preview 行是 runtime derived jobs，不进入 canonical Feature DAG 或 modelHash；其 identity 由 EvaluationId、view quality profile 和来源 artifact 决定。