# LinuxCNC 纯 Web/WASM 仿真全功能覆盖矩阵（第一版）

**对应路线**：[LinuxCNC 纯 Web/WASM 仿真机床技术路线](linuxcnc-web-wasm-technical-roadmap.md)
**执行治理**：[LinuxCNC Web/WASM 仿真项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)
**源码关联**：[LinuxCNC Web/WASM 仿真功能与源程序关联目录](linuxcnc-web-wasm-source-map.md)
**前端与通信**：[LinuxCNC Web/WASM 仿真前端与通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)
**总控执行**：[LinuxCNC Web/WASM 仿真移植总控执行手册](linuxcnc-web-wasm-integration-playbook.md)
**目标**：覆盖 LinuxCNC 面向仿真机床的全部用户可见功能
**范围**：只做仿真，不接真实机床，不实现真实硬件访问
**基线**：仓库当前 LinuxCNC `2.10.0~pre0`

## 1. 覆盖规则

本矩阵不是功能愿望清单，而是验收清单。每一行都必须拥有实现、测试和差异报告；只有标记为 `REAL-EXCLUDED` 的真实硬件/物理安全项目不进入仿真覆盖率。任务拆分、固定 context lock、上下文包预算、断网接续和发布门禁遵循[执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)；端到端场景和任务依赖以[总控执行手册](linuxcnc-web-wasm-integration-playbook.md)为准；本矩阵只维护功能条目及其证据索引。

| 标记 | 含义 | 验收要求 |
|---|---|---|
| `SIM-CORE` | 直接复用 LinuxCNC C/C++ 核心 | 原生与 WASM golden 对照 |
| `SIM-ADAPTER` | 进程、NML、文件、时钟等兼容层 | API、状态和错误码对照 |
| `SIM-DEVICE` | 硬件功能的虚拟数字孪生 | pin、时序、故障、报警和状态可录制 |
| `WEB-EQUIV` | 桌面 GUI/工具在 Web 中等价实现 | 工作流和配置结果对照，不要求像素一致 |
| `PY-WASM` | Python/remap/过滤器在 Pyodide 中执行 | 受控宿主 API、异常和返回值对照 |
| `REAL-EXCLUDED` | 真实硬件、物理安全和实时内核 | 不实现，但必须明确报错和文档说明 |

完成定义：所有 `SIM-*`、`WEB-EQUIV`、`PY-WASM` 项在正常、边界、错误、暂停/恢复、持久化/离线和适用的跨域交互维度达到 100% 通过；`REAL-EXCLUDED` 项在配置检查中全部被识别且不会误报为已连接。单一百分比不能替代来源闭包、维度闭包和交互闭包。

条目状态使用执行策略定义的 `planned`、`in_progress`、`implemented`、`verified`、`accepted`、`blocked` 和 `REAL-EXCLUDED`。`accepted` 必须有 context lock、自动测试和差异报告；状态缺失、来源新增但无 manifest 项、或上下文包超预算均为 CI 阻断。

## 2. 功能来源和清单生成

覆盖清单必须从以下仓库来源自动生成，避免只依赖人工整理：

各功能域的实际源文件、配置入口和测试入口维护在[源程序关联目录](linuxcnc-web-wasm-source-map.md)；本节定义扫描全集，两者共同构成 manifest 的来源合同。

| 来源 | 覆盖内容 |
|---|---|
| `linuxcnc/docs/src/Master_Documentation.adoc` | 用户、配置、HAL、ClassicLadder、运动、remap、GUI、G-code 和 Python 接口；Hardware Drivers/Examples 只生成排除项 |
| `linuxcnc/configs/sim/**` | 全部仿真 INI/HAL/TBL/NGC/PY/XML/TCL 配置和样例 |
| `linuxcnc/tests/**` | 启动、解释器、运动、HAL、IO、remap、工具、回零、限位和 UI 测试 |
| `linuxcnc/unit_tests/**` | TP、解释器和数学单元测试 |
| `linuxcnc/src/emc/**` | task、io、motion、kinematics、interpreter、tooldata、NML 接口 |
| `linuxcnc/src/hal/components/**` | 全部 `.comp`、C 组件、仿真组件、测试组件和组件模板 |
| `linuxcnc/src/hal/classicladder/**` | 梯形图、顺序功能图、变量、定时器、计数器、Modbus 逻辑和工程文件 |
| `linuxcnc/src/emc/usr_intf/**`、`lib/python/**` | AXIS、Gmoccapy、Touchy、Gscreen、QtVCP、PyVCP、GladeVCP、Vismach 等界面和脚本 |

