# DesignIR 3.0 支持能力分析与补全范围

本文档分析当前 CadSet 通过 `DesignIR 3.0 JSON -> text-to-cad / SimpleCADAPI -> STEP`
生成模型时的能力边界，并给出 DesignIR 3.0 JSON 应补全的支持范围。目标是把
DesignIR 从“少量语义特征可编译 + SurfaceIR 可重建”推进为能承接两个生成后端主要能力的
统一可编辑模型契约。

## 结论摘要

- 当前 DesignIR 3.0 的顶层契约已经统一了三种模式：纯语义参数化、STEP 推断的
  SurfaceIR、以及语义层加编译后 SurfaceIR 快照的 hybrid 模式。
- STEP 上传重建路径相对完整：可抽取 analytic/B-spline surface、拓扑、边界、pcurve，
  再通过独立 rebuild、几何验收、SimpleCADAPI B-Rep 比较和参数扰动验收交付。
- 语义生成路径仍然很窄：`designir_pipeline.py` 目前只真正编译
  `extrude_circle`、`add_cylinder`、`extrude_rectangle`、`through_hole`、
  `polar_hole_pattern`。
- DesignIR 3.0 schema 对 `features`、`sketches`、`constraints` 的结构约束较弱，
  允许任意 object，但 compiler 实际支持的 operation 很少。这导致“JSON 看似可写”，
  但不能稳定生成模型。
- SimpleCADAPI 本身能力明显更强，覆盖 primitives、sketch、curve、revolve、sweep、
  loft、twisted sweep、boolean、fillet、chamfer、shell、pattern、assembly constraint、
  unit、tolerance、semantic tag、operation graph、translator 和标准机械件库。
- text-to-cad 当前主要负责路由、DesignIR 所有权、验证、SurfaceIR 重建、Viewer 交付；
  对语义 DesignIR 的通用后端编译能力仍集中在 `designir_pipeline.py` 的小交集内。

## 支持等级定义

| 等级 | 含义 |
| --- | --- |
| L0 | 不支持，或只能作为自由文本/未定义 object 存在 |
| L1 | 路由或文档知道该能力，但 DesignIR 不能稳定表达或编译 |
| L2 | DesignIR 可表达，但缺少一个或多个后端 compiler adapter |
| L3 | 可由一个后端稳定生成并导出 STEP |
| L4 | build123d 和 SimpleCADAPI 路径都可生成，且有基础验证 |
| L5 | 有标准工厂/语义图/参数扰动/验收或专门测试覆盖 |

## 当前系统分层

| 层 | 当前职责 | 主要证据 |
| --- | --- | --- |
| cad-router | 根据需求选择 build123d 或 SimpleCADAPI，上传 STEP 时切到 SurfaceIR 执行 | `text-to-cad/skills/cad-router/scripts/route.py` |
| DesignIR 3.0 schema | 定义统一 envelope、语义层、SurfaceIR 层、编辑接口、验证契约 | `designir-pipeline/contracts/designir-3.0.schema.json` |
| semantic compiler | 把语义 DesignIR 编译为 build123d 或 SimpleCADAPI STEP | `designir-pipeline/scripts/designir_pipeline.py` |
| SurfaceIR runtime | 从 STEP 抽取/重建 surface-parametric DesignIR，验证几何和语义参数编辑 | `designir-pipeline/scripts/surfaceir_pipeline.py` |
| SimpleCADAPI | 标准机械件、语义图、单位、公差、assembly、translator、B-Rep 比较 | `SimpleCADAPI/src/simplecadapi` 与测试 |
| cad-agent-studio | 任务、参数、导出、预览 UI 集成 | `cad-agent-studio/src/lib` 与 API routes |

## 模型类型支持矩阵

