cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/06-决策记录.md

06-决策记录

D-013：缺 WASM artifact 时 build 与 path compare 继续显式失败

日期：2026-07-02

决策：本轮补齐 Web/native evidence 字段和 compare 规则，但在缺少 wasm-port/build/wasm artifact 时，npm run build、Web preview path、Web task/HAL execution path 和 compare path 检查继续显式失败或 blocked，不通过占位样本伪造通过。

理由：

• xyzbc-trt 的 G-code、remap、kinematics、planner、task/HAL 语义必须来自 LinuxCNC-derived WASM 或真实 LinuxCNC evidence。
• 当前仓库缺少 wasm-port/build/wasm/kinematics、core、tp、task-hal artifact，浏览器 worker/runtime 不具备真实执行条件。
• compare JSON 的失败项已经精确指向 artifact 与 path 样本缺口，保留失败状态比静默降级更利于后续验收。

D-012：DOCX 任务书整合为 working Markdown

日期：2026-07-02

决策：将 doc/xyzbc-trt-web-cnc-simulation-design-task-and-technical-plan.docx 的正文、表格和图片引用整合为 working/09-设计任务书与技术方案整合.md，并把它加入 working 索引和任务矩阵。

理由：

• DOCX 不便于命令行检索、diff、逐项验收和后续增量维护。
• working 目录是当前项目的开发和验收入口，任务书内容必须进入该目录才能和 01-08 工作文档形成闭环。
• Markdown 版本可以保留 DOCX 的完整任务书、技术方案、程序逻辑分析和状态联锁内容，同时继续引用 doc/assets 中的原始图片证据。

D-001：以 wasm-port 为 CNC 语义来源

日期：2026-07-02

决策：Web 项目不在 JavaScript 中重写 G-code、remap、tool table、parameter、kinematics 或 planner 语义，继续通过 wasm-port 的 LinuxCNC-derived SDK/WASM 获取语义。

理由：

• wasm-port/AGENTS.md 明确要求 LinuxCNC 源码是语义真源。
• wasm-port 已经包含 xyzbc-trt kinematics、remap、interp、task/HAL 的边界设计。

D-002：复制参考 app 后改为 xyzbc-trt 默认机型

日期：2026-07-02

决策：复用 web-rtcp-5axis-sim-plan/app 的结构，创建目标目录独立 app，并只做 xyzbc-trt 默认化和项目命名空间隔离。

理由：

• 参考 app 已包含 OPFS、WASM SDK、五轴可视化、profile、task/HAL、tool DB、session 等大部分产品外壳。
• 局部改造比重写界面风险低，且保留 LinuxCNC source-derived 边界。

D-003：目标项目 OPFS 根路径独立

日期：2026-07-02

决策：目标项目使用 web-rtcp-5axis-xyzbc-trt-sim-plan/machines、sessions、tool-db，不复用旧项目 web-rtcp-5axis-sim-plan 路径。

理由：

• 防止两个项目在 OPFS 中互相覆盖机器文件、会话、tool DB。
• 便于后续按项目清理和验收。

D-004：默认程序使用 xyzbc_switchkins.ngc

日期：2026-07-02

决策：为 xyzbc-trt profile 增加 machineFileStaging.defaultProgramFilename = "xyzbc_switchkins.ngc"。

理由：

• LinuxCNC INI [DISPLAY]OPEN_FILE 指向 ./demos/xyzbc_switchkins.ngc。
• 参考 app 的自动选择逻辑按 ${profileId}_switchkins.ngc 推导时会得到不存在的 xyzbc-trt_switchkins.ngc，必须显式覆盖。

D-005：完整浏览器验收等待 WASM artifact

日期：2026-07-02

决策：本轮先完成代码、工作文档和不依赖 artifact 的 Node smoke；完整 browser/WASM 验收记录为后续前置任务。

理由：

• 当前 wasm-port/build/wasm 不存在。
• 页面 runtime 代码已接入 worker/WASM，但缺少 .js/.wasm 产物时无法完成真实浏览器执行。

D-006：受控导入 xyzbc.var staging

日期：2026-07-02

决策：从当前真实运行树 /home/mes123456/linuxcnc-master/.../xyzbc.var 导入 xyzbc.var 到 wasm-port/vendor/linuxcnc/.../xyzbc.var，并加入 wasm-port/tools/source-manifest.txt。

理由：

• xyzbc-trt.ini 明确声明 PARAMETER_FILE = xyzbc.var。
• 若不导入，OPFS machine-file staging 无法覆盖完整 runtime files。
• 直接在 Web wrapper 中引用运行树绝对路径不可复现；纳入 vendor/manifest 后，Node/Web staging 可重复。

D-007：native/Web JSON 对比作为验收主线

日期：2026-07-02

决策：新增 native、Web、compare 三个 JSON 证据脚本，作为后续完善项目的主验收链路。

理由：

• 用户要求真实 xyzbc-trt 与 Web 仿真分别写入 JSON，再通过比对 JSON 完善项目。
• JSON 证据比单次截图或口头结论更容易复跑、归档和定位差异。
• 当前比较报告已把差异收敛到唯一环境前置：缺 WASM artifact。

D-008：WASM artifact 缺失不伪造通过

日期：2026-07-02

