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

生成时间：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 的验证需要时，继续收敛局部测试胶水。

一、2026-06-14 继续执行记录：INI panel restore/load session workflow helper

本轮按 `text11.txt` 第一原则继续推进实质性 UI/session persistence 能力，把
`Restore Session Snapshot` 和 `Restore And Load Session` 两条用户流程抽成可复用 workflow
helper，而不是继续做局部 path/test glue 收敛。

完成内容：

- 扩展 `wasm-port/runtime/ui/ini-panel/session-workflow.js`；
- 新增导出：
  - `restoreMachineSessionSnapshotWorkflow(input)`；
  - `sessionSnapshotRestoreLogLines(summary)`；
- restore workflow 通过注入函数执行：
  - `loadMachineSessionSnapshot(...)`；
  - `loadMachineTextFiles(...)`；
  - 可选 `loadSession()`；
- restore-only 返回：
  - restored snapshot；
  - editor INI text；
  - snapshot summary；
  - OPFS field state；
  - restore log lines；
- restore-and-load 返回：
  - loaded session；
  - load summary；
  - WASM field state；
  - snapshot + OPFS-to-WASM load log lines；
- `wasm-port/runtime/ui/ini-panel/app.js` 的 `Restore Session Snapshot` 和
  `Restore And Load Session` 按钮改为调用 workflow helper，按钮处理器只负责写 editor、
  field 和 log；
- `wasm-port/tests/ui/node/verify_ini_panel_session_workflow.mjs` 覆盖 save、restore-only
  和 restore-and-load 三条 workflow；
- `wasm-port/docs/ui-session-summary-helpers.md` 更新 restore workflow API、返回结构、
  log helper 和边界说明；
- 未改变 OPFS bridge、snapshot-store、machine-file-store、LinuxCNC interpreter、tool、
  parameter、G-code 文本或 LinuxCNC-owned runtime semantics。

验证已通过：

```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_panel_session_workflow_node_smoke=ok
ini_panel_run_summary_node_smoke=ok
ini_panel_session_summary_node_smoke=ok
ini_panel_machine_file_summary_node_smoke=ok
ini_panel_state_summary_node_smoke=ok
ui_node_smokes=ok
browser_ini_opfs_smoke=ok
vendor sync up to date
standalone CNC semantics guard complete
interp_wasm_node_smoke=ok
sim_configs_wasm_node_inventory_executed=28
sim_configs_wasm_node_inventory_passed=28
sim_configs_wasm_node_inventory_skipped=131
sim_configs_wasm_node_inventory_unexpected_fail=0
host_wasm_opfs_browser_smokes=ok
```

下一步建议：

继续按“实质性能力优先”推进。下一批优先把 `run-gcode` 的用户流程抽成可调用 workflow
helper，覆盖 snapshot/default program selection、G-code OPFS load、WASM write、LinuxCNC
interpreter run、run summary、field/log state 和 error state。该 helper 仍只能编排
host/runtime boundary，不解析或实现 G-code、planner、tool、parameter 或 canonical-event
语义。

二、2026-06-14 继续执行记录：INI panel run G-code workflow helper

本轮继续按 `text11.txt` 第一原则推进实质性 UI workflow 能力，把 `run-gcode` 用户流程抽成
可复用 helper，让上层 UI/API 可以直接复用 session/default G-code 选择、OPFS load、WASM
staging、LinuxCNC interpreter run、run summary、field/log state 的编排。

完成内容：

- 新增 `wasm-port/runtime/ui/ini-panel/run-workflow.js`；
- 导出：
  - `selectSessionGcodeProgram(input)`；
  - `runSessionContextLogLines(program, snapshot, snapshotLabel)`；
  - `runGcodeSessionWorkflow(input)`；
- workflow helper 执行 host/runtime boundary 编排：
  - 从 snapshot G-code OPFS path 或默认 G-code path 选择程序；
  - 通过注入的 `loadGcodeProgram(...)` 读取 OPFS G-code 文本；
  - 调用 `interp.writeTextFile(...)` 写入 interpreter WASM filesystem；
  - 调用 LinuxCNC-owned `interp.runFileWithIni(...)`；
  - 返回 program、resultText、run summary、UI field state、motionSnapshots 和 log lines；
