316 lines
19 KiB
Markdown
316 lines
19 KiB
Markdown
# 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`
|