FreeCAD CAM Path 原生 Oracle 实施说明

更新时间：2026-08-07

这份说明覆盖浏览器 CAM 对标所需的三类原生证据：FreeCAD Path 算法回放、Qt CAM 工作台动态状态、以及 Path::Feature / Path::FeaturePython 的 FCStd 保存与恢复。当前 Web 编辑边界是经 FreeCAD 重开验证的原生 Path::Feature 命令资源子集；Python-backed 对象仍只读且不执行代码。

参考环境

FreeCAD：1.1.1，源码提交 0108fd4b4850cc46e625b60e53cea7a7bbe69f8d
构建：.cache/freecad/install-desktop/bin/FreeCAD
GUI：通过 xvfb-run 启动，GuiUp=true
Qt：运行时采集为 6.8.2
CAM 模块：PathApp.so、PathGui.so、PathSimulator.so 均来自桌面构建

已完成的原生证据

能力	证据	状态
原生 Profile 算法	`Mod/CAM/CAMTests/test_profile.fcstd`，真实 `Path.Op.Profile` 覆盖工具补偿和无补偿两种场景；每种生成 32 条命令，其中 20 条切削命令；命令按 0.01 mm 数值容差规范化并锁定 SHA-256	verified-2-scenarios
原生 Helix 算法	`Mod/CAM/CAMTests/test_holes00.fcstd`，0.9 mm 刀具、9 个 base 子元素，覆盖 Inside/Outside 与 Climb/Conventional 四种组合；每种包含 1260 条原生 G2 或 G3 弧命令并验证 CW/CCW 方向	verified-4-scenarios
Qt 动态 oracle	激活 `CAMWorkbench`，读取 56 个实时 `CAM_*` 命令、QAction 文本/图标/快捷键/注册状态、菜单和工具栏；并通过真实 `setEdit()`、QDialogButtonBox OK/Cancel、14 个 Task 字段和关闭回放验证 Job/Profile Task 生命周期	verified
原生 Path FCStd	创建 `Path::Feature` 与 `Path::FeaturePython`，保存、重开、修改路径和属性、再次保存并重开；`Path::PropertyPath`、5/6 条命令和标签均被 FreeCAD 恢复	verified
Web Path 编辑与透明往返	Facade 对 `Path::Feature` 解码/重写 `.nc` 资源；显式 `allowFeaturePython` 时也可对 `Path::FeaturePython` 只改 `.nc` 资源，追加命令后由 FreeCAD 重开验证 5→6 条；脚本和 XML 仍保持不执行/不改写	verified-safe-resource-only-opt-in

结构化结果在 config/freecad-cam-path-oracle.json。生成和校验脚本分别是 scripts/run-freecad-cam-path-oracle.ts、scripts/freecad-cam-path-oracle.py 和 scripts/check-freecad-cam-path-oracle.mjs。

复跑和门禁

./npmw run probe:freecad-cam-path
./npmw run check:freecad-cam-path
./npmw run test:freecad-cam-path-report

probe 会在 .cache/freecad/cam-path-oracle/ 生成源档案、变更档案和 Web 透明副本。报告中的 FCStd 完整性哈希是重开后 Path 对象语义哈希；运行时仍比较透明副本和源档案的完整字节。Profile 命令使用 0.01 mm 规范化，避免 OCCT 在 1e-6 mm 级别的浮点抖动造成假差异。连续两次完整 probe 的报告语义结果稳定。

任务安排

任务	交付物	当前状态	后续验收
ORA-CAM-PATH-01	Profile/Helix 等 Path 算法原生 fixture 与规范化黄金	in_progress（Profile 2 场景 + Helix 4 场景）	继续扩展 Drilling、Pocket、Surface 等工序的输入、失败和版本黄金
ORA-CAM-PATH-02	Qt 工作台命令、QAction、菜单、工具栏、选择上下文和 TaskPanel 生命周期采集器	completed（56 命令 + Job/Profile 生命周期）	扩展更多工序的字段/校验/焦点黄金
ORA-CAM-PATH-03	原生 `Path::Feature` / `Path::FeaturePython` FCStd 双向保存恢复	completed（native-native）	增加 Job、ToolController、SetupSheet 和 Dress-up 对象
ORA-CAM-PATH-04	Web Facade `Path::PropertyPath` 结构化解码/编码与可编辑事务	completed（Path::Feature + FeaturePython 安全资源 opt-in）	扩展 Job/Operation 对象、属性/重算语义和 Undo/Redo；不宣称完整 operation-object 语义
ORA-CAM-PATH-05	FreeCAD Path 与 OpenCamLib/CAMotics 的连续差分	pending	版本锁定、同一 stock/tool/path 输入、体积/碰撞/时间差分

明确边界

当前 Web Facade 对 Path::Feature 提供结构化 Path::PropertyPath 解码/编码；对 Path::FeaturePython 只有显式 allowFeaturePython: true 才开放同样的资源级编辑。两者都只允许修改已有 native .nc 资源的命令列表，资源路径、版本和 Center 元数据保持不变；XML、脚本和 Python 代码从不执行或改写，编辑后由 FreeCAD 重开验证。算法 oracle 当前只覆盖 2 个 Profile 场景和 4 个 Helix 场景；完整 Path 操作对象、FeaturePython 属性/重算语义、其余工序算法、Undo/Redo 和全量 Qt Task 行为仍未达到 exact parity，整体报告的 exactParityClaim=false。

4.8 KiB Raw Blame History Unescape Escape