cnc_wams/web-rtcp-5axis-sim-plan/docs/docs-directory-file-guide.md

# docs 目录文件作用详解与关联流程图

生成日期：2026-07-01  
适用目录：`/home/mes123456/cnc_wams/web-rtcp-5axis-sim-plan/docs`

## 1. 文档集定位

`docs` 目录不是单一说明书，而是 Web-RTCP 五轴数控仿真项目的“方案、实施、追溯、参考、操作手册、截图证据”集合。它承担五类职责：

1. 定义项目要做什么、不能做什么。
2. 把 LinuxCNC 的源码、配置、GUI、HAL、G-code 示例映射到 Web 项目。
3. 指导开发人员按阶段实现 Web UI、WASM runtime、Three.js 可视化、Task/HAL 仿真边界。
4. 记录每一批功能的来源、边界、测试和剩余风险。
5. 给操作人员提供界面使用流程、截图和验证方法。

推荐阅读顺序：

```text
implementation-plan.md
  -> technical-roadmap.md
  -> program-implementation-guide.md
  -> native-task-hal-sync-implementation-steps.md
  -> development-continuation.md
  -> traceability-matrix.md
  -> linuxcnc-parity-matrix.md
  -> Web-RTCP五轴数控系统仿真界面操作手册新版.docx
```

参考类文档可按需阅读：

```text
linuxcnc-python-gui-reference.md
linuxcnc-gui-reference-gallery.md
gmoccapy-xyzab-reference.md
manual-assets/*
```

## 2. 文件总览

| 文件 | 类型 | 主要作用 | 当前使用方式 |
| --- | --- | --- | --- |
| [implementation-plan.md](implementation-plan.md) | 总体方案 | 定义项目定位、当前基线、LinuxCNC 参考案例、总体架构、RTCP 功能边界和阶段计划。 | 作为“为什么这样做”和“范围边界”的最高层说明。 |
| [technical-roadmap.md](technical-roadmap.md) | 技术路线 | 规定技术栈、目录建议、gmoccapy 风格 Web 方案、模块拆分、LinuxCNC 源码接入路线、数据流和里程碑。 | 作为架构拆分和里程碑路线图。 |
| [program-implementation-guide.md](program-implementation-guide.md) | 实施指南 | 给出具体编程步骤、目录结构、Step 1-11、当前实现状态、禁止事项和开工建议。 | 开发时按步骤查阅，避免把 UI fixture 当成 LinuxCNC 语义证明。 |
| [native-task-hal-sync-implementation-steps.md](native-task-hal-sync-implementation-steps.md) | Task/HAL 专项方案 | 详细规划 LinuxCNC task、motion、HAL 同步 runtime 的阶段、源码清单、C ABI、Worker 接线和验收矩阵。 | 推进 `nativeTaskReady`、`nativeHalSyncReady` Web 仿真边界时使用。 |
| [development-continuation.md](development-continuation.md) | 接续/交接文档 | 记录 M1 到 M23 的阶段状态、最新基线、后续任务、回归命令和禁止事项。 | 每轮开发前确认“当前最新状态”和必须跑的回归。 |
| [traceability-matrix.md](traceability-matrix.md) | 追溯矩阵 | 把功能、Web 实现位置、LinuxCNC 来源、边界分类、验证方式和每批开发记录串起来。 | 做合规追溯、验收和回归审计。 |
| [external-user-m-tool-db-simulation-plan.md](external-user-m-tool-db-simulation-plan.md) | 专项方案 | 说明红框 `external user-M/tool DB process` 如何以 Web 仿真纳入项目，以及 host/native 边界。 | 修改 tool DB 或 user-M 白名单前先看。 |
| [linuxcnc-python-gui-reference.md](linuxcnc-python-gui-reference.md) | GUI 参考说明 | 说明 AXIS、vismach、PyVCP、gmoccapy、QtVCP/QtDragon 各自提供哪些界面参考，以及哪些 native GUI 不能直接移植。 | Web UI 和 Three.js 机床模型设计参考。 |
| [linuxcnc-gui-reference-gallery.md](linuxcnc-gui-reference-gallery.md) | 界面图册 | 汇总 LinuxCNC 原始界面截图，说明 gmoccapy、QtVismach、AXIS、PyVCP、QtDragon 的参考优先级。 | 视觉和布局选型依据。 |
| [linuxcnc-parity-matrix.md](linuxcnc-parity-matrix.md) | 对标矩阵 | 记录当前 Web 项目对标的 LinuxCNC 配置、程序、功能和当前边界。 | UI diagnostics 和 Node smoke 的对标说明。 |
| [gmoccapy-xyzab-reference.md](gmoccapy-xyzab-reference.md) | gmoccapy XYZAB 参考 | 分析 LinuxCNC `gmoccapy_XYZAB.ini` 的启动、NML/HAL 通信、HAL 拓扑、G-code gate 和按钮图标边界。 | 作为 gmoccapy/trivkins reference profile，不作为 RTCP 证明。 |
| [Web-RTCP五轴数控系统仿真界面操作手册.docx](<Web-RTCP五轴数控系统仿真界面操作手册.docx>) | Word 操作手册旧版 | 面向操作人员，说明系统定位、界面区域、上电/回零、AUTO、MANUAL、MDI、倍率、会话和常见问题。 | 旧版用户手册，适合了解基础操作流程。 |
| [Web-RTCP五轴数控系统仿真界面操作手册新版.docx](<Web-RTCP五轴数控系统仿真界面操作手册新版.docx>) | Word 操作手册新版 | 在旧版基础上强化 LinuxCNC 对标、右侧九入口互锁、真实五轴程序来源、项目目录、INI/HAL/tool table/remap 校验和验证记录。 | 当前推荐对外使用的操作手册。 |
| `.~lock.Web-RTCP五轴数控系统仿真界面操作手册.docx#` | LibreOffice 锁文件 | 记录某次 LibreOffice 打开 Word 手册时的用户、主机、时间和配置路径。 | 临时文件，不属于项目设计文档，也不应作为功能依据。 |
| [manual-assets/](manual-assets/) | 截图资产目录 | 保存操作手册用的界面截图和局部截图。 | 用于重建/更新 Word 手册、PDF 手册或网页说明。 |

