Aira CAD 底座复用、版本兼容与证据体系修正调查：最小建模底座与职责推导

主文档与完整目录。本分篇保留原调查日期的依据与实测记录；其中的当前状态、建议和授权仅属于历史快照，不是执行队列。

8. 从 AI 可理解可操作建模推导最小充分方案

8.1 先核对成熟实现：比较完整职责，不只比较几何内核

2026-09-03 补查基线为 acf8987c020d1c1001d69fc03e3c076655515e89 加当前工作树。 本地 OCCT、Replicad、CadQuery 的 HEAD 与下列锁定提交一致，三个参考工作树均干净。 FreeCAD 为本轮读取的官方发布源码，不是已安装或已接入 Aira 的依赖。

真实需求	上游设施与核对版本	已证实差异 / 未知	决定与边界
保存参数对象、修改后重算、撤销与恢复	FreeCAD 1.1.3 / 145529fe741292ff0b3977a01195bf0247425794；DocumentPy::addObject/recompute/openTransaction/commitTransaction/abortTransaction/undo/redo/saveAs	官方源码已有文档和事务 API；这是原生应用执行环境，本轮未运行无 GUI 零件闭环，未测部署与适配成本；文档事务本身不等于跨进程持久提交或 Aira CAS	若允许本地/服务端进程，应优先验证完整文档引擎加薄接口；不能先假定这些职责必须由 Aira 重写
在浏览器组合实体、选面选边和生成显示网格	Replicad 90d176edde1cf3dec8db189d9228f34625ac84af；cut/shell/fillet/chamfer、FaceFinder/EdgeFinder、mesh	已查 fillet 返回 Shape，没有把 maker history 作为结果暴露；GCWithScope 依赖 FinalizationRegistry；mesh 返回 Float32。全库其他扩展点和接入总成本未穷尽验证	浏览器路线优先比较其高层封装；需要 lineage、确定释放或精度保护时，先核对扩展点/补绑定，不能据单个方法的缺口否定整库，也不能直接套用后丢失信息
用简洁参数与选择规则构造机械零件	CadQuery 2.7.0 / b8137fdc231ed0a0dc52a70dad761f201fe53e0f；Workplane.faces/revolve/cut/shell/fillet	已有参数建模与选择 API；锁定 setup.py 依赖 Python cadquery-ocp>=7.8.1,<7.9，与 Aira 当前 WASM 并非同一 ABI；浏览器移植成本未知	作为原生执行候选和建模操作粒度参考；运行语言是部署差异，不是 AI 不可用的证明
几何运算、拓扑演化、依赖更新和局部事务	OCCT 8.0.1 / b8f597c677811d1f9f4d8a97f5ae2825c0353a42；TopExp、BRepTools_History、TNaming_Selector、TFunction_Driver/IFunction、TDocStd_Document	Aira 绑定已调用原生索引/history；当前清单没有 TNaming/TFunction。Select/Solve 依赖命名上下文且可失败；TFunction 要应用提供 Execute/Arguments/Results。未测 OCAF 浏览器增量成本	已适用的设施直接复用；原始 OCCT 加自有文档层也要与上层成熟实现比较。缺 JS 绑定不能直接推出自研命名、调度或事务

证据：FreeCAD 锁定文档 API、 Replicad shapes与 生命周期、 CadQuery 操作与 依赖、 TNaming_Selector、 TFunction_Driver、 TFunction_IFunction、 TDocStd_Document。 Replicad 官方定位和CadQuery 官方定位 用于核对宿主与使用方式，具体 API 判断以上述版本源码为准。

这轮核对证明了职责覆盖与若干适配差异，没有证明哪条路线总成本最低。 已有上游 API 也没有证明 Aira 已经正确接入，或 AI 已经能独立完成任务。

8.2 定义“充分”：先限定可验收任务

目标：一个未读项目源码、未装专用 Skills 的 AI，取得软件提供的接口后，能创建一个参数化机械 零件，读取其状态，修改尺寸与局部特征，检查结果，处理失败，并保存后继续编辑。

首个任务域限定为可组合的单零件实体建模。一个带孔板件即可检验核心闭环：尺寸可变、孔的位置 表达相对基准的关系、可增加收边、上游修改会更新下游。充分性要求支持这类操作的合法组合， 不能靠一个固定零件生成器、预写答案或只会输出最终网格来满足。

必须区分三类条件：

