项目整体完成情况与后续执行铁律

生成时间：2026-06-17 CST

本文件接替 `text16.txt`，作为后续继续推进的接续文件。后续工作优先参考
`test17.txt`；除非明确要求审计旧记录，不再回到 `text1` 到 `text16` 扩展进度。

一、当前核心完成情况

1. LinuxCNC-backed WASM 核心仍是 CNC 语义来源。

- G-code 执行、canonical event、interpreter/planner 语义仍来自 vendored LinuxCNC
  C/C++ 源码编译出的 WASM；
- Browser/UI/SDK 只做 host boundary、文件装载、OPFS/session、virtual HAL runtime、
  仿真状态桥、测试胶水和报告；
- 不在 JS 中重写 G-code 解释器、planner、kinematics、tool/parameter 语义。

2. Web 数控仿真系统已经具备完整虚拟 HAL 闭环。

当前 virtual HAL 已提升为项目级 SDK/API 能力，并接入 browser simulation 页面。

已具备：

- source-derived HAL pin family registry；
- axisui / halui / iocontrol / motion / axis / joint / spindle / coolant / tool pin
  inventory；
- pin/signal/param/net store；
- HAL read/write API；
- virtual halcmd；
- virtual realtime HAL runtime report；
- virtual motion controller servo step；
- WASM HAL bridge snapshot；
- diagnostics artifact；
- browser page API；
- Node/browser smoke gate。

3. 仿真级 LinuxCNC realtime HAL / halcmd / motion controller 已由 virtual HAL 替代。

已新增/确认的核心 API：

- `VIRTUAL_HAL_SIMULATION_REPLACEMENT_TARGETS`：
  - `linuxcnc-realtime-hal`；
  - `halcmd`；
  - `motion-controller`；
- `VIRTUAL_HAL_SIMULATION_RUNTIME_CAPABILITIES`：
  - `realtime-hal-simulation-replacement`；
  - `halcmd-simulation-replacement`；
  - `motion-controller-simulation-replacement`；
  - `hal-pin-signal-param-store`；
  - `halcmd-setp-sets-net-show-getp-gets`；
  - `servo-period-motion-step`；
  - `axis-joint-position-feedback`；
- `executeVirtualHalcmd()`；
- `executeVirtualHalCommand()`；
- `stepVirtualHalMotion()`；
- `stepVirtualHalMotionController()`；
- `createVirtualHalSimulationRuntimeReport()`；
- `createVirtualHalSimulationReplacementReport()`；
- `createLinuxCncVirtualHalRuntime()`：
  - `executeHalcmd()`；
  - `stepMotion()`；
  - `stepMotionController()`；
  - `getSimulationRuntimeReport()`；
  - `getSimulationReplacementReport()`。

Browser simulation API 已暴露：

- `executeVirtualHalcmd()`；
- `executeVirtualHalCommand()`；
- `stepVirtualHalMotionController()`；
- `getVirtualHalSimulationRuntimeReport()`；
- `getVirtualHalSimulationReplacementReport()`；
- `getVirtualRealtimeHalRuntimeReport()`。

4. 当前 Web 仿真可满足数控系统仿真用途。

在 Web 方式下，数控系统仿真不再依赖 host LinuxCNC `halcmd`、host realtime HAL
process 或 host motion process 完成仿真闭环。当前 virtual HAL 可支撑：

- AXIS-style manual controls；
- ESTOP / power / home / jog；
- spindle / coolant / brake / override；
- HAL pin read/write；
- HAL net/signal/param；
- virtual halcmd 脚本执行；
- motion target stepping；
- DRO / limits-home / machine status；
- diagnostics / release report；
- browser smoke 和 Node smoke 自动验证。

二、虚拟 HAL 铁律

以下规则是后续推进的硬性约束，不能为了进度绕过。

1. 虚拟 HAL 功能来源铁律。

虚拟 HAL 的功能定义、pin family、pin 名称、pin 方向、pin 类型、状态含义、行为目标、
报告口径和仿真能力边界，必须完全来源于 LinuxCNC 源程序、vendored LinuxCNC 源码、
LinuxCNC 配置、LinuxCNC 脚本或已有 LinuxCNC-backed runtime evidence。

允许的来源包括但不限于：

