# 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 才能可靠实现。