linuxcncWebWASM/docs/linuxcnc-web-wasm-3axis-tutorial-parity.md

# 3axis Tutorial 案例对标实施文档

**唯一案例**：`linuxcnc/configs/sim/axis/vismach/3axis-tutorial`
**入口 INI**：`linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial.ini`
**机床**：3 轴笛卡尔、`trivkins`、X/Y/Z、3 joints、AXIS + Vismach
**范围**：LinuxCNC 源程序案例与 Web/WASM 仿真的功能、流程、界面三层对标
**状态**：单案例执行、功能、流程、界面、真实 individual home、真实 `change_button` tool ACK 和恢复证据已闭合；完整 235-case/release 仍不在本案例范围

**完成总报告**：[`coverage/axis3-tutorial-complete.report.json`](../coverage/axis3-tutorial-complete.report.json)

下一阶段总控方案：[`linuxcnc-web-wasm-3axis-tutorial-complete-parity-plan.md`](linuxcnc-web-wasm-3axis-tutorial-complete-parity-plan.md)。

状态机契约：[`linuxcnc-web-wasm-3axis-tutorial-state-machine.md`](linuxcnc-web-wasm-3axis-tutorial-state-machine.md)。

**持久化图片证据**：native AXIS [`native-axis.png`](../coverage/axis3-tutorial-visual/native-axis.png)、Chromium desktop [`chromium-desktop.png`](../coverage/axis3-tutorial-visual/chromium-desktop.png)、Chromium mobile [`chromium-mobile.png`](../coverage/axis3-tutorial-visual/chromium-mobile.png)。

后续工作只允许围绕这个案例展开。其它 `configs/sim` 案例、全量 matrix、其它机床族和 release closure 不属于本任务。

## 1. 已锁定的 exact 输入

案例目录中仅以下四个文件由 native runner 复制到隔离可写目录：

| 文件 | 用途 |
|---|---|
| `3axis-tutorial.ini` | AXIS、Task、RS-274、HAL、TRAJ、KINS、AXIS/JOINT limits |
| `3axis-tutorial.hal` | trivkins/motion/ddt/hypot、estop、manual toolchange、Vismach pins |
| `3axis-tutorial` | LinuxCNC Vismach Python model；Web 侧对应 Three.js model adapter |
| `tool.tbl` | 工具表和 tool-change 输入 |

运行时生成的 `3axis-tutorial_mm.var`、`.bak`、`position_mm.txt` 不复制为 source fixture，由 LinuxCNC/Web workspace 在运行时创建或提交。`INTRO_GRAPHIC = linuxcnc.gif` 通过 `linuxcnc/linuxcnc.gif` 共享资产语义解析。

源程序关联：

- 启动：`linuxcnc/scripts/linuxcnc.in`、`linuxcnc/scripts/update_ini`。
- INI：`linuxcnc/src/libnml/inifile/**`、`linuxcnc/src/emc/ini/**`。
- Task/IO：`linuxcnc/src/emc/task/**`、`linuxcnc/src/emc/iotask/ioControl.cc`、`linuxcnc/src/emc/tooldata/**`。
- Motion/Kinematics：`linuxcnc/src/emc/motion/**`、`linuxcnc/src/emc/kinematics/trivkins.c`、`linuxcnc/src/emc/tp/**`。
- HAL：案例 `3axis-tutorial.hal`、`linuxcnc/src/hal/hal_lib.c`、`linuxcnc/src/hal/utils/halcmd*`、`linuxcnc/src/hal/components/{ddt,hypot,sim_home_switch}.comp`。
- Vismach：`linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial`、`linuxcnc/lib/python/vismach.py`、`linuxcnc/lib/python/hal.py`、`linuxcnc/lib/python/linuxcnc.py`。
- AXIS UI：`linuxcnc/src/emc/usr_intf/axis/scripts/axis.py`、`linuxcnc/lib/python/rs274/glcanon.py`。

## 2. 正确 native 执行规约

执行器为 `scripts/run_axis3_tutorial_native.py`，报告为 `coverage/axis3-tutorial-native-run.report.json`。

1. 创建临时可写目录。
2. 只复制上表四个 exact source files。
3. 在副本上运行官方 `update_ini -f`，因为源 INI 的 `VERSION = 1.0` 会触发 LinuxCNC 的配置升级流程。
4. 保持 LinuxCNC 源程序目录 `/home/mes006/linuxcncWebWASM/linuxcnc` cwd、系统 `HALLIB_DIR`、真实 `DISPLAY`。
5. 先退出旧 LinuxCNC 服务（`linuxcncsvr`、`rtapi_app`、`milltask`、`halui`、`axis`）并确认 `/tmp/linuxcnc.lock` 不再被活动服务持有；然后在 `/home/mes006/linuxcncWebWASM/linuxcnc` 源程序目录执行 `linuxcnc <case_dir>/3axis-tutorial.ini`。
6. 轮询 X11 window tree；只有 WM class `axis / Axis`、标题含 `3axis-tutorial`、几何至少 `600x400` 才算成功。
7. 记录 update hash、source hash、生成文件、native log hash 和启动诊断。