构建脚本生成 `coverage/manifest.jsonl`，字段至少包括：`id`、`source`、`source_sha`、`domain`、`kind`、`dependencies`、`inputs`、`outputs`、`errors`、`sim_status`、`web_status`、`test_id`、`oracle`、`golden`、`difference`、`coverage_dimensions`、`context_id`、`exclusion_reason`。`source` 必须可定位到文档锚点、源码符号、配置文件或测试用例；`dependencies` 必须递归闭包；`oracle` 必须说明原生对照、规范结果或明确的 Web 等价判定。任何新增源码、文档功能或仿真配置没有 manifest 项时，CI 失败。

### 2.1 完整性闭包和防遗漏检查

每次生成 manifest 都执行以下闭包检查，并将结果作为构建产物：

1. 对文档标题、G/M/O/Python/HAL/API 名称、导出符号、`.comp`、ClassicLadder 对象、`configs/sim/**` 资源和测试入口做规范化扫描，记录来源总数和来源摘要。
2. 计算来源到 manifest 的反向索引；任何孤儿来源、重复 ID、空依赖、无测试、无 oracle 或状态字段缺失都使 CI 失败。
3. 对每个条目展开依赖图，确认依赖条目存在且没有未登记的真实硬件路径；仿真配置引用的排除功能必须有对应数字孪生条目。
4. 为每个条目生成正常、边界、错误、暂停/恢复、持久化/离线测试维度；G-code、HAL、IO、Python、UI 和存储之间的关键交互生成 pairwise/关键路径用例。
5. 比较原生参考运行器和 WASM 结果，保存首个差异 tick、状态/错误字段和容差；没有可比 oracle 的条目只能是 `blocked`，不能是 `accepted`。
6. 发布前生成完整性报告：已接受、进行中、阻断、排除、孤儿来源、未覆盖维度和未覆盖交互分别列出；任何非零的未覆盖或孤儿项阻止全功能声明。

## 3. 启动、工程和配置

| 功能 | Web/WASM 实现 | 标记 |
|---|---|---|
| LinuxCNC 启动、初始化、退出和重启 | Worker 内 `create/load/start/stop/reset/destroy` 状态机 | `SIM-ADAPTER` |
| 配置选择器和 sample 配置 | OPFS 工程浏览器；完整导入 `configs/sim/**` | `WEB-EQUIV` |
| INI 注释、section、变量和 include | 兼容解析、相对路径和循环检测 | `SIM-CORE` |
| `[EMC]`、`[DISPLAY]`、`[FILTER]`、`[RS274NGC]` | 仿真相关字段读取、校验、警告和 Web 配置编辑；桌面进程字段识别后映射或排除 | `SIM-ADAPTER` |
| `[EMCMOT]`、`[TASK]`、`[HAL]`、`[HALUI]`、`[APPLICATIONS]` | 仿真字段映射到虚拟运行时；外部宿主应用不执行 | `SIM-ADAPTER` |
| `[TRAJ]`、`[KINS]`、`[AXIS_*]`、`[JOINT_*]`、`[SPINDLE_*]`、`[EMCIO]` | 轴、关节、主轴、IO、回零和运动参数全部生效 | `SIM-ADAPTER` |
| 多入口 INI、include 目录和资源查找 | `/workspace` 虚拟 POSIX 路径 + OPFS | `SIM-ADAPTER` |
| HAL twopass、HALFILE 顺序、参数展开 | 解析、排序、重复加载和错误语义对照 | `SIM-ADAPTER` |
| HAL 命令 `loadrt/addf/setp/net/sets/ newsig/linksp/linkps` | Worker 内命令执行和状态回放 | `SIM-CORE` |
| 参数、变量、`.var`、tool table、tool database | 内存运行态 + OPFS 事务提交 | `SIM-ADAPTER` |
| 工程复制、删除、重命名、导入、导出 | OPFS journal + ZIP/目录导入导出 | `WEB-EQUIV` |
| 启动错误、配置警告、资源缺失 | 行号、路径、错误码和恢复建议 | `SIM-ADAPTER` |

## 4. G-code、O-code、M-code 和解释器

### 4.1 单词、模式和程序结构

