docs: add axis run process working set

This commit is contained in:
wangdequan
2026-07-07 16:46:39 -04:00
parent 8b6be369ff
commit 39b495cf16
672 changed files with 280923 additions and 59 deletions

View File

@@ -0,0 +1,113 @@
# 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 长流程暂停/恢复截图验证。

View File

@@ -0,0 +1,232 @@
# 02-项目程序开发详细步骤
## 开发原则
1. 以 LinuxCNC 源码语义为准,不在 JavaScript 层发明新的 CNC 暂停语义。
2. `wasm-port` 的 wrapper 只能作为 native/WASM 边界适配,不能扩大为独立 CNC 语义实现。
3. 先补 task/motion 可观测状态,再补 STEP再推进 TP 真实接入。
4. 每一步必须有 Node WASM 测试和 Web 集成测试证据。
## 步骤 1补齐 task 层暂停恢复状态
目标文件:
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
- `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs`
- `wasm-port/runtime/sdk/src/linuxcnc-task-hal.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/runtime/linuxcnc-task-hal-runtime.js`
开发动作:
1.`TaskRuntime` 增加字段:
- `std::string interp_resume_state = "IDLE";`
2. 初始化、reset、abort、home、program complete 时同步维护 `interp_resume_state`
3.`EMC_TASK_PLAN_PAUSE` 分支中按 LinuxCNC 语义处理:
```cpp
if (state.interp_state != "PAUSED") {
state.interp_resume_state = state.interp_state.empty() ? "READING" : state.interp_state;
}
state.interp_state = "PAUSED";
state.exec_state = "PAUSED";
state.task_paused = true;
forward_motion_command("{\"type\":\"EMCMOT_PAUSE\"}");
```
4.`EMC_TASK_PLAN_RESUME` 分支中按 LinuxCNC 语义处理:
```cpp
const std::string resume = state.interp_resume_state == "PAUSED" || state.interp_resume_state.empty()
? "READING"
: state.interp_resume_state;
state.interp_state = resume;
state.interp_resume_state = resume;
state.exec_state = resume == "IDLE" ? "DONE" : "WAITING_FOR_MOTION";
state.task_paused = false;
state.single_stepping = false;
forward_motion_command("{\"type\":\"EMCMOT_RESUME\"}");
```
5. `status_json()` 输出 `interpResumeState`
6. SDK 和 Web runtime wrapper 把 `interpResumeState` 转成小写并映射到 UI 状态。
验收:
- pause 前为 `READING`pause 后 `interpResumeState=READING`
- resume 后恢复 `READING`,不是固定靠前端猜测。
- pause 前为 `WAITING` 时 resume 能恢复 `WAITING`
## 步骤 2补齐 motion 层 immediate pause 语义
目标文件:
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
- `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs`
当前风险:
`lcmot_write_command_json()``EMC_TRAJ_PAUSE` 作为普通命令入队。如果队列中已有多个 movepause 可能排在 move 后执行。AXIS 用户点击暂停属于 GUI immediate command应尽快阻止继续消费运动队列。
开发动作:
1.`EMCMOT_PAUSE``EMC_TRAJ_PAUSE` 做即时状态切换:
- `lcmot_state.paused = 1`
- `lcmot_state.current_vel = 0`
- `lcmot_state.motion_type = 0`
- `lcmot_state.in_position = 0`
2. 不清空运动队列。
3. 暂停期间 `lcmot_step_servo()` 不消费普通 move只允许
- `STEP`
- `RESUME`
- `ABORT`
4. `EMCMOT_RESUME` 即时清除 paused后续 servo cycle 继续消费保留队列。
5. 状态 JSON 增加:
- `motion.stepping`
- `motion.idForStep` 或同等 step 追踪字段。
验收:
- 先入队多个 line move运行一部分后 pause。
- pause 后连续运行 20 个 cycle`programLine` 不变、axis 不变、queueDepth 不减少。
- resume 后 queueDepth 继续减少programLine 继续推进。
## 步骤 3实现 STEP 自动回暂停
目标文件:
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
- `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_run_feedback_loop.mjs`
LinuxCNC 对标:
- `EMCMOT_STEP` 在 paused 时记录当前 motion id短暂恢复 TP
- motion id 改变后自动 `tpPause()`
- 外部仍把程序视为 paused。
开发动作:
1. 在 motion runtime 增加:
- `int stepping;`
- `int id_for_step;`
- `int motion_id;`
2. 每执行一个普通 move 时递增 `motion_id`
3. `EMCMOT_STEP`
- 如果当前 paused设置 `stepping=1``id_for_step=motion_id`
- 允许消费一个普通 move
- 保持对外 `paused=true` 或在状态中明确 `paused=true, stepping=true`
4. `lcmot_step_servo()` 在 step 消费一个 move 后:
- 自动恢复 `paused=1`
-`stepping=0`
5. task 层 `EMC_TASK_PLAN_STEP`
- 不把解释器永久改成 running
- step 完成后恢复 `interpState=PAUSED``taskPaused=true`
验收:
- paused 状态下 STEP 后只推进一个 line 或一个 motion id。
- STEP 完成后 `task.interpState=PAUSED``taskPaused=true``motion.paused=true`
- 再次 Resume 可从 step 后位置继续运行。
## 步骤 4把 motion paused 字段接入 Web task policy
目标文件:
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/linuxcnc-task-policy.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/store.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/ui/axis-shell.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_run_feedback_loop.mjs`
开发动作:
1.`taskHalStatus.ui``taskHalStatus.motionStatus.motion.paused` 映射 `machine.motionPaused`
2. `isProgramPaused()` 判断改为包含:
- `state.machine.motionPaused === true`
- `state.programRuntimeFeedback.paused === true`
3. `canResume``RESUME` gate 改为:
```text
taskState == on
taskMode in auto/mdi
motionPaused 或 interpState paused 或 taskPaused
未被 resumeInhibit 阻止
```
4. `PAUSE_RESUME` toggle 优先看 motion paused贴近 AXIS `s.paused`
5. 保留菜单 Pause 的严格条件AUTO 且 `interpState``reading/waiting`
验收:
- motion paused 已 true 但 interpState 同步稍晚时,工具栏按钮显示 Resume。
- Resume 不再只依赖 `interpState === paused`
- 菜单 Pause/Resume 与工具栏 toggle 逻辑仍分离。
## 步骤 5补充 TP 层暂停验证
目标文件:
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_tp_wasm.c`
- `wasm-port/tests/wasm/node/verify_tp_wasm.mjs`
开发动作:
1. 在 TP probe 中增加 pause/resume 场景:
- 创建 TP
- 加入至少两段 line
- 运行若干 cycle
-`tpPause()`
- 继续运行若干 cycle
- 验证位置不继续跨段推进或速度趋向 0
-`tpResume()`
- 验证可继续完成队列。
2. 输出可测试字段:
- `tp_pause_rc=0`
- `tp_resume_rc=0`
- `tp_paused_velocity_zero=1`
- `tp_resume_done=1`
验收:
- `node wasm-port/tests/wasm/node/verify_tp_wasm.mjs` 通过。
- 证据显示 TP pause/resume 使用 vendored LinuxCNC TP API而不是 JS 模拟。
## 步骤 6构建与回归
推荐命令:
```bash
cd /home/mes123456/cnc_wams/wasm-port
./tools/build_task_hal_wasm.sh
./tools/build_tp_wasm.sh
node tests/wasm/node/verify_task_hal_wasm.mjs
node tests/wasm/node/verify_tp_wasm.mjs
```
Web 集成命令:
```bash
cd /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan
npm --prefix app run build
node tests/node/verify_run_feedback_loop.mjs
APP_URL_PATH=/web-rtcp-5axis-xyzbc-trt-sim-plan/app/dist/index.html node tools/trace-pause-position-json.mjs
RUN_STABLE_BEFORE_FIRST_PAUSE_MS=3000 node tools/verify-estop-power-home-run-pause-50ms.mjs
```
验收输出至少包括:
- `linuxcnc_task_runtime_smoke=ok`
- `tp_wasm_node_smoke=ok`
- `run_feedback_status_loop_smoke=ok`
- `pause_position_status=passed-position-frozen`
- `verification_status=passed`
## 步骤 7记录证据与关闭任务
每完成一个编号任务:
1. 更新 `03-推进台账.md`
2. 更新 `04-任务矩阵.md` 状态。
3. 把命令、输出、trace 路径、截图目录写入 `05-验收证据.md`
4. 如果出现新取舍,追加 `06-决策记录.md`

