linuxcncWebWASM/docs/linuxcnc-web-wasm-integration-playbook.md

# LinuxCNC Web/WASM 仿真移植总控执行手册

**文档状态**：Draft v0.1
**用途**：统一功能完整性、任务执行、依赖、测试、接续和里程碑验收
**固定基线**：LinuxCNC `2.10.0~pre0`，以 `linuxcnc/VERSION` 和 context lock 为准
**架构路线**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)
**完整实施蓝图**：[完整仿真机床实施蓝图](linuxcnc-web-wasm-full-port-implementation.md)
**运动学主线**：[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)
**源码目录**：[功能与源程序关联目录](linuxcnc-web-wasm-source-map.md)
**前端/通信**：[前端与 LinuxCNC 通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)
**覆盖验收**：[仿真全功能覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)
**治理规则**：[项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)
**最小任务与上下文**：[上下文治理与最小任务目录](linuxcnc-web-wasm-context-governance.md)

本手册是专项设计文档的总控入口。完整实施蓝图规定单个仿真入口如何启动和推进；本手册不替代这些专项文档，而是规定它们如何组合、谁负责什么、任务如何进入执行、依赖如何推进、失败如何恢复以及什么证据才能声明移植完成。

## 1. 当前审计结论

当前工作区已经形成完整的设计基线，并已落地 M0/M1 的实施前置产物。当前状态必须按代码证据标记为：

```text
设计基线：已建立
源码/功能清单：`coverage/source-index.jsonl` 和 `coverage/manifest.jsonl` 已生成，全部条目仍待归并
运行时实现：`wasm-core` ABI bootstrap 及部分 posemath/解释器/运动切片已编译，LinuxCNC 全量核心尚未接入
前端实现：未开始或尚未进入当前工作区
全功能验收：未开始，不得声明已完成
```

这是当前交付边界：后续任务从 M1/WS-1 的 ABI、原生 runner、固定 tick 和工作区契约继续；M0 清单重生成和哈希校验仍是每次基线变化的前置步骤。任何演示页面、mock Worker 或单一三轴样例都不能把项目状态提前改成“全功能完成”。

上下文治理的可执行入口是 `scripts/context_packet.py`、`scripts/validate_task_pointer.py`、`scripts/validate_model_budget.py` 和 `scripts/model_stream.py`，测试是 `scripts/test_context_packet.py`、`scripts/test_model_stream.py` 及对应校验器单测，任务拆分和分层读取以[上下文治理与最小任务目录](linuxcnc-web-wasm-context-governance.md)为准。模型预算校验还必须传入当前请求的 `--overhead-tokens`；连续任务从最新包重建，不累加旧对话。请求前校验输入、固定开销、输出预留和安全余量，请求后用 `validate_provider_response` 校验 provider usage；流式断开、上下文超限、usage 异常和截断响应只写 metadata-only checkpoint，不拼回下一轮。当前仓库已有可独立验证的核心切片，但尚未形成完整 LinuxCNC 运行时；上下文生成、启动指针、模型请求预算和流式恢复测试已经可以独立运行；CI 应在任何任务证据包生成或模型请求前调用相应脚本。

## 2. 唯一追踪链

所有工作都必须沿下面的链路登记，任何断点都会阻止对应条目进入 `accepted`：

```text
LinuxCNC source/config/test
        ↓ source_id + source_sha
feature_id / capability_id
        ↓ dependencies + protocol_messages + state_fields
WASM/Worker/UI task_id
        ↓ implementation commit + fixed context packet
test_id / scenario_id / oracle_id
        ↓ logs + golden + difference + performance evidence
milestone_id + gate_id + release report
```

### 2.1 记录归属

| 记录 | 规范入口 | 解决的问题 | 不允许替代它的东西 |
|---|---|---|---|
| 架构和范围 | 技术路线 | 做什么、边界在哪里 | 单个任务说明 |
| 源文件和符号 | 源程序关联目录 | LinuxCNC 哪些文件必须审查/适配 | 目录级“已处理” |
| 功能和覆盖 | 覆盖矩阵/manifest | 每项行为如何验收 | 演示成功截图 |
| UI 和通信 | 前端通信设计 | 前端、Worker、WASM 如何协作 | 直接跨层调用 |
| 执行和门禁 | 执行与交付策略 | 上下文、恢复、提交和发布规则 | 临时口头约定 |
| 证据 | CI/发布产物 | 结果能否复现、定位和回滚 | “本地跑过”描述 |

