cnc_wams/wasm-port/working/02-项目程序开发详细步骤.md

02-项目程序开发详细步骤

阶段 0：基线固定

1. 记录当前实现与 LinuxCNC 主循环差距。
2. 固定当前通过的 smoke：
   • ./tools/verify_task_hal_source_manifest.sh
   • ./tests/wasm/node/verify_motion_hal_sync.sh
   • ./tests/wasm/node/verify_task_hal_wasm.sh
   • ./tests/wasm/node/verify_task_hal_sdk.sh
3. 记录当前已知阻塞和 readiness：
   • ./tests/native/verify_task_hal_phase0.sh 曾因上游运行目录缺少 xyzac-trt_cmds.hal 失败，T-016 已通过运行目录 machine overlay 修复该 probe 输入完整性。
   • task-hal source manifest 仍显示 task_hal_runtime_promoted=0，不代表 full native task/HAL runtime 已 promoted。

阶段 1：建立 task 周期内 motion snapshot

1. 在 linuxcnc_task_hal_wasm.cpp 中新增 task runtime 内部 motion snapshot。
2. 在 linuxcnc_motion_runtime.h 中定义 LcmotStatusSnapshot，字段至少覆盖：
   • cycle、program_line、motion_id、status、in_position、paused、stepping、aborted；
   • queue_count、queue_capacity、queue_full、active_depth；
   • axis/joint command/feedback；
   • requested/current velocity；
   • switchkins/analog outputs。
3. 从 linuxcnc_motion_runtime.c 暴露结构化读取函数，避免 task 周期内解析 JSON。
4. 在 linuxcnc_task_hal_wasm.cpp 中新增 wasm_emcMotionUpdate()，把 LcmotStatusSnapshot 映射到 task 持有的 EMC_STAT.motion 等价结构。
5. 在每个 lctask_run_cycles() task 周期调用 motion snapshot update。
6. 将 status JSON 改为读取 task 内已更新的 snapshot，而不是独立拼接最新 motion JSON。
7. 新增测试：
   • 队列中 motion 状态变化必须在 runCycles() 后反映到 task status。
   • 不调用 runCycles() 时，仅调用 status API 不应推进 task 周期语义。
   • 直接调用 low-level lcmot_step_servo() 后，task status 不应自动更新，直到下一次 lctask_run_cycles()。

阶段 2：重排 lctask_run_cycles() 周期顺序

目标顺序：

1. task heartbeat / cycle 自增。
2. command read：从 staged command queue 或 C ABI command slot 取命令。
3. plan：处理模式、run、pause、resume、mdi、home、abort 等 task plan 行为。
4. execute：根据 task exec state 向 motion/io 发命令或等待 motion/io 完成。
5. motion update：读取 motion runtime snapshot 到 task 状态。
6. subordinate sync：处理 estop、motion error、io error、soft limit、abort cleanup 等。
7. task update：刷新 task-specific status。
8. status write：更新 C ABI 可读 status snapshot。
9. servo step：按 standalone WASM 边界推进 deterministic servo cycles。

注意：上游 LinuxCNC 是 native process/realtime 拓扑，WASM 内的 servo step 位置允许作为 standalone runtime 边界记录在决策里，但 task 对外语义必须说明与上游差异。

建议拆成内部函数，避免把所有逻辑堆回 lctask_run_cycles()：

static void task_cycle_begin(TaskRuntime &state);
static bool task_read_command(TaskRuntime &state);
static int wasm_emcTaskPlan(TaskRuntime &state);
static int wasm_emcTaskExecute(TaskRuntime &state);
static int wasm_emcMotionUpdate(TaskRuntime &state);
static void sync_subordinate_states(TaskRuntime &state);
static void wasm_emcTaskUpdate(TaskRuntime &state);
static void update_top_level_status(TaskRuntime &state);
static void write_status_snapshot(TaskRuntime &state);

每个函数必须在注释或文档中标明对应的上游 emctaskmain.cc 行为。

阶段 3：引入 EMC_STAT 等价状态容器

1. 对齐 EMC_STAT.task、EMC_STAT.motion、EMC_STAT.io 中本阶段需要的字段。
2. 识别上游真实定义来源：
   • enum 和函数声明主要在 emc.hh；
   • EMC_STAT、EMC_TASK_STAT、EMC_MOTION_STAT、EMC_TRAJ_STAT 真实字段在 emc_nml.hh。
