完善 text14 全项目收口路线图

2026-06-15 21:10:16 +08:00
parent b51ff3415a
commit ac77de3c13
1 changed files with 310 additions and 0 deletions
--- a/text14.txt
+++ b/text14.txt
@@ -219,3 +219,313 @@ wasm-port/tests/native/verify_sim_configs.sh
 `createIniPanelShellWorkflowOverviewEmbeddingMountDomContract()` 或等价 helper，为 mount render-state
 定义 mount/status/rows selectors、dataset keys 与 render-result fields，给后续 DOM readiness 和 renderer
 提供稳定契约；仍保持只读，不新增控制按钮，不解析 G-code。
+
+七、快速推进完成整个项目的详细工作内容和实现步骤
+
+本节是后续按 `text14.txt` 执行的总路线图。目标不是继续堆叠零散 helper，而是把当前
+LinuxCNC WASM/browser port 推到“可交付、可验证、可接续维护”的完整状态。
+
+总体完成定义：
+
+- CNC 语义边界清晰：所有解释器、G-code、tool、parameter、planner、kinematics、remap
+  语义仍来自 LinuxCNC upstream 或 vendored LinuxCNC C/C++/配置/脚本源码；
+- Browser 可用：INI panel、control page、workflow overview、外部 shell handoff、OPFS/session
+  persistence 都有真实 browser smoke；
+- SDK 可用：外部调用方能通过稳定 API 完成加载配置、保存/恢复 session、读取只读状态、
+  获取 workflow report/render-state、执行只读 mount；
+- Coverage 可解释：sim config inventory、promotion/skip 原因、blocked runtime family 都有
+  机器可读输出和文档说明；
+- Gate 可复现：Node、browser、host 聚合 smoke 和 source/vendor guard 稳定通过；
+- 文档可执行：新接手者只看 `text14.txt`、`README.md`、`docs/panel-entry.md`、coverage
+  docs 即可继续工作。
+
+推进顺序必须按以下批次执行；每批完成后追加一个新的中文编号记录到 `text14.txt` 并提交。
+
+1. Browser/UI workflow 收口批次。
+
+目标：完成 workflow overview embedding mount render-state 的 DOM contract/readiness/renderer/mount
+闭环，让外部 shell 无需手写 DOM 细节即可显示完整 embedding mount 结果。
+
+实现步骤：
+
+- 新增 `createIniPanelShellWorkflowOverviewEmbeddingMountDomContract()`：
+  - 定义默认 selectors：
+    - `[data-workflow-overview-embedding-mount]`；
+    - `[data-workflow-overview-embedding-mount-status]`；
+    - `[data-workflow-overview-embedding-mount-rows]`；
+  - 定义 `mountDatasetKeys`：
+    - `handoffPhase`；
+    - `handoffReady`；
+    - `handoffScope`；
+  - 定义 row dataset prefix，默认 `workflowOverviewEmbeddingMount`；
+  - 定义 `renderResultFields`：
+    - `rendered`；
+    - `statusLine`；
+    - `rowCount`；
+    - `rowIds`；
+    - `dataset`；
+- 新增 `createIniPanelShellWorkflowOverviewEmbeddingMountDomReadiness()`：
+  - 检查 document、mount、status、rows、rowDatasetPrefix；
+  - 返回 `apiName`、`readinessVersion`、`phase`、`ready`、`missing`、`checks`、`contract`；
+- 新增 `renderIniPanelShellWorkflowOverviewEmbeddingMountState()`：
+  - 输入 mount render-state 与 DOM contract；
+  - 写入 mount dataset；
+  - 写入 status text；
+  - 渲染 `dt/dd` rows；
+  - 返回结构化 render result；
+- 新增 `mountIniPanelShellWorkflowOverviewEmbeddingMountState()`：
+  - DOM 不 ready 时返回 blocked result；
+  - render 异常时捕获到 `error` 字段；
+  - 成功时返回 `workflowVersion`、`phase`、`ready`、`statusLine`、`domReadiness`、
+    `renderState`、`renderResult`、`error`；
+- 在 `createIniPanelLaunchApiManifest().methods`、`createIniPanelShellViewModel()`、
+  `launch.html`、`workflow-overview.html` 暴露上述 API；
+- 更新：
+  - `verify_ini_panel_ui_shell.mjs`；
+  - `verify_ini_panel_launch_api_manifest.mjs`；
+  - `verify_ini_panel_shell_integration_manifest.mjs`；
+  - `verify_ini_panel_entry_docs.mjs`；
+  - `ini_panel_workflow_overview_smoke.html`；
+  - `ini_panel_shell_integration_workflow_smoke.html`；
+  - `ini_panel_launch_smoke.html`；
+  - `docs/panel-entry.md`。
+
+完成判定：
+
+- 外部 shell 使用自定义 DOM contract 能拿到 ready DOM readiness；
+- mount render-state 能被真实 browser DOM renderer 渲染；
+- mount workflow result 不抛异常，错误通过结构化 `error` 返回；
+- `verify_ui_node_smokes.sh` 与 `verify_ini_panel_browser.sh` 通过。
+
+2. SDK/API surface 收口批次。
+
+目标：把当前分散的 UI helper/API 能力整理成外部调用方可稳定消费的 SDK surface。
+
+实现步骤：
+
+- 检查 `runtime/sdk/src/index.js`、`runtime/sdk/src/linuxcnc-ini.js`、
+  `runtime/sdk/src/linuxcnc-interp.js`、`runtime/sdk/src/sim-config-staging.js`；
+- 为浏览器 UI workflow 新增或整理 SDK export：
+  - entry manifest helper；
+  - launch API manifest/schema helper；
+  - shell integration manifest/readiness/workflow plan；
+  - session handoff summary/package/workflow helper；
+  - workflow overview embedding report/display/render/mount helper；
+  - OPFS file/session bridge helper；
+- 保持 SDK 只做 API 聚合、staging、OPFS/session、WASM/browser boundary，不加入 CNC 语义；
+- 增加 Node SDK smoke：
+  - 验证 export 名称；
+  - 验证 manifest schema；
+  - 验证 helper 返回稳定 shape；
+  - 验证不依赖 browser 目录枚举；
+- 更新 `runtime/sdk/README.md`：
+  - 最小 browser 调用示例；
+  - Node smoke 命令；
+  - 不支持项和 blocked family 说明。
+
+完成判定：
+
+- SDK exports 与 UI/browser manifest 一致；
+- Node SDK smoke 纳入 `verify_host_smokes.sh` 或明确纳入 UI node 聚合；
+- `runtime/sdk/README.md` 可直接指导外部调用方使用。
+
+3. OPFS/session persistence 收口批次。
+
+目标：把 OPFS 文件、session snapshot、control page readonly status、workflow handoff 的真实
+browser 使用路径收口为可复用 workflow。
+
+实现步骤：
+
+- 审查 `runtime/opfs/`：
+  - `file-service.js`；
+  - `machine-file-store.js`；
+  - `snapshot-store.js`；
+  - `linuxcnc-machine-session-bridge.js`；
+  - tool/parameter bridge；
+- 为 UI workflow 增加一个只读 summary/report：
+  - OPFS capability；
+  - session snapshot availability；
+  - loaded machine/session ids；
+  - last save/load status；
+  - readonly control status availability；
+- Browser smoke 增加一条端到端路径：
+  - 保存 machine file；
+  - 保存 session snapshot；
+  - reload/load session；
+  - control page 读取 readonly status；
+  - shell workflow 读取 handoff summary；
+- 不新增控制按钮，不模拟 LinuxCNC runtime，不解析 G-code。
+
+完成判定：
+
+- `browser_ini_opfs_smoke=ok` 仍通过；
+- 新增 OPFS/session workflow summary 的 Node 与 browser smoke；
+- 文档说明 browser OPFS 权限、scope、失败原因。
+
+4. Sim config coverage promotion 批次。
+
+目标：把当前 skipped sim configs 转为“有证据的 skip/promotion 矩阵”，能快速推进可 promotion
+类别，同时明确 blocked 类别。
+
+实现步骤：
+
+- 读取并更新：
+  - `docs/sim-configs-coverage-matrix.md`；
+  - `docs/sim-configs-completion-plan.md`；
+  - `docs/compatibility-validation.md`；
+  - `tests/wasm/node/verify_sim_configs_inventory_wasm.mjs`；
+- 将 skipped configs 按原因分组：
+  - `ASSET_ONLY`；
+  - `L4_PYTHON_REMAP`；
+  - `L4_TOOL_DB`；
+  - `L4_USER_M_PROCESS`；
+  - `NON_MAIN_CLASS`；
+  - `UPSTREAM_DEMO`；
+- 对可 promotion 类别只做 LinuxCNC-owned boundary proof：
+  - 先 native probe；
+  - 再 Node/WASM inventory；
+  - 最后 browser/host gate；
+- 不把 full-process/HAL/UI/Python/tool DB 依赖硬改成 pass；
+- 对仍 blocked 类别补齐机器可读 skip reason 与文档说明。
+
+完成判定：
+
+- `sim_configs_wasm_node_inventory_unexpected_fail=0`；
+- 每个 skip family 都有文档解释；
+- 可 promotion 项有 native/Node/browser 顺序证据；
+- blocked runtime family 不被误 promotion。
+
+5. Host/runtime boundary proof 批次。
+
+目标：把 host/runtime 能力边界从“能跑 smoke”提升为“能说明为什么 pass/skip/blocked”。
+
+实现步骤：
+
+- 审查 native probes：
+  - `probe_millturn_user_m_runtime.sh`；
+  - `probe_tool_db_runtime.sh`；
+  - `probe_python_remap_runtime.sh`；
+  - `verify_native_probes.sh`；
+- 在没有 LinuxCNC host runtime 的环境下保持 blocked，不执行 ENABLE probe；
+- 如果环境提供真实 LinuxCNC host runtime：
+  - 先单独执行 ENABLE probe；
+  - 记录真实输出；
+  - 再决定是否 promotion；
+  - 同步 Node/browser/host gate；
+- 增加或整理 boundary report：
+  - runtime family；
+  - native proof available；
+  - wasm/browser support；
+  - promotion status；
+  - blocking reason。
+
+完成判定：
+
+- `verify_host_smokes.sh` 输出稳定；
+- blocked family 有明确边界 report；
+- 没有把缺 runtime 的情况伪装成 pass。
+
+6. Browser UX 最小完成批次。
+
+目标：让当前 UI 不只是测试可用，也具备外部 shell 可嵌入、可诊断、可解释的最小完成度。
+
+实现步骤：
+
+- 保持现有页面结构：
+  - `launch.html`；
+  - `index.html`；
+  - `control-page.html`；
+  - `workflow-overview.html`；
+- 不新增控制按钮；
+- 不做营销 landing page；
+- 增加或收口只读显示：
+  - launch API manifest/status；
+  - workflow overview embedding mount result；
+  - OPFS/session summary；
+  - blocked reasons；
+- 保证每个 browser namespace 都有：
+  - schema/manifest；
+  - readiness；
+  - display view-model；
+  - render-state；
+  - DOM contract/readiness；
+  - renderer 或 mount workflow；
+- Playwright/browser smoke 验证真实 DOM 不缺节点、status text 与 rows 正确。
+
+完成判定：
+
+- `browser_ini_launch_smoke=ok`；
+- `browser_ini_workflow_overview_smoke=ok`；
+- `browser_ini_shell_integration_workflow_smoke=ok`；
+- 页面 API 与 docs 完全一致。
+
+7. Documentation/release gate 批次。
+
+目标：把项目收口为可交付状态，避免后续只能从聊天记录恢复上下文。
+
+实现步骤：
+
+- 更新 `README.md`：
+  - 项目目标；
+  - 当前可用能力；
+  - 快速验证命令；
+  - 当前不支持/blocked 项；
+- 更新 `docs/panel-entry.md`：
+  - browser entry；
+  - API namespace；
+  - shell handoff/workflow overview；
+  - embedding/mount render path；
+- 更新 `docs/source-reuse-map.md`：
+  - LinuxCNC-owned semantic source；
+  - JS/browser boundary；
+- 更新 `docs/drift-report.md`：
+  - upstream sync 状态；
+  - local wrapper/shim 状态；
+- 新增或更新最终 checklist：
+  - source/vendor guard；
+  - standalone CNC semantics guard；
+  - Node smoke；
+  - browser smoke；
+  - host smoke；
+  - native baseline 如适用。
+
+完成判定：
+
+- 新开发者可以只按 README/docs/text14 执行；
+- 没有必须依赖旧 `text1` 到 `text13` 的隐性步骤；
+- 所有命令可复制执行。
+
+8. 最终验收批次。
+
+目标：确认整个项目达到当前 scope 的完成状态。
+
+最终验收命令：
+
+```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
+```
+
+如涉及 native/source/staging 大范围改动，再执行：
+
+```bash
+wasm-port/tests/native/verify_nc_files.sh
+wasm-port/tests/native/verify_sim_configs.sh
+```
+
+最终完成判定：
+
+- 工作树 clean；
+- 最新提交包含最后一次 `text14.txt` 完成记录；
+- 所有必须 gate 通过；
+- sim config inventory `unexpected_fail=0`；
+- browser INI panel smoke 全部 `ok`；
+- host 聚合输出 `host_wasm_opfs_browser_smokes=ok`；
+- blocked runtime family 明确保留 blocked，不误 promotion；
+- 文档中下一步建议只剩真实外部依赖或明确 scope 外事项。