- `wasm-port/runtime/ui/ini-panel/app.js` 的 `Run G-code` 按钮改为调用 workflow helper；
- canonical-event 展示和 motion playback 仍留在 UI 层，workflow 只通过注入的
  `summarizeRun(...)` 接收已观察到的 UI summary/motion state；
- 新增 `wasm-port/tests/ui/node/verify_ini_panel_run_workflow.mjs` 和 shell wrapper；
- `wasm-port/tests/ui/node/verify_ui_node_smokes.sh` 纳入 run workflow smoke；
- `wasm-port/docs/ui-run-summary-helpers.md` 更新 run workflow API、返回结构和边界说明；
- 未改变 OPFS bridge、machine-file-store、LinuxCNC interpreter、G-code 文本、canonical-event
  语义、tool、parameter、planner 或 LinuxCNC-owned runtime semantics。

验证已通过：

```bash
git diff --check
wasm-port/tests/ui/node/verify_ini_panel_run_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_panel_run_workflow_node_smoke=ok
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
browser_ini_opfs_smoke=ok
vendor sync up to date
standalone CNC semantics guard complete
interp_wasm_node_smoke=ok
sim_configs_wasm_node_inventory_executed=28
sim_configs_wasm_node_inventory_passed=28
sim_configs_wasm_node_inventory_skipped=131
sim_configs_wasm_node_inventory_unexpected_fail=0
host_wasm_opfs_browser_smokes=ok
```

下一步建议：

继续按“实质性能力优先”推进。优先把 save/restore/load/run workflow 的结果汇总成一个
更完整的 machine session state snapshot helper，供上层 UI/API 直接消费当前 machine、
session、loaded WASM mapping、selected G-code、last run summary、panel badges 和 error
state；该 helper 只聚合已有 host/runtime boundary facts，不解析 G-code 或扩展 CNC 语义。

三、2026-06-14 继续执行记录：INI panel machine session state snapshot helper

本轮继续按 `text11.txt` 第一原则推进实质性 UI/API 能力，把 save/restore/load/run workflow
的结果汇总成一个 machine session state snapshot，供上层 UI/API 直接读取，而不是继续
依赖分散的 DOM 字段、日志文本和临时全局值。

完成内容：

- 扩展 `wasm-port/runtime/ui/ini-panel/panel-state-summary.js`；
- 新增导出 `createMachineSessionStateSnapshot(input)`；
- state snapshot 汇总：
  - panel badges；
  - machine；
  - machineFiles；
  - sessionSnapshot；
  - sessionLoad；
  - selectedProgram；
  - run summary；
  - fields；
  - lastAction；
  - error；
  - fiveaxisRemap；
- `wasm-port/runtime/ui/ini-panel/app.js` 在 save/restore/load/run/failure/boot 路径后更新
  `window.linuxCncIniPanelMachineSessionState`；
- browser INI panel smoke 现在直接校验该 state snapshot 的关键字段；
- `wasm-port/tests/ui/node/verify_ini_panel_state_summary.mjs` 覆盖新 state snapshot 形状；
- `wasm-port/docs/ui-panel-state-summary.md` 更新 state snapshot API、window 暴露和边界说明；
- 未改变 OPFS bridge、snapshot-store、machine-file-store、LinuxCNC interpreter、G-code 文本、
  canonical-event 语义、tool、parameter、planner 或 LinuxCNC-owned runtime semantics。

验证已通过：

```bash
git diff --check
wasm-port/tests/ui/node/verify_ini_panel_state_summary.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_panel_state_summary_node_smoke=ok
ini_panel_run_summary_node_smoke=ok
ini_panel_run_workflow_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
ui_node_smokes=ok
browser_ini_opfs_smoke=ok
vendor sync up to date
standalone CNC semantics guard complete
interp_wasm_node_smoke=ok
sim_configs_wasm_node_inventory_executed=28
sim_configs_wasm_node_inventory_passed=28
sim_configs_wasm_node_inventory_skipped=131
sim_configs_wasm_node_inventory_unexpected_fail=0
host_wasm_opfs_browser_smokes=ok
```

下一步建议：

继续按“实质性能力优先”推进。下一批优先把 `window.linuxCncIniPanelMachineSessionState`
整理成更明确的 API/文档使用方式，或者在 `run-gcode`/restore/load/save 之外再补一层
更高阶的 UI consumer helper，用于读取状态并生成上层展示/导出结果；只围绕已有
host/runtime boundary facts 组合，不回到 path guard。