## 3. 总体分工和责任边界

角色是责任类别，不预设具体人员；每个变更必须有一个 DRI（直接负责人）和至少一个独立审查角色。

| 责任域 | 主责任（DRI） | 复核角色 | 主要产物 | 不得越界 |
|---|---|---|---|---|
| 基线与清单 | WS-0/兼容性 | 发布/测试 | source map、manifest、context lock | 不直接实现功能 |
| 核心行为 | WS-1/WASM | 原生 LinuxCNC/测试 | C ABI、解释器、TP、motion、kinematics | 不把 UI 预期当行为定义 |
| Worker/虚拟设备 | WS-2/运行时 | 核心/持久化 | scheduler、HAL、IO、故障模型、事件 | 不直接改 React 状态 |
| Workspace/恢复 | WS-3/存储 | 运行时/安全 | POSIX 适配、journal、checkpoint、迁移 | 不改变运动算法 |
| Python/插件 | WS-4/脚本兼容 | 安全/核心 | Pyodide 模块、remap、VCP 权限 | 不暴露宿主能力 |
| 前端/可视化 | WS-5/FE 任务 | 通信/UX/测试 | UI、WorkerClient、3D、配置工作流 | 不读取 WASM 指针或直接写 OPFS |
| 参考与回归 | WS-6/测试 | 各域 DRI | native runner、WASM golden、浏览器/故障矩阵 | 不删除失败样本来变绿 |
| 发布/文档 | WS-7/发布 | 全部域 | 兼容报告、许可证、离线包、回滚包 | 不绕过门禁 |

协议、快照、工程格式、能力模型和错误码是跨域契约。任何一个域需要读取另一个域的内部结构时，必须先创建 C2 契约变更；禁止通过复制结构或共享未版本化对象解决问题。

## 4. 依赖图和并行策略

```text
M0 / WS-0 基线、source map、manifest、context lock
 ├─ WS-6 原生参考运行器和 golden 格式
 ├─ WS-1 WASM 核心、C ABI、解释器、TP、motion、kinematics
 │    └─ WS-2 Worker scheduler、HAL、IO、虚拟设备
 │         ├─ WS-3 Workspace/OPFS 恢复集成
 │         ├─ WS-4 Python/remap/VCP 集成
 │         └─ WS-5 前端/可视化集成
 └─ COM-01/05 协议和能力模型
      └─ COM-02/03/04 Worker 通信、账本、快照和 NML 映射
           └─ FE-01..10 前端工作流
                         ↓
             WS-6 全量回归 → WS-7 发布
```

可并行：来源扫描、协议类型、原生 runner、AppShell、静态 UI 原型和文档检查。必须串行：同一仿真会话的 tick/命令/HAL/OPFS 写入，协议语义冻结后的破坏性变更，恢复账本重放，以及同一 golden 的生成和验收。并行只能减少验证时间，不能改变仿真事件顺序。

## 5. 统一任务目录

专项文档中的 FE/COM 任务继续作为前端和通信的详细任务；核心、存储、测试和发布任务使用以下统一编号。

### 5.1 WS-0 基线和清单

| ID | 任务 | 输入 | 输出/完成证据 |
|---|---|---|---|
| INV-01 | 扫描文档、源码、符号、配置、组件和测试 | source map、LinuxCNC 基线 | 来源索引、扫描器版本、排除规则 |
| INV-02 | 生成 `coverage/manifest.jsonl` | 来源索引、coverage 规则 | 每个来源的 feature、依赖、oracle、测试和状态 |
| INV-03 | 建立 context lock | 源码/编译器/Python/schema/浏览器 | 可重建锁文件和摘要 |
| INV-04 | 建立原生参考 runner | configs/sim、tests、unit_tests | native 状态/canonical/HAL/IO/golden 格式 |
| INV-05 | 建立影响图和差异报告格式 | manifest、协议、测试 | source→feature→task→test→evidence 索引 |
| INV-06 | 固定上下文包生成器和预算测试 | 任务摘要、候选证据 | 预算前移选择、稳定排除码、必需项失败和生成器单测 |

### 5.2 WS-1 WASM 核心和 ABI

