cnc_wams/web-rtcp-5axis-sim-plan/docs/development-continuation.md

5 轴数控系统 Web 仿真编写过程接续文档

生成时间：2026-06-20 CST

1. 当前结论

已确定：

• Web 前端界面可实现；
• 首选界面风格为 gmoccapy_5_axis.png；
• 前端不使用 React/Vue 等框架，采用原生 HTML/CSS + TypeScript/JavaScript ES modules；
• 3D 使用 Three.js；
• LinuxCNC Python GUI 只做界面参考；
• LinuxCNC C/C++/WASM/source-derived boundary 才能作为 CNC 语义和五轴运动学依据。

当前准备文档已完成：

README.md
docs/implementation-plan.md
docs/technical-roadmap.md
docs/program-implementation-guide.md
docs/development-continuation.md
docs/traceability-matrix.md
docs/linuxcnc-python-gui-reference.md
docs/linuxcnc-gui-reference-gallery.md

2. 下一轮直接开工任务

下一轮不再继续扩展方案，直接进入实现。

第一批任务：

M1-web-shell-gmoccapy

状态：

completed_with_build_gate

目标：

• 创建 app/；
• 创建原生 HTML/CSS/TS 项目；
• 实现 gmoccapy 风格静态 shell；
• 复制必要的参考图路径到 docs；
• 加 browser smoke 验证页面区域存在。

已补齐 M1 工程化验收：

• app/tsconfig.json 已创建；
• npm run build 已可输出静态产物；
• build 产物目录 app/dist/ 已加入 .gitignore；
• browser smoke 已检查无 React/Vue/Angular/Svelte 依赖和 DOM 标记。

3. M1 任务拆分

M1.1 初始化 app

创建：

app/index.html
app/package.json
app/tsconfig.json
app/src/main.ts
app/src/styles/gmoccapy.css

要求：

• 不安装 React/Vue；
• 可使用 Vite；
• npm run dev 能启动；
• npm run build 能输出静态产物。

M1.2 静态 shell

创建：

app/src/ui/gmoccapy-shell.ts

渲染区域：

titlebar
preview
dro
gcode
status-sidebar
info-tabs
override
spindle-coolant
bottom-controls

M1.3 CSS layout

目标：

• 视觉接近 gmoccapy_5_axis.png；
• 黑底 preview；
• 绿色 DRO；
• 灰色面板；
• 橙色 override；
• 右侧竖向大按钮；
• 底部大按钮栏。

M1.4 smoke

创建：

tests/browser/gmoccapy_shell_smoke.html
tests/browser/verify_gmoccapy_shell_browser.sh

检查：

• 页面加载；
• 关键 data-region 存在；
• DRO 文本非空；
• G-code rows 存在；
• preview 容器非空；
• 无 React/Vue 依赖标记。

当前 gate：

gmoccapy_static_build=ok
gmoccapy_shell_smoke=ok

4. M2 任务

M2-state-and-controls

状态：

completed_with_rtcp_frame_and_control_wiring

目标：

• 实现 store；
• 实现 Run/Stop/Pause/Step action；
• G-code active line；
• DRO state update；
• Node smoke。

本轮追加 RTCP 最小可验证链路：

• 新增 xyzac-trt profile source reference；
• 新增 web-rtcp-5axis-motion-frame；
• store 输出 axisPose、jointPose、tcpPose、toolAxisVector、rtcpFrame；
• 右侧 TCP/IDENTITY 按钮可切换 rtcpState=on/off；
• DRO 和 info tabs 显示 TCP pose、tool axis vector、RTCP frame readiness；
• browser smoke 验证 RTCP DOM 和状态同步；
• node smoke 验证 frame/store 行为。

本轮继续补齐 M2 控件接线：

• preview X/Y/Z/Fit/Clear 按钮接入 store；
• Rapid Override / Feed Rate 加减按钮接入 store；
• Spindle override 加减按钮接入 store；
• Flood / Mist 冷却按钮接入 store；
• Reload / Home / Full 底部按钮接入 store；
• operatorMessage 记录最近一次仿真操作；
• Node smoke 和 browser smoke 覆盖上述控制链路。