• 目标本身导出的条件： 能力与状态可读，参数/单位明确，修改可组合，结果可检查，失败可恢复，设计可保存。
• Aira 已选择的产品条件： 工业 Exact 几何、浏览器优先、AI/UI 共用能力、受控修改和历史兼容。这些条件有实际成本，比较方案时须显式计入。
• 仍需论证的实现选择： AMIR 的内部组织、自研编译/调度、OCAF 的使用方式、分层数量、证据对象数量、缓存和部署组件。它们不能仅凭已经存在就进入最小方案。

“AI 可操作”本身没有推出必须纯浏览器、必须多个内核、必须自研 DSL，或必须建立通用 CAD 平台。 浏览器优先也不等于已经证明原生执行路线不可接受；现有产品约束若要改变，应明确提出改变及迁移影响。

8.3 逐项做删除检验：五类不可缺少的能力

最小能力	删除后，哪一步任务会失败	最小实现责任
发现与理解	AI 无法知道可用操作、参数含义和组合规则，只能猜	接口自带可查询的操作说明、输入/输出类型、单位、前置条件、错误与有效示例；复用成熟 schema 校验
读取与定位	AI 看不到模型事实，无法可靠指定要修改的对象	读取命名对象、参数、依赖和必要几何量；选择返回匹配对象、理由和当前版本，多解明确报告
执行可组合修改	只能生成固定样例，不能继续编辑	通过同一入口增删受支持特征、修改参数和连接已有输出；调用成熟建模 API，保存足以重新构造的参数与关系
检查、纠错与恢复	一次无效修改可能毁掉模型，AI 无法知道如何继续	候选隔离、参数/几何检查、授权范围、版本冲突检查、超时取消；失败定位到操作/参数/引用，保留最后有效状态
保存与继续使用	会话结束就丢失设计，结果不能交付	持久保存参数模型及解释版本，支持重开、恢复和一种明确的交付格式；显示与导出结果追溯到当前模型

这是五类能力，不是要求新增五个服务或协议。一次修改可以由软件内部完成预检、求值和验证， 在现有授权策略下决定提交；模型版本、候选句柄与验证结果由运行时提供。 AI 不应为了完成一次尺寸修改，手工组装软件能够推导的内部身份或执行清单。

8.4 推导出的最小结构与复用选择

推荐的目标结构是：成熟参数建模底座 + 薄的 AI 可读写接口 + 可保存和恢复的模型；UI 投影同一状态。

AI / 人的交互界面
        │ 发现、读取、修改、检查、保存/恢复
        ▼
薄的建模接口：类型/单位、对象定位、权限、诊断
        │
        ▼
一个参数模型及修改边界 ── 成熟 CAD 执行器 ── 几何查询 / 显示 / 导出
        │
        └── 持久保存与最后有效版本恢复

这些是职责，不预设必须分别实现为服务、编译器或自研框架。底座已有文档、依赖和事务时优先直接用。 底座仅提供操作 API 时，最小模型可以是带命名输入和参数的操作序列；依赖由引用形成， 先按依赖重算即可。可编辑性要求保存构造信息，但不要求首版提供通用图编辑器或增量计算框架。

具体选择顺序：

1. 从纯目标出发：优先验证完整成熟文档引擎的复用。 FreeCAD 加受限、结构化工具适配是明确候选， 比较它能否直接承担对象、依赖、事务、保存和恢复。适配器只调用允许的建模 API，不向 AI 暴露任意 Python 执行。
2. 计入 Aira 的浏览器优先条件：优先比较 Replicad 高层能力与现有 OCCT 薄适配。 按同一任务比较 几何输出、选择诊断、history、确定释放、包体和重建成本；需要的扩展从上游能力补齐。 当前 OCCT 路线是实际基线，不能仅因采用更多高层封装就宣布替代更省。
3. 仅为已证实的产品差异保留自有逻辑。 例如 AI 能理解的参数语义、授权策略和多解选择诊断。 这些职责也可建立在成熟存储/校验/命名设施上；不能把“需要此能力”自动等同“需要一个自研子系统”。

拓扑选择首版可限定为命名特征输出及有明确匹配规则的面/边查询。每次重新解析，唯一且满足操作 要求才继续；删除或歧义时允许 AI 查询并重新绑定。可恢复不要求预先承诺所有拓扑变化都自动恢复。 检查也应分清拓扑有效与设计满足：内核成功后仍需检查任务要求的尺寸、孔径等事实，不能回显输入即判通过。

8.5 最小充分方案允许后置什么

从零实现首个闭环时，下列工作没有由该任务直接推出的必要性：多几何表示同时上线、完整约束草图 编辑器、通用插件/模块市场、可视化节点编辑器、多用户分支合并、通用增量缓存、数学认证体系， 以及每个操作各一套 Session/Worker/事务编排。首版可以先用参数化基础体或简单轮廓加布尔完成零件。

