docs: add multi-robot platform design spec

This commit is contained in:
2026-10-27 18:00:14 +08:00
parent 2c5d64abaa
commit 8d74cdbf26
@@ -0,0 +1,376 @@
# 多机器人平台改造设计文档
- 日期:2026-10-27
- 状态:草案,待评审
- 范围:`app/` 浏览器端仿真(MuJoCo WASM + onnxruntime-web + three.js)
## 1. 目标与非目标
### 目标
1. 新增一个机器人时**不改平台代码**:提交一个 Robot Package(配置 + MJCF + 资源 + 策略)就能加载。
2. 支持**结构差异很大**的机器人:
- 浮动基座:双足(Microduck)、四足(Go2)、人形(G1)、轮式 / 轮腿(Microduck rollers)
- 固定基座:机械臂(Panda),也包括带夹爪的
- 观测可以是本体感知,也可以包含相机图像、历史帧
- 控制器可以是 ONNX 策略、脚本或遥操作(直接给关节 / 末端目标)
3. Microduck 现有体验(legs/rollers、kick/sit/roll/groundpick、摔倒恢复、ghost 联机、音效)**行为不变**,作为第一个 Robot Package 迁移过来。
4. 场景(World)和机器人解耦:arena、桌面、空地可以和不同机器人组合。
### 非目标(本期不做)
- 训练流程、服务端仿真、ROS 桥接
- 多个机器人在同一个物理世界里交互(ghost 仍然只做渲染层面的同步)
- 在线 IK 求解器以外的高级运动规划
## 2. 现状问题
| 问题 | 位置 |
|---|---|
| 机器人参数是全局常量(14 关节、61D obs、13D cmd、decimation、速度上限) | `game/constants.js` |
| `game.js` 2300 行,物理、观测、推理、技能状态机、摔倒恢复、相机、抓取、音效、联机全在一个闭包里 | `game/game.js` |
| 观测拼接写死(L741-790),技能对命令槽的语义用 `if (mode === ...)` 分支实现 | `buildObs()` |
| 摔倒判定写死成 trunk + `qpos[2]`,固定基座机器人没有这个概念 | `poseIsDead()` |
| 渲染依赖离线生成的 `kinematics.json` + GLB,不能直接吃 MJCF | `game/duck.js` |
| 材质按 Microduck 的 STL 文件名映射 | `game/variants.js` |
| 联机数据包固定为 14 个关节 + variant | `game/ghosts.js` |
| 输入直接绑到 kick/sit 等鸭子专属动作 | `game/controls/*`、`ui/Hud.jsx` |
| legs/rollers 切换是特例代码 | `ensureRollers / setLoco` |
已有可沿用的部分:`custom-policy.js` 的 manifest(`kind`、`slot`、`obs_len`、`robot.model`)和策略冒烟测试流程。
## 3. 方案选择
| 方案 | 说明 | 结论 |
|---|---|---|
| A. 纯配置化 | 常量移进 JSON | 处理不了相机观测、机械臂 IK、鸭子嘴巴这类异构需求 ✗ |
| B. 纯代码适配器 | 每个机器人写一个 JS 类 | 灵活,但每个机器人都要写代码,配置无法校验,也难以在线分享 ✗ |
| **C. 声明式配置 + 可注册算子 + 可选钩子** | 大多数机器人只写 `robot.json`;平台提供可扩展的 Term 注册表;特殊逻辑放进 `hooks.js` | **采用** ✓ |
C 的关键是把"异构"拆成**有限个可组合的维度**(基座类型、观测项、动作项、命令源、控制器、终止条件、渲染),每个维度由注册表提供内置实现,钩子负责兜底。
## 4. 总体架构
```mermaid
flowchart TD
subgraph Package["Robot Package (robots/<id>/)"]
RJ["robot.json"]
MJ["model.xml + meshes"]
PO["policies/*.onnx"]
HK["hooks.js (可选)"]
end
subgraph World["World Package (worlds/<id>/)"]
WJ["world.json + xml 片段"]
end
Loader["PackageLoader + SchemaValidator"] --> Composer["SceneComposer (拼 MJCF)"]
Package --> Loader
World --> Loader
Composer --> Sim["SimCore (mujoco model/data, step)"]
Sim --> Obs["ObservationPipeline (Term 注册表)"]
Cmd["CommandSources (twist / ee-pose / phase / joint)"] --> Obs
Obs --> Ctrl["Controller (onnx / script / teleop)"]
Ctrl --> Act["ActionPipeline (Term 注册表)"]
Act --> Sim
FSM["SkillManager (技能状态机 + 终止/恢复)"] --> Ctrl
FSM --> Cmd
Input["InputRouter (键盘/手柄/触屏 → 语义动作)"] --> FSM
Input --> Cmd
Sim --> Render["RigRenderer (读 MJCF visual geom)"]
Sim --> Net["GhostSync (通用 qpos 包)"]
HK -.钩子.-> Obs
HK -.钩子.-> Act
HK -.钩子.-> FSM
HK -.钩子.-> Render
```
### 4.1 模块划分(拆解 `game.js`)
| 模块 | 职责 | 依赖 |
|---|---|---|
| `platform/loader/` | 拉取 Package,校验 schema,解析相对路径 | 无 |
| `platform/sim/SimCore.js` | 拼 MJCF、写 VFS、编译、`step(n)`、reset、keyframe、名字到地址的解析 | mujoco |
| `platform/sim/SceneComposer.js` | Robot MJCF 与 World 片段合并(前缀命名空间、去 visual 等),沿用 `buildPhysicsXml` 现有逻辑 | SimCore |
| `platform/policy/ObservationPipeline.js` | 按配置调用 obs term,维护历史缓冲,输出多个具名张量 | Term 注册表 |
| `platform/policy/ActionPipeline.js` | 把控制器输出映射到 `ctrl` / `xfrc` / qpos,带缩放、限幅、NaN 防护 | Term 注册表 |
| `platform/policy/controllers/` | `OnnxController`、`ScriptController`、`TeleopController` | ort |
| `platform/skills/SkillManager.js` | 技能状态机:持续 / 一次性 / 切换,超时,终止条件与恢复技能 | 以上 |
| `platform/commands/` | 命令源:`twist`、`phase`、`ee_pose`、`joint_targets`、`gripper`、`constant`、`script` | InputRouter |
| `platform/render/RigRenderer.js` | 根据 MJCF 的 geom/mesh/material 建 three 场景,每帧从 `xpos/xquat` 同步 | three |
| `platform/input/InputRouter.js` | 设备 → 语义动作(`move`、`trigger:<skill>`、`ee_delta`…),绑定由机器人声明 | controls/* |
| `platform/net/GhostSync.js` | 通用位姿包,按 robotId 分发渲染 | trystero |
| `platform/hooks.js` | 钩子生命周期与沙箱 | 全部 |
| `game/`(保留) | 玩法层:arena、球、道具、ceremony、音效、贴纸 | platform |
每个模块都要能单独测试:`SimCore`、`ObservationPipeline`、`ActionPipeline`、`SkillManager` 不依赖 three 和 React,可以在 Node 中用 `node --test` 跑。
## 5. Robot Package 规范
### 5.1 目录
```
app/public/robots/<id>/
robot.json
model.xml # 完整 MJCF(含 visual geom)
assets/… # mesh / texture
policies/*.onnx
hooks.js # 可选,ES module
thumbnail.webp # 机器人选择界面用
```
### 5.2 `robot.json`(schema v1)
下面以 Microduck legs 为例,同时注释其他机器人的不同写法:
```jsonc
{
"schema": 1,
"id": "microduck-legs",
"name": "Microduck",
"family": "microduck", // 同一家族内可快速切换(legs <-> rollers)
"model": "model.xml",
"base": {
"type": "floating", // "floating" | "fixed"
"root_body": "trunk_base",
"spawn": { "pos": [0, 0, 0.13], "yaw": 0 },
"keyframe": "stand" // 不存在时用 joints[].default 生成
},
"sim": { "timestep": 0.005, "decimation": 4 },
// 受控关节;顺序 = 策略的关节顺序(不要求与 actuator 顺序一致)
"joints": {
"names": ["left_hip_yaw", "...", "right_ankle"],
"default": [0, -0.0873, "..."],
"source": "onnx_metadata" // 可选:从 ONNX metadata 自动读取 names/default
},
"passive_joints": ["wheel_*"], // 只渲染不控制(rollers 的轮子)
"observations": {
"policy": { // 组名 = ONNX 输入名(或用 input 字段显式映射)
"terms": [
{ "type": "imu_ang_vel", "sensor": "gyro" },
{ "type": "projected_gravity", "body": "trunk_base" },
{ "type": "joint_pos_rel" },
{ "type": "joint_vel" },
{ "type": "last_action" },
{ "type": "command", "size": 13 }
],
"history": 1,
"flatten": true
}
// 相机机器人示例:
// "image": { "terms": [{ "type": "camera_rgb", "camera": "wrist", "size": [64, 64] }] }
},
"actions": [
{ "type": "joint_position", "joints": "all", "scale": 1.0, "offset": "default" }
// 轮式:{ "type": "joint_velocity", "joints": ["wheel_l","wheel_r"], "scale": 10 }
// 机械臂:{ "type": "joint_position_delta", "joints": "arm", "scale": 0.05, "clip": "range" }
// 夹爪:{ "type": "binary_gripper", "actuator": "gripper", "open": 0.04, "close": 0 }
],
"commands": {
"twist": { "type": "twist", "slots": [0, 1, 2],
"limits": { "vx": [-0.2, 0.25], "vy": [0, 0], "wz": [-1, 1] } },
"head": { "type": "axes", "slots": [3, 4, 5, 6], "smoothing": 0.2 },
"phase": { "type": "phase", "slots": [0, 1] }
// 机械臂:{ "type": "ee_pose", "site": "ee", "frame": "base", "gizmo": true }
},
"skills": [
{ "id": "walk", "kind": "perpetual", "default": true,
"controller": { "type": "onnx", "policy": "policies/walk.onnx" },
"commands": ["twist", "head"] },
{ "id": "kick_left", "kind": "episodic", "duration": 0.5,
"controller": { "type": "onnx", "policy": "policies/kick_left.onnx" },
"commands": [], "input": "trigger:kick_left" },
{ "id": "groundpick", "kind": "episodic",
"controller": { "type": "onnx", "policy": "policies/ground_pick.onnx" },
"commands": [{ "use": "phase", "period": 4.0, "end_phase": 0.7 }],
"input": "trigger:groundpick" },
{ "id": "stand_up", "kind": "recovery",
"controller": { "type": "onnx", "policy": "policies/stand.onnx" } }
// 机械臂无策略:{ "id": "teleop", "kind": "perpetual",
// "controller": { "type": "ik", "site": "ee", "command": "ee_pose" } }
],
"termination": { // 固定基座可以省略
"fall": { "type": "tilt", "body": "trunk_base", "max_deg": 60, "min_height": 0.02 },
"on_fall": "stand_up", // 或 "reset"
"explode": "reset" // NaN 时立即重置(平台默认行为)
},
"input": {
"profile": "locomotion", // locomotion | manipulator | custom
"bindings": { // 不写就用 profile 的默认绑定
"trigger:kick_left": ["key:Q", "pad:LB"],
"trigger:groundpick": ["key:G", "pad:A"]
}
},
"render": {
"source": "mjcf_visual", // 或 "glb"(沿用预烘焙 GLB 以获得更好效果)
"glb": null,
"materials": "materials.json", // 可选:mesh/geom 名 → 材质 slot
"variants": "variants.json", // 可选:配色方案
"camera": { "follow": "trunk_base", "distance": 0.8 }
},
"net": { "sync": "qpos", "hz": 15 },
"hooks": "hooks.js"
}
```
### 5.3 内置 Term 注册表(首批)
| 类别 | 内置类型 |
|---|---|
| 观测 | `imu_ang_vel`、`imu_lin_acc`、`projected_gravity`、`base_lin_vel`、`base_ang_vel`、`base_height`、`joint_pos`、`joint_pos_rel`、`joint_vel`、`last_action`、`command`、`body_pos`(相对某 body/site)、`site_pose`、`touch`(MJCF touch 传感器)、`sensor`(任意 MJCF sensor)、`camera_rgb`、`camera_depth`、`phase_clock`、`constant` |
| 动作 | `joint_position`、`joint_position_delta`、`joint_velocity`、`joint_effort`、`binary_gripper`、`diff_drive`(`v, ω` → 轮速) |
| 命令 | `twist`、`axes`、`phase`、`ee_pose`、`joint_targets`、`gripper`、`constant`、`script` |
| 控制器 | `onnx`、`script`(关键帧时间线)、`ik`(阻尼最小二乘,基于 `mj_jacSite`)、`hold`(保持当前姿态) |
| 终止 | `tilt`、`height`、`nan`、`timeout`、`joint_limit` |
每个 term 统一实现:
```js
// 观测 term
{ type, size(spec, ctx) -> number, init(spec, ctx), write(out, offset, ctx) }
// 动作 term
{ type, size(spec, ctx) -> number, init(spec, ctx), apply(actionSlice, ctx) }
```
`ctx` 提供 `model`、`data`、已解析的地址表、`lastAction`、命令缓冲和 `dt`。所有 term 每步零分配(预分配 `Float32Array`)。
### 5.4 ONNX 对接规则
1. **多输入**:obs 组名与 `session.inputNames` 匹配;不匹配时用 `"input": "<name>"` 显式指定。只有一个输入时直接使用该输入。
2. **多输出**:默认取第一个输出;可以用 `"output": "<name>"` 指定。可以把 actor 输出拆给多个动作 term(依次切片)。
3. **形状校验**:加载时对比 term 的 size 总和与 ONNX 输入维度,不一致就拒绝加载并给出逐项明细。
4. **metadata 自动填充**:如果 ONNX 带 `joint_names`、`default_joint_pos`、`action_scale`(mjlab 导出格式),`"source": "onnx_metadata"` 时自动读入,与配置冲突时报错。
5. **冒烟测试**:沿用 `custom-policy.js` 的流程(全零输入 + 两次噪声输入,输出必须有限且不恒定)。
6. **有状态策略(RNN)**:支持 `"recurrent": { "state_inputs": [...], "state_outputs": [...] }`,平台负责回填隐藏状态,reset 时清零。
## 6. 关键设计点
### 6.1 固定基座与浮动基座
| 方面 | floating | fixed |
|---|---|---|
| 出生 | 设 freejoint qpos | 修改 base body 的 `pos` 属性 |
| 摔倒检测 | 按 `termination` 配置 | 默认没有 |
| 相机 | 跟随 `root_body` | 环绕 base 的固定相机 |
| 鼠标抓取 | 对任意 body 施加 `xfrc_applied` | 同左;另外提供 `ee_pose` gizmo 拖拽 |
| 联机包 | 根位姿 + 关节 | 只发关节 |
### 6.2 SkillManager(取代 `mode` / `setMode` / `recovery` 等分支)
- 状态:`active`(当前技能)、`pending`、`recovering`。
- `perpetual`:一直运行,直到切到别的技能。
- `episodic`:运行 `duration` 秒,或者 phase 走到 `end_phase`,然后回到默认技能;可选 `cooldown`。
- `toggle`:同一按键在两个状态之间切换(sit/stand 用 `command` 槽承载标志位)。
- `recovery`:`termination.fall` 触发后先 `settle`(冻结 ctrl,可配置时长),再运行恢复技能,直到 `upright` 条件满足。
- 技能之间切换时:清零 `lastAction`、重置 RNN 状态,并可配置是否插值过渡(`blend_s`)。
- **命令可见性**:每个技能声明自己使用哪些命令源,没声明的槽置零。这样就把 `gpZero` 这类分支换成了配置(例如 groundpick 不看 head 命令)。
### 6.3 渲染:直接读 MJCF
- 编译后的 `model` 已经包含 `geom_type/size/rgba/dataid`、`mesh_vert/face` 和 `mat_rgba`,直接用这些数据生成 `THREE.BufferGeometry`,不需要再次解析 STL。
- 每帧用 `data.geom_xpos / geom_xmat` 更新**所有 visual geom**(按 `geom_group` 过滤;默认 group 2 = visual,可配置)。
- 物理编译保持现在的做法:去掉 visual geom,用 collision-only 模型(`SceneComposer` 生成两个版本:物理用的和渲染用的)。如果性能允许,也可以用同一个模型,渲染时只读 visual geom 的位姿。
- `render.source = "glb"` 时继续支持现有的 GLB + kinematics 管线(Microduck 的高质量外观、嘴巴枢轴),由 hooks 接管。
- 材质优先级:`materials.json` 覆盖 > MJCF material/rgba > 平台默认。`variants.js` 改成通用的"slot → 材质"机制,Microduck 的配色表放进它自己的 package。
### 6.4 相机观测
- 使用 MJCF `<camera>`:每个控制步从 `data.cam_xpos / cam_xmat` 取相机位姿,用 three.js 离屏 `WebGLRenderTarget` 渲染一张低分辨率图(如 64×64),`readPixels` 后写入张量(支持 `rgb`、`gray`、`depth`,可配置归一化和 NCHW/NHWC 布局)。
- 只有带 `camera_*` term 的机器人才启用;`readPixels` 有同步开销,`camera_*` term 支持 `"hz"` 降频(例如 10 Hz,其余步复用上一帧)。
- 风险:渲染和物理画面的一致性、移动端性能。属于第 6 阶段,不阻塞前面的工作。
### 6.5 场景(World)组合
- `world.json`:XML 片段(地面、墙、道具、光照)、出生点列表、适用条件(`"supports": { "base": ["floating"], "max_size": 1.0 }`)。
- 内置三个 World:`arena`(现有 3×3 场地 + 球 + 地形起伏)、`tabletop`(桌子 + 几个可抓取的方块,给机械臂用)、`flat`(空地,调试用)。
- 合并时机器人元素统一加前缀 `r0/`,避免和 World 重名(同时给将来多机器人留余地)。
- 球、arena 墙、地形起伏这类逻辑从 `game.js` 移到 `game/worlds/arena/`。
### 6.6 输入路由
- 语义动作:`move`(2D 轴 + 转向)、`look`(头/相机轴)、`ee_translate`、`ee_rotate`、`gripper`、`trigger:<skill>`、`toggle:<skill>`、`reset`、`switch_family`。
- `profile` 提供默认绑定:
- `locomotion`:WASD/摇杆 → `move`
- `manipulator`:WASD+QE → `ee_translate`,右摇杆 → `ee_rotate`,空格 → `gripper`
- HUD 按钮、触屏按钮和提示文字都从 `skills[].input` 自动生成,`Hud.jsx` 中写死的 kick/sit 按钮全部去掉。
### 6.7 钩子(hooks.js)
```js
export default {
registerTerms(registry) {}, // 注册自定义 obs/action/command term
onLoad(ctx) {}, // 解析额外地址、建自定义 UI 状态
beforeObs(ctx) {}, afterAction(ctx) {},
onSkillChange(ctx, from, to) {},
onRender(ctx, rig) {}, // 例:Microduck 嘴巴开合
onInput(ctx, action, value) {}, // 例:右扳机 → quack
dispose() {},
};
```
- 内置 package 的钩子与平台一起打包;外部(Hub)package 的钩子默认**禁用**,需要用户明确确认,因为加载外部 JS 有安全风险。
- Microduck 的嘴巴、quack/wheee、脚步声都放进 `robots/microduck/hooks.js`。
### 6.8 联机 Ghost
数据包 v2:
```json
{ "v": 2, "robot": "microduck-legs", "pkg": "<content hash>",
"root": [x, y, z, qw, qx, qy, qz], "q": [...quantized joints], "extra": {...} }
```
- 根据 `robot` 懒加载对应 package 的渲染部分(不需要物理和策略)。本地加载不了时显示占位体(胶囊 + 名字)。
- `extra` 交给钩子处理(Microduck 的嘴巴、颜色)。
- 收到 v1 包时按 `microduck-legs` / `microduck-rollers` 解释,与老客户端兼容。
### 6.9 校验与错误处理
- `robot.json` 用 JSON Schema 校验,出错信息写明字段路径(如 `skills[2].controller.policy: file not found`)。
- 加载阶段:名字解析失败(joint/body/sensor 不存在)、obs 维度不匹配、ONNX 冒烟测试失败 → BIOS 界面显示 `SYSTEM HALTED` 和具体原因(复用现有的 `bootHalt`)。
- 运行阶段:动作出现 NaN 时不写入 ctrl;外部策略直接回退(沿用 `revertCustomPolicy`);物理出现 NaN 时立即 reset。
## 7. 迁移计划(分阶段,每阶段可独立合并)
| 阶段 | 内容 | 验收 |
|---|---|---|
| **P0 回归基线** | 用 Node 写一个 headless harness:固定初始状态和命令序列,walk/kick/groundpick/rollers 各跑 N 步,记录 qpos 轨迹快照 | 在当前代码上生成黄金快照 |
| **P1 拆分 game.js** | 按 4.1 节抽出 SimCore / ObservationPipeline / ActionPipeline / SkillManager / InputRouter,**参数仍取自 constants.js** | 快照逐位一致;手动体验不变 |
| **P2 Robot Package** | 定义 schema v1;创建 `robots/microduck-legs`、`robots/microduck-rollers`;constants.js 中与机器人相关的部分删除;legs/rollers 改为 family 切换 | 快照一致;`variants.js`、`custom-policy.js` 改为读 package |
| **P3 通用渲染** | RigRenderer 读 MJCF visual geom;Microduck 继续用 `glb` 模式 | 用 menagerie 任一模型能正确显示并随 qpos 运动 |
| **P4 第二个机器人:四足** | 接入 Unitree Go2(menagerie MJCF + 一个公开的 locomotion ONNX),只写 `robot.json` | 不改平台代码即可行走;机器人选择界面可以切换 |
| **P5 机械臂** | 接入 Franka Panda + `tabletop` World;实现 `ik` 控制器、`ee_pose` 命令、`manipulator` 输入 profile | 键盘/手柄可以控制末端和夹爪抓方块 |
| **P6 相机观测** | `camera_rgb/depth` term + 离屏渲染;用一个视觉策略(或合成测试策略)验证 | 张量形状和像素与 MuJoCo 相机视角一致;桌面端 50 Hz 不掉帧 |
| **P7 联机与分享** | Ghost v2;从 Hub 加载外部 Robot Package(钩子默认禁用) | 不同机器人的访客能互相看到对方 |
P4 和 P5 可以并行。P1 风险最高(大文件拆分),必须依靠 P0 的快照保证行为不变。
## 8. 测试策略
- **单元测试(node --test)**:每个 obs/action term 用 menagerie 的小模型(或手写 MJCF)验证维度和数值;SkillManager 的状态转换表;schema 校验的正反例。
- **回归测试**:P0 的轨迹快照,每个阶段都跑。注意 ONNX 推理在 Node(onnxruntime-node)与 Web(WASM)上可能有浮点差异,快照比较时允许 `1e-5` 容差,P1 阶段要求逐位一致(同一后端)。
- **Package 一致性测试**:遍历 `robots/*`,执行加载 → 校验 → 冒烟推理 → 跑 2 秒不出现 NaN / 不摔倒(浮动基座)。
- **手动验收清单**:每个阶段在 PR 中附上演示录屏。
## 9. 风险与开放问题
| 风险 | 缓解 |
|---|---|
| 人形等大模型在 WASM 中的性能(mesh 多、自由度多) | 渲染 mesh 简化(离线脚本);物理用 collision-only 模型;首屏只加载当前机器人 |
| WASM 绑定没有暴露 contact 数组(现有代码已注明) | 接触相关观测统一用 MJCF `touch` 传感器;需要时研究 `mj_contactForce` 是否可用 |
| 外部策略的观测约定五花八门(缩放、顺序、四元数格式) | 每个 term 支持 `scale`、`clip`、`noise:false`、`order`;必要时由钩子注册自定义 term |
| 资源体积与 Git LFS | package 支持 `"assets_base": "https://…"` 远程托管;构建时只内置 Microduck |
| menagerie 资产许可证各不相同 | 每个 package 带 `license` 字段,UI 中展示 |
| 加载外部 hooks.js 的安全问题 | 默认禁用;后续可以考虑放到 Worker 沙箱中执行 |
开放问题(需要评审时确认):
1. 第二、第三个目标机器人是否就是 Go2 和 Panda?有没有你们自己的机器人需要优先接入?
2. 玩法层(arena、球、贴纸、ceremony、Microduck 风格的 UI)是保留为默认主题,还是做一个更中性的"平台 UI"?
3. 是否需要支持外部 package 在线加载(P7),还是只考虑仓库内置的机器人?