docs: add axis run process working set

2026-07-07 16:46:39 -04:00
parent 8b6be369ff
commit 39b495cf16
672 changed files with 280923 additions and 59 deletions
--- a/项目分析/AXIS主控制按钮调用链与WASM完善指南.md
+++ b/项目分析/AXIS主控制按钮调用链与WASM完善指南.md
@@ -0,0 +1,929 @@
+# AXIS 主控制按钮调用链与 WASM 完善指南
+
+生成时间：2026-07-07
+
+分析范围：
+
+- LinuxCNC 源码：`/home/mes123456/cnc_wams/linuxcnc`
+- WASM 迁移工程：`/home/mes123456/cnc_wams/wasm-port`
+- Web 5 轴仿真工程：`/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan`
+
+本文重点分析 AXIS 主界面的“急停、上电、Home、执行、暂停、单步执行”的调用链、状态机制、按钮前置条件，以及对 WASM/Web 项目的完善建议。
+
+## 1. 总体架构结论
+
+LinuxCNC 中 AXIS 按钮不是直接操作运动控制，而是走统一命令/状态通道：
+
+```text
+AXIS Python/Tk 按钮
+  -> linuxcnc.command() Python C 扩展
+  -> NML 命令对象 EMC_TASK_*/EMC_JOINT_*
+  -> emcCommand NML 通道
+  -> task 主循环 emcTaskPlan()/emcTaskIssueCommand()
+  -> taskintf.cc 转为 EMCMOT_* motion 命令
+  -> motion 实时侧 command.c/control.c/homing.c
+  -> motion/status + task/status 合成为 emcStatus
+  -> linuxcnc.stat().poll() 供 AXIS 刷新 UI
+```
+
+核心状态不是由按钮自行保存，而是由 `emcStatus` 聚合：
+
+- `emcStatus->task.state`：任务状态，GUI 显示为 `STATE_ESTOP`、`STATE_ESTOP_RESET`、`STATE_ON` 等。
+- `emcStatus->task.mode`：任务模式，`MODE_MANUAL`、`MODE_AUTO`、`MODE_MDI`。
+- `emcStatus->task.interpState`：解释器状态，`INTERP_IDLE`、`INTERP_READING`、`INTERP_PAUSED`、`INTERP_WAITING`。
+- `emcStatus->task.task_paused`：task 层暂停标志。
+- `emcStatus->motion.traj.paused`：motion 轨迹规划器暂停标志。
+- `emcStatus->motion.traj.single_stepping`：task/GUI 可见的单步执行标志。
+- `emcStatus->motion.joint[n].homed`：每个 joint 的回零状态。
+- `emcStatus->motion.traj.enabled`：motion 是否上使能，用于推导 task 是否 `STATE_ON`。
+
+需要特别注意：LinuxCNC 的 task 层主要是 C++，motion 层主要是 C。用户所说的 C++ 实现，在源码中实际跨越 `emctask*.cc`、`taskintf.cc` 和 motion 的 `command.c`、`homing.c`。
+
+## 2. AXIS UI 按钮入口
+
+AXIS 主界面位于：
+
+- `linuxcnc/bin/axis`
+
+关键辅助函数：
+
+```python
+def manual_ok(do_poll=True):
+    if do_poll: s.poll()
+    if s.task_state != linuxcnc.STATE_ON: return False
+    return s.interp_state == linuxcnc.INTERP_IDLE or (
+        s.task_mode == linuxcnc.MODE_MDI and
+        s.queued_mdi_commands < vars.max_queued_mdi_commands.get()
+    )
+
+def ensure_mode(m, *p):
+    s.poll()
+    if s.task_mode == m or s.task_mode in p: return True
+    c.mode(m)
+    c.wait_complete()
+    s.poll()
+    return True
+```
+
+源码位置：`linuxcnc/bin/axis:986-1015`。
+
+这说明 AXIS 侧前置条件分两层：
+
+1. UI 层用 `s.poll()` 读当前状态，避免明显非法操作。
+2. task/motion 层仍会再次校验，非法命令会拒绝或报错。
+
+## 3. Python C 扩展到 NML 命令
+
+AXIS 使用 `linuxcnc.command()`。该对象由 `linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc` 暴露，关键映射如下：
+
+| AXIS 调用 | C 扩展函数 | NML 命令 |
+| --- | --- | --- |
+| `c.state(STATE_*)` | `state()` | `EMC_TASK_SET_STATE` |
+| `c.mode(MODE_*)` | `mode()` | `EMC_TASK_SET_MODE` |
+| `c.home(joint)` | `home()` | `EMC_JOINT_HOME` |
+| `c.auto(AUTO_RUN, line)` | `emcauto()` | `EMC_TASK_PLAN_RUN` |
+| `c.auto(AUTO_PAUSE)` | `emcauto()` | `EMC_TASK_PLAN_PAUSE` |
+| `c.auto(AUTO_RESUME)` | `emcauto()` | `EMC_TASK_PLAN_RESUME` |
+| `c.auto(AUTO_STEP)` | `emcauto()` | `EMC_TASK_PLAN_STEP` |
+
+源码依据：
+
+- `mode()` 创建 `EMC_TASK_SET_MODE`：`linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc:1691-1705`
+- `state()` 创建 `EMC_TASK_SET_STATE`：`linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc:1815-1829`
+- `home()` 创建 `EMC_JOINT_HOME`：`linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc:1941-1945`
+- `emcauto()` 分发 `RUN/PAUSE/RESUME/STEP`：`linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc:2093-2116`
+
+## 4. task 主循环的命令调度
+
+task 主循环在 `linuxcnc/src/emc/task/emctaskmain.cc`：
+
+```text
+emcCommandBuffer->read()
+  -> emcTaskPlan()
+  -> emcTaskExecute()
+  -> emcMotionUpdate(&emcStatus->motion)
+  -> emcTaskUpdate(&emcStatus->task)
+  -> 写 emcStatus 顶层 command/status/echo_serial_number
+```
+
+源码位置：`linuxcnc/src/emc/task/emctaskmain.cc:3301-3478`。
+
+`emcTaskPlan()` 按三类状态进行门禁：
+
+1. `task.state`：`OFF`、`ESTOP`、`ESTOP_RESET`、`ON`
+2. `task.mode`：`MANUAL`、`AUTO`、`MDI`
+3. `task.interpState`：`IDLE`、`READING`、`PAUSED`、`WAITING`
+
+因此，AXIS UI 的按钮条件必须与 `emcTaskPlan()` 的状态表一致，不能只看 `runState` 这类 Web 自定义状态。
+
+## 5. 急停按钮
+
+### 5.1 AXIS UI 调用链
+
+源码：`linuxcnc/bin/axis:2243-2248`
+
+```python
+def estop_clicked(event=None):
+    s.poll()
+    if s.task_state == linuxcnc.STATE_ESTOP:
+        c.state(linuxcnc.STATE_ESTOP_RESET)
+    else:
+        c.state(linuxcnc.STATE_ESTOP)
+```
+
+按钮语义：
+
+- 当前是 `STATE_ESTOP`：发送 `STATE_ESTOP_RESET`，表示解除急停。
+- 其他任意状态：发送 `STATE_ESTOP`，进入急停。
+
+### 5.2 NML/task 调用链
+
+```text
+c.state(STATE_ESTOP or STATE_ESTOP_RESET)
+  -> emcmodule.cc state()
+  -> EMC_TASK_SET_STATE
+  -> emcTaskPlan()
+  -> emcTaskIssueCommand()
+  -> emcTaskSetState()
+```
+
+`EMC_TASK_SET_STATE` 被 task 作为 immediate command 接收：
+
+- 非 ON 状态也允许接收：`emctaskmain.cc:795-829`
+- ON/MANUAL 允许：`emctaskmain.cc:897-956`
+- ON/AUTO/IDLE 允许：`emctaskmain.cc:1026-1075`
+- ON/AUTO/READING 允许：`emctaskmain.cc:1137-1174`
+- ON/AUTO/PAUSED 允许：`emctaskmain.cc:1206-1251`
+
+### 5.3 C++ task 状态处理
+
+`emcTaskSetState(ESTOP)` 源码：`linuxcnc/src/emc/task/emctask.cc:353-365`
+
+执行内容：
+
+- `emcMotionAbort()`：中止 motion。
+- `emcSpindleAbort()`：中止主轴。
+- `emcAuxEstopOn()`：IO 急停输出置位。
+- `emcTrajDisable()`：下发 motion disable。
+- 关闭 flood coolant。
+- `emcTaskAbort()`：清解释器队列、清 pause/step 状态。
+- `emcIoAbort(TASK_STATE_ESTOP)`。
+- `emcJointUnhome(-2)`：清除 `VOLATILE_HOME` joint 的 homed。
+- `emcTaskPlanSynch()`：同步解释器。
+
+`emcTaskSetState(ESTOP_RESET)` 源码：`linuxcnc/src/emc/task/emctask.cc:342-350`
+
+执行内容：
+
+- `emcAuxEstopOff()`：解除 IO 急停。
+- `emcTaskAbort()`：清程序运行状态。
+- `emcIoAbort(TASK_STATE_ESTOP_RESET)`。
+- `emcSpindleAbort()`。
+- `emcTaskPlanSynch()`。
+
+### 5.4 状态记录方式
+
+task 并不简单把 `task.state = ESTOP` 固定写死，而是周期性通过 `determineState()` 从 IO 和 motion 推导：
+
+源码：`linuxcnc/src/emc/task/emctask.cc:418-428`
+
+规则：
+
+| IO 急停 | motion enabled | 推导状态 |
+| --- | --- | --- |
+| true | 任意 | `ESTOP` |
+| false | false | `ESTOP_RESET` |
+| false | true | `ON` |
+
+`emcTaskUpdate()` 每周期写入 `stat->state`：`linuxcnc/src/emc/task/emctask.cc:688-699`。
+
+这意味着 Web/WASM 中不能只维护一个 `estopActive` 布尔值；应该同时维护：
+
+- IO estop 状态；
+- motion enable 状态；
+- task 推导状态；
+- volatile home 清除动作。
+
+## 6. 上电/下电按钮
+
+### 6.1 AXIS UI 调用链
+
+源码：`linuxcnc/bin/axis:2250-2260`
+
+```python
+def onoff_clicked(event=None):
+    s.poll()
+    if s.task_state == linuxcnc.STATE_ESTOP_RESET:
+        c.state(linuxcnc.STATE_ON)
+        ...
+    else:
+        c.state(linuxcnc.STATE_OFF)
+```
+
+按钮语义：
+
+- 只有 `STATE_ESTOP_RESET` 才能上电。
+- 其他状态一律发送 `STATE_OFF`。
+- 因此 `STATE_ESTOP` 下点电源不是“上电”，而是进入 OFF/保持不可上电语义；必须先通过急停按钮解除急停到 `ESTOP_RESET`。
+
+### 6.2 task 调用链
+
+```text
+c.state(STATE_ON/OFF)
+  -> EMC_TASK_SET_STATE
+  -> emcTaskSetState(ON/OFF)
+```
+
+`emcTaskSetState(ON)` 源码：`linuxcnc/src/emc/task/emctask.cc:336-340`
+
+执行内容：
+
+- `emcTrajEnable()`。
+- 关闭 flood coolant。
+
+`emcTrajEnable()` 源码：`linuxcnc/src/emc/task/taskintf.cc:1396-1400`
+
+```text
+emcTrajEnable()
+  -> emcmotCommand.command = EMCMOT_ENABLE
+  -> usrmotWriteEmcmotCommand()
+```
+
+motion 侧 `EMCMOT_ENABLE` 源码：`linuxcnc/src/emc/motion/command.c:1370-1384`
+
+执行内容：
+
+- 如果 HAL `motion.enable` 输入为 false，报错：`can't enable motion, enable input is false`。
+- 否则设置 `emcmotInternal->enabling = 1`，实际使能在 motion 控制周期中完成。
+
+`emcTaskSetState(OFF)` 源码：`linuxcnc/src/emc/task/emctask.cc:323-333`
+
+执行内容：
+
+- `emcMotionAbort()`。
+- `emcSpindleAbort()`。
+- `emcTrajDisable()`。
+- `emcIoAbort(TASK_STATE_OFF)`。
+- `emcTaskAbort()`。
+- `emcJointUnhome(-2)` 清 volatile home。
+- `emcTaskPlanSynch()`。
+
+motion 侧 `EMCMOT_DISABLE` 源码：`linuxcnc/src/emc/motion/command.c:1357-1368`
+
+执行内容：
+
+- 设置 `emcmotInternal->enabling = 0`。
+- 对 inverse-only kinematics，还会退出 teleop/coord。
+
+### 6.3 状态记录方式
+
+上电后并不是由 task 直接写 `STATE_ON`，而是 motion 报告 enabled 后，`determineState()` 推导为 `ON`。
+
+motion 状态更新路径：
+
+```text
+motion command/control 周期更新 emcmotStatus.motionFlag
+  -> taskintf.cc emcMotionUpdate()
+  -> emcTrajUpdate()
+  -> stat->traj.enabled
+  -> emcTaskUpdate()
+  -> determineState()
+```
+
+关键源码：
+
+- `emcMotionUpdate()` 读取 `emcmotStatus`：`linuxcnc/src/emc/task/taskintf.cc:2057-2102`
+- `emcTrajUpdate()` 写 `stat->enabled`：`linuxcnc/src/emc/task/taskintf.cc:1639-1652`
+- `determineState()` 推导状态：`linuxcnc/src/emc/task/emctask.cc:418-428`
+
+## 7. Home 按钮
+
+### 7.1 AXIS UI 调用链
+
+Home All 源码：`linuxcnc/bin/axis:2732-2740`
+
+```python
+def home_all_joints(event=None):
+    if not manual_ok(): return
+    ensure_mode(linuxcnc.MODE_MANUAL)
+    ...
+    go_home(-1)
+```
+
+单 joint Home 源码：`linuxcnc/bin/axis:2747-2767`
+
+关键条件：
+
+- `manual_ok()` 必须为真，即 machine 为 `STATE_ON`，解释器 idle 或 MDI 队列可接受。
+- 切到 `MODE_MANUAL`。
+- 已 homed 时弹窗确认是否 re-home。
+- 非 identity kinematics 下，单轴/单 joint 选择有额外限制。
+- 最终 `go_home(num)` 调 `c.home(num)`。
+
+### 7.2 NML/task/motion 调用链
+
+```text
+c.home(-1 或 joint)
+  -> emcmodule.cc home()
+  -> EMC_JOINT_HOME
+  -> emcTaskPlan()
+  -> emcTaskIssueCommand()
+  -> emcJointHome()
+  -> EMCMOT_JOINT_HOME
+  -> motion command.c
+  -> do_home_joint()
+  -> homing.c 状态机
+```
+
+`EMC_JOINT_HOME` 只在 ON/MANUAL 中直接允许：`linuxcnc/src/emc/task/emctaskmain.cc:897-956`。
+
+`emcJointHome()` 源码：`linuxcnc/src/emc/task/taskintf.cc:796-805`
+
+执行内容：
+
+- 检查 joint 范围。
+- 下发 `EMCMOT_JOINT_HOME`。
+
+motion 侧 `EMCMOT_JOINT_HOME` 源码：`linuxcnc/src/emc/motion/command.c:1411-1439`
+
+motion 前置条件：
+
+- `emcmotStatus->motion_state == EMCMOT_MOTION_FREE`，必须处于 joint/free 模式。
+- `motion.homing-inhibit` 不能为 true。
+- 当前不能已有 homing 流程在跑。
+- `GET_MOTION_ENABLE_FLAG()` 必须为 true。
+- 负 joint 表示 home all。
+
+### 7.3 homing 状态机
+
+`do_home_joint()` 最终进入 `linuxcnc/src/emc/motion/homing.c`。
+
+核心状态记录：
+
+- `H[joint].homing`
+- `H[joint].homed`
+- `H[joint].home_state`
+- `H[joint].joint_in_sequence`
+- `joint.free_tp.enable`
+
+输出 HAL pin：
+
+源码：`linuxcnc/src/emc/motion/homing.c:541-573`
+
+- `joint.N.homing`
+- `joint.N.homed`
+- `joint.N.home-state`
+- `joint.N.index-enable`
+
+完成逻辑：
+
+源码：`linuxcnc/src/emc/motion/homing.c:1376-1385`
+
+- `homing = 0`
+- `homed = 1`
+- `home_state = HOME_IDLE`
+- `joint_in_sequence = 0`
+
+异常中止：
+
+源码：`linuxcnc/src/emc/motion/homing.c:1387-1397`
+
+- 所有 joint `homing = 0`
+- 所有 joint `homed = 0`
+- 所有 `free_tp.enable = 0`
+- `home_state = HOME_IDLE`
+
+### 7.4 状态记录方式
+
+task 通过 `emcMotionUpdate()` 将 motion homed 状态复制到 `emcStatus->motion.joint[n].homed`，AXIS 的 `s.homed[n]` 来自这里。
+
+`task` 的 `all_homed()` 直接查 `emcStatus->motion.joint[i].homed`，源码：`linuxcnc/src/emc/task/emctaskmain.cc:151-152`。
+
+## 8. 执行 Run 按钮
+
+### 8.1 AXIS UI 调用链
+
+源码：`linuxcnc/bin/axis:2379-2393`
+
+```python
+def task_run(*event):
+    res = run_warn()
+    ...
+    ensure_mode(linuxcnc.MODE_AUTO)
+    c.auto(linuxcnc.AUTO_RUN, program_start_line)
+    program_start_line = 0
+```
+
+AXIS UI 层条件：
+
+- 会执行 `run_warn()`，处理文件变更、保存、运行前警告等。
+- `ensure_mode(MODE_AUTO)` 切入 AUTO。
+- 然后发送 `AUTO_RUN`。
+
+真正硬条件在 task 层：
+
+- machine 必须 ON。
+- AUTO 模式下允许。
+- 未 homed 且没有 `no_force_homing` 时拒绝。
+- 程序文件应已打开；未打开时会尝试打开 `emcStatus->task.file`。
+
+### 8.2 task 调用链
+
+```text
+c.auto(AUTO_RUN, line)
+  -> EMC_TASK_PLAN_RUN
+  -> emcTaskPlan() 按状态门禁
+  -> emcTaskIssueCommand()
+  -> case EMC_TASK_PLAN_RUN
+```
+
+`EMC_TASK_PLAN_RUN` 在 ON/AUTO/IDLE 中允许：`linuxcnc/src/emc/task/emctaskmain.cc:1015-1075`。
+
+核心处理源码：`linuxcnc/src/emc/task/emctaskmain.cc:2318-2335`
+
+执行内容：
+
+- 如果未 homed 且 `!no_force_homing`，报错：`Can't run a program when not homed`。
+- 清 `motion.traj.single_stepping`。
+- 清 `stepping`、`steppingWait`。
+- 必要时 `emcTaskPlanOpen(emcStatus->task.file)`。
+- 记录 `programStartLine = run_msg->line`。
+- 设置 `emcStatus->task.interpState = READING`。
+- 设置 `emcStatus->task.task_paused = 0`。
+
+### 8.3 解释器和 motion 下发
+
+Run 后 `emcTaskPlan()` 进入 `READING`，周期性调用 readahead 逻辑读取 G-code。解释器通过 canonical 函数把运动命令排入 `interp_list`，`emcTaskExecute()` 再把 motion 命令下发到 motion。
+
+运动命令如直线/圆弧最终在 motion `command.c` 中以 `EMCMOT_SET_LINE`、`EMCMOT_SET_CIRCLE` 等处理。运动状态通过 `emcmotStatus.id`、`depth`、`activeDepth`、`paused`、`current_vel` 等回传。
+
+### 8.4 状态记录方式
+
+Run 后主要状态变化：
+
+| 字段 | 变化 |
+| --- | --- |
+| `task.mode` | `AUTO` |
+| `task.interpState` | `READING` |
+| `task.task_paused` | `0` |
+| `motion.traj.single_stepping` | `0` |
+| `motion.traj.queue/activeQueue` | 随 motion 队列变化 |
+| `motion.traj.id/tag` | 跟随当前运动段与源代码 state tag |
+
+`emcStatus->task.status` 顶层状态由 `emctaskmain.cc:3458-3476` 合成：有错误为 `ERROR`，全部完成且解释器 idle 为 `DONE`，否则为 `EXEC`。
+
+## 9. 暂停 Pause 按钮
+
+### 9.1 AXIS UI 调用链
+
+源码：`linuxcnc/bin/axis:2402-2406`
+
+```python
+def task_pause(*event):
+    if s.task_mode != linuxcnc.MODE_AUTO or s.interp_state not in (
+        linuxcnc.INTERP_READING,
+        linuxcnc.INTERP_WAITING
+    ):
+        return
+    ensure_mode(linuxcnc.MODE_AUTO)
+    c.auto(linuxcnc.AUTO_PAUSE)
+```
+
+AXIS Pause 的严格条件：
+
+- `task_mode == MODE_AUTO`
+- `interp_state in (INTERP_READING, INTERP_WAITING)`
+- 不是仅凭 `runState == running`
+
+工具栏合并暂停/恢复 `task_pauseresume()` 源码：`linuxcnc/bin/axis:2433-2443`
+
+- 仅 `MODE_AUTO` 或 `MODE_MDI` 可操作。
+- 如果 `s.paused` 为真，发送 resume。
+- 否则如果解释器不是 idle，发送 pause。
+
+### 9.2 task/motion 调用链
+
+```text
+c.auto(AUTO_PAUSE)
+  -> EMC_TASK_PLAN_PAUSE
+  -> emcTaskPlan()
+  -> emcTaskIssueCommand()
+  -> emcTrajPause()
+  -> EMCMOT_PAUSE
+  -> tpPause()
+```
+
+task 处理源码：`linuxcnc/src/emc/task/emctaskmain.cc:2337-2345`
+
+执行内容：
+
+- `emcTrajPause()`
+- 若当前不是 `PAUSED`，保存 `interpResumeState = interpState`
+- `task.interpState = PAUSED`
+- `task.task_paused = 1`
+
+`emcTrajPause()` 源码：`linuxcnc/src/emc/task/taskintf.cc:1417-1421`
+
+motion 侧 `EMCMOT_PAUSE` 源码：`linuxcnc/src/emc/motion/command.c:1234-1240`
+
+执行内容：
+
+- `tpPause(&coord_tp)`
+- `emcmotStatus->paused = 1`
+
+### 9.3 状态记录方式
+
+Pause 后必须同时体现：
+
+- `task.interpState = PAUSED`
+- `task.task_paused = 1`
+- `motion.traj.paused = 1`
+- `interpResumeState` 保存暂停前的 `READING` 或 `WAITING`
+
+Web 项目必须避免只改 UI `runState = paused`，否则 resume/step 会缺少 LinuxCNC 必需的恢复上下文。
+
+## 10. 单步 Step 按钮
+
+### 10.1 AXIS UI 调用链
+
+源码：`linuxcnc/bin/axis:2395-2400`
+
+```python
+def task_step(*event):
+    if s.task_mode != linuxcnc.MODE_AUTO or s.interp_state != linuxcnc.INTERP_IDLE:
+        o.set_highlight_line(None)
+        if run_warn(): return
+    ensure_mode(linuxcnc.MODE_AUTO)
+    c.auto(linuxcnc.AUTO_STEP)
+```
+
+AXIS Step 的含义不是“前端播放下一帧”，而是向 task 发送 `EMC_TASK_PLAN_STEP`。task 根据解释器状态决定：
+
+- AUTO/IDLE：先启动程序，再立刻暂停，进入单步准备态。
+- AUTO/READING 或 WAITING：设置 single stepping，下一段读入/执行后停住。
+- AUTO/PAUSED：若 motion 队列中有暂停运动，发 `EMCMOT_STEP` 让 motion 走到下一段；否则恢复解释器状态继续读。
+
+### 10.2 task 处理
+
+AUTO/IDLE 中 `STEP` 源码：`linuxcnc/src/emc/task/emctaskmain.cc:1078-1091`
+
+执行内容：
+
+- 构造 `taskPlanRunCmd.line = 0`
+- 调 `emcTaskIssueCommand(&taskPlanRunCmd)` 启动程序
+- `emcTrajPause()`
+- 保存 `interpResumeState`
+- `task.interpState = PAUSED`
+- `task.task_paused = 1`
+
+AUTO/READING 中 `STEP` 源码：`linuxcnc/src/emc/task/emctaskmain.cc:1178-1182`
+
+执行内容：
+
+- `motion.traj.single_stepping = 1`
+- `stepping = 1`
+- `steppingWait = 0`
+
+AUTO/PAUSED 中 `STEP` 源码：`linuxcnc/src/emc/task/emctaskmain.cc:1254-1266`
+
+执行内容：
+
+- `motion.traj.single_stepping = 1`
+- `stepping = 1`
+- 如果 `motion.traj.paused && queue > 0`，调用 `emcTrajStep()`
+- 否则 `task.interpState = interpResumeState`
+- `task.task_paused = 1`
+
+AUTO/WAITING 中 `STEP` 源码：`linuxcnc/src/emc/task/emctaskmain.cc:1330-1334`
+
+执行内容同 READING：设置单步标志。
+
+### 10.3 motion 处理
+
+`emcTrajStep()` 源码：`linuxcnc/src/emc/task/taskintf.cc:1438-1442`
+
+motion 侧 `EMCMOT_STEP` 源码：`linuxcnc/src/emc/motion/command.c:1265-1273`
+
+处理逻辑：
+
+- 如果 motion 当前 paused：
+  - 记录 `idForStep = emcmotStatus->id`
+  - `emcmotStatus->stepping = 1`
+  - resume 轨迹规划器，使其执行到 id 变化或下一步边界再停。
+
+### 10.4 状态记录方式
+
+单步相关字段：
+
+- task 侧静态变量：`stepping`、`steppingWait`
+- task 可见状态：`emcStatus->motion.traj.single_stepping`
+- motion 状态：`emcmotStatus->stepping`、`idForStep`、`paused`
+- 解释器状态：`PAUSED` 或恢复到 `interpResumeState`
+
+Web 中若只实现“数组 frameIndex++”，不能等价于 LinuxCNC Step。正确做法是把 Step 作为 task 命令，驱动 task/motion 的 pause/step 状态机。
+
+## 11. Resume 补充
+
+虽然用户重点列出“急停、上电、Home、执行、暂停、单步执行”，但暂停机制必须包含 Resume 才完整。
+
+AXIS `task_resume()` 源码：`linuxcnc/bin/axis:2424-2431`
+
+条件：
+
+- `s.paused` 为真。
+- `task_mode` 是 `AUTO` 或 `MDI`。
+- 发送 `AUTO_RESUME`。
+
+task 处理源码：`linuxcnc/src/emc/task/emctaskmain.cc:2369-2376`
+
+执行内容：
+
+- `emcTrajResume()`
+- `task.interpState = interpResumeState`
+- `task.task_paused = 0`
+- `motion.traj.single_stepping = 0`
+- 清 `stepping`、`steppingWait`
+
+motion 侧 `EMCMOT_RESUME` 源码：`linuxcnc/src/emc/motion/command.c:1256-1263`
+
+执行内容：
+
+- `emcmotStatus->stepping = 0`
+- `tpResume()`
+- `emcmotStatus->paused = 0`
+
+## 12. 按钮前置条件汇总
+
+| 按钮 | AXIS UI 前置条件 | task/motion 硬条件 | 执行后状态 |
+| --- | --- | --- | --- |
+| 急停 | 无；读 `s.task_state` 决定 reset 或 estop | `EMC_TASK_SET_STATE` 在多数状态允许 | `ESTOP` 分支 abort、disable、IO estop on；reset 分支 IO estop off、abort、同步解释器 |
+| 上电 | 只有 `STATE_ESTOP_RESET` 发送 ON，否则发送 OFF | ON 要 motion enable 输入为真；OFF 总是 abort/disable | ON 后由 `motion.traj.enabled` 推导 `STATE_ON`；OFF 后推导 `ESTOP_RESET` 或 OFF 语义并清 volatile home |
+| Home | `manual_ok()`；切 `MODE_MANUAL`；必要时 re-home 确认 | motion 必须 FREE、enabled、未 homing、未 inhibit | `joint.N.homing` 过程态；完成 `joint.N.homed=1`；失败清 homed |
+| Run | `run_warn()`；切 `MODE_AUTO` | ON/AUTO/IDLE；已 homed 或 no_force_homing；程序打开 | `interpState=READING`，`task_paused=0`，motion 队列开始增长 |
+| Pause | `MODE_AUTO` 且 `INTERP_READING/WAITING` | `EMC_TASK_PLAN_PAUSE`；motion `EMCMOT_PAUSE` | `interpState=PAUSED`，`task_paused=1`，`motion.paused=1`，保存 resume state |
+| Step | 切 `MODE_AUTO`；非 idle 时可先 run_warn | 按 AUTO/IDLE/READING/PAUSED/WAITING 分支处理 | 设置 `single_stepping`；必要时 `EMCMOT_STEP`；保持/进入 paused |
+| Resume | `paused` 且 `MODE_AUTO/MDI` | `EMC_TASK_PLAN_RESUME`；motion `EMCMOT_RESUME` | 恢复 `interpResumeState`，清 `task_paused/single_stepping/stepping` |
+
+## 13. WASM-port 完善建议
+
+当前 `wasm-port` 已有 task/HAL WASM 入口：
+
+- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
+- `wasm-port/runtime/sdk/src/linuxcnc-task-hal.js`
+
+但是 `linuxcnc_task_hal_wasm.cpp` 仍是 `linuxcnc_task_motion_hal_wasm_phase4_minimal`，存在明显过渡实现：
+
+- 用字符串搜索和手写 JSON 解析命令。
+- 自己维护 `TaskRuntime.state/mode/interp_state/task_paused/single_stepping`。
+- 从 G-code 文本中用简单规则派生 motion，存在 G-code 语义重实现风险。
+- `readiness()` 中仍标记 `nativeTaskReady:false`、`nativeHalSyncReady:false`。
+
+这与 `wasm-port/AGENTS.md` 的要求冲突风险较高：项目应复用 LinuxCNC source，不应扩展项目自写 CNC 语义。
+
+建议按以下阶段完善。
+
+### 13.1 第一阶段：把状态枚举和门禁表固化为 LinuxCNC 镜像
+
+目标：先不改大架构，但移除随意字符串状态。
+
+建议：
+
+1. 在 `runtime/core/linuxcnc_wrap` 增加 task 状态模型头文件，例如 `linuxcnc_task_state_model.hh`。
+2. 用与 LinuxCNC 一致的枚举名：`ESTOP`、`ESTOP_RESET`、`ON`、`MANUAL`、`AUTO`、`MDI`、`IDLE`、`READING`、`PAUSED`、`WAITING`。
+3. 实现一个 `task_accepts_command(state, mode, interp, command)`，逐项映射 `emcTaskPlan()` 的允许表。
+4. 所有 `lctask_send_command_json()` 先走该门禁表，返回明确错误码和错误文本。
+5. 增加测试覆盖：
+   - ESTOP 下仅允许 state/mode/config 等 immediate 命令。
+   - ON/MANUAL 下允许 HOME，不允许 AUTO RUN。
+   - ON/AUTO/IDLE 下允许 RUN/STEP。
+   - ON/AUTO/READING 下允许 PAUSE/STEP，不允许 HOME。
+   - ON/AUTO/PAUSED 下允许 RESUME/STEP。
+
+### 13.2 第二阶段：替换手写 G-code motion 派生
+
+当前 `enqueue_linear_move_from_line()` 和 Web 侧 `buildSourceLineMotionSegments()` 都会从 G-code 行解析轴和 feed，这属于语义漂移高风险点。
+
+正确方向：
+
+1. G-code 到 canonical motion 必须由 vendored LinuxCNC interpreter 产生。
+2. task/HAL runtime 只消费 LinuxCNC canonical 输出或已验证的 motion plan，不自行解释 G-code。
+3. 对没有 motion plan 的程序，应返回“需要 interpreter plan”错误，而不是 fallback 解析 `G0/G1`。
+4. `buildTaskHalProgramMotionPlan()` 可保留为 host 边界适配器，但输入必须来自 LinuxCNC interpreter runtime 的 canonical events，而不是源码行正则解析。
+
+### 13.3 第三阶段：引入 vendored task/motion 源码闭环
+
+最终目标不是仿照 `emctaskmain.cc` 写一份 JS/C++ 状态机，而是逐步把 vendored LinuxCNC task/motion 代码纳入 WASM：
+
+1. 将 `emc/nml_intf/emc_nml.hh` 中的命令/状态结构作为 WASM 内部 ABI 参考。
+2. 用内存队列替代 NML transport，但保留 `EMC_TASK_*` / `EMCMOT_*` 命令类型。
+3. 将 `taskintf.cc` 的 `emcTrajEnable/Pause/Resume/Step/Home` 路由接到 `linuxcnc_motion_runtime.c`。
+4. 将 `emcTaskSetState()`、`emcTaskSetMode()`、`emcTaskAbort()` 的语义直接迁移或编译进 WASM。
+5. motion runtime 应逐步引入 `command.c`、`homing.c`、`control.c` 中真实状态更新，而不是只暴露“看起来相同”的 JSON status。
+
+### 13.4 第四阶段：状态发布完全对齐 `emcStatus`
+
+WASM SDK `readStatus()` 应输出与 Python `linuxcnc.stat()` 结构同构的字段：
+
+- `task.state`
+- `task.mode`
+- `task.interpState`
+- `task.execState`
+- `task.taskPaused`
+- `motion.traj.enabled`
+- `motion.traj.paused`
+- `motion.traj.singleStepping`
+- `motion.traj.queue`
+- `motion.traj.id`
+- `motion.joint[n].homed`
+- `motion.joint[n].homing`
+- `motion.joint[n].homeState`
+- `echoSerialNumber`
+- `commandType`
+
+这样 Web 项目可以直接消费 LinuxCNC 状态，而不是维护第二套状态。
+
+## 14. web-rtcp-5axis-xyzbc-trt-sim-plan 完善建议
+
+当前 Web 项目已有：
+
+- `app/src/state/linuxcnc-task-policy.js`
+- `app/src/state/store.js`
+- `app/src/runtime/linuxcnc-task-hal-runtime.js`
+- browser/node 对按钮路径的验证
+
+这已经完成一部分 AXIS 对标，但还需要继续收敛。
+
+### 14.1 状态源优先级必须调整
+
+建议状态优先级：
+
+```text
+taskHalStatus.ui/task/motion 原生状态
+  > LinuxCNC interpreter canonical events
+  > Web UI 派生状态
+```
+
+Web store 中 `machine.taskState/mode/interpState/runState` 应逐渐变成 task/HAL 状态的投影，而不是独立真相源。
+
+### 14.2 按钮 action 应发送 LinuxCNC 命令，不直接改业务状态
+
+按钮处理建议统一为：
+
+```text
+UI click
+  -> gateLinuxCncTaskAction()
+  -> taskHalRuntime.sendCommand({ type: "EMC_TASK_*" })
+  -> taskHalRuntime.runCycles()
+  -> taskHalRuntime.readStatus()
+  -> store 接收 STATUS_SYNC
+  -> UI 渲染
+```
+
+避免：
+
+- click 后直接 `runState = "running"`；
+- click 后直接 `machine.allHomed = true`；
+- pause/step 直接操作播放帧；
+- power 直接改 `powerOn` 而不等 motion enabled/status。
+
+### 14.3 补齐 Home 状态过程态
+
+Web 当前常见实现是 `HOME` 后立即 `allHomed=true`。LinuxCNC 真实机制是：
+
+```text
+EMC_JOINT_HOME
+  -> joint.N.homing = true
+  -> home_state 多阶段变化
+  -> joint.N.homed = true
+```
+
+建议 Web 状态增加：
+
+- `machine.joints[n].homing`
+- `machine.joints[n].homed`
+- `machine.joints[n].homeState`
+- `machine.homingActive`
+- `machine.allHomed`
+
+按钮门禁：
+
+- homing 过程中禁止再次 Home。
+- Run 前使用 `allHomed || noForceHoming`。
+- OFF/ESTOP 时清 volatile home，而不是无条件清所有 home；如果当前模型无法区分 volatile，先在文档和状态字段中标注“volatile home 简化”。
+
+### 14.4 补齐 Step 的 LinuxCNC 语义
+
+Web 需要区分三种 Step：
+
+1. 程序 idle 首次 step：等价于 RUN 后立即 PAUSE。
+2. 程序 running 中 step：设置 single stepping，等待下一段边界停住。
+3. 程序 paused 中 step：若 motion queue 有内容，发送 motion step；否则恢复 interpreter 读下一段。
+
+建议在 `linuxcnc-task-policy.js` 中把 `STEP` 门禁拆开：
+
+- `canStepFromIdle`
+- `canStepWhileReading`
+- `canStepWhilePaused`
+- `canStepWhileWaiting`
+
+并在 status 中显示：
+
+- `task.singleStepping`
+- `motion.stepping`
+- `motion.idForStep`
+- `motion.paused`
+
+### 14.5 Pause/Resume 继续保持 AXIS 门禁
+
+已完成的严格对标应继续保留：
+
+- `PAUSE`：仅 `STATE_ON + MODE_AUTO + INTERP_READING/WAITING`。
+- `PAUSE_RESUME`：仅 `MODE_AUTO/MDI`；paused 时 resume；非 idle 时 pause。
+- `RESUME`：必须 `paused && MODE_AUTO/MDI`。
+
+后续测试不要只断言按钮可点击，应断言 task/HAL status：
+
+- pause 后 `task.interpState=PAUSED`
+- pause 后 `task.taskPaused=true`
+- pause 后 `motion.paused=true`
+- resume 后恢复 `interpResumeState`
+- step 后 `singleStepping=true`
+
+### 14.6 5 轴 XYZBC-TRT 特有要求
+
+5 轴仿真不应把主按钮逻辑和 RTCP/kinematics 逻辑混在一起。建议分层：
+
+1. task/motion 状态机：只负责开关机、home、run、pause、step。
+2. kinematics/RTCP：只负责 XYZBC-TRT 位置变换和 TCP 显示。
+3. interpreter/remap：负责 M428/M429/M430、switchkins、G-code 语义。
+4. UI：只渲染状态并发送命令。
+
+Run 前置条件除 LinuxCNC 通用条件外，还应检查：
+
+- 选定 profile 的 INI 已加载；
+- machine files 已 staged；
+- 当前 G-code 已 open 到 task/HAL session；
+- kinematics runtime 与 task/HAL runtime readiness 均为 true；
+- 如果程序依赖 switchkins/remap，HAL `motion.switchkins-type` 同步状态应可观测。
+
+## 15. 推荐验证矩阵
+
+### 15.1 LinuxCNC 行为矩阵
+
+用本地 LinuxCNC 源码为基准建立 golden matrix：
+
+| 初始状态 | 命令 | 期望 |
+| --- | --- | --- |
+| ESTOP/MANUAL/IDLE | ESTOP button | `STATE_ESTOP_RESET` |
+| ESTOP_RESET/MANUAL/IDLE | Power | `STATE_ON` |
+| ESTOP/MANUAL/IDLE | Power | 不上电，走 OFF 分支 |
+| ON/MANUAL/IDLE | Home All | `joint.*.homing -> homed` |
+| ON/AUTO/IDLE + unhomed | Run | 拒绝，提示未 homed |
+| ON/AUTO/IDLE + homed | Run | `interpState=READING` |
+| ON/AUTO/READING | Pause | `interpState=PAUSED`、`motion.paused=true` |
+| ON/AUTO/PAUSED | Resume | 恢复 reading/waiting |
+| ON/AUTO/IDLE + homed | Step | run + pause，single step 准备 |
+| ON/AUTO/PAUSED + queue>0 | Step | `EMCMOT_STEP`，执行下一段后停 |
+
+### 15.2 wasm-port 测试建议
+
+新增或扩展：
+
+- `tests/wasm/node/verify_task_state_matrix.mjs`
+- `tests/wasm/node/verify_task_home_state_machine.mjs`
+- `tests/wasm/node/verify_task_pause_resume_step.mjs`
+
+每个测试不要只看返回码，要读 `lctask_read_status_json()`：
+
+- task 字段；
+- motion 字段；
+- HAL pins；
+- events；
+- command echo。
+
+### 15.3 Web 测试建议
+
+在现有 `verify_xyzbc_trt_web_app.mjs` 和 browser smoke 上补齐：
+
+- ESTOP/RESET/POWER 不允许绕过；
+- Home 有过程态；
+- Run 未 homed 拒绝；
+- Pause idle 拒绝；
+- Pause manual 拒绝；
+- Step idle 首次启动后暂停；
+- Step paused 推进一段；
+- Resume 清 single stepping；
+- Store 状态与 taskHalStatus 一致。
+
+## 16. 实施优先级
+
+建议按以下顺序推进：
+
+1. `wasm-port` 先消除 task/HAL runtime 中的 G-code 正则解析 fallback，要求 motion plan 必须来自 LinuxCNC interpreter canonical output。
+2. `wasm-port` 把 `lctask_send_command_json()` 改为显式命令结构解析和 LinuxCNC 状态门禁表。
+3. `wasm-port` 补齐 `task/motion/joint` 状态字段，使 `readStatus()` 接近 `linuxcnc.stat()`。
+4. Web store 改为 taskHalStatus 投影源，减少直接改 `runState/machine` 的分支。
+5. Web Home/Step 加过程态和真实 task/motion 状态断言。
+6. 再继续推进 vendored `emctask.cc/taskintf.cc/command.c/homing.c` 的更直接编译或等价适配。
+
+最终目标：Web 按钮只是 AXIS 的浏览器外壳，状态机和 CNC 语义来自 LinuxCNC 源码或其受控 WASM 适配层。