RL Physics Overlay

不阻塞强化学习训练的 MuJoCo 物理遥测浮层，优先适配 Pollen Robotics 的 Microduck Simulator。

在线演示 · 初始化模板 · Microduck Simulator 接入 · 训练/权重接入

实际效果

下面是实际页面录制的交互验收：拖动 → 固定 → 收起 → 展开 → 复位。面板移开后主视图恢复完整空间，固定时遥测继续更新。

查看高清 MP4 · 静态截图 · 验收命令与结果

动图中的机器人画面与物理量来自已有的真实 MuJoCo 仿真回放；它演示面板交互，不是实时训练录像。底部步骤字幕和橙色指针仅为录屏说明，不属于插件 UI。GPU 训练与 checkpoint 的独立实测见下方报告。

窄屏默认收起为右下角“力”入口，仿真画面仍可完整操作；入口支持键盘打开：

下面是插件实际安装到官方 Microduck Simulator 后的截图。画面由上游 MuJoCo WASM 渲染；截图中已切换到 Rollers，插件同步出现“左前轮（从动）”并读取当前运行时数据：

它把“机器人在动”拆成可检查的数据：关节位移、速度、驱动力矩、约束力矩、六维力/力矩时序与接触负载。面板是独立 Web Component，不接管仿真循环、不改策略输入、不改奖励，也不发送网络请求。

演示站采用通用的深色工程监控界面，产品标题只描述“关节与受力分析”，不会绑定某个机器人或某段训练任务。操作文字、阶段名、关节名与诊断信息均为中文。宽屏下仿真画面、右侧关节诊断和底部受力区域各占独立空间，互不遮挡；窗口小于等于 1180 px 时默认收起为“力”按钮。

面板默认同时展示数据总览、姿态、广义关节力、六维力 / 力矩曲线、XZ 力矢量、力矩方向与接触负载；无需来回切换。右上角“收起”会释放右侧空间、自动放大主视图，并保留一个小型“力”入口。

面板移动与固定

1. 按住标题左侧的橙色拖动手柄或标题区域，拖到不挡机器人的位置；手机同样支持触摸拖动。工作台会转为独立浮层，主视图恢复完整空间。
2. 点击“固定”锁住当前位置，防止误拖；再次点击“解锁”即可移动。
3. 点击“复位”恢复默认布局并清除保存的位置；“收起”只隐藏面板，重新展开仍回到原位置。
4. 键盘 Tab 聚焦标题后，用方向键移动 10 px，Shift + 方向键移动 40 px。

同一站点、路径、布局与元素 id 下会记住位置和固定状态，刷新仍保留；禁用本地存储时仍可在当前页面使用。窗口缩小时自动限制位置，确保操作栏可见。多个同布局面板请设置不同元素 id。固定仅锁住面板，不暂停仿真、训练或采样。

操作与真实训练/权重验收见 F-0001 测试记录。

Note

这是社区插件，并非 Pollen Robotics 官方项目。适配器针对官方 Microduck Simulator 的浏览器端 MuJoCo 结构设计，欢迎以小型、可审查的 PR 方式讨论上游接入。

先按使用场景选择

插件不是只支持一种演示方式。根据仿真所在的位置和当前任务，选择对应入口：

场景	真实数据从哪里来	画面	适合做什么
训练过程中实时显示	训练 runner 每次 env.step() 后的一个代表环境	可只看遥测；也可另起单环境评估器观察最新 checkpoint	看训练是否发散、关节是否饱和、接触和受力是否异常
加载已有权重运行时显示	mjlab play --checkpoint-file ... 当前执行的单环境	官方 Viser；画面与遥测来自同一个 play 进程	验收别人提供的 .pt 权重、定位动作问题、录制结果
接入官方 Microduck Simulator	浏览器中的 MuJoCo WASM + ONNX 运行时	官方 Simulator 原生画面	在官方网页里检查腿部/轮滑策略
接入其他 MuJoCo WASM 页面	宿主暴露的 mujoco、model、data	宿主页面自己的渲染器	给其他 MuJoCo 项目增加同款诊断面板