## 3. Markdown 文件详细说明

### 3.1 `implementation-plan.md`

角色：总体实现方案。

它回答四个问题：

- 项目是什么：独立 Web 五轴 RTCP 数控仿真界面，不是真实硬实时机床控制器。
- 现有基础是什么：已有 interpreter WASM、OPFS/session、virtual HAL、AXIS 风格页面、5 轴源码覆盖和案例资产。
- 参考哪些 LinuxCNC 内容：`xyzac-trt`、`xyzbc-trt`、bridgemill、table-dual-rotary、`trtfuncs.c`、`5axiskins.c`、`switchkins.c`、Python GUI 和 PyVCP/HAL 配置。
- 阶段怎么走：从方案文档、Web shell、5 轴 profile、kinematics WASM、RTCP 预览、操作级仿真到发布验证。

关键内容：

- 明确浏览器不直接驱动真实伺服、IO 或 Linux kernel realtime ABI。
- 要求 G-code 解释、canonical event、五轴运动学、remap 语义尽量保持 LinuxCNC-owned。
- 规定四层架构：Web UI、Web Runtime/Session、LinuxCNC WASM/Source Boundary、Visualization/Playback。
- 定义 `FiveAxisMotionFrame` 和 `FiveAxisMachineProfile`。

读者：

- 项目负责人用它判断范围。
- 开发者用它理解架构边界。
- 测试人员用它判断哪些能力不能被误宣称为完成。

### 3.2 `technical-roadmap.md`

角色：技术路线与模块设计。

它把总体方案落到工程结构，主要说明：

- 技术栈：原生 HTML/CSS + TypeScript/JavaScript ES modules、Vite/esbuild、Three.js、Emscripten、OPFS、Node smoke、Playwright/Chromium browser smoke。
- 不使用 React/Vue/Angular/Svelte 的原因：核心复杂度在 LinuxCNC/WASM、五轴运动学、RTCP 数据流和 Three.js。
- 推荐目录：`app/`、`core/linuxcnc_kinematics_wasm/`、`tests/`。
- gmoccapy 5 轴 Web 化方案：页面布局、组件拆分、状态模型、样式原则。
- 模块拆分：`profiles`、`runtime`、`linuxcnc_kinematics_wasm`、`visualization`、`ui`、`panel-schema`。
- LinuxCNC 源码接入步骤：引用清单、C ABI shim、WASM 编译、Node 验证、Browser 验证、Python GUI 参考验收。

