cadSet/docs/designir-3-support-analysis.md

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