likang
738934416e
- 扩展 CDSL engine 的 shell、sweep、loft、reference plane、pattern 等运行时能力， 支持新的实体结果模式、双向拉伸、曲线扫掠、镜像/圆周阵列及相关 selector 解析。 - 完善 Build123d 适配层的拓扑快照、Compound/ShapeList 兼容处理和旋转曲面识别， 兼容 Python 3.12 / 当前 Build123d 缺少 axis_of_rotation 的合法曲面场景。 - 扩展 CDSL schema、profile schema、capability analysis、semantic validation 和 sketch solver，使新增建模操作能够被校验、执行并保留可诊断的部分结果。 - 完善 CADFS FeatureScript lowering： 支持 shell、sweep、surface/实体 loft、圆周阵列副本、镜像副本、删除阵列实例、 新 body 操作、更多拉伸终止条件和 reference plane 变体。 - 补齐椭圆、B-spline、环形区域、imprint、SWEPT_FACE、CAP_FACE、OFFSET_FACE 等 草图和拓扑引用的转换逻辑，改善后续特征的工作平面、轴线和 profile 定位精度。 - 改进 selector binding：支持 pattern 前缀复合 B-rep 快照、交集顶点引用、 多面 match_mode=all、圆柱轴线/半径和面积下限等稳定匹配条件。 - 修复 MID_PLANE 法向统一后交线方向未同步的问题，恢复 00287955 基准面的正确位置； 修复 00542223 sweep 路径反转后的切线契约和 00423838 的拓扑面数不稳定测试假设。 - 修正 CADFS 比较模块 import 路径，补充重建报告、批量重建脚本、目标文档和 README。 - 新增并扩展 engine、lowering、parser、selector binding、reports、integration 和 Onshape pipeline 回归测试，覆盖代表性 CADFS 特征链及运行时兼容性。
196 lines
14 KiB
Markdown
196 lines
14 KiB
Markdown
# CADFS 全量重建目标与验收计划
|
||
|
||
## 目标
|
||
|
||
将 CADFS FeatureScript 历史稳定转换为 CDSL，由 engine 重建 STEP，并与
|
||
原始 STEP 做严格几何比较。近期交付门槛是 17 个代表性样本全部严格通过；
|
||
最终交付门槛是当前 CADFS 全量语料中的每个可比较模型都完成同一条链路。
|
||
|
||
这里的“重建成功”仅指 `comparison.json` 的 `strict.passed == true`，不是
|
||
仅生成 `rebuild.step`，也不是只通过 RP 宽松阈值。
|
||
|
||
本文件记录目标、阶段门槛和验收口径。实现进度、能力边界和每次代码变更
|
||
后的证据记录在本地台账
|
||
`ENGINE_CAPABILITY_GAPS_PROGRESS.local.md`；两者必须保持一致。
|
||
|
||
## 当前基线
|
||
|
||
- 全量输出快照：9,347 个 CADFS 样本，见 `output/summary.json`。产品目标可
|
||
称为“一万条全量数据”，但验收时必须以本次扫描得到的实际样本总数为分母，
|
||
不能将 10,000 写成未验证的固定数量。
|
||
- 代表性回归池：17 个样本，见 `regression/manifest.json`。它覆盖当前观察到的
|
||
FeatureScript 操作、草图实体、已 lower 的 engine atomic 和未支持能力变体。
|
||
- 本地能力台账记录该池已有 `17/17 rebuilt` 的可执行 STEP 证据；当前 checked-in
|
||
manifest 保留的是历史选择时的 `3` 个 engine baseline / `17` 个 conversion
|
||
样本分类。因此，开始严格回归前必须重新生成并核对 manifest，不能将旧分类
|
||
当作当前通过结果。
|
||
- 当前全量报告中仍有 `rebuild_failed`、`rebuild_timeout`、`comparison_timeout` 和
|
||
`rebuilt_rejected`。这些都是待消除的问题，不可因保留了可执行 STEP 而视为完成。
|
||
|
||
## 验收口径
|
||
|
||
一个样本必须同时具备以下工件和结果，才计入严格重建成功：
|
||
|
||
1. `candidate.cdsl.json` 通过 schema 和语义验证，且没有以跳过后续几何换取成功。
|
||
2. `bound.cdsl.json`（若样本需要 selector 绑定）可复现产生，绑定证据可追溯到
|
||
feature、owner 和 topology snapshot。
|
||
3. `rebuild.step` 由完整的 CDSL feature history 生成；中间失败不能被最终可执行
|
||
前缀掩盖。
|
||
4. `comparison.json` 的 `decision` 为 `strict_pass`，并同时满足：
|
||
`surface_max <= 0.01 mm`、`surface_p99 <= 0.01 mm`、
|
||
`bbox_max_delta <= 0.01 mm`、体积和表面积相对误差均不超过 `1e-5`，以及实体数相等。
|
||
5. `status.json`、转换诊断、重建报告和比较报告保存于该样本目录；可执行但不相似
|
||
的模型必须保留，而不能在失败时删除。
|
||
|
||
`approximate_pass` 仅用于定位接近结果，不能通过本计划的 17 样本或全量目标。
|
||
缺失原始 STEP、源数据损坏或外部资产不可取得时，必须单独列为 source exception，
|
||
附原始证据；不得伪装成 engine 或 converter 已完成。
|
||
|
||
## 第一阶段：17 个代表样本
|
||
|
||
阶段完成条件：下面 17 个样本全部以 `--compare-mode strict` 重新执行并严格通过，
|
||
同时 manifest 的覆盖标签与当前输出一致。每次修复只针对实际失败根因扩展能力；
|
||
一个样本可能由多个能力共同阻塞。
|
||
|
||
| 样本 | 代表的操作或几何 | 当前需要验证或补齐的门槛 |
|
||
| --- | --- | --- |
|
||
| `00002243` | extrude、hole、chamfer | 孔宿主、端盖/边 selector、倒角参数与稳定选边。 |
|
||
| `00035682` | cPlane、extrude、revolve | `line_point` 基准面及其后续特征引用。 |
|
||
| `00054089` | extrude、revolve | `swept_edge` selector。 |
|
||
| `00111611` | extrude、revolve、fillet、chamfer | 复杂草图、回转轴、圆角和倒角的拓扑稳定性。 |
|
||
| `00129362` | cPlane、extrude、revolve | 可复用基准面 frame、回转 add/cut。 |
|
||
| `00159804` | circularPattern、through-all add | 环形阵列 replay、`line_angle` 和 through-all 加料。 |
|
||
| `00192744` | circularPattern、extrude | 已执行 `curve_point` 附着 frame、`up_to_next` 和 pattern copy deletion；仍缺多 body transform 与 source/STEP 一致性证据。 |
|
||
| `00212904` | shell、two-sided cut | shell、`three_point`、双向切除终止条件。 |
|
||
| `00287955` | loft、cPlane、revolve | 多 profile loft、`cap_edge`、`mid_plane`。 |
|
||
| `00423838` | circularPattern、extrude | `up_to_vertex` 与 two-sided cut 的非盲终止。 |
|
||
| `00542223` | shell、sweep、circularPattern | sweep path/profile、shell、`plane_point`、through-all cut。 |
|
||
| `00612529` | loft、mirror、cPlane | loft profile 对齐、镜像 replay、`mid_cap_edge`。 |
|
||
| `00694309` | extrude、fillet | `up_to_body` 和 feature 后继 selector。 |
|
||
| `00710855` | extrude、chamfer | 曲面拉伸与 surface/solid 混合拓扑。 |
|
||
| `00789939` | shell、extrude、fillet | shell、`offset_face`、`swept_face`。 |
|
||
| `00835610` | booleanBodies、revolve | 多 body boolean、`cap_face`、`intersect`、revolve surface。 |
|
||
| `00925274` | mirror、through-all cut | 镜像 replay、`up_to_surface`、`line_angle`。 |
|
||
|
||
推荐的完整验收命令：
|
||
|
||
```bash
|
||
PYTHONPATH=backend:. python -m cadfs_to_cdsl regression \
|
||
--tier all --stage pipeline --compare-mode strict --timeout-seconds 60
|
||
```
|
||
|
||
命令结束后应检查 17 个 `comparison.json`，而不是只检查 CLI 的进程退出码。
|
||
|
||
## 能力完成目标
|
||
|
||
能力的完成定义为同一能力的 CADFS lowering、CDSL contract、runtime/adapter、
|
||
selector 或 body 语义（需要时）、严格比较回归均具备。仅实现其中一层时只能记为
|
||
“部分完成”。优先级依据全量影响数和 17 样本依赖关系确定。
|
||
|
||
### P0：使特征历史成为完整实体
|
||
|
||
1. 复杂草图与 B-spline：稳定的多 wire、孔洞、闭合排序、退化诊断；开口 wire
|
||
可作为 sweep path，闭合 wire 可作为实体 profile。
|
||
2. 显式多 body 结果模型：body ID、选择集、复制、保留和生命周期；这是
|
||
`booleanBodies`、transform、pattern copy 的前置条件。
|
||
3. sweep、完整 loft、shell 和 booleanBodies：包含实体/曲面模式、导轨或 profile
|
||
对齐、移除面、结果 body 和可诊断的失败边界。
|
||
4. circularPattern 与 mirror：source replay、完整轴/面引用和嵌套 pattern；实例必须
|
||
是独立的几何结果，不能依赖隐式全局主体。
|
||
|
||
### P0：补齐拉伸终止语义
|
||
|
||
按全量影响数优先完成复杂 `extrude`，以及 through-all、two-sided、up-to-surface、
|
||
up-to-next、up-to-body、up-to-vertex 和 surface/mixed 模式。终止距离必须由目标 body
|
||
的真实相交结果或明确的源参考决定，不能用固定默认值近似。
|
||
|
||
### P1：让后续特征引用稳定
|
||
|
||
1. 记录内核拓扑 delta：`preserved`、`modified`、`generated`、`deleted` 和 feature
|
||
输出角色；不唯一的后继必须诊断为歧义。
|
||
2. 补齐 CAP、SWEPT、OFFSET、INTERSECT、MID_CAP 的 face/edge selector，并保留
|
||
owner 与几何签名。
|
||
3. 完成 line-angle、plane-point、three-point、mid-plane、line-point、curve-point
|
||
基准面，覆盖曲面和曲线切线引用及退化输入。
|
||
4. 完成 fillet、chamfer、hole、revolve/revolve_surface 的参数变体、可行性预检查
|
||
和拓扑后继处理。
|
||
|
||
### P2：清除全量语料的剩余 FeatureScript 缺口
|
||
|
||
实现 draft、thicken、split、moveFace、deleteFace、replaceFace、完整 transform，
|
||
以及 derive/import 的受控外部资产协议。任何依赖外部模型的操作只有在资产身份、
|
||
输入、版本和失败方式均可复现时，才能计入全量成功。
|
||
|
||
## 实现参考与边界
|
||
|
||
`/Users/lk/Downloads/SimpleCADAPI-master 4` 可作为 OCP 调用和拓扑建模的实现
|
||
参考，而不是可直接替换的 engine：
|
||
|
||
- sweep、loft、shell 分别可参考 `BRepOffsetAPI_MakePipeShell`、
|
||
`BRepOffsetAPI_ThruSections` 和 shell builder 的调用边界、失败处理和 shape
|
||
输出方式。
|
||
- boolean、fillet、chamfer 应参考其内核 `Modified`、`Generated`、`IsDeleted`
|
||
的拓扑 delta 采集方式，落实本计划要求的 feature 输出角色和 selector 后继证据。
|
||
- transform 和 pattern 应作用于明确的 shape/body 输入，并保留每个实例的独立结果。
|
||
|
||
SimpleCADAPI 强制将 boolean 结果收敛为单个 `Solid`，不满足 CADFS 的多 body、
|
||
保留工具体、复制和 body 生命周期语义。实现时只能借鉴 OCP 调用与拓扑证据模型，
|
||
必须保留本项目的 CDSL schema、runtime adapter 和显式 body-result contract。
|
||
|
||
## Source Exception Evidence
|
||
|
||
严格重建失败必须先按下表归类。只有“已验证 source exception”能够从全量
|
||
成功分母移除；候选项仍是未完成样本，必须保留 source、CDSL、STEP 和比较工件。
|
||
|
||
| 分类 | 样本 | 当前证据 | 处理要求 |
|
||
| --- | --- | --- | --- |
|
||
| 已验证 source exception | 无 | 当前 17 样本没有已经证明可豁免的 source exception。 | 不得从验收分母移除。 |
|
||
| engine / converter 缺陷（受限路径已修复） | `00710855` | F5 的 CADFS IMPRINT cut 已由错误圆盘改为 `r=19..25.5 mm` 环。对于 F10，runtime 仅在显式同轴 surface shell 在 selected plane 提供内边界证据时，才以源 `width=10 mm` 构造受限圆锥倒角；完整 history 已可执行。 | 将该受限模式扩展为一般 surface/solid split、topology delta 和后继 selector；不得缩小源倒角宽度。 |
|
||
| source / STEP 精度候选 | `00710855` | 完整 history 的 surface 最大差为 `0.0035 mm`，面积、bbox 与实体数满足 strict；但 source F8 E14 是 `r=22 mm`，gold STEP 对应圆柱是 `r=21.9965 mm`，导致体积相对误差 `7.998e-5` 超过 strict。 | 保存 source literal 与 STEP 测量证据；未获得 source export 版本证明前不得回填 gold 半径，也不得从验收分母移除。 |
|
||
| source / STEP 差异候选 | `00035682` | FeatureScript 圆柱/孔径 literal 的精度低于原 STEP 的测量值；现有拓扑类型和数量相同，但严格体积/面积不一致。 | 保存原始精度证据；复核 source 导出版本后才能定为 exception。 |
|
||
| source / STEP 差异候选 | `00192744` | F3/F5 的 frame 与 `UP_TO_NEXT` 已修复，F7/F12 的 `COPY(BODY)` 删除也已 replay，完整 history 可执行且 bbox 对齐；但 source F15 将 F1 移动约 `-10000 mm`，gold STEP 仍位于约 `y=[-500,500]`。按 source 缺省 `NEW` 保留 8 个实体，gold 只有 1 个，体积相对误差仍为 `1.001e-3`。 | 保持严格失败并完成通用 multi-body transform/body lifecycle；不以 gold STEP 反推、伪造 transform 参数或把 source `NEW` 改成 `ADD`。 |
|
||
| source / STEP 差异候选 | `00212904` | 原 STEP 出现 source FeatureScript history 未表达的正交 cut strip。 | 保留对比工件；除非 source 能提供缺失 feature，不得在 converter 伪造几何。 |
|
||
| source / STEP 精度候选 | `00835610` | 完整 history 可执行且 RP 通过，严格最大表面差约 `0.014 mm`；FeatureScript 值与 STEP 存在约 `0.014 mm` 的 literal 差异。 | 不能从 gold STEP 回填尺寸；继续标为严格失败，等待 source 版本证据。 |
|
||
|
||
## 全量完成门槛
|
||
|
||
在 17 样本严格通过后，按 capability family 对全量语料滚动运行，并按失败原因选择
|
||
新的最小代表样本。最终报告必须以扫描快照中的全部样本为分母，同时满足：
|
||
|
||
1. 每个有效源样本生成语义有效、可执行的 CDSL；`parse_failed`、
|
||
`unsupported_operation`、`unsupported_engine_capability` 和因 converter 丢失
|
||
feature 而导致的 `converted_partial` 均为零。
|
||
2. 每个拥有原始 STEP 的样本生成完整 `rebuild.step`；`rebuild_failed` 和
|
||
`rebuild_timeout` 均为零。
|
||
3. 每个可比较样本严格通过比较；`comparison_timeout`、`rebuilt_rejected` 和仅
|
||
`rebuilt_approximate` 均不计入完成。
|
||
4. 任何合法 source exception 都有单独清单、原始证据和可复现原因；它不进入成功
|
||
分母，也不得吞并为“未分类失败”。
|
||
5. 生成全量 capability-gap、比较汇总和逐样本证据，确保任一退化都可定位到
|
||
converter、engine、源数据或比较基础设施。
|
||
|
||
17 个样本覆盖了已观察到的特征类别，但不是全量正确性的数学证明。只有滚动的
|
||
全量比较通过，才能声称完成全量重建。
|
||
|
||
## 每次修复的执行规则
|
||
|
||
1. 先重跑发生退化的代表样本，并读取 `history.json`、`candidate.cdsl.json`、
|
||
`bound.cdsl.json`、`rebuild.json` 和 `comparison.json`。
|
||
2. 将问题归类为：CADFS parser/lowering 丢失或误译、CDSL schema/contract 无表达、
|
||
engine/adapter 几何能力不足、selector/body 引用错误、源数据异常，或比较基础设施
|
||
问题。证据不足时不得猜测分类。
|
||
3. 只在责任层修复：转换问题修改 CADFS lowering；执行问题扩展 engine；两者都涉及
|
||
时分开提交证据和测试。保留最新可执行 STEP/GLB 和失败诊断。
|
||
4. 每项代码改动至少重跑受影响样本、17 样本严格回归和相应单元测试；能力状态与
|
||
证据同步到本地能力台账。全量统计变化后重新生成 `regression/manifest.json`。
|
||
5. 不以关闭诊断、跳过 feature、降低 strict 阈值或用未说明的默认尺寸换取通过。
|
||
|
||
## 阶段交付物
|
||
|
||
| 阶段 | 必须交付 | 通过条件 |
|
||
| --- | --- | --- |
|
||
| R0：证据稳定 | 刷新的 regression manifest、17 份完整工件 | 每个样本可重复运行并可定位当前失败。 |
|
||
| R1：代表样本 | 17 个严格比较报告、能力台账更新 | `17/17 strict_pass`。 |
|
||
| R2：能力扩展 | 按能力 family 的 converter/engine/selector 实现及回归 | 对应缺口不再造成该 family 的失败。 |
|
||
| R3：全量验证 | 全量 CDSL、STEP、比较结果和汇总报告 | 满足“全量完成门槛”的五项条件。 |
|