# 01-项目功能内容

## 项目目标

完善 `/home/mes123456/cnc_wams/wasm-port` 中 LinuxCNC WASM task/motion 暂停能力，使 `/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan` 的 AXIS 风格暂停按钮具备真实 LinuxCNC 语义。

最终用户可见目标：

1. 运行中点击工具栏暂停按钮，程序进入暂停。
2. 暂停时 G-code 解释器不继续读行，运动采样不继续推进。
3. 暂停时 DRO、刀具位置、TCP、canvas toolhead、当前行和速度保持稳定。
4. 暂停中再次点击同一按钮，按 AXIS `task_pauseresume` 语义恢复。
5. 菜单 Pause 与 Resume 保持分离语义，不能被工具栏 toggle 逻辑污染。

## LinuxCNC 对标依据

来源文档：

`/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/doc/AXIS暂停按钮LinuxCNC调用链分析.md`

核心调用链：

```text
AXIS toolbar task_pauseresume
  -> linuxcnc.command().auto(AUTO_PAUSE/AUTO_RESUME)
    -> EMC_TASK_PLAN_PAUSE / EMC_TASK_PLAN_RESUME
      -> emcTrajPause() / emcTrajResume()
        -> EMCMOT_PAUSE / EMCMOT_RESUME
          -> tpPause() / tpResume()
```

核心语义：

1. `EMC_TASK_PLAN_PAUSE`：
   - 调用 `emcTrajPause()`；
   - 如果当前解释器不是 `PAUSED`，保存 `interpResumeState`；
   - 设置 `interpState = PAUSED`；
   - 设置 `task_paused = 1`。
2. `EMC_TASK_PLAN_RESUME`：
   - 调用 `emcTrajResume()`；
   - 恢复 `interpState = interpResumeState`；
   - 设置 `task_paused = 0`；
   - 清理 single stepping 状态。
3. `EMCMOT_PAUSE`：
   - 调用 `tpPause()`；
   - 设置 motion paused 状态。
4. `EMCMOT_RESUME`：
   - 调用 `tpResume()`；
   - 清除 motion paused 状态。
5. 暂停后 `emcTaskExecute()` 不继续从 interpreter list 取新命令。

## 当前代码基线

### wasm-port 已有基础

已存在文件：

- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_tp_wasm.c`
- `wasm-port/runtime/sdk/src/linuxcnc-task-hal.js`
- `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs`
- `wasm-port/tests/wasm/node/verify_tp_wasm.mjs`

当前已有能力：

- `EMC_TASK_PLAN_PAUSE` 会设置 `interpState=PAUSED`、`taskPaused=true`，并转发 `EMC_TRAJ_PAUSE`。
- `EMC_TASK_PLAN_RESUME` 会转发 `EMC_TRAJ_RESUME`。
- motion runtime 状态 JSON 已有 `motion.paused` 字段。
- Node WASM smoke 已覆盖 pause/resume 的最低限度状态变化。

### 当前主要差距

1. `linuxcnc_task_hal_wasm.cpp` 没有显式保存 LinuxCNC 风格的 `interpResumeState` 字段，resume 目前近似恢复为 `READING`。
2. `linuxcnc_motion_runtime.c` 的 pause 命令在队列中处理，用户即时暂停时可能被前序 move 阻塞，和 AXIS GUI immediate pause 语义不完全一致。
3. `STEP` 当前近似为 resume 一次，缺少 LinuxCNC `idForStep` 或 motion id 改变后自动重新 pause 的语义。
4. `linuxcnc_tp_wasm.c` 已链接 vendored TP，但 task-hal motion runtime 还没有直接使用 TP 的 `tpPause()/tpResume()` 做运动减速与队列保持。
5. 前端 task policy 的 resume gate 仍以 `interpState === paused` 为主，需要纳入 motion/traj paused 字段，贴近 AXIS `s.paused`。
6. 现有前端测试证明 UI 冻结可用，但还不能证明底层 WASM 完整对标 LinuxCNC task/motion/TP 暂停链。

## 完成定义

本项目完成必须同时满足：

1. WASM task 状态输出包含并正确维护：
   - `task.interpState`
   - `task.interpResumeState`
   - `task.taskPaused`
   - `task.singleStepping`
2. WASM motion 状态输出包含并正确维护：
   - `motion.paused`
   - `motion.stepping`
   - `motion.programLine`
   - `commandQueueDepth`
3. 暂停后执行若干 `lctask_run_cycles()`：
   - `interpState` 保持 `PAUSED`；
   - `taskPaused=true`；
   - `motion.paused=true`；
   - `programLine`、axis pose、HAL `motion.program-line` 不继续推进。
4. 恢复后：
   - `interpState` 恢复到暂停前状态；
   - `taskPaused=false`；
   - `motion.paused=false`；
   - 程序从暂停位置继续推进。
5. 单步后：
   - 只推进一个 motion id 或一个可观测程序行；
   - 自动回到 paused 状态。
6. 前端暂停按钮继续通过：
   - Node store 测试；
   - WASM Node 测试；
   - 浏览器 trace 暂停位置冻结测试；
   - 50ms 长流程暂停/恢复截图验证。