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.
30 KiB
多机器人平台首期实施计划
- 日期:2026-10-27
- 状态:首期工程实现及本地自动化验收完成;待用户体验确认,未提交/发布(执行记录见下)
- 设计依据:多机器人平台改造设计
- 交付范围:Microduck legs / rollers + Microban 行走 / 独立转头;单一仿真界面,首期键盘输入
- 方法:逐任务先补测试、验证失败原因、最小实现、运行回归;每个阶段设置合并 / 继续门槛
执行结果更新
2026-10-27:P0–P5 首期实现和本地验证完成。29 项 Node 测试、25 项完整浏览器/WASM 测试、20 项生产构建浏览器测试和 /play/ 部署前缀检查通过;资产/schema/格式/构建/依赖审计通过。具体证据、实现映射、基线出处和未验证范围见 工程验收报告。Docker、私有 HF 实际部署与 15 小时耐久未验证,不能据此声称通过。
以下分任务保留制定时的计划措辞;第 2 节是实施前历史基线,不是当前测试或架构状态。
1. 已确认范围与执行纪律
- 默认 Microduck,自动进入仿真;无标题、RESUME 菜单或 BIOS 动画。
- 后续用户确认更新:统一 comic 风格与背后相机/C 恢复;进一步统一所有机器人的默认有界场地为 4.5 × 4.5 m(原长宽各扩大 50%,墙高/厚不变)。新包可省略 world,默认由平台解析;Microduck 保留外观、配色和核心玩法。详见 有界场地验收。
- Microban 为 63D obs / 18D actor,metadata 含 19 关节;head 独立 H 开关,不能进入 actor 映射。
- 简化 PD 力矩后端允许调参,但必须在真实重力和物理仿真下稳定行走,不用 qpos 动画冒充。
- 首期不要求下蹲、BAM、联机、贴纸、庆祝动画、手柄、触屏、在线 Package、Go2 / Panda。
- 不修改源 Microban 项目;复制到本仓库,记录实际工作区文件哈希与许可。
- 不因引入通用框架改变 Microduck 现有技能切换、lastAction、动作尺度和恢复规则。
- 所有“通过”必须有实际测试输出 / 记录。制定计划时,以下命令、文件与验收是待实现项;当前结果以链接的工程验收报告为准。
- 设计冻结后如需改变验收或扩大范围,先报告原因;不为通过测试悄悄放宽判据。
2. 规划时已核实的基线
| 项目 | 当前事实 |
|---|---|
| 平台代码版本 | 44d3681726468bdd00e88241894d5faa53e3c63e,实施前重新记录实际版本 |
| Node 测试 | npm --prefix app test 已执行,8 项 keyboard-layout 测试通过;目前不是仿真回归套件 |
| 构建 | npm --prefix app run build 已执行成功;存在 MuJoCo module 浏览器 externalization 警告,尚未据此验证浏览器运行 |
| 测试框架 | 当前只有 node --test;无浏览器 E2E 基础设施 |
| 调试接口 | window.rl 已暴露 model / data、buildObs、step、resetSim、技能触发和 locomotion 切换 |
| 控制循环 | 独立 async while (running),不随 R3F rAF 停止;直接调用 rl.step() 会与后台循环争用 |
| 全局生命周期 | bootStarted 模块级单例;大部分监听器、订阅、定时器、渲染 / 模型资源尚无统一 dispose |
| World | arena / 球 / hfield 在 buildPhysicsXml() 与主闭包中混合生成 |
| 音频 | 当前 audio.js 的 SOUND_DISABLED = true;首期不擅自把这个总开关改成启用 |
| Microban 来源 | 源仓库 HEAD 为 d0a128d180ecfce69eaaf31b295a0fce31280bfd,但工作区有未提交修改,包括 constants / walk / 仿真文件;仅记录 HEAD 不足以复现 |
| Microban I/O | 源环境实际读取为 obs [1,63] / actions [1,18],metadata names/defaults 均 19 项 |
基线中的成功仅限上述检查。尚未生成 Microduck 黄金轨迹,尚未运行 Microban 浏览器稳定性验证。
3. 依赖、目录与验证入口
3.1 实施依赖
T01 浏览器测试与独占步进 ──> T02 Microduck 基线
T03 Microban 来源/观测样例 ──> T04 简化控制可行性
T02 + T04 ──> P0 gate
P0 ──> T05 生命周期/暂停 ──> T06 单界面/提示(P1)
P1 ──> T07 schema/loader ──> T08 sim/composer
T08 ──> T09 obs/action/actuation ──> T10 skill/commands
T07~T10 ──> T11 Microduck Package 迁移(P2)
P2 ──> T12 World/presentation ──> T13 MJCF renderer
T12 + T13 ──> T14 切换事务(P3)
P3 ──> T15 Microban 产品化(P4)
P4 ──> T16 完整验收与文档(P5)
T03 / T04 的实验使用隔离测试入口,不先改生产启动逻辑。P0 的最小数值 / PD 代码在 T09 收敛到平台,不维护第二套正式 runtime。
3.2 测试目录
app/test/:纯逻辑node --test,新测试使用唯一主题文件名。app/e2e/:真实浏览器 / WASM 集成与 UI;与 Node 默认匹配路径分开。app/test/fixtures/:小 MJCF、显式命令序列、按版本记录的数值参考。app/e2e/support/:仅测试模式可用的 step / snapshot 辅助,避免依赖生产 UI 的动画时序。app/test-results/:运行报告、录像和截图,加入忽略列表;需要长期保留的验收摘要写入 docs。app/scripts/:资产检查、校验、快照生成;生成黄金快照必须显式执行,不能由普通测试自动覆盖。
3.3 命令契约(已建立)
现有命令继续保留:
npm --prefix app test
npm --prefix app run build
npm --prefix app run dev -- --host 127.0.0.1
T01 / T02 / T07 中补充的脚本现已可执行:
npm --prefix app run test:e2e # 浏览器 UI + WASM 集成
npm --prefix app run baseline:record # 显式生成候选基线,不自动接受
npm --prefix app run test:regression # 只读比较已接受的 Microduck 基线
npm --prefix app run validate:packages # 内置包静态校验;WASM 动态校验由 E2E 承担
E2E 使用项目内 @playwright/test devDependency 与固定 lockfile;浏览器安装独立记录,缺依赖明确报错,不能静默 skip 后报告全绿。不依赖全局 CLI 或源 Microban Python 环境运行正式回归。
4. P0:回归基线与 Microban 可行性
T01. 建立浏览器测试和独占步进
文件:
- 修改
app/package.json、app/package-lock.json、app/.gitignore。 - 新增
app/playwright.config.js、app/e2e/runtime-smoke.spec.js、app/e2e/support/simulation.js。 - 最小修改
app/src/game/game.js,只增加可停止、等待 idle、测试独占步进的控制边界,不改controlStep()数值顺序。
步骤与测试:
- 先写测试:加载实际页面 / WASM,等待 boot;接管自动控制循环后,只有显式 step 会改变
data.time。 - 实现 single-owner / single-flight:暂停入口先停止调度,再等待已经提交的 ONNX 推理及完整控制 tick 结束。
- 禁止自动 tick 与
window.rl.step()重叠;测试 N 个控制 tick,物理时间应增加N * timestep * decimation。 - 错误传播到测试,捕获未处理 rejection / console error;不在生产默认开启调试路由。
- 运行 Node 测试、浏览器 smoke 和 build。
完成标准: 新建浏览器会话可重复独占执行固定步数,既有仿真数值路径未被更改。
T02. 生成并接受 Microduck 回归基线
文件:
- 新增
app/e2e/microduck-regression.spec.js、app/scripts/record-baseline.mjs。 - 新增
app/test/fixtures/microduck/下命令序列、候选 / 已接受轨迹、环境说明。 - 按需扩展测试专用观测接口,保留现有
window.rl诊断能力。
步骤与测试:
- 固定 backend(ORT WASM 单线程)、初始姿态、随机种子和输入序列;排除联网、动画与墙钟调度噪声。
- 分别记录 legs 静止 / 行走 / kick / sitstand / groundpick / roll / recovery,以及 rollers drive / crouch。
- 每 tick 记录 qpos / qvel / ctrl、obs、lastAction、mode / recovery、必要的 phase;轨迹覆盖切入与退出,不只截图。
- 对 setTimeout / performance.now 驱动的技能制定可控制时钟或分段用例;测试接管不能让旧时间逻辑无意冻结或跳过技能。
- 同环境重复生成两次,比较结果。若不确定性仍存在,先定位而不是直接把容差设大。
- 录制核心外观 / arena / 相机截图和技能手动清单,记录未开启的功能。
- 普通回归只比较已有快照;候选基线变更须明确审核原因,不能自动更新。
完成标准: 当前实现具有可重复的同后端回归证据;若原项目某流程已失败,先记录为既有问题,不伪造成功基线。
T03. 固化 Microban 来源、资产与数值参考
文件:
- 新增
app/public/robots/microban/model.xml、实际引用的assets/*、policies/walk.onnx。 - 新增
app/public/robots/microban/SOURCE.md、LICENSES/*、来源哈希清单。 - 新增
app/scripts/check-robot-assets.mjs、app/test/fixtures/microban/、app/test/microban-reference.test.js。
步骤与测试:
- 只读核对源工作区,记录 HEAD、实际使用文件哈希及未提交修改事实;不复制整个
.venv、CAD 或与模型无关文件。 - 枚举 robot XML 引用和 include / meshdir;逐文件检查复制结果及许可。无法明确的资产许可列为发布阻塞,不臆测继承许可。
- 读取实际 ONNX names / shapes / metadata,保存诊断结果和文件 hash;不把 Python 环境设为平台运行依赖。
- 以源代码为参考,生成中立、倾斜、非零速度 / 命令 / lastAction 的观测样例。Python 可用于一次性校对,样例必须可由仓库内 JS 测试独立验证。
- 测试 19D metadata 按名字筛选 18 个策略关节,缺项 / 重名 / 错误长度明确失败。
- 测试
q_body = q_imu * conjugate(q_mount)与重力逆旋转;保留源 gyro site frame,不能擅自改成 body frame。
完成标准: 本仓库资源自足,来源可复现;18D 顺序、63D 拼接、坐标系与默认姿态均有数值参照。
T04. 在真实 WASM 中验证 Microban 简化控制
文件:
- 新增隔离验证入口
app/e2e/fixtures/microban-probe.html和对应 JS。 - 新增
app/e2e/microban-probe.spec.js、探针参数 / 结果记录。 - 小型共享数值辅助放在明确的试验模块;T09 迁入平台后删除重复实现。
步骤与测试:
- 使用项目同版 MuJoCo / ORT WASM、真实复制模型与 actor,检查 model / data、mesh 和 sensor 可访问性。
- 按名字建立 joint / qpos / dof / actuator 映射,19 个模型关节与 18 个 actor 关节分离。
- 初始化源中立姿态与参考姿态,确保 qpos、目标、lastAction 不混淆;计算源定义的 63D obs。
- 每 20 ms 运行 actor,每 5 ms 更新限幅 PD 力矩并步进;head 暂保持 0。
- 显式记录 kp / kd / torque limits、源关节阻尼叠加情况、spawn、速度和跌倒判据,不硬编码进共享平台。
- 完成设计第 11.2 节中站立和前后 / 左右移动部分;P4 再加入 head 并复跑完整三轮。
- 记录是否达成实际位移 / 转向、非有限值、跌倒、限幅比例和计算耗时;实验失败必须保留诊断。
P0 gate: T02 基线可重复且 T04 取得稳定站立 / 行走证据后,才开始大规模生产重构。若映射正确仍无法稳定行走,报告简化控制限制并讨论调整,不用改重力 / 固定根部 / qpos 回放替代。
5. P1:单一仿真界面
T05. 明确生命周期、暂停和实例释放
文件:
- 新增
app/src/platform/runtime/RuntimeState.js、ControlScheduler.js、Disposables.js。 - 新增对应
app/test/runtime-state.test.js、control-scheduler.test.js、disposables.test.js。 - 修改
app/src/store.js、app/src/game/game.js、app/src/scene/GameCanvas.jsx。
步骤与测试:
- 状态区分 loading / ready / error / switching 与用户 pause intent;fallen 为机器人运行状态,不能和启动错误混同。
- 生产暂停复用 T01 single-flight 边界;暂停操作完成后 model time 不变,恢复重设调度 deadline,不追赶墙钟。
- 用可暂停时钟 / 调度器替代会在暂停期间完成的 sit / stand setTimeout 与控制相关计时;保持未暂停时原有时长与流程,跑 T02。
- 引入统一清理登记:循环、timer、store subscription、全局 error handler、输入和鼠标监听器、OrbitControls。
bootGame返回运行实例而非只写全局;消除不可重入的模块级bootStarted生命周期假定,兼容挂载 / 卸载 / HMR。- 关闭 / 替换实例时先等待在途推理结束,再释放 model / data / session / VFS;确认实际绑定的释放 API,禁止凭空调用 destroy 方法。
- GameCanvas 管理 PMREM generator、环境贴图和旧 scene 对象的清理;共享 geometry / material 不重复释放。
- 测试重复 mount / dispose、延迟推理、出错后 retry 和 dispose 幂等;任何旧实例完成回调不再更新全局 UI。
完成标准: 可暂停 / 重试 / 释放,不泄漏额外循环;Microduck 基线仍通过。
T06. 去菜单、整合工具栏和键盘提示
文件:
- 修改
app/src/App.jsx、app/src/ui/Hud.jsx、app/src/store.js、app/src/game/controls/keyboard.js、app/src/game/audio.js。 - 新增
app/src/ui/SimulationToolbar.jsx、ControlsHelp.jsx、RuntimeStatus.jsx。 - 新增
app/test/keyboard-input.test.js、app/e2e/simulation-shell.spec.js。
步骤与测试:
- 默认自动启动 Microduck;移除
TitleMenu、MenuDuck、BiosOverlay的挂载与启动依赖。先断开入口,最终确认无引用再删除死代码。 - 以显式 runtime state 驱动 loading / error,不用写死
entered=true或依赖?boot=1。 - Back / menu 改为工具栏暂停;Esc 同等切换;Space reset;加载 / 切换时禁止无效操作并保留必要的取消 / 重试入口。
- 提示默认展开、可折叠;初期用 Microduck 绑定描述表,T07 后移入 Package,不能另写一份与实际 input 不同的列表。
- 输入支持 held 清空、失焦清空、按键去重复、文本 / select / 按钮焦点保护;现有键盘布局测试继续通过。
- 去掉对 ceremony 完成的启动锁依赖,首期立即显示完整场景;reset 不等待庆祝 / 物化动画解锁。
- 音频不阻塞自动仿真。保留当前
SOUND_DISABLED=true默认,单独测试启用音频路径的首次有效手势解锁,不把当前无声误判为重构回归。 - 如保留
?move兼容,只允许匹配的 Microduck adapter 处理,Microban 不加载鸭子自定义策略;首期不新增在线 Package 能力。 - 测试无点击启动、Esc 暂停恢复、错误面板、提示收起展开、输入焦点、静音状态与 title 预览资源无额外下载。
P1 gate: 浏览器只有仿真界面,Microduck 核心体验不回归;禁止仅靠 CSS 隐藏全屏菜单。
6. P2:通用核心与 Microduck Package
T07. schema、内置索引与资源加载
文件:
- 新增
app/src/platform/loader/{robot.schema.json,world.schema.json,PackageLoader.js,SchemaValidator.js,metadata.js,urls.js}。 - 新增
app/public/robots/index.json、两个 Microduckrobot.json;Microban manifest 在 T15 定稿。 - 新增
app/test/{package-schema,package-loader,onnx-metadata,package-urls}.test.js、app/scripts/validate-packages.mjs。 - 修改
app/package.json/ lockfile;若使用 JSON Schema 库,以明确版本纳入依赖。
步骤与测试:
- schema 覆盖已批准字段、类型、枚举和资源清单;拒绝 unsupported controller / term,不忽略未知能力。
- 定义 resolve / validate → load resources → compile → resolve addresses → create controllers 的加载顺序,错误包含 Package id 和字段路径。
- metadata 解析与 term dimension 校验独立测试,覆盖 19→18、缺关节、重复、数字非有限、输入输出 name / shape。
- URL 以 manifest 所在目录为基准,兼容 Vite
/与/play/;保留signed()对同源资源的既有认证行为,不把签名拼到外域。 - Package 中不出现运行时依赖
/home/cen/...的路径;旧 Microduck 资源可用明确相对引用共享,避免无意义复制。 - hooks 只接受显式内置注册 key,不提供动态外部 import。
完成标准: 两个 Microduck manifest 能静态校验,错误样例拒绝原因可定位,包索引与机器人 family / locomotion UI 数据分离。
T08. 抽出 SimCore 与 SceneComposer
文件:
- 新增
app/src/platform/sim/{SimCore.js,SceneComposer.js,addresses.js,resources.js}。 - 修改
app/src/game/game.js的buildPhysicsXml()、VFS、model / data、reset 和地址解析逻辑。 - 新增
app/test/sim-addresses.test.js、小型 MJCF fixture 与app/e2e/sim-core.spec.js。
步骤与测试:
- 在小模型验证 name→qpos / dof / actuator 映射,包含 actuator 重排、ball freejoint、被动关节;不假定 root / ctrl 从 0 开始。
- 分离 Robot XML 适配与 World 注入。迁移期间 arena legacy composer 保持原生成顺序和 keyframe 布局,再逐步收敛。
- 正确处理 include、meshdir / texturedir、默认 class、相对引用;重复 / 冲突名字明确失败。
- Microduck 保留原 collision-only + GLB 资源路径,Microban 保留完整 visual / collision model;不能用全局去 visual 规则处理所有机器人。
- reset 按具名 keyframe / freejoint / joint defaults 处理;world ball 初值单独负责,不按
qpos[2]假定所有机器人。 - 验证 step / reset / compile-failure cleanup / VFS 生命周期;每次抽出后跑 T02,拒绝未经解释的数值漂移。
T09. 通用 obs、action、ONNX 与执行器后端
文件:
- 新增
app/src/platform/policy/{ObservationPipeline.js,ActionPipeline.js,TermRegistry.js}、所需 terms。 - 新增
app/src/platform/policy/controllers/OnnxController.js。 - 新增
app/src/platform/sim/actuation/{NativeActuation.js,JointPdActuation.js}。 - 新增
app/test/{observation-pipeline,action-pipeline,actuation,onnx-controller}.test.js、WASM 集成测试。
步骤与测试:
- 用精确输入样例先测试 gyro、gravity、joint pos rel、joint vel、lastAction、command,再实现预分配拼接。
- float32 shape / feeds / output 绑定与实际 session 匹配;全零 / 噪声只作诊断,合法站立观测必须验证。
- actor 输出先检查长度和全体有限性,再生成目标;禁止部分写入后才发现 NaN。
- 原生 position ctrl 和 torque PD 为不同后端;PD 每子步执行、具名映射、torque limit 与 joint limits 独立验证。
- 迁入并替换 T04 数值 / PD 辅助,复跑探针,避免两套公式逐渐分叉。
- 明确 lastAction 是未缩放 actor 输出,不是目标角、限幅力矩或 head 输出。
- Microduck kick 进入 / 退出保持 lastAction,roll / recovery 等按原流程清零;不能由通用 controller 无条件 reset。
- 异步 ONNX output 在会话失效时不得提交到新实例;测试 rejection / NaN / stale output。
T10. 主技能、并行 overlay 与命令源
文件:
- 新增
app/src/platform/skills/SkillManager.js、platform/commands/*。 - 新增
app/src/platform/policy/controllers/ScriptController.js。 - 新增
app/test/{skill-manager,commands,head-overlay}.test.js。
步骤与测试:
- 测试 primary 互斥、overlay 关节组不相交、重复所有权加载失败。
- head 使用通用脚本控制接口:0.35 Hz、±π/4、0.5 s 启停插值、停止回 0;不依赖 React 或墙钟。
- 启停 head 不改变 walk lastAction / controller / 命令;暂停后相位不变。
- 命令按技能可见性填槽,测试 groundpick / recovery head zero-padding、sitstand flag、phase 结束条件。
- 把 Microduck 特殊恢复规则放入 Package adapter / hooks,核心只提供状态和条件机制;保留 settle / upright hysteresis / give-up 行为。
- reset 同步清理 controller、overlay、命令、phase 与输入,避免新状态被下一帧旧 input 重新覆盖。
T11. Microduck 完成 Package 迁移
文件:
- 新增
app/src/robots/microduck/{adapter.js,hooks.js,presentation.js},按需要保留小模块。 - 完善两个 Microduck manifest;修改
game.js、constants.js、variants.js、custom-policy.js、controls/*。 - 新增
app/src/platform/input/InputRouter.js、app/test/input-router.test.js、Microduck Package 集成测试。
步骤与测试:
- 把 joint order / defaults / policy URLs / obs / command / timing / limits 移入 manifest 与适当 Package 模块。
- 平台按 generic groups / registry 取值,不再 import Microduck JOINT_NAMES / OBS_SIZE 等机器人全局常量。
- 配色、GLB / jaw、音效、相机特例由 adapter / hooks 负责;保留旧资源地址与几何缓存所有权。
- InputRouter 使用 Package bindings 和 labels,为工具栏 / ControlsHelp 提供同源数据;Microduck 键位保持不变。
- legs / rollers 作为同 family Package 选择;在家族内切换继续保留原有安全门控、必要的位姿 / 速度转移和核心体验,不套用跨机器人全量 reset 规则。
- 旧 custom-policy 只在 Microduck 功能边界内保留其既有校验,不与通用 Package metadata 校验混用。
- 首期关闭联机初始化,移除等待 ceremony 的网络启动依赖;贴纸和庆祝不再作为核心流程前置条件。
- 跑全部黄金轨迹、技能回归、UI / 键盘用例;审查平台层无
robot === "microban"分支。
P2 gate: Microduck 完整从 Package 读取机器人参数,核心回归通过;过渡 adapter 不成为额外独立仿真引擎。
7. P3:World、通用渲染与事务切换
T12. World 与 presentation profile
文件:
- 新增
app/public/worlds/{arena,flat}/world.json与必要 XML 片段。 - 新增
app/src/game/worlds/arena/、app/src/platform/render/presentation.js。 - 修改 arena / ball / props / relief 逻辑、
GameCanvas.jsx、Overlays.jsx、CrtDistortion.jsx、Hud.jsx、主题选择。 - 新增 World fixture、组合 / 回归测试与
app/e2e/presentation.spec.js。
步骤与测试:
- arena World 拥有球、墙、terrain、碰撞和可视化;机器人 runtime 不拥有 world-specific qpos 下标。
- flat 只有所需地面 / 光照,不混入球、墙、terrain 或鸭子视觉效果。
- 同一 World 配置驱动物理和显示,验证 arena relief 与地形碰撞仍一致。
- profile 控制场景背景、灯光、相机、HUD 皮肤、CRT / halftone 和机器人专属控件;中性界面不强制覆盖 Microduck 原主题。
- 所有场景资源进入 dispose registry,切换后无旧 render target、材质 uniform 或监听器残留。
- 对照 T02 截图、轨迹和球 / 地形手动清单。
T13. MJCF RigRenderer
文件:
- 新增
app/src/platform/render/{RigRenderer.js,mjcfGeometry.js,mjcfMaterials.js,coordinates.js}。 - 新增
app/test/render-coordinates.test.js、app/e2e/mjcf-renderer.spec.js与 geom / mesh fixture。
步骤与测试:
- 先用带命名 primitive 和偏置 mesh 的小模型测试顶点 / face / scale、颜色、geom 局部变换。
- 使用同一完整 model / data 的 geom_xpos / geom_xmat;检查编译 mesh 变换语义,不能重复应用 mesh 居中 / 缩放变换。
- 明确 MuJoCo Z-up 到 three Y-up 的统一转换,测试 root 平移 / yaw 与嵌套关节运动,避免只静态看起来对。
- visual group 与 World 可见对象分开选择,碰撞代理默认隐藏;保留调试查看能力而不污染产品 UI。
- 支持本期模型实际使用的 geom / mesh / rgba / material;未支持材质特征给诊断,不先承诺完整 MuJoCo 渲染器。
- Microban 与真实 qpos 同步,head / 手臂 / 脚底位置对齐;多次创建释放不持续增加 renderer 的 geometry / texture 计数。
T14. RuntimeManager 与机器人切换事务
文件:
- 新增
app/src/platform/runtime/{RuntimeManager.js,RobotRuntime.js,presentationState.js}。 - 修改
store.js、GameCanvas.jsx、SimulationToolbar.jsx,替换旧全局 gameApi 赋值方式。 - 新增
app/test/runtime-manager.test.js、app/e2e/robot-switching.spec.js。
步骤与测试:
- 统一 runtime 接口:load / start / pause / reset / step / frame / dispose / status;行为测试先于接入。
- 切换时保存用户 pause intent、清输入、等待旧 tick idle;保留旧实例直到候选模型 / 策略 / render 校验完成。
- 用 request generation 丢弃过期结果;按设计 UI 禁止切换重入,仍须对程序触发、卸载和取消做防御。
- 原子替换仿真 + scene root + profile + camera + controls + UI,再释放旧实例;共享 runtime / cache 不随每次切换重复初始化或误释放。
- 注入 404 / XML 错误 / shape 错误 / inference 延迟验证失败回滚、retry 和无双循环。
- 跨 Microduck / Microban 重置物理;本会话恢复 Microduck variant / loco 设置。family 内 legs / rollers 仍遵循 T11 兼容行为。
- 从 paused 切换后仍 paused,从 running 切换成功后运行;失败不误改变原暂停意图。
- 重复切换至少 20 次,检查 scene 数量、监听器 / timer 数量、WASM / WebGL 资源释放证据;允许已说明的缓存,不要求浏览器进程内存精确回到同一数值。
P3 gate: 小模型候选可测试完整切换事务;Microduck 往返不残留输入、主题、World 或失效推理。
8. P4:Microban 产品化
T15. Package、头部 overlay 与完整操作入口
文件:
- 定稿
app/public/robots/microban/robot.json和来源清单,加入内置索引。 - 优先用通用 ScriptController 表达 head;只有接口不能表达时新增
app/src/robots/microban/hooks.js,不在平台中插入机器人特判。 - 新增
app/e2e/microban-walking.spec.js、microban-head.spec.js、app/test/microban-package.test.js。
步骤与测试:
- 将 T04 通过的参数、正确的 63D obs / 18D action、IMU frame、model joint groups 和安全规则写入 Package。
- 工具栏显示 Microban;默认 flat、中性 profile、仅适用的键盘提示(方向 / WASD、H、Esc、Space)。
- H 启停 head,可行走中切换,0.5 s 插值回正;测试 actor 输出、lastAction 及 50 Hz 调用次数不因 head 重启。
- fallen 停策略并提示手动 reset,保留有界安全控制;无 stand-up 入口、无自动 reset 掩盖失败。
- 界面 / 说明标注 simplified actuation、已验证默认速度和范围,不把 metadata gains 或原项目最大速度当成已经验证。
- 运行设计 11.2 节完整协议三轮:静止、前后走、左右转、行走中转头,段间归零;记录姿态、位移、yaw、fall / reset 计数和 ctrlHz。
- 确定性加速测试验证数值稳定;额外在真实墙钟运行中检查可持续 50 Hz,不用“tick 数正确”冒充实时性能达标。
- 完整 Microduck → Microban → Microduck 回归,确认默认首次进入依然 Microduck legs。
P4 gate: Microban 正式入口不依赖 probe、源路径或 Python;稳定行走三轮通过,head 并行无回归。
9. P5:验收、清理与交付
T16. 完整回归与用户文档
文件:
- 更新
README.md,新增docs/robots/microban.md、docs/robots/package-authoring.md。 - 新增
docs/superpowers/verification/2026-10-27-multi-robot-platform.md(实际执行时记录真实日期 / 版本,不预填通过)。 - 清理未再引用的 title / BIOS / legacy adapter / probe 重复实现;按需保留隔离的诊断工具。
步骤与测试:
- 运行 Node tests、静态 Package 校验、浏览器 E2E、Microduck 数值回归和生产 build。
- 在生产 preview 验证资源加载与 WASM sidecar,而不只在 dev server;额外验证
VITE_BASE=/play/的部署前缀。 - 检查默认页面不下载 title 专属预览资源、不连接 ghost relay;控制台无未处理异常。
- 手动验收 Microduck 外观 / 配色 / 两种 locomotion / 技能 / 恢复 / 相机 / 物理交互,以及 Microban 行走 / head / fallen / reset。
- 检查全屏菜单未以隐藏组件方式残留,键盘提示能反映当前 Package;所有关键按钮可键盘聚焦操作。
- 首手势音频解锁在受控测试中验证;生产当前总静音状态如实记录,不擅自改变已存在的总开关。
- 记录每项命令、浏览器与硬件环境、通过 / 失败 / 未执行、可复现参数、截图 / 录像路径;如有 skipped,明确说明不能计入验收。
- 文档描述复制资产、许可证、如何增加基于已支持能力的 Package、简化执行器限制和暂缓功能。
- 最终检查平台核心无 robot-id 特判,无 Microban 源绝对路径依赖,无两个独立 game 引擎。
最终交付门槛: 设计第 11 节全部首期要求有证据;未通过项必须报告,不以“构建成功”代替稳定行走或 Microduck 体验验收。
10. 阶段交付物与停止条件
| 阶段 | 必须交付的证据 | 不满足时的动作 |
|---|---|---|
| P0 | Microduck 可重复基线;Microban 映射 / 观测样例;真实 WASM 稳定行走探针 | 暂停大规模重构,定位坐标系 / 参数 / 模型,不悄悄放宽物理条件 |
| P1 | 单界面启动 / 暂停 / reset / 错误 E2E;Microduck 回归 | 修复生命周期和时钟回归 |
| P2 | manifests、通用数值与技能测试、全部 Microduck 核心回归 | 保留可回滚边界,按模块定位差异 |
| P3 | World / renderer fixture、切换回滚 / 泄漏测试、Microduck 往返 | 不开放不安全的选择器路径 |
| P4 | Microban 完整三轮稳定性与 head 并行、真实时间性能记录 | 报告未达标参数和限制,不宣称兼容完成 |
| P5 | 命令结果、手动清单、来源 / 许可、使用与扩展文档 | 明确剩余问题,不把长期功能混进首期完成声明 |
实现按上述任务串行推进;本计划不要求或授权自动启动多代理 / workflow,也不自动提交 Git commit。新增依赖、生成资产和基线变更在相应阶段明示记录。