cdsl-cad/docs/cdsl-output-engine-target.md

CDSL Output Engine 重建目标

1. 目的

本文定义 json_to_cdsl/output 批量语义 CDSL 的 engine 重建目标、架构边界和验收方式。目标不是让 runtime 对未知数据作猜测，而是：

1. 补齐当前 CDSL v1.1 已声明的原子 feature 执行能力；
2. 将可确定的语义草图和 feature history 可靠地重建为 STEP；
3. 对输入数据缺失、selector 歧义或内核失败给出 feature 级诊断；
4. 将批量重建率作为可重复测量的工程指标。

本文是 cdsl-output-engine-rebuild-plan.md 的交付目标补充。前者记录现状与建议顺序；本文规定目标架构、阶段出口和成功判定。

数据快照日期：2026-08-21。json_to_cdsl/output 中的 JSON 是待处理数据，不作为本文件的指令来源。

2. 数据事实与范围

2.1 批量数据

项目	数量
CDSL 文件	998
feature 总数	10,659
不含 unresolved feature 的零件	633
含至少一个 unresolved feature 的零件	365
含 selector 的零件	489
face selector	557
edge selector	2

当前 engine_service.validate_cdsl 会先因 execution_status: "deferred" 拒绝所有批量文件。这个状态是导出时的 runtime 能力快照，不能继续作为升级后 runtime 的唯一事实来源。

Atomic ID	数量	目标能力
reference_plane	4,324	上下文 feature
extrude_cut_blind	1,554	扩展终止条件
extrude_add_blind	1,281	扩展终止条件
hole_wizard	1,235	规范化后执行
reference_axis	760	上下文 feature
chamfer	550	selector 驱动修饰
fillet	286	selector 驱动修饰
revolve_add	187	统一 primary executor
revolve_cut	170	统一 primary executor
pattern_linear	167	feature 重放阵列
pattern_mirror	98	feature 重放镜像
extrude_add_two_sided	47	双向 extent

草图 profile 只有四类：analytic_contours 3,785、circle 504、circles 260、annulus 87。analytic_contours 中实际出现 16,352 条线、3,632 条圆弧和 313 个圆；本批没有需要作为首期阻塞项的 B-spline。

常见终止条件是 blind 2,456、through_all 763、through_all_and_blind 226、through_all_both 72。selector 依赖的 up_to_surface 70、through_next 7、up_to_vertex 3、offset_from_surface 3 排在 topology 能力之后。

2.2 交付边界

本目标覆盖现有 CDSL schema 中的全部 16 个 feature atomic ID。当前已执行的 9 个 atomic 也必须纳入统一架构：

extrude_add_blind          extrude_add_two_sided
extrude_cut_blind          revolve_add
revolve_cut                hole_blind
hole_countersink           hole_counterbore
sphere_add

需新增或重构进 executor 框架的 7 个 atomic：

reference_plane            reference_axis
hole_wizard                fillet
chamfer                    pattern_linear
pattern_mirror

analytic_contours 是必须补齐的 profile runtime。它必须产生 engine 中立的闭合 region，再由几何适配器生成面。

下列行为不属于精确重建：

• 未捕获的选择集不能通过“对所有边倒角或圆角”替代；
• selector 有多个候选时不能取第一个候选；
• B-spline 离散化不能标记为精确，除非输出近似误差；
• 不允许重新启用 compiler_context 或 legacy translator 作为 CDSL-only 成功回退。

3. 成功定义

每份批量报告必须记录下列独立状态：

semantic_valid       CDSL 符合 schema、ID 和依赖顺序
runtime_eligible     所有 feature 当前可执行，且输入完整、无歧义
compiled             已形成可执行 feature plan
built                已成功输出 STEP
geometry_verified    与 source truth 的数值几何比对通过
topology_observed    面、边、顶点数量已记录，仅作诊断

built 不是 geometry_verified 的同义词。默认 strict 模式只有所有 feature 均 runtime_eligible 时才可标记为成功重建；调试模式可以输出部分 STEP，但必须标记为 partial。