| 功能 | 覆盖内容 | 标记 |
|---|---|---|
| 行语法 | `%`、序号 `N`、注释、空行、大小写、空格、行尾 | `SIM-CORE` |
| 轴/关节词 | `X Y Z A B C U V W`、额外关节和旋转轴 | `SIM-CORE` |
| 速度/主轴/刀具 | `F S T H D Q I J K L P R E` 等全部合法词 | `SIM-CORE` |
| 参数 | `#1..#5399`、命名参数、系统参数、数组、间接寻址 | `SIM-CORE` |
| O-code | sub、call、return、do/while、if/elseif/else、break、continue、repeat、call file、返回值、错误 | `SIM-CORE` |
| Fanuc 风格 | `M98/M99`、编号程序和参数传递 | `SIM-CORE` |
| 读前瞻/队列破坏 | MDI、M-code、输入等待、暂停、remap 的队列语义 | `SIM-ADAPTER` |
| 程序控制 | run、pause、optional stop、single block、step、abort、resume、restart、line seek | `WEB-EQUIV` |
| 错误 | 语法、表达式、参数、路径、运动学和运行时错误 | `SIM-CORE` |

### 4.2 G-code 全量列表

以下代码全部纳入解析、状态、canonical 输出和运动结果测试：

| 类别 | 代码 |
|---|---|
| 运动与停留 | `G0 G1 G2 G3 G4` |
| 样条/NURBS | `G5 G5.1 G5.2 G5.3` |
| 车床模式 | `G7 G8` |
| 参数/坐标/刀具写入 | `G10 L0 L1 L2 L10 L11 L20` |
| 平面 | `G17 G17.1 G18 G18.1 G19 G19.1` |
| 单位与预定义点 | `G20 G21 G28 G28.1 G30 G30.1` |
| 同步/探针 | `G33 G33.1 G38.2 G38.3 G38.4 G38.5` |
| 刀补 | `G40 G41 G41.1 G42 G42.1 G43 G43.1 G43.2 G49` |
| 坐标系 | `G52 G53 G54 G55 G56 G57 G58 G59 G59.1 G59.2 G59.3` |
| 轨迹控制 | `G61 G61.1 G64` |
| 车床循环 | `G70 G71 G71.1 G71.2 G72 G72.1 G72.2 G74 G76` |
| 铣削/钻孔循环 | `G73 G80 G81 G82 G83 G84 G85 G86 G87 G88 G89` |
| 距离/弧距离 | `G90 G90.1 G91 G91.1` |
| G92 | `G92 G92.1 G92.2 G92.3` |
| 进给与主轴模式 | `G93 G94 G95 G96 G97 G98 G99` |

### 4.3 M-code 全量列表

| 类别 | 代码及仿真行为 |
|---|---|
| 暂停/结束 | `M0 M1 M2 M30 M60`；由 Web 控制面板和虚拟托盘/换盘事件驱动 |
| 主轴 | `M3 M4 M5 M19`；虚拟主轴转速、方向、定向和到速状态 |
| 换刀 | `M6 M61`；虚拟手动/随机/非随机换刀、准备/完成状态和失败注入 |
| 冷却 | `M7 M8 M9`；虚拟雾/洪水/主轴冷却 pin 和状态 |
| 倍率 | `M48 M49 M50 M51 M52 M53`；进给、主轴、adaptive、feed stop |
| IO | `M62 M63 M64 M65 M66 M67 M68`；同步/立即数字和模拟 IO、输入等待和超时 |
| 模态 | `M70 M71 M72 M73`；保存、失效、恢复和自动恢复模态状态 |
| 子程序 | `M98 M99`；程序调用、返回和选择性模态恢复 |
| 用户命令 | `M100-M199`；映射为 OPFS 工程内白名单 Python/NGC 虚拟动作，不执行宿主命令 |

### 4.4 Remap、Python 和过滤器

| 功能 | Web/WASM 实现 | 标记 |
|---|---|---|
| 内置 remap prolog/epilog | 解释器内 C++ ABI 复用 | `SIM-CORE` |
| NGC remap | 虚拟文件工作区中的 O-code 执行 | `SIM-ADAPTER` |
| Embedded Python remap | Pyodide Worker，暴露 linuxcnc/hal/INI/参数虚拟模块 | `PY-WASM` |
| `T/M6/M61/S/F` remap | 完整参数、返回值、异常和顺序对照 | `PY-WASM` |
| 自定义 G/M code | 工程 manifest 注册和安全限额 | `PY-WASM` |
| `[FILTER]` 程序过滤器 | 在 Pyodide 中执行 `.py/.pyc` 的纯计算/文本过滤部分 | `PY-WASM` |
| CAD/CAM 外部程序 | 不执行宿主程序；提供内置转换插件接口和错误状态 | `WEB-EQUIV` |
| Python `subprocess/threading/socket/设备` | 虚拟 API 返回 LinuxCNC 约定错误 | `REAL-EXCLUDED` |

