# 07-全量对标追踪矩阵

本文件把 `doc/xyzbc-trt-runtime-files.md` 中记录的 LinuxCNC `xyzbc-trt` 真实运行功能，逐项映射到 Web 数控系统仿真界面的目标、证据和缺口。

原则：

- Web 实现必须完全对标 `xyzbc-trt-runtime-files.md` 的运行语义。
- LinuxCNC 源码、INI、HAL、remap、tool table、parameter file 和 kinematics 是语义真源。
- AXIS、PyVCP、Vismach 这类桌面 UI 组件在 Web 中做同语义等效实现。
- 每项对标最终都要进入 native/Web evidence JSON 和 compare JSON，不能只停留在 UI 文案。
- 后续 native 真实执行基线统一采用 `/home/mes123456/cnc_wams/linuxcnc`，`/home/mes123456/linuxcnc-master` 只作为历史运行树参考。

## 运行入口与进程对标

| LinuxCNC 功能 | 真实配置来源 | Web 对标目标 | Evidence/验收 |
| --- | --- | --- | --- |
| `.desktop` 启动 `rip-environment linuxcnc xyzbc-trt.ini` | `/home/mes123456/cnc_wams/linuxcnc/linuxcnc-rtcp-5axis-shortcuts/.../xyzbc-trt.desktop` | Web profile 一键进入 `xyzbc-trt`，自动加载同一 INI/staging 文件集 | web JSON 记录 `profile=xyzbc-trt`、`iniPath`、`startupSequence` |
| `linuxcncsvr`、`rtapi_app`、`milltask`、`halui` | 当前进程清单 | Web runtime 用 worker/WASM/task-HAL 表示 server/task/halui 边界 | compare 检查 `runtimeComponents` 包含 `interp`、`tp`、`taskHal`、`haluiEquivalent` |
| AXIS 主界面进程 | `bin/axis -ini xyzbc-trt.ini` | Web 首屏直接进入 CNC 操作界面，不做营销页 | 浏览器 smoke 检查坐标、程序、switchkins、3D canvas 均可见 |
| Vismach 进程 | `loadusr -W xyzbc-trt-gui` | Web 3D 机床模型按 HAL pin 驱动 | evidence 记录 Vismach pin 等效映射 |

## INI 与显示配置对标

| INI 字段 | LinuxCNC 行为 | Web 对标目标 | 状态 |
| --- | --- | --- | --- |
| `[EMC] MACHINE = sim-xyzbc-trt-kins (switchkins)` | AXIS 标题/机器名 | 页面机器名、JSON machine name 一致 | 待验收 |
| `[DISPLAY] DISPLAY = axis` | 启动 AXIS | Web 实现 AXIS 等效操作面板 | 待全量验收 |
| `[DISPLAY] GEOMETRY = XYZB` | AXIS 几何显示 | Web 坐标/预览按 XYZB 几何显示，C 轴仍参与机床/路径 | 待补充 |
| `[DISPLAY] JOG_AXES = XYZC` | 手动 jog 轴集合 | Web jog 控制至少覆盖 X/Y/Z/C，并显示 B/C 状态 | 待补充 |
| `[DISPLAY] POSITION_OFFSET = RELATIVE` | 坐标偏置显示 | Web 默认显示相对坐标并可记录 work offset | 待补充 |
| `[DISPLAY] POSITION_FEEDBACK = ACTUAL` | 显示实际反馈位置 | Web 坐标读数来自 task/HAL actual feedback，不只显示 commanded | 待 task-HAL |
| `[DISPLAY] MAX_FEED_OVERRIDE = 2` | 进给倍率最大 200% | Web feed override 控件范围 0-200% | 待补充 UI 验收 |
| `[DISPLAY] MAX_LINEAR_VELOCITY = 1000` | AXIS UI 限速 | Web UI 限速显示/约束一致 | 待补充 |
| `[DISPLAY] MAX_ANGULAR_VELOCITY = 360` | 角轴限速 | Web 角轴 jog/显示限速一致 | 待补充 |
| `[DISPLAY] PROGRAM_PREFIX = ../../nc_files` | 打开程序默认目录 | Web 程序文件浏览/staging 根目录记录等效路径 | 待补充 |
| `[DISPLAY] TOOL_EDITOR = tooledit z diam` | 工具编辑字段 | Web tool editor 至少支持 Z 和 diameter | 待补充 |
| `TKPKG/NGCGUI_*` | AXIS Ngcgui 面板加载子程序 | Web 需 stage 并提供子程序参数化调用入口或等效验证 | 待实现 |

