# 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 语义和五轴运动学依据。 当前准备文档已完成： ```text 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. 下一轮直接开工任务 下一轮不再继续扩展方案，直接进入实现。 第一批任务： ```text M1-web-shell-gmoccapy ``` 状态： ```text 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 创建： ```text 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 创建： ```text app/src/ui/gmoccapy-shell.ts ``` 渲染区域： ```text 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 创建： ```text tests/browser/gmoccapy_shell_smoke.html tests/browser/verify_gmoccapy_shell_browser.sh ``` 检查： - 页面加载； - 关键 `data-region` 存在； - DRO 文本非空； - G-code rows 存在； - preview 容器非空； - 无 React/Vue 依赖标记。 当前 gate： ```text gmoccapy_static_build=ok gmoccapy_shell_smoke=ok ``` ## 4. M2 任务 ```text M2-state-and-controls ``` 状态： ```text 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 覆盖上述控制链路。 边界说明： ```text 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 任务 ```text M3-threejs-preview ``` 状态： ```text 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： ```text gmoccapy_static_build=ok rtcp_store_smoke=ok gmoccapy_shell_smoke=ok ``` ## 6. M4 任务 ```text M4-profile-and-linuxcnc-boundary ``` 状态： ```text 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 状态。 边界说明： ```text 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 ``` 说明： ```text M4 现在可视为在 profile/source-map/panel-schema/adapter 层面完全满足； 但这不等于 LinuxCNC interpreter/kinematics runtime 已接入。 ``` ## 7. M5 任务 ```text M5-operator-program-workflow ``` 状态： ```text 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、复位和急停。 边界说明： ```text 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. 当前状态 ```text 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 任务 ```text M12-switchkins-rtcp-program-execution ``` 状态： ```text 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。 边界说明： ```text 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 任务 ```text M16-linuxcnc-tp-queue-timing-runtime ``` 状态： ```text 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。 边界说明： ```text 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 ``` 验证： ```text 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 任务 ```text M13-interpreter-worker-runtime ``` 状态： ```text 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 两条路径。 边界说明： ```text browserInterpreterExecutionContext=worker nodeInterpreterExecutionContext=direct interpreterBoundary=linuxcnc_interpreter_wasm_canonical_events remapRuntimeReady=false plannerRuntimeReady=false fullLinuxCncProgramExecutionReady=false ``` ## 14. M16 任务 ```text M16-planner-task-hal-boundary-audit ``` 状态： ```text 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。 边界说明： ```text 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 任务 ```text M17-linuxcnc-5axis-gcode-source-ingest ``` 状态： ```text 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` 指向该源文件。 边界说明： ```text 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 任务 ```text M14-opfs-machine-file-staging ``` 状态： ```text 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。 边界说明： ```text 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 任务 ```text M15-machine-file-backed-fiveaxis-remap-run ``` 状态： ```text 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 状态。 边界说明： ```text 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 ```