它和 `implementation-plan.md` 的关系：

- `implementation-plan.md` 偏“产品与边界”。
- `technical-roadmap.md` 偏“工程结构与技术路径”。

### 3.3 `program-implementation-guide.md`

角色：逐步编码指南。

它面向实际开发，按 Step 拆分：

- Step 1：Web shell。
- Step 2：状态模型。
- Step 3：gmoccapy UI 组件。
- Step 4：Three.js 五轴预览。
- Step 5：profile 和 panel schema。
- Step 6：LinuxCNC adapter。
- Step 7：RTCP/kinematics frame。
- Step 8：测试和验收。
- Step 9：LinuxCNC TP queue timing runtime。
- Step 10：Native task/HAL readiness artifact。
- Step 11：LinuxCNC source program case coverage。

这个文件的特点是它同时保存“原计划”和“当前实现状态”。例如它会写明某些路径已经实现、某些 runtime 已经 ready、哪些 fallback 只能作为 UI 安全路径，不能作为 LinuxCNC proof。

维护规则：

- 新增 runtime 或 UI gate 时，应同步更新此文件的对应 Step。
- 如果只是记录某批开发结果，也要同时在 `traceability-matrix.md` 中登记。

### 3.4 `native-task-hal-sync-implementation-steps.md`

角色：LinuxCNC Task/Motion/HAL 同步 runtime 的专项实施书。

它围绕两个 blocker 展开：

```text
nativeTaskReady=false
nativeHalSyncReady=false
```

文档目标不是把浏览器变成真实机床控制器，而是建立一个 LinuxCNC 源码拥有语义的 task/HAL 同步仿真 runtime，使 Web UI 能按 LinuxCNC task、motion、HAL 的顺序运行程序、执行 MDI/JOG、同步 HAL pin。

主要内容：

- LinuxCNC 源程序参考清单：`task.hh`、`emctask.cc`、`motion.c`、`control.c`、`hal_lib.c` 等。
- 推荐架构：Web UI -> Worker -> `linuxcnc_task_hal.wasm` -> task loop -> canonical queue -> motion command queue -> deterministic HAL scheduler -> status snapshot。
- textbak 和已有 virtual HAL 成果的可复用点。
- 阶段 0 到阶段 8：source manifest、native probe、HAL runtime、motion sync、task runtime、machine-file session、SWITCHKINS、Worker/store 接线、Full boundary 提升。
- C/C++ API 和 WASM C ABI 设计。
- Node、Browser、WASM、Native optional proof 的验收矩阵。

边界重点：

- `nativeTaskReady=true` 和 `nativeHalSyncReady=true` 只允许在 Web simulation boundary 内成立。
- `hardwareDrive=false`、`hostRealtimeKernel=false`、`hostExternalUserMProcessReady=false`、`hostToolDbProcessReady=false` 和 `arbitraryUserMExecution=false` 必须继续显式显示；`externalUserMProcessReady=true`、`toolDbProcessReady=true` 只表示 `web_simulation_only`。

### 3.5 `development-continuation.md`

角色：开发接续和最新状态基线。

这个文件是“下一轮继续干活时先看这里”的文档。它保留了 M1-M17 的历史记录，并在后半部分以“最新接续基线”重写当前状态。

重点章节：

- 当前完成情况：UI shell、profile、kinematics WASM、interpreter WASM、TP queue timing、machine-file staging、task/motion/HAL Web simulation boundary、Three.js、source program coverage、OPFS 降级等。
- Three.js 当前状态：明确 Three.js 只消费 LinuxCNC runtime 输出，不解析 G-code，不生成 CNC 运动语义。
- M18-M23：native task/HAL audit、真实 LinuxCNC 源程序案例覆盖、Three.js 显示质量、OPFS 降级、Host/native 边界可见性、受控 tool DB/user-M Web 仿真。
- 每轮必须执行的回归命令。
- 禁止事项。

注意事项：

- 由于它是长期接续文档，章节编号有历史遗留和不连续现象。判断当前工作时应优先看“最新接续基线”。
- 它不等同于追溯证据，追溯证据应看 `traceability-matrix.md`。

### 3.6 `traceability-matrix.md`

角色：实现追溯和验收账本。

它把每个功能回答成五列：