## 文件 staging 对标

| 文件 | 作用 | Web 对标目标 | 当前要求 |
| --- | --- | --- | --- |
| `xyzbc-trt.ini` | 主配置 | OPFS/wasm runtime 必须使用同源 INI | 已有 staging，需全量字段校验 |
| `xyzbc-trt.xml` | PyVCP switchkins 面板 | Web switchkins 面板由 XML/schema 驱动 | 已有，需 pin 连接证据 |
| `switchkins_postgui.hal` | PyVCP 到 halui MDI 的连接 | Web 需记录 `pyvcp.* -> halui.mdi-command-*` | 待 compare 检查 |
| `basic_sim.tcl` | 基础仿真 HAL | Web task/HAL runtime 等效模拟 joint/home/spindle/toolchange | 待 task-HAL 验收 |
| `xyzbc-trt_cmds.hal` | 运行后生成 HAL | Web evidence 需记录等效展开 HAL nets | 待实现 |
| `xyzbc-trt-gui.py` | Vismach 模型 | Web 3D pin/模型层级对标 | 待模型验收 |
| `axis.py` | AXIS 主界面行为 | Web 操作面板对标 AXIS 关键行为 | 待 UI 验收 |
| `xyzbc-trt-kins.c` | 运动学真源 | WASM kinematics 使用 source-derived artifact | 待构建 artifact |
| `xyzbc-trt.tbl` | 工具表 | Web tool DB 读取 T/P/Z/D | 已有 staging，需 UI/tool-offset 验收 |
| `xyzbc.var` | 参数文件 | OPFS 保存/恢复参数 | 已有 staging，需运行后变更验证 |

## HAL 与 switchkins 对标

| LinuxCNC HAL 语义 | Web 对标目标 | Evidence/验收 |
| --- | --- | --- |
| `motion.analog-out-03 => motion.switchkins-type` | Web remap/MDI 写入 switchkins type，并暴露当前类型 | native/Web JSON 对比 switchkins transitions |
| `halui.mdi-command-00 = M429` | Web `IDENTITY` 按钮执行 M429 | 按钮事件、MDI 命令、switchkins type 都写入 evidence |
| `halui.mdi-command-01 = M428` | Web `TCP:XYZBC` 按钮执行 M428 | 同上 |
| `halui.mdi-command-02 = M430` | Web `userk` 按钮执行 M430 | 同上 |
| `kinstype.is-0/1/2 -> pyvcp.multilabel` | Web multilabel 显示当前 kinematics | UI state 与 HAL state 一致 |
| `pyvcp.vismach-clear -> vismach.plotclear` | Web clear 按钮清除 3D 轨迹/preview buffer | evidence 记录 clear 前后 path count |
| `joint.N.pos-fb -> xyzbc-trt-gui.*` | Web 3D 模型从 actual joint feedback 驱动 | path/execution JSON 记录 feedback 来源 |
| `motion.tooloffset.z -> xyzbc-trt-kins.tool-offset -> gui.tool-offset` | 工具长度同时影响 kinematics 和模型显示 | tool table、tool offset、TCP/toolAxis 误差检查 |

## 运动学与机床模型对标

