项目结构

• 进一步理解整个OpenDuckMini强化学习框架项目结构

目录树

.
├── pyproject.toml           # 项目配置与依赖声明
├── README.md                # 项目说明文档
├── playground/              # 核心代码目录
│   ├── common/              # 共享模块
│   │   ├── export_onnx.py   # ONNX 模型导出
│   │   ├── onnx_infer.py    # ONNX 推理接口
│   │   ├── poly_reference_motion.py     # 参考运动生成 (JAX)
│   │   ├── poly_reference_motion_numpy.py  # 参考运动生成 (NumPy)
│   │   ├── randomize.py     # 域随机化
│   │   ├── rewards.py       # 通用奖励函数
│   │   ├── rewards_numpy.py # 奖励函数 (NumPy 版本)
│   │   ├── runner.py        # 训练 Runner 基类
│   │   └── utils.py         # 工具函数
│   └── open_duck_mini_v2/   # Open Duck Mini V2 机器人特定代码
│       ├── base.py          # 基础环境 (OpenDuckMiniV2Env)
│       ├── constants.py     # 常量定义
│       ├── custom_rewards.py        # 机器人特定奖励 (JAX)
│       ├── custom_rewards_numpy.py  # 机器人特定奖励 (NumPy)
│       ├── joystick.py      # 摇杆控制环境
│       ├── mujoco_infer.py  # MuJoCo 推理主入口
│       ├── mujoco_infer_base.py     # MuJoCo 推理基类
│       ├── ref_motion_viewer.py     # 参考运动可视化
│       ├── runner.py        # 机器人特定训练 Runner
│       ├── standing.py      # 站立任务环境
│       ├── data/            # 数据目录
│       │   └── polynomial_coefficients.pkl  # 参考运动多项式系数
│       └── xmls/            # MuJoCo XML 模型文件
│           ├── assets/      # 3D 网格资源 (STL 文件)
│           ├── open_duck_mini_v2.xml                # 机器人模型定义
│           ├── open_duck_mini_v2_backlash.xml       # 含回差建模的机器人模型
│           ├── open_duck_mini_v2_no_head.xml        # 无头部的机器人模型
│           ├── scene_flat_terrain.xml               # 平坦地形场景
│           ├── scene_flat_terrain_backlash.xml      # 平坦地形 + 回差
│           ├── scene_rough_terrain.xml              # 粗糙地形场景
│           ├── scene_rough_terrain_backlash.xml     # 粗糙地形 + 回差
│           ├── scene.xml                            # 默认场景
│           ├── sensors.xml                          # 传感器定义
│           └── joints_properties.xml                # 关节属性定义

各文件作用

共享模块 (playground/common/)

机器人特定代码 (playground/open_duck_mini_v2/)

XML 模型文件 (xmls/)

架构分层

┌─────────────────────────────────────────────────┐
│                  应用层                           │
│  runner.py      mujoco_infer.py   ref_motion_viewer.py │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────┐
│                  环境层                           │
│  joystick.py   standing.py                      │
│  (任务特定逻辑、奖励计算)                         │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────┐
│                  基础层                           │
│  base.py → OpenDuckMiniV2Env                    │
│  (MJCF 加载、关节管理、传感器读取)                │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────┐
│                  共享层                           │
│  rewards.py  randomize.py  onnx_infer.py        │
│  export_onnx.py  poly_reference_motion.py       │
└─────────────────────────────────────────────────┘

添加新机器人的步骤

该框架设计为可扩展的。要添加新的机器人：

1. 创建机器人目录：在 playground/ 下创建以机器人命名的目录（可以复制 open_duck_mini_v2 目录作为起点）

2. 编辑 base.py：

   • 重命名类以匹配新机器人名称
   • 调整模型加载逻辑

3. 编辑 constants.py：

   • 指定关节名称、几何体名称、传感器名称
   • 在 MJCF 中可能需要添加 site、命名 body/geom 并配置传感器

4. 添加 MJCF 资源：

   • 在 xmls/ 目录中添加机器人的 XML 模型文件和 3D 网格资源
   • 注意：目前关节顺序等部分值仍是硬编码的，后续将改进

5. 配置奖励：编辑 joystick.py 选择所需的奖励组件

6. 配置训练：编辑 runner.py 设置训练参数

7. 安装 Open Duck Playground 包：

cd Open_Duck_Playground
uv sync