| 模型/零件类型 | text-to-cad 路由 | DesignIR 语义 JSON | build123d 编译 | SimpleCADAPI 编译 | 当前等级 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| 简单圆柱、圆盘、轴类 | 可识别 | `extrude_circle/add_cylinder` | 支持 | 支持 | L4 | 任意轴圆柱在 build123d 路径较好；SimpleCADAPI 路径圆柱支持任意轴 |
| 简单长方体、板、块 | 可识别 | `extrude_rectangle` | 支持 | 支持 | L4 | SimpleCADAPI box 当前要求正 Z 轴 |
| 法兰/轮毂/中心孔/螺栓孔阵列 | 可识别 | 圆柱 + 通孔 + polar hole | 支持 | 支持 | L4 | 当前最成熟的语义样例 |
| 单孔/通孔 | 可识别 | `through_hole` | 支持 | 支持 | L4 | 语义 compiler 中孔切割要求正 Z 轴 |
| 线性孔阵列 | SurfaceIR 可推断 | JSON 没有可编译语义 operation | 不支持 | 不支持 | L1 | SurfaceIR 可推断 `linear_hole_pattern`，语义 compiler 未实现 |
| 一般挤出草图 | 后端可做 | DesignIR 未定义稳定 profile vocab | 不支持 | 不支持 | L1 | 目前只规范化圆/矩形 |
| 旋转体、轴肩、锥台 | 后端可做 | 缺少 `revolve`/`cone` 语义 operation | 不支持 | 不支持 | L1 | SurfaceIR 可从 STEP 捕捉结果面，但语义生成不支持 |
| sweep/loft/twisted/helical sweep | 后端可做 | 缺少语义 operation | 不支持 | 不支持 | L1 | SimpleCADAPI 已有可回放操作 |
| fillet/chamfer/shell | 后端可做 | 缺少 modifier/selector 契约 | 不支持 | 不支持 | L1 | 最大缺口是稳定选择边/面 |
| 一般 boolean union/cut/intersect | 后端可做 | 只有隐式 union 和孔 cut | 部分 | 部分 | L2 | 需要把工具体、host、结果命名写入 JSON |
| 镜像/平移/旋转 | 后端可做 | 缺少 transform operation | 不支持 | 不支持 | L1 | SimpleCADAPI 支持表达式参数 |
| 线性/径向 pattern | 后端可做 | 缺少通用 pattern | 不支持 | 不支持 | L1 | 当前仅 polar hole special case |
| 齿轮、齿条、内齿圈、锥齿轮、摆线盘 | 路由到 SimpleCADAPI | 无标准工厂 feature | 不支持 | 不支持 | L1 | SimpleCADAPI stdlib 原生强，但 DesignIR 不会调用 |
| 螺栓、螺母、滚子链轮 | 路由到 SimpleCADAPI | 无标准工厂 feature | 不支持 | 不支持 | L1 | fastener/chain 工厂已有参数语义 |
| 滚珠轴承 | 路由到 SimpleCADAPI | 无 assembly/factory feature | 不支持 | 不支持 | L1 | SimpleCADAPI 返回 assembly，DesignIR part contract 未承接 |
| 行星/摆线减速器、关节执行器 | 路由倾向 SimpleCADAPI | 缺少 product/assembly/constraint JSON | 不支持 | 不支持 | L1 | examples 已证明后端能做复杂 product |
| 自由曲面/NURBS | 路由偏 build123d | SurfaceIR 可存 final surface；语义生成不足 | 低 | 低 | L1-L2 | 语义层缺少 profile/path/surface patch vocab |
| 上传 STEP 任意 B-Rep 重建 | route `--execute` | `surface_parametric` 完整 envelope | SurfaceIR 执行 | B-Rep 比较 | L5 | 这是重建路径，不等价于语义 authoring |

## 特征能力支持矩阵