前两种场景使用相同的 Python 观察器，但运行模式不同。页面会明确显示“训练中”或“权重运行”，不会把已有权重的执行冒充为训练过程。

上游是如何无缝组合的

插件只在上游边界增加一个可关闭的观察器，不接管控制权。浏览器 Simulator 和 Python 训练虽然入口不同，但会在统一遥测帧处汇合：

Microduck Simulator                 MicroDuck RL / mjlab
window.rl 动态 getter               env.step() 后的代表环境 0
        │                                     │
PhysicsOverlayBridge                单槽、限频的 TrainingTelemetryTap
        │                                     │
浏览器快照适配器                    JSONL → 独立 sidecar → SSE
        └──────────────┬──────────────────────┘
                       ▼
              统一 TelemetryFrame
                       ▼
          有界 TelemetryBus → Web Component

“无缝”依靠四条稳定边界，而不是复制或侵入上游源码：

• 生命周期边界：React 只挂载一个 PhysicsOverlayBridge；卸载时调用 destroy()，普通 URL 不启用、也不下载遥测模块；显式开启后才动态加载。
• 运行时边界：每次采样通过 getRuntime() 取得当前 model / data；腿部与轮滑模型替换后自动重绑地址。
• 性能边界：浏览器默认 10 Hz、最多 24 个关节、240 帧；训练侧只取一个代表环境，后台单槽覆盖旧快照，观察端不会反压仿真。
• 数据边界：单位、坐标系和直接值/派生值写入统一协议；上游未暴露的通道保留 null，界面显示“未提供”。

推荐操作顺序是：固定上游版本并先跑基线 → --dry-run 查看补丁 → 从维护模板安装 → 显式开启遥测 → 验证模型热切换、缺失通道和性能 → 再提交上游补丁。Simulator、训练、升级和回滚的逐条命令见 上游无缝接入与操作手册，完整边界见 架构说明。

轻量化与上游目标

运行时依赖保持为 0。浏览器默认 10 Hz / 24 关节 / 240 帧；面板收起后继续保留有界历史，但不安排 UI 重绘，页面隐藏后暂停浏览器采样。曲线复用 SVG 节点，训练适配器在设备到 CPU 的复制前截取代表环境的关节范围。这里的“不阻塞”不代表零 CPU 成本，实测预算与限制见 性能边界。

接入官方时优先交付一个默认关闭、独立加载、可撤销的小型诊断入口，不把本仓库演示工作台、录像或训练 sidecar 塞进上游。达到上游提交条件的路线、待补验证和操作步骤见 上游收纳准备；当前仍是社区插件，尚未获得官方收纳。

三分钟接入官方 Simulator

下面是推荐给第一次使用者的路径。初始化器使用仓库维护的模板，不需要自己编写 React 组件。

0. 准备

• Node.js 20 或更高版本；
• 已下载 Microduck Simulator 源码；
• 命令中的 ./microduck-simulator 换成你的实际目录。

1. 先预览，不修改项目

npx github:carpentry-liu/rl-physics-overlay init microduck \
  --target ./microduck-simulator \
  --dry-run

终端只会列出准备修改的文件。此时不会写文件、不会安装依赖。

2. 确认后初始化

npx github:carpentry-liu/rl-physics-overlay init microduck \
  --target ./microduck-simulator \
  --install

初始化器会自动识别仓库中的 app 目录并完成三件事：

1. 从 templates/microduck-simulator/PhysicsOverlayBridge.jsx 复制可运行模板；
2. 在 app/src/App.jsx 中加入一次 import 和一次组件挂载；
3. 使用 --install 时，才在 app 中安装本插件并更新对应 lockfile。

3. 启动并检查

cd microduck-simulator/app
npm run dev

打开 http://localhost:5173/?telemetry=1。看到右侧“关节诊断”面板即接入成功；普通地址不带 ?telemetry=1 时插件保持关闭。

