wangdequan
626bcfe8e3
结论：完成 LinuxCNC kinematics WASM ABI 覆盖，并将 web-rtcp-5axis-sim-plan 的 RTCP frame/boundary adapter 接到 xyzac-trt kinematics SDK；Node、build、browser smoke 验证通过。
255 lines
7.5 KiB
Plaintext
255 lines
7.5 KiB
Plaintext
text36.txt
|
||
|
||
一、接续说明
|
||
|
||
执行时间：2026-06-20 CST
|
||
|
||
本文件只服务于一个目标：
|
||
|
||
```text
|
||
快速完成“当前 smoke 收尾”
|
||
```
|
||
|
||
这里的 smoke 特指：
|
||
|
||
```text
|
||
wasm-port/tests/browser/real_simulation_page_smoke.html
|
||
```
|
||
|
||
本文件不讨论 77 SKIP promotion 复核，不讨论 inventory baseline 变化，也不继续新增
|
||
real simulation page runtime surface。目标是尽快把 handoff smoke 收敛工作收口，形成
|
||
稳定、低重复、可继续维护的 browser smoke。
|
||
|
||
二、当前状态
|
||
|
||
当前已经完成的收敛：
|
||
|
||
```text
|
||
1. 已为 handoff summary / operator snapshot / action plan / compact status /
|
||
preflight / history 提取共享 smoke helper；
|
||
2. 已把 blocked / saved ready / restored ready 三态里一批 dataset / DOM /
|
||
status-history 重复断言迁移到 helper；
|
||
3. 浏览器 smoke 当前保持通过；
|
||
4. inventory baseline 仍保持 82/82/77/0。
|
||
```
|
||
|
||
当前仍可能残留的问题，不是行为错误，而是测试结构层面的尾项：
|
||
|
||
```text
|
||
1. review/statusbar/external-shell 同一批 surface 仍可能存在对象字段重复断言；
|
||
2. 个别断言仍混合“主入口契约检查”和“兼容入口镜像检查”；
|
||
3. 三态大 if 仍偏长，后续维护成本高；
|
||
4. helper 与大 if 的边界尚未完全固化。
|
||
```
|
||
|
||
三、收尾目标
|
||
|
||
本轮 smoke 收尾的完成标准：
|
||
|
||
```text
|
||
1. blocked / saved ready / restored ready 三态继续完整覆盖；
|
||
2. handoff summary / operator / preflight / history 这批兼容入口不再在三态大 if 中重复散落；
|
||
3. review/statusbar/external-shell 同一批 surface 的重复断言尽量收口到 helper；
|
||
4. 不新增 getter / dataset / DOM selector；
|
||
5. 不改 runtime surface；
|
||
6. browser_real_simulation_page_smoke=ok。
|
||
```
|
||
|
||
不在本轮范围内的工作：
|
||
|
||
```text
|
||
1. 不新增任何新的 external-shell bundle / badge / receipt / verification surface；
|
||
2. 不修改 wasm-port/runtime/ui/simulation/index.html 的行为；
|
||
3. 不改 diagnostics artifact schema；
|
||
4. 不改 release artifact schema；
|
||
5. 不触碰 77 SKIP promotion 主线。
|
||
```
|
||
|
||
四、建议执行顺序
|
||
|
||
第一阶段：列出剩余重复断言
|
||
|
||
目标：
|
||
|
||
```text
|
||
把 real_simulation_page_smoke.html 中仍残留在三态大 if 里的 handoff 相关断言，按主题归类。
|
||
```
|
||
|
||
建议操作：
|
||
|
||
```text
|
||
1. 只看 blocked / saved ready / restored ready 三段；
|
||
2. 标记仍属于以下主题的断言：
|
||
- review packet / copy-export / verification / badge
|
||
- statusbar snapshot / receipt / receipt verification / receipt badge
|
||
- external shell badge snapshot / copy-export
|
||
- external shell bundle / receipt / receipt verification / audit bundle
|
||
3. 判断每类断言里哪些是：
|
||
- 主对象字段契约检查
|
||
- dataset / DOM 兼容镜像检查
|
||
4. 只迁移兼容镜像检查，不迁移真正承担对象契约的字段检查。
|
||
```
|
||
|
||
退出条件：
|
||
|
||
```text
|
||
形成“剩余重复断言清单”，并明确哪些适合继续进 helper，哪些必须保留在大 if。
|
||
```
|
||
|
||
第二阶段：继续提取 helper
|
||
|
||
目标：
|
||
|
||
```text
|
||
把第一阶段识别出的兼容镜像断言继续迁移到共享 helper。
|
||
```
|
||
|
||
建议操作：
|
||
|
||
```text
|
||
1. 优先复用已有 assertLegacyHandoff* helper 风格；
|
||
2. 新 helper 只做以下事情：
|
||
- dataset 值一致性；
|
||
- DOM 文本一致性；
|
||
- statusbar / diagnostics / document.body.dataset 镜像一致性；
|
||
3. helper 入参使用 phase / action / preflight / digest / expectedText 这类已稳定字段；
|
||
4. 不在 helper 中重新实现复杂业务拼接逻辑，尽量使用调用方已构造好的 expected text。
|
||
```
|
||
|
||
helper 命名建议：
|
||
|
||
```text
|
||
若继续扩展 legacy helper，优先保持：
|
||
- assertLegacyHandoffReviewStatusbarDom(...)
|
||
- assertLegacyHandoffReviewStatusbarDataset(...)
|
||
|
||
若必须新增 helper，命名应保持主题聚合，避免再出现更细碎的 micro-helper。
|
||
```
|
||
|
||
退出条件：
|
||
|
||
```text
|
||
新增 helper 后，三态大 if 中同类 dataset / DOM 重复断言明显减少。
|
||
```
|
||
|
||
第三阶段：清理三态大 if
|
||
|
||
目标：
|
||
|
||
```text
|
||
删除已被 helper 完整覆盖的旧断言，保留真正需要的对象契约检查。
|
||
```
|
||
|
||
删除原则：
|
||
|
||
```text
|
||
1. helper 已检查的数据，不再在大 if 中重复检查第二次；
|
||
2. 主对象字段、API 名、phase / ready / digest / rows 长度这类核心契约，仍可保留；
|
||
3. 不为了“更短”而把关键对象字段契约也删掉；
|
||
4. 不删除三态覆盖；
|
||
5. 不删除公开 surface 的存在性检查。
|
||
```
|
||
|
||
建议保留的大 if 检查类型：
|
||
|
||
```text
|
||
1. apiName / phase / ready / baseline / digest 等对象自身契约；
|
||
2. rows.length / every(row.ready===true) 这类结构契约；
|
||
3. JSON.parse(packetJson) 后的关键字段；
|
||
4. 与 helper 不同层级的对象内容一致性。
|
||
```
|
||
|
||
退出条件：
|
||
|
||
```text
|
||
三态大 if 剩余内容主要是对象契约，而不是兼容入口镜像重复检查。
|
||
```
|
||
|
||
第四阶段：统一 helper 边界
|
||
|
||
目标：
|
||
|
||
```text
|
||
让后续维护者一眼能看出：哪些断言该放 helper，哪些该留在大 if。
|
||
```
|
||
|
||
建议操作：
|
||
|
||
```text
|
||
1. helper 内只处理“同一组 surface 的镜像一致性”；
|
||
2. 大 if 只处理“该阶段对象契约是否成立”；
|
||
3. 若 helper 和大 if 都检查同一值，优先保留 helper，删除重复镜像检查；
|
||
4. 若某值同时承载业务契约和镜像一致性，则在大 if 留对象字段，在 helper 留 DOM/dataset。
|
||
```
|
||
|
||
退出条件：
|
||
|
||
```text
|
||
文件结构形成稳定分层：
|
||
helper = 兼容镜像一致性
|
||
大 if = 阶段对象契约
|
||
```
|
||
|
||
五、建议具体检查清单
|
||
|
||
下一轮可直接按下面 checklist 执行：
|
||
|
||
```text
|
||
[ ] 1. 扫描 blocked / saved / restored 三段剩余 handoff 断言；
|
||
[ ] 2. 标记 review/statusbar/external-shell 中仍重复的 dataset / DOM 检查；
|
||
[ ] 3. 判断哪些是对象契约，哪些只是兼容镜像；
|
||
[ ] 4. 继续扩展现有 legacy helper，避免新增碎片 helper；
|
||
[ ] 5. 删除 helper 已覆盖的旧断言；
|
||
[ ] 6. 检查三态是否仍完整覆盖；
|
||
[ ] 7. 运行 git diff --check；
|
||
[ ] 8. 运行 browser real simulation smoke；
|
||
[ ] 9. 若 helper 边界稳定，补写下一份接续记录并宣布 smoke 收尾完成。
|
||
```
|
||
|
||
六、退出标准
|
||
|
||
本轮 smoke 收尾可宣布完成的标准：
|
||
|
||
```text
|
||
1. real_simulation_page_smoke.html 中 handoff 相关 helper 边界稳定；
|
||
2. 三态大 if 不再承载大量兼容入口重复镜像断言；
|
||
3. review/statusbar/external-shell 同一批 surface 的重复检查已基本收平；
|
||
4. browser_real_simulation_page_smoke=ok；
|
||
5. 没有新增 runtime surface；
|
||
6. inventory baseline 仍保持 82/82/77/0。
|
||
```
|
||
|
||
如果满足以上条件，下一轮就不应继续在这一批 smoke 上做小修小补，而应：
|
||
|
||
```text
|
||
1. 正式结束“当前 smoke 收尾”阶段；
|
||
2. 选择返回 promotion / inventory 主线，或继续已 PASS row 的 evidence expansion 主线。
|
||
```
|
||
|
||
七、建议验证命令
|
||
|
||
最低验证：
|
||
|
||
```bash
|
||
git diff --check
|
||
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
|
||
```
|
||
|
||
如果下一轮顺手碰到 inventory / docs / artifact 路径，再补：
|
||
|
||
```bash
|
||
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
|
||
wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh
|
||
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
|
||
```
|
||
|
||
八、注意事项
|
||
|
||
```text
|
||
1. 不要为了“测试更短”而删除对象契约检查；
|
||
2. 不要继续叠加新的 external-shell micro-surface；
|
||
3. 不要把 runtime 业务逻辑搬进 smoke helper；
|
||
4. 不要重新打开 77 SKIP promotion 总复核；
|
||
5. 这轮只做 smoke 收尾，不做主线切换。
|
||
```
|