## 5. 运动、轨迹、轴、关节和运动学

| 功能域 | 全量覆盖项 | 标记 |
|---|---|---|
| TP | 直线、圆弧、球面弧、样条、NURBS、前瞻、blend、exact path、exact stop、速度/加速度/jerk 限制 | `SIM-CORE` |
| 运行模式 | coordinated、teleop、free/joint jog、MDI、单步、暂停、恢复、abort、queue-buster | `SIM-ADAPTER` |
| 轴/关节 | X/Y/Z/A/B/C/U/V/W、额外关节、随机/非随机配置、轴-关节映射 | `SIM-CORE` |
| 限制 | soft limit、hard limit、following error、backlash、offset limit、速度/加速度限制 | `SIM-ADAPTER` |
| 回零 | search/latch/final velocity、index、shared switch、offset、sequence、volatile、immediate、locking indexer、inhibit | `SIM-DEVICE` |
| 坐标 | machine/world/relative/display、G5x、G52、G92、rotation、scale、external offset、moveoff | `SIM-CORE` |
| 补偿 | cutter radius、tool length、dynamic tool length、additional tool offset、wear、螺距误差 | `SIM-CORE` |
| 主轴同步 | threading、G33/G33.1、rigid tapping、CSS、gear、orient、multiple spindle | `SIM-DEVICE` |
| 控制环 | PID、feed/velocity/position loop、encoder、stepgen、adaptive feed | `SIM-CORE` |
| 运动学模块 | `trivkins`、`5axiskins`、`corexykins`、`cubic`、`genhexkins`、`genserkins`、`lineardelta`、`maxkins`、`pentakins`、`rosekins`、`rotarydelta`、`rotatekins`、`scarakins`、`scorbot`、`tripod`、`xyzac-trt`、`xyzbc-trt`、`switchkins`、`ugenser/userkfuncs` | `SIM-CORE`；实现族、正逆解、分支/奇异性和 K0-K8 门禁见[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md) |
| DH/机器人 | DH 参数、PUMA、SCARA、六足、Delta、Pentapod、Scorbot 和自定义静态 kinematics | `SIM-CORE` |
| 用户 kinematics | 构建期静态 WASM ABI、热切换由仿真状态机完成 | `SIM-ADAPTER` |
| 坐标/姿态显示 | joints、axes、pose、forward/inverse、tool orientation 和 singularity 错误 | `WEB-EQUIV` |

## 6. 机床类型和数字孪生

| 仿真机床 | 覆盖内容 | 标记 |
|---|---|---|
| 3/4/5/6/7/8/9 轴铣床 | 轴、关节、刀具、冷却、换刀、探针、坐标系和轨迹 | `SIM-DEVICE` |
| 车床 | G7/G8、G70/G71/G72/G76、主轴 CSS、刀尖半径、背刀塔、Fanuc Y、双主轴 | `SIM-DEVICE` |
| Gantry/CoreXY | 双关节、耦合、gantry HAL、同步误差和回零 | `SIM-DEVICE` |
| 机器人/Delta/Hexapod | 全部内置 kinematics、关节限位、姿态和模型 | `SIM-DEVICE` |
| 等离子 | torch enable、height control、arc-ok、ohmic、pierce、cut recovery、material table、qtplasmac 行为 | `SIM-DEVICE` |
| 激光 | laser power、PWM/模拟输出、动态功率和轨迹同步 | `SIM-DEVICE` |
| 泡沫切割 | 双平面/双 Z、foam kinematics、丝热功率和同步 | `SIM-DEVICE` |
| 探针/自动对刀 | probe input、触发位置、失败/超时、tool sensor 和宏 | `SIM-DEVICE` |
| 3D 打印/挤出 | 虚拟挤出轴、温度/风扇/材料状态（若 LinuxCNC 仿真配置启用） | `SIM-DEVICE` |
| 毛坯和切削 | 轨迹核心与可视化切削层分离；heightfield/voxel/SDF 按机床类型选择 | `WEB-EQUIV` |
| 故障注入 | 限位、跟随误差、探针不触发、主轴不到速、换刀失败、IO 超时、存储失败 | `SIM-DEVICE` |

