项目整体完成情况与后续执行计划

生成时间：2026-06-14 CST

本文件接替 `text10.txt`。后续工作按 `text11.txt` 执行；除非明确要求审计旧记录，
不要再回到 `text1/text2/text3/text4/text5/text6/text7/text8/text9/text10` 扩展进度。
`text10.txt` 作为历史归档保留。

一、第一原则：加快实质性推进

后续批次必须以“实质性能力优先”为第一遵守原则。

1. 优先级从高到低：

- OPFS/session persistence；
- SDK/API surface；
- browser/UI workflow；
- sim config coverage promotion；
- host/runtime boundary proof；
- 文档化可执行工作流。

2. 每批默认应产出至少一种可直接复用的能力：

- 可调用 helper；
- 可复用 API；
- 可验证用户流程；
- 可执行 gate；
- 可提升覆盖面的 runtime boundary proof；
- 能直接指导下一步实现的设计/清单。

3. 暂停低收益推进：

- 不再把“局部常量化、路径变量收敛、断言分组整理”作为主目标；
- 只有当它支撑可复用 workflow/API/gate 时，才允许做测试胶水；
- 禁止为了推进而扩大 CNC 语义边界；
- 禁止启动性能测试，除非已有明确用户流程需要性能基线。

4. LinuxCNC 仍是唯一 CNC 语义来源：

- G-code、remap、tool、parameter、planner、kinematics、user-M、tool DB、Python remap
  等语义必须来自 LinuxCNC upstream 或 vendored LinuxCNC C/C++/配置/脚本源码；
- JS/browser 只允许做 build、source sync、runtime shim、filesystem staging、OPFS、
  WASM/browser boundary、测试胶水、文档和机器可读 gate/artifact；
- 不在 JS 中重写 G-code 或 CNC 语义；
- 不修改 vendored LinuxCNC 源文件来让测试通过；
- 不把 full-process/HAL/UI/Python/tool DB 依赖伪装成 standalone pass；
- 不把 expected failure 硬改成 pass，除非已有 LinuxCNC-owned runtime proof，并且
  native、Node、browser gate 都按顺序通过；
- browser 不能依赖目录枚举。

二、续接状态与防重规则

1. 当前续接点。

`text10.txt` 已推进到：

```text
二十八、2026-06-14 继续执行记录：INI panel session snapshot workflow helper
```

该批已提交：

```text
4e4a9c6 推进 INI 面板 session snapshot workflow helper
```

本文件从 `text11.txt` 重新开始记录后续进度。

2. 每轮开始前必须先执行：

```bash
git status --short
git log -5 --oneline
tail -n 120 text11.txt
awk '/^[一二三四五六七八九十百]+、/ {print}' text11.txt | sort | uniq -d
```

执行规则：

- 如果 `git status --short` 是 clean，且最新提交已经包含当前建议工作，不要重复追加记录；
- 每轮只追加一个新的中文编号记录；
- 提交前再次检查标题唯一性；
- `text11.txt` 只记录新的后续进度，不复制 `text10.txt` 的长历史；
- 每批完成后，如果要写记录，先写 `text11.txt`，再提交该批代码和记录；
- 如果发现重复记录，先做 dedupe 清理并提交，再继续新功能或新 guard；
- `text10.txt` 不再追加新进度，除非明确要求审计或修正历史记录。

三、当前完成情况摘要

1. 当前工作树状态。

切换到 `text11.txt` 前已确认：

```text
git status --short: clean
```

当前最近提交：

```text
4e4a9c6 推进 INI 面板 session snapshot workflow helper
48a0f61 收拢 browser explicit session readback path helper
b85444b 推进 INI 面板状态汇总 helper
405cc0b 推进 INI 面板 machine file helper 文档
a60826b 推进 INI 面板 machine file summary helper
```

2. WASM port 基础架构稳定。

`wasm-port` 仍按独立移植工作区组织，包含 vendor、runtime/core、runtime/sdk、
runtime/opfs、runtime/ui、native/wasm/browser tests、docs 和 tools。

3. 关键基线保持稳定。

- `linuxcnc/nc_files` native Layer 1：
  - `total 107`
  - `pass 101`
  - `expected_fail 6`
  - `unexpected_fail 0`
- `linuxcnc/configs/sim` native Layer 2：
  - `total 159`
  - `pass 151`
  - `expected_fail 8`
  - `unexpected_fail 0`
- Node sim-config inventory：
  - `executed=28`
  - `passed=28`
  - `skipped=131`
  - `unexpected_fail=0`

4. blocked runtime family 仍未 promotion。

