wangdequan
626bcfe8e3
结论：完成 LinuxCNC kinematics WASM ABI 覆盖，并将 web-rtcp-5axis-sim-plan 的 RTCP frame/boundary adapter 接到 xyzac-trt kinematics SDK；Node、build、browser smoke 验证通过。
454 lines
13 KiB
Plaintext
454 lines
13 KiB
Plaintext
项目接续文件：tool DB 解锁步骤与方法
|
||
|
||
生成时间：2026-06-18 CST
|
||
|
||
本文件接替 `text19.txt` 中关于 blocked runtime family 的后续推进说明，专门规划
|
||
`L4-TOOL-DB` / `axis/db_demo/base.ngc` 的解锁路径。当前目标不是绕过 tool DB，
|
||
而是在已有 source-derived evidence、transaction contract、native readiness gate 和
|
||
promotion lock 框架基础上，把 tool database process protocol 证明补齐，然后再允许
|
||
真实 inventory promotion。
|
||
|
||
重要状态说明：本文件是未来解锁研究计划，不是当前阶段实施范围。当前阶段铁律仍是
|
||
“virtual HAL 成果作为 sim config promotion 证据基础”，同时明确不解锁
|
||
`L4-PYTHON-REMAP`、`L4-TOOL-DB`、`L4-USER-M-PROCESS` 这些 hard block。
|
||
因此在当前交付中，`axis/db_demo/base.ngc` 必须继续保持 `SKIP L4-TOOL-DB`，
|
||
`promotion_allowed=0`，`promotion_lock_active=1`。
|
||
|
||
一、当前已完成条件
|
||
|
||
当前项目已经具备以下基础，不需要重做：
|
||
|
||
1. source/config ownership 已明确。
|
||
|
||
- `axis/db_demo/base.ngc` 当前 blocked kind 为 `L4-TOOL-DB`；
|
||
- owning INI 为 `axis/db_demo/db_nonran.ini`；
|
||
- INI 声明：
|
||
|
||
```text
|
||
[EMCIO]
|
||
DB_PROGRAM = ./db_nonran.py
|
||
```
|
||
|
||
- LinuxCNC source owner 已记录：
|
||
- `configs/sim/axis/db_demo/db_nonran.ini`
|
||
- `configs/sim/axis/db_demo/db.py`
|
||
- `src/emc/task/taskclass.cc`
|
||
- `src/emc/tooldata/tooldata_db.cc`
|
||
- `lib/python/tooldb.py`
|
||
|
||
2. machine-readable artifacts 已有。
|
||
|
||
当前已有并通过 inventory gate 的 tool DB 相关 artifact：
|
||
|
||
```text
|
||
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-boundary-summary.tsv
|
||
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-protocol-gates.tsv
|
||
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-transaction-plan.tsv
|
||
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-native-protocol-alignment.tsv
|
||
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-native-runtime-readiness.tsv
|
||
wasm-port/build/wasm/sim-configs-inventory/tool-db-process-native-runtime-probe-gate.tsv
|
||
```
|
||
|
||
3. transaction contract 已明确。
|
||
|
||
`tool-db-process-transaction-plan.tsv` 已把 DB protocol 拆成以下 pending proof：
|
||
|
||
- `startup_handshake`：启动后返回 `v2.1`；
|
||
- `initial_get_all`：发送 `g`，读取直到 `FINI`；
|
||
- `spindle_load_notify`：发送/验证 `l`；
|
||
- `tool_offset_notify`：发送/验证 `p`；
|
||
- `spindle_unload_notify`：发送/验证 `u`。
|
||
|
||
4. 当前 readiness 状态已明确。
|
||
|
||
当前 `tool-db-process-native-runtime-readiness.tsv` / probe gate 显示：
|
||
|
||
```text
|
||
python3=1
|
||
axis/db_demo/db_nonran.py=1
|
||
linuxcnc.so=1
|
||
tooldb.py=1
|
||
linuxcnc=0
|
||
milltask=0
|
||
halcmd=0
|
||
runtime_ready=0
|
||
source_proof_ready=1
|
||
gate_status=blocked_missing_host_runtime
|
||
proof_status=pending
|
||
execution_enabled=0
|
||
promotion_allowed=0
|
||
```
|
||
|
||
这说明当前缺的不是 source evidence，也不是 Python 文件本身，而是完整 LinuxCNC
|
||
task/tooldata DB host runtime。
|
||
|
||
二、解锁原则
|
||
|
||
tool DB 解锁必须遵守以下规则：
|
||
|
||
1. 不允许用 `.tbl` fallback 解锁。
|
||
|
||
`DB_PROGRAM` 模式明确替代普通 tool table path。用 `.tbl` 让程序跑通会绕过
|
||
LinuxCNC tool database process protocol，属于错误 promotion。
|
||
|
||
2. 不允许用 JS/virtual HAL 重新实现 tool DB 语义。
|
||
|
||
virtual HAL 可以继续作为 HAL/motion/browser diagnostics evidence，但不能替代：
|
||
|
||
- `DB_PROGRAM` 子进程启动；
|
||
- `tooldb.py` protocol loop；
|
||
- `v2.1` / `g` / `l` / `u` / `p` protocol；
|
||
- nonrandom DB state mutation；
|
||
- flat-file persistence。
|
||
|
||
3. native proof 必须先于 Node/browser promotion。
|
||
|
||
只有 native runtime probe 明确通过以后，才允许更新 Node/browser promotion gate。
|
||
|
||
4. promotion lock 必须手动更新。
|
||
|
||
即使 native probe 通过，也不能自动把 `axis/db_demo/base.ngc` 从 skipped 改为 executed。
|
||
必须明确更新 promotion readiness、blockers、post-native-pass gate 和 lock artifact。
|
||
|
||
三、第一阶段：准备 host runtime
|
||
|
||
目标：让 tool DB runtime readiness 从：
|
||
|
||
```text
|
||
runtime_ready=0
|
||
missing_requirements=linuxcnc,milltask,halcmd
|
||
```
|
||
|
||
变为：
|
||
|
||
```text
|
||
runtime_ready=1
|
||
missing_requirements=-
|
||
```
|
||
|
||
需要准备的命令/模块：
|
||
|
||
```text
|
||
python3
|
||
linuxcnc
|
||
milltask
|
||
halcmd
|
||
axis/db_demo/db_nonran.py
|
||
linuxcnc.so
|
||
tooldb.py
|
||
```
|
||
|
||
当前已有：
|
||
|
||
```text
|
||
python3
|
||
axis/db_demo/db_nonran.py
|
||
linuxcnc.so
|
||
tooldb.py
|
||
```
|
||
|
||
当前缺失：
|
||
|
||
```text
|
||
linuxcnc
|
||
milltask
|
||
halcmd
|
||
```
|
||
|
||
建议方法：
|
||
|
||
1. 在具备完整 LinuxCNC userspace runtime 的 host / container 中执行。
|
||
2. 确保 `linuxcnc`、`milltask`、`halcmd` 在 `PATH` 上。
|
||
3. 确保 LinuxCNC Python 模块路径能被 `db_nonran.py` import：
|
||
|
||
```text
|
||
python3 -c "import linuxcnc; import tooldb; print('linuxcnc_tooldb_python_modules=ok')"
|
||
```
|
||
|
||
4. 重新运行 native probes / inventory gate 以刷新 readiness artifacts：
|
||
|
||
```text
|
||
wasm-port/tests/native/probe_tool_db_runtime.sh
|
||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
|
||
```
|
||
|
||
预期中间状态：
|
||
|
||
- 如果 host runtime 仍缺失：
|
||
|
||
```text
|
||
tool_db_runtime_probe_status=skipped_missing_host_runtime
|
||
```
|
||
|
||
- 如果 host runtime 已满足但未显式启用 probe：
|
||
|
||
```text
|
||
tool_db_runtime_probe_status=ready_disabled_by_default
|
||
```
|
||
|
||
四、第二阶段：执行 native DB protocol probe
|
||
|
||
目标：证明 LinuxCNC-owned DB process protocol 真实可运行。
|
||
|
||
执行命令：
|
||
|
||
```text
|
||
ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh
|
||
```
|
||
|
||
该 probe 必须证明：
|
||
|
||
1. `db_nonran.py` 按 `DB_PROGRAM` 配置启动；
|
||
2. startup handshake 返回 `v2.1`；
|
||
3. `g` get-all 返回 expected nonrandom startup tools；
|
||
4. startup state 覆盖 `T10..T19` / `tno+100` pockets；
|
||
5. `l` load notify 触发 spindle load state；
|
||
6. `p` tool offset notify 触发 DB update path；
|
||
7. `u` unload notify 触发 spindle unload state；
|
||
8. flat-file persistence 能反映 state mutation；
|
||
9. probe 输出：
|
||
|
||
```text
|
||
tool_db_runtime_probe_status=runtime_protocol_probe_passed
|
||
```
|
||
|
||
失败处理：
|
||
|
||
- 如果失败在 import `linuxcnc` / `tooldb`：修 Python module path，不改项目语义；
|
||
- 如果失败在 `linuxcnc` / `milltask` / `halcmd`：修 host runtime，不改 Node/browser fallback；
|
||
- 如果失败在 protocol message：先对齐 native `db_nonran.py` / `tooldb.py` 行为和
|
||
`tool-db-process-transaction-plan.tsv`，不允许用简化协议绕过；
|
||
- 如果失败在 persistence：修 probe 环境的临时 DB 文件隔离和 cleanup，不把 persistence
|
||
检查删除。
|
||
|
||
五、第三阶段：刷新 native/runtime artifacts
|
||
|
||
native probe pass 后，重新生成并验证 artifacts：
|
||
|
||
```text
|
||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
|
||
```
|
||
|
||
预期变化方向：
|
||
|
||
```text
|
||
tool-db-process-native-runtime-readiness.tsv:
|
||
runtime_ready=1
|
||
missing_requirements=-
|
||
|
||
tool-db-process-native-runtime-probe-gate.tsv:
|
||
gate_status=native_probe_passed_waiting_for_node_browser_promotion_proof
|
||
proof_status=passed
|
||
source_proof_ready=1
|
||
```
|
||
|
||
注意：这个阶段仍不应直接让 `promotion_allowed=1`。native pass 只是打开下一步
|
||
Node/browser proof 的条件。
|
||
|
||
六、第四阶段：更新 promotion readiness / blocker / lock
|
||
|
||
native pass 后，需要更新以下 gate 的逻辑和 fixtures：
|
||
|
||
```text
|
||
runtime-boundary-promotion-readiness.tsv
|
||
runtime-boundary-promotion-blockers.tsv
|
||
runtime-boundary-post-native-pass-gates.tsv
|
||
runtime-boundary-native-evidence-acceptance-gate.tsv
|
||
blocked-runtime-promotion-lock.tsv
|
||
next-boundary-recommendations.tsv
|
||
promotion-candidates.tsv
|
||
```
|
||
|
||
目标状态：
|
||
|
||
1. `native_evidence_ready=1`；
|
||
2. `node_inventory_gate_complete=0`，直到 Node inventory row 真实执行；
|
||
3. `browser_smoke_gate_complete=0`，直到 browser proof 真实通过；
|
||
4. `promotion_lock_active=1`，直到人工明确解锁；
|
||
5. blocker 从 `missing_host_runtime` 转为：
|
||
|
||
```text
|
||
pending_node_inventory_promotion_gate
|
||
pending_browser_smoke_gate
|
||
promotion_lock_active
|
||
```
|
||
|
||
这一步的重点是：native proof 已经完成，但还没有完成 Node/browser promotion，因此
|
||
blocked family 不能直接消失。
|
||
|
||
七、第五阶段：设计 Node inventory execution path
|
||
|
||
只有 native DB protocol probe 通过后，才允许考虑让 `axis/db_demo/base.ngc` 进入
|
||
Node inventory execution。
|
||
|
||
可接受方向：
|
||
|
||
1. 通过 LinuxCNC-owned tooldata DB protocol wrapper 执行；
|
||
2. 保留 `DB_PROGRAM = ./db_nonran.py` 的行为边界；
|
||
3. Node/WASM 侧只做 file staging、protocol bridge、result capture；
|
||
4. 所有 tool DB state 来自 LinuxCNC protocol / db.py 行为，而不是 JS 自行解释。
|
||
|
||
不可接受方向：
|
||
|
||
1. 把 `axis/sim.tbl` 或任意 `.tbl` 当作 DB fallback；
|
||
2. 在 JS 中手写 `T10..T19` tool DB state；
|
||
3. 跳过 `v2.1` / `g` / `l` / `u` / `p` protocol；
|
||
4. 只因为 native `bin/rs274` 能 parse `base.ngc` 就标记 Node inventory PASS；
|
||
5. 把 virtual HAL readiness 当作 tool DB process readiness。
|
||
|
||
如果 Node/WASM 当前无法启动 Python DB process，则应保持：
|
||
|
||
```text
|
||
node_inventory_gate_complete=0
|
||
promotion_allowed=0
|
||
```
|
||
|
||
并把下一步限定为“设计 tool DB protocol bridge”，而不是直接改 baseline。
|
||
|
||
八、第六阶段：Browser proof
|
||
|
||
Browser proof 只能在 Node inventory gate 真实完成后做。
|
||
|
||
Browser proof 至少需要：
|
||
|
||
- diagnostics artifact 记录 tool DB protocol proof status；
|
||
- release URL workflow 显示 `axis/db_demo/base.ngc` 的 DB proof；
|
||
- 明确 `tool_table_fallback_sufficient=0`；
|
||
- 明确 `python3_sufficient=0`；
|
||
- 明确 source owner 是 LinuxCNC DB protocol；
|
||
- browser 只呈现 proof / workflow / artifact，不自行执行 tool DB semantics。
|
||
|
||
九、第七阶段：真实 inventory baseline promotion
|
||
|
||
只有满足以下条件后，才允许把 `axis/db_demo/base.ngc` 从 skipped 变为 executed：
|
||
|
||
1. native DB runtime probe passed；
|
||
2. Node inventory execution path 通过 LinuxCNC-owned DB protocol；
|
||
3. browser proof / release diagnostics gate 已通过；
|
||
4. promotion lock 手动关闭；
|
||
5. `promotion-candidates.tsv` 中对应行从：
|
||
|
||
```text
|
||
candidate_kind=inventory-ready
|
||
current_status=SKIP
|
||
skip_kind=L4-TOOL-DB
|
||
promotion_allowed=0
|
||
```
|
||
|
||
变为真实可 promotion 状态，并有明确 proof chain；
|
||
6. `summary.tsv` 中 `axis/db_demo/base.ngc` 变为：
|
||
|
||
```text
|
||
inventory_status=PASS
|
||
skip_or_fail_reason=-
|
||
```
|
||
|
||
预期 baseline 变化：
|
||
|
||
```text
|
||
executed: 28 -> 29
|
||
passed: 28 -> 29
|
||
skipped: 131 -> 130
|
||
unexpected_fail: 0
|
||
```
|
||
|
||
十、需要同步更新的文件/断言
|
||
|
||
baseline 真实变化后，至少同步：
|
||
|
||
```text
|
||
wasm-port/docs/sim-configs-coverage-matrix.md
|
||
wasm-port/docs/sim-config-coverage-promotion-analysis.md
|
||
wasm-port/docs/compatibility-validation.md
|
||
wasm-port/runtime/sdk/src/linuxcnc-hal.js
|
||
wasm-port/runtime/sdk/src/project-release-readiness.js
|
||
wasm-port/tests/fixtures/project-release-readiness-ready.json
|
||
wasm-port/tests/sdk/node/verify_sdk_surface.mjs
|
||
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.mjs
|
||
wasm-port/tests/host/verify_project_release_readiness_artifact.mjs
|
||
wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.mjs
|
||
```
|
||
|
||
需要同步更新的固定 baseline：
|
||
|
||
```text
|
||
VIRTUAL_HAL_SIM_CONFIG_INVENTORY_BASELINE
|
||
project release readiness fixture simConfigInventory
|
||
coverage matrix Current Node inventory
|
||
compatibility validation current gate text
|
||
promotion candidate expected status
|
||
skip-summary expected count
|
||
```
|
||
|
||
十一、最小验证命令
|
||
|
||
host runtime 准备阶段：
|
||
|
||
```text
|
||
wasm-port/tests/native/probe_tool_db_runtime.sh
|
||
```
|
||
|
||
native runtime proof 阶段：
|
||
|
||
```text
|
||
ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh
|
||
```
|
||
|
||
artifact / inventory 阶段：
|
||
|
||
```text
|
||
git diff --check
|
||
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
|
||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
|
||
wasm-port/tests/sdk/node/verify_sdk_surface.sh
|
||
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
|
||
```
|
||
|
||
browser / release proof 阶段：
|
||
|
||
```text
|
||
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
|
||
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
|
||
wasm-port/tests/host/verify_project_release_readiness_artifact.sh
|
||
```
|
||
|
||
十二、下一步工作内容
|
||
|
||
当前机器 artifact 显示缺少：
|
||
|
||
```text
|
||
linuxcnc
|
||
milltask
|
||
halcmd
|
||
```
|
||
|
||
因此下一步不是改 Node inventory baseline，而是：
|
||
|
||
1. 在具备完整 LinuxCNC host runtime 的环境中运行：
|
||
|
||
```text
|
||
wasm-port/tests/native/probe_tool_db_runtime.sh
|
||
```
|
||
|
||
2. 如果状态变为 `ready_disabled_by_default`，继续运行：
|
||
|
||
```text
|
||
ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh
|
||
```
|
||
|
||
3. 拿到 `runtime_protocol_probe_passed` 后，刷新 inventory artifacts：
|
||
|
||
```text
|
||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
|
||
```
|
||
|
||
4. 再进入 promotion readiness / lock 更新，而不是直接把
|
||
`axis/db_demo/base.ngc` 改成 PASS。
|
||
|
||
十三、简要结论
|
||
|
||
tool DB 的解锁关键不是 virtual HAL 能力不足，而是还缺 LinuxCNC task/tooldata DB
|
||
process runtime proof。当前 source evidence、contract、readiness artifact、probe gate
|
||
都已铺好；真正的第一步是补齐 host runtime 并跑通
|
||
`ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh`。
|