Files
chenlin a8be5e0134 feat: release v0.5 with shared interactive arenas and textured RP1
Unify lighting and line-colour controls across robots, replace the football with a shared layout of draggable physical props, and import the supplied RP1 GLBs without changing trained physics or policies.

Include reproducible visual import/provenance, regression coverage and verification records. Verified 66 unit tests, 55 browser tests and production-build checks.
2026-10-30 14:14:03 +08:00

160 lines
11 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.
# RP1:第三个机器人与独立多技能策略
## 当前可用
```bash
npm --prefix app run dev -- --host 127.0.0.1
```
在 Robot 下拉框选择 **RP1**,所有物理与推理都在浏览器,不需要训练后端:
- W/S 或 ↑/↓:前进/后退,命令 `+0.4 / -0.3 m/s`。
- A/D 或 ←/→:左右转,命令角速度 `±0.6 rad/s`。
- **J:舞蹈前 10 秒片段;H:完整 4.36 秒挥手**。也可点击按键面板的对应按钮。先释放移动键,再请求动作。
- 动作完成自动混回走路;方向键可提前中断。Space 重置;Esc 暂停/继续;C 恢复跟随相机。
- 暂停时动作按钮禁用;参考帧和技能计时也一起冻结。
- 场地按名义站立高度 1.32 m 相对 Microduck 0.27 m 缩放:22 × 22 m,墙高约 1.222 m、厚约 0.244 m。网格/淡出距离同步缩放,真实碰撞墙与视觉一致。
右侧动作按钮仅显示英文 **Dance**、**Wave**,不显示括号补充文字。
**限制:完整舞蹈参考长 131.46 秒;旧版 model_7999 的长程测试在参考帧 994(约 19.9 秒)失稳。新版 model_23998 目前只验证并开放前 10 秒,完整时长尚未重新验收,不自动延长 duration。** 训练完成不等于任意长度播放已收敛;不能仅延长 duration 就宣称稳定。
## GLB 材质与外观
已接入用户提供的 `RP1机器人glb.zip`:白/灰/蓝 PBR 材质、法线贴图、面部屏幕和发光标识均保留。63 个部件映射到现有 25 个物理 body,物理模型仍为 24 自由度;23 个 body 直接使用原 GLB,双手各 20 个部件按原始固定手 URDF 组合到手腕 body。手指随手腕整体运动,不新增独立手指控制,也不改变行走、舞蹈或挥手策略。
模型 XML、原始碰撞体、惯性、关节及全部 ONNX / motion 文件不变;仅新增 `render.body_visuals`。原 GLB 为 Y-up,绑定时统一绕 X 轴 +90°,不能当作 Z-up 直接贴到 body。原始 STL 可视 mesh 会隐藏,而不是与新模型重叠绘制。
复现导入:
```bash
python3 app/scripts/import-rp1-visuals.py "/home/cen/Downloads/RP1机器人glb.zip" \
app/public/robots/rp1/visuals/rp1_hand_fixed.urdf
npm --prefix app run validate:packages
npm --prefix app run test:e2e -- rp1-visuals
```
来源和 SHA-256 见 `app/public/robots/rp1/visual-source-manifest.json`;包内未附再分发许可。首次 RP1 加载会额外读取约 93 MB 的自包含 GLB,具体帧率取决于 GPU;本次没有简化或改写用户的网格、贴图和材质。验证记录见 [RP1 GLB 材质替换](../superpowers/verification/rp1-glb-materials.md)。
## 已完成权重
均来自 `/home/cen/Embodied_Workspace/Mujoco_Projects/roboparty_train/logs/rsl_rl`,显式选择最终、完整且稳定的文件,不动态追踪目录中的最新文件:
| 技能 | Run / checkpoint | 训练迭代 | 部署时长 |
|---|---|---:|---:|
| walk | `rp1_24dof_flat/2026-10-28_15-47-49/model_9000.pt` | 9000 / 配置 9001 次 | 连续 |
| dance | `rp1_24dof_beyondmimic_dance/2026-10-29_11-05-14_dance_resume/model_23998.pt` | 从 7999 续训 16000 次,最终 23998 | 前 10 s |
| wave | `rp1_24dof_beyondmimic_wave/2026-10-28_19-00-23_wave/model_7999.pt` | 7999 / 配置 8000 次 | 全 4.36 s |
包在 `app/public/robots/rp1/`;`source-manifest.json` 保存 checkpoint、配置、motion、ONNX 与资源哈希。导入不会启动、停止或修改训练。
## 数值合同
共同约定:floating base `base_link`,24 个具名关节;物理步长 0.005 s、decimation 4、控制 50 Hz;`default_joint_pos + 0.25 * action`;每物理子步应用具名 PD、力矩上限和四象限 torque-speed envelope。
### 行走
- float32 `[1,243] → [1,24]`,ELU MLP `243→512→256→128→24`。
- 单帧:gyro 3、projected gravity 3、velocity command 3、relative joint position 24、joint velocity 24、last action 24。
- 3 帧 term-major,每个 term 内 oldest→newest;首次采样回填,reset 清空历史。
- 包含经验归一化 `(obs - mean) / (std + 0.01)` 和 runner 的 ±100 动作裁剪。
### BeyondMimic 舞蹈/挥手:实际是 student 分支
必须读取日志的 `agent.yaml: obs_groups.actor`,本次是 **`[student]`**,不是带 motion_preview/anchor 的 `policy` 观测组。
- float32 `[1,126] → [1,24]`,ELU MLP `126→512→256→128→24`,内含经验归一化;runner 未裁剪动作,导出器也不增加裁剪。
- 顺序:`motion_command` 48(参考 joint_pos 24,然后 joint_vel 24)、root-frame gyro 3、projected gravity 3、相对该技能 defaults 的 joint_pos 24、joint_vel 24、last action 24。无历史。
- actor、动作和 motion 都按日志 `joint_ordering` / action 的 `preserve_order` 具名顺序解析,不按 MJCF actuator 索引猜测。
- `skills[].defaults` 保留各自训练的参考姿态;不会用行走策略的参考姿态代替。
- 这两个 student actor **不需要** anchor/reference quaternion 或 motion_preview 输入。带这些输入的其他 BeyondMimic 导出仍不支持;未知 terms 和不同 actor branch 会明确拒绝,而不是伪造兼容。
浏览器省略训练时的随机延迟(0–2 physics steps)、域随机化、随机 default positions、外推力及观测噪声。它不是 Newton/MJWarp 或实机电机的精确等价物。跌倒停止推理、请求手动 reset,不自动起身。
## 统一生命周期与参考数据
`platform/policy/controllers/OnnxPolicy.js` 对每个技能独立拥有 session、观测历史、lastAction、defaults 和 motion reference,仅共享物理状态与最终 target map:
- `load()`:编译自己的观测/动作管线、检查真实 dtype/shape、执行有限值 smoke test。
- `reset()`:清空该策略自己的历史/lastAction,参考时钟回到未启动状态。
- `run()`:按仿真时间采样参考,构建观测、推理、原子提交关节目标。
- `dispose()`:释放 session;部分加载失败释放已创建资源,切换失败回滚到旧机器人。
`JointMotionReference` **只写 observation,不写 qpos、速度或关节 targets**。不是运动学动画,也不在动作开始/结束传送 root。每次真正激活策略时从帧 0 开始,50 Hz 一帧,暂停不推进;末帧 clamp,不 wrap、不随机重采样、不复用上次进度。
`skills[].reference` 是 Package 相对路径,例如 `motions/wave.json`:
```json
{
"schema": 1,
"layout": "positions_then_velocities",
"dtype": "float32-le",
"step_dt": 0.02,
"frames": 218,
"joint_names": ["实际 24 个具名关节,顺序须与 owns 相同"],
"data": "motions/wave.f32"
}
```
`.f32` 是 little-endian float32:所有 `[frames, joints]` positions,随后所有 `[frames, joints]` velocities。该 JSON 的 data 同样相对 Package 根目录解析,支持部署 base path / 同源签名。尺寸、顺序、控制时钟、长度和有限值均检查,不会悄悄插值或重排。`validate:packages` 也验证参考样本,不只检查文件存在。
## 状态机
```text
walk → settling → entering → playing → returning → walk
↘ 移动/取消/超时 → walk
```
- 停稳门限:实际平移速度 <0.15 m/s、角速度 <0.2 rad/s,持续 0.4 s;5 s 超时取消。继续移动时拒绝 pending 动作。
- entry/return 各 0.5 s 混合当前 target 与策略 target,只覆盖 primary 拥有的关节,不破坏独立 overlay。
- duration 从进入新策略开始计时,**包含进入 blend**。Dance 使用参考帧 0–499,wave 使用 0–217;返回 walk 重置行走历史。
- 方向键中断动作,以零命令行走混回,随后恢复移动输入;不支持 episode→episode 直接抢占。
- pause 不推进计时/参考;reset 清除 pending/active episode 和所有策略状态;跌倒优先停止推理。状态栏显示当前 skill / phase。
## 更新权重
### 走路
```bash
TRAIN=/home/cen/Embodied_Workspace/Mujoco_Projects/roboparty_train
"$TRAIN/.venv/bin/python" app/scripts/import-rp1.py \
--source "$TRAIN" \
--checkpoint "$TRAIN/logs/rsl_rl/rp1_24dof_flat/2026-10-28_15-47-49/model_9000.pt" \
--policy-only --completed
```
`--policy-only` 保留资产和其他技能;`--completed` 要求达到日志配置的最终迭代并更新训练状态/显示名。省略 `--policy-only` 会完整重建 manifest,把舞蹈/挥手恢复为不可用;不要用它无意覆盖已验证的配置。
### 舞蹈/挥手
```bash
"$TRAIN/.venv/bin/python" app/scripts/import-rp1-motion.py --skill dance \
--checkpoint "$TRAIN/logs/rsl_rl/rp1_24dof_beyondmimic_dance/2026-10-29_11-05-14_dance_resume/model_23998.pt"
"$TRAIN/.venv/bin/python" app/scripts/import-rp1-motion.py --skill wave \
--checkpoint "$TRAIN/logs/rsl_rl/rp1_24dof_beyondmimic_wave/2026-10-28_19-00-23_wave/model_7999.pt"
```
导出器读取日志中真实 actor/观测/关节/default/action/actuator 合同和 motion 路径,拒绝中间 checkpoint、时钟不符、不支持的分支/结构或不同驱动参数。导出含归一化,并比较 PyTorch 与 ONNX 输出。Dance 默认部署 10 s,wave 默认全片;`--duration` 可显式缩短/选择验证时长,不能超出参考总长。
**导入始终把该动作设为 `available:false`、绑定 `disabled:true`,避免新权重未经物理验证就上线。** 先运行 staged 资格测试,再检查测试报告;通过后显式启用 skill / binding,并更新 label 与 `source-manifest.json` 的 validation。源文件与导出内容的哈希不能凭空改成“已验证”。
```bash
npm --prefix app run validate:packages
RP1_TEST_STAGED=1 npm --prefix app run test:e2e -- rp1-motion.spec.js
npm --prefix app test
npm --prefix app run build
npm --prefix app run test:e2e
```
如果现有 Vite 进程已经运行很久,添加新 public 文件/目录后请重启 dev server;本机发现过旧进程缓存文件集合/变换的问题。资格测试与最终回归使用单独的新进程,不能仅依赖旧服务热更新结果。
## 验证与许可
`rp1.spec.js` 验证最终行走权重、3×25 s 序列、频率、跌倒/reset/切换和通用 episode 接口 fixture;它复用 walk 的那个测试不是动作质量证明。
`rp1-motion.spec.js` 使用真实 dance/wave ONNX 和参考:三个朝向的实际行走→动作→行走,核对 observation 内参考数值、完整部署区间、无跌倒/传送,键盘、pause/reset/中断、连续四次无 reset 触发和损坏 reference 的加载回滚。
最新舞蹈权重与标签更新见 [23998 更新验收](../superpowers/verification/2026-10-29-rp1-dance-23998.md);原多技能集成见 [最终技能验收](../superpowers/verification/2026-10-29-rp1-completed-skills.md)。[原接入记录](../superpowers/verification/2026-10-28-rp1-platform.md) 描述先前中途权重;[场地尺寸验证](../superpowers/verification/2026-10-28-robot-scaled-arena.md) 描述按机器人缩放的边界。
RP1 description 和 motion 来源未明确提供可统一再分发的许可;仅供本机评估。请在公开部署/再分发前确认模型、mesh、用户权重及动作数据各自的权限,见 `app/public/robots/rp1/SOURCE.md`。没有自动提交或公开发布。