完善五轴 RTCP 仿真与验证资料

2026-07-01 21:49:58 -04:00
parent ac4e855b2b
commit d0d58998ac
159 changed files with 6771594 additions and 339 deletions
--- a/web-rtcp-5axis-sim-plan/docs/docs-directory-file-guide.md
+++ b/web-rtcp-5axis-sim-plan/docs/docs-directory-file-guide.md
@@ -0,0 +1,578 @@
+# docs 目录文件作用详解与关联流程图
+
+生成日期：2026-07-01  
+适用目录：`/home/meswork/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/` |