# 01-项目功能内容

## 项目目标

将 `wasm-port` 的 task/motion/HAL 运行时从当前 minimal adapter 推进到尽可能贴近 LinuxCNC 原生 `emctaskmain.cc` 的 task 主循环结构。

核心要求：

- 每个 task 周期都建立 LinuxCNC 式 motion 状态快照。
- task 状态机使用该 motion 快照驱动等待、错误、estop、abort、queueFull、in-position、program line 等行为。
- 周期顺序对标上游 `emctaskmain.cc`：command read -> plan -> execute -> motion update -> subordinate sync -> task update -> status write。
- 当前 JSON 自有状态机逐步收缩为 host/runtime 边界，CNC/task 语义优先来自 LinuxCNC 源码。
- 后续 WASM 程序定位为核心状态机实现的运行载体：task/motion 状态机、周期调度、状态聚合、命令执行位于 C/C++ WASM 侧；JS/SDK 和 JSON 只承担外部边界职责。

## 对标源

主要对标文件：

- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emctaskmain.cc`
- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emctask.cc`
- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/taskintf.cc`
- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emccanon.cc`
- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/task.hh`
- `/home/mes123456/cnc_wams/linuxcnc/src/emc/nml_intf/emc.hh`
- `/home/mes123456/cnc_wams/linuxcnc/src/emc/nml_intf/emc_nml.hh`
- `/home/mes123456/cnc_wams/linuxcnc/src/emc/motion/usrmotintf.h`
- `/home/mes123456/cnc_wams/linuxcnc/src/emc/motion/motion.h`

当前 WASM 侧入口：

- `/home/mes123456/cnc_wams/wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
- `/home/mes123456/cnc_wams/wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
- `/home/mes123456/cnc_wams/wasm-port/runtime/sdk/src/linuxcnc-task-hal.js`

## 当前闭合状态

当前 `wasm-port` 已有：

- `lctask_*` C ABI。
- `lcmot_*` minimal motion runtime。
- HAL pin/snapshot runtime。
- Node WASM task/motion/HAL smoke。
- LinuxCNC 式 task 周期骨架：command read -> plan -> execute -> motion update -> subordinate sync -> task update -> status write。
- 周期内 `LcmotStatusSnapshot` 到 `StandaloneEmcStatus.motion` 的映射。
- `StandaloneEmcStatus` 作为当前阶段 `EMC_STAT` 等价容器，集中导出 task/motion/io/top status。
- RUN 文件主路径通过 staged program plan read/command/execute、`emccanon.cc` command envelope 和 `taskintf.cc` motion issue 工作，不依赖 host JSON motion plan。
- task 状态、模式、pause/resume/step/home/run gate、wait-for-motion、queueFull、motion error、soft-limit、IO error、RCS 聚合和 no-JSON RUN path 的 WASM/SDK/state-matrix 覆盖。

当前保守边界：

- 当前 shim `runtime/core/shims/nml_intf/emc.hh` 只暴露 `motion.traj.linearUnits`，远小于上游 `emc_nml.hh` 中 `EMC_STAT`、`EMC_TASK_STAT`、`EMC_MOTION_STAT`、`EMC_TRAJ_STAT` 的字段范围。
- task-HAL WASM 构建接入的是 `emctask.cc`、`taskintf.cc`、`emccanon.cc` 的窄 source-anchored subset，不是完整上游 process/NML topology。
- `tools/task-hal-source-manifest.txt` 仍是 Phase 0 references，`task_hal_runtime_promoted=0`。
- `nativeTaskReady=false`、`nativeHalSyncReady=false`、`fullLinuxCncProgramExecutionReady=false` 仍是当前 readiness contract。

## WASM核心状态机边界

后续完善时按以下职责划分：

| 层 | 职责 |
| --- | --- |
| WASM/C++ | 核心状态机、LinuxCNC 语义复用、task cycle、motion snapshot、`StandaloneEmcStatus`、command read/plan/execute、RCS 聚合。 |
| JS/SDK | 加载 WASM、传命令、读状态、管理 Emscripten FS/OPFS 和浏览器/Node 边界。 |
| JSON | 作为外部通信格式，例如 command JSON 和 status JSON；不得作为核心状态机事实源。 |

因此，新增状态应优先进入 C/C++ 结构体、枚举、队列和周期函数；status JSON 只能从最后一次 status write 或 `StandaloneEmcStatus` 导出。

`status JSON` 的具体 LinuxCNC 对标方案详见 `12-status-json-LinuxCNC对标方案.md`。该方案要求 `emcStatus` 成为 LinuxCNC 对标字段的唯一 task/motion/io 状态入口；`task`、`motionStatus`、`rcsStatus`、`taskTopLevelStatus` 等旧顶层字段不再输出。

## 功能范围

本阶段要实现或准备实现：

1. 在 WASM task runtime 内建立 `EMC_STAT` 等价状态容器。
2. 将 minimal motion runtime 的状态导入 `EMC_STAT.motion` 等价快照。
3. 重排 `lctask_run_cycles()`，使每个 task 周期符合上游主循环顺序。
4. 把 wait-for-motion、motion queue、pause/step/resume、abort/error 逻辑改为依赖 motion 快照。
5. 增加测试证明 task 周期内读取 motion，而不是只在 status API 读取时拼接 motion。
6. 分阶段引入 vendored/upstream task 源码，减少自有状态机语义。

## 最小字段闭环

第一阶段必须优先闭合以下字段，原因是它们直接参与 `emctaskmain.cc` 主循环、`emcTaskExecute()` 或顶层 status 聚合：

| 领域 | 字段 | 用途 |
| --- | --- | --- |
| task | `state`、`mode` | state/mode gate、power/home/run 前置 |
| task | `execState`、`interpState` | `emcTaskPlan()` 和 `emcTaskExecute()` 状态机 |
| task | `currentLine`、`readLine`、`motionLine` | interpreter/motion line 对齐 |
| task | `task_paused` | pause/resume/step |
| motion | `status` | wait-for-motion、error、top-level status |
| motion.traj | `enabled`、`inpos`、`queue`、`activeQueue`、`queueFull` | motion wait、queue gate、disable edge |
| motion.traj | `id`、`paused`、`single_stepping` | stepping、motion id、pause |
| motion.traj | `position`、`actualPosition`、`current_vel` | UI/status、interpreter sync |
| motion | `on_soft_limit` | soft-limit error path |
| io | `status`、`aux.estop` | subordinate sync、top-level status |

完整字段映射详见 `07-emctaskmain周期对标蓝图.md`。

后续 WASM 核心状态机完善路线详见 `11-WASM核心状态机边界与后续完善路线.md`。

## 非目标

本阶段不做：

- 驱动真实硬件。
- 浏览器内复刻 LinuxCNC 原生多进程拓扑。
- 移植 native GUI。
- 用 JavaScript 重写 CNC/task/motion 语义。
- 一次性完整移植 realtime motion controller。

## 完成定义

阶段完成至少满足：

- 文档记录 task 主循环对标范围、步骤、任务矩阵和验收证据。
- 新增测试能区分“task 周期读取 motion”和“status API 拼接 motion”。
- `lctask_run_cycles()` 内存在清晰的 LinuxCNC 式周期结构。
- `nativeTaskReady`、`nativeHalSyncReady`、`fullLinuxCncProgramExecutionReady` 等 readiness 字段与真实能力一致。
- 现有 WASM task/motion/HAL smoke 不回退。
- `lctask_send_command_json()` 不再直接产生 LinuxCNC task 语义变化；语义变化必须由后续 `lctask_run_cycles()` 的 command read/plan/execute 阶段产生。
- `lctask_read_status_json()` 不推进、不同步、不重新读取 motion；它只导出最后一次 status write 的快照。