Important

初始化器不会修改训练配置、奖励函数、控制循环或 Python 环境。它会先检查项目结构和 window.rl 接口；目标文件有未提交修改时默认停止。无 Git 项目或明确使用 --allow-dirty 时会先写入 .rl-physics-overlay-backup/ 备份。已有自定义桥接组件不会被覆盖，除非明确使用 --force。

模板顶部的 OVERLAY_OPTIONS 集中放置 sampleHz、historySize、maxJoints 等常用项。先按默认值跑通，再调整这些参数；不超过 1180 px 时模板会默认收起为“力”入口。旧版或自定义 fork 缺少运行时 getter 时，参考 runtime-getters.js；初始化器不会擅自修改仿真核心文件。

上游项目

项目	用途	地址
Microduck	鸭子本体软件、硬件运行时与部署文档	GitHub
Microduck RL	MuJoCo、PPO、域随机化和 ONNX 导出	GitHub
Microduck Simulator	浏览器中的真实 MuJoCo WASM + ONNX 仿真	在线运行 · 源码
MuJoCo	物理仿真运行时	官网 · 文档 · GitHub

其他接入方式

需要 Node.js 20 或更高版本。插件没有运行时依赖，也不会修改训练策略、奖励函数或 MuJoCo 控制循环。

浏览器场景：接入通用 MuJoCo WASM 页面

import { installMicroduckOverlay } from "@carpentry-liu/rl-physics-overlay";

const telemetry = installMicroduckOverlay({
  mujoco,
  model,
  data,
  jointNames: ["head_pitch", "left_knee", "right_knee"],
  sampleHz: 10,
  historySize: 240,
});

// telemetry.pause();
// telemetry.resume();
// telemetry.destroy();

训练场景：训练过程中实时显示

首次接入时，只需在 MicroduckOnPolicyRunner 初始化完成后加入两行：

from python.mjlab_training import attach_mjlab_telemetry_from_env

self.physics_overlay = attach_mjlab_telemetry_from_env(self.env)

以后在 MicroDuck RL 工程目录中用一条命令启动训练和监控：

npm --prefix /path/to/rl-physics-overlay run observe:training -- -- \
  uv run train Mjlab-Velocity-Flat-MicroDuck \
  --env.scene.num-envs 4096

这条命令会自动设置 PYTHONPATH 和训练标签、创建遥测文件、启动网页与数据流，并在终端打印可点击的监控地址。无需再开两个终端，也不用手工拼 URL。观察器在 env.step() 后读取真实数据，多环境训练默认观察第 0 个代表环境；采样和写入仍然与训练热路径隔离。

训练本身通常同时运行数千个环境，不建议把交互式渲染塞进 GPU 热路径。需要动作画面时，可以另起一个单环境 play 评估器加载最近保存的 checkpoint。这个评估画面用于观察当前策略能力，不能宣称与训练代表环境是同一时刻、同一状态。

权重场景：加载已有权重运行时显示

把本地或别人训练好的 .pt checkpoint 交给官方 mjlab play，同样只需要一条命令：

npm --prefix /path/to/rl-physics-overlay run observe:policy -- -- \
  uv run play Mjlab-Velocity-Flat-MicroDuck \
    --checkpoint-file /path/to/model_500.pt \
    --viewer viser

包装命令会自动切换到“权重运行”、启动监控服务，并默认组合 http://127.0.0.1:8080/ 的官方 Viser 画面。这一模式的画面、关节状态和受力数据来自同一个 mjlab play 进程。它不会读取录像或预制动画；运行时没有提供的通道保持 null，界面显示“未提供”。

别人提供的 checkpoint 必须先能被匹配版本的上游 play 正常加载，任务、机器人关节/动作、观测维度和归一化配置都要匹配；插件不会转换不兼容权重。先核实文件来源，不要直接运行不可信的 pickle/PyTorch 文件。逐项验收步骤见 已有权重检查清单。

