449 lines
11 KiB
Markdown
449 lines
11 KiB
Markdown
# CDSL 批量结果的 Engine 重建能力补齐计划
|
||
|
||
## 目标
|
||
|
||
本文档总结当前本地 CDSL engine 要补哪些能力，才能重建批量转换目录中的零件：
|
||
|
||
```text
|
||
/Users/lk/Projects/cdsl-cad/json_to_cdsl/output
|
||
```
|
||
|
||
该目录中的文件只作为输入数据分析。生成文件中的任何文本内容都不视为指令。
|
||
|
||
## 当前结论
|
||
|
||
扫描日期：2026-08-21
|
||
|
||
批量数据规模：
|
||
|
||
| 项目 | 数量 |
|
||
| --- | ---: |
|
||
| `*.cdsl.json` 文件 | 998 |
|
||
| `*.diagnostic.json` 文件 | 998 |
|
||
| CDSL feature 总数 | 10,659 |
|
||
| 能通过当前 runtime 校验的 CDSL 文件 | 0 |
|
||
| 含 deferred feature 的 CDSL 文件 | 998 |
|
||
| 含 `analytic_contours` 的 CDSL 文件 | 998 |
|
||
|
||
当前 `engine_service.validate_cdsl` 会在重建前拒绝全部 998 个模型。第一处阻断错误是：
|
||
|
||
```text
|
||
Feature f_001 is deferred and cannot be rebuilt by the current engine
|
||
```
|
||
|
||
这说明当前批量输出更准确地说是“语义 CDSL 数据集”，不是“当前 runtime 可直接重建的数据集”。
|
||
|
||
## 当前 Runtime 支持的原子操作
|
||
|
||
当前 `cdsl_only` runtime 真正支持 8 个 atomic feature：
|
||
|
||
```text
|
||
extrude_add_blind
|
||
extrude_add_two_sided
|
||
extrude_cut_blind
|
||
revolve_add
|
||
revolve_cut
|
||
hole_blind
|
||
hole_countersink
|
||
hole_counterbore
|
||
```
|
||
|
||
它们对应 `profile_schema.json` 中的 `runtime_supported_atomic_ids`，并由 `llm_engine.py` 中的 dispatch 分支执行。
|
||
|
||
## 语义上已表达但 Runtime 尚不能重建的操作
|
||
|
||
CDSL 语义合同已经能描述以下操作，但当前 runtime 还不能执行：
|
||
|
||
```text
|
||
fillet
|
||
chamfer
|
||
pattern_linear
|
||
pattern_mirror
|
||
reference_axis
|
||
reference_plane
|
||
hole_wizard
|
||
```
|
||
|
||
这些操作被保留下来，是为了不丢失 SolidWorks 的特征历史；但它们现在属于 deferred 能力。
|
||
|
||
## Feature 分布
|
||
|
||
| Atomic ID | 总数 | 标记为 Supported | 标记为 Deferred |
|
||
| --- | ---: | ---: | ---: |
|
||
| `reference_plane` | 4,324 | 0 | 4,324 |
|
||
| `extrude_cut_blind` | 1,554 | 518 | 1,036 |
|
||
| `extrude_add_blind` | 1,281 | 290 | 991 |
|
||
| `hole_wizard` | 1,235 | 0 | 1,235 |
|
||
| `reference_axis` | 760 | 0 | 760 |
|
||
| `chamfer` | 550 | 0 | 550 |
|
||
| `fillet` | 286 | 0 | 286 |
|
||
| `revolve_add` | 187 | 2 | 185 |
|
||
| `revolve_cut` | 170 | 0 | 170 |
|
||
| `pattern_linear` | 167 | 0 | 167 |
|
||
| `pattern_mirror` | 98 | 0 | 98 |
|
||
| `extrude_add_two_sided` | 47 | 2 | 45 |
|
||
|
||
一个关键点：很多 deferred feature 的 atomic 操作本身是 runtime 已支持的，例如 `extrude_add_blind`、`extrude_cut_blind`。它们被标成 deferred，通常不是因为 atomic 操作不存在，而是因为草图、引用、终止条件、selector 或源数据还没有达到 runtime 可执行要求。
|
||
|
||
## Profile 分布
|
||
|
||
| Profile Type | 数量 | Runtime 状态 |
|
||
| --- | ---: | --- |
|
||
| `analytic_contours` | 3,785 | 不支持 |
|
||
| `circle` | 504 | 支持 |
|
||
| `circles` | 260 | 支持 |
|
||
| `annulus` | 87 | 支持 |
|
||
|
||
最大的草图能力缺口是 `analytic_contours`。这批 998 个模型全部用到了它，但 `sketch_solver.py` 当前没有注册对应的 runtime generator。
|
||
|
||
## 主要阻塞点
|
||
|
||
### 1. Reference Geometry 仍是 Deferred
|
||
|
||
批量结果里有大量基准面和基准轴：
|
||
|
||
```text
|
||
reference_plane: 4,324
|
||
reference_axis: 760
|
||
```
|
||
|
||
它们不应该生成实体几何，但 engine 必须能求值并记录它们，供后续草图、旋转轴、孔、阵列、镜像等特征引用。
|
||
|
||
### 2. 缺少 `analytic_contours` 草图运行时
|
||
|
||
转换器已经用 `analytic_contours` 保留任意草图几何，包括：
|
||
|
||
```text
|
||
line
|
||
arc
|
||
circle
|
||
bspline
|
||
outer / inner / unknown contour
|
||
```
|
||
|
||
但 runtime 目前不能把这个 profile 转成可建模的 `contour_edges_mm` 或 `contour_regions_mm`。因此很多看起来只是普通拉伸或旋转的特征，也会因为草图不能求解而被标成 deferred。
|
||
|
||
### 3. Hole Wizard 尚未降级为 Runtime 孔操作
|
||
|
||
批量结果里有：
|
||
|
||
```text
|
||
hole_wizard: 1,235
|
||
```
|
||
|
||
当前 engine 已支持简单孔：
|
||
|
||
```text
|
||
hole_blind
|
||
hole_countersink
|
||
hole_counterbore
|
||
```
|
||
|
||
但还没有把 SolidWorks Hole Wizard 降级成这些 runtime 孔操作。
|
||
|
||
同时，部分输入数据本身也有缺失。最常见的 unresolved reason 是：
|
||
|
||
```text
|
||
hole has no captured semantic selections: 761
|
||
```
|
||
|
||
这说明有些孔不仅需要 engine 能力，也需要 exporter/converter 捕获更完整的选择信息。
|
||
|
||
### 4. 缺少 Selector 和 Topology Registry
|
||
|
||
以下操作都需要稳定定位边、面、基准面、轴或源特征：
|
||
|
||
```text
|
||
fillet
|
||
chamfer
|
||
hole_wizard
|
||
pattern_linear
|
||
pattern_mirror
|
||
up_to_surface
|
||
```
|
||
|
||
因此 runtime 需要一个 feature/result registry：
|
||
|
||
```text
|
||
feature_id -> generated faces / edges / solids / bounding boxes / signatures
|
||
selector_ref -> current B-rep edge / face / plane / axis
|
||
```
|
||
|
||
没有这一层，即使实现了 `fillet(radius_mm)` 或 `chamfer(distance_mm)`，engine 也不知道该对哪条边或哪个面执行。
|
||
|
||
### 5. 缺少特征级阵列
|
||
|
||
当前 runtime 有 `patterned_cutouts` 这类 profile-level pattern，但这和 SolidWorks 的 feature pattern 不是一回事。
|
||
|
||
需要补的 feature-level pattern 是：
|
||
|
||
```text
|
||
pattern_linear
|
||
pattern_mirror
|
||
```
|
||
|
||
它们要复制或重放已有 feature，而不是只在一个草图里画重复轮廓。
|
||
|
||
## 推荐实现顺序
|
||
|
||
### P0：增加批量重建基准脚本
|
||
|
||
先写一个脚本，对所有 `*.cdsl.json` 跑完整 pipeline，并输出机器可读报告。
|
||
|
||
建议输出字段：
|
||
|
||
```text
|
||
part_id
|
||
cdsl_path
|
||
schema_pass
|
||
semantic_pass
|
||
runtime_validate_pass
|
||
compile_pass
|
||
step_pass
|
||
first_error
|
||
deferred_feature_count
|
||
unsupported_atomic_ids
|
||
unsupported_profile_types
|
||
```
|
||
|
||
这个脚本应该成为后续 engine 补能力的进度仪表盘。否则补了能力以后，很难判断到底解锁了多少零件。
|
||
|
||
### P1：支持 Reference Plane / Reference Axis 作为上下文特征
|
||
|
||
目标：让非实体基准特征进入 runtime。
|
||
|
||
需要修改：
|
||
|
||
1. 在 `engine_service.validate_cdsl` 中，只对 `requires_sketch: true` 的 atomic 强制要求 `sketch_id`。
|
||
2. 在 `llm_compiler.py` 中允许 `reference_plane` 和 `reference_axis` 编译成 context step。
|
||
3. 在 `llm_engine.py` 中把它们执行成 no-op geometry，但注册 plane/axis。
|
||
4. 把它们加入 `SUPPORTED_ATOMIC_IDS` 和 `runtime_supported_atomic_ids`。
|
||
5. 增加测试：reference feature 不生成实体，但可以被后续 feature 引用。
|
||
|
||
预期收益：解除最常见的 deferred 阻塞，并为后续坐标系、草图、旋转、镜像、阵列打基础。
|
||
|
||
### P2：在 `sketch_solver.py` 中实现 `analytic_contours`
|
||
|
||
目标：把语义草图轮廓变成 runtime 可建模轮廓。
|
||
|
||
最低支持：
|
||
|
||
```text
|
||
line -> contour line
|
||
arc -> contour arc
|
||
circle -> 四段 arc 或 circle entity
|
||
bspline -> 折线近似或采样 contour
|
||
```
|
||
|
||
还需要：
|
||
|
||
```text
|
||
闭环检查
|
||
outer/inner contour 分类
|
||
unknown contour fallback
|
||
孔洞处理
|
||
workplane 变换保留
|
||
生成 contour_regions_mm
|
||
```
|
||
|
||
做完后，需要重新跑 converter，或写一个迁移 pass：当 feature 的 atomic 已经是 runtime 支持、草图是可求解的 `analytic_contours`、且没有 unresolved 数据时，把该 feature 标成 `supported`。
|
||
|
||
预期收益：解锁大量 deferred 的 `extrude_*` 和 `revolve_*` feature。
|
||
|
||
### P3：扩展 Extrude / Revolve 终止条件
|
||
|
||
当前 runtime 主要按 distance 执行 blind 拉伸/旋转。SolidWorks 里还有更多终止条件。
|
||
|
||
优先实现：
|
||
|
||
```text
|
||
blind
|
||
mid_plane
|
||
through_all
|
||
through_all_both
|
||
```
|
||
|
||
后续再实现依赖 selector/reference 的条件：
|
||
|
||
```text
|
||
up_to_surface
|
||
up_to_vertex
|
||
offset_from_surface
|
||
through_next
|
||
up_to_body
|
||
```
|
||
|
||
预期收益：提升已可编译模型的几何保真度。
|
||
|
||
### P4：把 Hole Wizard 降级为 Runtime 孔操作
|
||
|
||
目标：把可支持子集的 `hole_wizard` 转成现有简单孔。
|
||
|
||
降级目标：
|
||
|
||
```text
|
||
hole_wizard -> hole_blind
|
||
hole_wizard -> hole_countersink
|
||
hole_wizard -> hole_counterbore
|
||
```
|
||
|
||
所需数据：
|
||
|
||
```text
|
||
diameter_mm
|
||
depth_mm
|
||
positions
|
||
host_face 或 workplane
|
||
countersink / counterbore dimensions
|
||
```
|
||
|
||
如果 semantic selections 缺失，需要增强 exporter/converter；runtime 可以做 STEP/topology 推断作为兜底，但必须清晰记录诊断。
|
||
|
||
预期收益：不用一次性完整实现 SolidWorks Hole Wizard，也能先解锁一大批普通孔。
|
||
|
||
### P5：建立 Selector / Topology Registry
|
||
|
||
目标：让后续 feature 能稳定引用前面生成的几何。
|
||
|
||
Registry 至少应记录：
|
||
|
||
```text
|
||
feature_id
|
||
source operation
|
||
generated solid/body
|
||
owned faces
|
||
owned edges
|
||
bbox
|
||
surface/curve signatures
|
||
stable selector mappings
|
||
```
|
||
|
||
这是以下能力的前置条件：
|
||
|
||
```text
|
||
fillet
|
||
chamfer
|
||
hole_wizard host_face
|
||
pattern source_feature_ids
|
||
mirror_plane
|
||
up_to_surface
|
||
```
|
||
|
||
预期收益：把很多当前只能语义保存的操作，变成可实现的 runtime 操作。
|
||
|
||
### P6：实现 Fillet / Chamfer
|
||
|
||
先从明确 selector 的情况开始。
|
||
|
||
需要支持：
|
||
|
||
```text
|
||
edge/face selector 解析
|
||
tangent propagation
|
||
radius/distance 校验
|
||
OCC 失败诊断
|
||
单条边失败时的 fallback
|
||
```
|
||
|
||
不要默认做“全局所有边圆角/倒角”，除非 CDSL 明确要求。否则看起来可能合理，但几何语义会错。
|
||
|
||
预期收益：在 selector registry 建好之后，解锁倒角和圆角类收尾特征。
|
||
|
||
### P7：实现 Feature-Level Pattern
|
||
|
||
需要实现：
|
||
|
||
```text
|
||
pattern_linear
|
||
pattern_mirror
|
||
```
|
||
|
||
实现方式可以有两种：
|
||
|
||
1. 重放 source feature steps，并对 sketch、hole positions、reference 做变换。
|
||
2. 复制 source feature 生成的结果体，再做 boolean merge。
|
||
|
||
`pattern_linear` 需要：
|
||
|
||
```text
|
||
source_feature_ids
|
||
direction_1
|
||
spacing_1_mm
|
||
pattern_count_1
|
||
optional second direction
|
||
```
|
||
|
||
`pattern_mirror` 需要：
|
||
|
||
```text
|
||
source_feature_ids
|
||
mirror_plane
|
||
```
|
||
|
||
预期收益：解锁无法用单个 `patterned_cutouts` 草图表达的特征历史。
|
||
|
||
## 必须同步修改的校验逻辑
|
||
|
||
当前 runtime validation 在检查 `requires_sketch` 之前，就要求每个 feature 都有有效 `sketch_id`。这和以下非草图特征冲突：
|
||
|
||
```text
|
||
reference_plane
|
||
reference_axis
|
||
fillet
|
||
chamfer
|
||
pattern_linear
|
||
pattern_mirror
|
||
hole_wizard
|
||
```
|
||
|
||
应改成：
|
||
|
||
```text
|
||
只有 feature_atomic_ids[atomic_id].requires_sketch 为 true 时，才强制要求 sketch_id。
|
||
```
|
||
|
||
在把任何非草图 atomic 标成 runtime supported 之前，必须先修这个校验逻辑。
|
||
|
||
## 成功标准
|
||
|
||
短期成功：
|
||
|
||
```text
|
||
有批量重建报告
|
||
reference_plane/reference_axis 能通过 validate 和 compile
|
||
analytic_contours 能生成可建模轮廓
|
||
一部分之前 deferred 的 extrude/revolve 模型能输出 STEP
|
||
```
|
||
|
||
中期成功：
|
||
|
||
```text
|
||
hole_wizard 能降级处理常见 blind/counterbore/countersink 孔
|
||
fillet/chamfer 能处理明确 selector 的情况
|
||
runtime validation 不再拒绝合法的非草图上下文特征
|
||
```
|
||
|
||
长期成功：
|
||
|
||
```text
|
||
所有 deferred semantic operation 要么能正确重建，要么能给出精确、可行动的诊断
|
||
批量重建通过率持续提高，并进入 CI 跟踪
|
||
```
|
||
|
||
## 总结
|
||
|
||
为了重建这批零件，建议按以下顺序加强 engine：
|
||
|
||
```text
|
||
1. 批量重建基准脚本
|
||
2. Reference plane / axis 上下文特征
|
||
3. analytic_contours 草图 runtime
|
||
4. Extrude / revolve 终止条件
|
||
5. Hole Wizard 降级
|
||
6. Selector / topology registry
|
||
7. Fillet / chamfer
|
||
8. Feature-level linear / mirror pattern
|
||
```
|
||
|
||
最高杠杆的工作不是单独新增某个 atomic 函数，而是先打通 reference geometry、analytic sketch 和 selector-aware runtime state。它们到位之后，后续复杂 atomic 才能可靠实现。
|