cdsl-cad/AGENTS.md

CAD Agent 运行原则

首要目标

产品的首要目标是稳定、可执行的 CAD 生成流程。任何已经获得可执行检查点的任务，系统都必须发布当前最完整、最可用的 CAD 模型。严格满足全部需求是期望目标，但绝不能因此进入无限修复循环，也不能丢弃本来可用的模型。

必须将以下两类结果严格区分：

• 执行可靠性： 工作流只接收有效协议数据，只调用引擎支持的操作，保留有效工作；只要存在可执行模型，就必须以最佳可用结果终止。
• 需求符合度： 最终模型可能满足全部、部分或不满足用户要求。未满足项必须作为警告和证据报告，不能成为销毁、隐藏可用模型的理由。

职责边界

• 服务端负责校验输出格式、schema、有限数值、操作可用性、selector/reference 有效性、Runtime 安全、持久化和状态转换。
• 服务端不得判断 LLM 是否“正确理解”了用户的设计语义。不得引入基于语义分歧而阻止建模的 reviewer 循环。
• 可以使用工程默认值补全常见但描述不足的零件，但未指定的值不得变成虚构的、严格的确定性验收尺寸。例如，仅因为 verifier 需要数值，不能把未指定的孔径编译成硬性的 1 mm claim。
• 不要求 LLM 输出内部运行时 ID，例如 task、revision、action、candidate、requirement、claim、evidence、source ID。所有这些值由服务端从当前状态生成和绑定。
• LLM 的规划、坐标、宿主面、操作选择或几何策略错误，通常属于模型质量问题，不是程序失败。必须保留诊断，并按下述恢复规则继续。
• schema 无效、引擎不支持的操作、非法状态转换、provider 协议不兼容、持久化失败或 Runtime 崩溃，属于程序、协议或服务问题，必须准确报告。

结果与用户沟通

• 始终保留并暴露最新可执行 STEP、GLB 和渲染工件。
• 完成结果必须区分：已满足目标、未解决目标、因依赖跳过的操作、Runtime/协议故障和 LLM 规划局限。
• 不得把未满足需求声称为已通过；同样不得因仍有未满足需求而隐藏可用模型。
• 需求文档和完成文档是面向用户的工程工件。需求文档可以用已接受的 CAD 默认规则完善描述不足的提示词；完成结果必须描述生成模型实际达成了什么。

改动评审指引

修改本系统时，优先保证执行确定性、部分结果可持久化、失败可诊断，以及终止行为有边界。避免加入语义审查关卡、要求复制 ID 的协议，或会在没有改善可执行模型的情况下无限消耗调用的重试机制。

CADFS 全量能力开发

CADFS 到 CDSL 到 STEP 的工作是在实现通用绘图引擎和通用 converter，不是为回归样本 编写修复脚本。能力实现必须以 FeatureScript 语义、显式 CDSL contract、body 生命周期和内核拓扑为边界，并对同类输入普遍成立。

• 禁止按 sample_id、路径、特定 feature ID、特定坐标、尺寸或 gold STEP 测量值分支； 禁止从原 STEP 回填 FeatureScript 未提供的参数，或为某模型硬编码 selector、profile、 偏移量、布尔策略和默认尺寸。
• 不得将不支持或不唯一的语义伪装成盲拉伸、当前 body、默认 union、任意相近拓扑元素 或静默跳过。必须保留最佳可执行前缀和 STEP，并给出稳定、可归因的能力诊断。
• 优先在 schema、semantic validation、runtime state、body graph 和 adapter 的 kernel-level topology delta 中实现能力；lowering 层只能表达源语义，不能承担样本化 的几何补丁。受限算法必须有通用、可验证的适用条件和拒绝路径。
• 一项能力只有在 lowering、CDSL contract、runtime/adapter、selector/body 语义、 单元测试和多个真实语料回归均具备后才能标为完成。操作名称覆盖不等于参数、拓扑来源、 几何类型或 body 生命周期覆盖。
• 严格比较用于诊断；工程验收遵循 rp.passed。不得降低 RP 阈值、关闭诊断、跳过 feature 或修改 source 参数来换取通过。source STEP 损坏或历史/STEP 精度不一致必须 作为有证据的 source exception 单独报告。
• 每次涉及 CADFS lowering、CDSL schema、runtime、adapter、selector 或测试的改动， 都必须同步更新 cadfs_to_cdsl/ENGINE_CAPABILITY_GAPS_PROGRESS.local.md；全量能力 计划以 cadfs_to_cdsl/CADFS_FULL_CAPABILITY_TARGET.md 为准。

CADFS 修改、文档与回归纪律

以下规则适用于每一次 CADFS converter、CDSL engine、selector、比较器、回归集或相关 测试的修改；它们是仓库规则，不依赖当前对话上下文。

修改前与实现方式

