wip: preserve local engine and agent workflow changes before ganjihong refactor integration
This commit is contained in:
@@ -29,3 +29,104 @@
|
||||
## 改动评审指引
|
||||
|
||||
修改本系统时，优先保证执行确定性、部分结果可持久化、失败可诊断，以及终止行为有边界。避免加入语义审查关卡、要求复制 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、回归结果和可回滚边界。
|
||||
|
||||
Reference in New Issue
Block a user