需要对象稳定身份和版本检查，并不自动需要复杂内容寻址平台；需要正确性检查和可追溯记录， 并不自动需要独立证书服务；需要能力发现，并不自动需要动态模块市场。 同理，界面可以先只有模型视图、参数/特征摘要、修改预览、确认与恢复，AI 通过接口完成全部建模。

以上是最小产品的必要性判断。Aira 已发布的身份、历史模型和验证保护仍按原契约处理； 是否简化某项现有实现，要列出实际消费者与兼容影响，不能直接将“首版可后置”转成删除授权。

8.6 用一个连续任务检验充分性，再决定扩张

验收任务为：AI 发现能力 → 创建带圆孔板件 → 查询真实尺寸与孔的位置 → 添加圆角 → 把板宽从 40 改为 48 mm，并保持孔距指定侧边的关系 → 检查结果 → 保存重开 → 尝试无效圆角并取得具体失败原因 → 修正参数成功 → 恢复上一有效设计。

同时检查一种会使选择失效/多解的修改，以及过期版本修改；软件必须返回可行动的诊断， 不能错绑目标或覆盖新的有效模型。实际数值与失败边界由所选底座核对，未运行前不宣称通过。

每增加一层或一种能力，先指出这个任务族中哪一步会在缺少它时失败；成熟底座已覆盖的部分 直接复用。若任务已可完成，而新增结构只服务尚未出现的扩展设想，则后置。 首轮比较记录在本文、验收沿用既有测试入口；不新建评测平台或进度台账。

本节给出产品方案及复用候选，尚未运行 FreeCAD/Replicad 对照或真实 AI 验收。 Aira 当前统一图路径的已有实现可以作为候选组件，但“统一旧管线完成”与“最小充分产品成立” 应分别判断；不能把当前改造计划当作这次推导的前提，也不能将本研究标记为运行时替换完成。

9. CAD 底座：先核对成熟实现，再从目标与约束推导

9.1 选型对象：几何内核、应用框架和高层 API 分开比较

本节关注参数模型如何得到可靠几何，以及编辑、引用、保存和重建如何持续成立。 补查基线为 4f7a762ff32db46197846fd7dbbbcbc286502462 加当前工作树；沿用 §8.1 的锁定来源。

层次 / 真实需求	核对的成熟实现	已证实差异与采用边界
精确曲面、实体拓扑和建模运算	OCCT 8.0.1；TopoDS/Geom、BRepPrimAPI、BRepAlgoAPI、BRepFilletAPI、BRepOffsetAPI	当前内核可执行拉伸、旋转、布尔、薄壁和收边；其算法与 B-Rep 数据结构直接复用。WASM 是交付/绑定方式，不是另一套几何算法
商业几何内核候选	Siemens Parasolid、Spatial ACIS 的官方产品资料	官方资料确认实体/曲面建模能力；本轮未取得 SDK、锁定版本、目标运行环境许可或报价，也未比较几何反例。保留为候选，不能宣称更稳或因商业许可先行排除
参数文档、重建、命名、事务	同版 OCCT 的 OCAF；FreeCAD 1.1.3 的 Document、TopoShape	OCAF 有 TFunction、TNaming、TDocStd；FreeCAD 有自身的文档与 element map 实现。两者是应用机制选择，不能视为同一实现或只按有无方法名判断兼容
简化建模调用、选择与导出	锁定 Replicad 和 CadQuery，见 §8.1	两者基于 OCCT；采用它们主要改变封装职责和宿主，不等于换用独立几何算法。需比较能否保留 history、失败诊断、资源生命周期和操作语义
二维几何约束	实际安装 @salusoft89/planegcs@1.2.0 的 GcsSystem/GcsWrapper	上游已有求解、冲突、冗余及部分冗余查询；Aira 负责参数/单位/ID 映射和结果接受条件。仅显式尺寸构造不强制调用求解器，声明约束草图时须兑现完整诊断
网格/隐式建模	产品 Manifold 3.5.1；Fidget 为锁定研究参考	是另外的表示与任务域。当前机械零件的参数化 B-Rep 闭环不以同时完成 Mesh/Field 框架为前提；已有独立路线按其任务和合同保留

官方来源：OCCT Modeling Data、 OCAF、 Parasolid、 ACIS、 FreeCAD Document、 FreeCAD TopoShape。 PlaneGCS 查阅安装包 sketch/gcs_wrapper.ts 与 planegcs_dist/gcs_system.ts，版本由 产品依赖固定；参考 Manifold 3.5.2 不作为产品 3.5.1 的验证依据。