• 先用完整 FeatureScript history、candidate.cdsl.json、bound.cdsl.json、 diagnostics.json、rebuild.json、comparison.json 和 source/rebuild 工件定位失败层： converter/lowering、schema/semantic validation、selector binding、runtime/adapter、 source STEP/FeatureScript 不一致，或 comparison infrastructure。没有证据不得把失败 归因于任一层，也不得先改阈值或样本数据。
• 修改必须遵循目标模块已有的命名、分层、格式、注释语言和错误处理模式。优先扩展既有 contract、helper 和架构边界；没有明确收益时不得进行无关重构或引入平行实现。
• 先实现可复用的几何和拓扑语义，再将 CADFS source lower 到该 contract。任何只为单个 形状、数值、feature history 或截图成立的逻辑均视为缺陷，不得提交。
• 内核无法完成某个输入时，保留有界的失败和诊断；不得用较小的 dress-up 半径、替代孔型、 固定 extent、隐式 fuse 或未经来源证明的几何补偿伪造结果。
• 当前实现若被证明确实违反 source/contract 语义、无法表达全量已出现的通用输入、 受内核 API 的结构性限制，或反复需要样本化补丁，应停止继续叠加补丁并评估替代方案。 替换前必须具备可复现失败、根因证据、与成熟开源/官方 API 或最小原型的对照、对 CDSL/body/selector 兼容性的影响评估，以及受影响回归的迁移计划。
• 不得因单个样本、偶发 OCC 失败、一次性能波动或主观偏好轻易重写成熟路径。只有新方案 能以更少特例、更完整的通用语义和可验证的回归证据解决结构性问题时，才替换旧方案； 替换过程中保留旧工件和比较基线，分阶段迁移并记录回滚边界。

文档同步

• 每次实现、修复、扩展或确认某项 CADFS 能力后，必须在同一工作变更中更新 cadfs_to_cdsl/ENGINE_CAPABILITY_GAPS_PROGRESS.local.md：记录能力状态、通用语义、 已验证边界、未覆盖边界、受影响样本/能力矩阵和测试/比较证据；完成项必须勾选， 未完成项不得因单个样本通过而勾选。
• 上述 .local.md 是本地工作台账，必须保持在 .gitignore 中，绝不加入 Git 提交。 每次 CADFS 相关代码变更后都要同步，即使最终只得到失败诊断或发现 source exception。
• 新增能力、能力范围、验收口径、全量快照或实施优先级变化时，同步更新受版本控制的 cadfs_to_cdsl/CADFS_FULL_CAPABILITY_TARGET.md。它定义全量能力矩阵和路线； CADFS_RECONSTRUCTION_TARGET.md 记录核心回归与当前近期目标，两者不得冲突。
• 从全量 output 发现新的操作、参数变体、拓扑来源、body lifecycle 或 comparison failure 类型时，必须先登记为待办和能力矩阵条目，再选择多个真实样本回归；不得只加入一个 “代表模型”就宣称覆盖完成。
• 文档中的计数、样本 ID、状态和通过标准必须来自当前工件。必须区分 strict、RP 工程相似、 几何拒绝、可执行前缀、转换/运行时失败、比较超时和 source exception。

回归与可视证据

• 每次代码修改至少运行受影响的原子/单元测试和真实语料样本；涉及共享 runtime、 selector、body lifecycle 或 comparison 时，还必须运行核心 17、相应扩展能力矩阵和 可控的全量 shard。报告未运行的范围和原因，不能将缓存旧工件当作新代码的证据。
• 对用户要求查看或人工判定的样本，生成并保留 source STEP 与 rebuild STEP 的一致视角 对比截图；截图只辅助人工审查，最终分类仍以完整 history、B-rep 比较和诊断为准。
• 任何失败都保留最后可执行 STEP、GLB（如可生成）、comparison/diagnostic 工件和前缀 信息。不可执行或不相似不允许清理、覆盖或隐藏已有可用工件。
• 提交前执行与改动比例相称的测试、git diff --check，并确认本地能力台账未被 staged。 除非用户明确要求，不得提交、push、覆盖用户未提交修改或变更回归基线。

开源实现与 SimpleCADAPI 参考

• 在自行设计 shell、sweep、loft、boolean、fillet/chamfer、transform、topology tracking、 body graph 或比较基础设施前，必须先检索成熟的开源实现、官方 OCCT/OCP API 和已有 项目依赖；优先复用经过测试的算法、内核调用模式或小范围实现，而不是重新发明基础 B-rep 算法。外部代码的许可证、版本兼容性、异常语义和维护状态必须先核实。
• 本地首选参考是 /Users/lk/Downloads/SimpleCADAPI-master 4。重点阅读其 src/simplecadapi/topology/tracking.py、kernel/ocp_booleans.py、 kernel/ocp_topology.py、kernel/ocp_transforms.py 及对应 tests/docs：其中的 OCC builder history、Modified/Generated/IsDeleted、section edges、same-domain cleanup、显式 shape transform、shell/sweep/loft 调用边界是当前 engine 的优先参考。
• 借鉴必须经过本项目的 CDSL schema、runtime body graph、selector provenance 和 回归测试适配。不得直接替换本项目的 CDSL contract，也不得照搬其“强制单一 Solid” 的 union/cut 语义，因为 CADFS 需要保留独立 body、copy、keep tools 和 pattern instance 生命周期。
• 每次因开源参考新增或调整能力时，在本地能力台账记录参考来源、采用的通用语义、 未采用部分及理由、许可证/依赖影响和本项目回归证据。无法安全采用时，也应记录 评估结论，避免后续重复实现或重复调研。
• 发现现有方案方向错误或外部方案明显更适合时，可替换而不是继续打补丁；但必须满足 “修改前与实现方式”中的结构性根因和对照验证门槛，并在台账记录替换理由、迁移影响、 保留的 contract、回归结果和可回滚边界。