diff --git a/text14.txt b/text14.txt index b185ee6..99fe711 100644 --- 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 外事项。