Files
VibemakerSandbox/docs/superpowers/specs/2026-10-27-multi-robot-platform-design.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

426 lines
29 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-27
- 状态:用户已确认设计及交互默认值;实施计划已编写,尚未开始代码改造
- 范围:`app/` 浏览器端仿真(MuJoCo WASM + onnxruntime-web + three.js)
- 首期机器人:Microduck(legs / rollers)与 Microban
## 1. 已确认的产品决策
| 项目 | 首期决定 |
|---|---|
| 接入目标 | 首个新增机器人是本地 `microban` 项目,不是 Go2;首期不接入其他机器人 |
| Microban 功能 | 行走 ONNX 策略 + 独立转头;Placo IK 下蹲延后 |
| Microban 仿真精度 | 允许简化电机及传感器模型,以稳定行走为验收,不要求复现 Python/BAM 轨迹 |
| Microduck 回归范围 | 保留核心仿真、legs / rollers、已有技能和摔倒恢复;联机、贴纸、庆祝动画等非核心功能可暂缓 |
| 启动 | 默认 Microduck;加载完成自动运行,不再点击 Waddle in / RESUME |
| 界面 | 只有仿真操作界面;暂停、重置、机器人选择、提示、加载和错误均在同一界面内 |
| 暂停 | Esc 切换暂停 / 继续,不再打开全屏菜单;提供同等界面按钮 |
| 风格与场景 | 按后续用户确认:Microban 保留空地,但与 Microduck 统一 comic 界面风格;所有内置机器人默认背后跟随,C 恢复该视角 |
| 输入 | 首期仅要求键盘;保留鼠标相机操作,手柄 / 触屏适配延后 |
| 资源 | 允许复制 Microban 模型与策略进本仓库,保留来源和许可证;运行时不依赖源项目绝对路径 |
| 工作顺序 | 先确认修订设计,再编写实施计划,之后开始开发 |
第 12 节的交互默认值也已由用户确认,作为首期实现依据。实施拆解见 [实施计划](../plans/2026-10-27-multi-robot-platform-implementation.md)。
## 2. 目标与非目标
### 2.1 首期目标
1. 把机器人相关的模型、关节映射、策略 I/O、命令、技能、渲染与键盘绑定从 Microduck 全局逻辑中分离。
2. 首期通过同一平台加载 Microduck 与 Microban;Microban 差异由 Robot Package 配置和必要的内置钩子表达,不在平台中加入 `if (robot === "microban")` 分支。
3. 对平台已有算子和控制器能表达的机器人,新增机器人只增加 Package,不修改平台核心。新型控制能力可以扩充注册表,不承诺任意未知机器人都能零代码接入。
4. 保持 Microduck 核心行为及原场景体验;统一取消标题 / 暂停菜单,不要求逐像素保留旧的导航外壳。
5. Microban 在空地稳定站立、前后行走、左右转向;转头可独立开关并与行走同时运行。
6. Robot 与 World 分离;切换机器人时能安全切换完整模型、控制器、场景、主题与输入提示。
7. 所有首期功能能用键盘和仿真界面按钮完成;按键提示由当前机器人的真实绑定生成。
### 2.2 长期方向(不是首期交付)
- 浮动 / 固定基座、四足、人形、轮式 / 轮腿、带夹爪机械臂。
- 多输入 ONNX、历史观测、RNN、视觉观测、IK / 遥操作。
- Go2、Panda、tabletop World、手柄 / 触屏、Ghost v2、在线 Package 分享。
- Microban 下蹲、BAM 电机模型、供电与延迟仿真。
### 2.3 非目标
- 首期不做训练流程、服务端仿真、ROS 桥接或硬件控制。
- 不做同一物理世界中的多机器人交互;首期本地单机器人。
- 不实现外部 JS 沙箱或任意远程 hooks 执行。
- 不把简化的浏览器 Microban 仿真描述为实机精度验证或原 Python 仿真的等价实现。
## 3. 代码核对与主要约束
### 3.1 当前平台耦合
| 问题 | 位置 / 影响 |
|---|---|
| 14 关节、61D obs、13D command 等是全局常量 | `app/src/game/constants.js` |
| 仿真、观测、推理、技能、恢复、渲染交互等集中在同一闭包 | `app/src/game/game.js` |
| 观测、技能命令槽、根部高度 / 倾角假定与 Microduck 绑定 | `buildObs()`、`poseIsDead()` 等 |
| 渲染依赖 GLB + kinematics,材质依赖鸭子 mesh 名 | `duck.js`、`variants.js` |
| 输入与界面写死鸭子动作 | `controls/*`、`ui/Hud.jsx`、`ui/TitleMenu.jsx` |
| 启动 / 暂停 / 音频解锁依赖标题菜单 | `App.jsx`、`store.js`、`BiosOverlay.jsx`、`game.js` |
| World 与机器人生命周期混合 | arena、球、地形、道具、相机等 |
### 3.2 Microban 的已核实接口
源项目:`/home/cen/Embodied_Workspace/Mujoco_Projects/microban`。
| 项目 | 当前源实现 |
|---|---|
| 模型 | `src/model/mjcf/robot.xml`,源场景为 `scene.xml`,mesh 位于 `assets/` |
| 关节 | 19 个执行关节:18 个策略控制关节 + `head` |
| 根部 | `trunk`,freejoint 为 `trunk_freejoint` |
| 策略 | `src/agents/walk.onnx` |
| 实际 ONNX 输入 | `obs`,float32,形状 `[1, 63]` |
| 实际 ONNX 输出 | `actions`,float32,形状 `[1, 18]` |
| metadata | `joint_names` / `default_joint_pos` 含 19 项,包含 `head`;`action_scale = 1.0` |
| 策略顺序 | `src/constants.py` 的 `OBSERVATION_DOF_ORDER`,18 项,不含 `head` |
| 观测 | gyro(3) + projected gravity(3) + joint position relative(18) + joint velocity(18) + last action(18) + twist(3) |
| 相位 | 当前 63D 模型不含额外 cos / sin 相位;不能因 Python 支持可选相位而无条件添加 |
| IMU | `angular-velocity` gyro 和 `orientation` framequat 均在 `imu` site;安装四元数为 `(0.5, -0.5, -0.5, 0.5)` |
| 行走周期 | 源调度默认 50 Hz;浏览器首期采用物理 0.005 s、decimation 4 |
| 转头 | `RotateHeadMove`:独立控制 head 的正弦转动,启停带插值;可与 walk 并行 |
| 原仿真执行器 | MJCF 是 torque motor;Python 使用 BAM 生成力矩,不能把关节角直接写进原始 `data.ctrl` |
| 下蹲 | 使用 Placo 多任务 IK,并覆盖 walk;首期不迁移 |
以上模型 I/O 已使用源项目 Python 环境实际读取;这不是浏览器运行或稳定性验证。
关键约束:
1. 模型关节、策略关节、执行器不能混为一张按下标排列的表。必须按名字解析 `qpos`、`qvel`、actuator 地址。
2. metadata 的 19 个名字不代表 19 维 actor 输出。应先以 Package 显式声明的 18 个策略关节筛选 metadata,再按声明顺序组装 default pose。
3. gyro 坐标系和 projected gravity 坐标系分别按源代码验证,不把二者未经核对都替换为根 body 坐标。投影重力须扣除 IMU 安装旋转。
4. ONNX metadata 中的 stiffness / damping 不能自动当作 BAM 的等价 PD 参数;简化执行器需独立标注和验证。
## 4. 总体方案与模块边界
采用**声明式配置 + 可注册算子 + 可选内置钩子**。先实现两种机器人所需的公共能力,不一次性兑现所有长期注册表。
```mermaid
flowchart TD
Package[Robot Package] --> Loader[PackageLoader / SchemaValidator]
World[World Package] --> Composer[SceneComposer]
Loader --> Composer
Composer --> Sim[SimCore]
Keyboard[Keyboard / UI intents] --> Input[InputRouter]
Input --> Skills[SkillManager: primary + overlays]
Input --> Commands[CommandSources]
Sim --> Obs[ObservationPipeline]
Commands --> Obs
Obs --> Controllers[OnnxController / ScriptController]
Skills --> Controllers
Controllers --> Actions[ActionPipeline / Joint ownership]
Actions --> Actuation[Actuation backend]
Actuation --> Sim
Sim --> Render[GLB adapter / RigRenderer]
Package --> Presentation[Robot presentation profile]
```
| 模块 | 职责 |
|---|---|
| `platform/loader/` | Package 路径、资源列表、schema、metadata 与维度校验 |
| `platform/sim/SimCore.js` | model / data 生命周期、命名地址解析、固定步长、reset、资源释放 |
| `platform/sim/SceneComposer.js` | World 与 Robot MJCF 组合、include / mesh 路径解析、仿真参数及执行器适配 |
| `platform/policy/ObservationPipeline.js` | term 拼接、坐标系、默认姿态、lastAction、具名张量 |
| `platform/policy/ActionPipeline.js` | 输出切片、关节映射、目标合成、缩放、限幅、非有限值防护 |
| `platform/policy/controllers/` | ONNX 主策略、脚本 overlay;预留其他控制器 |
| `platform/sim/actuation/` | MuJoCo 原生执行器目标 / 简化 PD 力矩后端,避免混淆目标角和 ctrl |
| `platform/skills/SkillManager.js` | 主技能、并行 overlay、启停过渡、恢复与 reset |
| `platform/commands/` | twist、axes、phase 等,仅先实现实际使用的类型 |
| `platform/input/InputRouter.js` | 键盘 / 按钮 → 语义动作,生成同源提示,处理失焦与输入屏蔽 |
| `platform/render/` | Microduck GLB adapter;Microban 通用 MJCF RigRenderer |
| `platform/runtime/` | 仿真暂停、异步切换事务、加载状态与错误状态 |
| `game/worlds/arena/` | Microduck 原有 arena、球、地形、道具等场景逻辑 |
| `ui/` | 常驻仿真界面、工具栏、加载 / 错误面板、机器人专属样式与提示 |
核心仿真、obs、action、技能模块不依赖 React 或 three。渲染生命周期单独测试。若 MuJoCo / ONNX WASM 的 Node 加载受限,数值集成测试在浏览器同一 WASM 后端执行,不能为了 headless 改写一套不同语义的仿真器。
迁移允许短期保留 Microduck 兼容 adapter,但首期结束时 Microban 必须使用通用流水线,不能另外复制出一个 `game.js`。
## 5. Package 与配置契约
### 5.1 目录
```text
app/public/robots/
microduck-legs/robot.json
microduck-rollers/robot.json
microban/
robot.json
model.xml
assets/...
policies/walk.onnx
LICENSES/...
SOURCE.md
app/public/worlds/
arena/world.json
flat/world.json
app/src/robots/
microduck/ # 内置 hooks、GLB adapter、主题等
microban/ # 如声明式脚本不足,放独立转头 hooks
```
- Microduck 两个 Package 使用 `family: "microduck"`,允许共享模型资源、GLB 与策略,不强制重复复制。
- 首期只从显式内置列表加载三个 Package;无在线 Hub、任意 URL 或上传执行入口要求。
- schema 支持版本号、资源清单与相对路径。MJCF include、meshdir、纹理等依赖必须可枚举加载到 VFS。
- Microban 复制模型实际引用的 mesh 与策略;不复制整个 CAD 工程或 Python 运行环境。
- `SOURCE.md` 记录源项目、源版本 / 文件哈希、复制文件及模型修改。逐文件保留适用许可证与归属;源仓库整体许可摘要不能替代 XML / mesh / 策略的具体许可核对。
### 5.2 首期 schema 的关键字段
| 字段 | 含义 |
|---|---|
| `schema`、`id`、`name`、`family` | 版本和机器人身份 |
| `model`、`assets` | 原始 Robot MJCF 与可枚举资源 |
| `base` | floating / fixed、root body、freejoint、spawn、reset pose |
| `sim` | timestep、decimation |
| `joints.groups` | 模型中具名关节组,例如 `policy` 和 `head` |
| `joints.defaults` | 所有需要初始化的关节;可通过指定策略 metadata 按名字填充 |
| `observations` | 具名输入、term 顺序、关节组、坐标系、scale / clip |
| `actions` | 输出名、切片、目标关节组、scale、offset、限幅 |
| `actuation` | 原生执行器或简化 PD 后端及参数、力矩限制;与策略输出语义分离 |
| `commands` | 命令布局、数值范围、平滑和每个技能的可见性 |
| `skills` | 主技能和 overlay、控制器、关节所有权、启停过渡 |
| `termination` | 跌倒 / 非有限值检测及恢复或 reset 行为 |
| `input` | 语义动作绑定、标签、提示分组 |
| `render` | glb / mjcf_visual、visual group、材质、相机 |
| `presentation` | 默认 World、主题、机器人专属面板 |
| `hooks`、`license` | 内置扩展标识和资产许可说明 |
首期 schema 只接受已实现能力;未来字段不能被静默忽略或伪装成已支持。
### 5.3 Microban 配置的核心数据
策略关节顺序必须显式固定为:
```text
right_shoulder_pitch, right_shoulder_roll, right_elbow,
right_hip_yaw, right_hip_roll, right_hip_pitch, right_knee,
right_ankle_pitch, right_ankle_roll,
left_shoulder_pitch, left_shoulder_roll, left_elbow,
left_hip_yaw, left_hip_roll, left_hip_pitch, left_knee,
left_ankle_pitch, left_ankle_roll
```
- `policy` group 是以上 18 个关节;`head` group 只有 `head`。
- `obs` 依次为 gyro、projected gravity、policy joint position relative、policy joint velocity、policy last action、3D twist,总计 63 维。
- actor 的 `actions` 是 18 维,按 policy group 映射为 `default + action * 1.0` 的关节目标。
- head 的初始值 / 中立值为 0,不参加 actor lastAction 或策略 obs。
- 默认 spawn 高度参考源仿真的 0.165 m;最终以足底不穿地和启动稳定性验证为准,配置必须区分源中立姿态和策略参考姿态。
- 保留源项目速度范围作为参考,不默认以最大速度驱动;首期默认键盘速度可以降低,实际验证通过的范围写进 Package 和验收记录。
### 5.4 ONNX 校验
1. 按具名输入 / 输出绑定;只有单输入时可省略显式 input,输出仍记录实际采用的名称。
2. 对比实际 tensor dtype、shape 和 term size;错误列出每项大小及期望 / 实际维度。
3. metadata 按关节名解析:显式 group 选取所需项,允许 metadata 包含其他模型关节;缺失关节、重复名字、names / defaults 长度不一致或配置冲突时报错。
4. 不因 metadata 的 `joint_names` 长度自动决定 action 维度,也不自动启用相位或把所有 metadata gains 应用于执行器。
5. 冒烟推理检查输出形状和有限性,再使用合法站立观测测试;全零 / 噪声探针可以辅助诊断,但“输出对任意探针不变”不作为所有控制器的通用拒绝条件。
6. 切换和 reset 清零策略 lastAction;head overlay 不污染它。
7. 首期不实现 RNN、多相机或历史缓冲;后续按需求扩展,不阻塞本期。
## 6. 控制、技能与仿真语义
### 6.1 主技能 + 并行 overlay
原文单一 `active` 技能不足以表达 Microban。调整为:
- 一个互斥主技能槽 `primary`:walk、Microduck kick / sit / groundpick / recovery 等按原有规则切换。
- 零到多个 `overlay`:首期只需 head。每个控制器声明 `owns` 关节组。
- 不相交关节组可并行;重叠所有权在加载时拒绝,不使用依赖遍历顺序的“最后写入覆盖”。特殊 override 留待后续明确设计。
- 所有控制器先生成目标,再统一校验、合成和写入执行器。
- head overlay 启停不重启 walk,不清空 walk lastAction,不改变行走命令。
- 主技能切换 / reset 执行相应状态清理;Microduck 迁移不得无条件加入与旧实现不同的动作清零或混合规则。
- 暂停冻结物理时间、策略、脚本计时和技能计时;允许相机操作。恢复不追赶暂停期间的墙钟时间。
Microban head 参考源 `RotateHeadMove`:0.35 Hz、幅值 ±π/4、启停 0.5 s 插值;使用仿真时间,关闭后平滑回到 0。若模型限位更窄,按关节 range 限幅。
### 6.2 Microban 简化执行器
原模型 `<motor>` 接受力矩,不接受关节角。首期提供通用的简化关节 PD 后端:
```text
tau = clamp(kp * (target - q) - kd * dq, -torque_limit, torque_limit)
```
- 每个物理子步读取当前位置 / 速度并更新力矩,策略目标按控制周期保持。
- 增益、力矩上限、必要的关节参数适配由 Package 声明并记录来源;不能直接将 metadata stiffness 视为已验证值。
- 避免在原 MJCF 阻尼与 PD 后端之间无意叠加;任何覆盖保存在复制模型 / 配置与来源说明中。
- 不复现 BAM 的反电动势、摩擦、电压下降、电流限制或延迟;界面 / 说明明确为 simplified actuation。
- 若简化后无法通过稳定行走验收,先检查观测坐标系、姿态、关节映射及参数,不能偷偷改成 qpos 动画或关闭重力以宣称通过。
Microduck 保持现有执行器语义,不为了共用 Microban 后端而改变其控制规律。
### 6.3 安全与重置
- 非有限动作不进入 ctrl;物理非有限状态停止本轮并 reset / 报错,防止无限重置循环。
- Microduck 保持原摔倒与恢复流程。
- Microban 首期无 stand-up 策略,跌倒后进入明确 fallen 状态、停止策略更新并提示手动重置;保持安全目标 / 力矩限制,不无限复用异常输出。
- 不能在验收中用自动 reset 掩盖跌倒。
- reset 清理模型状态、控制器内部状态、lastAction、overlay、命令与累积时间;不得沿用切换前按住的方向键。
## 7. 场景、渲染与机器人切换
### 7.1 World 与主题
| 机器人 | 默认 World | 显示与体验 |
|---|---|---|
| Microduck legs / rollers | `arena` | 原 arena、球、地形、GLB 外观、配色、相机与核心玩法;保留原机器人专属 HUD 视觉风格 |
| Microban | 默认 `arena` | 按追加确认,所有机器人默认使用 4.5 × 4.5 m 有界场地(原长宽各扩大 50%,墙高 .25 m、厚 .05 m);内部平地、同款网格/CRT、背后跟随与 C 恢复;新包不指定 world 时同样采用此默认值 |
- 统一的暂停 / 重置 / 机器人选择 / 按键提示属于平台,主题可以变化,但不重新引入标题 / RESUME / BIOS 页面。
- Microduck 的 CRT / halftone 等原有视觉效果限于其 presentation profile;不让这些效果污染 Microban 默认界面。
- 联机、贴纸、庆祝动画可不进入首期。其余 Microduck 音效和机器人交互在可用时保留,详见音频解锁约束。
- 首期不要求任意 Robot / World 自由组合;先验证 Microduck + arena、Microban + flat,底层保持解耦。
- SceneComposer 需正确处理引用、default class 和资源路径。首期单机器人不强制全局加 `r0/` 前缀;若实施前缀,必须完整重写所有 MJCF 引用并做等价验证,不能做简单字符串替换。
### 7.2 渲染
- Microduck 继续 GLB + kinematics,经 adapter / hooks 保留外观、材质与嘴巴等特殊逻辑。
- Microban 使用编译模型中的 mesh / geom / material 建立 three 对象,默认 visual group 2;同时渲染 World 的可见对象。
- 优先使用同一完整编译 model / data 渲染与仿真:visual geom 非碰撞,不必为去 visual 再维护一个姿态不同步的模型。
- 每帧从该 data 的 geom 位姿同步;禁止拿 collision-only model 的索引读取另一个 visual model。
- 如性能测试确需独立渲染模型,应另行设计按具名 joint / body 同步与映射测试,不能默认两者数组顺序相同。
- mesh、材质、模型、策略和监听器随运行实例释放;共享缓存有明确所有权。
### 7.3 切换事务
1. 暂停旧实例控制,清空键盘 held 状态与命令;禁用重入切换。
2. 加载 / 校验新 Package、World、model、策略和渲染资源,显示进度。
3. 用请求代号忽略过期异步结果;在途推理不得再写入已释放模型。
4. 成功后一次性替换仿真、渲染、相机、主题、工具栏、提示,再释放旧实例。
5. 失败则保留或恢复旧机器人,显示错误及重试入口;初次加载失败时留在仿真外壳内显示错误。
6. 新机器人从初始化姿态开始,不带入旧 qpos / 时间 / 控制器状态;保留当前明确的暂停状态。
7. 本会话中记住 Microduck 的颜色与 legs / rollers 选择;切回时恢复这些设置和原场景,但重置物理状态。默认首次进入 legs。
## 8. 单一仿真界面与输入
### 8.1 界面结构
- 主体:仿真 canvas。
- 常驻工具栏:机器人选择、暂停 / 继续、重置;Microduck 另有原配色 / legs-rollers 控件。
- 状态区域:当前机器人 / 技能、loading、paused、fallen、error;提供诊断明细和重试。
- 可折叠按键提示面板:默认展开,避免遮挡主要操作区域;切机器人时即时更新。
- 保留已有基础遥测(例如 FPS、控制 Hz、速度),首期不新增完整调参 / 日志工作台。
- 不再挂载 `TitleMenu` / `MenuDuck`,不加载其专属预览资源;BIOS 动画退出用户流程,原 boot log 可作为错误明细数据源。
- 不通过 `?boot=1` 或伪造旧 `entered` 状态来永久绕过旧流程;启动、运行、暂停、切换、错误为显式生命周期。
### 8.2 键盘
| 动作 | 默认绑定 |
|---|---|
| 前进 / 后退 / 左转 / 右转 | 方向键及物理 WASD,默认不绑定侧移 |
| 暂停 / 继续 | Esc,及工具栏按钮 |
| 重置当前机器人 | Space,及工具栏按钮 |
| Microban 开关独立转头 | H |
| Microduck 技能 / 相机 / legs-rollers | 保持当前键盘绑定;提示覆盖实际支持项 |
| 鼠标相机 | 保留拖动环绕、滚轮缩放及当前适用的相机切换 |
- 不照搬 Microban Python 的 `R reset` / `Q quit` 等冲突快捷键,浏览器使用统一平台绑定。
- 输入 binding 和提示标签来自同一配置;仅展示当前机器人拥有的动作,不向 Microban 展示 kick / groundpick。
- 保留物理 `KeyboardEvent.code` 与键盘布局标签解析,避免显示按键和实际触发位置不一致。
- 忽略输入框 / select / 可编辑区域内的机器人快捷键;按钮焦点下 Space 不应同时触发控件和机器人 reset。
- 失焦、暂停、reset、切换时清空按键和命令;恢复后需重新按键,不能残留移动。
- 手柄 / 触屏首期不验收,可保留旧模块但不作为首期主流程依赖。
### 8.3 自动启动与音频
去掉进入按钮后不再有天然音频解锁手势:
- 仿真加载完成后立即运行,不因音频受限而停在等待状态。
- 在首次有效点击 / 按键手势中恢复 AudioContext;之前保持静音或排队策略,不抛出未处理异常。
- 保留静音开关;Microban 不自动播放鸭子叫声或环境音。
- 自动启动与“浏览器允许立即有声”是两件事,不能依赖更改浏览器策略规避。
## 9. 首期算子与扩展规则
只实现迁移实际需要的集合:
- 观测:gyro / body angular velocity(明确 frame)、projected gravity、joint position relative、joint velocity、lastAction、command;Microduck 特殊项可由其 hooks 过渡。
- 动作:具名关节位置目标与现有 Microduck 动作路径;简化 PD 后端独立于动作 term。
- 命令:twist、Microduck 的 head / posture / phase 等实际命令槽。
- 控制器:ONNX、独立脚本 overlay / hold。
- 终止:非有限值、机器人配置的倾角 / 高度、技能时间条件。
term 提供 size / init / write 或 apply 接口,使用预分配缓冲。ctx 只暴露需要的 model / data、解析地址、命令、仿真 dt 与控制器状态,不允许每个 term 自行推进物理时间。
内置 hooks 通过编译期注册表加载,用于 Microduck 特殊渲染 / 音效、必要的自定义 term;不是可信沙箱。首期不从 Package URL 动态执行外部 JS。
## 10. 分阶段迁移与验收门槛
下表为设计阶段的里程碑,不代替后续逐文件、逐测试的实施计划。
| 阶段 | 内容 | 验收门槛 |
|---|---|---|
| P0 基线与可行性验证 | 记录 Microduck 同后端固定输入轨迹、关键技能流程;用真实 Microban ONNX / MJCF 验证 WASM I/O、映射、观测和简化执行器 | 基线可重复;暴露运行环境限制;先取得可稳定站立 / 行走的最小证据,不只看模型显示 |
| P1 仿真界面生命周期 | 去标题 / BIOS 流程;同界面启动、暂停、重置、加载 / 错误与按键提示;音频首手势解锁 | 默认 Microduck 自动运行;Esc 无菜单;核心体验基线不回归 |
| P2 平台核心与 Microduck Package | 抽离 SimCore、obs / action、命令、技能、输入;配置化 legs / rollers 与 presentation | Microduck 核心回归通过;不把所有长期能力塞进本阶段 |
| P3 World / 通用渲染 / 切换 | arena 与 flat 解耦;MJCF RigRenderer;加载事务、主题及资源释放 | 两类场景渲染正确;切换 / 回滚不残留输入、主题或过期回调 |
| P4 Microban 完整接入 | 复制资产 / 许可,63D obs、18D actor、PD 后端、head overlay | 仅 Package / 内置扩展表达差异;稳定行走并可同时转头 |
| P5 首期收尾 | 自动化回归、浏览器手动验收、资源来源与简化限制说明 | 本文首期验收全部满足,列出暂缓功能,不以长期路线阻塞首期 |
P0 的 Microban 小型验证可以是临时验证入口,不形成第二套长期 runtime。若稳定行走不可达,应先报告参数 / 建模问题并调整方案,不在大规模拆分后才发现控制不可行。
## 11. 测试与验收
### 11.1 自动化
- schema 正反例:不存在的 body / joint / actuator / sensor、非法 group、重叠控制权、错误资源路径和 I/O 维度必须明确拒绝。
- metadata 专项:19 项 metadata 正确筛选成 18D policy group;head 缺省值正确,不增加 obs / actions 长度。
- 观测数值:63D 拼接逐项对照源 `build_observation()`;测试 IMU 安装旋转、body gravity、关节重排和 reference pose;不只测长度。
- 执行器:关节角目标不能直接写给 torque motor;PD 子步更新、限幅、非有限值防护。
- 技能:walk 与 head 并行;启停 head 不改变 walk 状态;暂停冻结 phase;reset 全状态清理。
- 生命周期:失败回滚、快速重复切换、在途异步推理、资源释放、失焦、暂停后重新输入。
- UI:默认 Microduck 自动进入仿真;无标题 / RESUME / BIOS 动画;切换后提示和主题匹配。
- Microduck 同一后端 / 同一版本固定输入数值回归;优先逐位比较。确有浮点差异时先定位原因,再记录合理容差;不能用大容差掩盖行为变化。
- Node 与浏览器 / 不同 ONNX 后端不要求逐位相同,跨后端比较不能代替目标浏览器回归。
### 11.2 Microban 稳定行走验收协议
在桌面浏览器、flat、正常重力、无外力、50 Hz 控制、确定初始状态下:
1. 零命令站立 10 s。
2. 前进 20 s、后退 10 s、原地左右转各 10 s;段间零命令 3 s。
3. 前进行走中开启 head 10 s,再关闭;头部确有转动并平滑回正,行走策略未被重启。
4. 至少三次从重置状态执行上述序列,记录版本、浏览器、速度、PD 参数、姿态 / 倾角、控制 Hz、实际位移与转向。
5. 全程不触发配置的跌倒条件、不出现非有限状态、不发生自动重置、不持续依赖关节 / 力矩限幅卡住姿态;命令方向和实际运动方向匹配。
6. 仅测试低速站立而不产生实际位移,不算“稳定行走”。允许降低默认速度,但通过的速度范围必须明确记录。
这是实现后的验收要求,尚未执行,也不保证当前简化参数能直接通过。
### 11.3 Microduck 手动回归
- 默认 legs、外观 / 配色、arena / 球 / 地形、鼠标相机及原键盘控制。
- legs / rollers 切换、已有 walk / sit / kick / roll / groundpick 等适用技能、跌倒恢复、鼠标物理交互。
- 切到 Microban 再切回:恢复原主题、World、相机配置、颜色和 locomotion 选择;物理从安全初态开始。
- 首次手势后的音效与静音开关正常;无手势时仍可自动仿真。
- 明确记录未恢复的联机、贴纸、庆祝动画;这些不作为首期失败项。
## 12. 已确认的交互默认值
用户已确认第 1 节范围及以下交互默认值:
1. Microban 转头采用原项目的 H 开关正弦转头,不做手动头部角度遥操作。
2. 提示面板默认展开、可折叠;机器人选择放在同一仿真工具栏。
3. 切换机器人重置物理状态,只保留会话内 Microduck 颜色 / legs-rollers 设置;不保存并恢复完整仿真快照。
4. Microban 跌倒后提示手动重置,不伪造不存在的自动起身技能。
5. “Microduck 和原来一样”保留其原场景、渲染风格与核心玩法,但统一取消旧菜单 / BIOS;非核心功能按已确认范围暂缓。
设计已确认,下一步按独立实施计划开展代码改造;本设计文档本身不表示任何功能已实现或验收通过。
## 13. 风险与后续路线
| 风险 | 处理 |
|---|---|
| 简化执行器下策略不稳定 | P0 先验证;严查 frame、顺序、姿态、增益与 torque limit;必要时重新评估精度范围 |
| Microduck 拆分回归 | 同后端基线、分阶段 adapter、关键技能手动验收,不要求一口气重写 |
| MJCF 资源 / 渲染差异 | 基于完整 model / data 与实际资源依赖验证;不假定不同编译模型索引一致 |
| 去入口按钮导致音频受限 | 仿真自动启动、音频首次手势解锁,互不阻塞 |
| 异步切换泄漏或旧推理写入新模型 | 事务、请求代号、状态隔离、dispose 测试 |
| 复制资产许可不统一 | 保留文件级声明、记录来源与修改;未明确的许可作为交付前核对项 |
| 过度泛化拖慢首期 | 只实现两种机器人真实需要的能力,保留接口而不提前实现所有控制器 |
后续独立阶段再讨论:Microban 下蹲 / IK、多任务覆盖、BAM / 延迟建模、Go2 / Panda、视觉 / 历史 / RNN、手柄 / 触屏、通用 Ghost 和远程 Package。它们不属于本次首期交付或验收。