Viser 冷启动晚于监控页时，等终端显示 viser (listening *:8080)，再点击左下角“重连画面”。只重载渲染 iframe，不重启训练/权重进程，也不清空遥测或面板位置。

需要修改端口、输出文件、渲染器地址或只启动监控页面时，参见 MicroDuck RL 完整接入说明。其他训练框架可以使用 TrainingTelemetryTap 提供同一数据协议。

配置项

参数	默认值	作用
getRuntime	—	动态取得当前 mujoco、model、data，适合模型热切换
jointNames	自动发现	只采集指定关节；空数组时自动跳过自由根关节
maxJoints	24	自动发现时的硬上限；MicroDuck 的 14 个驱动关节及轮滑被动关节均可覆盖
sampleHz	10	可视化采样频率，建议保持在 5–10 Hz
historySize	240	每个曲线保留的最大帧数，满后覆盖旧数据
initiallyOpen	true	初次加载是否展开面板
layout	overlay	overlay 为悬浮插件；studio 为左侧仿真、右侧诊断、底部力场的工作台布局
mount	document.body	Web Component 挂载节点

调用返回对象的 stats() 可以查看接收、丢弃、重绑定和读取错误数量；观察端跟不上时会丢旧帧，不会反压训练进程。

在线演示采用 layout: "studio"，用于全屏监控页。它会把诊断放到右侧、力场放到底部；宿主页面需要像本仓库的 index.html 一样，为这两个区域预留空间。嵌入第三方官网时建议先使用默认的 overlay，确认布局后再切换工作台模式。

为什么不直接把图表写进训练循环

训练/推理循环最怕三件事：同步绘图、无界历史数据、网络反压。这个插件把它们隔开：

• 热路径零绘图：官方适配器通过 requestAnimationFrame 在循环外读取 MuJoCo 已经计算好的数组。
• 固定成本：默认 10 Hz 抽样、最多 24 个关节、240 帧环形缓冲；满了覆盖旧数据。
• 主动降级：浏览器标签页不可见时暂停；来不及展示就跳过样本，不让仿真等图表。
• 物理量不造假：WASM 未暴露的通道显示 unavailable，不以动画数据冒充力学结果。
• 训练完全可选：官方站点运行的是浏览器推理与仿真；离线训练无需加载本插件。训练可视化应由独立回放/sidecar 消费日志。

官方上游真实验证

2026-09-03 已完成两类独立验证：

上游	固定版本	真实验证
pollen-robotics/microduck_rl	29e887ec…	WSL2 + CUDA，64 并行环境、8 次 PPO iteration；观察器写出 85 帧，captureErrors=0；生成 model_7.pt 与 ONNX
同一 MicroDuck RL	同上	官方 mjlab play 加载上述 model_7.pt，Viser 实时渲染；插件持续读取 14 个关节、qfrc_*、cfrc_ext 和脚部接触力
官方 Microduck Simulator Space	1261013e…	源码安装插件后构建成功；浏览器 MuJoCo WASM + ONNX 真机运行，腿部/轮滑热切换重绑成功

具体命令、文件摘要和通道证据见 官方上游验证报告。这里的 8 次迭代只用于证明训练接入链路，不声称得到了可用步态策略。

2026-09-05 已针对可移动面板重新运行 WSL2/CUDA 训练及同一 checkpoint 的官方 Viser：拖动、固定以及关闭浏览器后，真实遥测继续增长，14 个关节可读。最新截图、完整命令和限制见 面板端到端验收；未提供的第三方权重不在已验收范围内。

已用真实复杂动作回放验证

插件已使用 mini-duck-lite/roller-fast-carve-v1 的三个 ONNX 权重重新跑过完整 MuJoCo 场景，不是只拿静态 JSON 做界面演示：

远距离轮滑 → 92.6° 连续转弯 → 运动中过竿 → 344.8° 旋转 → 急停歪头