已验证结果：AXIS `2.10.0~pre1` 窗口 `1300x1293`，标题 `AXIS ... on 3axis-tutorial`，LinuxCNC task 正常运行，生成 parameter/position 文件。

## 3. Web/WASM 对标流程

Web loader 固定入口为同一 `3axis-tutorial.ini`：

1. 解析 exact INI 和 `3axis-tutorial.hal`。
2. 获取 `tool.tbl`、共享 intro graphic 和 Vismach Python executable。
3. 对缺失 `3axis-tutorial_mm.var` 生成空 parameter workspace file，并记录 `data_hash`。
4. 将案例 `loadusr -W ./3axis-tutorial` 识别为唯一的 `WEB-EQUIV` Vismach adapter；任意其它 `loadusr` 仍 blocked。
5. 用同一 `trivkins`、3 joints、X/Y/Z 配置启动 Worker。
6. Three.js 使用 Worker 的 joints/pose/toolpath snapshot，不直接运行宿主 Python GUI。

## 4. 功能对标任务

| ID | 任务 | 完成条件 |
|---|---|---|
| `TUTORIAL-00` | 锁定案例和 native runner | native AXIS 可见窗口 verified；exact source/update/generated hashes 有报告 |
| `TUTORIAL-01` | exact resource/INI graph | INI、HAL、tool、var、intro、Vismach executable 路径和 source line 全部可追踪 |
| `TUTORIAL-02` | HAL/Vismach adapter | `3axis-tutorial.hal` 的 loadrt/addf/net/loadusr 通过 Web 等价 adapter；非该程序的宿主 loader 仍 blocked |
| `TUTORIAL-03` | Task startup | Worker 阶段映射到 `TASK_READY`；startup hash 与资源 hash 稳定 |
| `TUTORIAL-04` | 三轴 motion | home、X/Y/Z jog、速度/加速度、limit、following error、trivkins pose/joint 一致 |
| `TUTORIAL-05` | RS-274/MDI | mm units、G90/G91、G0/G1、feed、M2、MDI、pause/resume/step/abort/restart 一致 |
| `TUTORIAL-06` | Tool/IO | `tool.tbl`、prepare/change、source `hal_manualtoolchange.change_button` ACK、spindle/at-speed、冷却、probe、estop/recover 一致 |
| `TUTORIAL-07` | Vismach model | Python model 的 jointX/Y/Z、toollength、tooldiameter pin 语义映射到 Three.js，姿态不跳变 |
| `TUTORIAL-08` | AXIS UI | 菜单、DRO、Manual/MDI、G-code、Preview、jog/home、tool/spindle/coolant/estop、错误和快捷键对标 |
| `TUTORIAL-09` | persistence/recovery | var/tool/position workspace commit、checkpoint、journal、replay、重启恢复无重复副作用 |
| `TUTORIAL-10` | integrated acceptance | native panel、Worker state、Three.js canvas、DOM controls、operation/event/checkpoint hashes 同一操作序列通过 |

每项必须有专项测试、正常/边界/错误样本、source/data hash 和 self-hashed report。不能用 `timeout`、后台 `task:` 或静态 catalog READY 代替真实结果。

## 5. 统一对标操作序列

1. native/Web 启动并确认 AXIS panel / Worker `TASK_READY`。
2. 按源 AXIS 语义依次执行 Z、X、Y individual home，记录 X/Y/Z pose、joint 和 homed 状态。
3. 分别 jog X/Y/Z，记录 position/velocity/limit。
4. 加载并运行 `G21 G90`、`G0 X0 Y0 Z0`、`G1 X10 Y5 F120`、`G1 Z-1`、`M2`。
5. 执行 MDI、pause、resume、step、abort、restart。
6. prepare/change tool 1，启停主轴，等待 at-speed，切换 coolant。
7. 注入 limit、following error、probe 和 ESTOP，检查错误码、禁用控件和 recover。
8. checkpoint 后继续一个 tick，再恢复并比较 endpoint/event/state hash。
9. 退出并重启，比较 var/position/tool workspace state。

## 6. 明确边界

- `3axis-tutorial` Python 模型在 Web 中是源码驱动的 `WEB-EQUIV` Three.js adapter，不运行宿主 Python 进程。
- POSIX fallback 只说明 native 仿真可以运行，不是实时内核或硬件验证。
- AXIS native window 是启动成功必要条件；完整对标仍需功能、流程、界面三层分别通过。
- 其它案例、浏览器矩阵、OPFS 物理崩溃、官方 oracle 和 release acceptance 不在本案例任务范围内。