3. 优先复用 vendored emc_nml.hh/emc.hh 类型；如依赖过重，建立字段同名、语义同向的窄 StandaloneEmcStatus，并记录差异。
4. 把 TaskRuntime 中重复字段逐步映射到 EMC_STAT.task。
5. 把 lcmot motion status 映射到 EMC_STAT.motion。
6. 初始 IO 可用 shim 固定 DONE，但必须具备 status、aux.estop、fault、reason 字段。
7. 确保 JSON status 只是 EMC_STAT 或等价 status buffer 的导出视图。

阶段 4：迁移 wait/execute 语义

1. 对标 emcTaskExecute() 的关键状态：
   • DONE
   • WAITING_FOR_MOTION_QUEUE
   • WAITING_FOR_MOTION
   • WAITING_FOR_IO
   • WAITING_FOR_MOTION_AND_IO
   • WAITING_FOR_DELAY
   • WAITING_FOR_SYSTEM_CMD
   • ERROR
2. 先迁移 motion 相关状态，不急于实现 system command/process。
3. queueFull、motion.status、io.status 的判断必须从周期 snapshot 读取。
4. pause/step/resume 的状态变化必须覆盖现有 smoke。

阶段 5：逐步替换自有状态机

1. 把当前 JSON command 分派收缩为 host/C ABI 边界。
2. lctask_send_command_json() 不直接修改 state/mode/interp/exec，而是入队 command envelope。
3. 在 command read 阶段消费 envelope，生成 LinuxCNC task command 等价物。
4. 把 task plan/execute 语义迁向 vendored/upstream emctask.cc、taskintf.cc、emccanon.cc。
5. 为 native-only/runtime-edge 功能建立 shim：
   • NML transport
   • file IO
   • process spawning
   • IO process
   • realtime HAL/thread scheduling
6. 每替换一段，补一条 matrix 任务和验收证据。

具体源码替换顺序见 08-上游task源码替换分解.md。实施时按以下顺序推进：

1. taskintf.cc minimal bridge：先替换 motion init/update/abort、traj pause/step/resume/linear move。
2. emctask.cc state/update/abort：替换 task state/mode/abort/update。
3. emctask.cc plan wrapper：接 interpreter open/read/execute/synch。
4. emccanon.cc straight motion：接 INIT_CANON()、FINISH()、STRAIGHT_TRAVERSE()、STRAIGHT_FEED()。
5. emctaskmain.cc execute 分支：用 interp_list 和 taskintf issue command。
6. emccanon.cc spindle/tool/io 子集：dwell、switchkins、tool/spindle command。

阶段 6：readiness 和文档收口

1. 修正文档、代码、测试中的 readiness 口径。
2. nativeTaskReady 只有在真实 vendored/native task 周期被采用后才能为 true。
3. nativeHalSyncReady 只有在 HAL 同步达到对应验收后才能为 true。
4. fullLinuxCncProgramExecutionReady 只有在完整 program execution 语义闭合后才能为 true。
5. 更新 docs/source-reuse-map.md，避免文档声称与实现不一致。

阶段 7：后续 WASM 核心状态机完善

本阶段用于后续新增任务，不改变 T-001 到 T-049 的闭合状态。实施前必须先在 04-任务矩阵.md 新增任务编号、状态、验收标准和 gate。

1. 坚持 WASM/C++ 为核心状态机实现：
   • task/motion 状态机、周期调度、状态聚合、命令执行进入 C/C++。
   • StandaloneEmcStatus 或后续 EMC_STAT 等价容器是 status 事实源。
   • LcmotStatusSnapshot 是 task 周期读取 motion 的结构化输入。
2. 保持 JS/SDK 为 host 边界：
   • JS/SDK 可以加载 WASM、写入文件、入队 command、读取 status。
   • JS/SDK 不实现 G-code、task、motion、planner 或 canon 语义。
3. 保持 JSON 为通信格式：
   • command JSON 只描述 host command envelope。
   • status JSON 只导出最后一次 status write。
   • 不允许新增依赖 JSON 文本推进 task cycle 的路径。
   • 新增 status 字段优先进入 emcStatus 对标对象，再按需提供旧字段兼容视图。
4. 每次迁移新语义时优先查找 vendored LinuxCNC source：
   • 能接入 source-anchored subset 时接入 subset。
   • 不能直接接入时建立窄 shim，并在 06-决策记录.md 写明原因。
5. 每次新增状态字段时同步更新：
   • C/C++ status 结构体。
   • status JSON 导出。
   • WASM smoke。
   • SDK smoke。
   • state matrix。
   • source reuse/drift docs gate。

详细边界和检查清单见 11-WASM核心状态机边界与后续完善路线.md；status JSON 字段映射、禁止链路和后续 SJ 批次见 12-status-json-LinuxCNC对标方案.md。