# SimpleCADAPI 2.0.2 融合说明

## 融合结果

CadSet 已将内置 SimpleCADAPI 从 `2.0.1b1` 对齐到 `2.0.2`，并完成运行
环境、DesignIR 编译器、CAD Router、上传 STEP 验收、Skill、测试和文档
的同步接入。

这次不是简单复制依赖目录。新增能力已经进入实际执行链：

| 新能力 | CadSet 使用位置 | 当前状态 |
|---|---|---|
| `@model` / `ModelResult` | DesignIR SimpleCAD 编译器 | 已使用 |
| 语义标签与拓扑来源 | 每个 DesignIR 特征和布尔工具 | 已使用 |
| STEP B-Rep 严格比较 | 上传 STEP 独立验收区 | 已使用 |
| 螺栓、螺母、链轮、锥齿轮工厂 | cad-router 标准件识别 | 已纳入路由 |
| 单位与公差链 | cad-router 需求识别 | 已纳入路由，待扩展 DesignIR 映射 |
| Scene Schema / `.scene.zip` | SimpleCADAPI 产物能力 | 源码已具备，尚未替换现有 Viewer |
| Fusion 360 / SolidWorks 翻译 | SimpleCADAPI 派生导出能力 | 源码已具备，尚未开放前端按钮 |
| B-Rep 多视图与截面 XOR | 诊断工具 | 源码已具备，严格 compare 已接入 |

CAD Agent Studio 已同步读取新的路由结果，不再在路由字段缺失时静默
假定 Build123d。上传 STEP 的任务清单会保存 `routing_policy` 和
`strict_brep_acceptance` 报告，并在聊天结果中区分 `brep_exact` 与仅几何
通过的情况。

## 新的角色边界

### text-to-cad

继续是系统核心，但核心含义变为“编排层”，不是“默认建模后端”：

- CAD Router
- DesignIR 3.0 所有权
- SurfaceIR 上传 STEP 重建
- 需求细化和视觉修复
- 验收、产物和 Viewer 交付

### Build123d

作为平权建模后端，适合：

- 定制支架、壳体、轴、法兰和夹具
- 复杂草图、自由曲面、放样和扫掠
- 已有 build123d 源码的连续修改
- 源级装配与基准关系

### SimpleCADAPI 2.0.2

提升为平权建模与验收后端，适合：

- 齿轮、齿条、内齿圈、锥齿轮和摆线件
- 轴承、螺栓、螺母和滚子链轮
- 减速器、执行器和带运动约束的机构
- 需要 Model JSON 重放、语义标签和拓扑来源的模型
- 需要单位、公差链或 FreeCAD/Fusion 360/SolidWorks 翻译的模型
- 上传 STEP 的严格 B-Rep 几何与拓扑验收

## CAD Router 2.0

路由取消永久默认后端。两个后端从相同基础分开始，按以下证据评分：

1. 已有可编辑源属于哪个后端。
2. 是否存在直接覆盖的标准机械工厂。
3. 是否要求模型图重放、语义拓扑、单位、公差或 CAD 翻译。
4. 是否需要复杂自定义轮廓或自由曲面。
5. 是否需要装配和运动约束。
6. 是否需要特定验收能力。

主要决策示例：

| 请求 | 结果 | 原因 |
|---|---|---|
| 模数 2 直齿轮 | SimpleCADAPI | 有确定性标准工厂 |
| M8 螺栓 | SimpleCADAPI | 有紧固件工厂 |
| 滚子链轮 | SimpleCADAPI | 有链轮工厂 |
| 带语义标签和公差链的法兰 | SimpleCADAPI | 语义、单位和公差是主要要求 |
| 普通定制法兰 | Build123d，低置信度 | 两者都能表达，Build123d 的通用特征略优 |
| NURBS 自由曲面壳体 | Build123d | 定制曲面词汇更适合通用后端 |
| 修改已有 SimpleCAD Model JSON | SimpleCADAPI | 保持原生编辑源 |
| 上传 STEP 重建 | SurfaceIR | 重建引擎固定；后端评分只用于后续语义修改 |

路由输出新增：

- `routing_policy.version`
- `routing_policy.requirements`
- `routing_policy.native_source_backend`
- `routing_policy.score_margin`
- `routing_policy.effective_execution_engine`
- `routing_policy.validation_engines`

上传 STEP 时，`selected_backend` 表示后续语义修改的优选后端，
`effective_execution_engine` 明确为 `surfaceir`，避免把 SurfaceIR 重建
错误描述为 Build123d 或 SimpleCADAPI 重建。

## DesignIR → SimpleCADAPI

SimpleCAD 编译器现在使用：

```text
DesignIR feature
  -> SimpleCAD primitive/feature
  -> feature.<id> topology tag
  -> boolean lineage
  -> feature.<id>.result semantic tag
  -> capture_result
  -> ModelResult.model_json
  -> STEP
```

每个基础体、孔工具和最终特征结果都会进入模型图。这样 Model JSON 不再
只是低层操作列表，还可以根据特征 ID 定位语义对象，为后续参数修改和
非目标区域保持检查提供锚点。

## 上传 STEP 验收

上传 STEP 仍严格执行教师隔离：

```text
Teacher STEP
  -> 私有证据提取
  -> DesignIR 3.0 / SurfaceIR
  -> 无教师文件的独立重建
  -> SurfaceIR 几何验收
  -> SimpleCADAPI B-Rep 硬验收
```

SimpleCADAPI 比较器在验收区同时读取教师 STEP 和候选 STEP，检查：

- `target - candidate` 差集体积
- `candidate - target` 差集体积
- 几何点集是否一致
- 带几何标签的面/边/点邻接图是否同构

新增质量等级：

| 等级 | 含义 |
|---|---|
| `brep_exact` | 几何集合一致且拓扑邻接图同构 |
| `geometry_equal_topology_differs` | 几何通过，但拓扑结构不同，需要复查 |
| `geometry_accepted_brep_unavailable` | 原验收通过，但补充比较器不可用 |
| `review_required` | 只达到可用重建或存在其他验收问题 |

严格比较器不可用时会记录原因，不会伪造成通过；拓扑不一致时模型仍可供
查看，但任务状态为 `review_required`。

## 依赖更新

两个本地 Python 环境均已安装 SimpleCADAPI `2.0.2` 的新增运行依赖：

- `jsonschema`
- `rfc8785`
- `typing-extensions`

仓库的 `SimpleCADAPI/uv.lock` 已随上游版本同步。虚拟环境仍由 `.gitignore`
排除，不会提交。

## 已完成验证

本次融合已通过：

- cad-router：24 项测试
- DesignIR 编译器：11 项测试
- 上传 STEP 完整重建与 B-Rep 硬验收：1 项测试
- SimpleCADAPI 完整回归：934 项通过，3 项按可选环境条件跳过
- CAD Agent Studio：8 项测试，生产构建通过

完整回归包含：

- `@model` / `ModelResult`
- 单位
- 公差链
- B-Rep 逆向检查
- 螺栓和螺母
- 滚子链轮

## 后续扩展边界

本次没有直接把所有新能力暴露到网页：

- `.scene.zip` 与现有 CAD Viewer 存在功能重叠，需要先确定统一场景合同。
- Fusion 360 和 SolidWorks 翻译必须在对应软件或命令环境中做真实执行验收。
- 单位和公差已进入路由，但 DesignIR schema 仍需增加完整公差图映射。
- B-Rep 截面 XOR 适合失败诊断，不应默认对每个大模型高密度运行。

这些能力已经保留在源码和 Skill 中，后续接入不需要再次升级依赖。