View File

@@ -0,0 +1,151 @@
# 03-推进台账
## 记录规则
每轮推进必须记录:
- 时间;
- 用户目标;
- 本轮做了什么;
- 改了哪些文件;
- 验证了什么;
- 遗留问题;
- 下一步。
## 2026-07-07 轮次 1暂停功能 wasm 补齐方案建档
### 用户目标
根据 `AXIS暂停按钮LinuxCNC调用链分析.md`,实现暂停功能,完善 `wasm-port` 中 LinuxCNC 的 WASM 功能,最终实现 `web-rtcp-5axis-xyzbc-trt-sim-plan` 的暂停按钮正确功能;把完善方法和详细步骤写入 `work/working8`,并包含项目内容、开发步骤、推进台账、任务矩阵、验收证据、决策记录和 README 索引。
### 本轮做了什么
1. 阅读 AXIS 暂停按钮调用链分析文档,确认暂停必须同时覆盖 task/interpreter 与 motion/trajectory 两层。
2. 检查 `wasm-port` 结构,确认已有 task-hal、motion runtime、TP wasm、SDK 和 WASM Node 测试。
3. 检查 `web-rtcp-5axis-xyzbc-trt-sim-plan` 暂停按钮、task policy、store 分发逻辑和已有暂停测试报告。
4. 识别当前主要差距:
- task wrapper 没有完整保存和输出 `interpResumeState`
- motion pause 仍偏普通队列命令,缺少 GUI immediate pause 语义;
- STEP 缺少 LinuxCNC 式自动回暂停;
- Web resume gate 仍需以 motion paused 为优先依据;
- TP pause/resume 需要补可观测测试。
5. 创建 `work/working8` 文档体系。
### 本轮新增或修改文件
- `work/working8/README.md`
- `work/working8/01-项目功能内容.md`
- `work/working8/02-项目程序开发详细步骤.md`
- `work/working8/03-推进台账.md`
- `work/working8/04-任务矩阵.md`
- `work/working8/05-验收证据.md`
- `work/working8/06-决策记录.md`
### 本轮验证
本轮是方案与推进文档建档,未修改业务代码,未运行构建和测试。
已完成的静态核对:
- 确认 `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp` 已有 `EMC_TASK_PLAN_PAUSE/RESUME/STEP` 分支。
- 确认 `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c` 已有 `paused` 字段和 pause/resume 命令识别。
- 确认 `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs` 已有最低限度 pause/resume smoke。
- 确认 Web 侧已有 `trace-pause-position-json.mjs``verify-estop-power-home-run-pause-50ms.mjs` 暂停冻结验证工具。
### 下一步
`04-任务矩阵.md``W8-001` 开始:
1. 修改 task runtime增加 `interpResumeState`
2. 扩展 WASM status JSON 和 SDK 映射。
3. 增加 Node WASM 测试,证明 pause/resume 恢复暂停前解释器状态。
## 2026-07-07 轮次 2暂停语义代码实现、回归验证与任务关闭
### 用户目标
完成 `/home/mes123456/cnc_wams/work/working8` 的全部任务。
### 本轮做了什么
1. 补齐 `wasm-port` task runtime 的 LinuxCNC 风格暂停恢复状态:
- 增加 `interpResumeState`
- pause 保存暂停前解释器状态;
- resume 按保存状态恢复;
- abort/home/program complete 同步清理状态。
2. 补齐 motion runtime immediate pause/resume/step
- pause/resume/step/abort 改为即时命令;
- pause 不清空 queue
- paused 时不消费普通 move
- STEP 只消费一个普通 motion 后自动恢复 paused
- status JSON 输出 `motion.stepping``motion.idForStep``motion.motionId``commandQueueDepth`
3. 增加 TP pause/resume probe
- 直接调用 vendored LinuxCNC `tpPause()``tpResume()`
- 验证暂停速度归零、位置保持、恢复后队列完成。
4. Web 侧接入 motion paused
- runtime normalize 输出 `ui.interpResumeState``ui.taskPaused``ui.singleStepping``ui.motionPaused``ui.motionStepping``ui.motionQueueDepth`
- task policy 的 resume gate 接受 motion paused/task paused/interp paused
- store 的 `PAUSE_RESUME` 优先用 `machine.motionPaused` 判断 resume
- UI pause 按钮 active/title/data-paused 接入 `motionPaused`
5. 扩展测试:
- WASM task-hal Node 覆盖 pause freeze、resume restore、step returns paused、motion queue preserved
- Web Node 覆盖 motion paused gate 和暂停期间 active line/motion line 不推进;
- 50ms 截图 manifest 增加 `motionPaused` 证据字段。
6. 运行全部验收命令并关闭 `W8-001``W8-014`
### 本轮新增或修改文件
- `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/tests/wasm/node/verify_task_hal_wasm.mjs`
- `wasm-port/tests/wasm/node/verify_tp_wasm.mjs`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/runtime/linuxcnc-task-hal-runtime.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/linuxcnc-task-policy.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/store.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/ui/axis-shell.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_run_feedback_loop.mjs`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tools/verify-estop-power-home-run-pause-50ms.mjs`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/dist/**` 中本轮重新构建的静态产物和 WASM artifact
- `work/working8/03-推进台账.md`
- `work/working8/04-任务矩阵.md`
- `work/working8/05-验收证据.md`
- `work/working8/06-决策记录.md`
### 本轮验证
已通过:
```text
linuxcnc_task_hal_wasm_build=ok
linuxcnc_task_runtime_smoke=ok
task_status_from_linuxcnc_runtime=ok
task_commands_drive_motion_runtime=ok
mdi_jog_task_motion_hal_sync=ok
pause_freezes_motion_queue=ok
resume_restores_interp_resume_state=ok
step_returns_to_paused=ok
tp_wasm_node_smoke=ok
tp_pause_resume_smoke=ok
gmoccapy_static_build=ok
run_feedback_status_loop_smoke=ok
run_ready_sequence_smoke=ok
pause_uses_motion_paused_gate=ok
pause_freezes_task_hal_status_loop=ok
pause_position_status=passed-position-frozen
verification_status=passed
```
生成证据:
- trace`/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/pause-position-traces/pause-position-20260707T140646Z/trace.json`
- screenshots`/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/screenshots/estop-power-home-run-pause-50ms-20260707T141219Z`
- manifest`/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/screenshots/estop-power-home-run-pause-50ms-20260707T141219Z/manifest.json`
### 遗留问题
本轮 `working8` 任务矩阵内任务均已完成。底层 task-hal motion runtime 仍是 wrapper 级可观测语义补齐,完整将 task-hal motion 执行迁移到 vendored TP runtime 仍属于后续架构演进,不再阻塞本轮 AXIS 暂停按钮验收。
### 下一步
无本轮阻塞项。后续如果继续推进,可把 task-hal motion runtime 的手写队列逐步替换为 vendored TP 队列执行路径。

View File

@@ -0,0 +1,32 @@
# 04-任务矩阵
状态定义:
- `待办`:尚未修改代码。
- `进行中`:已有部分修改或验证。
- `已完成`:代码、测试、证据均完成。
- `阻塞`:需要外部输入或依赖。
| 任务编号 | 状态 | 任务 | 目标文件 | 验收标准 |
|---|---|---|---|---|
| W8-001 | 已完成 | task runtime 增加 `interpResumeState` 保存与恢复 | `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp` | pause 前状态为 `READING/WAITING` 时被保存resume 后恢复原状态status JSON 输出该字段。 |
| W8-002 | 已完成 | 扩展 task-hal SDK 和 Web runtime 映射 | `wasm-port/runtime/sdk/src/linuxcnc-task-hal.js``web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/runtime/linuxcnc-task-hal-runtime.js` | Web state 可读取小写 `interpResumeState``motionPaused``singleStepping`。 |
| W8-003 | 已完成 | motion runtime 实现 immediate pause/resume | `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c` | pause 后连续 cycles 不消费普通 movequeue 保留resume 后继续消费。 |
| W8-004 | 已完成 | motion runtime 增加 stepping/id 追踪 | `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c` | STEP 只推进一个 motion id 或一行,并自动回到 paused。 |
| W8-005 | 已完成 | task STEP 与 motion STEP 对齐 | `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp` | STEP 完成后 task 仍为 `PAUSED``taskPaused=true`resume 可继续运行。 |
| W8-006 | 已完成 | 扩展 WASM task-hal Node 测试 | `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs` | 覆盖 pause freeze、resume restore、step one motion、queue preserved。 |
| W8-007 | 已完成 | TP wasm 增加 pause/resume probe | `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_tp_wasm.c``wasm-port/tests/wasm/node/verify_tp_wasm.mjs` | `verify_tp_wasm.mjs` 可证明 `tpPause()/tpResume()` 生效。 |
| W8-008 | 已完成 | Web task policy 接入 motion paused | `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/linuxcnc-task-policy.js` | `canResume` 使用 motion paused/task paused/interp paused 综合判断;菜单 Pause 仍保持 AXIS 严格条件。 |
| W8-009 | 已完成 | Store 暂停恢复分发优先使用 motion paused | `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/store.js` | `PAUSE_RESUME` 在 motion paused 时触发 resumepause 后写入 `machine.motionPaused`。 |
| W8-010 | 已完成 | UI 暂停按钮 active 状态接入 motion paused | `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/ui/axis-shell.js` | motion paused 同步窗口内按钮显示 Resume`data-paused=true`。 |
| W8-011 | 已完成 | Web Node 回归增加暂停底层状态断言 | `web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_run_feedback_loop.mjs` | pause 后断言 `taskHalStatus.motionStatus.motion.paused=true` 且 active line 不推进。 |
| W8-012 | 已完成 | 浏览器暂停冻结证据重跑 | `web-rtcp-5axis-xyzbc-trt-sim-plan/tools/trace-pause-position-json.mjs` | 输出 `pause_position_status=passed-position-frozen`trace 写入 working evidence。 |
| W8-013 | 已完成 | 50ms 长流程暂停/恢复截图重跑 | `web-rtcp-5axis-xyzbc-trt-sim-plan/tools/verify-estop-power-home-run-pause-50ms.mjs` | 输出 `verification_status=passed`,截图 manifest 记录两次暂停保持。 |
| W8-014 | 已完成 | 更新验收证据与推进台账 | `work/working8/03-推进台账.md``work/working8/05-验收证据.md` | 每个完成任务都有命令、输出和路径证据。 |
## 防重复规则
1. 前端 `runState=paused` 通过不等于 `W8-003/W8-004` 完成。
2. Node smoke 只检查 `motion.paused` true/false 不等于 STEP 对标完成。
3. 未记录 trace 或截图路径,不得关闭浏览器验收任务。
4. 任何 task/motion pause 行为变化必须同步更新 task matrix 和验收证据。

View File

@@ -0,0 +1,350 @@
# 05-验收证据
## 证据要求
每条证据必须记录:
- 执行时间;
- 命令或页面;
- 关键输出;
- 生成文件路径;
- 对应任务编号。
## 当前已有参考证据
### Web 前端暂停冻结历史证据
来源文件:
`/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/17-20260706-暂停按钮严格测试报告.md`
历史结论:
- `npm --prefix app run build` 通过。
- `npm --prefix app run smoke:node` 通过。
- `npm --prefix app run smoke:browser` 通过。
- `trace-pause-position-json.mjs` 输出 `pause_position_status=passed-position-frozen`
- `verify-estop-power-home-run-pause-50ms.mjs` 输出 `verification_status=passed`
注意:
该证据证明 Web 表层暂停冻结通过,但不能单独证明 `wasm-port` 底层已完整对标 LinuxCNC task/motion/TP 暂停链。
## 本轮文档建档证据
时间2026-07-07
操作:
```bash
sed -n '1,240p' web-rtcp-5axis-xyzbc-trt-sim-plan/doc/AXIS暂停按钮LinuxCNC调用链分析.md
rg -n "pause|paused|AUTO_PAUSE|AUTO_RESUME|task_paused|interpState|EMCMOT_PAUSE|PLAN_PAUSE|runState|tbtn_pause" wasm-port web-rtcp-5axis-xyzbc-trt-sim-plan/app web-rtcp-5axis-xyzbc-trt-sim-plan/tests web-rtcp-5axis-xyzbc-trt-sim-plan/tools -S
sed -n '600,755p' wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp
sed -n '1,460p' wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c
sed -n '1,260p' wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs
```
结论:
- 已确认 AXIS 暂停调用链和当前 WASM wrapper 差距。
- 已确认 `work/working8` 文档体系建立。
对应任务:
- `W8-014` 部分完成:文档框架已建立,后续仍需随代码实现补证据。
## 待执行验收命令
### WASM task/motion 验收
对应任务:`W8-001``W8-006`
```bash
cd /home/mes123456/cnc_wams/wasm-port
./tools/build_task_hal_wasm.sh
node tests/wasm/node/verify_task_hal_wasm.mjs
```
期望输出:
```text
linuxcnc_task_runtime_smoke=ok
task_status_from_linuxcnc_runtime=ok
task_commands_drive_motion_runtime=ok
mdi_jog_task_motion_hal_sync=ok
```
新增断言期望:
```text
pause_freezes_motion_queue=ok
resume_restores_interp_resume_state=ok
step_returns_to_paused=ok
```
### WASM TP 验收
对应任务:`W8-007`
```bash
cd /home/mes123456/cnc_wams/wasm-port
./tools/build_tp_wasm.sh
node tests/wasm/node/verify_tp_wasm.mjs
```
期望输出:
```text
tp_wasm_node_smoke=ok
tp_pause_resume_smoke=ok
```
### Web Node 集成验收
对应任务:`W8-008``W8-011`
```bash
cd /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan
npm --prefix app run build
node tests/node/verify_run_feedback_loop.mjs
```
期望输出:
```text
run_feedback_status_loop_smoke=ok
run_ready_sequence_smoke=ok
```
新增断言期望:
```text
pause_uses_motion_paused_gate=ok
pause_freezes_task_hal_status_loop=ok
```
### 浏览器 trace 验收
对应任务:`W8-012`
```bash
cd /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan
APP_URL_PATH=/web-rtcp-5axis-xyzbc-trt-sim-plan/app/dist/index.html node tools/trace-pause-position-json.mjs
```
期望输出:
```text
pause_position_status=passed-position-frozen
position_changed=false
changed_fields=
```
需要记录:
- `trace=.../trace.json`
### 50ms 长流程截图验收
对应任务:`W8-013`
```bash
cd /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan
RUN_STABLE_BEFORE_FIRST_PAUSE_MS=3000 node tools/verify-estop-power-home-run-pause-50ms.mjs
```
期望输出:
```text
verification_status=passed
captured_frames=...
manifest=...
```
需要记录:
- screenshots 目录;
- manifest 文件;
- 两次暂停保持阶段的 `sampleIndex``interpState``taskPaused``motionPaused``currentVelocity`
## 2026-07-07 10:16 EDT 本轮完成证据
### WASM task/motion 验收
对应任务:
- `W8-001`
- `W8-002`
- `W8-003`
- `W8-004`
- `W8-005`
- `W8-006`
命令:
```bash
cd /home/mes123456/cnc_wams/wasm-port
source /home/mes123456/emsdk/emsdk_env.sh >/dev/null && ./tools/build_task_hal_wasm.sh
node tests/wasm/node/verify_task_hal_wasm.mjs
```
关键输出:
```text
linuxcnc_task_hal_wasm_build=ok
linuxcnc_task_runtime_smoke=ok
task_status_from_linuxcnc_runtime=ok
task_commands_drive_motion_runtime=ok
mdi_jog_task_motion_hal_sync=ok
pause_freezes_motion_queue=ok
resume_restores_interp_resume_state=ok
step_returns_to_paused=ok
```
结论:
- task status 已输出并维护 `interpResumeState`
- pause 后 `interpState=PAUSED``taskPaused=true``motion.paused=true`,连续 cycles 不推进 task line、motion line、axis pose 和 motion id。
- resume 后恢复 `interpResumeState=READING` 并继续推进。
- motion direct queue 验证 pause 即时生效、queue 保留、STEP 只消费一个 motion 后自动回 paused。
### WASM TP pause/resume 验收
对应任务:
- `W8-007`
命令:
```bash
cd /home/mes123456/cnc_wams/wasm-port
source /home/mes123456/emsdk/emsdk_env.sh >/dev/null && ./tools/build_tp_wasm.sh
node tests/wasm/node/verify_tp_wasm.mjs
```
关键输出:
```text
tp_wasm_node_smoke=ok
tp_pause_resume_smoke=ok
```
新增 probe 断言:
```text
tp_pause_rc=0
tp_resume_rc=0
tp_paused_velocity_zero=1
tp_paused_position_frozen=1
tp_resume_done=1
tp_pause_resume_final_depth=0
tp_pause_resume_final_pos_near_end=1
```
结论:
- `linuxcnc_tp_wasm.c` 通过 vendored LinuxCNC `tpPause()``tpResume()` 验证暂停减速到零、暂停保持位置、恢复后完成队列。
### Web Node 集成验收
对应任务:
- `W8-008`
- `W8-009`
- `W8-010`
- `W8-011`
命令:
```bash
cd /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan
npm --prefix app run build
node tests/node/verify_run_feedback_loop.mjs
```
关键输出:
```text
gmoccapy_static_build=ok
run_feedback_status_loop_smoke=ok
run_ready_sequence_smoke=ok
pause_uses_motion_paused_gate=ok
pause_freezes_task_hal_status_loop=ok
```
结论:
- Web runtime `ui` 可读取 `interpResumeState``taskPaused``singleStepping``motionPaused``motionStepping``motionQueueDepth`
- `canResume``PAUSE_RESUME` 已接入 motion paused/task paused/interp paused 综合判断。
- Node 集成断言 pause 后 `taskHalStatus.motionStatus.motion.paused=true``machine.motionPaused=true`、active line 和 motion program line 不推进。
### 浏览器暂停冻结 trace 验收
对应任务:
- `W8-012`
命令:
```bash
cd /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan
APP_URL_PATH=/web-rtcp-5axis-xyzbc-trt-sim-plan/app/dist/index.html node tools/trace-pause-position-json.mjs
```
关键输出:
```text
pause_position_status=passed-position-frozen
trace=/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/pause-position-traces/pause-position-20260707T140646Z/trace.json
app_url_path=/web-rtcp-5axis-xyzbc-trt-sim-plan/app/dist/index.html
position_changed=false
changed_fields=
```
结论:
- 浏览器 trace 证明暂停后 position 未变化。
### 50ms 长流程暂停/恢复截图验收
对应任务:
- `W8-013`
命令:
```bash
cd /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan
RUN_STABLE_BEFORE_FIRST_PAUSE_MS=3000 node tools/verify-estop-power-home-run-pause-50ms.mjs
```
关键输出:
```text
verification_status=passed
screenshots=/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/screenshots/estop-power-home-run-pause-50ms-20260707T141219Z
captured_frames=459
sample_period_ms=50
manifest=/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/working/screenshots/estop-power-home-run-pause-50ms-20260707T141219Z/manifest.json
```
manifest 暂停保持关键字段:
```text
第一次暂停保持 5 秒sampleIndex=109, activeLine=17, interpState=paused, taskPaused=true, motionPaused=true, currentVelocity=0
第二次暂停保持 5 秒sampleIndex=341, activeLine=13, interpState=paused, taskPaused=true, motionPaused=true, currentVelocity=0
```
结论:
- 50ms 截图验证通过,两次暂停保持阶段 `sampleIndex``activeLine``interpState``taskPaused``motionPaused``currentVelocity` 均符合暂停冻结要求。
### 记录与关闭
对应任务:
- `W8-014`
结论:
- 本轮已更新 `03-推进台账.md``04-任务矩阵.md``05-验收证据.md``06-决策记录.md`

View File

@@ -0,0 +1,126 @@
# 06-决策记录
## DR-W8-001暂停语义必须分成 task/interpreter 与 motion/trajectory 两层
日期2026-07-07
决策:
暂停按钮不能只修改 Web `runState`,必须同时维护:
- task/interpreter`interpState``interpResumeState``taskPaused`
- motion/trajectory`motion.paused`、queue 保留、速度归零或受控减速;
- 后续 TP`tpPause()``tpResume()`
原因:
LinuxCNC AXIS 的暂停调用链明确同时发送 `EMC_TASK_PLAN_PAUSE``EMCMOT_PAUSE`,并由 TP 完成暂停减速语义。只改 UI 状态会出现按钮显示暂停但底层行号或运动继续推进的问题。
影响:
所有验收必须检查 task 与 motion 两层状态,不能只检查 `runState=paused`
## DR-W8-002工具栏 Pause 是 toggle菜单 Pause 和 Resume 是独立命令
日期2026-07-07
决策:
Web 工具栏 `tbtn_pause` 对标 AXIS `task_pauseresume`;菜单 Pause 对标 `task_pause`;菜单 Resume 对标 `task_resume`
原因:
AXIS 源码中工具栏按钮会根据 `s.paused` 在 pause/resume 间切换,菜单命令则分别有独立 gate。混用会导致菜单 Pause 在 paused 状态误触发 resume或工具栏无法恢复。
影响:
`linuxcnc-task-policy.js` 中必须保留菜单 Pause 的严格条件AUTO 且 interpreter 为 `reading/waiting`。工具栏 toggle 的恢复判断优先使用 motion paused。
## DR-W8-003Resume gate 应优先接受 motion paused
日期2026-07-07
决策:
Web resume gate 不应只依赖 `interpState === "paused"`,应接受:
- `motionPaused === true`
-`taskPaused === true`
-`interpState === "paused"`
原因:
AXIS `task_resume()``task_pauseresume()` 的恢复判断核心是 `s.paused`,该字段来自 motion/traj 层,而不是单纯 task interpreter 状态。WASM 和 Web 状态同步存在短窗口motion paused 是恢复按钮是否可用的关键来源。
影响:
需要把 `taskHalStatus.motionStatus.motion.paused` 映射进 Web state并更新按钮 active/title 和 RESUME gate。
## DR-W8-004Immediate pause 不清空运动队列
日期2026-07-07
决策:
用户点击暂停时motion runtime 应立即停止继续消费普通 move但不能清空队列。
原因:
LinuxCNC `tpPause()` 设置 `tp->pausing=1`,使规划器受控降速并保留队列;`tpResume()` 后从原队列继续。清空队列会把 pause 变成 stop/abort破坏恢复语义。
影响:
`linuxcnc_motion_runtime.c` 的 pause 处理应设置 paused 和速度状态,暂停期间只允许 STEP/RESUME/ABORT 继续处理。
## DR-W8-005STEP 不是普通 Resume
日期2026-07-07
决策:
STEP 必须实现“短暂推进一个 motion id 或一行后自动回暂停”,不能等同于 resume。
原因:
LinuxCNC motion 中 `EMCMOT_STEP` 会记录 `idForStep`,短暂恢复 TP检测 id 改变后自动 `tpPause()`。如果 STEP 只是 resume会导致程序连续运行破坏 AXIS 单步语义。
影响:
需要在 motion runtime 中增加 stepping/id 追踪,并在 task runtime 中保持 step 完成后的 paused 状态。
## DR-W8-006短期先修 wrapper 可观测语义,长期迁移到 vendored TP
日期2026-07-07
决策:
当前阶段先在 `linuxcnc_task_hal_wasm.cpp``linuxcnc_motion_runtime.c` 修正 pause/resume/step 的可观测状态与队列行为;随后通过 `linuxcnc_tp_wasm.c` 增加 TP pause/resume probe并逐步让 task-hal motion runtime 使用 vendored TP。
原因:
`wasm-port` 的原则是复用 LinuxCNC 源码,不扩展手写 CNC 语义。但现有前端依赖 task-hal runtime直接替换为 TP 全链路风险较大。分两步推进可以先修正暂停按钮,再用 TP 证据收敛底层实现。
影响:
任务矩阵把 `W8-001``W8-006` 作为短期必要任务,把 `W8-007` 作为向 LinuxCNC TP 真实语义收敛的关键任务。
## DR-W8-007Run Ready 验证不代替 ESTOP/Power/Home/Run
日期2026-07-07
决策:
Web Node 回归中的 `RUN_READY` 保持 AXIS 风格“准备并打开程序”的语义不把上电、Home All、切 AUTO 或 Run 混入 Run Ready。需要运行程序时测试显式执行
- `TOGGLE_POWER`
- `HOME`
- `SET_MODE auto`
- `RUN`
原因:
AXIS toolbar/menu 的 Run Ready 入口不是 LinuxCNC task run 命令,也不能替用户绕过机床状态前置条件。把 power/home/run 混进 Run Ready 会污染暂停按钮验收,因为后续 pause/resume gate 无法区分“程序准备”与“任务正在运行”。
影响:
`verify_run_feedback_loop.mjs` 先断言 Run Ready 已准备 task/HAL session再显式走 power/home/auto/run 流程;暂停恢复验收只在真实 running 状态下执行。

View File

@@ -0,0 +1,33 @@
# working8 README 索引
## 主题
基于 `web-rtcp-5axis-xyzbc-trt-sim-plan/doc/AXIS暂停按钮LinuxCNC调用链分析.md`,推进 `wasm-port` 中 LinuxCNC task/motion/TP 暂停语义补齐,最终支撑 `web-rtcp-5axis-xyzbc-trt-sim-plan` 的 AXIS 风格暂停按钮正确工作。
## 文档索引
| 文件 | 用途 |
|---|---|
| `01-项目功能内容.md` | 定义暂停功能范围、LinuxCNC 对标语义、当前差距和完成定义。 |
| `02-项目程序开发详细步骤.md` | 按源码层级列出可执行开发步骤、目标文件、测试路径和回滚边界。 |
| `03-推进台账.md` | 记录每轮做了什么、改了哪些文件、验证了什么、下一步是什么。 |
| `04-任务矩阵.md` | 管理全部任务编号、状态、依赖和验收标准,防止重复推进。 |
| `05-验收证据.md` | 汇总命令、页面、日志、截图、trace、report 等证据位置。 |
| `06-决策记录.md` | 固化关键技术决策,避免后续重复争论同一问题。 |
## 当前推进入口
1. 先读 `01-项目功能内容.md` 明确验收目标。
2.`04-任务矩阵.md``W8-001` 开始推进。
3. 每完成一个任务,把命令和结果追加到 `05-验收证据.md`
4. 每轮结束更新 `03-推进台账.md`
5. 如果改变技术方向,先补 `06-决策记录.md`
## 当前结论
前端已有暂停冻结测试证据,但 `wasm-port` 底层暂停语义仍需要补齐为 LinuxCNC 双层语义:
- task/interpreter 层:`EMC_TASK_PLAN_PAUSE/RESUME` 保存并恢复 `interpResumeState`,维护 `interpState``taskPaused`
- motion/trajectory 层:`EMCMOT_PAUSE/RESUME/STEP` 维护 `motion.paused`、单步状态,并阻止暂停期间继续消费运动队列。
- TP 层:后续应逐步从手写 motion runtime 迁移到 vendored LinuxCNC `tpPause()/tpResume()/tpRunCycle()` 的可观测暂停行为。