| 特征类别 | 当前 DesignIR 语义支持 | 后端原生能力 | 主要差距 | 建议目标等级 |
| --- | --- | --- | --- | --- |
| 参数与表达式 | 数值参数、简单表达式、`mm/deg/count/ratio` | SimpleCADAPI 有 expression graph 和 units | 缺少 typed unit value、dimension checking、参数域/默认 UI hints | L5 |
| Datum/坐标系 | primary axis 和基本 axis | 两后端均可定位 | 缺少 datum plane、local frame、workplane、connector datum 的规范结构 | L4 |
| Sketch | 仅圆/矩形归一化 | SimpleCADAPI 支持 point/line/circle/arc/bspline 和约束 | schema 未定义 sketch entity/constraint vocab | L4 |
| Primitive | 圆柱/圆挤出、矩形盒 | box/cylinder/cone/sphere 等 | 缺少 cone、sphere、torus-like primitive、primitive metadata | L4 |
| Extrude | 圆/矩形 profile 的 add body | 一般 face extrude | 缺少 profile 引用、direction、extent、symmetric、cut/new/merge 模式 | L4 |
| Revolve | 无 | SimpleCADAPI/build123d 均可 | 缺少 axis/origin/angle/profile contract | L4 |
| Sweep/Loft | 无 | SimpleCADAPI 已有 sweep/loft/twisted/helical | 缺少 path/profile/section/ruled/twist contract | L3-L4 |
| Boolean | add body 隐式 union；hole cut special case | union/cut/intersect | 缺少 body graph、tool list、skip strategy、tracking policy | L4 |
| Hole feature | through hole、polar hole pattern | 后端可更多 | 缺少 blind/counterbore/countersink/threaded/tapped/slot hole | L5 |
| Edge/face modifiers | 无 | fillet/chamfer/shell | 缺少 stable selector 与作用范围 | L4 |
| Patterns | polar hole only | linear/radial/mirror pattern | 缺少通用 source feature、transform series、merge/cut policy | L4 |
| Standard factory | 无 | SimpleCADAPI stdlib 强 | 缺少 factory op、参数 schema、生成 graph/metadata 绑定 | L5 |
| Assembly/product | 另有 assembly schema，但未接入 DesignIR semantic compiler | SimpleCADAPI assembly/connector/constraint 完整 | DesignIR part envelope 与 product-level contract 分离 | L3-L5 |
| Semantic tags/lineage | feature id、preserved interface | SimpleCADAPI tag/topology lineage/source mapping | 缺少 output role、selector by semantic tag、lineage carry-over | L5 |
| Tolerance/material | validation_contract 字符串为主 | SimpleCADAPI units/tolerance/material | 缺少公差链、材料、表面处理的结构化字段 | L4 |
| Translators/scene package | 无 | SimpleCADAPI FreeCAD/Fusion/SolidWorks/scene.zip | DesignIR 没声明 translator intent 和 export contract | L3 |
| Validation/edit | perturbation 契约、SurfaceIR 参数验收 | 两路径均可扩展 | 语义 compiler 的 edit validation 只覆盖少数参数 | L5 |

## 当前 DesignIR 3.0 JSON 的关键不足

1. `features` 是松散 object array，缺少 machine-readable operation enum 和 per-operation schema。
2. semantic compiler 仍把 DesignIR 3.0 压平成 legacy 2.0 payload 再验证，实际 vocabulary 被
   `SUPPORTED_OPERATIONS` 限制。
3. schema 层能容纳 `sketches/patterns/constraints/attachments`，但 compiler 只使用极少字段。
4. 缺少稳定 selector 模型。fillet/chamfer/shell/general boolean 需要选择边/面/feature 输出，
   不能依赖 STEP face id 或后端临时拓扑 id。
5. SimpleCADAPI 的 `ModelResult`、operation graph、semantic tag、source mapping、units、
   tolerance chain 没有映射回 DesignIR。
6. SimpleCADAPI 标准工厂已覆盖多个机械族，但 DesignIR 无 `standard_factory` feature，
   导致路由能选 SimpleCADAPI，JSON compiler 却不会生成齿轮/轴承/紧固件等模型。
7. assembly/product 能力没有成为 DesignIR 3.0 的一等对象。复杂 reducers/actuators 只能靠
   原生 Python generator，不能靠 DesignIR JSON 表达。
8. build123d 的广义建模能力没有在 DesignIR vocabulary 中体现；当前 DesignIR 对它也只开放
   圆柱、盒子和孔阵列小子集。

## 补全后的 DesignIR 3.0 JSON 支持范围

补全应分为“统一语义词汇”和“后端 adapter 映射”两部分。DesignIR 不应直接复制后端 API，
但必须覆盖足够稳定的建模意图。

### 1. 通用结构

建议新增或规范化以下结构：

- `operation_registry_version`: 语义 feature vocabulary 版本。
- `semantic_layer.bodies`: 命名 body graph，用于区分 source body、tool body、result body。
- `semantic_layer.feature_outputs`: feature 输出角色，例如 `body`, `top_face`, `side_faces`,
  `created_edges`, `tool_body`。
- `semantic_layer.selectors`: 以 semantic role/tag、feature output、datum relation、geometry rule
  选择边/面/体。
- `backend_capabilities`: 每个 feature 对 `build123d`、`simplecadapi` 的支持状态、fallback、
  最低版本和测试状态。
- `model_graph_artifacts`: SimpleCADAPI `*.simplecad.model.json`、operation graph、scene package
  等派生产物引用。