9.2 第一性原理：从必须保持的事实推导职责

目标是让 AI 创建并反复修改有明确尺寸、构造关系和几何含义的工业零件。 最小底座必须覆盖下列因果关系；每一项可以由成熟实现承担，不预设一个自研子系统。

目标或约束	必然需要的能力	最小充分实现
圆孔、平面、圆角需要保持解析几何含义，支持工程测量与实体交换	带容差的曲线/曲面、裁剪边界和实体拓扑	单一成熟 B-Rep 内核作为本切片的几何后端；显示网格由它派生
改宽度后孔与收边仍随构造关系更新	保存参数、操作、输入依赖与引用规则，并重新求值	一个可重建的参数文档；复用已有文档引擎，或用薄的有类型操作记录；先完整重算即可
拓扑会生成、删除、分裂和合并	操作 history、当前拓扑查询，以及跨重建的匹配政策	原生 history/索引/命名加产品语义查询；返回基数、匹配理由和失效原因
无效修改不能破坏已接受模型	候选隔离、验证及原子发布边界	成熟文档事务或候选重建，成功后通过现有持久事务发布；失败丢弃候选
内核成功不充分证明尺寸与设计要求成立	几何有效性检查及独立于参数回显的任务断言	原生检查/测量 API 加薄的接受规则；记录适用域、容差及未知项
重开、取消、崩溃之后仍能继续	可序列化构造信息、解释版本和明确的资源所有权	保存参数文档及依赖版本；Worker/进程内重建几何，所有派生缓存可丢弃
浏览器优先且历史模型保持可解释	可部署的绑定/包体/内存和兼容边界	比较 WASM 与显式 native/server 执行策略；保留公开语义与历史身份，宿主变化单独计成本

这里的“Exact”指 B-Rep 几何表示及声明的数值/容差语义，不能推出零误差或全算法使用精确算术。 渲染离散、Float32 转换与实体计算分别核算；提高画面细分不能替代几何精度检查。 具体的 AMIR 内部类结构、TDF Label 组织和调度器均是实现选择，不能作为推导前提。

9.3 由此得到的最小 CAD 底座

一个参数模型、一种主几何表示、一条求值与查询路径、一处持久提交边界。

参数文档：稳定特征 ID、带单位参数、依赖、约束/引用规则
      │
      ├── 有约束的草图 → 成熟约束求解器 → 轮廓与求解诊断
      │
      └── 按依赖重建 → 成熟 B-Rep 运算 → 本次实体 + history
                                          │
                           原生拓扑查询、选择解析、有效性与尺寸检查
                                          │
                           绑定本次输入的结果 / 结构化失败
                                          │
                         既有原子提交与保存 → 显示 / 工程交换

“一条路径”允许草图求解和几何运算调用不同专长库，也允许按需求采用 native/server worker。 它要求同一个操作只有一套实际语义和编排；候选与已提交结果各有正确来源，必要重放仍使用同一实现。

参数文档必须保留构造语义；其底层容器可以复用 TDF/OCAF 等原生设施。 有一个 OCAF document 不自动产生双权威；只有它与另一份模型可分别改写且没有唯一提交裁决时才有问题。 完整 FreeCAD 主文档路线同样应比较，但接管既有 AMIR 模型权威需要显式兼容与迁移方案。

STEP/BREP 属于几何交换/派生物路径，不能由保存终态实体推断原始参数历史也已保存。 OCCT 已有 STEPControl_Writer::Transfer/Write/WriteStream，应直接复用并检查返回状态。 其 SetTolerance 设置交换文件的不确定度字段，不能当作修复几何或证明精度达标的方法。 当前受查 graph binding 及产品 Exact 源码未发现 STEPControl/STEPCAF 接线；本节不将上游能力计为现有产品完成项。

9.4 成熟机制的真实边界决定适配内容

命名与重建。 TNaming_Builder::Generated/Modify/Delete 保存演化关系，TNaming_Selector::Select/Solve 根据命名上下文解析选择；应用必须提供正确的 history，仍要检查结果数量与产品意图。 TFunction_Driver 要求实现 Execute/Arguments/Results；同版 TFunction_IFunction::UpdateDependencies 源码按结果和参数 Label 建依赖，包含函数间遍历。已有 TFunction 不等于免写操作适配，也不能未经实测 声称它比当前显式依赖重建更快。反过来，已有自研 DAG 也不是排除它的理由。

事务与持久化。 TDocStd_Document::CommitCommand 处理文档变更/undo delta，Undo 默认关闭，需配置 SetUndoLimit。这些是可复用的文档机制；浏览器存储是否完成、head 是否变化及并发冲突仍须由实际 持久事务确认。文档内 commit 返回成功，不能直接解释成 Aira 已经持久提交。 当前 Core/CAS 的公开保护保留，内部的候选回滚、参数容器和依赖机制仍可按真实收益替换。