边界说明：

sourceMode=fixture-ui-only
semanticBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof
linuxCncKinematicsReady=false
promotionAllowed=false

也就是说，Web 仿真界面现在已经具备 RTCP 状态链路和显示链路，但尚未把 LinuxCNC/source-derived 五轴运动学 WASM 接入为最终语义源。

5. M3 任务

M3-threejs-preview

状态：

completed_with_canvas_smoke

目标：

• Three.js canvas；
• 基础五轴机床；
• tool marker；
• simple path；
• canvas nonblank browser smoke。

M3 需要消费 M2 的 rtcpFrame：

• Three.js tool marker 使用 tcpPose；
• 刀轴显示使用 toolAxisVector；
• RTCP on/off 需要在预览中产生可见姿态差异；
• canvas smoke 需要检查 frame 与预览数据同步。

已完成：

• 新增 app/src/vendor/three/three.module.js 和 three.core.js；
• 新增 app/src/visualization/five-axis-scene.js；
• gmoccapy preview 区域由真实 WebGL canvas 渲染；
• 预览显示基础五轴工作区、工作台、刀具/TCP marker、刀轴和刀路；
• Three.js canvas 消费 tcpPose、toolAxisVector、rtcpState、rtcpFrame；
• browser smoke 验证 canvas nonblank、scene objects、path points、RTCP on/off 同步和 STEP 后 TCP pose 更新。

当前 gate：

gmoccapy_static_build=ok
rtcp_store_smoke=ok
gmoccapy_shell_smoke=ok

6. M4 任务

M4-profile-and-linuxcnc-boundary

状态：

completed_with_profile_boundary_smoke

目标：

• xyzac-trt profile；
• source reference map；
• PyVCP/HAL panel schema；
• LinuxCNC adapter 接入点；
• traceability update。

已完成：