| ID | 任务 | 输入 | 输出/完成证据 |
|---|---|---|---|
| CORE-01 | 独立 CMake/Emscripten 工程 | source map、编译锁 | `wasm-core` 可重复构建 |
| CORE-02 | C ABI 和错误码 | frontend communication design | `sim_create/load/command/step/snapshot/event/export/import/destroy` |
| CORE-03 | rs274ngc/参数/O-code/remap | `src/emc/rs274ngc/**` | 解释器 golden 和错误定位 |
| CORE-04 | TP/posemath/几何 | `src/emc/tp/**`、posemath | canonical、轨迹和容差报告 |
| CORE-05 | Task/NML/状态 | `src/emc/task/**`、nml_intf、libnml | message bus 和状态快照 |
| CORE-06 | Motion/homing/limit | `src/emc/motion/**` | jog、home、limit、following error |
| CORE-07 | Kinematics 全集 | `src/emc/kinematics/**` | 按[K0-K8 运动学主线](linuxcnc-web-wasm-kinematics-migration-plan.md)执行；静态模块、能力注册、姿态 golden |
| CORE-08 | Tooldata/IO 基础 | `src/emc/tooldata/**`、iotask | 工具、主轴、换刀、IO 状态 |

### 5.3 WS-2/WS-3/WS-4 运行时集成

| ID | 任务 | 依赖 | 输出/完成证据 |
|---|---|---|---|
| RT-01 | 固定 tick scheduler、批量 step、暂停/单步 | CORE-02/04/05 | 1x/快速/单步结果一致 |
| RT-02 | HAL 对象、thread/function、组件 manifest | CORE-05 | `.comp` 全量索引和 HAL golden |
| RT-03 | 虚拟轴/编码器/主轴/探针/限位/换刀 | RT-02、CORE-06/08 | 正常和故障注入可录制 |
| RT-04 | ClassicLadder/虚拟寄存器 | RT-02 | ladder/scan/IO 交互结果 |
| FS-01 | WasmFS/POSIX 工作区挂载 | INV-02、CORE-03 | open/read/write/stat/readdir 等价测试 |
| FS-02 | OPFS journal/事务/配额 | FS-01 | prepare/commit、损坏和配额恢复 |
| FS-03 | checkpoint/增量重放/迁移 | FS-02、CORE-02 | 连续与恢复终点相同 |
| PY-01 | Pyodide 虚拟 linuxcnc/hal/INI | CORE-03、FS-01 | API/异常/资源限制对照 |
| PY-02 | remap/filter/VCP 生命周期和权限 | PY-01、RT-02 | Python、HAL、UI 回调闭环 |
| COM-01..06 | 协议、账本、快照、NML、能力和浏览器测试 | CORE-02、RT-01、FS-02 | 详见前端通信设计 |

### 5.4 WS-5/WS-6/WS-7 交付

| ID | 任务 | 依赖 | 输出/完成证据 |
|---|---|---|---|
| FE-01..10 | UI、WorkerClient、程序、控制台、HAL/PLC、3D、插件和性能 | COM、RT、FS | 详见前端通信设计 |
| REG-01 | 全量 configs/sim 运行矩阵 | INV-02、CORE/RT/PY | 每个入口有结果和差异 |
| REG-02 | 全量 tests/unit_tests 对照 | INV-04、WASM runner | 通过/排除/阻断逐项报告 |
| REG-03 | 断网、崩溃、回答失败、租约和恢复矩阵 | FS-02/03、COM-02 | 无重复副作用、无静默丢失 |
| REG-04 | 浏览器/性能/视觉矩阵 | FE、COM-03 | Chromium/Firefox/Safari、P95/P99、截图/像素 |
| REL-01 | 兼容、许可证、迁移、回滚和离线包 | 全部 REG | 发布候选证据包和签名报告 |

### 5.5 运动学主线 K0-K8

运动学不再作为 CORE-07 的单个串行任务处理。K0-K8 是从来源审计到发布闭合的硬门，详细输入、算法族和测试矩阵见[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)。

