wangdequan/cnc_wams

Fork 0

Files

mes123456 c4a721f6cf 提交当前项目改动

2026-07-02 08:01:34 -04:00

28 KiB

Raw Blame History

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

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

1. 文档集定位

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

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

推荐阅读顺序：

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

参考类文档可按需阅读：

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

2. 文件总览

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

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`

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

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

功能 -> 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 操作屏、状态区、工具区、探测区、大屏布局。

关键边界：

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 机床仿真参考。

当前推荐组合：

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 边界。

边界结论：

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。

重要说明：

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	1440 x 1000	主界面总览，展示预览区、DRO、G-code、右侧状态入口、底部控制栏。
manual-assets/02-power-home-manual.png	1440 x 1000	POWER 和 HOME 后的手动状态，用于说明上电、回零、MANUAL/AUTO 可用性。
manual-assets/03-right-sidebar-manual.png	108 x 958	手动状态下右侧纵向按钮局部图，用于说明 MANUAL/JOG/MDI/AUTO/TCP 入口状态。
manual-assets/04-auto-active.png	1440 x 1000	AUTO 激活后的整屏状态，用于说明自动模式、G-code 区和运行准备。
manual-assets/05-right-sidebar-auto.png	108 x 958	AUTO 激活后的右侧按钮局部图，用于说明 AUTO 绿色、MANUAL 灰色等颜色规则。
manual-assets/06-run-program.png	1440 x 1000	程序运行状态截图，用于说明 G-code 当前行、DRO、runtime feedback、刀具路径预览。
manual-assets/07-manual-jog.png	1440 x 1000	MANUAL/JOG 点动后的状态，用于说明 DRO 和轴值同步。
manual-assets/08-mdi-command.png	1440 x 1000	MDI 命令输入状态，用于说明 MDI 输入框和执行入口。
manual-assets/09-mdi-executed.png	1440 x 1000	MDI 执行后的状态，用于说明坐标、程序来源和 MDI 历史同步。
manual-assets/10-overrides-and-hal.png	1440 x 1000	倍率、HAL 输入、主轴、冷却截图，用于说明 Rapid/Feed/Spindle/Coolant 控件。
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. 临时锁文件说明

文件：

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

作用：

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

处理建议：

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

7. 文档分层关系图

高清 PNG：

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：

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：

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：

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. 文档维护建议

更新规则：

改项目范围或边界：先改 implementation-plan.md，再改 technical-roadmap.md。
改工程步骤或新增 runtime：更新 program-implementation-guide.md。
改 Task/HAL、motion、native probe、Worker 接线：更新 native-task-hal-sync-implementation-steps.md。
完成一批开发：更新 development-continuation.md 和 traceability-matrix.md。
增加 LinuxCNC 对标来源：更新 linuxcnc-parity-matrix.md 或对应参考文档。
改 UI 操作或截图：更新 manual-assets 和新版 Word 操作手册。
任何 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/`

28 KiB Raw Blame History Unescape Escape

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

1. 文档集定位

2. 文件总览

3. Markdown 文件详细说明

3.1 implementation-plan.md

3.2 technical-roadmap.md

3.3 program-implementation-guide.md

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

3.5 development-continuation.md

3.6 traceability-matrix.md

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

3.8 linuxcnc-python-gui-reference.md

3.9 linuxcnc-gui-reference-gallery.md

3.10 linuxcnc-parity-matrix.md

3.11 gmoccapy-xyzab-reference.md

4. Word 操作手册说明

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

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

5. manual-assets 截图资产说明

6. 临时锁文件说明

7. 文档分层关系图

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

9. 操作流程关联图

10. Native Task/HAL 专项流程图

11. 文档维护建议

12. 快速查找

28 KiB

Raw Blame History

3.1 `implementation-plan.md`

3.2 `technical-roadmap.md`

3.3 `program-implementation-guide.md`

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

3.5 `development-continuation.md`

3.6 `traceability-matrix.md`

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

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

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

3.10 `linuxcnc-parity-matrix.md`

3.11 `gmoccapy-xyzab-reference.md`

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

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

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