数值验证至少比较 bounding box、volume、surface area 和 solid count。门槛应配置化，初始建议：bounding box 每个坐标绝对误差不超过 0.01 mm，volume 与 area 相对误差不超过 0.1%，solid count 必须相同。拓扑数量因 STEP/OCC 表达差异不是首期硬门槛。

4. 目标架构

目标 pipeline 的依赖方向如下：

Semantic CDSL
    -> Semantic Validator
    -> Capability Analyzer
    -> Feature Planner
    -> Execution Session -> Atomic Executor Registry -> Geometry Adapter -> build123d / OCC
                            <-> Topology and Context Registry
    -> STEP + Build Report

建议在 backend/engine/cdsl_engine 内按以下职责拆分。文件名可调整，但依赖方向不得反转。

层	责任	不应承担的责任
semantic_validation	schema、ID、依赖顺序与自包含数据检查	判断当前内核是否支持 feature
capabilities	根据 registry、参数和 selector 条件计算可执行性	生成或修改 CDSL
sketch	profile、闭环、outer/inner 分类，输出 SketchRegion	直接修改实体
planning	feature DAG、归一化、执行顺序和 plan diagnostics	复制 build123d 对象或做布尔运算
runtime	session、executor registry、结果与错误边界	解析原始 JSON 细节
topology	context、body、face、edge 注册与 selector 解析	私自补全缺失选择集
adapters/build123d	region 到 B-rep、布尔、修饰、STEP 导出	读取 CDSL schema 或决定依赖
batch_rebuild	批量调度、报告、truth 对比、回归基线	实现几何算法

4.1 核心接口

每个 feature 必须经由同一类接口运行：

class AtomicExecutor(Protocol):
    atomic_id: str

    def preflight(self, node: FeaturePlanNode,
                  session: ExecutionSession) -> CapabilityResult: ...
    def execute(self, node: FeaturePlanNode,
                session: ExecutionSession) -> FeatureResult: ...

class GeometryAdapter(Protocol):
    def make_regions(self, regions: list[SketchRegion]) -> GeometryResult: ...
    def extrude(self, body, regions, extent: ExtentSpec, mode: BooleanMode): ...
    def revolve(self, body, regions, axis: AxisSpec,
                angle_deg: float, mode: BooleanMode): ...
    def hole_tool(self, spec: HoleSpec, starts, inward,
                  through_depth_mm: float): ...
    def apply_fillet(self, body, edges, radius_mm: float): ...
    def apply_chamfer(self, body, targets, spec: ChamferSpec): ...
    def body_geometry(self, body) -> BodyGeometry: ...
    def export(self, body, path: str): ...

FeatureResult 至少包含 feature_id、产生或修改的 body、context object、拓扑快照、可回放的执行定义和 feature 级诊断。任何 executor 都不得通过全局变量或 BuildPart 隐式上下文查找前序结果。

HoleSpec 是 runtime-neutral 的孔定义：包含孔径、深度、终止条件、位置以及可选 countersink/counterbore 尺寸，但不包含 OCC 对象或 host-face 推断。runtime 负责严格解析 host frame 和坐标，adapter 只将已解析的 HoleSpec 构造成切削工具。

runtime 对 B-rep 实体保持 opaque：包围盒、体积、STEP 导出及所有内核向量转换都只能经 adapter 返回；runtime 不得 import 或读取 build123d/OCC 对象属性。

4.2 现有代码的迁移约束

现有 sketch_solver.py -> llm_compiler.py -> llm_engine.py 流程可以逐步迁移，但必须保持单一路径：

• sketch_solver.py 输出中立 region/curve 数据，不能让 profile generator 拥有实体执行逻辑；
• llm_compiler.py 只构建 feature plan。当前 pattern_linear 的坐标偏移克隆逻辑必须迁出 compiler，避免 pattern、selector 和 host face 语义被扁平化；
• llm_engine.py 的大分支改为 executor registry；build123d import 只保留在 adapter 层；
• engine_service.validate_cdsl 只在 atomic contract 声明 requires_sketch: true 时强制 sketch_id。reference、pattern、dress-up 与 Hole Wizard 都是合法的非草图 feature；
• profile_schema.json、cdsl_schema.json、executor registry 和测试必须由同一 capability 声明校验，避免维护多个手写 supported set。

