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

29 KiB
Raw Blame History

多机器人平台改造设计文档

  • 日期: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 节的交互默认值也已由用户确认,作为首期实现依据。实施拆解见 实施计划。

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. 总体方案与模块边界

采用声明式配置 + 可注册算子 + 可选内置钩子。先实现两种机器人所需的公共能力,不一次性兑现所有长期注册表。

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 目录

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 配置的核心数据

策略关节顺序必须显式固定为:

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 后端:

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。它们不属于本次首期交付或验收。