Microduck 仿真环境拆解：四套 MJCF 模型怎么对应四种运动行为
做过 sim2real 的人都知道，仿真环境不是”建一个模型跑所有任务”。不同的运动行为对碰撞、接触、自由度的需求完全不一样。Microduck 的训练仓库里有四套 MJCF 模型，每套对应一类任务族。今天拆开看这四套模型的区别，以及为什么不能用一个模型搞定所有训练。
四套模型各干什么
Microduck 的 MJCF 模型文件全部放在 src/mjlab_microduck/robot/microduck/ 目录下，从 Onshape 用 onshape-to-robot 工具导出。每个模型有对应的 config_mjcf_*.json 导出配置。四套基础模型分别是：
robot_walk.xml — 行走任务专用。这个模型剥离了躯干和头部的碰撞几何体。原因很直接：行走任务里鸭子摔了就摔了，不需要计算身体哪个部位碰到了地面。剥离碰撞体减少了仿真中的接触点数量，MuJoCo 求解器跑得更快。训练时 4096 个并行环境，每减少一个接触点就是乘 4096 的计算节省。
robot_groundcontact.xml — 地面接触任务用。包括 VelStand（行走+跌倒恢复）、StandUp（从地上站起来）、SitStand（坐站切换）、GroundPick（弯腰触地）、BallKick（踢球）、Roulade（前滚翻）。这些任务有一个共同点：鸭子身体会真的躺在地上。模型配置了一组精选的碰撞几何体——脚底、腿外壳、躯干外壳、头部外壳、下巴、电池、髋部——覆盖所有可能接触地面的部位，但不包含每个零件。
robot_groundcontact_rollers.xml — 轮滑任务专用。在 groundcontact 基础上加了被动轮铰链关节（passive_*wheel）。这些关节不受策略控制，属于被动物理元素。
robot_allcollisions.xml — 真正的全碰撞模型，70 个碰撞几何体、37 个网格。目前没有任何任务使用它，2026 年 9 月导出，留给未来需要全接触感知的环境。
为什么不用一个全碰撞模型
你可能会问：直接用 allcollisions 跑所有任务不就行了？不行。
第一个原因是计算成本。MuJoCo 的接触求解在每个时间步要对所有活跃接触点做 LCP 求解。70 个碰撞几何体意味着潜在的接触对数量是 O(n²) 级别。4096 个环境并行训练，每个环境每步 50Hz，多出来的接触计算直接乘上去。robot_walk.xml 剥离躯干头部碰撞后，接触点大幅减少，训练吞吐量明显提升。
第二个原因是物理保真度。走路时鸭子的躯干不应该碰到地面——如果碰到了，那是一个失败 episode，应该尽早终止。但如果模型里有躯干碰撞体，MuJoCo 会在躯干接触地面时产生接触力，这个力可能让鸭子”弹”起来或者以不自然的姿态停住。策略会学到利用这个不真实的接触力。剥离碰撞体 = 接触不会发生 = 策略不能利用不存在的物理。
第三个原因更微妙：不同任务对”什么部位可以碰地面”的定义不同。行走任务里，只有脚底应该碰地面。但 StandUp 任务里，鸭子从面朝下趴着开始，胸部、下巴、膝盖都可能接触地面。GroundPick 任务里，下巴要触地。如果用 walk 模型跑 StandUp，鸭子趴下时躯干穿透地面——MuJoCo 会产生不稳定的穿透修正力，可能导致 NaN。
onshape-to-robot 导出流程
MJCF 模型不是手写的。Microduck 用 Rhoban 开发的 onshape-to-robot 工具，从 Onshape CAD 装配体直接导出。每个模型有一个 config_mjcf_*.json 配置文件，定义导出哪些零件、哪些零件带碰撞体、关节摩擦参数等。
这个流程的好处是 CAD 和仿真模型保持同步。Microduck 的硬件设计在 Onshape 上迭代，每次设计变更后重新导出 MJCF，仿真模型就更新了。手写 MJCF 最大的问题是跟 CAD 脱节——改了零件尺寸忘记更新 XML，仿真和现实就不匹配了。
导出后有一个后处理步骤：add_backlash.py。这个脚本给每个舵机关节加一个串联的被动铰链（passive_），模拟齿轮间隙。±1° 的游隙，2° 总行程。这个被动关节不受策略控制，但它影响编码器读数——因为真实编码器在齿轮输出端，在游隙之后。Backlash 变体一共六个，覆盖三种基础模型 × walk/groundcontact 两种碰撞配置。
场景文件和 keyframe
每个机器人模型有一个对应的 scene XML。场景文件做的事情很简单：加一个地板、加载机器人到初始姿态。Microduck 定义了三个 keyframe：STAND、SIT、FOLD。
STAND 是站立姿态，也是训练的默认起始姿态。SIT 是坐姿，SitStand 任务用。FOLD 是折叠姿态，运输或更新时用。
场景文件还用于 infer_policy.py——这个脚本在 CPU MuJoCo 里加载导出的 ONNX 策略，用键盘控制。它是 sim2real 验证的最后一步：策略在仿真里能走，导出成 ONNX 后在独立 MuJoCo 实例里还能走。如果这一步失败了，问题出在导出过程而不是策略本身。
HOME_FRAME：仿真和现实的交汇点
HOME_FRAME 是 Microduck 在仿真中的初始关节角度配置。这不是随便选的——它必须跟真机的一致。
2026 年的一个修正值得注意。原来的 HOME 帧把躯干重心放在踝关节后方约 5mm 处，这导致鸭子有一个微小的后倾趋势。StandUp 策略为了补偿这个后倾，学会了一个前倾头部的动作——用头部当前摆来配平。这不是策略 bug，是 HOME 帧的 bug。
修正后的 HOME2 姿态把躯干前移 5mm，让重心正好在踝关节上方。髋关节俯仰角从 30° 调到 26.24°，踝关节从 30° 调到 25.95°，膝关节从 0° 调到 0.28°。这些数字不是拍脑袋定的——是从真机上测量站立姿态的关节角度，再映射回仿真。
这个故事的教训是：仿真里的初始条件偏差会被策略放大。5mm 的重心偏移听起来不大，但策略会找到一个利用这个偏移的局部最优解——那个最优解在真机上不成立，因为真机的重心在正确位置。
地形配置：小机器人的小台阶
Microduck 的 rough terrain 配置跟标准 MuJoCo 地形生成器差别很大。原因是鸭子太小了——脚底离地间隙只有 1-2cm，标准台阶高度（10cm）对它来说是悬崖。
rough 地形配置分四种：平地 25%、金字塔台阶 25%（最大 1.5cm）、随机网格 30%（最大 1cm 高度差）、金字塔斜坡 20%（坡度 1.7°-5.7°）。
1.5cm 台阶上限是有讲究的。Microduck 的脚在行走时最大离地高度约 1-2cm。台阶高于这个值，鸭子根本迈不上去，策略学不到任何有用的东西——只会学撞墙后退。把台阶限制在脚可达到的高度内，策略才能学到”抬脚上台阶”这个动作。
还有一个细节：地形边缘的接触软化。_soften_terrain_contacts 函数把地形 box 几何体的 solref 时间常数从默认 0.02s 改到 0.04s，让接触弹簧软两倍。原因是相邻地形 box 的高度差会产生硬边缘，MuJoCo 在这些边缘上的接触法线计算不稳定，可能产生脉冲式 NaN 力。软化的接触弹簧能吸收这个不稳定，同时不影响宏观行走物理。
仿真频率 vs 控制频率
Microduck 的训练环境跑在 50Hz，跟真机控制循环一致。这意味着仿真步长是 20ms。但 MuJoCo 的物理求解步长通常比控制步长小——mjlab 框架里物理步长默认是 0.002s（500Hz），控制策略每 10 个物理步执行一次。
这个 10:1 的比例不是随便选的。物理步长太小（比如 0.01s），接触求解会不稳定——脚底接触地面时的穿透修正力会跳跃。物理步长太小（比如 0.001s），4096 个并行环境的计算成本太高。500Hz 物理 + 50Hz 控制是一个在稳定性和计算成本之间的平衡点。
BAM 执行器模型也在这个频率下运行。每个控制步，BAM 接收策略输出的 14 维目标关节角度，转换成电压控制信号，在 10 个物理步内模拟舵机的电压-扭矩-摩擦响应。这个子步级别的仿真精度是 sim2real 成功的关键——XL330 舵机在 800g 负载下的动态响应不是瞬时完成的，它有电压跌落、摩擦死区、反电动势，这些都需要子步级别的仿真才能准确捕捉。
对复刻者的实操建议
如果你在搭自己的 Microduck 仿真环境，有几件事值得注意。
先从 walk 模型开始。不要一上来就搞 groundcontact 或 allcollisions。walk 模型最简单、计算最快、最容易调试。策略能稳定行走后再换更复杂的模型。
导出 MJCF 时务必用 onshape-to-robot，不要手写。手写 MJCF 跟 CAD 脱节的后果很严重——你可能花几天时间调参数，结果发现零件尺寸跟真机差了 2mm。
HOME_FRAME 的关节角度要从真机测量，不要用 CAD 的理论值。CAD 里的装配公差和真机的螺丝拧紧程度会导致实际站立姿态跟理论值差几度。这个偏差在仿真里看不出来，在真机上会让策略表现完全不同。
地形高度不要超过脚的离地间隙。这个错误很常见——直接用 MuJoCo 默认地形配置，台阶 10cm，鸭子永远迈不上去。Microduck 的最大台阶是 1.5cm，这个数字是从脚的运动学工作空间反推的。
接触软化是必须的。不软化的话，地形边缘的 NaN 会让你在 4096 个环境里随机炸掉几个，排查起来非常痛苦——因为不是每个环境都炸，只有接触边缘的那个炸。
数据来源：pollen-robotics/microduck_rl GitHub 仓库 README.md（四套 MJCF 模型描述、任务列表、BAM 执行器配置、onshape-to-robot 导出流程、add_backlash.py 后处理、infer_policy.py 部署验证），CLAUDE.md（环境构建工作流、HOME_FRAME 修正历史、物理验证方法、地形配置原则、训练频率约定），src/mjlab_microduck/robot/microduck_constants.py（MJCF 文件路径定义、HOME_FRAME 关节角度参数、BAM 执行器 kwargs 配置、碰撞配置），src/mjlab_microduck/tasks/microduck_velocity_env_cfg.py（MICRODUCK_ROUGH_TERRAINS_CFG 地形配置参数、_soften_terrain_contacts 接触软化函数、域随机化参数范围）。