### 2. 参数、表达式、单位

目标支持：

- typed parameter：`length`、`angle`、`count`、`ratio`、`dimensionless`、`area`、`volume`。
- `value_ref`: 支持 literal、parameter、expression、unit value。
- 参数域：`min`、`max`、`step`、`recommended_values`、`integer_only`。
- 派生表达式 DAG：记录依赖、单位推断、是否可编辑。
- UI/edit hints：slider、number input、enum、toggle，但不替代验证。

### 3. Datum、Frame、Connector

目标支持：

- datum point/axis/plane/frame/workplane。
- local coordinate frame 与 parent frame。
- connector datum：face/edge/vertex/placement connector，用于 assembly 和可编辑接口。
- preserved interface：用 connector 和 semantic selector 表示，而不是纯字符串。

### 4. Sketch 与 Profile

目标支持：

- sketch entity：point、line、circle、arc、ellipse、polyline、bspline、construction geometry。
- sketch constraints：coincident、distance、distance_x/y、horizontal、vertical、parallel、
  perpendicular、tangent、concentric、equal_length、equal_radius、diameter、radius、angle、
  midpoint、symmetric、fix。
- profile：closed wire、outer loop、inner loops、face from sketch、face from wires。

### 5. Solid Feature Vocabulary

第一阶段应补齐两后端高确定性的共同能力：

- `primitive_box`
- `primitive_cylinder`
- `primitive_cone`
- `primitive_sphere`
- `extrude`
- `revolve`
- `boolean_union`
- `boolean_cut`
- `boolean_intersect`
- `through_hole`
- `blind_hole`
- `counterbore_hole`
- `countersink_hole`
- `linear_pattern`
- `radial_pattern`
- `mirror_feature`
- `translate_feature`
- `rotate_feature`
- `fillet`
- `chamfer`
- `shell`

第二阶段补齐曲面和复杂生成：

- `sweep`
- `loft`
- `twisted_sweep`
- `helical_sweep`
- `thread_external`
- `thread_internal`
- `knurl`
- `rib`
- `boss`
- `pocket`
- `slot`
- `draft`
- `surface_patch`
- `surface_trim`

### 6. Standard Factory Vocabulary

DesignIR 应提供稳定的 `standard_factory` feature，用于调用 SimpleCADAPI 标准库，同时保留
参数语义和 ModelResult graph：

| family | factory operation | 关键参数 |
| --- | --- | --- |
| spur gear | `standard_factory.gear.spur` | `n_teeth`, `module`, `pressure_angle`, `gear_height`, `backlash`, bore |
| helical gear | `standard_factory.gear.helical` | spur 参数 + `helix_angle/handedness` |
| herringbone gear | `standard_factory.gear.herringbone` | helical 参数 + center gap/phase |
| ring gear | `standard_factory.gear.ring` | internal teeth、rim、bore、height |
| straight bevel gear | `standard_factory.gear.straight_bevel` | `n_teeth`, `module`, `pitch_angle`, `face_width` |
| rack | `standard_factory.gear.rack` | tooth count/length、module、height、width |
| cycloidal disc | `standard_factory.gear.cycloidal_disc` | lobe count、pin radius、eccentricity、disc thickness |
| bolt | `standard_factory.fastener.bolt` | diameter、length、head style、drive style、thread style/detail |
| nut | `standard_factory.fastener.nut` | diameter、width、height、nut style、hole style、thread detail |
| roller chain sprocket | `standard_factory.chain.roller_sprocket` | tooth count、chain pitch、roller diameter、thickness、bore radius |
| ball bearing | `standard_factory.bearing.ball_bearing` | inner/outer diameter、width、ball diameter/count、clearance |

这些 feature 对 build123d 的支持可以是 `unsupported` 或 `fallback_to_backend_native_python`，
但 DesignIR 必须诚实记录；对 SimpleCADAPI 应达到 L5。

### 7. Assembly/Product Vocabulary

复杂机械产品需要 product-level DesignIR，而不只是 part-level DesignIR：

- `components`: part、subassembly、standard factory component。
- `placements`: explicit placement、connector-to-connector placement。
- `connectors`: face/edge/vertex/placement connector。
- `constraints`: fixed、revolute、prismatic、gear、belt、rack-pinion。
- `solve_policy`: strict/non-strict、residual thresholds。
- `public_interfaces`: 对外暴露的轴线、安装面、孔系、连接器。
- `export_policy`: STEP compound、scene package、URDF/MJCF fixed-base 或显式机构导出。

