Files
VibemakerSandbox/docs/superpowers/verification/2026-10-27-multi-robot-platform.md
chenlin fc5ee4f2c6 feat: release v0.2 multi-robot simulator
Add declarative robot packages, shared simulation lifecycle and Microban ONNX/PD walking with independent head control.

Unify comic UI and chase camera; default robot packages to a 4.5m arena with real collision walls. Include regression tests, asset provenance/licenses and verification evidence.
2026-10-28 14:00:26 +08:00

113 lines
9.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 多机器人平台首期工程验收
> 历史检查点:2026-10-28 已按用户确认统一界面风格和背后跟随相机。当前行为与验证见 [更新报告](2026-10-28-style-and-chase-camera.md);下文保留原验收状态与当时的输入哈希。
- 日期:2026-10-27;最终自动化检查完成于 22:03(UTC+08:00)。
- 结论:本地首期实现及自动化验收通过;待用户实际体验确认。**未提交、未推送、未部署。**
- 范围:Microduck legs / rollers;Microban ONNX 行走及独立转头;单一仿真界面。
- 依据:[批准的设计](../specs/2026-10-27-multi-robot-platform-design.md)、[实施计划](../plans/2026-10-27-multi-robot-platform-implementation.md)。
## 1. 交付内容
| 阶段 | 结果 |
|---|---|
| P0 / T01–T04 | 真实浏览器/WASM、独占步进、原版 Microduck 参考、资产来源/许可与 Microban PD 可行性验证 |
| P1 / T05–T06 | 生命周期、冻结式暂停、自动启动、行内错误/重试、工具栏及默认展开的键盘帮助;移除菜单/BIOS/触屏层 |
| P2 / T07–T11 | Package/World schema、加载与验证、共享调度/模型寻址/观测/动作/驱动、primary/overlay 技能;Microduck 兼容适配器 |
| P3 / T12–T14 | arena/flat World、编译后 MJCF 视觉、事务切换、失败回滚、资源释放与偏好恢复 |
| P4 / T15 | Microban 正式接入、50 Hz 控制、行走和独立 head overlay、手动倒地复位 |
| P5 / T16 | 单元/浏览器/生产构建/子路径检查、文档、截图、录像和数值记录;下述未验证事项不计入已通过范围 |
入口是 `app/src/App.jsx` / `app/src/scene/GameCanvas.jsx`。通用能力在 `app/src/platform/`,注册表在 `app/src/robots/registry.js`;原有 Microduck 行为迁至 `app/src/robots/microduck/runtime.js`,`game/game.js` 仅保留兼容导出。
平台核心没有按 Microduck/Microban ID 分派的逻辑,也不导入 `game/`;内置适配器名称在 schema 中显式允许。Microduck 的 GLB、材质和既有技能仍由专用适配器维护,并未声称全部转换成通用声明式状态机。
## 2. 最终检查结果
环境:Linux x86_64、Node v24.19.0、Playwright 1.64.1、Chromium/SwiftShader,MuJoCo `@mujoco/mujoco` 3.11.0。依赖由 `app/package-lock.json` 锁定。以下均为实际执行,没有 skip、自动重试或更新已接受黄金快照。
| 检查 | 结果 | 持久证据 |
|---|---|---|
| `npm --prefix app test` | **29/29** | 测试源:`app/test/*.test.js` |
| `npm --prefix app run validate:packages` | 三包 schema、World、路径通过;Microban 实际文件哈希通过 | 两个 Microduck 包各 10 路径;Microban 27 路径 |
| `npm --prefix app run format:check` | 通过 | 按脚本指定的新模块/测试范围检查,不代表整个历史代码库重排格式 |
| `npm --prefix app run test:e2e` | **25/25,226.54 s** | [开发态结果](assets/development-results.json) |
| `npm --prefix app run build` + production preview | **20/20,173.34 s** | [生产结果](assets/production-results.json) |
| `VITE_BASE=/play/` build + preview | **1/1,20.20 s**;两机器人、资源前缀、字体均通过 | [子路径结果](assets/prefix-results.json) |
| `npm --prefix app audit` | **0 vulnerabilities** | 当前锁定依赖的检查;不等于安全审计保证 |
| `git diff --check` | 通过 | 没有自动提交 |
最终 `app/dist` 已重新构建为默认根路径版本。临时原版/生产/prefix preview 服务在验收后关闭;未关闭已有开发服务器。
生产套件包括九个 Microduck 数值场景、Microban 三轮协议/实时控制/IMU、鼠标选点与物理拖拽、双向切换与回滚、独占步进和 UI。完整开发套件还包含隔离 PD probe、渲染器夹具、并发竞态及 20 次切换资源检查;因此不要把“生产 20 项”误写成生产环境执行了全部 25 项。
## 3. Microduck 保真
九个场景:stand、walk、kick、sitstand、groundpick、roll、recovery、rollers、crouch。按固定输入和种子执行,当前实现与原版同后端参考的观测、动作和物理轨迹比较通过,没有提高容差或用当前实现覆盖参考。
参考来自独立归档的原始提交 `44d3681726468bdd00e88241894d5faa53e3c63e`,不是重构后 runtime 自己生成的“预期值”。建立参考时发现外观用球生成会改变 RNG/物理状态,随后统一隔离条件并从原版重新采集;出处及条件见 [基线说明](../../../app/test/fixtures/microduck/README.md)。`baseline:record` 只生成忽略的候选,不自动接受。
保留 arena、GLB、配色、追随/轨道相机、鼠标物理拖拽、主要技能和原有倒地恢复。跨机器人切换重新初始化物理,并记住本会话内 Microduck 配色和 legs/rollers;家族内切换仍走原有安全路径。窗口实际相机与加载时被 helper 捕获的相机已同步,并新增真实鼠标选点/拖拽检查。
视觉材料供用户复核,不以九条数值回归代替所有可能玩法或像素级视觉验收:
![Microduck](assets/microduck.png)
## 4. Microban 实际物理证据
- 原模型、25 个 STL 与 ONNX 复制到包内,正式运行不依赖 `../microban` 或 Python。
- 源 HEAD 为 `d0a128d180ecfce69eaaf31b295a0fce31280bfd`,源工作区本来有未提交修改;记录的是实际文件哈希,未修改源项目。
- 真实 policy `obs [1,63] → actions [1,18]`;metadata 有 19 个关节,按名称选取 18 个 actor 关节,head 不进入 actor/lastAction。
- IMU 角速度保持 site frame;投影重力由去除安装旋转的 trunk 姿态计算,已用非零姿态/角速度检查。
- 简化 PD:`kp=.3`、`kd=.02`、`|tau|≤.65 Nm`,每个 `.005 s` 物理子步更新;decimation 4,控制 50 Hz。原 `<motor>` 的 ctrl 写入力矩,不把目标角当力矩。
- 键盘速度:前进 `.15 m/s`、后退 `-.1 m/s`、转向 `±.6 rad/s`。未降低重力、锁定底座、播放 qpos 轨迹或以定时 reset 掩盖倒地。
[完整三轮记录](assets/microban-three-trials.json)。每轮从复位开始,10 s 站立、20 s 前进、10 s 后退、左右转向各 10 s、四段 3 s 零命令、行走中转头 10 s、关头后继续 2 s,共 **84 s**。轮内无倒地/重置,状态有限;三个复位起步重复通过。
| 指标(每轮) | 实测 |
|---|---:|
| 20 s 前进:按段起始朝向投影位移 | +2.438 m |
| 10 s 后退:同定义投影位移 | −0.769 m |
| 左转/右转累计偏航 | +4.780 / −4.564 rad |
| 行走并行转头实测范围 | −0.692 至 +0.693 rad |
| 关头 2 s 后角度 | 约 +0.040 rad;目标为 0 |
| 力矩采样/饱和 | 319,200 / **0** |
Head 目标仍为 `.35 Hz`、`±π/4`,启停 `.5 s` 插值;H 开关不清 walking actor 的 lastAction,暂停冻结技能时间。实际关节幅度/残差反映简化 PD 跟踪,不宣称 BAM 等价。
[实时记录](assets/real-time.json):约 5.005 s 墙钟推进 5.040 s 仿真,比例 **1.007**。这是本机短窗测量,不是所有设备实时性保证。另测了主动制造倒地、Space 手动复位和键盘 H;正式运行没有 Microban 自动站起。
![Microban](assets/microban.png)
## 5. 生命周期和故障
[同页面 20 次切换记录](assets/runtime-ownership.json):旧 model/data 均确认 deleted;稳定阶段 Microduck 约 46 geometry/4 texture/24 个被跟踪监听器,Microban 64/1/14,场景顶层 children 为 5。跟踪范围是 window/canvas,不声称穷尽浏览器/驱动的每一字节。
已实际覆盖:
- 自动循环与手动步进互斥,等待在途推理;暂停后不补偿过去的墙钟时间。
- 切换 single-flight、旧 tick 排空、held keys 清理、暂停意图保留。
- 模型/GLB/策略加载失败:行内错误、重试、保留旧 runtime、未污染共享 GLB 缓存。
- 复位与暂停的技能计时;输入框/选择器/按钮的原生键盘行为;帮助与输入路由共用 bindings。
- 编译后 mesh/primitive 的变换、倒序 actuator 的名称寻址,不使用两个模型间的索引巧合。
收尾修复:Google Fonts 外部 CSS 曾使 `page.goto(..., waitUntil=load)` 等待到 180 s 超时。现本地打包 Anton 并保留 OFL 通知;根路径/子路径默认加载两机器人均验证**没有外站请求**。中性 World 的参考网格直接着色于编译后的物理地面视觉,不增加碰撞体,也不使用有裁剪伪影的长 GL line 叠层。
[自动启动与 Microduck→Microban 录像](assets/robot-switching.webm)
## 6. 已知限制 / 未验证
- 简化 PD 不是 BAM。Microban 前进会有方向漂移,转向/头关节跟踪存在误差;没有硬件、BAM 或 Python 全轨迹等价保证。
- 没有连续 15 小时耐久试验。20 次切换的平台资源计数不能证明任意使用时长绝无泄漏。
- Docker、实际公网部署、私有 Hugging Face 签名鉴权未独立部署验收;已有同源 `signed()` 行为保留。构建仍有 MuJoCo `module` browser-externalization 提示,真实浏览器运行测试已通过。
- 音频 master `SOUND_DISABLED=true` 保持原状。仿真不等用户音频手势;未启用或验收有声音频。
- 移动端、触屏、手柄、Microban Placo 下蹲、联网/贴纸/庆祝、任意远程 Package、固定底座机械臂、RNN/历史/图像观测不在首期交付。
- 保留 Microban 各资产实际混合许可与来源,并保留 Anton OFL;发布/再分发前仍应复核相应义务。
- 没有自动提交;实施前已有的设计文档修改也一并留在工作区供用户审阅。
## 7. 复现与进一步接入
运行、测试和 `/play/` 构建命令见 [README](../../../README.md)。新增包流程见 [Package authoring](../../robots/package-authoring.md),Microban 坐标/策略/PD 参数详见 [Microban 接入](../../robots/microban.md)。
[验收时源码与资产 SHA-256](assets/verified-inputs.json) 不含生成的 dist、node_modules 或本报告;依赖以锁文件为准。机器可读通过列表和物理数据保留在本目录,不依赖 `/tmp` 测试日志。