4.3 execution_status 的兼容策略

保留 CDSL 中的 execution_status，用于说明导出时的能力快照；不再仅因其为 deferred 而拒绝升级后的 runtime。实际执行前由 CapabilityAnalyzer 为每个 feature 产生：

declared_status       CDSL 中的 execution_status
resolved_status       executable | blocked | unsupported
required_capabilities 原子、profile、selector、extent 能力
blockers              精确的缺参、歧义或内核前置条件

旧输出因此可以在 engine 升级后直接重跑；converter 重跑仍应更新导出状态，但不是重建前置条件。

5. 原子能力完成合同

5.1 Reference geometry

reference_plane 和 reference_axis 不生成实体，但必须作为正式 FeatureResult 写入 context registry，用于后续 workplane、revolve axis、mirror plane、pattern direction 和 hole host frame。

要求：

• 使用 canonical PlaneSpec 与 AxisSpec；
• 校验零长度向量，正交化并记录修正后的坐标系；
• 支持由显式参数、前序 reference、feature 或 sketch 推导；
• 无法恢复的朝向缺失返回 blocked: missing_reference_orientation，不得默认 XY；
• context feature 不修改 body，但可作为后续 feature 的依赖节点。

5.2 Analytic contour runtime

首期支持 line、arc、circle。固定流程为：二维 segment 归一化、端点容差拼接、闭环验证、workplane 映射、outer/inner 分类、生成 SketchRegion。一个 region 可以有一个 outer loop 和多个 hole loop。

必须诊断端点反转、退化边、自交、开放 loop、非共面输入，以及无法分类的 unknown contour。circle 是独立 loop，不能用零长度线模拟；嵌套环按奇偶包含关系分类。

对于四段等半径、90 度圆角组成的闭环，若导出逐段 clockwise 标记互相矛盾，runtime 可以依据闭环有向面积统一其短圆角方向；这是一种可证明的 rounded-rectangle 归一化。两段半圆或任意长圆弧无法仅由该规则恢复 sweep intent，必须保留原始证据或在 truth 验证中报告不匹配，不能根据目标 STEP 猜测方向。

B-spline 是后续扩展。采用采样近似时必须声明 chord tolerance 和最大偏差，且 geometry_verified 需使用对应容差策略。

5.3 Extrude 与 revolve

现有 add/cut/revolve atomic 保持原 ID，内部统一归一化为 BooleanMode、ExtentSpec 和 AxisSpec。执行器先生成 region 面，再调用 adapter；不得根据“草图中有圆”改变 feature 语义。

层次	终止条件	规则
A	blind、mid_plane、through_all、through_all_both、through_all_and_blind	使用当前 body 的精确包围范围与 margin 计算 extent；双向值保持独立
B	up_to_surface、up_to_vertex、offset_from_surface、through_next、up_to_body	先通过 selector resolver 得到唯一目标，再由 adapter 做射线或相交查询；up_to_body 使用 active B-rep 的 body record，不允许引用失效快照

extrude_add_two_sided 必须保留正反两侧的距离与终止条件，不能简化为单个对称距离；每一侧都要独立解析 blind、through 或 selector-dependent end condition。revolve axis 可以来自显式 AxisSpec 或 owner-qualified 的 reference_axis selector；无 owner 的 source stable ID 不能被当作 OCC 轴。axis 与 profile 的退化相交必须在 preflight 阶段诊断。

5.4 Hole Wizard

hole_wizard 是独立 atomic，不在 compiler 中改写成匿名多个 hole step。执行器先解析为中立 HoleSpec，再选择 blind/countersink/counterbore/tapped 子型并调用 hole adapter。plan 和报告保留原 feature_id 与 atomic_id。

要求：

• 由 host face selector 或明确 workplane 得到唯一孔位 frame；
• 支持 blind、through_all、through_all_both 与 countersink/counterbore；
• 将 SolidWorks 位置坐标转换为 host frame，不能将局部坐标当世界坐标；
• thread、非标准钻尖或不支持孔型返回 unsupported_hole_subtype，不能静默退化为普通圆柱孔；
• 源 STEP 的 stable_id 只是线索，host face 必须在重建中间体上重新解析。

