cdsl-cad/cadfs_to_cdsl/CADFS_RECONSTRUCTION_TARGET.md

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。

推荐的完整验收命令：

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、比较结果和汇总报告	满足“全量完成门槛”的五项条件。