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

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

文档状态：Draft v0.1 用途：统一功能完整性、任务执行、依赖、测试、接续和里程碑验收 固定基线：LinuxCNC 2.10.0~pre0，以 linuxcnc/VERSION 和 context lock 为准 架构路线：技术路线 源码目录：功能与源程序关联目录 前端/通信：前端与 LinuxCNC 通信详细设计 覆盖验收：仿真全功能覆盖矩阵 治理规则：项目执行与交付策略 最小任务与上下文：上下文治理与最小任务目录

本手册是五份设计文档的总控入口。它不替代各专项文档，而是规定它们如何组合、谁负责什么、任务如何进入执行、依赖如何推进、失败如何恢复以及什么证据才能声明移植完成。

1. 当前审计结论

当前工作区已经形成完整的设计基线：技术路线、源码关联、覆盖矩阵、前端通信设计和执行治理均已建立，并且互相有链接。当前工作区尚未出现 wasm-core/、web/、tests/golden/、tests/browser/ 等实际 Web/WASM 运行时代码目录，因此当前状态只能标记为：

设计基线：已建立
源码/功能清单：规则已建立，待生成机器 manifest
运行时实现：未开始或尚未进入当前工作区
前端实现：未开始或尚未进入当前工作区
全功能验收：未开始，不得声明已完成

这不是缺陷，而是交付边界：后续任务必须从 M0/WS-0 开始，先生成可重建的来源和覆盖清单，再实现运行时代码。任何演示页面、mock Worker 或单一三轴样例都不能把项目状态提前改成“全功能完成”。

上下文治理的可执行入口是 scripts/context_packet.py，测试是 scripts/test_context_packet.py，任务拆分和分层读取以上下文治理与最小任务目录为准。当前仓库没有运行时实现，但上下文生成和预算测试已经可以独立运行；后续 CI 应在任何任务证据包生成前调用该脚本。

2. 唯一追踪链

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

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. 依赖图和并行策略

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/**	静态模块、能力注册、姿态 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	发布候选证据包和签名报告

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 通过	CORE-03..08、native/WASM runner、解释/轨迹/运动 golden	核心 manifest verified，首个差异 tick 可定位	回退到对应核心任务，不进入 UI 全量
M3 虚拟设备和恢复	M2 通过	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 关联。