fc5ee4f2c6
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.
426 lines
29 KiB
Markdown
426 lines
29 KiB
Markdown
# 多机器人平台改造设计文档
|
||
|
||
- 日期: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。它们不属于本次首期交付或验收。
|