| 项目 | LinuxCNC 来源 | Web 对标目标 |
| --- | --- | --- |
| `KINEMATICS = xyzbc-trt-kins sparm=identityfirst` | INI/KINS | 默认 switchkins type 0 为 identity，M428 后为 XYZBC TCP |
| `JOINTS = 5` | INI/KINS | Web runtime 固定 XYZBC 五关节 |
| `x-offset = -20` | HALCMD sets | Web kinematics pin 默认值一致 |
| `z-offset = -15` | HALCMD sets | Web kinematics pin 默认值一致 |
| `x/y/z-rot-point = 0` | HALCMD setp | Web kinematics pin 默认值一致 |
| `conventional-directions = 0` | HALCMD setp | Web kinematics pin 默认值一致 |
| `table-x/saddle-y/spindle-z/tilt-b/rotate-c` | Vismach pins | Web 模型层级按这些反馈驱动 |
| `tool-offset/x-offset/z-offset` | Vismach/kines pins | Web 刀具和模型偏置一致 |

## G-code、remap 与子程序对标

| 文件/命令 | LinuxCNC 行为 | Web 对标目标 |
| --- | --- | --- |
| `M429` | kinstype=0，Identity | Web MDI/remap 执行后 switchkins type 为 0 |
| `M428` | kinstype=1，XYZBC/TCP | Web MDI/remap 执行后 switchkins type 为 1 |
| `M430` | kinstype=2，USERK | Web MDI/remap 执行后 switchkins type 为 2 |
| `xyzbc_switchkins.ngc` | 默认打开并调用子程序 | Web 默认程序一致 |
| `xyzbc_switchkins_sub.ngc` | 四象限 switchkins/TCP 演示 | Web 必须 stage 并可执行 |
| `centering.ngc` | Ngcgui 子程序 | Web 必须 stage；后续实现参数入口 |
| `helix_bc.ngc` | B/C helix 五轴轨迹 | Web 必须 stage 并进入路径对比 |
| `boat-xyzbc.ngc` | 额外演示程序 | Web 必须 stage 并可作为验收程序 |

## JSON 证据对标

native evidence、Web evidence、compare evidence 必须覆盖：

- `startupSequence`：启动/初始化顺序和等效组件。
- `iniDisplay`：DISPLAY/TRAJ/KINS/TASK/EMCMOT/EMCIO 关键字段。
- `stagedFiles`：所有对标文件，包括 remap 子程序和 demo 程序全集。
- `halNets`：switchkins、PyVCP、Vismach、tool-offset、joint feedback 连接。
- `kinematicsPins`：offset、rot-point、conventional-directions、tool-offset。
- `axisJointLimits`：X/Y/Z/B/C 和 JOINT_0..4 限制、单位、速度/加速度。
- `switchkinsTransitions`：M429/M428/M430 的命令、HAL pin 和状态变化。
- `toolTable`：T/P/Z/D 解析和当前工具偏置。
- `previewPath`：刀具预览路径，20ms 统一采样。
- `executionPath`：刀具执行路径，20ms 统一采样。
- `pathComparison`：native/Web 预览与执行路径误差统计。
- `uiEquivalence`：AXIS/PyVCP/Vismach 在 Web 中的等效控件和状态。

## 当前主要缺口

1. WASM artifact 尚未构建，`wasm-port/build/wasm` 缺少 kinematics/core/tp/task-hal `.js/.wasm`。
2. Web evidence 还未记录完整 `startupSequence`、`halNets`、`kinematicsPins`、`axisJointLimits`。
3. Web UI 还需按 AXIS 等效面板补齐 jog、override、tool editor、Ngcgui 子程序入口。
4. Vismach 等效模型还需按 `xyzbc-trt-gui.py` 的 pin 和模型层级做验收。
5. 刀具预览路径和执行路径 JSON 采集尚未实现。
6. `boat-xyzbc.ngc` 和 Ngcgui 子程序的 Web 可执行验收尚未完成。