## 7. HAL 全量和仿真 I/O

### 7.1 HAL 运行时契约

| 功能 | 覆盖内容 | 标记 |
|---|---|---|
| HAL 对象 | component、pin、signal、parameter、owner、type、direction、value、export/unexport | `SIM-CORE` |
| HAL 命令 | `loadrt`、`addf`、`start/stop`、`setp`、`sets`、`net`、`linksp`、`linkps`、`unlinkp`、`show`、`save`、`source` | `SIM-CORE` |
| HAL 线程 | base/servo/thread 周期、顺序、浮点标志、超时和 overrun 事件 | `SIM-ADAPTER` |
| `.comp` ABI | 全部组件模板的参数、pin、function、personality 和 lifecycle | `SIM-CORE` |
| HAL UI | `halui` 全 pin、模式、jog、home、abort、feed/spindle override 和消息 | `SIM-CORE` |
| HAL scope | 采样、触发、通道、缩放、保存和回放 | `WEB-EQUIV` |
| HAL show/meter | pin 图、实时值、类型和连接关系 | `WEB-EQUIV` |

### 7.2 组件 manifest

`linuxcnc/src/hal/components/**` 下的每个 `.comp`、C 组件和测试组件都必须在 manifest 中出现。按类别验收：

- 数学/转换：abs、scale、sum、mult、div、min/max、near、hypot、lincurve、lut、modmath、bit/float/s32/s64/u32/u64 转换。
- 逻辑/选择：and/or/not、mux、demux、select、logic、flipflop、toggle、tristate、oneshot、edge、multiswitch、multiclick。
- 时序/滤波：time、timedelay、timedelta、ton、tof、updown、counter、sample-hold、lowpass、ilowpass、biquad、filter-kalman、ddt、integ、deadzone。
- 运动/控制：PID、limit、limit-axis、limit1/2/3、blend、simple_tp、tpcomp、feedcomp、moveoff、gantry、corexy、millturn、orient、spindle、spindle-monitor、stepgen、encoder、encoder-ratio。
- 信号/诊断：message、watchdog、safety-latch、estop-latch、histobins、latencybins、sampler、streamer、lcd、matrix-kb。
- 设备/仿真：sim-axis-hardware、sim-encoder、sim-home-switch、sim-matrix-kb、sim-parport、sim-spindle、sphereprobe、probe、raster、laserpower、plasmac、thc/thcud、ohmic、charge-pump。
- 测试和用户模板：constant、test、thread、userkins、usercomp、所有 `*.comp` personality 和示例工程。

### 7.3 通用虚拟机床部件

Web 仿真不移植具体硬件驱动，而由稳定的通用模型为仿真配置提供输入输出：

| 通用模型 | 仿真能力 |
|---|---|
| 虚拟数字/模拟 I/O | pin 值、同步/立即变化、等待、延迟、噪声和故障注入 |
| 虚拟寄存器组 | 为 ClassicLadder/仿真 PLC 提供本地寄存器，不实现真实 Modbus transport |
| 虚拟 MPG/手轮/键盘 | Pointer/键盘/触控事件映射为脉冲和 HAL pin |
| 伺服/编码器 | 位置环、量化、噪声、丢脉冲、跟随误差模型 |
| 电机/主轴/冷却/阀 | 可配置惯性、加减速、到速、温度/压力/状态数字孪生 |

真实并口、GPIO、PCI、Mesa/HostMot2/FPGA、串口、VFD、Modbus transport、现场总线和协议工具统一为 `REAL-EXCLUDED`。

## 8. ClassicLadder、Modbus 和 PLC

| 功能 | 覆盖内容 | 标记 |
|---|---|---|
| 工程文件 | `.clp`、sections、symbols、variables、project load/save | `SIM-ADAPTER` |
| Ladder 对象 | contacts、coils、set/reset、timers、IEC timers、monostable、counters、compare、assignment、jump/call | `SIM-CORE` |
| 顺序控制 | GRAFCET steps/transitions/actions、状态和扫描顺序 | `SIM-CORE` |
| 扫描周期 | 虚拟 PLC thread、周期、overrun 和暂停恢复 | `SIM-ADAPTER` |
| Modbus 逻辑 | 使用虚拟寄存器、延迟和错误状态验证 Ladder 逻辑；不实现真实 serial/TCP transport | `SIM-DEVICE` |
| ClassicLadder UI | Web sections、ladder editor、variable/symbol/config/debug windows | `WEB-EQUIV` |
| PLC 与 HAL | pin 绑定、消息、工具换刀、E-stop、冷却和顺序动作 | `SIM-CORE` |