```text
功能 -> Web 实现位置 -> LinuxCNC 参考 -> 边界分类 -> 验证方式
```

它覆盖：

- gmoccapy shell、DRO、右侧按钮、底部控制、G-code 当前行。
- 上电、急停、复位、模式、JOG、MDI、RUN/PAUSE/RESUME/STOP。
- LinuxCNC 5 轴源程序 staging 和真实程序案例覆盖。
- interpreter WASM、TP WASM、Three.js 预览和执行轨迹。
- `xyzac-trt`、`xyzbc-trt`、`gmoccapy-xyzab` profile。
- PyVCP/HAL panel schema。
- Full execution boundary audit。
- Native task/HAL readiness artifact。
- OPFS/session fallback。
- tool DB Web 仿真和受控 user-M Web 仿真。

后半部分按批次记录 M0 到 M23 的开发追溯，包括：

- Files changed。
- Feature。
- LinuxCNC references。
- Boundary。
- Tests。
- Result。
- Remaining risk。
- Next。

使用场景：

- 验收时查“某个 UI 功能来自哪个 LinuxCNC 文件”。
- 修改代码后查“应该补哪条追溯记录”。
- 发现文档声称过高时，用边界分类纠偏。

### 3.7 `external-user-m-tool-db-simulation-plan.md`

角色：红框 `external user-M/tool DB process` 的专项设计与实施边界文档。

它说明：

- 为什么该能力不能作为任意 host 进程执行；
- tool DB Web/WASM 仿真如何读取 staged `tool.tbl`、保存到 OPFS/memory fallback，并接入 `Tn/M6/G43/M61`；
- 受控 user-M 仿真如何只允许白名单 `M128/M129/M428/M429/M430`；
- UI 和 full boundary 如何显示 `toolDbProcessReady=true for web_simulation_only` 与 `externalUserMProcessReady=true for web_simulation_only`；
- host tool DB process、host external user-M process、任意系统脚本执行仍为 false。

### 3.8 `linuxcnc-python-gui-reference.md`

角色：LinuxCNC Python GUI 到 Web 的转换指南。

它逐项说明：

- AXIS：菜单、工具栏、Manual/MDI、Preview、DRO、G-code 当前行、高亮和状态栏。
- vismach：机床几何树、`Translate`、`Rotate`、`HalTranslate`、`HalRotate`、工作台/转台/主轴/刀具层级。
- PyVCP：`SWITCHKINS`、`IDENTITY`、`TCP:XYZAC`、`TCP:XYZBC`、`USERK`、joint 数值和 HAL pin 绑定。
- gmoccapy：大按钮、jog increment、override、右侧嵌入面板、多轴状态。
- QtVCP/QtDragon：现代 CNC 操作屏、状态区、工具区、探测区、大屏布局。

关键边界：

```text
Python GUI 是界面和结构参考，不是浏览器 runtime 依赖。
```

不直接移植：

- Tkinter 主循环。
- `rs274.OpenGLTk`。
- PyQt/QTVCP native widget。
- GTK/Glade native UI。
- native `hal.component()` 进程。
- LinuxCNC GUI 与 task/motion 的 native IPC。
- Python remap runtime。

### 3.9 `linuxcnc-gui-reference-gallery.md`

角色：界面截图参考图册。

它把 LinuxCNC 源码树自带界面截图整理成设计依据：

- `qtvismach_5axis_gantry.png`：五轴机床模型和 3D 视图优先参考。
- `gmoccapy_5_axis.png`：本项目首选操作员界面风格。
- `axis.png`：经典 LinuxCNC 操作布局参考。
- `axis-pyvcp.png`：右侧 PyVCP 面板和 SWITCHKINS 控件参考。
- `qtdragon.png`、`qtdragon_hd.png`：现代大屏/触控界面参考。
- `vismach.png`、`qtvismach.png`：Python/QtVismach 机床仿真参考。

当前推荐组合：

```text
gmoccapy 5 Axis + QtVismach 5 Axis Gantry + PyVCP SWITCHKINS
```

### 3.10 `linuxcnc-parity-matrix.md`

角色：当前对标功能矩阵。

它记录 Web-RTCP 五轴仿真界面当前对标的 LinuxCNC 程序、配置文件和功能边界。运行时状态对象为 `linuxCncParityMatrix`，gmoccapy diagnostics 会显示摘要，Node smoke 通过 `tests/node/verify_linuxcnc_parity_matrix.mjs` 校验。