短期可复用 `assembly-designir-1.0.schema.json`，但需要在 DesignIR 3.0 文档中明确
part 与 product 的边界和交付 artifact contract。

### 8. Validation Contract 补全

每个新增 feature 至少要有：

- geometry checks：solid count、volume、bounds、face/edge count、surface type mix。
- semantic checks：参数是否驱动目标 feature、selector 是否解析到非空对象。
- edit checks：参数扰动后目标变化、非目标 interface 保持。
- backend checks：build123d/SimpleCADAPI 生成一致性，或明确单后端支持。
- graph checks：SimpleCADAPI replay、model JSON roundtrip、semantic tag presence。
- translator checks：需要导出 FreeCAD/Fusion/SolidWorks 时才启用。

## 推荐实现阶段

### P0: 文档和注册表对齐

- 把本文档中的 feature vocabulary 拆成 machine-readable `designir-capabilities.json`。
- 在 `designir-3.0.schema.json` 中给 `features` 增加 operation discriminators。
- 保留 `missing_capabilities`，但要求 unsupported feature 必须列明后端和原因。

### P1: 两后端共同核心

- 实现 cone、sphere、general extrude、revolve、boolean union/cut/intersect。
- 实现 linear/radial pattern、transform、fillet、chamfer、shell。
- 为 build123d 和 SimpleCADAPI 都加 compiler tests。

### P2: Sketch/Profile

- 定义 sketch entity 和 constraints schema。
- 支持 face from sketch/wire，并让 extrude/revolve/sweep/loft 引用 profile。
- 加入 selector by feature output role，避免 brittle topology refs。

### P3: SimpleCADAPI 标准机械件

- 增加 `standard_factory.*` operation。
- 输出 `.simplecad.model.json` 并在 `cad-task.json` 中登记。
- 对 gear、fastener、bearing、chain 四类先做端到端测试。

### P4: Product/Assembly

- 统一 part DesignIR 与 assembly DesignIR 的引用关系。
- 映射 SimpleCADAPI assembly、connector、constraint、solve report。
- 让 reducer/actuator 类模型可由 JSON 组织，而不是只能依赖示例 Python。

### P5: Surface/Freeform 与高级编辑

- 在 semantic layer 增加 surface patch、trim、loft continuity、NURBS control support。
- 将 SurfaceIR 的推断参数与语义 authoring 参数合流，但仍区分 inferred 与 authored。
- 对上传 STEP 的语义修复和新建自由曲面模型建立共同 vocabulary。

## 当前优先级建议

最高优先级不是继续扩大 router 关键词，而是扩展 DesignIR 语义 vocabulary 和 compiler adapter：

1. 先补 `operation schema + compiler adapter + tests` 的闭环。
2. 然后补 `standard_factory.*`，因为 SimpleCADAPI 已经有成熟工厂，收益最大。
3. 再补 selector/feature output role，支撑 fillet/chamfer/shell/general boolean。
4. 最后补 product-level assembly，使 reducer、bearing、actuator 等复杂模型真正能由
   DesignIR JSON 表达和编辑。

## 参考文件

- `text-to-cad/skills/cad-router/references/designir-3.0.md`
- `text-to-cad/skills/cad-router/references/capabilities.md`
- `text-to-cad/skills/cad-router/scripts/capabilities.json`
- `text-to-cad/skills/cad-router/scripts/route.py`
- `text-to-cad/skills/cad-router/scripts/reconstruct_step.py`
- `designir-pipeline/contracts/designir-3.0.schema.json`
- `designir-pipeline/scripts/designir_pipeline.py`
- `designir-pipeline/scripts/surfaceir_pipeline.py`
- `designir-pipeline/tests/test_designir_pipeline.py`
- `designir-pipeline/tests/test_surfaceir_pipeline.py`
- `SimpleCADAPI/src/simplecadapi/__init__.py`
- `SimpleCADAPI/src/simplecadapi/operations.py`
- `SimpleCADAPI/src/simplecadapi/std/gear.py`
- `SimpleCADAPI/src/simplecadapi/std/fastener.py`
- `SimpleCADAPI/src/simplecadapi/std/bearing.py`
- `SimpleCADAPI/src/simplecadapi/std/chain.py`