## 9. 工具、IO、主轴、换刀和探针

| 功能 | 覆盖内容 | 标记 |
|---|---|---|
| 工具表 | pocket/tool、X/Y/Z/A/B/C/U/V/W、diameter、front/rear angle、orientation、wear、offset | `SIM-CORE` |
| 工具数据库 | `db_program`、JSON/文本数据库、查询、更新、备份和迁移 | `SIM-ADAPTER` |
| 换刀 | manual、random、non-random、carousel、prepare/change、M6 remap、tool sensor、失败恢复 | `SIM-DEVICE` |
| IO control v1/v2 | tool prepare/change、coolant、lube、spindle brake、mist/flood、aux outputs | `SIM-DEVICE` |
| 主轴 | 多主轴、方向、速度、加减速、CSS、orient、gear、encoder、到速和故障 | `SIM-DEVICE` |
| 进给 | G93/G94/G95、feed hold、override、adaptive、feed stop、feed inhibit | `SIM-CORE` |
| 探针 | G38.x、probe input、位置锁存、宏、失败/超时和对刀 | `SIM-DEVICE` |
| 位置日志 | motion logger、采样、导出、回放和差异 | `WEB-EQUIV` |

## 10. GUI、VCP、可视化和配置工具

所有桌面界面不要求像素级复制，但必须覆盖其仿真工作流、状态、控制项、配置项和脚本接口。

组件信息架构、命令 pending/ack/result、通信信封、快照字段、事件/高频流、背压、错误/取消、离线恢复、多标签页租约、详细任务和 FE-M0..M5 退出条件见[前端与通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)。本节条目必须绑定该文档中的 UI 工作流和协议消息，不能只以页面存在作为验收。

| LinuxCNC 界面/工具 | Web 等价实现 |
|---|---|
| AXIS/Gremlin | 主控制台、程序、预览、3D 视图、状态、MDI、jog、override、报警、HAL 面板 |
| Gmoccapy/Gscreen | 工业面板、主题、消息、宏按钮、偏好、键盘和触控布局 |
| Touchy/QtTouchy | 触控操作、轴/关节 jog、home、MDI、程序控制和软键 |
| QtDragon/QtVCP | screen/widget schema、动态属性、signals/slots、tabs、custom widget、Vismach |
| QtPlasmaC | 等离子流程、材料表、切割参数、探高、arc-ok、暂停/恢复和日志 |
| PyVCP/GladeVCP | XML/descriptor 转 Web Component，全部 widget 属性、pin 和回调 |
| PanelUI/MDRO | 面板、数字输出、override、模式和用户按键 |
| NGCGUI/PyNGCGUI | 子程序参数表单、预览、生成/加载/运行和参数持久化 |
| HALShow/HALScope/HALMeter | pin 树、连接图、波形、触发、缩放、保存和回放 |
| Vismach | WebGL/WebGPU 机床模型、层级、关节、刀具和姿态 |
| 仿真配置编辑器 | 生成兼容的仿真 INI/HAL/工程 manifest；Stepconf/Pncconf 的驱动、板卡、引脚和时序配置排除 |
| Tooledit/Tool Database | 工具表、数据库查询、编辑、导入导出和换刀状态 |
| Image-to-G-code/NGC tools | 浏览器内纯计算插件；文件通过 OPFS/用户导入，不调用宿主程序 |
| 国际化/主题/快捷键 | 语言资源、主题变量、可配置快捷键和触摸交互 |

## 11. API、远程接口和脚本接口

| 接口 | 仿真实现 | 标记 |
|---|---|---|
| NML command/status/error | Worker 内 message bus，保留消息类型、顺序、状态和错误语义 | `SIM-ADAPTER` |
| `linuxcnc.command/stat/error` | TypeScript API + 可选 Pyodide Python binding | `PY-WASM` |
| `hal`/`hal_glib`/`pyhal` | 虚拟 pin/signal/param、监听、周期回调和类型转换 | `PY-WASM` |
| `gstat`/position logger | 状态快照、流式订阅、OPFS 日志和回放 | `WEB-EQUIV` |
| `linuxcncrsh`/远程命令 | 同源 Worker loopback；可选 WebSocket 仅连接当前仿真会话 | `SIM-ADAPTER` |
| `halcmd`/`haltcl`/`halrun` | Web 控制台命令解析；脚本只作用于当前虚拟工程 | `WEB-EQUIV` |
| MQTT/消息发布 | 本地事件总线和可选浏览器 WebSocket mock，不访问真实设备 | `SIM-DEVICE` |
| UI 插件/自定义面板 | manifest、权限、版本、生命周期和 OPFS 资源 | `WEB-EQUIV` |