主要内容：

- 对标的 LinuxCNC 配置：`xyzac-trt.ini`、`xyzbc-trt.ini`。
- 对标的 PyVCP/POSTGUI/HAL：`xyzac-trt.xml`、`xyzbc-trt.xml`、`switchkins_postgui.hal`。
- 对标的 remap：`428remap.ngc`、`429remap.ngc`、`430remap.ngc`。
- 对标的真实五轴 G-code：`boat-xyzac.ngc`、`boat-xyzbc.ngc`、`impeller-7bl-xyzac.ngc`、`xyzac_switchkins*.ngc`、`xyzbc_switchkins.ngc`。
- 已承接功能：右侧纵向入口、模式互锁、颜色规则、项目目录、INI 对标、程序验证、实时轴值、预览路径、gmoccapy HAL 语义、task/HAL 边界。

边界结论：

```text
semanticBoundary=linuxcnc_source_function_parity_matrix_for_browser_simulation_not_hardware_control
```

### 3.11 `gmoccapy-xyzab-reference.md`

角色：gmoccapy XYZAB native 示例到 Web 的参考边界。

它分析 LinuxCNC `gmoccapy_XYZAB.ini`：

- native 配置：`DISPLAY=gmoccapy`、`TASK=milltask`、`EMCMOT=motmod`、`COORDINATES=X Y Z A B`、`KINEMATICS=trivkins coordinates=xyzab`。
- native 启动顺序：解析 INI、启动 `linuxcncsvr`、启动 HAL/RTAPI、加载 `milltask`、加载 `halui`、执行 HALFILE、启动 gmoccapy、执行 POSTGUI_HALFILE。
- native 通信模型：gmoccapy -> `linuxcnc.command()` -> NML -> milltask；status/error channel；HAL shared memory；HALUI；REMAP。
- HAL 拓扑：joint command/feedback loop、spindle speed feedback、simulated home、gmoccapy postgui pin。
- G-code gate：RESET、POWER、HOME、mode、interpreter idle。
- 按钮图标边界：图标资产只证明 UI 来源，按钮正确性仍依赖 Web store、task policy、runtime state 和 browser evidence。

重要说明：

```text
gmoccapy_XYZAB 是 trivkins simulation，不是 TCP/RTCP proof。
```

## 4. Word 操作手册说明

### 4.1 `Web-RTCP五轴数控系统仿真界面操作手册.docx`

角色：基础操作手册旧版。

正文内容包括：

- 系统定位与安全边界。
- 界面区域说明。
- 标准开机、回零和模式切换流程。
- AUTO 自动运行流程。
- MANUAL 手动点动流程。
- MDI 命令流程。
- RTCP、IDENTITY 与 TCP 切换。
- 倍率、主轴、冷却和 HAL 输入。
- 程序来源、会话保存与恢复。
- 诊断信息和验收检查表。
- 常见问题处理。
- 关键按钮速查。

适用场景：

- 给第一次使用界面的人看。
- 排查 AUTO/MANUAL 颜色、POWER、Home、Run、MDI、Save Session 等基础问题。

### 4.2 `Web-RTCP五轴数控系统仿真界面操作手册新版.docx`

角色：当前推荐操作手册。

新版更强调“对标 LinuxCNC”：

- 对标范围：gmoccapy_5_axis、`xyzac-trt`、`xyzbc-trt`、INI/HAL/tool table/remap 文件结构。
- 右侧纵向按钮区：E-STOP、POWER、RESET、AUTO、MANUAL、JOG、MDI、IDENTITY、TCP 的 active/allowed/status/operatorMessage/colorRule。
- 标准流程：RESET -> POWER -> MANUAL -> HOME -> AUTO -> 选择 LinuxCNC 5-axis source -> TCP 或 M428 -> RUN。
- 刀具预览路径：由 LinuxCNC interpreter canonical motion、TP planner 或 task/HAL runtime 生成，Three.js 只显示结果。
- G-code 实时执行与轴值：RUN、STEP、PAUSE/RESUME、JOG、MDI 的数据来源。
- LinuxCNC 真实五轴程序来源：`xyzac_switchkins.ngc`、`xyzbc_switchkins.ngc`、`impeller-7bl-xyzac.ngc`、`boat-xyzac.ngc`、`boat-xyzbc.ngc`、`xyzac_switchkins_test_1/2/3.ngc`。
- 项目目录：`machines/<profile>`，保存 INI、HAL/XML/TBL、remap_subs、demos。
- 诊断、倍率、主轴与冷却。
- 验证记录：gmoccapy sidebar、machine-file staging、real LinuxCNC 5axis program cases、XYZAB gates、run feedback loop、build。

