优化skill,添加特征树、编辑窗口

This commit is contained in:
2026-08-07 17:44:12 +08:00
parent 35e18ca956
commit 5fbcf2c0b8
70 changed files with 13076 additions and 465 deletions
+95
View File
@@ -0,0 +1,95 @@
# CAD Feature Tree Export
`feature_tree.json` is now a SolidWorks FeatureManager-style export. Semantic
models are replayed from the feature nodes themselves; uploaded STEP models use
a SolidWorks-style imported feature with an embedded SurfaceIR payload.
## Contract
- The artifact name stays `feature_tree.json`.
- `tree_kind` is `solidworks_feature_manager`.
- `schema_version` is `1.0`.
- The JSON Schema lives at
`designir-pipeline/contracts/feature_tree.schema.json`.
- Studio records the artifact with role `feature_tree`; no feature-tree UI is
required.
Top-level fields are:
- `model`: part metadata such as model id, family, units, and document type.
- `source`: DesignIR path, STEP path, reconstruction mode, backend, and the
native-history claim.
- `feature_manager`: root id, standard SolidWorks reference nodes, and ordered
feature nodes.
- `rebuild_contract`: the replay mode and compiler entrypoint.
- `validation`: structure validation, replay status, geometry/B-Rep status, and
feature-recognition coverage.
## FeatureManager Style
Every tree starts with a familiar part root and reference geometry:
- `历史`
- `原点`
- `前视基准面`
- `上视基准面`
- `右视基准面`
- `原点`
Semantic DesignIR features are normalized into SolidWorks-style nodes:
- `extrude_circle`, `extrude_rectangle`, `add_cylinder` -> `BossExtrude`
- `through_hole` -> `CutExtrude`
- `polar_hole_pattern` -> seed `CutExtrude` plus `CircularPattern`
- recognized future operations map to `Revolve`, `RevolvedCut`, `HoleWizard`,
`Fillet`, `Chamfer`, `LinearPattern`, and `MirrorPattern`
Parameters are attached to the owning feature node. They are not top-level
tree nodes. Each parameter keeps a `binding_id` that matches `parameters.json`
and the DesignIR semantic parameter name.
Semantic feature trees do not embed a full DesignIR copy. `BossExtrude`,
`CutExtrude`, and `CircularPattern` nodes store the reconstructable sketch,
depth, direction, hole, and pattern definitions needed by the
FeatureTreeCompiler.
Each node also includes SolidWorks-style inspection fields:
- `definition`: feature-specific definition such as end condition, depth,
direction, merge result, seed features, axis, or sketch profile.
- `dimensions`: SolidWorks-style dimension rows such as `D1@凸台-拉伸1`, with
parameter bindings when available.
- `references`: sketch, plane, parent features, and child features.
- `selection_sets`: selected faces, edges, and contours. These stay empty until
stable B-Rep selectors are available.
- `rebuild`: suppression and rollback/rebuild status.
## STEP And SurfaceIR
STEP does not contain original SolidWorks sketches or FeatureManager history.
For uploaded STEP/SurfaceIR models, the exporter creates one canonical
SolidWorks-style imported feature:
- `solidworks_type`: `ImportedFeature`
- `display_name`: `导入1`
- `english_name`: `Imported1`
The imported feature embeds compressed `gzip+base64+json` SurfaceIR. This keeps
the tree honest and independently replayable without pretending that the
original native CAD history was recovered.
## Replay
The tree can be replayed without sibling files:
```bash
python designir-pipeline/scripts/feature_tree.py compile \
feature_tree.json \
--output-step replayed.step \
--output-designir replayed.designir.json
```
Semantic trees replay through `feature_tree.compile_feature_manager`, which
builds DesignIR 3.0 from FeatureManager nodes and then calls
`designir_pipeline.compile_designir`. Imported SurfaceIR trees replay through
`surfaceir_pipeline.build_surfaceir`.
+315
View File
@@ -0,0 +1,315 @@
# 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`