### 11.1 诊断、开发和运维工具

| LinuxCNC 工具/能力 | 仿真实现 | 标记 |
|---|---|---|
| `linuxcnc_info` | 输出浏览器、WASM、Worker、OPFS、配置、组件和仿真能力报告 | `WEB-EQUIV` |
| `inivar`/INI 检查 | Web 配置查看、类型转换、include 展开和错误定位 | `WEB-EQUIV` |
| `lintini` | Worker 内静态检查全部 INI/HAL/资源引用 | `WEB-EQUIV` |
| `halcompile`/`modcompile` | 构建流水线中编译 `.comp`；Web 编辑器提供语法/接口检查 | `SIM-ADAPTER` |
| `runtests`/测试选择器 | 浏览器内按 manifest 运行 golden、回归和故障测试 | `WEB-EQUIV` |
| 仿真性能诊断 | 提供批处理耗时、Worker 延迟和 UI 帧率；`latency-test` 的内核实时延迟测试排除 | `WEB-EQUIV` |
| `debuglevel`/调试标志 | 虚拟运行时动态日志级别和 OPFS 日志 | `SIM-ADAPTER` |
| `tool_watch`/tool data monitor | 工具、换刀、数据库和快照监视器 | `WEB-EQUIV` |
| `motion-logger`/`halsampler`/`halstreamer` | 采样、导出、回放和差异可视化 | `WEB-EQUIV` |
| `axis-remote`/`schedrmt`/`linuxcnclcd`/`emclcd` | 同源命令/状态通道和虚拟显示终端 | `SIM-ADAPTER` |
| `linuxcncsvr`/远程 NML 服务 | 仅提供同源仿真会话服务；不监听宿主真实端口 | `SIM-ADAPTER` |
| `decode_dmesg`/系统诊断 | 虚拟设备和 WASM 运行时日志；无宿主内核日志 | `REAL-EXCLUDED` |

## 12. OPFS、快照和可重复仿真

| 功能 | 覆盖要求 | 标记 |
|---|---|---|
| 工程目录 | INI/HAL/TBL/VAR/NGC/PY/XML/TCL/CLP/模型/材料/日志全部可保存 | `SIM-ADAPTER` |
| 文件语义 | open/read/write/stat/readdir/rename/unlink/fsync、相对路径、大小写和错误 | `SIM-ADAPTER` |
| 事务 | prepare/commit、临时文件、SHA-256、原子替换、版本索引 | `SIM-ADAPTER` |
| 恢复 | 刷新、崩溃、半提交、版本迁移、损坏文件和回滚 | `SIM-ADAPTER` |
| 快照 | 任务、解释器、TP、运动、HAL、IO、Python、工具、参数和 UI 状态 | `SIM-ADAPTER` |
| 回放 | 从 tick/事件恢复后与连续运行结果一致 | `SIM-CORE` |
| 任务接续账本 | 请求超时、回答/工具结果丢失、重复响应、Worker 重启；按 `operation_id`、prepare/commit 和最后已验证步骤恢复 | `SIM-ADAPTER` |
| 配额 | estimate、persist、配额不足、清理 cache、导出备份 | `WEB-EQUIV` |
| 离线 | Service Worker 缓存 WASM、Pyodide、样例和 UI；无网加载已有工程 | `WEB-EQUIV` |

## 13. 测试覆盖模型

### 13.1 Golden 对照

原生 LinuxCNC 和 WASM 对每个 manifest 项输出：

- 解释器状态、当前行、模态、参数和返回值
- canonical motion、每 tick 位置/速度/加速度/跟随误差
- 轴/关节/姿态、运动学错误和限位状态
- HAL pin/signal/param、线程顺序和组件输出
- 主轴、工具、探针、换刀、冷却、等离子/激光/泡沫 IO
- Python/remap 输出、异常、日志和事件
- UI 命令、报警、状态和快照恢复结果

### 13.2 样本集合