5.5 Selector 与 topology registry

selector 是 dress-up、Hole Wizard、pattern 和 selector-dependent extent 的共同前置能力。每完成一个 feature，registry 记录：

feature_id, parent feature ids, body id, context objects,
generated/owned faces and edges, bbox, center, area, normal,
surface or curve type, adjacency signature, local feature signature

每次实体变更都产生新的 active B-rep snapshot，旧 OCC 对象不能继续用于 selector。若且唯若新旧拓扑项存在唯一、完整且几何等价的签名匹配（包括 bbox、中心、面积/长度、朝向与邻接签名），才可将其 durable owner provenance 继承到新对象；分裂、合并、修改或多候选匹配不得继承 owner。这样 owner_feature_id 仍可约束当前实体上的有效对象，而不会把所有存活拓扑误标为最后一个变更 feature。

解析顺序固定为：owner_feature_id 限定候选集，显式 kind 限定面/边/轴，再以几何签名评分，最后应用置信度和唯一性阈值。0 个候选报 selector_not_found，多个同分候选报 selector_ambiguous。两种情况都不能继续 strict rebuild。

原始 stable_id 不能被当作 OCC 持久名称。解析器必须输出候选、评分和最终原因，而不是隐藏地选择拓扑对象。

5.6 Fillet 与 chamfer

实现顺序为：edge selector、face selector 展开到边、单距离 chamfer、双距离或角度 chamfer、tangent propagation。tangent propagation 只能从已解析 edge 出发，沿当前 B-rep 中共享顶点且切向连续的 edge chain 扩展，不能退化为全局边集合。每次 OCC 修饰后都重新扫描 registry，因为此前 B-rep 对象可能失效。

不得提供“没有 selector 时对全部边应用”的回退。当前 550 个 chamfer 与 286 个 fillet feature 均没有 selector；这不是仅新增 runtime 函数就能解决的问题。它们必须由 converter/exporter 提供选择集，或由针对 source truth 的独立 selector enrichment pass 产生唯一、可审计的 selector，才可进入严格重建池。

5.7 Feature-level pattern

pattern_linear 和 pattern_mirror 重放 source feature 的语义执行定义，不复制完整 body，也不在 compiler 中仅平移三维坐标。每个实例有独立 transform scope，并通过相同 atomic executor 在当前 body 上执行。

• linear pattern 支持一维和二维 direction/spacing/count，并保留 direction reverse；
• mirror pattern 使用 canonical plane，支持显式 plane 或 registry reference；
• source feature 必须已成功执行，且其 selector/reference 经 transform 后仍可唯一解析；显式 host_face.frame 与局部孔位是可直接变换的坐标 contract，未显式 frame 的 host selector、dress-up selector 和 B 层终止 selector 在具备完整 transform contract 前必须阻断；
• 无 source feature、不可变换 selector 或布尔失败时，整个 pattern 阻断并给出实例级错误。

6. 数据补全责任

engine 负责执行确定的 CDSL，不负责虚构 source intent。下列数据问题必须由 exporter/converter 或可审计 enrichment pass 解决：

数据缺口	当前数量	所需动作
Hole Wizard 缺少 semantic selections	761	捕获 host face、placement frame 和位置关联
缺 source sketch parent	153	记录草图 parent feature/reference plane
reference plane 朝向未捕获	21	导出 origin、normal、x direction 或稳定派生关系
hole 直径或深度缺失	3	捕获原始尺寸及单位
revolve 缺 selection 或 axis	2	捕获 revolve axis/reference
fillet 尺寸无效	1	导出有效 radius/distance
chamfer 缺 semantic selections	1	捕获 edge/face 选择集

部分 Hole Wizard 虽有 host_face，但其来自 source STEP 推断。enrichment pass 必须将其转换为可解析 selector contract，并在置信度不足时保留 unresolved。同一规则适用于 fillet/chamfer，不能为了提高覆盖率创造不稳定 ID。

7. 分阶段交付与覆盖目标