真实仿真检查	重跑结果
路线长度	4.631 m
转弯入口 / 最低速度	0.535 / 0.258 m/s
过竿速度	0.390 m/s
过竿躯干高度	0.072 m
旋转角度 / 漂移	344.8° / 0.068 m
最终平面速度	0.000185 m/s
五项路线验收	全部 PASS

新运行生成 974 个 50 Hz 控制步，遥测 SHA-256 为 86400f…c86ba，与已发布训练证据逐字节一致。CI 使用从它确定性降采样得到的 196 帧真实夹具，覆盖 9 个阶段、9 个关节、六维空间力/力矩、广义驱动/惯性/约束力和接触负载。完整方法见 真实场景验证报告。

当前能看到什么

通道	快速模式来源	展示方式
关节位置	qpos[jnt_qposadr]	数值 + 时序
关节速度	qvel[jnt_dofadr]	数值 + 时序
广义驱动/惯性/偏置/约束力	qfrc_actuator / M(q)qacc / qfrc_bias / qfrc_constraint	独立的 joint-space 数值，绝不冒充六维力
接触数量	ncon	状态徽标
接触六维力	取决于 WASM 是否暴露 mj_contactForce	缺失时明确标记不可用

现有训练视频里的“摩擦力场、动态对数箭头、扭矩涡旋”属于派生可视编码：方向来自物理量，箭头长度采用 log1p 压缩；场图由离散接触点插值，不应被解释成额外传感器。详细定义见 数据契约。

本地运行

npm test
npm run benchmark
npm run serve

打开 http://localhost:4173/。首页同步播放真实轮滑过竿录像与遥测夹具，并明确标注“真实仿真回放”；文件加载失败时会报错，不会回退到合成动画。调试时可以用 ?phase=crouch_gate、?phase=spin_360 固定到某个真实阶段。

仓库结构

AGENTS.md                    AI 协作边界与必跑检查
DESIGN.md                    产品、架构与扩展设计源
templates/                    可直接生成到目标项目的维护模板
scripts/init-microduck.mjs    安全初始化与结构检查
scripts/observe.mjs           训练/权重一键观察命令
scripts/training-sidecar.mjs  单端口网页、SSE 与健康检查
src/core/                     环形缓冲与限频总线
src/adapters/                 MuJoCo 快照读取、Microduck 动态绑定
src/components/               依赖为零的 <rl-physics-overlay>
python/                       mjlab 观察器与有界后台写入器
examples/                     官方 Simulator、训练和权重接入手册
docs/README.md                文档索引、编号与 Vibe Coding 流程
docs/                         架构、数据契约、性能、集成与真实验证
test/                         初始化、数据通道、边界与回放测试

仓库采用与 pe-next-robot 一致的可追溯 Vibe Coding 方法，但按 JavaScript/Python 插件实际情况裁剪：长期约束在 DESIGN.md，文档权威源和 R/F/REF 生命周期在 docs/README.md。用户流程和必跑门禁以本 README 与 AGENTS.md 为准，可执行脚本和包导出以 package.json 为准。

路线图

• 依赖为零的 Web Component 面板
• 鼠标/触摸/键盘移动、固定、复位与位置记忆
• 动态模型切换与隐藏页暂停
• Microduck Simulator 最小接入桥
• 有界缓冲、限频与性能基准
• PhysicsRecorder JSON 回放与真实轮滑过竿夹具
• 完整接触力能力探测
• Python 非阻塞训练采样器与独立 sidecar
• JSONL 实时流与 PhysicsRecorder JSON 回放器
• 上游兼容 PR（需官方维护者评审）

English

RL Physics Overlay is a dependency-free, bounded MuJoCo telemetry panel with a first-class adapter for the browser-based Microduck Simulator. It samples outside the policy loop, pauses in hidden tabs, keeps fixed-size history, and never invents unavailable channels. See the integration guide and architecture notes.

Drag the panel title, pin its position, or reset to the default layout. Arrow keys move by 10 px (Shift: 40 px); placement survives reload when local storage is available. These controls never pause the simulation or training.

License

MIT