| 主线阶段 | 解锁范围 | 对整体项目的门禁 |
|---|---|---|
| K0 | 源文件、符号、配置入口、native FK/IK 样本和缺失输入 | 未闭合时不得声明任何非 trivkins 配置可运行 |
| K1 | C ABI、pose/joint 映射、flags、数值/迭代策略 | 未闭合时 motion 只能保留 bootstrap，不得接入全量算法 |
| K2 | trivkins 全类型、重复轴、extra joints、corexy/rose/max/rotate | 未闭合时不得验收 axis/joint 模式、HAL 耦合或恢复 |
| K3 | 5 轴 TRT、SCARA/PUMA/Scorbot/GenSer | 未闭合时不得验收刀尖跟随、机器人和 5 轴可视化 |
| K4 | Delta、RotaryDelta、Tripod、Hexapod、Pentapod | 未闭合时不得验收并联机构、迭代正解和 Vismach |
| K5 | switchkins、userk/ugenser 静态扩展和能力注册 | 未闭合时不得加载切换或用户运动学配置 |
| K6 | TP→IK→motion→FK feedback、home/limit、IO/数字孪生 | 未闭合时 M3 运动故障和恢复场景不具备发布资格 |
| K7 | Three.js 姿态、全配置回归和浏览器故障矩阵 | 未闭合时 M4 UI 只能作为结构原型 |
| K8 | 兼容、迁移、许可证、来源和回滚闭合 | 未闭合时 M5 不能进入发布候选 |

## 6. 里程碑总表

| 里程碑 | 入口条件 | 必须完成 | 退出证据 | 失败动作 |
|---|---|---|---|---|
| M0 基线锁定 | 版本和范围确认 | INV-01..05、状态枚举、责任人 | source/manifest/context lock 可重建，零孤儿规则生效 | 返回清单阶段，不写运行时代码 |
| M1 运行时骨架 | M0 通过 | CORE-01/02、RT-01、FS-01、COM-01/02 最小集 | create/load/command/step/snapshot/recover、离线缓存启动 | 固定 ABI/schema，修复后重跑 M1 |
| M2 核心行为 | M1 通过，K0 入口审计完成 | CORE-03..08、K0-K5、native/WASM runner、解释/轨迹/运动 golden | 核心 manifest `verified`，每个运动学族的首个差异 tick 可定位 | 回退到对应 K/核心任务，不进入 UI 全量 |
| M3 虚拟设备和恢复 | M2 通过，K6 完成 | RT-02..04、FS-02/03、PY-01/02、COM-03..05、运动学数字孪生 | HAL/PLC/IO/故障/配额/重启/断网矩阵通过 | 阻断仿真会话发布，保留本地证据 |
| M4 前端工作流 | M3 通过 | FE-01..10、COM-06、关键 UI/3D/配置工作流 | UI 条目有协议、源文件、测试、oracle 和恢复证据 | 禁止 mock 冒充完成，回退 FE/COM |
| M5 发布候选 | M0..M4 通过 | REG-01..04、REL-01 | G0-G5 全绿、全计入条目 `accepted`、排除项可识别 | 维持候选冻结，创建修复 context 或回退 |

里程碑退出不按日期判断，而按证据判断。契约或基线变化必须回退到最早受影响里程碑；不能在 M5 以“后续补齐”方式接受未完成条目。

## 7. 端到端场景验收

| 场景 | 覆盖链 | 必须验证 |
|---|---|---|
| S1 最小三轴启动 | INI→WASM→Worker→UI→OPFS | 能力协商、配置错误、初始快照、停止/销毁 |
| S2 G-code 正常运行 | rs274ngc→canonical→TP→motion→轨迹/UI | 当前行、模态、坐标、轨迹、最终状态和 golden |
| S3 MDI/jog/home | UI command→Task/Motion→HAL/IO | pending/ack/result、释放保护、模式非法转换 |
| S4 主轴/换刀/探针 | iotask/tooldata→虚拟设备→HAL→UI | 正常、不到速、失败、超时、恢复 |
| S5 Python/remap/VCP | Python plugin→HAL/Task→UI | 参数/异常/权限/资源限制和状态哈希 |
| S6 ClassicLadder/HAL | component/PLC→thread→IO→scope | 扫描顺序、pin graph、触发、回放和故障 |
| S7 断网继续 | Service Worker→Worker→OPFS | 无网启动、中途断网、离线保存、重新联网对账 |
| S8 崩溃/回答失败 | TaskLedger→checkpoint→replay | 已确认不重复、未确认不跳过、无法对账时阻断 |
| S9 多浏览器/大负载 | FE/COM→流控→渲染 | P95/P99、背压、内存、UI 长任务和最终状态 |

每个场景产出一个固定大小上下文包、运行日志摘要、source/feature/task/test 索引、状态哈希和可重跑命令。只通过截图或人工点击成功的场景不算验收证据。

## 8. 任务执行规程

### 8.1 开始前

