239 lines
13 KiB
Markdown
239 lines
13 KiB
Markdown
# 3axis Tutorial 全功能对标总方案
|
||
|
||
## 0. 目标和执行边界
|
||
|
||
唯一目标案例：
|
||
|
||
`/home/mes006/linuxcncWebWASM/linuxcnc/configs/sim/axis/vismach/3axis-tutorial`
|
||
|
||
入口文件：
|
||
|
||
`linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial.ini`
|
||
|
||
目标不是“再做一个示例”，而是把该案例在 LinuxCNC 中可观察的配置、启动、运动、解释器、HAL、工具、主轴、冷却、探针、Vismach、AXIS UI、持久化和恢复行为逐项映射到 WASM + Dedicated Worker + React + Three.js。后续任务不得切换到其它 `configs/sim` 案例；其它案例只能作为通用模块回归输入，不能作为本案例完成证据。
|
||
|
||
明确排除：实时内核调度、真实硬件、PCI/串口设备、宿主动态 loader、宿主 Python GUI 进程。排除项必须有 `REAL-EXCLUDED`/`HOST_EXCLUDED` 诊断，不得静默删除功能。
|
||
|
||
## 1. 锁定输入和执行规约
|
||
|
||
### 1.1 Exact 输入
|
||
|
||
| 输入 | 作用 | 规则 |
|
||
|---|---|---|
|
||
| `3axis-tutorial.ini` | AXIS、Task、RS-274、TRAJ、EMCIO、KINS、AXIS/JOINT limits | 原路径、原始字节和 source line 保留 |
|
||
| `3axis-tutorial.hal` | trivkins/motmod/ddt/hypot、反馈环、手动换刀、Vismach pins | 按原顺序解析 `loadrt/addf/net/loadusr` |
|
||
| `3axis-tutorial` | Vismach Python model 和 5 个 HAL pins | Web 使用源码驱动 `WEB-EQUIV` adapter，不运行宿主 Python |
|
||
| `tool.tbl` | T1/T2/T3/T99999 工具、长度和直径 | exact path；工具状态必须可恢复 |
|
||
| `linuxcnc/linuxcnc.gif` | `DISPLAY.INTRO_GRAPHIC` | 仅作为 shared display asset |
|
||
| runtime `.var/.bak/position_mm.txt` | 参数、备份、位置持久化 | 运行时生成，写入 workspace journal，不作为 source fixture |
|
||
|
||
### 1.2 Native 标准命令
|
||
|
||
每次运行前必须停止本 runner 或历史运行留下的 `linuxcncsvr`、`rtapi_app`、`milltask`、`halui`、`iocontrol`、`axis`，确认没有活动进程持有 `/tmp/linuxcnc.lock`；只允许在 lock 无活动持有者时删除 stale lock。
|
||
|
||
然后固定使用：
|
||
|
||
```bash
|
||
cd /home/mes006/linuxcncWebWASM/linuxcnc
|
||
linuxcnc <isolated-case-dir>/3axis-tutorial.ini
|
||
```
|
||
|
||
成功条件同时包括：
|
||
|
||
- `update_ini -f` 在隔离目录成功；
|
||
- AXIS WM class 为 `axis / Axis`；
|
||
- 标题含 `3axis-tutorial`；
|
||
- 窗口至少 `600x400`；
|
||
- native log 没有未分类首错；
|
||
- 记录生成的 `.var/.bak/position_mm.txt`；
|
||
- 退出后 LinuxCNC 服务和 lock 清理完成。
|
||
|
||
禁止用 timeout、`Starting LinuxCNC`、后台 `task:`、进程存在或 lock 文件存在替代窗口证据。
|
||
|
||
## 2. 全功能对标清单
|
||
|
||
### 2.1 配置、资源和流程
|
||
|
||
1. `VERSION/MACHINE/DEBUG` 解析和 `update_ini` 迁移。
|
||
2. `[DISPLAY]`：AXIS、cycle time、relative/actual 初始显示、feed/spindle override、increments、program prefix、intro graphic、file filters。
|
||
3. `[RS274NGC]`：参数文件路径、缺失文件空初始化、保存和 `.bak` 策略。
|
||
4. `[EMCMOT]/[TASK]/[EMCIO]`：motmod、milltask、io、cycle/servo period、tool table、tool-change position。
|
||
5. `[TRAJ]`：3 axes、XYZ、mm/degree、速度、加速度、position file、arc blend 参数。
|
||
6. `[KINS]/[AXIS_X/Y/Z]/[JOINT_0/1/2]`：trivkins identity、limits、velocity、acceleration、scale、FERROR、MIN_FERROR、home offset。
|
||
7. HAL 文件和 `LIB:`/相对路径解析保持 exact path、行号、顺序、缺失诊断。
|
||
8. 启动状态映射：`NEW -> MOUNTED -> PARSED -> RESOLVED -> CORE_CREATED -> HAL_READY -> TASK_READY`。
|
||
9. 退出状态映射：停止、HAL unload、服务退出、参数/位置提交和 journal close。
|
||
|
||
### 2.2 运动、Task 和解释器
|
||
|
||
1. MANUAL/MDI/AUTO 模式和 READY/RUNNING/PAUSED/STOPPED/ESTOP/FAULT 状态。
|
||
2. X/Y/Z 全部 home、独立 jog、连续/增量 jog、stop、速度/加速度、override。
|
||
3. trivkins pose/joint identity、commanded/actual/relative DRO。
|
||
4. X `[-500,500]`、Y `[-100,100]`、Z `[-240,0.001]` limits。
|
||
5. following error、limit fault、fault latch、recover 和禁用条件。
|
||
6. `G20/G21`、`G90/G91`、`G0/G1`、F feed、G17/G40/G49/G54/G64、G10/G92、M2/M30、参数表达式和错误列。
|
||
7. PROGRAM_LOAD/RUN/PAUSE/RESUME/STEP/SEEK/ABORT/RESTART、MDI 队列和活动程序期间 MDI 拒绝。
|
||
8. fixed tick 1x/fast/step 与 pause/recovery endpoint parity。
|
||
|
||
### 2.3 HAL、工具、主轴、冷却、探针和故障
|
||
|
||
1. `trivkins`、`motmod`、6 个 ddt、2 个 hypot 的 component/thread/function 记录。
|
||
2. 三轴 motor-pos-cmd 到 motor-pos-fb 的 loopback。
|
||
3. velocity/acceleration 派生信号 `Xvel/Yvel/Zvel/XYvel/XYZvel`。
|
||
4. estop loopback、`hal_manualtoolchange` prepare/change/changed 生命周期。
|
||
5. Vismach pins：`jointX/jointY/jointZ/toollength/tooldiameter`，pin direction/type 和 net 连接。
|
||
6. T1/T2/T3/T99999 prepare、pocket、change、abort、fault、clear。
|
||
7. spindle direction/RPM、ramp、at-speed、encoder/index、inhibit、orient、fault。
|
||
8. mist/flood/lube request、interlock、coolant fault 和恢复。
|
||
9. probe arm/input/trip/latched position/disarm；没有 source pin 时保留 capability boundary。
|
||
10. ESTOP、door/interlock、following-error、limit、tool/spindle/coolant fault 的错误码、message key、状态 hash 和 UI gate。
|
||
|
||
### 2.4 Vismach 和 AXIS UI
|
||
|
||
1. frame/base/column/top、X table/work、Y assembly、Z frame/spindle、CAT30/tool/tooltip 的几何层次。
|
||
2. `HalTranslate` 对 jointX/Y/Z 的轴向变换和工具长度/直径变化。
|
||
3. tool cylinder 半径、z offset、当前工具和 tooltip 连续性。
|
||
4. AXIS File/Machine/View/Help 菜单、快捷键、toolbar icon、F3 Manual、F5 MDI、Preview、DRO、G-code editor、active G-codes。
|
||
5. DRO machine/relative、actual/commanded、mm/inch、tick/hash。
|
||
6. Three.js canvas 非空像素、pose/joint/toolpath/limits/layers、desktop/mobile 不重叠。
|
||
7. 控件 enable/disable 必须来自 Worker snapshot；所有不可用操作必须显示诊断。
|
||
|
||
### 2.5 持久化、恢复和证据治理
|
||
|
||
1. `.var` 缺失/空文件/参数写入/`.bak` 生成/重启恢复。
|
||
2. `position_mm.txt` 保存、读取、恢复和错误处理。
|
||
3. `tool.tbl` 读取、工具状态更新、workspace commit 和重启恢复。
|
||
4. checkpoint、event cursor、journal、trace import、replay endpoint equality。
|
||
5. recovery 不重复已提交副作用；坏 checkpoint、seq gap、tick regression、未知 event 必须 fail-closed。
|
||
6. 每个报告保存 context id、输入 hash、输出 hash、命令、首个 divergent phase/tick、失败样本和 self-hash。
|
||
|
||
## 3. 实施任务和依赖
|
||
|
||
| ID | 实施结果 | 主要输出 | 依赖 |
|
||
|---|---|---|---|
|
||
| `TUTORIAL-00` | 锁定源目录、隔离副本、服务清理和 native AXIS runner | native report + AXIS screenshot | 无 |
|
||
| `TUTORIAL-01` | exact INI/HAL/resource graph 和 runtime file policy | resource graph report | 00 |
|
||
| `TUTORIAL-02` | HAL manifest、loadrt/addf/net、Vismach `WEB-EQUIV` adapter | HAL adapter report | 01 |
|
||
| `TUTORIAL-03` | startup phase、TASK_READY、loader/startup hash | startup report | 01/02 |
|
||
| `TUTORIAL-04` | home/jog/limit/FERROR/trivkins fixed tick | motion report | 03 |
|
||
| `TUTORIAL-05` | RS-274/G-code/MDI/program controls | program report | 04 |
|
||
| `TUTORIAL-06` | tool/spindle/coolant/probe/ESTOP/IO full matrix | tool-io report | 03/05 |
|
||
| `TUTORIAL-07` | Vismach geometry graph、pin-to-pose、tool continuity | model report + canvas samples | 02/04/06 |
|
||
| `TUTORIAL-08` | AXIS menus、DRO、tabs、editor、gates、mobile layout | DOM/visual report | 03/05/07 |
|
||
| `TUTORIAL-09` | var/tool/position commit、checkpoint/journal/replay | persistence report | 05/06/08 |
|
||
| `TUTORIAL-10` | same operation sequence native/Worker/UI integrated acceptance | complete scoped report | 00..09 |
|
||
| `TUTORIAL-11` | probe and complete tool-offset behavior closure | probe/tool report + native/Worker diff | 06/09/10 |
|
||
| `TUTORIAL-12` | native/Web same-sequence recorder and first-divergence report | sequence ledger + endpoint comparison | 10/11 |
|
||
| `TUTORIAL-13` | persistence restart with explicit service/lock cleanup and visual recovery evidence | restart report + screenshots | 09/12 |
|
||
| `TUTORIAL-14` | final selected-case acceptance freeze and evidence index | signed/self-hashed closure index | 11/12/13 |
|
||
|
||
当前 `TUTORIAL-00..10` 的已验证报告必须继续复用；下一阶段从 `TUTORIAL-11` 开始，不得重复创建其它案例任务。
|
||
|
||
当前执行状态：`TUTORIAL-11` verified；`TUTORIAL-12` verified with source-defined individual `Z/X/Y` homing and real `change_button` ACK；`TUTORIAL-13` verified after replay-order fix；`TUTORIAL-14` verified as selected-case closure index. Firefox/Safari、OPFS physical crash、realtime hardware 和 full release 仍是独立外部边界。
|
||
|
||
## 4. 统一实施顺序
|
||
|
||
每个任务执行以下固定步骤：
|
||
|
||
1. 读取 `nextTask1.md`、context lock 和本任务直接输入。
|
||
2. 服务清理；native exact command；保留截图、日志和 source hash。
|
||
3. 先新增失败边界测试，再实现最小 vertical slice。
|
||
4. Worker 使用真实 WASM 和固定 logical tick；不使用 mock Worker 作为完成证据。
|
||
5. React 只消费 Worker authoritative state；UI gate、错误和状态不能本地猜测。
|
||
6. 运行任务专项测试、native CTest、WASM build、selected-case Worker/App 回归。
|
||
7. 生成 self-hashed report，记录正常、边界、错误、非有限、容量、暂停/恢复/终止和确定性 hash。
|
||
8. 只有当前任务达到验收条件才更新指针；若输入、oracle 或环境缺失，保留 `blocked` 和 failure sample。
|
||
|
||
## 5. 验证计划
|
||
|
||
### 5.1 基线和构建
|
||
|
||
```bash
|
||
python3 scripts/validate_baseline.py
|
||
python3 scripts/validate_task_pointer.py nextTask1.md
|
||
scripts/build-wasm.sh
|
||
ctest --test-dir build-native --output-on-failure
|
||
cd web/react && npm run typecheck && npm run build
|
||
```
|
||
|
||
### 5.2 Native 验证
|
||
|
||
```bash
|
||
python3 scripts/run_axis3_tutorial_native.py \
|
||
--output coverage/axis3-tutorial-native-run.report.json \
|
||
--screenshot coverage/axis3-tutorial-visual/native-axis.png
|
||
python3 scripts/test_axis3_tutorial_native.py
|
||
```
|
||
|
||
必须检查：窗口 class/title/geometry、服务清理、lock、exact source hashes、生成文件、首错和截图 hash。
|
||
|
||
### 5.3 Worker/WASM 验证
|
||
|
||
```bash
|
||
node web/worker/test_axis3_selected_case.mjs
|
||
node web/worker/test_axis3_tutorial_hal_adapter.mjs
|
||
node web/worker/test_axis3_tutorial_startup.mjs
|
||
node web/worker/test_axis3_tutorial_motion.mjs
|
||
node web/worker/test_axis3_tutorial_program.mjs
|
||
node web/worker/test_axis3_tutorial_tool_io.mjs # TUTORIAL-06/11
|
||
node web/worker/test_axis3_tutorial_persistence.mjs # TUTORIAL-09/13
|
||
node web/worker/test_axis3_tutorial_sequence.mjs # TUTORIAL-12
|
||
```
|
||
|
||
每个 Worker endpoint 必须同时记录 `task/program/motion/joints/devices/hal/authoritative/state_hash`，不能只断言 `status=verified`。
|
||
|
||
### 5.4 React/Chromium 验证
|
||
|
||
```bash
|
||
npm --prefix web/react run preview -- --port 5174
|
||
python3 scripts/generate_gui_browser_visual_report.py
|
||
python3 scripts/test_gui_browser_visual_report.py
|
||
```
|
||
|
||
桌面 `1440x900` 和移动 `390x844` 都必须有：DOM marker、4 tabs/tabpanel 关系、至少 20 toolbar icons、ARIA labels、非空截图、Three.js canvas、case selector、DRO、G-code、Manual/MDI 和无重叠布局。
|
||
|
||
### 5.5 Integrated acceptance
|
||
|
||
```bash
|
||
python3 scripts/generate_axis3_tutorial_complete_report.py
|
||
python3 scripts/test_axis3_tutorial_complete_report.py
|
||
python3 scripts/validate_baseline.py
|
||
python3 scripts/validate_task_pointer.py nextTask1.md
|
||
```
|
||
|
||
统一逻辑序列：启动 -> 全轴 home -> X/Y/Z jog -> override -> MDI -> G-code load/run -> pause/resume/step -> abort/restart -> tool prepare/change -> spindle/at-speed -> coolant -> probe -> limit/FERROR/ESTOP -> checkpoint -> 继续一个 tick -> recover -> persistence restart。native、Worker 和 UI 必须使用同一操作 ID 顺序；时间只用 logical tick。
|
||
|
||
## 6. 通过、阻塞和停止条件
|
||
|
||
### 通过
|
||
|
||
- exact path 和 source hash 一致；
|
||
- native AXIS 窗口真实可见；
|
||
- Worker `TASK_READY` 且 HAL blocked count 为 0；
|
||
- native/Worker endpoint 和恢复 hash 可解释；
|
||
- UI 证据有持久化图片、DOM hash 和 canvas 非空；
|
||
- report self-hash 和 pointer validation 通过。
|
||
|
||
### 保持 blocked
|
||
|
||
- native 服务或 lock 未清理；
|
||
- 首个 divergent tick/phase 未定位；
|
||
- probe/tool offset 没有 source 或实现契约；
|
||
- checkpoint/event/hash 不可验证；
|
||
- 只能依赖墙钟、随机数、宿主 Python、mock Worker 或真实硬件；
|
||
- Firefox/Safari/OPFS/oracle 外部条件缺失。
|
||
|
||
### 不得宣称
|
||
|
||
该方案的 `verified` 只代表固定 `3axis-tutorial` 选定案例范围。它不代表 LinuxCNC 全功能、235-case acceptance、实时硬件、Firefox/Safari release 或 owner/license gate 已完成。
|
||
|
||
## 7. 当前证据索引
|
||
|
||
- 总报告：`coverage/axis3-tutorial-complete.report.json`
|
||
- Native：`coverage/axis3-tutorial-native-run.report.json`
|
||
- Resource graph：`coverage/axis3-tutorial-resource-graph.report.json`
|
||
- Program：`coverage/axis3-tutorial-program.report.json`
|
||
- Chromium visual：`coverage/gui-browser-visual-fe-m4.report.json`
|
||
- 图片目录：`coverage/axis3-tutorial-visual/`
|
||
- 接续入口：`nextTask1.md`
|