适用场景：

- 交付、验收、演示时优先使用。
- 需要证明程序来源、INI 对标、项目目录、真实五轴程序边界时使用。

## 5. `manual-assets` 截图资产说明

| 文件 | 图片尺寸 | 作用 |
| --- | --- | --- |
| [manual-assets/01-main-overview.png](manual-assets/01-main-overview.png) | 1440 x 1000 | 主界面总览，展示预览区、DRO、G-code、右侧状态入口、底部控制栏。 |
| [manual-assets/02-power-home-manual.png](manual-assets/02-power-home-manual.png) | 1440 x 1000 | POWER 和 HOME 后的手动状态，用于说明上电、回零、MANUAL/AUTO 可用性。 |
| [manual-assets/03-right-sidebar-manual.png](manual-assets/03-right-sidebar-manual.png) | 108 x 958 | 手动状态下右侧纵向按钮局部图，用于说明 MANUAL/JOG/MDI/AUTO/TCP 入口状态。 |
| [manual-assets/04-auto-active.png](manual-assets/04-auto-active.png) | 1440 x 1000 | AUTO 激活后的整屏状态，用于说明自动模式、G-code 区和运行准备。 |
| [manual-assets/05-right-sidebar-auto.png](manual-assets/05-right-sidebar-auto.png) | 108 x 958 | AUTO 激活后的右侧按钮局部图，用于说明 AUTO 绿色、MANUAL 灰色等颜色规则。 |
| [manual-assets/06-run-program.png](manual-assets/06-run-program.png) | 1440 x 1000 | 程序运行状态截图，用于说明 G-code 当前行、DRO、runtime feedback、刀具路径预览。 |
| [manual-assets/07-manual-jog.png](manual-assets/07-manual-jog.png) | 1440 x 1000 | MANUAL/JOG 点动后的状态，用于说明 DRO 和轴值同步。 |
| [manual-assets/08-mdi-command.png](manual-assets/08-mdi-command.png) | 1440 x 1000 | MDI 命令输入状态，用于说明 MDI 输入框和执行入口。 |
| [manual-assets/09-mdi-executed.png](manual-assets/09-mdi-executed.png) | 1440 x 1000 | MDI 执行后的状态，用于说明坐标、程序来源和 MDI 历史同步。 |
| [manual-assets/10-overrides-and-hal.png](manual-assets/10-overrides-and-hal.png) | 1440 x 1000 | 倍率、HAL 输入、主轴、冷却截图，用于说明 Rapid/Feed/Spindle/Coolant 控件。 |
| [manual-assets/11-session-diagnostics.png](manual-assets/11-session-diagnostics.png) | 1440 x 1000 | 会话和诊断信息截图，用于说明 Save/Restore、OPFS/memory fallback、Task/HAL、Full boundary 等诊断。 |

维护建议：

- 更新 Word 手册时，先用同名截图替换 `manual-assets`，再重新嵌入手册。
- 如果 UI 布局或按钮状态改变，需要同步更新对应截图和手册说明。
- 截图文件本身是视觉证据，不是 runtime proof；runtime proof 仍来自 Node/browser smoke、readiness artifact 和 traceability matrix。

## 6. 临时锁文件说明

文件：

```text
.~lock.Web-RTCP五轴数控系统仿真界面操作手册.docx#
```

作用：

- 这是 LibreOffice 打开 Word 文档时生成的锁文件。
- 内容包含用户、主机、打开时间和 LibreOffice 配置路径。
- 它不描述项目功能、不参与构建、不参与测试、不应作为文档依据。

处理建议：

- 如果确认没有 LibreOffice 正在编辑对应文档，可以删除。
- 如果文档仍在打开，保留锁文件，避免并发编辑冲突。
- 提交代码或整理文档资产时，建议不要把该文件纳入正式版本。

## 7. 文档分层关系图

高清 PNG：![文档分层关系图](diagram-assets/01-docs-layer-relationship.png)