1. 从最小任务目录选择一个单结果子任务，读取最新 context lock 和固定八段上下文包；确认 `context_id`、子任务、主工作流和里程碑一致。上下文包由 `scripts/context_packet.py` 生成，不能手工拼接。
2. 读取 source map/coverage manifest 中的受影响条目，确认输入、依赖、协议、oracle 和非目标。
3. 写明预计变更类型 C0-C3、失败恢复点、回滚提交和测试命令。
4. 若任务跨越三个以上工作流，先拆分；若需要修改协议或格式，先提交 C2 方案。

### 8.2 执行中

1. 先添加失败测试或差异记录，再实现正常路径；不要先删除/放宽测试。
2. 运行受影响图的快速测试，同时保留完整证据路径；独立测试可并行，同一会话必须串行。
3. 每个副作用操作遵循 prepare/execute/verify/commit；回答或工具失败先查账本和产物，不盲目重做。
4. 只更新固定上下文包的对应段，旧历史以摘要/哈希引用；超预算就拆任务。

### 8.3 完成时

任务只有在代码、manifest 状态、自动测试、差异报告、性能/配额影响和文档引用都更新后才能标记完成。合并请求必须包含 `Context-ID`、`Context-Packet`、Scope、Contract-Change、Evidence、Offline-Impact、Coverage 和预算声明。

## 9. 统一完成定义

### 功能完成

- 源程序关联目录中没有孤儿来源、未解析符号或未闭合依赖。
- 所有可计入功能条目达到 `accepted`；每项有实现、测试、oracle、差异和 context lock。
- 正常、边界、错误、暂停/恢复、持久化/离线和适用交互维度全部通过。
- `REAL-EXCLUDED` 只用于真实硬件、实时内核和安全认证，且配置检查返回明确错误；仿真可观察行为仍有数字孪生实现。

### 任务完成

- DRI、审查人、依赖、非目标、回滚点和固定上下文包齐全。
- 未确认操作可安全恢复；重复提交不造成重复副作用；失败原因和下一步可执行。
- 测试、日志、golden、差异、性能和文档链接均可重跑。

### 发布完成

- G0-G5 全部通过；浏览器、离线、恢复、性能、安全、许可证和迁移报告齐全。
- 发布包包含 WASM、Pyodide、Service Worker、协议 schema、source/coverage/golden manifest、兼容报告、排除项清单和回滚包。
- 任何孤儿来源、未覆盖交互、无 oracle、静默降级、半提交数据或超预算上下文都会阻止发布。

## 10. 风险账本和停止线

| 风险 | 触发条件 | 立即动作 | 恢复条件 |
|---|---|---|---|
| 来源遗漏 | source map 与 manifest 数量/哈希不一致 | 停止实现合并，回到 M0 | 重新扫描、补关联、重生成影响图 |
| 核心差异 | 首个 divergent tick、错误码或状态字段不一致 | 冻结受影响域，保留 golden | 定位源文件/编译差异并重跑 |
| 协议漂移 | UI/Worker/C ABI schema 不一致 | 拒绝握手，不能自动降级 | 新版本契约、迁移和双向测试 |
| 数据损坏 | journal 无 commit、哈希不匹配、配额失败 | 保留旧版本，进入恢复/导出 | 完整 commit 或明确阻断 |
| 非确定性 | 同输入同 context 结果不同 | 禁止性能优化合并 | 固定顺序、种子、线程和时钟后重跑 |
| 性能退化 | P95/P99 或 UI 长任务超预算 | 阻止里程碑 | profiling、优化和回归证据 |
| 任务失联 | 固定上下文缺失、无 DRI、无下一步 | 任务标记 blocked | 补齐上下文和负责人，不复制历史 |

## 11. 文档维护规则

新增 LinuxCNC 源文件、配置、G/M/O、HAL 组件、Python API、UI 工作流、协议消息或测试时，必须同时检查：

1. 源程序关联目录是否新增 `source_files/source_symbols/config_inputs`。
2. 覆盖矩阵是否新增 `feature_id`、状态、测试维度、oracle 和差异字段。
3. 前端通信设计是否新增命令、事件、快照字段、能力或 UI 工作流。
4. 执行策略是否需要新增工作流、任务、门禁、恢复场景或上下文锁字段。
5. 技术路线是否需要更新依赖、阶段、风险或代码组织。

6. 若任务新增证据类型，生成器是否为其提供字节大小、优先级、必需性和稳定排除码；是否增加“证据字节预算”和“完整包剩余空间”测试。

文档检查必须验证本地链接、编号、状态枚举、manifest 字段、任务引用和里程碑映射。文档通过不代表代码完成；代码通过也不能绕过文档和 manifest 关联。