训练和跑机器人，用的是两套仓库
先别搞错目录：真机运行时在 pollen-robotics/microduck，是一组 Rust 守护进程；训练环境在隔壁的 pollen-robotics/microduck_rl，基于 mjlab（MuJoCo Warp）与 PPO，用 uv 管理依赖。官方产品页讲的四步——仿真里训练、部署到机器人、按真机表现回头调仿真、把策略发布给社区——落到这里就是一串具体命令。
两边唯一的交汇点是 ONNX：训练仓导出策略，运行时以 50 Hz 加载它。训练仓的策略同样按 50 Hz 训练，两边频率对得上。下面按官方 README 与训练指引的顺序走，每步都写预期结果。
环境与前置条件
| 条件 | 要求 | 不满足时怎么办 |
|---|---|---|
| GPU | 训练主路径要求 NVIDIA CUDA GPU，官方参考是 4096 并行环境下约 1 到 2 小时得到可用步态 | 在任意 train 命令后加 --hf-jobs，把训练放到 Hugging Face Jobs 上跑 |
| Python 与包管理 | Python 3.12 及以上，用 uv 按锁文件自动同步，不需要手工建虚拟环境 | 先装 uv 再检查 uv --version 与 nvidia-smi |
| ARM 主机 | 首次 uv sync 要拉约 2GB 的 CUDA 依赖，默认超时容易中断 | 先设置 UV_HTTP_TIMEOUT=600 再同步 |
| 只想验证流程 | 不需要 GPU：列任务、跑 CPU 测试、导出后在 CPU 的 MuJoCo 里复演都能做 | 跳过正式训练，直接看第 3 步和第 7 步 |
从零到一条能上机的策略，共八步
- 取两份仓库并进入训练目录。预期结果：本地同时有 microduck 与 microduck_rl 两个目录，且知道后面所有 uv run 命令都在训练目录里执行。
-
让 uv 自动同步并检查显卡。跑
uv --version与nvidia-smi；第一次执行 uv run 时依赖会按锁文件装好。预期结果：命令能跑通、显卡被识别。ARM 机器若卡在下载，退回设置超时后重试。 -
列任务与跑 CPU 测试。
uv run list-envs看任务注册表，uv run --with pytest pytest tests/检查关节索引、奖励符号、NaN 防护等基础约束。预期结果：任务名里能看到 Mjlab-Velocity-Flat-MicroDuck，测试通过。这步不耗 GPU，可以先做。 -
做低成本冒烟测试：
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 64 --agent.max_iterations 5。预期结果：配置、观测、导出链路都跑通一轮，没有形状或索引错误。冒烟测试跑出来的不是步态，别拿它判断「会不会走」。 -
正式训练：
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096。预期结果：奖励曲线收敛，用uv run play加训练记录路径在查看器里能看到步态。奖励刚进平台期就急着停，很容易得到一个仿真里能走、真机上一推就倒的策略，后面还得补随机化训练。 -
只用官方导出脚本产出 ONNX：
uv run scripts/export.py Mjlab-Velocity-Flat-MicroDuck --wandb-run-path 你的训练记录。预期结果：得到 ONNX 文件，观测归一化已烘焙进图。不要手转 checkpoint，否则真机运行时没有外部训练器补归一化，策略会看到未归一化的观测。 -
CPU 复演：
uv run scripts/infer_policy.py --walking output.onnx，可加 --standing、--sitstand、--roulade 等参数演练运行时热切换，也可加 --save-csv 做仿真与真机对比。预期结果：键盘能驱动、策略切换正常、数值无异常。仿真能走不等于真机可立即上力。 -
发布与装机：用
uv run publish把 ONNX 发到策略仓库，再在机器人上用sudo robotctl policy add装 episodic 策略、robotctl policy load换 gait 策略、robotctl robot do触发动作。预期结果：策略能被加载且动作名可调用。也可以直接在/etc/robot/robotd.toml的 policy 段写自定义 ONNX 路径再重启 robotd；这种配置不会被系统更新覆盖，删掉配置行就回到出厂策略。
61 维观测与 14 维动作，改不动也不能改
运行时之所以能在 walk、recover、trick 之间热切换，是因为所有策略共享同一份观测布局。训练端与真机端必须对每个数字的顺序、单位、缩放完全一致。形状对、推理能跑，顺序或单位错了照样出事：真机会做出诡异动作，还不报错。
| 区间 | 维度 | 内容 |
|---|---|---|
| 0 到 3 | 3 | 躯干坐标系角速度，弧度每秒 |
| 3 到 6 | 3 | 躯干坐标系中的投影重力，单位向量 |
| 6 到 20 | 14 | 关节位置减去 home pose，弧度，嘴部除外 |
| 20 到 34 | 14 | 关节速度，弧度每秒，嘴部除外 |
| 34 到 48 | 14 | 上一时刻策略原始输出，动作缩放前 |
| 48 到 61 | 13 | 命令块：速度与转向 3 维、头部目标 4 维、身体姿态 6 维 |
输出是 14 个动作，对应左腿五个、头颈四个、右腿五个；嘴部舵机不参与步态。运行时要把 14 个动作插进含嘴部槽位的 15 元目标数组，插错一位，右髋的命令就送到嘴上去了。另外官方策略集名称是 pollen-robotics/microduck-policies，阶段驱动动作与 sit 到 stand 的 posture flag 只在这个官方集里，uv run publish 目前只支持 constant-command 策略。
sim-to-real 的边界在哪里
训练仓里为缩小仿真与真机差距做了几件具体的事：BAM 执行器物理（电压控制律、反电动势、负载相关摩擦）、域随机化、齿隙模拟（约 ±1° 齿轮游隙的 twin 任务），reward 设计经验集中在 AGENTS.md。这些都是让策略尽量迁移得过去的工程手段，不等于仿真通过就能直接上真机。
还有一条必须写清的社区边界：第三方 ROS 2 Jazzy 与 Isaac Sim 集成仓库自带简体中文教程和可视化，但仓库原文明确写了这是独立社区项目、未获 Pollen Robotics 背书，不包含物理机器人驱动或 ros2_control，其 Isaac 任务用的是近似 PD，不是 sim-to-real 声明；随附的 USD 与训练输入仍是历史基线，官方策略则来自不可变策略集的 SHA-256 校验产物。把它当官方训练路线会踩版本对齐的坑。
上机前与失败时的检查
- 换策略前把旧 ONNX 留一份在目录外，走差了先换回去对比，马上就能分清是模型的问题，还是这台机器本来标定就不准。
- 加载失败时看
robotctl health与robotctl monitor，运行时会点名策略不健康的原因；同时确认固件、策略与当前硬件版本对得上。 - 第一次上机按四级放开：卸力预览、固定中位开环、软地面或安全绳、小范围行走。别在桌边测。
- 想扩大动作范围，得重新调奖励与鲁棒性参数再训练一遍，把目标速度调大是跑不起来的。
边界与下一步
本页命令与契约整理自官方训练仓、产品页与公开训练指引，属于可核验的一手资料，不是本站真机训练实测；耗时、环境数量等数字是官方参考值，随硬件变化。只想用现成动作，看《Microduck 玩法扩展与社区资源》；想写规则动作或遥控面板，看《Microduck 编程：Python 与 JavaScript 自定义动作》；策略加载后行为异常，按《Microduck 常见问题与故障排查》的「策略异常」反查。