决策：当前 wasm-port/build/wasm 为空，Web evidence 和 compare evidence 保持 blocked/fail，不伪造 WASM 执行完成。emcc 6.0.2 已安装后，下一步是构建 artifact，而不是改写证据为通过。

理由：

• wasm-port 规则要求 LinuxCNC 源码语义和 WASM 边界真实可验证。
• 没有 .js/.wasm artifact 时，浏览器 worker runtime 无法完成真实执行。
• 保留失败项可以明确下一步是激活已安装的 Emscripten 并构建 artifact，而不是继续堆叠 Web UI 假状态。

D-009：刀具路径按统一 20ms 周期采样后比较

日期：2026-07-02

决策：native/Web 的刀具预览路径和刀具执行路径进入 evidence JSON 前，统一按 samplePeriodMs = 20 重采样；compare 只对同一 sampleIndex/timeMs 的样本做逐点比较。

理由：

• LinuxCNC 真实系统和 Web 仿真系统的内部刷新、planner、HAL/task 采样频率可能不同，直接比较原始样本会产生时间错位。
• 固定 20ms 可以覆盖人眼可见刀路和 UI 动画判断，同时让 JSON 体积可控。
• 统一 sampleIndex/timeMs 后，TCP、XYZBC joint、toolAxis、feed、spindle 的误差统计可以稳定复跑。
• 如果 Web 缺少 WASM task/HAL 执行反馈，不允许用预览路径冒充执行路径；compare 必须显式 fail/blocker。

D-010：以全量对标追踪矩阵作为开发和验收主索引

日期：2026-07-02

决策：新增 working/07-全量对标追踪矩阵.md，作为 Web xyzbc-trt 仿真界面后续开发、JSON 采集和 compare 验收的主索引。

理由：

• doc/xyzbc-trt-runtime-files.md 覆盖的范围超过单个 INI/staging 检查，还包括 AXIS、PyVCP、POSTGUI HAL、basic_sim、Vismach、kinematics HAL pins、Ngcgui、演示程序和加载顺序。
• 若没有追踪矩阵，后续容易只完成页面可见部分，而漏掉 HAL/task/kinematics/tool-offset 等运行语义。
• 追踪矩阵把每个 LinuxCNC 功能点映射到 Web 对标目标和 evidence 字段，便于自动化 compare 脚本逐步落地。

D-011：native 真实执行基线切换到 /home/mes123456/cnc_wams/linuxcnc

日期：2026-07-02

决策：后续 Web 界面和逻辑设计以 /home/mes123456/cnc_wams/linuxcnc 编译后执行 xyzbc-trt 的真实行为为 native 基线；/home/mes123456/linuxcnc-master 只保留为历史运行参考。

理由：

• 用户明确要求以已编译成功并能执行 xyzbc-trt 的 /home/mes123456/cnc_wams/linuxcnc 为对标依据。
• /home/mes123456/cnc_wams/linuxcnc 是干净 Git 源码仓库，便于把 native 行为、Web WASM 构建和后续代码追踪关联到同一源码树。
• 该路径已完成 run-in-place 编译，scripts/rip-environment、bin/axis、bin/xyzbc-trt-gui、rtlib/xyzbc-trt-kins.so 已生成；因此后续第一步是用该路径重新生成 native evidence。

D-012：WASM artifact 已生成，后续 blocker 改为路径采集与 interpreter 回归

日期：2026-07-02

决策：wasm-port/build/wasm artifact 已通过 emcc 6.0.2 生成，Web evidence 不再把缺 artifact 作为 blocker；后续开发重点转向 native/Web path 采集闭环、Web task/HAL execution path collector，以及 verify_interp_wasm.sh 的 G10 L11 回归断言差异。

理由：

• core、kinematics、TP、task/HAL 所需 .js/.wasm 均已存在，web-xyzbc-trt-evidence.json.wasm.missing=[]。
• kinematics、TP、task/HAL 的 Node WASM smoke 已通过，说明主要 runtime artifact 可加载执行。
• Web preview path 已由 linuxcnc_interp WASM 生成样本，证明 Web evidence 已越过原先缺 artifact 的前置阻塞。
• compare 剩余失败项均指向 native path 样本和 Web execution path 样本缺失；这是采集能力缺口，不再是构建产物缺口。
• 历史状态：当时 verify_interp_wasm.sh 仍有 interp_g10_l11_wasm 断言失败，完整 interpreter/remap WASM 验收不能标记为完成。

D-013：G10 L11 验收期望对齐 vendored LinuxCNC expected

日期：2026-07-02

决策：将 verify_interp_wasm.mjs 中 interp_g10_l11_wasm 的 SET_G92_OFFSET 期望值调整为 x=-43.0622 y=-47.4282 z=-72，与 wasm-port/vendor/linuxcnc/tests/interp/g10/g10-l11/expected 保持一致。

理由：

• 单独复现 g10-l11 后，WASM 实际 canonical 输出为 SET_G92_OFFSET x=-43.0622 y=-47.4282 z=-72。
• vendored LinuxCNC 当前 expected 文件同样记录 SET_G92_OFFSET(-43.0622, -47.4282, -72.0000)。
• 因此失败原因是 Node 验收脚本中的期望值过期，不是 WASM interpreter/remap 行为偏离 vendored LinuxCNC。
• 修正后，SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh 和完整 wasm-port/tests/wasm/node/verify_interp_wasm.sh 均通过，输出 interp_wasm_node_smoke=ok。