Files
chenlin d5e9004f6c
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
docs: add AI agent workflow guide and clean up residual single-robot references
2026-11-05 11:52:07 +08:00

80 lines
4.8 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.
# MJRL 机器人平台
<!-- tracks: README.md @ sha256:124d41b6e17eb69c -->
[English](README.md) · [接入流程](docs/WORKFLOWS.md) · [命令手册](docs/USAGE.zh.md)
把机器人模型导入 MuJoCo,验证动力学和控制响应,再打包为原生仿真应用。
平台可以适配兼容的外部策略,也可以通过同一训练环境在原生 MuJoCo CPU 或
MuJoCo Warp GPU 上训练运动策略。
| 层级 | 起点 | 产物 |
|---|---|---|
| 0 | 网格、URDF 或缺少已验证控制的 MJCF | 可编译模型和查看应用 |
| 1 | 兼容策略与明确的观测、动作和关节元数据 | 适配后的 ONNX、布局及数值一致性结果 |
| 2 | 完整模型与已知运动学 | 确定性控制器及原生验证报告 |
| 3 | 站姿已标定且控制意图明确的足式机器人 | 机器人规格及锁定形态模板训练 |
## 使用 AI Agent 进行接入与训练(推荐)
建议使用 AI Agent(如 Claude Code、Antigravity、Cursor、Codex 等)直接打开本仓库根目录文件夹,并通过自然语言指挥 AI 进行机器人接入、训练与打包。
仓库内置了 [AGENTS.md](AGENTS.md)、[CLAUDE.md](CLAUDE.md) 以及位于 `.claude/skills/` 下的专用工作流技能(`setup-env`、`onboard-asset`、`tier1-adapt`、`tier2-control`、`tier3-train`、`new-task`、`train`、`controls`、`deploy`、`bundle-manual`)。在仓库根目录下打开后,AI Agent 会自动读取工作规则与验证门禁——你只需告知 URDF、MJCF 或网格模型路径,即可指挥 AI 自动完成环境配置、模型检查与站姿标定、生成 `tasks/<robot_id>/robot_spec.py`、启动或恢复 PPO 训练、执行量化回放评测以及打包原生 `.app` 应用。
## 运行模型查看应用
在代码库根目录中使用 Python 3.10–3.13:
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
python scripts/onboard.py inspect assets/smoke/smoke_biped.xml
python scripts/deploy.py --robot viewer_smoke --model assets/smoke/smoke_biped.xml --bundle out/viewer_demo
python scripts/play.py --app out/viewer_demo/viewer_smoke.app --headless --steps 20
```
选择尚未使用的输出目录。Windows 上使用 `.venv\Scripts\Activate.ps1` 激活。
该模型用于检验加载与打包。接入自己的机器人时,替换为实际模型并按检查报告的建议继续。
## 接入自己的机器人
1. 用 `scripts/onboard.py inspect` 检查模型和可用的配置或策略元数据。URDF
和独立网格可用 `build-mjcf` 转换。
2. 根据[接入流程](docs/WORKFLOWS.md)选择层级。打包可控制应用前,分别验证
动力学和命令响应。
3. 足式机器人先标定站姿,再用 `scaffold-tier3` 生成
`tasks/<robot_id>/robot_spec.py`。双足、四足、轮足双足和多足模板负责
观测、奖励、域随机化、课程和 PPO。
4. 用 `python scripts/train.py --list` 查看注册机器人,用
`python scripts/train.py --task <robot_id> --dry-run` 检查参数解析。
原生 `.app` 包含模型、资产依赖、控制器或策略以及 Python 入口。宿主提供
Python 和所列依赖。现有 Rust 浏览器与板端走独立的旧版包格式。轮足双足的混合
动作可导出并在原生运行时回放,旧版 Rust 使用其位置动作布局。
四个模板分别在原生 CPU 和 Warp GPU 上用合成模型完成过一次 PPO 更新,
用于验证执行路径。
[Go1 示例](assets/go1_example/README.md)还在 RTX 5080 上完成了 1,000 次 PPO
更新。选定检查点在 0.400 m/s 前进命令下,18 秒回放平均速度为 0.401 m/s,
平均绝对误差为 0.022 m/s,无重置。原生检查点与 ONNX 回放通过了前进、后退、
横移、转向及静止探测。这些是平地仿真结果,不是硬件资格认证,也不代表每个
机器人都能用相同训练规模学会控制。
[轮足双足示例](assets/wheeled_biped_example/README.md)验证了腿部位置与车轮速度
混合控制。所选策略通过了原生前进、后退、转向和静止探测,并在其声明的
±0.91 m/s 和 ±0.77 rad/s 范围内完成键盘及手柄测试。
[G1 双足示例](assets/g1_example/README.md)在完成 7,800 次 Warp 更新后,通过了
七项独立原生探测和满量程键盘测试。
[研发记录](docs/REFACTOR_STATUS.md)汇总已验收应用、未通过的试验及实测原因。
## 参考
- [项目指南](docs/PROJECT_GUIDE.zh.md):导航与支持边界说明。
- [教程](docs/TUTORIAL.zh.md):验证、训练与量化回放流程。
- [Colab](docs/COLAB.zh.md):在 GPU 上训练已注册的机器人。
- [硬件与模型参数](docs/HARDWARE.zh.md):标定要求与执行器输入规范。
- [部署指南](deploy/README.zh.md)与[部署包格式](deploy/BUNDLE.md):应用结构与运行时契约。
- [贡献指南](CONTRIBUTING.md):目录结构与仓库检查项。