```mermaid
flowchart TD
  A[docs 目录] --> B[方案层]
  A --> C[实施层]
  A --> D[追溯与对标层]
  A --> E[参考层]
  A --> F[操作手册层]
  A --> G[截图资产层]

  B --> B1[implementation-plan.md]
  B1 --> B2[technical-roadmap.md]

  C --> C1[program-implementation-guide.md]
  C --> C2[native-task-hal-sync-implementation-steps.md]
  B2 --> C1
  C2 --> C1

  D --> D1[development-continuation.md]
  D --> D2[traceability-matrix.md]
  D --> D3[linuxcnc-parity-matrix.md]
  C1 --> D1
  D1 --> D2
  D3 --> D2

  E --> E1[linuxcnc-python-gui-reference.md]
  E --> E2[linuxcnc-gui-reference-gallery.md]
  E --> E3[gmoccapy-xyzab-reference.md]
  E1 --> B1
  E2 --> B2
  E3 --> D2
  E3 --> D3

  F --> F1[操作手册旧版 docx]
  F --> F2[操作手册新版 docx]
  G --> G1[manual-assets/*.png]
  G1 --> F1
  G1 --> F2

  D2 --> F2
  D3 --> F2
```

## 8. LinuxCNC 来源到 Web 仿真的关联流程图

高清 PNG：![LinuxCNC 来源到 Web 仿真的关联流程图](diagram-assets/02-linuxcnc-to-web-simulation-flow.png)

```mermaid
flowchart LR
  L1[LinuxCNC INI/HAL/TBL/remap] --> P[profiles 与 machine-file staging]
  L2[LinuxCNC 5轴 G-code demos] --> P
  L3[LinuxCNC kinematics C 源码] --> K[kinematics WASM]
  L4[LinuxCNC interpreter/TP 源码] --> I[interpreter WASM + TP queue timing]
  L5[LinuxCNC task/motion/HAL 源码] --> T[task/motion/HAL WASM simulation runtime]
  L6[AXIS/vismach/PyVCP/gmoccapy/QtVCP GUI] --> U[Web UI + panel schema + Three.js scene]

  P --> R[Web runtime/session]
  K --> R
  I --> R
  T --> R
  R --> S[store/state snapshot]
  S --> U
  U --> O[DRO/G-code/Three.js/diagnostics]

  O --> M[操作手册截图与 manual-assets]
  R --> V[Node/browser/WASM smoke 与 readiness artifact]
  V --> X[traceability-matrix.md]
  X --> D[development-continuation.md]

  T -. 明确不包含 .-> H[真实硬件驱动]
  T -. 明确不包含 .-> N[host realtime kernel]
  T -. 明确不包含 .-> E[external user-M/tool DB process]
```

## 9. 操作流程关联图

高清 PNG：![操作流程关联图](diagram-assets/03-operator-workflow.png)

```mermaid
flowchart TD
  S0[打开 Web 仿真界面] --> S1{E-STOP 是否激活}
  S1 -- 是 --> S2[RESET]
  S1 -- 否 --> S3[POWER]
  S2 --> S3
  S3 --> S4[HOME]
  S4 --> S5[选择模式]

  S5 --> M1[MANUAL]
  M1 --> M2[JOG X/Y 或其他轴]
  M2 --> M3[DRO 与 runtime feedback 更新]

  S5 --> A1[AUTO]
  A1 --> A2[选择 LinuxCNC 5-axis source]
  A2 --> A3[TCP 按钮或程序内 M428]
  A3 --> A4[RUN / STEP / PAUSE / RESUME / STOP]
  A4 --> A5[G-code 当前行、DRO、Three.js 执行轨迹同步]

  S5 --> D1[MDI]
  D1 --> D2[输入 MDI 命令]
  D2 --> D3[执行命令]
  D3 --> M3

  A5 --> Q[Info Tabs 诊断]
  M3 --> Q
  Q --> Q1[Task policy]
  Q --> Q2[INI/project]
  Q --> Q3[Task/HAL]
  Q --> Q4[Full boundary]
  Q --> Q5[Host/native false 状态]
  Q --> Q6[Tool DB/User-M Web simulation]
```

## 10. Native Task/HAL 专项流程图

高清 PNG：![Native Task/HAL 专项流程图](diagram-assets/04-native-task-hal-flow.png)