仍 blocked，不允许 promotion：

- `L4-USER-M-PROCESS`
- `L4-TOOL-DB`
- `L4-PYTHON-REMAP`

当前 host 仍按缺少 LinuxCNC host runtime 处理，不执行任何：

```bash
ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh
ENABLE_TOOL_DB_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_tool_db_runtime.sh
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_python_remap_runtime.sh
```

四、当前实质能力进展

1. INI panel/UI helper 能力。

当前 UI helper 已覆盖：

- run summary；
- session snapshot summary；
- session load summary；
- machine file save/load summary；
- panel state summary；
- session snapshot save workflow。

当前聚合验证入口：

```bash
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
```

当前 `verify_ui_node_smokes.sh` 覆盖：

```text
ini_panel_run_summary_node_smoke=ok
ini_panel_session_summary_node_smoke=ok
ini_panel_session_workflow_node_smoke=ok
ini_panel_machine_file_summary_node_smoke=ok
ini_panel_state_summary_node_smoke=ok
ui_node_smokes=ok
```

2. Session snapshot save workflow。

当前已新增：

```text
wasm-port/runtime/ui/ini-panel/session-workflow.js
```

导出：

```text
saveMachineSessionSnapshotWorkflow(input)
createSessionSnapshotFieldState(summary)
sessionSnapshotSaveLogLines(summary)
```

该 workflow helper 执行完整 host-boundary 保存链路：

- 写入当前 INI/tool/parameter machine text files；
- 写入默认 G-code program；
- 保存 machine session snapshot；
- 返回 snapshot summary、UI field state 和 log lines。

`wasm-port/runtime/ui/ini-panel/app.js` 的 `Save Session Snapshot` 按钮已改为调用该
workflow helper，按钮处理器只负责 field/log 渲染。

3. Browser/UI workflow 验证。

当前 browser INI panel smoke 继续覆盖真实 OPFS/session persistence workflow：

```bash
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
```

关键输出：

```text
browser_ini_opfs_smoke=ok
```

五、当前必须保持通过的验证入口

每批后续改动至少运行：

```bash
git diff --check
wasm-port/tools/verify_vendor_sync.sh
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
wasm-port/tests/host/verify_host_smokes.sh
```

如果涉及 browser interpreter smoke，再运行：

```bash
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_interp_browser.sh
```

涉及 native baseline 或大范围 source/staging 改动时，再运行：

```bash
wasm-port/tests/native/verify_nc_files.sh
wasm-port/tests/native/verify_sim_configs.sh
wasm-port/tests/native/verify_native_probes.sh
```

六、下一步执行计划

1. 当前第一候选批次：restore/load session workflow helper。

按“实质性能力优先”，下一批不要回到零散 path guard。优先把
`Restore Session Snapshot` 与 `Restore And Load Session` 抽成 session workflow helper，
让 restore、load、field state、summary/log lines 走同一套可调用 API。

建议目标：

- 在 `wasm-port/runtime/ui/ini-panel/session-workflow.js` 增加 restore workflow helper；
- helper 通过注入函数执行：
  - `loadMachineSessionSnapshot(...)`；
  - `loadMachineTextFiles(...)`；
  - 可选 `loadMachineSessionFromOpfs(...)`；
- 返回：
  - restored snapshot；
  - editor INI text；
  - snapshot summary；
  - optional load summary；
  - UI field state；
  - log lines；
- `app.js` 的 `Restore Session Snapshot` 和 `Restore And Load Session` 按钮改为调用该
  workflow helper；
- Node smoke 覆盖 restore-only 与 restore-and-load 两种流程；
- Browser INI panel smoke 继续验证真实 OPFS/session persistence；
- 不改变 snapshot-store、machine-file-store、LinuxCNC interpreter、tool、parameter 或
  G-code semantics。

2. 第一候选批次验证。

执行：

```bash
git diff --check
wasm-port/tests/ui/node/verify_ini_panel_session_workflow.sh
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
wasm-port/tools/verify_vendor_sync.sh
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
wasm-port/tests/host/verify_host_smokes.sh
```

如果通过，提交建议：

```text
推进 INI 面板 restore/load session workflow helper
```

3. 后续候选。

如果 restore/load workflow 完成后仍有余力，继续推进更实质的用户流程能力：

- 把 `run-gcode` 的 snapshot/default program selection、WASM write、run summary、field/log
  更新抽成可调用 workflow helper；
- 给 UI/API 暴露一个更完整的 machine session state snapshot，用于上层应用直接消费；
- 只在这些 workflow helper 的验证需要时，继续收敛局部测试胶水。
