# Universal Humanoid **面向 AI 代码智能体的模块化人形机器人强化学习框架。** Universal Humanoid 将代码智能体与可复现的机器人工程流程连接起来,支持任务定义、奖励迭代、策略训练、定量评估、可视化回放和推理策略包导出。框架基于 **mjlab、MuJoCo Warp 和 RSL-RL**,将机器人专属配置与共享训练工具分离。 “Universal”指的是**可扩展的工程架构**,而不是一个无需适配就能控制所有机器人的策略。 [English](README.md) · [环境配置](docs/SETUP.md) · [训练运维](docs/TRAINING_OPERATIONS.md) · [架构设计](docs/ARCHITECTURE.md) · [Agent 手册](AGENTS.md) · [验证记录](docs/VALIDATION.md) ## 工作流程 ```text 开发者 / AI Coding Agent ↓ 任务定义与奖励配置 ↓ 机器人适配 → mjlab → MuJoCo Warp → RSL-RL PPO ↓ 检查点与实验记录 ↓ 定量评估 + 可视化回放 ↓ 经过校验的 ONNX 研究用策略包 ``` 可以直接使用 CLI,也可以让支持文件编辑与命令执行的代码智能体操作相同工具。项目不绑定某个模型厂商,不要求额外部署专用 Agent 服务;智能体使用各自配置的模型和工具。 ## 核心能力 - **仓库内后端**:`rl/mjlab`、`rl/rsl_rl`、G1/T1 资产随项目安装,提供带哈希的依赖锁和源码清单。 - **机器人自动检查**:一次检查脚部 site、IMU 参考系、实际接触反馈、PD/限幅、关节顺序及初始姿态。 - **模块化任务**:机器人、环境和训练配置通过统一入口组合。 - **奖励迭代**:严格校验实验 JSON,支持权重、参数和 Python 奖励函数扩展。 - **GPU 强化学习**:MuJoCo Warp 批量仿真与 RSL-RL PPO 训练,支持中间检查点及优化器续训。 - **训练运维**:Linux 后台任务、进度查询、安全停止,以及 TensorBoard 曲线读取与 JSON/CSV/SVG 输出。 - **实验可追溯**:保存配置、源码快照、依赖与资产指纹、检查点哈希。 - **批量评估**:多个检查点 × 评估 seed × 站立/前进/横移/转向,汇总均值、样本方差与定义明确的失败指标。 - **压力评估**:各世界分别随机初始化,可叠加观测噪声和随机速度扰动,记录实际扰动次数。 - **检查点选择**:按显式指标排序,支持同协议矩阵的配对比较,不自动批准部署。 - **可视化回放**:MP4、重置前逐步关节/力矩 CSV,集成 mjlab 原生与 Viser 查看器。 - **策略导出**:ONNX、观测/动作契约、关节顺序、推理一致性和完整性校验。 - **Agent 手册体系**:setup-env、new-task、train、controls、deploy 及跨阶段 RL 手册;附环境脚本和文档/接口一致性测试。 ## 项目状态 项目处于**早期研究阶段**。后端源码、适配器和示例模型已纳入仓库;参考锁定环境为 Linux x86-64 + NVIDIA CUDA,不代表支持所有平台、GPU 或任意机器人。 | 机器人 | 示例任务 | 接入状态 | |---|---|---| | Unitree G1,29 自由度 | 平地速度跟踪 | 使用 mjlab 已适配模型,已记录短流程验证结果 | | Booster T1,23 自由度 | 平地速度跟踪 | 已包含适配器及 BSD 许可模型/网格,已记录短流程验证结果 | | 其他人形机器人 | 待扩展 | 需新增并验证适配器;发现模型文件不等于完成支持 | **安装规则:**直接安装本项目,不要再单独安装 `mjlab` 或 `rsl-rl-lib`。包括 `sim.py`、速度命令与 T1 适配在内的修改均已纳入仓库,并在[后端来源说明](docs/VENDOR.md)中记录;不再依赖外部未提交的工作区。 实验配置是起点,不是预训练行走策略。初始短训练策略仍会跌倒;G1 和 T1 分别训练,不共享一个通用策略。具体证据与限制见 [VALIDATION.md](docs/VALIDATION.md)。 ## 快速开始 ### 无仿真依赖地查看任务 在仓库根目录,使用 Python 3.11 或更新版本: ```bash PYTHONPATH=src python -m universal_humanoid list PYTHONPATH=src python -m universal_humanoid plan --config experiments/g1_smoke.json ``` ### 配置运行环境 训练需要兼容的 NVIDIA GPU/驱动。G1/T1 无需外部后端或资产路径,按锁文件安装即可: ```bash python3 .agents/skills/setup-env/scripts/detect.py uv sync --locked --extra dev --python 3.13 ./scripts/uh doctor ./scripts/uh verify-vendor ./scripts/uh check-robot --config experiments/g1_smoke.json --output runs/g1-check.json ./scripts/uh smoke --config experiments/g1_smoke.json --steps 16 ``` 也支持标准 `pip install -e '.[dev]'`;[环境配置](docs/SETUP.md)提供带哈希的 pip 锁定安装方式。`doctor` 检查环境,`check-robot` 检查适配器和实际接触;setup-env 脚本可统一执行并保存各项日志。旧的 `MJLAB_ROOT` 外部后端覆盖已被拒绝。 ### 运行一个小规模完整流程 ```bash ./scripts/uh pipeline --config experiments/g1_smoke.json \ --output runs/g1-first --eval-steps 250 --eval-envs 4 ./scripts/uh verify-bundle runs/g1-first/bundle --inference ``` 每次使用新的输出目录。`*_smoke.json` 仅训练两轮,用于验证工程流程,**不用于行走能力验收**。使用已包含的 T1 适配器时,改用 `experiments/t1_smoke.json`。完整训练、评估、视频和导出命令见 [English README](README.md)。 ## 看训练过程,而不只看耗时 ```bash ./scripts/uh train --config experiments/g1_flat.json --output runs/g1-long --background ./scripts/uh status runs/g1-long ./scripts/uh curves runs/g1-long --output analysis/g1-curves ./scripts/uh checkpoints runs/g1-long ./scripts/uh stop runs/g1-long # 从已有的、已提交的检查点再训练 200 轮;始终使用新目录。 ./scripts/uh train --resume runs/g1-long/model_0.pt --iterations 200 \ --output runs/g1-continued --background ``` 这些是生命周期操作示例,不应无等待地全部连跑。先确认检查点已提交;训练与评估共用 GPU 时需预留显存。`curves` 同时读取跟踪项、动作分布标准差和回合长度,缺失曲线会明确报告。 `benchmark` 默认的 seed 是**评估 seed**;如需研究训练种子差异,应分别训练不同 seed 的配置。默认评估采用随机初始状态,`--profile stress` 额外开启任务观测噪声与随机速度扰动。续训恢复优化器等训练状态,但不是中断轨迹的逐位复现。 完整的矩阵评估、检查点选择、失败率口径与 `play --measure` 示例见[训练运维手册](docs/TRAINING_OPERATIONS.md)。 ## 让代码智能体参与实验 可向代码智能体提出: > 按 AGENTS.md 和 rl-engineer 手册,为 G1 建立 baseline 并提出奖励改进。在约定预算内训练,用相同评估协议比较跟踪误差和失败事件,记录视频并导出研究用策略包,不连接真机。 规范入口:[AGENTS.md](AGENTS.md)、[RL 工程手册](.agents/skills/rl-engineer/SKILL.md)。不同奖励定义下的总奖励不能直接比较;需要结合任务指标、视频、多种随机种子和足够长的评估时间。 ## 项目结构 | 位置 | 用途 | |---|---| | `rl/mjlab/`、`rl/rsl_rl/` | 仓库内固定后端源码与许可证 | | `uv.lock` | 完整依赖解析与制品哈希 | | `src/universal_humanoid/robot_specs/` | 独立声明的机器人检查契约 | | `src/universal_humanoid/registry.py` | 机器人/任务注册与工厂引用 | | `src/universal_humanoid/tasks.py` | 配置适配、奖励注入、评估协议 | | `src/universal_humanoid/rewards.py` | 可扩展的奖励机制 | | `experiments/` | 独立实验配方 | | `src/universal_humanoid/runtime.py` | 训练、评估、视频与交互回放 | | `src/universal_humanoid/deployment.py` | 策略导出、契约校验与纯推理消费者 | | `docs/` | 环境、架构、验证和发布说明 | | `runs/`、`bundles/` | 运行生成的产物,不纳入版本控制 | 迁移安装、独立环境、机器人门禁、wheel 资源及完整短流程的实测结果见[可移植性验证](docs/PORTABILITY_VALIDATION.md)。 新增机器人需要验证模型、传感器、碰撞、控制参数及关节顺序。原始机器人描述不会被自动替换进训练任务;详细扩展方式见[架构文档](docs/ARCHITECTURE.md)。 ## 边界与安全 当前不包含真机通信、状态估计、安全监督器、急停、ROS/DDS 映射、自动形态转换、复杂地形任务、动作模仿、多 GPU 训练或原生 CPU 强化学习后端。 导出产物是**研究/推理用策略包**,不是机器人可执行程序。所有包均标记 `hardware_approved: false`,没有启用电机的命令。仅加载可信检查点;文件哈希不是数字签名或安全沙箱。 ## 致谢与发布 Git、许可证、依赖锁与 CI 的配置和本地检查结果见[仓库基线](docs/REPOSITORY_BASELINE.md)。 工程流程设计参考 Jumper 的模块化任务与操作规范,仿真和学习依托 mjlab、MuJoCo Warp 与 RSL-RL。组件和资产归属见 [NOTICE.md](NOTICE.md)。 参考 Jumper,本项目原创代码和文档采用 [Apache-2.0](LICENSE);内置依赖和机器人资产保留原许可证,见 [NOTICE.md](NOTICE.md)。对外发布前仍需完成[发布检查清单](docs/RELEASING.md)中的跨机器验证和来源审核。