• 扩展 app/src/profiles/xyzac-trt.js，记录 INI、PyVCP XML、postgui HAL、generated HAL、tool table、remap、switchkins type、HAL pins、offsets、sample programs；
• 进一步按 LinuxCNC xyzac-trt.ini/xyzac-trt_cmds.hal/*.tbl/428-430remap.ngc 整理 machine name、DISPLAY/RS274NGC/TRAJ、axis/joint limits、HALCMD nets、HALUI MDI commands、tool table 条目；
• 新增 app/src/profiles/source-reference-map.js，建立 xyzac-trt source/config/reference map；
• 新增 app/src/panel-schema/xyzac-trt-pyvcp.js，把 xyzac-trt.xml 与 switchkins_postgui.hal 的 SWITCHKINS 控件整理为 Web panel schema；
• 新增 app/src/runtime/linuxcnc-boundary-adapter.js，作为后续 LinuxCNC interpreter/kinematics WASM 的接入点；
• store 输出 linuxCncBoundaryAdapter 和 linuxCncBoundaryReadiness；
• info tabs 显示 adapter、panel schema、source map 和 boundary readiness；
• 新增 tests/node/verify_profile_boundary.mjs，并接入 npm run smoke:node；
• browser smoke 验证 LinuxCNC boundary adapter/schema/readiness DOM 状态。

边界说明：

sourceMapBoundary=profile_source_map_only_not_runtime_proof
panelSchemaBoundary=pyvcp_hal_schema_reference_only
adapterBoundary=adapter_entrypoint_only_runtime_not_connected
linuxCncKinematicsReady=false
promotionAllowed=false

说明：

M4 现在可视为在 profile/source-map/panel-schema/adapter 层面完全满足；
但这不等于 LinuxCNC interpreter/kinematics runtime 已接入。

7. M5 任务

M5-operator-program-workflow

状态：

completed_with_operator_program_smoke

目标：

• 上电、急停、自动、手动、JOG、MDI、复位等操作；
• 加载 G-code 文件；
• 刀具预览；
• 执行程序并显示执行的当前行。

已完成：

• store 新增 machine.powerOn、machine.estopActive、machine.mode、JOG/MDI/reset 状态；
• 右侧按钮栏新增 POWER、E-STOP、RESET、AUTO、MANUAL、JOG、MDI；
• 底部控制栏新增本地 G-code 文件输入、JOG X/Y、MDI run；
• LOAD_PROGRAM 可从浏览器 FileReader 或 public dispatch 加载 operator G-code 文本；
• G-code 面板显示程序来源、当前执行行，并按当前行高亮；
• Three.js 预览区域新增刀具预览卡，显示 T 号、直径、长度和 holder；
• RUN/STEP 会在上电且非急停状态下推进当前行，未上电时明确 blocked；
• node/browser smoke 覆盖上电、加载程序、运行、高亮当前行、JOG、MDI、复位和急停。

边界说明：

operatorWorkflowBoundary=browser_ui_runtime_fixture
gcodeLoadBoundary=file_text_staging_only
programExecutionBoundary=fixture_line_playback_not_linuxcnc_interpreter
linuxCncKinematicsReady=false
promotionAllowed=false

8. 每批完成后必须更新

每批完成后更新：

• 本文件的“当前状态”；
• docs/traceability-matrix.md；
• 如果新增 UI 或 runtime 约束，更新 docs/program-implementation-guide.md；
• 如果新增参考来源，更新 docs/linuxcnc-python-gui-reference.md 或 docs/linuxcnc-gui-reference-gallery.md。

9. 当前状态

status=M17_linuxcnc_5axis_gcode_source_ingest_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=M17-linuxcnc-5axis-gcode-source-ingest
latest_gate=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,gmoccapy_static_build=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
linuxcnc_5axis_gcode_sources=implemented_and_guarded_to_linuxcnc_source_manifest_trt_demos_only
program_current_line=implemented_linuxcnc_canonical_motion_highlight_with_fixture_fallback
tool_preview=implemented_tool_card_and_threejs_marker
threejs_preview=implemented_basic_canvas_scene
profile_source_map=implemented_xyzac_trt_and_xyzbc_trt
profile_switching=implemented_xyzac_trt_and_xyzbc_trt_with_runtime_reload
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
linuxcnc_kinematics_wasm=browser_and_node_proof_ready_xyzac_trt
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
switchkins_rtcp_program_execution=implemented_m428_m429_program_events_drive_rtcp_and_kinematics_switch
full_program_execution=partial_interpreter_canonical_and_switchkins_event_ready_remap_planner_not_promoted
session_persistence=implemented_opfs_save_restore_for_5axis_session
machine_file_staging=implemented_linuxcnc_trt_ini_hal_tool_table_remap_demo_opfs_staging
machine_file_backed_run=implemented_linuxcnc_fiveaxis_remap_wasm_machine_file_execution
planner_task_hal_gap=audited_as_blocked_without_native_task_nml_realtime_hal_and_planner_queue_runtime
next_batch=trajectory_planner_wasm_boundary_or_native_task_hal_port

10. M12 任务

M12-switchkins-rtcp-program-execution

状态：

completed_with_program_level_rtcp_switching

已完成：

• linuxcnc-interpreter-runtime 识别 LinuxCNC TRT 配置中的 M428/M429/M430 switchkins remap M-code；
• 因当前 interpreter WASM 未启用 Python/NGC remap runtime，运行前会从送入 WASM 的程序文本中移除这些高位 M-code，避免 M-code greater than 199 阻断普通 canonical motion；
• 原始程序的 M428/M429/M430 被保留为 switchkinsEvents，并打上 linuxcnc_switchkins_remap_mcode_preserved_web_runtime_applied 边界；
• canonical motion event 继承最近的 switchkins 状态，RUN/STEP/RUN_FRAME 按程序自动切换 identity / tcp-xyzac / tcp-xyzbc；
• node/browser kinematics runtime 增加 switchKinematics()，程序内 M428/M429 会同步切换 LinuxCNC kinematics WASM 的 lckins_switch()；
• gmoccapy diagnostics 显示 program switchkins event count；
• smoke 覆盖含 M428/M429 的五轴联动 RTCP 程序：加载后进入 TCP，执行 A/C 联动段保持 RTCP on，运行到 M429 后回到 identity。

边界说明：

switchkinsProgramBoundary=linuxcnc_remap_mcode_preserved_and_web_runtime_applied
interpreterBoundary=linuxcnc_interpreter_wasm_canonical_events
kinematicsBoundary=linuxcnc_kinematics_wasm_c_abi
remapRuntimeReady=false
plannerRuntimeReady=false
fullLinuxCncProgramExecutionReady=false

14. M16 任务

M16-linuxcnc-tp-queue-timing-runtime

状态：

completed_with_tp_wasm_and_web_node_smoke

已完成：

• wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_tp_wasm.c 新增 lctp_run_canonical_motion_timing()；
• TP WASM C ABI 将 LinuxCNC interpreter canonical motion events 入队到 vendored LinuxCNC src/emc/tp runtime，并通过 tpRunCycle() 生成 segment timing；
• canonical 零长度 motion 保留为 0 秒 timing segment，不作为 TP enqueue failure；
• 新增 wasm-port/runtime/sdk/src/linuxcnc-tp.js；
• linuxcnc-interpreter-runtime 在 runProgram() / runMachineFileProgram() 后调用 TP SDK，programExecution.plannerTiming 使用 linuxcnc_tp_queue_runtime_timing_from_canonical_motion 边界；
• store 优先使用 TP planner timing；JS execution-timing.js 保留为 fallback/MDI lightweight path；
• full execution boundary 可在 TP timing 成功时报告 plannerRuntimeReady=true。
• browser source/dist smoke 验证 interpreter Worker readiness 包含 TP planner runtime， 并验证含 ARC_FEED 的真实 G-code 程序通过 TP arc timing segment。

边界说明：

timingBoundary=linuxcnc_tp_queue_runtime_timing_from_canonical_motion
plannerRuntimeReady=true for interpreter canonical motion with TP WASM timing
nativeTaskReady=false
nativeHalSyncReady=false
fullLinuxCncProgramExecutionReady=false
hardwareDrive=false

验证：

source /home/cnc/emsdk/emsdk_env.sh >/dev/null && bash wasm-port/tools/build_tp_wasm.sh && bash wasm-port/tests/wasm/node/verify_tp_wasm.sh
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_interpreter_runtime.mjs
npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
npm --prefix web-rtcp-5axis-sim-plan/app run smoke

11. M13 任务

M13-interpreter-worker-runtime

状态：

completed_with_browser_worker_smoke

已完成：

• 新增 linuxcnc-interpreter-worker.js 和 linuxcnc-interpreter-worker-client.js；
• 浏览器默认优先通过 Web Worker 加载 LinuxCNC interpreter WASM；
• store 的 RUN_INTERPRETER_PROGRAM 支持 async runtime，避免 worker 结果阻塞 UI 线程；
• 增加 interpreterExecutionPending 和 sequence guard，防止旧解释器结果覆盖新加载程序；
• gmoccapy diagnostics 显示 interpreter execution context；
• browser smoke 验证 kinematics 和 interpreter 都在 Worker，并验证 source/dist 两条路径。

边界说明：

browserInterpreterExecutionContext=worker
nodeInterpreterExecutionContext=direct
interpreterBoundary=linuxcnc_interpreter_wasm_canonical_events
remapRuntimeReady=false
plannerRuntimeReady=false
fullLinuxCncProgramExecutionReady=false

14. M16 任务

M16-planner-task-hal-boundary-audit

状态：

completed_with_full_execution_boundary_smoke

已完成：

• 新增 full-execution-boundary.js，统一汇总 kinematics、interpreter canonical、machine-file staging、five-axis remap run、switchkins HAL evidence；
• store 新增 fullExecutionBoundary 派生状态和 RUN_FULL_BOUNDARY_AUDIT_REQUEST；
• gmoccapy diagnostics 显示 full boundary、planner/task/HAL blockers 和证据摘要；
• 底部新增 Audit 按钮，可触发 machine-file staging + machine-file backed five-axis remap run；
• interpreter runtime 对 machine-file backed run 的 remapRuntimeReady 改为基于 fiveaxis_ini_open=1、fiveaxis_remaps_ready=1、fiveaxis_file_reached_exit=1；
• Node/browser smoke 验证 partial remap boundary ready，同时继续禁止 full LinuxCNC program execution promoted。

边界说明：

fullExecutionBoundary=linuxcnc_machine_file_remap_ready_planner_task_hal_blocked
remapRuntimeReady=true for staged fiveAxisRemap C ABI run
halSwitchkinsEvidenceReady=true for fiveaxis_hal_switchkins evidence
nativeTaskReady=false
nativeHalSyncReady=false
plannerRuntimeReady=false
fullLinuxCncProgramExecutionReady=false
promotionAllowed=false

15. M17 任务

M17-linuxcnc-5axis-gcode-source-ingest

状态：

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；
• 新增 listLinuxCncGcodeSources() 和 selectMachineFileProgram()；
• store 新增 LOAD_LINUXCNC_GCODE_SOURCE，可把 staged LinuxCNC 真实 5 轴 .ngc 源文件加载到 G-code 面板；
• gmoccapy G-code 面板新增 LinuxCNC 5-axis source 下拉框和 staging 按钮；
• machine-file backed remap run 使用当前选中的 LinuxCNC .ngc 源程序路径；
• Node/browser smoke 验证选择 impeller-7bl-xyzac.ngc 后，UI 加载真实源程序，machine-file run 的 wasmProgramPath 指向该源文件。

边界说明：

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
remapRuntimeReady=true for staged fiveAxisRemap C ABI run
plannerRuntimeReady=false
nativeTaskReady=false
nativeHalSyncReady=false
fullLinuxCncProgramExecutionReady=false

12. M14 任务

M14-opfs-machine-file-staging

状态：

completed_with_node_and_browser_opfs_smoke

已完成：

• 新增 linuxcnc-machine-file-staging.js；
• 复用 wasm-port/runtime/sdk/src/sim-config-staging.js 的 planSimConfigStaging()，为 xyzac-trt / xyzbc-trt 生成 LinuxCNC sim-config staging plan；
• 将 INI、tool table、HAL、PyVCP XML、remap_subs/*.ngc、demo G-code 等 vendored LinuxCNC 文本文件保存到 OPFS 风格路径；
• store 增加 machineFileStaging 状态和 stageMachineFiles() API；
• gmoccapy diagnostics 显示 machine-file staging 状态；
• build 产物复制 wasm-port/tools/source-manifest.txt，保证 dist 页面也能生成 staging plan；
• node smoke 使用 memory OPFS 验证文件保存；browser smoke 使用真实 OPFS 验证 source/dist staging。

边界说明：

machineFileStagingBoundary=linuxcnc_sim_config_file_staging_plan_plus_opfs_text_persistence
stagedFiles=ini,hal,pyvcp,tool_table,remap_ngc,demo_gcode
nativeHalTaskSync=false
remapRuntimeReady=false
plannerRuntimeReady=false
fullLinuxCncProgramExecutionReady=false

13. M15 任务

M15-machine-file-backed-fiveaxis-remap-run

状态：

completed_with_node_and_browser_fiveaxis_remap_run

已完成：

• linuxcnc-interpreter-runtime 新增 runMachineFileProgram()；
• interpreter Worker 支持 runMachineFileProgram 转发；
• store 新增 RUN_MACHINE_FILE_PROGRAM action 和 machineFileExecution 状态；
• 使用 M14 的 machine-file staging plan/files，把 TRT INI、tool table、remap NGC、demo G-code 写入 Emscripten FS；
• 调用 LinuxCNC interpreter SDK runSimConfigProgram({ executionMode: "fiveAxisRemap" })；
• Node/browser smoke 验证 fiveaxis_ini_open=1、fiveaxis_remaps_ready=1、fiveaxis_file_reached_exit=1；
• gmoccapy diagnostics 显示 machine-file backed run 状态。

边界说明：

machineFileBackedRunBoundary=linuxcnc_fiveaxis_remap_wasm_machine_file_execution
sourceMode=linuxcnc-machine-file-remap-wasm
remapRuntimeReady=vendored_linuxcnc_fiveaxis_remap_c_abi_for_staged_files
nativeTaskHalSync=false
plannerRuntimeReady=false
fullLinuxCncProgramExecutionReady=false