- `linuxcnc/bin/axis`；
- `linuxcnc/src/emc/usr_intf/axis/scripts/axis.py`；
- `linuxcnc/src/emc/usr_intf/halui.cc`；
- `linuxcnc/src/emc/task/taskclass.cc`；
- `linuxcnc/src/emc/motion/motion.c`；
- `linuxcnc/src/emc/motion/axis.c`；
- `linuxcnc/src/emc/motion/homing.c`；
- `linuxcnc/src/emc/motion/motion.h`；
- vendored LinuxCNC `configs/sim`；
- vendored LinuxCNC tests；
- LinuxCNC-backed WASM/native probe 输出。

禁止：

- 凭空创造 LinuxCNC 不存在的 HAL pin、G-code 语义、planner 行为或 machine semantics；
- 为了 UI 便利修改 LinuxCNC CNC 语义；
- 用 JS/browser 重新解释 G-code；
- 把未由 LinuxCNC 源码或 runtime evidence 支撑的行为标成 LinuxCNC 兼容；
- 把 browser virtual HAL 伪装成 Linux kernel hard-realtime ABI。

2. Web 仿真满足性铁律。

在 Web 数控系统仿真范围内，virtual HAL 必须作为完整替代层满足：

- LinuxCNC realtime HAL 仿真替代；
- `halcmd` 仿真替代；
- motion controller 仿真替代；
- AXIS-style UI/manual control 仿真；
- diagnostics/report/gate 可验证性；
- SDK/API 可复用性。

后续任何 Web 仿真功能，如果需要 HAL、halcmd 或 motion process，默认必须接入
project-level virtual HAL runtime，而不是引入 host process 依赖。

3. 边界表述铁律。

对外描述必须同时满足：

- 可以明确说：virtual HAL 已完全满足 Web 方式数控系统仿真系统；
- 可以明确说：在仿真范围内，virtual HAL 已替代 LinuxCNC realtime HAL / halcmd /
  motion controller；
- 必须同时说明：它不是 Linux kernel hard-realtime ABI；
- 必须同时说明：它不替代外部硬件驱动 ABI、native HAL module ABI；
- 必须同时说明：G-code/interpreter/planner/canonical motion 语义仍来自 LinuxCNC-backed
  WASM。

三、当前已通过验证

最近关键验证：

```text
wasm-port/tests/sdk/node/verify_sdk_surface.sh
wasm-port/tests/ui/node/verify_real_simulation_programs.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
git diff --check
```

关键输出：

```text
sdk_surface_node_smoke=ok
project_release_gate_manifest_node_smoke=ok
project_release_artifact_url_workflow_node_smoke=ok
project_batch_acceptance_workflow_node_smoke=ok
project_batch_acceptance_artifact_node_smoke=ok
real_simulation_programs_node_smoke=ok
browser_real_simulation_page_smoke=ok
git diff --check ok
```

四、后续执行规则

1. 每轮开始前建议执行：

```bash
git status --short
git log -5 --oneline
tail -n 160 test17.txt
awk '/^[一二三四五六七八九十百]+、|^### / {print}' test17.txt | sort | uniq -d
```

2. 后续记录规则：

- 新进度只追加到 `test17.txt`；
- 每批只追加一个新的中文编号或 `###` 标题记录；
- 提交前检查标题唯一性；
- 不复制 `text16.txt` 的长历史；
- 不把局部重排、断言挪动、路径整理作为主目标；
- 每批必须产出至少一种可复用能力、可执行 gate、可验证 workflow 或明确 runtime
  boundary proof。

3. 后续优先级。

优先推进：

- virtual HAL 与更多 LinuxCNC sim configs 的 source-derived 覆盖；
- Web simulation 的完整 machine/session workflow；
- Browser diagnostics artifact 和 release gate；
- OPFS/session persistence 与 virtual HAL runtime state 的整合；
- HAL command script fixtures；
- motion controller 仿真测试矩阵；
- project release handoff 文档与 gate。

暂不推进：

- 原生 Linux kernel realtime ABI；
- 外部硬件驱动；
- native HAL module ABI；
- Python/Tcl UI process emulation；
- standalone JS G-code interpreter；
- 未有 LinuxCNC 源码证据的 CNC 语义扩展。