批量覆盖数字是静态“输入就绪池”，不是尚未实现内核下的通过率承诺。所有数字均要求无 unresolved、profile 限于本批四类、analytic_contours 仅含 line/arc/circle，且终止条件在当前阶段已支持。

阶段	交付物	阶段出口	静态就绪池
P0	batch_rebuild、基线 manifest、feature 级报告	998 个输入均有机器可读结果；可复现首个阻断 feature	998
P1	capability analyzer、execution session、reference plane/axis、校验修正	非草图 atomic 可规划；旧 deferred 不再是唯一阻断理由	-
P2	analytic_contours region resolver	line/arc/circle、洞与闭环测试通过	-
P3	unified extrude/revolve 与 A 层终止条件	基础实体池全部通过 runtime preflight，并以 truth 运行回归	266 current / 271 historical estimate
P4	topology/selector registry 与 Hole Wizard	有 position、唯一 host face 的孔可严格执行	309 current / 312 historical estimate
P5	fillet/chamfer 和 selector enrichment 闭环	只接受唯一 selector；所有缺 selector 输入明确阻断	取决于 enrichment
P6	linear/mirror feature replay	source feature、context、transform 和实例诊断完整	341 current / 343 historical estimate
P7	B 层终止条件、剩余数据补全和回归收敛	633 个无 unresolved 零件按实际 feature 组合进入全量目标池	633

P3 的 271、P4 的 312 与 P6 的 343 都是初始导出统计的历史估计。按当前 998 份 CDSL 的严格闭合-region contract 复算后，P3/P4/P6 静态池分别为 266/309/341：差额来自仅 reference history 或 consumed profile 无闭合 region，不能由 runtime 补齐。P3 的 266 件中另有 4 件缺 captured extent reference 或 revolve axis，因而当前 strict runtime-eligible 为 262；P4/P6 当前 strict runtime-eligible 分别为 277/290，主要阻断是 threaded Hole、缺 active body/reference 及不可变换的 selector。它们不是简单相加。

运行时以 phase_pools.select_static_phase_pool 固化 P3/P4/P6 输入定义：无 unresolved、仅该阶段允许的 atomic、至少一个 primary feature，且所有 consumed sketch 都是四种可解析 profile 的闭合 region。静态池不代表每个 feature 的 selector/reference 已完整捕获；当前缺 axis、extent reference 或 history 中无 active body 的文件必须在 strict preflight 报具体 blocker，不能被计入 runtime-eligible。

剩余 365 个带 unresolved 的零件不能仅靠补 engine atomic 达到严格重建。P7 的目标是把每个零件归入“可通过数据补全解锁”或“当前证据不足”，而不是报告模糊失败。

8. 批量基准与 CI 门槛

新增单一入口，例如 backend/engine/cdsl_engine/batch_rebuild.py，接收 CDSL 目录、truth 目录和输出目录。每次运行至少产生：

manifest.json
parts/<part_id>.report.json
parts/<part_id>.step
summary-by-atomic.json
summary-by-blocker.json

每份报告包含：

part_id, cdsl_path, semantic_valid, runtime_eligible, compiled, built,
geometry_verified, topology_observed, first_blocker, feature_results,
unsupported_atomic_ids, unsupported_profile_types, unresolved_input,
selector_resolution, numeric_comparison, timings

报告还必须输出稳定的 failure_category：input_incomplete、selector_resolution、unsupported_capability、occ_execution_failure、geometry_mismatch 或 coordinate_frame_mismatch_candidate；geometry_verified 是唯一成功类别。未请求 --build 但已通过预检的报告标为 runtime_eligible_not_built，它是非终态，不是失败或 verified。该分类只归纳已有证据，不能将构建完成或坐标框候选计为 verified。

numeric_comparison 必须保留严格的 passed 判定，并把体积、面积、实体数及无序包围盒跨度均吻合、但绝对坐标框不吻合的情况标为 coordinate_frame_mismatch_candidate。该标记仅帮助定位 workplane/export frame 数据问题，不能替代 geometry_verified。

CI 分三层运行：

