# working_run 运行功能测试与原理记录

生成时间：2026-06-22

本目录记录 `web-rtcp-5axis-sim-plan` 本地项目中 G-code 程序加载、解释、`RUN` 执行链路、task/HAL feedback 消费方式，以及当前测试发现的问题。

## 文件清单

| 文件 | 用途 |
| --- | --- |
| `01-run-gcode-execution-principle-and-test.md` | G-code 具体执行过程、`RUN` 执行原理、源码证据、测试观察和问题结论 |
| `02-run-preconditions-test-and-implementation-steps.md` | `RUN` 前置条件、INI definition contract、LinuxCNC 源码对照、INI/机床/五轴运动学确认流程、详细测试用例和编写 `RUN` 程序步骤 |
| `03-run-step1-preconditions-complete-next-steps.md` | 本轮已完成的 `RUN` 前置条件 gate、验证结果和下一步接续建议 |
| `04-run-status-loop-complete-next-steps.md` | 本轮已完成的 `RUN` 连续 task/HAL status loop、验证结果和下一步接续建议 |
| `05-run-program-implementation-detailed-steps.md` | 根据 01-04 文档整理的程序实现详细实施步骤、代码落点、测试与验收顺序 |
| `06-run-implementation-traceability-matrix-and-next-steps.md` | 按 05 核对后的完成情况矩阵、本轮补强项、验证结果和后续接续工作 |
| `07-browser-run-feedback-evidence-complete-next-steps.md` | 浏览器端 RUN feedback JSON/截图证据完成记录和后续控制类测试建议 |
| `08-linuxcnc-source-test-assets.md` | 从 LinuxCNC 源程序选定并复制到 working_run 的真实 INI/G-code 测试资产说明 |
| `09-linear-units-meter-scene-complete-next-steps.md` | 英寸/毫米/米单位换算、Three.js 米单位场景、执行轨迹单位语义完成记录和后续建议 |
| `10-run-control-tests-and-ini-cycle-steps.md` | RUN 控制类测试、INI 周期派生、ABORT/STEP/RUN gate/xyzbc 对称测试实施步骤与完成记录 |
| `11-browser-meter-scene-and-mixed-units-complete.md` | 浏览器 desktop/mobile 米尺度截图证据、G20/G21 混合单位预览用例与完成记录 |
| `12-working-run-final-completion-record.md` | 按 `working_run` 接续项最终复核后的剩余工作完成记录 |

## 结论摘要

`RUN` 不应作为第一步实现。正确顺序必须是：

```text
1. 先确定明确的 LinuxCNC INI 文件。
2. 验证 INI definition contract：[EMC]、[DISPLAY]、[RS274NGC]、[KINS]、[HAL]、[TRAJ]、[EMCMOT]、[TASK]、[EMCIO]、[AXIS_*]、[JOINT_*] 必须完整且互相一致。
3. 由 INI/profile 确定机床类型、坐标轴、joint 配置、HAL/remap/tool-table 资产。
4. 由 INI 的 [KINS] KINEMATICS 确定五轴运动学算法和 switchkins 映射。
5. 验证对应 LinuxCNC kinematics WASM 已加载，并能产生 source-derived frame。
6. 验证同一 INI 上下文下的 G-code 已通过 task plan open 打开。
7. 确认 machine ON、AUTO mode、homed/no_force_homing 等 LinuxCNC task gate。
8. 之后才进入 RUN：发送 task command，持续消费 task/HAL/motion feedback。
```

当前项目明确支持的五轴机床上下文是：

| profile | INI | 机床类型 | 坐标 | 运动学 |
| --- | --- | --- | --- | --- |
| `xyzac-trt` | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini` | table rotary tilting | `XYZAC` | `xyzac-trt-kins sparm=identityfirst` |
| `xyzbc-trt` | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini` | table rotary tilting | `XYZBC` | `xyzbc-trt-kins sparm=identityfirst` |

当前实现已经能显示 G-code 程序文本、当前行、高亮行、DRO、runtime feedback 和 task/HAL 状态。

`04` 完成后，当前 `RUN` 已从单次 task/HAL status 读取推进为连续 status loop：

```text
RUN 点击后:
1. UI 确认 opened program、machine ON、AUTO、homed 后发送 EMC_TASK_SET_STATE / EMC_TASK_SET_MODE / EMC_TASK_PLAN_RUN；
2. store 调用 taskHalRuntime.runCycles(...)；
3. store 调用 taskHalRuntime.readStatus()；
4. TASK_HAL_STATUS_APPLIED 将 task/HAL/motion status 映射到 activeLine / axisPose / velocity / feedback；
5. taskHalStatusLoop 持续重复 runCycles/readStatus；
6. programRuntimeFeedbackHistory 保留最近 100 条 task/HAL/motion feedback。
```

该顺序与 LinuxCNC 源码中的 `halui.cc::sendProgramRun()`、`shcom.cc::sendProgramOpen/sendProgramRun()`、`emctaskmain.cc::EMC_TASK_PLAN_OPEN/RUN/PAUSE/RESUME` 对齐：RUN 不是前端播放，而是在已打开程序和可运行 task 状态下发送 `EMC_TASK_PLAN_RUN`，后续状态来自 task/motion/HAL feedback。

当前仍需保持的边界是：

```text
taskHalStatusLoop 只负责调度 runCycles/readStatus；
status 内容必须来自 task/HAL/motion runtime；
UI/store 不自增 activeLine；
UI/store 不自造 axisPose；
浏览器端米尺度 desktop/mobile 截图证据已补齐；
G20/G21 混合单位浏览器预览证据已补齐。
working_run 已列出的必做接续项已全部复核通过，仅保留可选增强。
```