181 lines
9.3 KiB
Markdown
181 lines
9.3 KiB
Markdown
# 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`。
|