```mermaid
flowchart TD
  N0[阶段0 源码和构建清单补齐] --> N1[阶段1 Native 对照探针]
  N1 --> N2[阶段2 HAL 内存模型和线程调度器]
  N2 --> N3[阶段3 Motion realtime 同步最小闭环]
  N3 --> N4[阶段4 Task runtime 移植]
  N4 --> N5[阶段5 TRT machine-file session 接入]
  N5 --> N6[阶段6 SWITCHKINS/M428/M429/M430 同步]
  N6 --> N7[阶段7 Browser Worker 和 store 接线]
  N7 --> N8[阶段8 Full boundary 提升]

  N8 --> W[Web simulation boundary promoted]
  W --> C1[nativeTaskReady=true 仅限 Web simulation]
  W --> C2[nativeHalSyncReady=true 仅限 Web simulation]
  W --> C3[fullLinuxCncProgramExecutionReady=true 仅限仿真边界]

  W -. 仍为 false .-> B1[hardwareDrive=false]
  W -. 仍为 false .-> B2[hostRealtimeKernel=false]
  W --> B3[externalUserMProcessReady=true web_simulation_only]
  W --> B4[toolDbProcessReady=true web_simulation_only]
  W -. host 仍为 false .-> B5[hostExternalUserMProcessReady=false]
  W -. host 仍为 false .-> B6[hostToolDbProcessReady=false]
```

## 11. 文档维护建议

更新规则：

1. 改项目范围或边界：先改 `implementation-plan.md`，再改 `technical-roadmap.md`。
2. 改工程步骤或新增 runtime：更新 `program-implementation-guide.md`。
3. 改 Task/HAL、motion、native probe、Worker 接线：更新 `native-task-hal-sync-implementation-steps.md`。
4. 完成一批开发：更新 `development-continuation.md` 和 `traceability-matrix.md`。
5. 增加 LinuxCNC 对标来源：更新 `linuxcnc-parity-matrix.md` 或对应参考文档。
6. 改 UI 操作或截图：更新 `manual-assets` 和新版 Word 操作手册。
7. 任何 fixture、fallback、UI-only 结果都不能写成 LinuxCNC runtime proof。

最容易混淆的边界：

| 名称 | 可以说明 | 不能说明 |
| --- | --- | --- |
| Three.js 预览 | 显示 LinuxCNC runtime 输出的路径、TCP、刀轴、当前段。 | Three.js 自己解释 G-code 或生成 CNC 运动语义。 |
| Python GUI 参考 | 参考界面布局、机床模型层级、HAL 控件结构。 | 在浏览器中运行 Tk/PyQt/GTK/gmoccapy native runtime。 |
| Web simulation task/HAL | 在浏览器 WASM/Worker 中按仿真边界同步 task/motion/HAL 状态。 | 驱动真实硬件、接入 host realtime kernel、替代 LinuxCNC native realtime。 |
| `gmoccapy-xyzab` | 参考 gmoccapy native 启动、HAL、按钮和 gate。 | 证明 TRT/RTCP 五轴运动学。 |
| OPFS memory fallback | 当前页面生命周期内继续 staging/save/restore。 | 跨刷新持久化。 |

## 12. 快速查找

| 想查的问题 | 推荐文件 |
| --- | --- |
| 项目为什么不直接控制真实机床？ | `implementation-plan.md`、`native-task-hal-sync-implementation-steps.md` |
| 第一版 Web UI 应该长什么样？ | `technical-roadmap.md`、`linuxcnc-gui-reference-gallery.md` |
| 具体从哪个文件开始写代码？ | `program-implementation-guide.md` |
| 下一轮工作基线是什么？ | `development-continuation.md` 的“最新接续基线” |
| 某功能对应哪个 LinuxCNC 源文件？ | `traceability-matrix.md` |
| 真实五轴程序有哪些？ | `linuxcnc-parity-matrix.md`、新版操作手册 |
| Task/HAL runtime 怎么实现？ | `native-task-hal-sync-implementation-steps.md` |
| gmoccapy XYZAB 与 Web 的关系是什么？ | `gmoccapy-xyzab-reference.md` |
| 操作员怎么上电、回零、运行、MDI？ | `Web-RTCP五轴数控系统仿真界面操作手册新版.docx` |
| 手册截图从哪里来？ | `manual-assets/` |