1. `configs/sim/**` 下全部 INI 和关联资源，而不是只抽取 10 个样例。
2. `tests/**` 下全部可运行仿真测试；只依赖真实硬件、内核实时或驱动的测试登记为排除项。
3. `unit_tests/interp`、`unit_tests/tp`、posemath 和 kinematics 单元测试。
4. 每个 G/M/O 代码至少一个正常、边界、错误和暂停/恢复样例。
5. 每个 HAL 组件至少一个 pin 类型、周期、复位和异常样例。
6. 每种机床类型至少一个完整工程、模型、程序、工具表、IO 和故障回放。
7. 每个 Web UI 工作流覆盖首次启动、刷新恢复、离线、导入导出和键盘/触摸路径。
8. 每个可恢复任务至少覆盖一次请求失败、确认丢失、幂等重试和无法对账的阻断路径。

### 13.3 覆盖率门槛

- 覆盖率门槛与发布门禁 G4/G5 同步；来源、依赖、维度和交互闭包以及具体任务上下文和证据包格式见[执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)第 2.1、3、7 节。
- `SIM-CORE`、`SIM-ADAPTER`、`SIM-DEVICE`、`WEB-EQUIV`、`PY-WASM`：100% manifest 条目有实现和自动测试。
- 每个条目的正常、边界、错误、暂停/恢复、持久化/离线及适用交互维度均有通过记录；缺失任一维度不得为 `accepted`。
- 关键状态和错误的原生/WASM 对照通过率：100%。
- 浮点误差按算法定义容差，默认机床单位目标 `1e-6`。
- OPFS 已提交数据在刷新、Worker 重启和模拟崩溃后可恢复。
- 任何 manifest 缺失、未测试或静默降级都阻止发布。
- 任何孤儿来源、未闭合依赖、无 oracle、未覆盖交互或未解释的差异都阻止发布。
- 前端通信条目必须同时有消息 schema、LinuxCNC 源程序映射、UI 工作流、错误/取消、背压和离线恢复测试；详细字段和 FE/COM 任务见[前端与通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)。
- `REAL-EXCLUDED` 不计入仿真覆盖率，但配置检查必须返回明确 `real_hardware_excluded`。

## 14. 实施顺序

本节的阶段 A-E 只描述功能交付顺序；对应的 M0-M5 里程碑、工作流边界、固定上下文和返工规则见[执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)第 4、6、8 节。

### 阶段 A：全量清单和运行时骨架

- 生成 manifest，锁定所有文档、源码、配置和测试输入。
- 建立单 Worker、固定 tick、OPFS journal、快照和版本化 ABI。
- 建立 Python/Pyodide Worker 和虚拟 `linuxcnc/hal/gstat` 模块。

### 阶段 B：核心解释和运动全覆盖

- 移植全部 G/M/O、remap、参数、坐标系、补偿、TP、motion、全部 kinematics。
- 完成 mill/lathe/gantry/robot/delta/pentapod/foam/plasma/laser/probe 数字孪生。

### 阶段 C：HAL、PLC、IO 和虚拟机床部件

- 生成并编译全部 HAL 组件 manifest。
- 完成 ClassicLadder、虚拟寄存器、主轴/换刀/探针/编码器/stepgen/限位/故障模型。
- 完成 halcmd/haltcl/halui/HALScope/HALShow。

### 阶段 D：全部 Web UI 和配置工具

- 完成 AXIS、Gmoccapy、Touchy、Gscreen、QtVCP、QtDragon、QtPlasmaC、VCP、Vismach、NGCGUI 等仿真操作能力的 Web 等价工作流和仿真配置编辑器。
- 完成工程导入、导出、离线、国际化、主题和插件权限。

### 阶段 E：全量回归和发布

- 全部 configs/tests/golden/浏览器矩阵跑通。
- 生成版本化差异报告、兼容报告、许可证清单和工程迁移工具。

## 15. 明确排除项

以下不是仿真机床功能，因此不实现，也不能通过浏览器 API 绕过：

- 真实电机、驱动器、主轴、刀具、冷却、气路、液压和工件。
- 真实 Mesa/FPGA、并口、GPIO、PCI、串口、USB、Modbus 设备和现场总线。
- PREEMPT_RT、RTAI、Xenomai、内核模块、CPU 绑定、硬实时和物理步进脉冲。
- 真实急停、安全继电器、门锁、限位开关和人员/设备安全认证。
- 任意宿主路径、shell、fork/exec、子进程、设备文件和网络原始套接字。

排除项的仿真等价行为必须由第 6～9 节的数字孪生提供；例如“主轴不到速”要模拟成可配置状态和故障，而不是把主轴驱动标为“不支持”。