检查与修复。 同版 BRepCheck_Analyzer 的几何检查有适用边界；默认曲线/曲面距离检查使用有限 采样，SetExactMethod 也有 SameParameter 条件，头文件还列出未实现的部分容差检查。 因此最小实现应准确传递原生检查结论，并另查所需尺寸/实体条件；不能把单个 IsValid 包装成全部 工业要求的证明。healing 或放宽容差需要显式结果与接受政策，不能悄悄用于提高成功率。

原生所有权。 布尔可复用 SetNonDestructive 保护输入；拓扑索引、history 与批量提取采用已接入 的原生设施。shape 借用/持有、临时对象释放、WASM memory growth 和 Worker 终止仍须在适配边界明确。 Replicad 的便利 API、FreeCAD 的文档管理与 OCAF 的事务都需要按其实际生命周期接线，不能仅靠 “成熟库”三个字推定这些边界已经满足。

本轮补查源码：TNaming_Builder、 TFunction 依赖更新、 TDocStd_Document、 BRepCheck_Analyzer、 布尔输入保护、 STEPControl_Writer。

9.5 本轮方案裁决

1. 几何后端采用 OCCT；有约束的草图采用 PlaneGCS。 这是当前机械零件目标、浏览器条件和实际 执行证据共同支持的选择。布尔、相交、偏置、倒角/圆角、拓扑索引和约束数值求解继续复用原生实现。 本轮没有证据要求换几何内核，商业内核的适配、许可和对照结果也尚不足以支持迁移决定。
2. 参数文档、重建与命名作为独立选型项。 当前薄 AMIR/OCCT 路径是实测基线；OCAF 的 TNaming/TFunction/文档事务是必须认真对照的成熟实现。扩展自研同类机制前，应先核对直接调用、 补绑定或薄适配是否更小；本轮不将“保留现状”宣布为已证明的最优解。
3. 高层封装按可删除的适配职责采用。 Replicad/CadQuery 需要保留原生 history、诊断和生命周期 时，先比较上游扩展点与补绑定；满足接受域并能合并旧实现才采用。不能为加入高层库再长期保留 一套等价现行执行路径，也不能因为少数方法缺输出就跳过整库复用调查。
4. 浏览器约束的成本单独判断。 若绑定、内存或维护成本使浏览器路线不再合适，则比较完整 FreeCAD 原生底座加薄接口，包括其部署、持久化和既有模型迁移成本。原生 API 已存在是候选资格， 不是浏览器闭环和历史兼容已通过的证据。
5. 底座扩张由具体建模需求触发。 当前先完成可组合、可编辑的单零件 Exact 链；多表示统一、 通用增量编译、插件平台与自研持久命名框架不作为这条链的预设依赖。既有保护与独立任务不因此删除。

9.6 已验证什么，以及能改变选型的下一份证据

本轮直接运行既有测试，没有新增测试平台或修改运行时：

• @aira/occt-spike 的 exact-feature-graph.test.ts 按名称选取 6/6 通过，32 项未运行：真实 WASM 壳体→圆孔→倒角、上游改尺寸与重排输入、歧义拒绝、操作间取消、无效壁厚清理、同堆 Revolve。
• @aira/web 的 constrained-sketch-planegcs-adapter-v0.1.test.ts 5/5 通过：真实 PlaneGCS 的 冗余/冲突诊断、线圆约束及残差、参数重解、圆弧规则。

这些结果支持当前内核与求解器能承担所检验职责，不是对 OCAF/FreeCAD/Replicad 替代收益的证明， 也不是全 CAD 能力、浏览器 E2E、长期内存或真实 AI 验收通过。

下一份有决策价值的证据，应在同一个壳体/圆孔/收边模型上对照当前路径和一个成熟机制候选： 连续改参，制造目标删除/分裂/多解，触发失败与取消，清空派生状态后重建。 比较几何和选择语义、正确拒绝、资源清理、新增绑定/包体、启动与重建成本，以及真正能退役的代码。 先做引用机制对照即可；TFunction、文档事务可以独立判定，无须同时接入整套 OCAF。

正确性与历史解释成立后，再用净维护/运行成本裁决“采用、保留当前薄适配或改变宿主”。 现有实现的投入不构成收益，候选库的功能清单也不构成收益；未知项保留为未知。 该对照沿用现有样本与研究记录，不把资料核对直接升级为运行时迁移或产品完成声明。