提交当前项目改动

2026-07-02 08:01:34 -04:00
parent 83075c4b96
commit c4a721f6cf
274 changed files with 157294 additions and 1394 deletions
--- a/web-rtcp-5axis-xyzbc-trt-sim-plan/working/02-项目程序开发详细步骤.md
+++ b/web-rtcp-5axis-xyzbc-trt-sim-plan/working/02-项目程序开发详细步骤.md
@@ -0,0 +1,215 @@
+# 02-项目程序开发详细步骤
+
+## 步骤
+
+1. 读取 `doc/xyzbc-trt-runtime-files.md`，确认 LinuxCNC 进程、INI、PyVCP、POSTGUI HAL、Vismach、remap、tool table、parameter file 的运行关系。
+2. 读取 `wasm-port/AGENTS.md` 和 `wasm-port/SKILL.md`，确认必须复用 LinuxCNC 源码语义，Web 只做 UI/OPFS/运行边界适配。
+3. 检查 `wasm-port` 是否包含 `xyzbc-trt`：确认 SDK、probe、vendored configs、remap harness 已覆盖。
+4. 复制参考 Web app 到目标目录：
+
+```text
+web-rtcp-5axis-xyzbc-trt-sim-plan/app
+web-rtcp-5axis-xyzbc-trt-sim-plan/tests
+```
+
+5. 将目标 app 默认机型改为 `xyzbc-trt`：
+
+```text
+app/src/state/store.js
+app/src/profiles/index.js
+app/src/runtime/linuxcnc-kinematics-runtime.js
+app/src/runtime/linuxcnc-kinematics-worker-client.js
+app/src/main.js
+```
+
+6. 将 OPFS/session/tool-db 根路径改为目标项目命名空间：
+
+```text
+web-rtcp-5axis-xyzbc-trt-sim-plan/machines
+web-rtcp-5axis-xyzbc-trt-sim-plan/sessions
+web-rtcp-5axis-xyzbc-trt-sim-plan/tool-db
+```
+
+7. 为 `xyzbc-trt` profile 增加默认机器文件 staging：
+
+```js
+machineFileStaging: {
+  defaultProgramFilename: "xyzbc_switchkins.ngc",
+  wasmDir: "/work/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt",
+}
+```
+
+8. 新增目标项目 Node smoke：
+
+```text
+tests/node/verify_xyzbc_trt_web_app.mjs
+```
+
+9. 创建工作文档：
+
+```text
+working/01-项目功能内容.md
+working/02-项目程序开发详细步骤.md
+working/03-推进台账.md
+working/04-任务矩阵.md
+working/05-验收证据.md
+working/06-决策记录.md
+working/07-全量对标追踪矩阵.md
+working/README.md
+```
+
+10. 按 `07-全量对标追踪矩阵.md` 继续补齐 Web 对标功能：
+
+```text
+AXIS 等效界面
+PyVCP/POSTGUI HAL 等效连接
+basic_sim task/HAL 等效运行
+Vismach xyzbc-trt-gui.py 等效 3D 模型
+Ngcgui/remap 子程序全集 staging 和执行
+TRAJ/AXIS/JOINT 限制、速度、单位和 override
+tool table/tool offset 对 kinematics 和模型的双向影响
+native/Web JSON 全字段对比
+```
+
+11. 切换 native 真实执行基线到 `/home/mes123456/cnc_wams/linuxcnc`：
+
+```bash
+test -x /home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment
+test -x /home/mes123456/cnc_wams/linuxcnc/bin/axis
+test -x /home/mes123456/cnc_wams/linuxcnc/bin/xyzbc-trt-gui
+test -f /home/mes123456/cnc_wams/linuxcnc/rtlib/xyzbc-trt-kins.so
+test -f /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
+```
+
+验收要求：
+
+- 上述文件存在后，native 采集脚本统一使用 `/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment`。
+- 真实执行命令的 INI 必须是 `/home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini`。
+- Web 界面布局、状态流、switchkins 逻辑、Vismach 等效模型、刀具路径和 JSON 字段都以该路径实际执行结果为准。
+- `/home/mes123456/linuxcnc-master` 只能作为历史运行参考，不再作为新的 native evidence 基线。
+
+## 后续完整验收步骤
+
+1. 生成 WASM artifact：
+
+```bash
+source /home/mes123456/emsdk/emsdk_env.sh
+wasm-port/tools/build_kinematics_wasm.sh
+wasm-port/tools/build_wasm_core.sh
+wasm-port/tools/build_tp_wasm.sh
+wasm-port/tools/build_task_hal_wasm.sh
+```
+
+2. 运行 wasm-port 对应验证：
+
+```bash
+wasm-port/tests/wasm/node/verify_kinematics_wasm.sh
+wasm-port/tests/wasm/node/verify_interp_wasm.sh
+wasm-port/tests/wasm/node/verify_task_hal_wasm.sh
+wasm-port/tests/browser/verify_interp_browser.sh
+```
+
+3. 运行目标 app 验证：
+
+```bash
+npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run smoke:node
+npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run build
+```
+
+4. 生成 native/Web 对比证据：
+
+```bash
+/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment \
+  python3 web-rtcp-5axis-xyzbc-trt-sim-plan/tools/collect-native-xyzbc-trt-evidence.py --run --timeout 90
+npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:web
+npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:compare
+```
+
+输出：
+
+```text
+web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/native-xyzbc-trt-evidence.json
+web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/web-xyzbc-trt-evidence.json
+web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/compare-xyzbc-trt-evidence.json
+```
+
+5. 补充刀具预览路径和刀具执行路径采集：
+
+```text
+tools/collect-native-xyzbc-trt-evidence.py
+tools/collect-web-xyzbc-trt-evidence.mjs
+tools/compare-xyzbc-trt-evidence.mjs
+```
+
+实现要求：
+
+- 在 native evidence 中增加 `pathSampling`、`previewPath`、`executionPath`。
+- 在 Web evidence 中增加同名字段，字段结构必须与 native 完全一致。
+- 统一对比采样周期为 `samplePeriodMs = 20`。
+- 采集脚本可保留原始高频/低频轨迹，但写入对比 JSON 的曲线必须重采样到 20ms。
+- 预览路径从 LinuxCNC preview/canon 或 Web preview planner 采集；执行路径从 LinuxCNC `stat()`/HAL 反馈或 Web task/HAL runtime 采集。
+- 每个样本必须包含 `sampleIndex`、`timeMs`、`line`、`motionType`、`activeKinematics`、`tool`、`joint`、`tcp`、`toolAxis`、`feed`、`spindle`。
+- 对 B/C 旋转轴和 TCP/toolAxis 的计算必须以 `xyzbc-trt` kinematics/WASM 结果为准，不能用 UI 插值伪造。
+
+6. 补充刀路 compare 规则：
+
+```json
+{
+  "pathComparison": {
+    "samplePeriodMs": 20,
+    "previewVsPreview": {},
+    "executionVsExecution": {},
+    "previewVsExecutionNative": {},
+    "previewVsExecutionWeb": {}
+  }
+}
+```
+
+验收要求：
+
+- `compare-xyzbc-trt-evidence.json` 中新增 `pathComparison`。
+- `checks` 中新增 `path-preview`、`path-execution`、`path-preview-execution-consistency` 类别。
+- 每类检查至少输出 `maxTcpErrorMm`、`rmsTcpErrorMm`、`maxJointError`、`rmsJointError`、`maxToolAxisAngleDeg`、`sampleCountDelta`、`missingSamples`。
+- 若 native/Web 两侧采样周期不一致，compare 必须直接 fail，并输出实际周期。
+- 若 WASM artifact 缺失导致 Web 执行路径无法采集，compare 必须保持 fail/blocker，不能用预览路径替代执行路径。
+
+7. 补充全量对标 JSON 字段：
+
+```json
+{
+  "startupSequence": [],
+  "iniDisplay": {},
+  "halNets": [],
+  "kinematicsPins": {},
+  "axisJointLimits": {},
+  "switchkinsTransitions": [],
+  "uiEquivalence": {},
+  "vismachEquivalent": {},
+  "ngcguiSubroutines": [],
+  "demoPrograms": []
+}
+```
+
+验收要求：
+
+- `startupSequence` 对标 `.desktop -> rip-environment -> linuxcncsvr/rtapi_app/milltask/halui -> basic_sim -> kinematics -> Vismach -> AXIS -> PyVCP -> POSTGUI HAL -> OPEN_FILE`。
+- `halNets` 覆盖 `motion.switchkins-type`、`halui.mdi-command-*`、`pyvcp.*`、`joint.N.pos-fb`、`motion.tooloffset.z`、`xyzbc-trt-kins.*`。
+- `kinematicsPins` 覆盖 `x-offset=-20`、`z-offset=-15`、`x/y/z-rot-point=0`、`conventional-directions=0`、`tool-offset`。
+- `axisJointLimits` 覆盖 `XYZBC` 单位、关节数、B/C 角轴限制、TRAJ 速度/加速度。
+- `uiEquivalence` 覆盖 AXIS 主界面的程序区、坐标区、MDI/switchkins、override、工具、状态、预览/执行路径。
+- `vismachEquivalent` 覆盖 `xyzbc-trt-gui.py` 的模型 pin 和清除轨迹行为。
+- `ngcguiSubroutines` 覆盖 `xyzbc_switchkins_sub.ngc`、`centering.ngc`、`helix_bc.ngc`。
+- `demoPrograms` 覆盖 `xyzbc_switchkins.ngc` 和 `boat-xyzbc.ngc`。
+
+8. 启动目标 Web：
+
+```bash
+cd web-rtcp-5axis-xyzbc-trt-sim-plan/app
+npm run dev
+```
+
+默认 URL：
+
+```text
+http://127.0.0.1:4174/
+```