wangdequan/cnc_wams
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
wangdequan
2026-07-01 21:49:58 -04:00
parent ac4e855b2b
commit d0d58998ac
159 changed files with 6771594 additions and 339 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
web-rtcp-5axis-sim-plan/docs/development-continuation.md
View File

@@ -333,14 +333,14 @@ promotionAllowed=false
## 9. 当前状态
```text
status=M22_host_native_boundary_visibility_complete
status=M24_xyzbc_trt_kinematics_parity_complete
active_style=gmoccapy_5_axis
frontend_framework=none
ui_stack=html_css_typescript_es_modules
preview_stack=threejs
semantic_boundary=linuxcnc_owned
latest_batch=M22-host-native-boundary-visibility
latest_gate=host_native_boundary_ui=ok,hardware_drive_false_visible=1,host_realtime_false_visible=1,external_user_m_false_visible=1,tool_db_false_visible=1,threejs_program_preview_mode=program-preview-and-tool-execution,threejs_preview_source=linuxcnc-interpreter-wasm_or_linuxcnc-machine-file-remap-wasm,threejs_toolpath_preview_source=linuxcnc_interpreter_canonical_motion,threejs_tool_execution_trace_source=linuxcnc_tp_samples_or_task_motion_hal_feedback,threejs_path_fit_bounds=ok,threejs_current_segment_highlight=ok,threejs_rapid_feed_visual_distinction=ok,threejs_no_gcode_semantics_generation=ok,threejs_canvas_nonblank_desktop=ok,threejs_canvas_nonblank_mobile=ok,opfs_unavailable_detected=1,opfs_fallback_current_page_lifecycle_only=1,non_opfs_workflows_still_pass=1,public_http_smoke_no_uncaught_exception=1,real_linuxcnc_5axis_program_cases_smoke=ok,native_task_hal_source_artifact_audit=ok,task_hal_web_simulation_boundary_consistent=1,full_execution_boundary_smoke=ok,linuxcnc_kinematics_runtime_smoke=ok,linuxcnc_interpreter_runtime_smoke=ok,linuxcnc_ini_runtime_smoke=ok,full_linuxcnc_5axis_source_node_smoke=ok,machine_file_staging_smoke=ok,five_axis_session_smoke=ok,profile_boundary_smoke=ok,rtcp_store_smoke=ok,gmoccapy_shell_smoke=ok,gmoccapy_dist_smoke=ok
latest_batch=M24-xyzbc-trt-kinematics-parity
latest_gate=xyzac_trt_kinematics_runtime=ok,xyzbc_trt_kinematics_runtime=ok,xyzbc_b_axis_tcp_pose_preserved=1,tool_db_web_simulation_smoke=ok,staged_tool_tbl_loaded=1,tool_db_query_edit_save=1,tool_db_t_m6_g43_state=1,tool_db_memory_fallback_save=1,host_tool_db_process=0,tool_db_user_m_simulation_smoke=ok,tool_db_process_ready_web_simulation_only=1,external_user_m_process_ready_web_simulation_only=1,arbitrary_user_m_blocked=1,host_process_execution=0,host_native_boundary_ui=ok,hardware_drive_false_visible=1,host_realtime_false_visible=1,host_external_user_m_false_visible=1,host_tool_db_false_visible=1,threejs_program_preview_mode=program-preview-and-tool-execution,threejs_preview_source=linuxcnc-interpreter-wasm_or_linuxcnc-machine-file-remap-wasm,threejs_toolpath_preview_source=linuxcnc_interpreter_canonical_motion,threejs_tool_execution_trace_source=linuxcnc_tp_samples_or_task_motion_hal_feedback,threejs_path_fit_bounds=ok,threejs_current_segment_highlight=ok,threejs_rapid_feed_visual_distinction=ok,threejs_no_gcode_semantics_generation=ok,threejs_canvas_nonblank_desktop=ok,threejs_canvas_nonblank_mobile=ok,opfs_unavailable_detected=1,opfs_fallback_current_page_lifecycle_only=1,non_opfs_workflows_still_pass=1,public_http_smoke_no_uncaught_exception=1,real_linuxcnc_5axis_program_cases_smoke=ok,native_task_hal_source_artifact_audit=ok,task_hal_web_simulation_boundary_consistent=1,full_execution_boundary_smoke=ok,linuxcnc_kinematics_runtime_smoke=ok,linuxcnc_interpreter_runtime_smoke=ok,linuxcnc_ini_runtime_smoke=ok,full_linuxcnc_5axis_source_node_smoke=ok,machine_file_staging_smoke=ok,five_axis_session_smoke=ok,profile_boundary_smoke=ok,rtcp_store_smoke=ok,gmoccapy_shell_smoke=ok,gmoccapy_dist_smoke=ok
rtcp_ui_state=implemented_browser_worker_and_node_kinematics_wasm_frame_with_fixture_fallback
control_wiring=power_estop_reset_auto_manual_jog_mdi_run_stop_pause_step_overrides_coolant_spindle_preview_home_reload_full
gcode_loading=implemented_browser_file_text_staging_with_linuxcnc_interpreter_execution
@@ -355,7 +355,7 @@ pyvcp_hal_schema=implemented_xyzac_trt_switchkins
linuxcnc_boundary_adapter=kinematics_and_interpreter_runtime_connected_remap_planner_missing
full_execution_boundary=implemented_machine_file_remap_ready_with_planner_task_hal_blockers
host_native_boundary_visibility=implemented_ui_and_browser_smoke_guard_for_hardware_realtime_external_user_m_tool_db_false
linuxcnc_kinematics_wasm=browser_and_node_proof_ready_xyzac_trt
linuxcnc_kinematics_wasm=browser_and_node_proof_ready_xyzac_trt_and_node_direct_xyzbc_trt_b_axis_tcp_pose
browser_kinematics_wasm=worker_connected_source_and_dist_xyzac_trt
linuxcnc_interpreter_wasm=browser_worker_and_node_direct_canonical_program_execution_ready_with_switchkins_mcode_preservation
browser_interpreter_wasm=worker_connected_source_and_dist
@@ -368,6 +368,7 @@ planner_task_hal_gap=closed_for_web_simulation_boundary_with_task_motion_hal_was
native_task_hal_sync_plan=docs_native_task_hal_sync_implementation_steps_ready
native_task_hal_phase0_8=source_manifest_native_probe_hal_runtime_motion_hal_sync_task_shim_sdk_machine_file_store_ui_full_boundary_smokes_ready_and_m18_readiness_artifact_audited
native_task_hal_readiness_artifact=web-rtcp-5axis-sim-plan/build/readiness/native-task-hal-readiness.json
tool_db_user_m_web_simulation=ready_for_staged_tool_tbl_and_whitelisted_user_m
next_batch=none_from_development_continuation
```
@@ -379,7 +380,7 @@ next_batch=none_from_development_continuation
- Phase 3 minimal motion/HAL C ABI 已覆盖 servo cycle、program-line、switchkins、jog/status HAL 同步；
- Phase 4 minimal task/HAL C ABI 已覆盖 `lctask_*` session/stage/open/command/cycle/status/events，RUN/MDI/JOG/PAUSE/RESUME/ABORT 能从 task shim 驱动 motion/HAL runtime，并已补 SDK wrapper；
- Phase 5-8 已把 machine-file session、task/HAL runtime adapter、Worker/client 文件、store action mapping、gmoccapy diagnostics 和 full boundary gate 接上；
- `nativeTaskReady=true`、`nativeHalSyncReady=true` 当前只表示 Web simulation boundary 内的 task/motion/HAL WASM runtime proof；仍保持 `hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=false`、`toolDbProcessReady=false`。
- `nativeTaskReady=true`、`nativeHalSyncReady=true` 当前只表示 Web simulation boundary 内的 task/motion/HAL WASM runtime proof；`toolDbProcessReady=true` 和 `externalUserMProcessReady=true` 也只表示 Web simulation boundary 内的 staged `tool.tbl` 与白名单 user-M 仿真；仍保持 `hardwareDrive=false`、`hostRealtimeKernel=false`、`hostExternalUserMProcessReady=false`、`hostToolDbProcessReady=false`、`arbitraryUserMExecution=false`。
补充实施文档：
@@ -447,10 +448,13 @@ linuxcnc_source_program_case_coverage=ready_node_and_browser_guarded
nativeTaskReady=web_simulation_boundary_only
nativeHalSyncReady=web_simulation_boundary_only
opfs_degradation=ready_memory_fallback_current_page_lifecycle_only
toolDbProcessReady=true for web_simulation_only
externalUserMProcessReady=true for web_simulation_only
hardwareDrive=false
hostRealtimeKernel=false
externalUserMProcessReady=false
toolDbProcessReady=false
hostExternalUserMProcessReady=false
hostToolDbProcessReady=false
arbitraryUserMExecution=false
```
已通过的当前 gate：
@@ -524,7 +528,7 @@ threejs_generated_toolpath_semantics=forbidden
1. 不用 Web 侧自定义状态机替代 LinuxCNC task/HAL/motion 语义。
2. 不把 browser simulation boundary 扩大描述为真实硬件 runtime。
3. `nativeTaskReady=true`、`nativeHalSyncReady=true` 只允许在 Web simulation boundary 内成立，除非另有 host-native 对照和 WASM 比对 artifact。
4. `hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=false`、`toolDbProcessReady=false` 必须继续明确展示。
4. `hardwareDrive=false`、`hostRealtimeKernel=false`、`hostExternalUserMProcessReady=false`、`hostToolDbProcessReady=false`、`arbitraryUserMExecution=false` 必须继续明确展示；`externalUserMProcessReady=true`、`toolDbProcessReady=true` 只能附带 `web_simulation_only`。
5. 不修改用户个人备忘文件；本项目接续只写 `docs/development-continuation.md` 和必要工程文档。
### 16.4 下一批直接执行任务
@@ -569,8 +573,10 @@ task_hal_web_simulation_boundary_consistent=1
native_task_hal_host_probe_status=passed_or_ready_disabled_by_default_or_skipped_missing_host_runtime
hardware_drive=0
host_realtime_kernel=0
external_user_m_process_ready=0
tool_db_process_ready=0
external_user_m_process_ready=1
tool_db_process_ready=1
host_external_user_m_process_ready=0
host_tool_db_process_ready=0
promotion_scope=web_simulation_only
```
@@ -580,7 +586,7 @@ promotion_scope=web_simulation_only
- 新增 `tests/node/verify_native_task_hal_audit.mjs`，默认运行 `wasm-port/tests/native/verify_task_hal_phase0.sh` 刷新 source/probe 证据；
- 生成机器可读 artifact `build/readiness/native-task-hal-readiness.json`；
- `npm run smoke:node` 已接入该 gate；
- 明确区分 `webSimulation.promoted=true` 与 `nativeHostAndHardware.hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=false`、`toolDbProcessReady=false`。
- 明确区分 `webSimulation.promoted=true`、`toolUserWebSimulation.externalUserMProcessReady=true`、`toolUserWebSimulation.toolDbProcessReady=true` 与 `nativeHostAndHardware.hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=false`、`toolDbProcessReady=false`。
当前 M18 gate：
@@ -590,8 +596,10 @@ task_hal_web_simulation_boundary_consistent=1
native_task_hal_host_probe_status=ready_disabled_by_default
hardware_drive=0
host_realtime_kernel=0
external_user_m_process_ready=0
tool_db_process_ready=0
external_user_m_process_ready=1
tool_db_process_ready=1
host_external_user_m_process_ready=0
host_tool_db_process_ready=0
promotion_scope=web_simulation_only
```
@@ -793,14 +801,14 @@ completed_with_host_native_boundary_ui_smoke
目标：
- 在 Web simulation boundary 已 promoted 时，继续明确展示非浏览器仿真范围；
- UI diagnostics 必须显示 `hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=false`、`toolDbProcessReady=false`；
- UI diagnostics 必须显示 `hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=true for web_simulation_only`、`toolDbProcessReady=true for web_simulation_only`、`hostExternalUserMProcessReady=false`、`hostToolDbProcessReady=false`、`arbitraryUserMExecution=false`；
- browser smoke 同时验证 state 字段和 DOM 文本，避免把 Web simulation promoted 误读为真实硬件、host realtime、外部 user-M 或 tool DB runtime ready。
已完成：
- gmoccapy info tabs 新增 `Host/native` 诊断行；
- `Host/native` 显示 hardware drive、host realtime、external user-M、tool DB 四项 false 状态；
- browser smoke 在 task/HAL full simulation boundary promoted 后验证四项 state 和 DOM 可见性。
- `Host/native` 显示 hardware drive、host realtime、Web tool/user 仿真 only、host external user-M、host tool DB、arbitrary user-M 状态；
- browser smoke 在 task/HAL full simulation boundary promoted 后验证 Web tool/user ready 与 host/native false 的 state 和 DOM 可见性。
当前 M22 gate：
@@ -808,11 +816,120 @@ completed_with_host_native_boundary_ui_smoke
host_native_boundary_ui=ok
hardware_drive_false_visible=1
host_realtime_false_visible=1
external_user_m_false_visible=1
tool_db_false_visible=1
external_user_m_web_simulation_only_visible=1
tool_db_web_simulation_only_visible=1
host_external_user_m_false_visible=1
host_tool_db_false_visible=1
arbitrary_user_m_false_visible=1
```
### 16.9 每轮必须执行的回归
### 16.9 M23：受控 tool DB / user-M Web 仿真
```text
M23-controlled-tool-db-user-m-web-simulation
```
状态：
```text
completed_with_linuxcnc_tooldb_index_spindle_semantics
```
目标：
- 对标 LinuxCNC `taskclass.cc`、`tooldata/*`、TRT remap subroutines 和受控 user-M 用法；
- 读取 staged `tool.tbl`，在 Web storage 中支持 OPFS/memory fallback 保存；
- 支持刀具号、刀长、刀径、刀袋的查询/编辑/保存；
- 接入 `Tn/M6/G43/M61` 仿真状态；
- 只允许白名单 `M128/M129/M428/M429/M430`，不执行任意系统脚本；
- UI 显示 `toolDbProcessReady=true for web_simulation_only` 和 `externalUserMProcessReady=true for web_simulation_only`。
已完成：
- 新增 `app/src/runtime/tool-db-simulation.js`；
- 新增 `app/src/runtime/controlled-user-m-simulation.js`；
- `tool-db-simulation.js` 按 LinuxCNC `CANON_TOOL_TABLE` 字段建模，保留非随机刀库的真实 `pocketno`，同时用内部 `idx=1..n` 表示 tool table 行，`idx=0` 固定为 spindle pocket；
- `Tn/M6/G43/M61` 按 `tooldata_find_index_for_tool()`、`Task::load_tool()`、`Task::read_tool_inputs()` 和 `convert_tool_length_offset()` 语义更新 `tool_prep_*`、`toolInSpindle`、`toolFromPocket`、`activeToolOffset` 与 #5400/#5401-#5413 参数；
- store 和浏览器入口暴露 `queryToolDb()`、`editToolDb()`、`saveToolDb()`，支持 staged `tool.tbl` 查询、编辑和 OPFS/memory fallback 保存；
- store 在 machine-file staging 后自动解析 profile 的 staged `tool.tbl`；
- store 在加载 LinuxCNC source program 时扫描 tool commands 和受控 user-M 事件；
- full boundary 把 tool DB/user-M 纳入 Web promotion gate，同时保留 host/native false；
- gmoccapy info tabs 新增 `Tool/User process` 诊断；
- 新增 `tests/node/verify_tool_db_web_simulation.mjs` 与 `tests/node/verify_tool_db_user_m_simulation.mjs` 并接入 `smoke:node`。
当前 M23 gate：
```text
tool_db_web_simulation_smoke=ok
staged_tool_tbl_loaded=1
tool_db_query_edit_save=1
tool_db_t_m6_g43_state=1
tool_db_memory_fallback_save=1
host_tool_db_process=0
tool_db_user_m_simulation_smoke=ok
tool_db_process_ready_web_simulation_only=1
external_user_m_process_ready_web_simulation_only=1
arbitrary_user_m_blocked=1
host_process_execution=0
```
边界：
```text
toolDbProcessReady=true for web_simulation_only
externalUserMProcessReady=true for web_simulation_only
hostToolDbProcessReady=false
hostExternalUserMProcessReady=false
arbitraryUserMExecution=false
```
### 16.10 M24：XYZBC TRT kinematics parity proof
```text
M24-xyzbc-trt-kinematics-parity
```
状态：
```text
completed_with_b_axis_tcp_pose_preserved
```
目标：
- 对标 LinuxCNC `xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`trtfuncs.c` 和 `switchkins.c`；
- Node direct runtime 同时证明 `linuxcnc_xyzac_trt_kinematics.wasm` 与 `linuxcnc_xyzbc_trt_kinematics.wasm`；
- 使用 `switchkinsType=1` 验证 TCP 模式正解/逆解闭环；
- `rtcpFrame.tcpPose` 同时保留 `a/b/c`，避免 XYZBC 的 B 轴姿态在 UI 诊断链路中丢失；
- Three.js `data-three-tcp-pose` 输出 B 轴，方便浏览器 smoke 和人工检查。
已完成：
- `app/src/runtime/rtcp-frame.js` 的 fixture frame 和 LinuxCNC kinematics frame 均输出 `tcpPose.b`；
- `app/src/visualization/five-axis-scene.js` 的 rounded TCP pose dataset 输出 `b`；
- `tests/node/verify_linuxcnc_kinematics_runtime.mjs` 扩展为 XYZAC/XYZBC 双模块 runtime proof，校验 wasm 文件、switchkins type、forward/inverse rc、关节闭环、A/B/C TCP 姿态与刀轴方向；
- `tests/node/verify_rtcp_store.mjs` 增加 XYZBC store 状态对 `tcpPose.b` 的保持校验。
当前 M24 gate：
```text
xyzac_trt_kinematics_runtime=ok
xyzbc_trt_kinematics_runtime=ok
linuxcnc_kinematics_runtime_smoke=ok
xyzbc_b_axis_tcp_pose_preserved=1
rtcp_store_smoke=ok
```
边界：
```text
semanticBoundary=linuxcnc_kinematics_wasm_c_abi
scope=node_direct_web_runtime_proof
hardwareDrive=false
hostRealtimeKernel=false
```
### 16.11 每轮必须执行的回归
常规回归：
@@ -979,7 +1096,7 @@ completed_with_real_linuxcnc_5axis_source_program_smoke
已完成：
- machine-file staging 从 LinuxCNC source manifest 中追加 TRT `demos/*.ngc`，包括 `boat-xyzac.ngc`、`boat-xyzbc.ngc`、`impeller-7bl-xyzac.ngc`、`xyzac_switchkins*.ngc`、`xyzbc_switchkins.ngc`；
- `selectMachineFileProgram()` 强制 5 轴 G-code 必须来自 LinuxCNC 源程序目录 `configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc`；
- `selectMachineFileProgram()` 强制 5 轴 G-code 必须来自当前 profile 对应的 LinuxCNC 源程序目录；axis/vismach 使用 `configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc`，gmoccapy TRT 使用 `configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/*.ngc`；
- 新增 `listLinuxCncGcodeSources()` 和 `selectMachineFileProgram()`；
- store 新增 `LOAD_LINUXCNC_GCODE_SOURCE`，可把 staged LinuxCNC 真实 5 轴 `.ngc` 源文件加载到 G-code 面板；
- gmoccapy G-code 面板新增 LinuxCNC 5-axis source 下拉框和 staging 按钮；
@@ -992,7 +1109,7 @@ completed_with_real_linuxcnc_5axis_source_program_smoke
gcodeSourceBoundary=linuxcnc_vendored_5axis_gcode_source_file
sourceMode=linuxcnc-vendored-5axis-gcode
machineFileBackedRunProgram=selected_staged_linuxcnc_ngc_source
sourceDirectoryGuard=configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc only
sourceDirectoryGuard=profile_specific_linuxcnc_demos_or_gmoccapy_examples_only
remapRuntimeReady=true for staged fiveAxisRemap C ABI run
plannerRuntimeReady=false
nativeTaskReady=false

39
web-rtcp-5axis-sim-plan/docs/diagram-assets/01-docs-layer-relationship.mmd Normal file
View File

@@ -0,0 +1,39 @@
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

BIN
web-rtcp-5axis-sim-plan/docs/diagram-assets/01-docs-layer-relationship.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 368 KiB

27
web-rtcp-5axis-sim-plan/docs/diagram-assets/02-linuxcnc-to-web-simulation-flow.mmd Normal file
View File

@@ -0,0 +1,27 @@
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]
L7[LinuxCNC tooldata/task 与 remap user-M 来源] --> E[tool DB + controlled user-M Web simulation]
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
E --> 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]
E -. 不执行 .-> X1[任意 host user-M 脚本]
E -. 不提升 .-> X2[host tool DB process]

BIN
web-rtcp-5axis-sim-plan/docs/diagram-assets/02-linuxcnc-to-web-simulation-flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 132 KiB

31
web-rtcp-5axis-sim-plan/docs/diagram-assets/03-operator-workflow.mmd Normal file
View File

@@ -0,0 +1,31 @@
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]

BIN
web-rtcp-5axis-sim-plan/docs/diagram-assets/03-operator-workflow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 181 KiB

22
web-rtcp-5axis-sim-plan/docs/diagram-assets/04-native-task-hal-flow.mmd Normal file
View File

@@ -0,0 +1,22 @@
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 --> C4[toolDbProcessReady=true web_simulation_only]
W --> C5[externalUserMProcessReady=true web_simulation_only]
W -. 仍为 false .-> B1[hardwareDrive=false]
W -. 仍为 false .-> B2[hostRealtimeKernel=false]
W -. host 仍为 false .-> B3[hostExternalUserMProcessReady=false]
W -. host 仍为 false .-> B4[hostToolDbProcessReady=false]
W -. 仍为 false .-> B5[arbitraryUserMExecution=false]

BIN
web-rtcp-5axis-sim-plan/docs/diagram-assets/04-native-task-hal-flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 86 KiB

BIN
web-rtcp-5axis-sim-plan/docs/docs-directory-file-guide.docx Normal file
View File

Binary file not shown.

578
web-rtcp-5axis-sim-plan/docs/docs-directory-file-guide.md Normal file
View File

@@ -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/` |

BIN
web-rtcp-5axis-sim-plan/docs/external-user-m-tool-db-simulation-plan.docx Normal file
View File

Binary file not shown.

224
web-rtcp-5axis-sim-plan/docs/external-user-m-tool-db-simulation-plan.md Normal file
View File

@@ -0,0 +1,224 @@
# External user-M / Tool DB Web 仿真实施方案
生成日期：2026-07-01
## 1. 目标
本文件把图中红框 `external user-M/tool DB process` 从“明确不包含”推进为
Web/WASM 仿真边界内的可验证能力：
```text
toolDbProcessReady=true for web_simulation_only
externalUserMProcessReady=true for web_simulation_only
hardwareDrive=false
hostRealtimeKernel=false
arbitraryHostProcessExecution=false
```
该能力只表示浏览器仿真可以读取、编辑、保存 tool table，并能执行受控白名单
user-M/remap 事件。它不启动 host native LinuxCNC 外部进程，不执行任意 shell 脚本，
不接入真实 HAL shared memory，不驱动真实机床 IO。
## 2. LinuxCNC 对标源程序
### 2.1 Tool DB / tool table
主要参考：
```text
linuxcnc/src/emc/task/taskclass.cc
linuxcnc/src/emc/task/taskclass.hh
linuxcnc/src/emc/tooldata/tooldata.hh
linuxcnc/src/emc/tooldata/tooldata_common.cc
linuxcnc/src/emc/tooldata/tooldata_mmap.cc
linuxcnc/src/emc/tooldata/tooldata_db.cc
linuxcnc/src/emc/tooldata/tooldata_nml.cc
linuxcnc/src/emc/nml_intf/emc.hh
linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc
```
关键 LinuxCNC 语义：
- `[EMCIO] TOOL_TABLE` 指向 tool table 文件。
- `[EMCIO] DB_PROGRAM` 存在时，native LinuxCNC 会启用工具数据库进程模式，并可能忽略普通 tool table 文件。
- `Task::emcToolPrepare()` 设置 `iocontrol.0.tool-prepare`、`tool-prep-number`、`tool-prep-pocket`、`tool-prep-index`。
- `Task::emcToolLoad()` 设置 `iocontrol.0.tool-change`，等待 `iocontrol.0.tool-changed`。
- `Task::read_tool_inputs()` 在 `tool-prepared` 或 `tool-changed` 输入到达后更新 `toolInSpindle`、`toolFromPocket`、`pocketPrepped` 并复位 HAL pin。
- `Task::emcToolSetOffset()` 更新 tool offset、diameter、front/back angle、orientation，并保存 tool table。
- `Task::emcToolSetNumber()` 对应 `M61` 设置当前刀具号。
本项目第一阶段只实现上述语义的 Web 仿真子集，不实现 LinuxCNC native DB_PROGRAM
外部进程协议。
### 2.2 user-M / remap
主要参考：
```text
linuxcnc/src/emc/rs274ngc/interp_* # user M / remap 解释入口
linuxcnc/src/emc/task/emctask.cc
linuxcnc/src/emc/task/emccanon.cc
linuxcnc/src/emc/nml_intf/emc.hh
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/428remap.ngc
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/429remap.ngc
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/430remap.ngc
linuxcnc/configs/sim/qtaxis/non-trivial/scara/remap_subs/428remap.ngc
linuxcnc/configs/sim/qtaxis/non-trivial/scara/remap_subs/429remap.ngc
linuxcnc/configs/sim/qtaxis/non-trivial/scara/remap_subs/430remap.ngc
```
关键 LinuxCNC 语义：
- native user-M 可以调用外部可执行文件或 remap 子程序。
- `M428/M429/M430` 在 TRT/switchkins 配置中通过 remap 子程序、`M68`、`M66`
和 HAL pin 同步 `motion.switchkins-type`。
- 任意 user-M 外部程序可能访问文件、HAL、IO 或系统命令，不能在浏览器中直接执行。
本项目只允许白名单 user-M/remap 行为。白名单事件必须能追溯到 vendored
LinuxCNC 配置或 remap 文件，并在 Worker/WASM/Web runtime 中输出结构化 event 和
HAL/state patch。
## 3. Web 仿真功能范围
### 3.1 Tool DB Web/WASM simulation
必须支持：
- 读取 staged `tool.tbl`。
- 解析 `T`、`P`、`X/Y/Z/A/B/C/U/V/W`、`D`、`I`、`J`、`Q`、`; comment`。
- 查询工具号、刀袋、直径、长度/坐标偏置。
- 编辑并保存工具号、刀袋、刀长、刀径。
- OPFS 可用时持久保存；OPFS 不可用时使用 memory fallback，范围限定为当前页面生命周期。
- 按 LinuxCNC `CANON_TOOL_TABLE` 字段建模：`toolno`、`pocketno`、`offset`、`diameter`、`frontangle`、`backangle`、`orientation`、`comment`。
- 按 LinuxCNC 非随机换刀器语义区分内部 `idx` 与真实 `pocketno`：
- staged `tool.tbl` 中的 `P` 保留为 `pocketno`；
- Web tool table 内部从 `idx=1` 顺序装载；
- `idx=0` 固定为 spindle pocket。
- 接入 `Tn/M6/G43/M61` 的仿真状态：
- `Tn`：按 `tooldata_find_index_for_tool()` 语义找到内部 `idx`，设置 `tool_prep_*` HAL pins。
- HAL loopback：`read_tool_inputs()` 语义把 `tool_prepared` 转换为 `pocketPrepped`。
- `M6`：按 `Task::emcToolLoad()` 和 `read_tool_inputs()` 把已准备刀具复制到 spindle pocket `idx=0`，设置 `toolInSpindle`、`toolFromPocket`、`tool_number`。
- `G43 Hn`：按 `convert_tool_length_offset()` 使用 tool table offset，设置 `activeToolOffset` 和 #5400/#5401-#5413 参数快照。
- `M61 Qn`：直接设置当前刀具号。
- 保存时按 LinuxCNC `tooldata_format_toolline()` 风格输出，例如 `T4 P44 D+12.500000 Z+42.250000`。
- UI diagnostics 显示 `toolDbProcessReady=true for web_simulation_only`。
第一阶段不支持：
- LinuxCNC native `DB_PROGRAM` 外部工具数据库进程。
- 随机刀库完整换刀策略。
- 任意 host 文件系统写入。
- 真实 IO 或真实换刀机构。
### 3.2 受控 user-M simulation
必须支持：
- 不执行任意系统脚本。
- 只允许白名单内的 vendored M-code/remap 行为。
- 在 Worker/WASM/Web runtime 边界输出结构化 event：
```text
code
allowed
sourceRel
semanticBoundary
halPatch
statePatch
promotionScope=web_simulation_only
hostExecution=false
```
第一批白名单：
| code | 来源 | Web 仿真效果 |
| --- | --- | --- |
| `M428` | TRT `428remap.ngc` / switchkins config | `motion.switchkins-type=1`，RTCP/TCP on |
| `M429` | TRT `429remap.ngc` / switchkins config | `motion.switchkins-type=0`，identity |
| `M430` | TRT `430remap.ngc` / switchkins config | `motion.switchkins-type=2`，userk |
| `M128` | millturn/user-M reference | 受控事件，switchkins/tool state 可追溯，不执行 host script |
| `M129` | millturn/user-M reference | 受控事件，switchkins/tool state 可追溯，不执行 host script |
不在白名单内的 `M100-M199` 或任意外部程序必须 blocked，并输出 blocked evidence。
## 4. 代码落点
建议新增：
```text
app/src/runtime/tool-db-simulation.js
app/src/runtime/controlled-user-m-simulation.js
tests/node/verify_tool_db_user_m_simulation.mjs
```
建议更新：
```text
app/src/runtime/full-execution-boundary.js
app/src/state/store.js
app/src/ui/gmoccapy-shell.js
app/package.json
docs/implementation-plan.md
docs/program-implementation-guide.md
docs/native-task-hal-sync-implementation-steps.md
docs/development-continuation.md
docs/traceability-matrix.md
docs/linuxcnc-parity-matrix.md
docs/docs-directory-file-guide.md
docs/diagram-assets/02-linuxcnc-to-web-simulation-flow.mmd/png
docs/diagram-assets/04-native-task-hal-flow.mmd/png
```
## 5. 验收 gate
Node smoke：
```text
node web-rtcp-5axis-sim-plan/tests/node/verify_tool_db_web_simulation.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_tool_db_user_m_simulation.mjs
npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
```
必须输出：
```text
tool_db_web_simulation_smoke=ok
staged_tool_tbl_loaded=1
tool_db_query_edit_save=1
tool_db_t_m6_g43_state=1
tool_db_memory_fallback_save=1
host_tool_db_process=0
tool_db_user_m_simulation_smoke=ok
tool_db_process_ready_web_simulation_only=1
external_user_m_process_ready_web_simulation_only=1
arbitrary_user_m_blocked=1
host_process_execution=0
```
UI 必须显示：
```text
Tool DB/User-M: tool DB web simulation ready / controlled user-M ready
Host/native: hardware drive false / host realtime false / external user-M web simulation only / tool DB web simulation only
```
## 6. 边界声明
完成后允许：
```text
toolDbProcessReady=true
externalUserMProcessReady=true
toolDbProcessScope=web_simulation_only
externalUserMProcessScope=web_simulation_only
```
仍必须保持：
```text
hardwareDrive=false
hostRealtimeKernel=false
hostToolDbProcess=false
hostExternalUserMProcess=false
arbitraryUserMExecution=false
```

80
web-rtcp-5axis-sim-plan/docs/gmoccapy-xyzac-trt-rtcp-verification-evaluation.md Normal file
View File

@@ -0,0 +1,80 @@
# gmoccapy XYZAC TRT RTCP 五轴对标验证评价
日期：2026-07-01
## 1. 评价结论
`gmoccapy-xyzac-trt` 页面功能已在 Web 仿真边界内对标 LinuxCNC `gmoccapy` 非平凡五轴 TRT 示例。结论为：通过。
通过范围是浏览器/Web/WASM 仿真边界：页面 profile、INI/HAL/TBL/NGC 项目文件 staging、gmoccapy POSTGUI 工具与主轴 HAL 语义、固定 TRT 默认 TCP 运动学、LinuxCNC interpreter canonical motion、TP planner sample、RTCP frame、DRO/Three.js 页面状态和 source guard 均已验证。该结论不声明原生 GTK `gmoccapy.py` 已移植，不声明真实硬件、host realtime kernel、host HAL shared memory、native LinuxCNC task 进程或 host tool DB process 已就绪。
## 2. LinuxCNC 基线
本轮对标的 LinuxCNC 来源位于 `/home/meswork/cnc_wams/linuxcnc`：
| 类别 | 基线文件 | 对标要点 |
| --- | --- | --- |
| gmoccapy TRT INI | `configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/xyzac-trt.ini` | `DISPLAY=gmoccapy`、`OPEN_FILE=./examples/impeller-7bl-xyzac.ngc`、`JOG_AXES=XYZC`、`TRAJ=XYZAC`、`KINEMATICS=xyzac-trt-kins` |
| gmoccapy POSTGUI HAL | `configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/postgui.hal` | `gmoccapy.spindle_feedback_bar`、`gmoccapy.spindle_at_speed_led`、`gmoccapy.toolchange-*`、`gmoccapy.tooloffset-z` |
| generated HAL / tool table / vars | `xyzac-trt_cmds.hal`、`xyzac-trt.tbl`、`xyzac.var` | gmoccapy 机床项目文件、刀具表和 task/HAL session 来源 |
| remap macros | `configs/sim/gmoccapy/macros/change_g43.ngc`、`settool_g43.ngc` | `M6`、`M61` gmoccapy 工具更换/设刀 remap |
| 实际五轴程序 | `examples/impeller-7bl-xyzac.ngc`、`boat-xyzac.ngc`、`boat-xyzbc.ngc`、`test-xyzac.ngc`、`test-xyzbc.ngc` | gmoccapy TRT 示例程序 staging、选择、解释、预览 |
| 运动学源码 | `src/emc/kinematics/xyzac-trt-kins.c`、`trtfuncs.c`、`switchkins.c` | TRT 正逆解、TCP/identity/userk 类型语义 |
关键差异已经显式建模：axis/vismach TRT profile 使用 `sparm=identityfirst`，`switchkinsType=1` 为 TCP；gmoccapy TRT INI 不带 `sparm=identityfirst`，因此默认 type 0 即固定 TRT/TCP。Web profile 将这一点映射为 `kinsType=tcp-xyzac`、`rtcpState=on` 的默认状态。
## 3. Web 对标实现
| 实现项 | 文件 | 评价 |
| --- | --- | --- |
| 新增 profile | `app/src/profiles/gmoccapy-xyzac-trt.js`、`app/src/profiles/index.js` | 已对齐 gmoccapy INI 路径、display、open file、jog axes、M6/M61 remap、POSTGUI HAL、tool table、fixed TRT 默认 TCP |
| source reference | `app/src/profiles/source-reference-map.js` | 已把 gmoccapy TRT INI、HAL、TBL、examples、macros、kinematics source 纳入可追溯来源 |
| vendored LinuxCNC 文件 | `../wasm-port/vendor/linuxcnc/configs/sim/gmoccapy/...`、`../wasm-port/tools/source-manifest.txt` | 已复制 LinuxCNC gmoccapy TRT 配置、examples 和 macros；manifest 已纳入这些文件 |
| machine-file staging | `app/src/runtime/linuxcnc-machine-file-staging.js` | 已支持 profile-specific `machineRel`、`demoDirectory=examples`、gmoccapy examples source guard、OPFS/memory fallback |
| INI parser | `app/src/runtime/linuxcnc-ini-runtime.js` | 已区分 switchkins TRT 与 gmoccapy fixed TRT；gmoccapy 不强制 HALUI M428/M429/M430 和 `HAL_PIN_VARS=1`，改为要求 M6/M61 与 gmoccapy HALCMD 关键项 |
| store/main | `app/src/state/store.js`、`app/src/main.js` | 已让 fixed TRT 默认进入 `tcp-xyzac`/RTCP on，并按 profile 默认加载 `impeller-7bl-xyzac.ngc` |
| build/static | `app/scripts/build-static.mjs` | 已把 gmoccapy config assets 复制到 source/dist 两套浏览器路径 |
| 页面 smoke | `tests/browser/gmoccapy_shell_smoke.html` | 已通过真实页面 profile selector 切换到 `gmoccapy-xyzac-trt`，验证 gmoccapy display、examples staging、INI、kinematics runtime、RTCP frame |
## 4. 测试与验证
| 测试项 | 验证内容 | 结果 |
| --- | --- | --- |
| profile/source map | profile 字段、fixed TRT 默认 type、gmoccapy HAL pins、source reference kinds | 通过 |
| INI 解析 | `xyzac-trt.ini` 的 DISPLAY、TRAJ、KINS、M6/M61、POSTGUI、HALCMD、servo/task period | 通过 |
| 文件 staging | gmoccapy INI、TBL、macros、examples 进入 staged project，source guard 接受 `/examples/` | 通过 |
| 实际程序解释 | `impeller-7bl-xyzac.ngc`、`boat-xyzac.ngc`、`boat-xyzbc.ngc` 由 LinuxCNC interpreter runtime 输出 canonical motion 与 planner samples | 通过 |
| 运动学/RTCP | `xyzac-trt` WASM 以 fixed TRT type 0 构造 source-derived RTCP frame，页面默认 RTCP on | 通过 |
| store/run preconditions | 切换 profile、加载 INI/runtime、加载 gmoccapy example、programValidation source guard、tool DB readiness、run preconditions | 通过 |
| 浏览器页面 | source 与 dist 页面均完成 gmoccapy shell smoke，并显式覆盖 `gmoccapy-xyzac-trt` profile 切换 | 通过 |
| 静态构建 | gmoccapy config assets 被复制到 dist 并通过浏览器 dist smoke | 通过 |
已执行命令及关键输出：
```text
node tests/node/verify_gmoccapy_xyzac_trt_parity.mjs
gmoccapy_xyzac_trt_parity_smoke=ok
npm --prefix app run smoke:node
xyzac_trt_kinematics_runtime=ok
xyzbc_trt_kinematics_runtime=ok
real_linuxcnc_5axis_program_cases_smoke=ok
machine_file_staging_smoke=ok
rtcp_store_smoke=ok
profile_boundary_smoke=ok
gmoccapy_xyzac_trt_parity_smoke=ok
gmoccapy_trt_project_sidebar_smoke=ok
linuxcnc_parity_matrix_smoke=ok
npm --prefix app run smoke
gmoccapy_shell_smoke=ok
gmoccapy_dist_smoke=ok
```
此前也已执行 `npm --prefix app run build`，输出 `gmoccapy_static_build=ok`。
## 5. 评价
`gmoccapy-xyzac-trt` 已达到本项目页面功能对标要求：页面选择、项目文件、默认程序、INI/HAL/TBL/macros、真实 gmoccapy TRT examples、fixed TCP 运动学和 RTCP 页面状态均来自 LinuxCNC 源文件或 source-derived runtime 证据，不再把 axis/vismach switchkins 配置误当作 gmoccapy fixed TRT 配置。
剩余边界不是本轮缺陷，而是明确的能力边界：浏览器不运行 native GTK gmoccapy，不连接 host HAL shared memory，不控制真实电机/IO，不启动 host realtime kernel，不执行任意 host user-M 或 native tool DB process。后续若要声明这些能力，需要新增 host/native 级验证，而不能沿用当前 Web simulation 结论。

5
web-rtcp-5axis-sim-plan/docs/implementation-plan.md
View File

@@ -33,7 +33,7 @@
- RTCP/TCP 五轴联动还没有作为独立 Web 产品能力完整闭环。
- 当前浏览器页面主要是通用 AXIS 风格仿真，还不是专门的五轴/RTCP 操作界面。
- TRT/bridge 五轴运动学虽然有 source coverage 和 probe 基础，但需要形成面向 UI 的统一五轴 pose/joint/TCP 数据模型。
- Python remap、tool DB、external user-M process 等 hard block 仍不能伪装成浏览器 PASS。
- 任意 Python remap、任意 external user-M host process、host tool DB process 等 hard block 仍不能伪装成浏览器 PASS；`tool.tbl` 和白名单 user-M 只允许在 `web_simulation_only` 边界内仿真。
- Python GUI 的 native 控件、HAL component 进程、Tk/PyQt/GTK 主循环和 OpenGLTk 不能直接作为 Web 运行时使用，需要转换成 Web 组件、Three.js 场景和 virtual HAL 数据绑定。
## 3. LinuxCNC 参考案例选择
@@ -218,7 +218,8 @@ JavaScript 不直接复写 trtfuncs.c / 5axiskins.c 的公式作为最终语义
- 真实伺服周期硬实时；
- 完整 LinuxCNC task/motion 进程；
- 任意 Python remap runtime；
- 任意 external user-M process；
- 任意 external user-M host process；
- 任意未在白名单内的 user-M 行为；
- 完整工业级碰撞检测；
- CAM 后处理器。

12
web-rtcp-5axis-sim-plan/docs/linuxcnc-parity-matrix.md
View File

@@ -11,7 +11,9 @@
| PyVCP/POSTGUI/HAL | `xyzac-trt.xml`、`xyzbc-trt.xml`、`switchkins_postgui.hal`、`xyzac-trt_cmds.hal` | SWITCHKINS 按钮语义、HALUI MDI 命令、`motion.switchkins-type` 映射 |
| remap 子程序 | `remap_subs/428remap.ngc`、`429remap.ngc`、`430remap.ngc` | `M428` TCP、`M429` identity、`M430` userk 的 kinstype 切换语义 |
| Vismach Python | `src/hal/user_comps/vismach/xyzac-trt-gui.py`、`xyzbc-trt-gui.py` | 机床预览层级、关节反馈 pin、刀补/偏置显示语义 |
| Kinematics C 源码 | `src/emc/kinematics/xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`trtfuncs.c`、`switchkins.c` | 正逆解、TCP/identity/userk 切换、DRO/TCP frame 更新 |
| Kinematics C 源码 | `src/emc/kinematics/xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`trtfuncs.c`、`switchkins.c` | XYZAC/XYZBC 正逆解、TCP/identity/userk 切换、DRO/TCP frame 更新；Node direct proof 覆盖 `switchkinsType=1`、A/B/C TCP 姿态和 XYZBC B 轴保留 |
| Tool DB / task tool state | `src/emc/task/taskclass.cc`、`src/emc/tooldata/tooldata_common.cc`、`src/emc/nml_intf/emctool.h`、`src/emc/rs274ngc/interp_convert.cc`、`xyzac-trt.tbl`、`xyzbc-trt.tbl` | staged `tool.tbl` 解析、`CANON_TOOL_TABLE` 字段、非随机刀库 `idx/pocketno` 分离、spindle pocket `idx=0`、tool prepare/load/read_tool_inputs/offset、OPFS/memory fallback 保存 |
| controlled user-M/remap | `remap_subs/428remap.ngc`、`429remap.ngc`、`430remap.ngc`、LinuxCNC millturn M128/M129 用法 | 白名单 `M128/M129/M428/M429/M430` 转换为可追溯 HAL/state 事件，不执行 host 脚本 |
| gmoccapy TRT 示例 | `configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/xyzac-trt.ini`、`postgui.hal` | gmoccapy 入口、POSTGUI 工具/主轴 HAL、TRT 示例程序来源 |
| gmoccapy 原生界面 | `src/emc/usr_intf/gmoccapy/gmoccapy.py`、`share/gmoccapy/gmoccapy.glade`、gmoccapy 图标清单 | 操作台布局、右侧状态入口、按钮颜色/禁用/激活规则、HAL pin 语义 |
| LinuxCNC task/NML | `src/emc/nml_intf/emc.hh`、`src/emc/task/emctaskmain.cc`、`src/emc/task/emctask.cc` | E-STOP/POWER/RESET、AUTO/MANUAL/JOG/MDI、RUN/PAUSE/RESUME/STEP/STOP 的互锁 |
@@ -31,6 +33,10 @@
| `demos/xyzac_switchkins_test_1.ngc` | M428/M429 多次切换验证 |
| `demos/xyzac_switchkins_test_2.ngc` | TCP/identity 过渡验证 |
| `demos/xyzac_switchkins_test_3.ngc` | switchkins 程序验证覆盖 |
| `gmoccapy/.../examples/impeller-7bl-xyzac.ngc` | gmoccapy fixed TRT 默认打开程序 |
| `gmoccapy/.../examples/boat-xyzac.ngc` | gmoccapy XYZAC TCP 船体程序 |
| `gmoccapy/.../examples/boat-xyzbc.ngc` | gmoccapy 示例目录中的 XYZBC TCP 程序，用于 interpreter/planner source guard 覆盖 |
| `gmoccapy/.../examples/test-xyzac.ngc`、`test-xyzbc.ngc` | gmoccapy TRT 示例 staging 完整性验证 |
## 3. 已承接的功能
@@ -46,10 +52,12 @@
| 预览路径 | Three.js/WebGL 预览程序路径、当前刀具位置、TCP 点和刀轴方向 |
| gmoccapy HAL 语义 | 硬按钮、jog、override、spindle、coolant、tool change、message/tool/user inputs 建模 |
| task/HAL 边界 | 保留 native task/HAL 与硬件实时边界，不把 Web 仿真误标为真实机床控制 |
| tool DB Web 仿真 | 读取 staged `tool.tbl`，支持刀具号/刀长/刀径/刀袋查询、编辑、保存；按 LinuxCNC 非随机刀库语义保留真实 `pocketno`，使用内部 `idx=1..n` 和 spindle pocket `idx=0`；接入 `Tn/M6/G43/M61`、HAL loopback `read_tool_inputs()` 与 #5400/#5401-#5413 工具参数快照 |
| 受控 user-M Web 仿真 | 只允许白名单 user-M/remap 行为输出 HAL/state patch；任意未白名单 user-M 被标记为 blocked |
## 4. 当前边界
- Web 端运行的是浏览器仿真状态机和 WASM/JS runtime，不运行原生 GTK `gmoccapy.py`。
- `gmoccapy.py`、Glade、Vismach Python 是界面/机床模型/HAL 语义参考，不是浏览器运行时。
- 硬件驱动、实时内核、真实 HAL shared memory、外部 user M 进程和真实 tool DB 不在浏览器内提升为 ready。
- 硬件驱动、实时内核、真实 HAL shared memory、host external user-M 进程、host tool DB process 不在浏览器内提升为 ready；`externalUserMProcessReady=true` 与 `toolDbProcessReady=true` 只代表 `web_simulation_only`。
- `linuxCncParityMatrix` 的 `semanticBoundary` 固定为 `linuxcnc_source_function_parity_matrix_for_browser_simulation_not_hardware_control`。

17
web-rtcp-5axis-sim-plan/docs/native-task-hal-sync-implementation-steps.md
View File

@@ -28,10 +28,16 @@ promotionAllowed=true for Web simulation boundary only
- 真实硬件 IO、Mesa/并口/伺服驱动；
- Linux 内核实时线程等同物；
- 任意外部 user-M 进程；
- 任意外部 user-M host 进程或系统脚本执行；
- Python GUI、GTK、Tk、QtVCP runtime；
- 未经过 LinuxCNC 源码边界验证的 JavaScript CNC 语义。
已单独实现但只限 Web simulation boundary：
- staged `tool.tbl` 的 tool DB Web/WASM 仿真；
- 白名单 `M128/M129/M428/M429/M430` 的受控 user-M 仿真；
- `Tn/M6/G43/M61` 与 HAL/state 事件的可追溯状态输出。
## 2. LinuxCNC 源程序参考清单
后续实现必须以这些源文件为主参考，不能用 Web 侧自定义状态机替代 CNC 语义：
@@ -182,7 +188,7 @@ ini.x.min_limit / ini.x.max_limit
ini.z.min_limit / ini.z.max_limit
```
这对 TRT `M428/M429/M430` 的 task/HAL 同步很有价值：可复用状态目标、guard pin、source-boundary report 的写法。但它仍然不执行 arbitrary external user-M process，不解除 native promotion。
这对 TRT `M428/M429/M430` 的 task/HAL 同步很有价值：可复用状态目标、guard pin、source-boundary report 的写法。当前实现已把这些模式收敛为白名单 user-M Web 仿真事件，但仍然不执行 arbitrary external user-M host process，不解除 native promotion。
### 4.5 kinematics 和 HAL shim 已有注意事项
@@ -798,6 +804,9 @@ Traceability document records every source file and boundary
```text
hardwareDrive=false
hostRealtimeKernel=false
externalUserMProcessReady=false unless separately implemented
toolDbProcessReady=false unless separately implemented
externalUserMProcessReady=true for web_simulation_only
toolDbProcessReady=true for web_simulation_only
hostExternalUserMProcessReady=false
hostToolDbProcessReady=false
arbitraryUserMExecution=false
```

32
web-rtcp-5axis-sim-plan/docs/program-implementation-guide.md
View File

@@ -186,7 +186,7 @@ plannerRuntimeReady=false
fullLinuxCncProgramExecutionReady=false
```
这只提升普通 G-code canonical execution source，不代表 Python remap、tool DB、external user-M process 或完整 planner 已 promoted。
这只提升普通 G-code canonical execution source，不代表任意 Python remap、host tool DB process、host external user-M process 或完整 planner 已 promoted。`tool.tbl` 读取/编辑/保存使用 Web/WASM tool DB 仿真边界：按 LinuxCNC `CANON_TOOL_TABLE` 字段、非随机刀库内部 `idx` 与真实 `pocketno`、spindle pocket `idx=0`、`Tn/M6/G43/M61` 和 `read_tool_inputs()` 语义运行；白名单 user-M 行为同样只能在 `web_simulation_only` 边界内声明 ready。
### Step 3：gmoccapy UI 组件
@@ -493,7 +493,8 @@ readiness
HAL runtime、HAL sync 和 task/HAL comparison artifact 都通过时，才允许在 Web
simulation boundary 内标记 `nativeTaskReady=true`、`nativeHalSyncReady=true` 和
`fullLinuxCncProgramExecutionReady=true`。该提升仍不代表 hardware drive、host realtime
kernel、external user-M process 或 tool DB process ready。
kernel、host external user-M process 或 host tool DB process ready；受控 user-M 和
tool DB 只能以 `web_simulation_only` 进入 full boundary。
当前边界：
@@ -507,7 +508,11 @@ nativeHalSyncReady=true for Web simulation boundary
fullLinuxCncProgramExecutionReady=true when machine-file remap and task/HAL gates also pass
hardwareDrive=false
hostRealtimeKernel=false
externalUserMProcessReady=false
externalUserMProcessReady=true for web_simulation_only
toolDbProcessReady=true for web_simulation_only
hostExternalUserMProcessReady=false
hostToolDbProcessReady=false
arbitraryUserMExecution=false
```
### Step 10：Native task/HAL readiness artifact
@@ -539,6 +544,8 @@ nativeHostAndHardware.hardwareDrive=false
nativeHostAndHardware.hostRealtimeKernel=false
nativeHostAndHardware.externalUserMProcessReady=false
nativeHostAndHardware.toolDbProcessReady=false
toolUserWebSimulation.externalUserMProcessReady=true
toolUserWebSimulation.toolDbProcessReady=true
gates.promotion_scope=web_simulation_only
```
@@ -550,8 +557,10 @@ task_hal_web_simulation_boundary_consistent=1
native_task_hal_host_probe_status=passed_or_ready_disabled_by_default_or_skipped_missing_host_runtime
hardware_drive=0
host_realtime_kernel=0
external_user_m_process_ready=0
tool_db_process_ready=0
external_user_m_process_ready=1
tool_db_process_ready=1
host_external_user_m_process_ready=0
host_tool_db_process_ready=0
promotion_scope=web_simulation_only
```
@@ -612,20 +621,23 @@ real_linuxcnc_5axis_program_cases_smoke=ok
- 不在 JavaScript 中实现 G-code 解释器。
- 不在 JavaScript 中实现 LinuxCNC 五轴运动学公式作为最终语义源。
- 不把 gmoccapy Python/GTK runtime 移植进浏览器。
- 不把 Python remap/tool DB/external user-M process 伪装成已支持。
- 不把任意 Python remap、host tool DB process、host external user-M process 伪装成已支持；只允许 staged `tool.tbl` 和白名单 user-M 在 Web/WASM 仿真边界内声明 ready。
- 不用 UI fixture 结果冒充 LinuxCNC runtime proof。
- 用于 5 轴 machine-file backed run 的 G-code 必须来自 LinuxCNC 源程序目录
`configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc`；
- 用于 5 轴 machine-file backed run 的 G-code 必须来自当前 profile 对应的 LinuxCNC 源程序目录：
`configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc` 或
`configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/*.ngc`；
用户上传或手写的 G-code 只能作为 operator file/普通 interpreter 输入，不得标记为
`linuxcnc-vendored-5axis-gcode` 或用于 5 轴源程序边界证明。
## 6. 开工建议
当前已完成 Step 1 到 Step 9 的 Node/browser LinuxCNC kinematics proof、浏览器 Worker kinematics 隔离、浏览器 Worker interpreter canonical execution source、`xyzac-trt`/`xyzbc-trt` profile 切换、OPFS 五轴会话保存/恢复、OPFS machine-file staging、machine-file backed `fiveAxisRemap` C ABI run、程序级 `M428/M429` switchkins RTCP 自动切换、LinuxCNC TP queue timing runtime、full execution boundary audit，以及真实 LinuxCNC TRT 5 轴 `.ngc` 源程序 staging/选择/运行路径。native task/HAL 执行文档的 Phase 0-8 已建立 Web simulation boundary：source manifest、默认禁用的 native TRT probe、HAL registry/thread scheduler、minimal motion/HAL servo-cycle C ABI、`lctask_*` task shim、SDK wrapper、machine-file session、store/UI diagnostics 和 full boundary gate。`M428/M429/M430` 当前既可作为 Web runtime switchkins 事件驱动 `lckins_switch()`，也可在 staged machine-file run 中交给 vendored LinuxCNC five-axis remap C ABI 验证，还可通过 task/HAL runtime 的 MDI path 写入 `motion.switchkins-type` HAL snapshot；只有 LinuxCNC source manifest 中的 `configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc` 可作为 `linuxcnc-vendored-5axis-gcode` 进入 UI 和 machine-file run。`web-rtcp-5axis-full-linuxcnc-execution-boundary` 可以在 kinematics/interpreter/machine-file-remap/TP/task-HAL gates 同时通过时报告 `promotionAllowed=true`，但该提升仅限 Web simulation boundary，仍必须显示 `hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=false` 和 `toolDbProcessReady=false`。
当前已完成 Step 1 到 Step 10 的 Node/browser LinuxCNC kinematics proof、浏览器 Worker kinematics 隔离、浏览器 Worker interpreter canonical execution source、`xyzac-trt`/`xyzbc-trt`/`gmoccapy-xyzac-trt` profile 切换、OPFS 五轴会话保存/恢复、OPFS machine-file staging、machine-file backed `fiveAxisRemap` C ABI run、程序级 `M428/M429` switchkins RTCP 自动切换、LinuxCNC TP queue timing runtime、full execution boundary audit、受控 tool DB/user-M Web 仿真，以及真实 LinuxCNC TRT 5 轴 `.ngc` 源程序 staging/选择/运行路径。native task/HAL 执行文档的 Phase 0-8 已建立 Web simulation boundary：source manifest、默认禁用的 native TRT probe、HAL registry/thread scheduler、minimal motion/HAL servo-cycle C ABI、`lctask_*` task shim、SDK wrapper、machine-file session、store/UI diagnostics 和 full boundary gate。`M428/M429/M430` 当前既可作为 Web runtime switchkins 事件驱动 `lckins_switch()`，也可在 staged machine-file run 中交给 vendored LinuxCNC five-axis remap C ABI 验证，还可通过受控 user-M Web 仿真输出可追溯 HAL/state patch。staged `tool.tbl` 当前可被 Web tool DB 读取、编辑、保存到 OPFS/memory fallback，并按 LinuxCNC `CANON_TOOL_TABLE`、非随机刀库 `idx/pocketno`、spindle pocket `idx=0`、`Tn/M6/G43/M61`、`read_tool_inputs()` 和 #5400/#5401-#5413 语义更新仿真状态；store/browser API 暴露 `queryToolDb()`、`editToolDb()`、`saveToolDb()` 供查询、编辑和保存。只有 LinuxCNC source manifest 中当前 profile 对应的 `configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc` 或 `configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/*.ngc` 可作为 `linuxcnc-vendored-5axis-gcode` 进入 UI 和 machine-file run。`web-rtcp-5axis-full-linuxcnc-execution-boundary` 可以在 kinematics/interpreter/machine-file-remap/TP/task-HAL/tool-DB/user-M gates 同时通过时报告 `promotionAllowed=true`，但该提升仅限 Web simulation boundary，仍必须显示 `hardwareDrive=false`、`hostRealtimeKernel=false`、`hostExternalUserMProcessReady=false`、`hostToolDbProcessReady=false` 和 `arbitraryUserMExecution=false`。
M24 已把 LinuxCNC kinematics runtime Node direct proof 从 `xyzac-trt` 扩展到 `xyzbc-trt`，并以 `switchkinsType=1` 验证两个 TRT WASM 模块的正解/逆解闭环。`rtcpFrame.tcpPose` 和 Three.js `data-three-tcp-pose` 现在同时输出 `a/b/c`，其中 XYZBC 的 B 轴姿态可被 store smoke 和浏览器诊断链路追溯，不再只依赖 C 轴或默认 A 轴字段。
OPFS session 和 machine-file staging 当前具备 capability 检测。安全上下文且 `navigator.storage.getDirectory()` 可用时使用 OPFS；公网 HTTP/IP 或浏览器禁用 OPFS 时切换到 memory fallback。memory fallback 只保证当前页面生命周期内的保存、恢复、staging 和 full boundary audit 可继续运行，不声明跨刷新持久化。UI diagnostics 必须显示 storage mode、OPFS unavailable 状态和原因，公共 HTTP smoke 必须验证无 uncaught exception，且不依赖 OPFS 的预览、DRO、G-code 加载、运行和 Three.js 显示继续通过。
gmoccapy info tabs 当前还必须显示 Host/native boundary：`hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=false`、`toolDbProcessReady=false`。browser smoke 需要同时检查 DOM 和 `fullExecutionBoundary` state，避免把 Web simulation promoted 误读为 host-native 或硬件能力 ready。
gmoccapy info tabs 当前还必须显示 Host/native boundary：`hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=true for web_simulation_only`、`toolDbProcessReady=true for web_simulation_only`、`hostExternalUserMProcessReady=false`、`hostToolDbProcessReady=false`、`arbitraryUserMExecution=false`。browser smoke 需要同时检查 DOM 和 `fullExecutionBoundary` state，避免把 Web simulation promoted 误读为 host-native 或硬件能力 ready。
注意：`wasm-port/tests/wasm/node/verify_hal_runtime.sh`、`wasm-port/tests/wasm/node/verify_motion_hal_sync.sh`、`wasm-port/tests/wasm/node/verify_task_hal_wasm.sh` 和 `wasm-port/tests/wasm/node/verify_task_hal_sdk.sh` 会写同一个 `build/wasm/task-hal/linuxcnc_task_hal.*` 输出，验证时应串行运行，避免并发构建竞争造成无效 WASM 产物。

219
web-rtcp-5axis-sim-plan/docs/traceability-matrix.md
View File

@@ -140,12 +140,12 @@ src/emc/kinematics/kins_util.c
| RTCP frame UI plumbing | implemented_fixture_and_kinematics_wasm | fixture fallback 仍为 `linuxCncKinematicsReady=false`；browser/node kinematics proof 为 `source-derived-kinematics-wasm` / `linuxcnc_kinematics_wasm_c_abi` |
| Operator workflow | implemented_linuxcnc_task_policy_with_canonical_motion | 上电/急停/复位/模式/JOG/MDI/RUN/PAUSE/RESUME/STOP/HOME 通过 `linuxcnc_task_state_mode_command_gate`；普通程序执行来自 LinuxCNC canonical motion |
| LinuxCNC boundary adapter | kinematics_and_interpreter_connected | `web-rtcp-5axis-linuxcnc-boundary-adapter` 可区分 kinematics-only ready 与 interpreter/remap missing |
| Full execution boundary audit | implemented_task_motion_hal_simulation_runtime | `web-rtcp-5axis-full-linuxcnc-execution-boundary` 汇总 kinematics/interpreter/machine-file-remap/TP/task-HAL evidence；Web simulation boundary 可提升，仍明确 `hardwareDrive=false`、`hostRealtimeKernel=false`、`externalUserMProcessReady=false`、`toolDbProcessReady=false` |
| Full execution boundary audit | implemented_task_motion_hal_simulation_runtime | `web-rtcp-5axis-full-linuxcnc-execution-boundary` 汇总 kinematics/interpreter/machine-file-remap/TP/task-HAL/tool-DB/user-M evidence；Web simulation boundary 可提升，仍明确 `hardwareDrive=false`、`hostRealtimeKernel=false`、`hostExternalUserMProcessReady=false`、`hostToolDbProcessReady=false`、`arbitraryUserMExecution=false` |
| PyVCP/HAL panel schema | implemented_reference_only | `xyzac-trt-switchkins-pyvcp` 已整理 SWITCHKINS 控件与 HAL nets；不执行 native HAL |
| Python GUI runtime | not_ported | 只参考，不运行 |
| Python remap runtime | blocked | 不在第一版实现 |
| tool DB runtime | blocked | 不在第一版实现 |
| external user-M process | blocked | 不在第一版实现 |
| tool DB runtime | web_simulation_only | 读取 staged `tool.tbl`，支持查询/编辑/保存刀具号、刀长、刀径、刀袋，并接入 `Tn/M6/G43/M61` 仿真状态；host tool DB process 仍为 false |
| external user-M process | controlled_web_simulation_only | 只允许白名单 `M128/M129/M428/M429/M430` 输出 HAL/state 事件；任意 host user-M 脚本和系统进程执行仍为 false |
| native hard realtime | out_of_scope | Web 仿真不实现 |
## 5. 每批开发追溯记录模板
@@ -1456,5 +1456,216 @@ Remaining risk:
realtime kernel, hardware IO, external user-M process, or native tool DB
process support.
Next:
none_from_development_continuation
M23 adds controlled tool DB and user-M Web simulation while keeping host
external process readiness false.
```
## 26. M23 受控 tool DB / user-M Web 仿真追溯记录
```text
Batch: M23-controlled-tool-db-user-m-web-simulation
Date: 2026-07-01 CST
Files changed:
app/src/runtime/tool-db-simulation.js
app/src/runtime/controlled-user-m-simulation.js
app/src/runtime/full-execution-boundary.js
app/src/runtime/native-task-hal-audit.js
app/src/state/store.js
app/src/main.js
app/src/ui/gmoccapy-shell.js
app/package.json
tests/node/verify_tool_db_web_simulation.mjs
tests/node/verify_tool_db_user_m_simulation.mjs
tests/node/verify_full_execution_boundary.mjs
tests/node/verify_machine_file_staging.mjs
tests/node/verify_native_task_hal_audit.mjs
tests/browser/gmoccapy_shell_smoke.html
Feature:
Implements the previously excluded red-box external user-M/tool DB capability
as a controlled Web/WASM simulation boundary. The runtime reads staged
LinuxCNC tool tables, models CANON_TOOL_TABLE fields, preserves LinuxCNC
non-random changer idx versus pocketno semantics, keeps idx=0 as the spindle
pocket, simulates tool prepare/load/read_tool_inputs/offset state, saves edits
through OPFS or memory fallback, and converts whitelisted user-M/remap actions
into traceable HAL/state events without executing arbitrary host scripts.
LinuxCNC references:
linuxcnc/src/emc/task/taskclass.cc:281
linuxcnc/src/emc/task/taskclass.cc:425
linuxcnc/src/emc/task/taskclass.cc:482
linuxcnc/src/emc/task/taskclass.cc:527
linuxcnc/src/emc/task/taskclass.cc:572
linuxcnc/src/emc/task/taskclass.cc:614
linuxcnc/src/emc/task/taskclass.hh
linuxcnc/src/emc/tooldata/tooldata_common.cc:70
linuxcnc/src/emc/tooldata/tooldata_common.cc:365
linuxcnc/src/emc/nml_intf/emctool.h:29
linuxcnc/src/emc/nml_intf/emc.hh
linuxcnc/src/emc/rs274ngc/interp_convert.cc:6236
linuxcnc/src/emc/rs274ngc/interp_find.cc:716
linuxcnc/src/emc/task/emctask.cc
linuxcnc/src/emc/task/emccanon.cc
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.tbl
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.tbl
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/428remap.ngc
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/429remap.ngc
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/430remap.ngc
Boundary:
toolDbProcessReady=true for web_simulation_only
externalUserMProcessReady=true for web_simulation_only
toolDbProcessScope=web_simulation_only
externalUserMProcessScope=web_simulation_only
hostToolDbProcessReady=false
hostExternalUserMProcessReady=false
arbitraryUserMExecution=false
hostProcessExecution=false
Tests:
node web-rtcp-5axis-sim-plan/tests/node/verify_tool_db_web_simulation.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_tool_db_user_m_simulation.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_full_execution_boundary.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_machine_file_staging.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_native_task_hal_audit.mjs
Result:
tool_db_web_simulation_smoke=ok
staged_tool_tbl_loaded=1
tool_db_query_edit_save=1
tool_db_t_m6_g43_state=1
tool_db_memory_fallback_save=1
host_tool_db_process=0
tool_db_user_m_simulation_smoke=ok
tool_db_process_ready_web_simulation_only=1
external_user_m_process_ready_web_simulation_only=1
arbitrary_user_m_blocked=1
host_process_execution=0
Remaining risk:
This does not implement LinuxCNC DB_PROGRAM, random changer semantics, native
host tool DB services, arbitrary user-M script execution, or hardware IO.
Next:
Keep whitelist entries and tool-table fields traceable to staged LinuxCNC
source assets when new machine profiles are added.
```
## 27. M24 XYZBC TRT kinematics parity proof 追溯记录
```text
Batch: M24-xyzbc-trt-kinematics-parity
Date: 2026-07-01 CST
Files changed:
app/src/runtime/rtcp-frame.js
app/src/visualization/five-axis-scene.js
tests/node/verify_linuxcnc_kinematics_runtime.mjs
tests/node/verify_rtcp_store.mjs
docs/development-continuation.md
docs/linuxcnc-parity-matrix.md
docs/program-implementation-guide.md
Feature:
Completes the next five-axis parity step for the XYZBC table rotary tilting
profile. The Web RTCP frame now preserves B in tcpPose for both fixture and
LinuxCNC kinematics frames, the Three.js diagnostic dataset exposes the same
B-axis TCP pose, and the runtime smoke proves both XYZAC and XYZBC TRT WASM
modules in switchkins TCP mode.
LinuxCNC references:
linuxcnc/src/emc/kinematics/xyzac-trt-kins.c
linuxcnc/src/emc/kinematics/xyzbc-trt-kins.c
linuxcnc/src/emc/kinematics/trtfuncs.c
linuxcnc/src/emc/kinematics/switchkins.c
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
Boundary:
semanticBoundary=linuxcnc_kinematics_wasm_c_abi
scope=node_direct_web_runtime_proof
hardwareDrive=false
hostRealtimeKernel=false
Tests:
node --check app/src/runtime/rtcp-frame.js
node --check app/src/visualization/five-axis-scene.js
node tests/node/verify_linuxcnc_kinematics_runtime.mjs
node tests/node/verify_rtcp_store.mjs
Result:
xyzac_trt_kinematics_runtime=ok
xyzbc_trt_kinematics_runtime=ok
linuxcnc_kinematics_runtime_smoke=ok
xyzbc_b_axis_tcp_pose_preserved=1
rtcp_store_smoke=ok
Remaining risk:
This is still browser/Web runtime parity. It does not promote hardware IO,
host realtime kernel execution, or native LinuxCNC task/HAL processes.
Next:
Keep XYZBC browser smoke evidence aligned with B-axis tcpPose when expanding
UI diagnostics or adding additional TRT machine profiles.
```
## 28. M25 gmoccapy XYZAC TRT RTCP 页面对标追溯记录
```text
Batch: M25-gmoccapy-xyzac-trt-rtcp-parity
Date: 2026-07-01 CST
Files changed:
app/src/profiles/gmoccapy-xyzac-trt.js
app/src/profiles/index.js
app/src/profiles/source-reference-map.js
app/src/profiles/xyzac-trt.js
app/src/runtime/linuxcnc-machine-file-staging.js
app/src/runtime/linuxcnc-ini-runtime.js
app/src/state/store.js
app/src/main.js
app/scripts/build-static.mjs
app/package.json
tests/node/verify_gmoccapy_xyzac_trt_parity.mjs
tests/browser/gmoccapy_shell_smoke.html
docs/gmoccapy-xyzac-trt-rtcp-verification-evaluation.md
docs/linuxcnc-parity-matrix.md
docs/program-implementation-guide.md
docs/development-continuation.md
wasm-port/tools/source-manifest.txt
wasm-port/vendor/linuxcnc/configs/sim/gmoccapy/...
Feature:
Adds a gmoccapy-specific XYZAC table-rotary-tilting profile that maps the
LinuxCNC gmoccapy non-trivial kinematics sample into the Web page. The profile
preserves DISPLAY=gmoccapy, OPEN_FILE examples/impeller-7bl-xyzac.ngc,
JOG_AXES=XYZC, M6/M61 gmoccapy remaps, POSTGUI tool/spindle HAL pins, gmoccapy
macros, tool table, and fixed TRT default TCP semantics.
LinuxCNC references:
linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/xyzac-trt.ini
linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/postgui.hal
linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/xyzac-trt.tbl
linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/xyzac-trt_cmds.hal
linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/*.ngc
linuxcnc/configs/sim/gmoccapy/macros/change_g43.ngc
linuxcnc/configs/sim/gmoccapy/macros/settool_g43.ngc
linuxcnc/src/emc/kinematics/xyzac-trt-kins.c
linuxcnc/src/emc/kinematics/trtfuncs.c
linuxcnc/src/emc/kinematics/switchkins.c
Boundary:
profileId=gmoccapy-xyzac-trt
semanticBoundary=linuxcnc_gmoccapy_nontrivial_xyzac_trt_profile_source_map
fixedTrtDefault=true
defaultKinsType=tcp-xyzac
rtcpState=on
sourceGuard=profile_specific_linuxcnc_gmoccapy_examples_only
hardwareDrive=false
hostRealtimeKernel=false
nativeGtkGmoccapy=false
Tests:
node tests/node/verify_gmoccapy_xyzac_trt_parity.mjs
node tests/node/verify_machine_file_staging.mjs
node tests/node/verify_linuxcnc_ini_runtime.mjs
node tests/node/verify_linuxcnc_parity_matrix.mjs
npm --prefix app run smoke:node
npm --prefix app run smoke
npm --prefix app run build
Result:
gmoccapy_xyzac_trt_parity_smoke=ok
machine_file_staging_smoke=ok
linuxcnc_ini_runtime_smoke=ok
linuxcnc_parity_matrix_smoke=ok
gmoccapy_shell_smoke=ok
gmoccapy_dist_smoke=ok
gmoccapy_static_build=ok
Remaining risk:
This proves the Web page and Web/WASM simulation boundary. It does not port
native GTK gmoccapy, host HAL shared memory, hardware IO, host realtime kernel,
arbitrary host user-M scripts, or native host tool DB processes.
Next:
If native gmoccapy or host realtime capability is required, add a separate
host/native validation layer rather than promoting this Web simulation proof.
```