1. 单元与 contract 测试：每个 atomic executor、profile resolver、selector 歧义、extent 计算与 capability/schema 同步；
2. 小型集成 fixture：reference -> sketch -> primary feature -> dress-up/pattern 跨 feature 路径；
3. 批量回归：保存按零件和 atomic 分组的基线，禁止已验证零件退化，新增通过必须附带数值比对。

每次新增 atomic 或终止条件，必须同时更新 schema contract、capability registry、executor、诊断、单元测试和至少一个批量 fixture。不得只把名称加入 SUPPORTED_ATOMIC_IDS。

8.1 当前 P3 严格基线

2026-08-23 已按当前静态 P3 pool 运行以下 CDSL-only 基线；每个零件在独立进程中构建，单件 timeout 为 15 秒：

PYTHONPATH=backend/engine python -m cdsl_engine.batch_rebuild \
  json_to_cdsl/output --out /tmp/cdsl-p3-current-baseline \
  --phase p3 --build --build-timeout 15

最终结果为 266/266 已完成、262 份 strict runtime eligible、253 份 built、57 份 geometry verified。其余终态分类为 147 份 geometry_mismatch、49 份 coordinate_frame_mismatch_candidate、6 份 input_incomplete、5 份 occ_execution_failure、2 份 selector_resolution。这是一份验收基线而非成功率承诺：坐标框候选和已构建 STEP 均没有并入 verified。

该命令和输出目录结构是可恢复的；CI 应将经过审查的报告摘要保存在持久化工件中，而不依赖本机 /tmp 的 STEP 临时文件。

同日使用相同的 CDSL-only、每件 15 秒隔离构建策略完成 P4 池：309/309 已完成、277 份 strict runtime eligible、258 份 built、59 份 geometry verified。其余终态为 150 份 geometry_mismatch、49 份 coordinate_frame_mismatch_candidate、8 份 input_incomplete、5 份 occ_execution_failure、12 份 selector_resolution、26 份 unsupported_capability。P4 的 5 个 OCC 失败均已出现于 P3 基础主体能力池，未发现 Hole Wizard 新增的 OCC 失败。

P6 池也已使用同一策略完成：341/341 已完成、290 份 strict runtime eligible、268 份 built、60 份 geometry verified。其余终态为 159 份 geometry_mismatch、49 份 coordinate_frame_mismatch_candidate、9 份 input_incomplete、6 份 occ_execution_failure、14 份 selector_resolution、44 份 unsupported_capability。其中嵌套 pattern source 已按可回放 feature definition 递归执行；不能产生实体的 context source 会在 capability preflight 以 unsupported_pattern_source 阻断，不会再被归为 OCC 执行失败。

P7 的全量 capability 审计也已完成：998/998 份 CDSL 均有 machine-readable report，全部 semantic valid；290 份 strict runtime eligible（未请求 --build，因此分类为 runtime_eligible_not_built）、612 份 input_incomplete、96 份 unsupported_capability。这证明所有当前输入均被审计和分类，但不将 preflight 通过等同于 STEP 构建或 geometry verified。

9. 完成判定

本目标完成需要同时满足：

1. schema 已声明的 16 个 feature atomic 都有 executor、preflight contract 和 feature 级诊断；
2. analytic_contours 的 line/arc/circle 可构成带洞 region，并由统一 adapter 执行；
3. 266 个当前基础静态就绪零件均已由 phase-pool 回归审计；其中 262 个在现有输入下通过 strict runtime preflight，剩余 4 个以缺 axis/reference 的 feature-level blocker 报告；当前 CDSL-only P3 基线为 253 built、57 geometry verified，且所有非 verified 结果已有严格终态分类；
4. Hole、dress-up、pattern 与 selector-dependent extent 不再依赖 compiler 内特例或全局 build123d 状态；
5. 每个无法严格重建的零件都能区分为输入缺失、selector 歧义、未支持能力或 OCC 执行失败；
6. 批量报告和 CI 基线持续追踪 998 个输入，且 CDSL-only 成功路径不调用 legacy translator。

这样，engine 的扩展单位是可独立测试、可替换内核、可追溯失败原因的原子能力，而不是为某一批零件增加临时分支。