1.2 项目结构

Vita2026/4/2大约 5 分钟

新建外部项目的文件结构

一、完整文件结构

source/
└── ur10e_ocs_2/
    ├── config/
    ├── docs/
    ├── ur10e_ocs_2/
    │   ├── __pycache__/
    │   ├── tasks/
    │   │   ├── __pycache__/
    │   │   └── manager_based/
    │   │       ├── __pycache__/
    │   │       └── ur10e_ocs_2/
    │   │           ├── __pycache__/
    │   │           ├── agents/
    │   │           │   ├── __pycache__/
    │   │           │   ├── __init__.py
    │   │           │   ├── skrl_amp_cfg.yaml
    │   │           │   └── skrl_ppo_cfg.yaml
    │   │           ├── mdp/
    │   │           │   ├── __pycache__/
    │   │           │   ├── __init__.py
    │   │           │   └── rewards.py
    │   │           ├── __init__.py
    │   │           └── ur10e_ocs_2_env_cfg.py
    │   ├── __init__.py
    │   └── ui_extension_example.py
    ├── ur10e_ocs_2.egg-info/
    ├── pyproject.toml
    ├── setup.py
    ├── .dockerignore
    ├── .flake8
    ├── .gitattributes
    ├── .gitignore
    ├── .pre-commit-config.yaml
    └── README.md

二、结构后面的简单注释

source/
└── ur10e_ocs_2/                         # 外部项目源码根目录
    ├── config/                          # 扩展或项目配置目录
    ├── docs/                            # 项目文档目录
    ├── ur10e_ocs_2/                     # 真正的 Python 包目录
    │   ├── __pycache__/                 # Python 运行后生成的缓存文件
    │   ├── tasks/                       # 任务代码目录
    │   │   ├── __pycache__/             # tasks 模块缓存
    │   │   └── manager_based/           # manager-based 风格任务目录
    │   │       ├── __pycache__/         # manager_based 模块缓存
    │   │       └── ur10e_ocs_2/         # 当前具体任务目录
    │   │           ├── __pycache__/     # 当前任务模块缓存
    │   │           ├── agents/          # 强化学习算法配置目录
    │   │           │   ├── __pycache__/ # agents 模块缓存
    │   │           │   ├── __init__.py  # agents 包初始化文件
    │   │           │   ├── skrl_amp_cfg.yaml  # skrl 的 AMP 配置
    │   │           │   └── skrl_ppo_cfg.yaml  # skrl 的 PPO 配置
    │   │           ├── mdp/             # MDP 相关逻辑目录
    │   │           │   ├── __pycache__/ # mdp 模块缓存
    │   │           │   ├── __init__.py  # mdp 包初始化文件
    │   │           │   └── rewards.py   # 奖励函数定义
    │   │           ├── __init__.py      # 当前任务包初始化文件，通常用于任务注册
    │   │           └── ur10e_ocs_2_env_cfg.py # 环境总配置文件
    │   ├── __init__.py                  # 顶层 Python 包初始化文件
    │   └── ui_extension_example.py      # UI 扩展示例文件
    ├── ur10e_ocs_2.egg-info/            # 安装后生成的包元数据目录
    ├── pyproject.toml                   # Python 项目构建配置
    ├── setup.py                         # Python 包安装配置
    ├── .dockerignore                    # Docker 打包忽略文件
    ├── .flake8                          # flake8 代码检查配置
    ├── .gitattributes                   # Git 属性配置
    ├── .gitignore                       # Git 忽略文件配置
    ├── .pre-commit-config.yaml          # pre-commit 钩子配置
    └── README.md                        # 项目说明文件

三、结构分析

1. 这是一个“外层包装 + 内层任务代码”的结构

这个项目不是一上来就直接把所有任务代码平铺出来，而是分成了两层：

第一层是项目工程层：

pyproject.toml
setup.py
README.md
.gitignore
config/
docs/

这一层主要负责：

项目安装
项目说明
Git 管理
代码规范
扩展配置

第二层才是真正的任务开发层：

ur10e_ocs_2/
tasks/manager_based/ur10e_ocs_2/

所以可以把它理解成：

外层是一个标准 Python 外部项目
内层才是 Isaac Lab 的任务源码

2. 真正最重要的代码，其实集中在很小的范围内

虽然这个目录看起来不少，但你当前学习阶段真正最重要的文件其实只有几个：

ur10e_ocs_2/
└── tasks/
    └── manager_based/
        └── ur10e_ocs_2/
            ├── __init__.py
            ├── ur10e_ocs_2_env_cfg.py
            ├── mdp/
            │   └── rewards.py
            └── agents/
                ├── skrl_ppo_cfg.yaml
                └── skrl_amp_cfg.yaml

这几个文件分别负责：

__init__.py
负责任务注册，把任务名和环境配置绑定起来
ur10e_ocs_2_env_cfg.py
负责环境整体配置，是整个任务的核心
mdp/rewards.py
负责奖励逻辑
agents/*.yaml
负责强化学习算法参数配置

所以从学习角度看，这个项目的真正重点是：

任务注册文件 + 环境配置文件 + 奖励文件 + 算法配置文件

3. 这个结构是“单任务导向”的，不是“多机器人平台导向”的

从目录上看，你现在的项目是：

tasks/
└── manager_based/
    └── ur10e_ocs_2/

这说明它当前是围绕一个具体任务 ur10e_ocs_2 来组织的。
也就是说：

这种结构很适合初学者，因为：

文件集中
好定位
改动直接
报错也比较容易找

但它还不是那种很成熟的大型平台结构。
比如它暂时还没有明显拆出：

assets/
robots/
observations.py
commands.py
terminations.py

所以它更像是：

一个适合入门和快速实验的单任务外部项目

4. `manager_based` 这一层很关键

目录里有：

tasks/
└── manager_based/

这说明你这个任务采用的是 Isaac Lab 中的 manager-based 环境组织方式。

这种方式通常会把环境拆成几大块来配置：

scene
actions
observations
events
rewards
terminations

也就是说，你后面在 ur10e_ocs_2_env_cfg.py 里面看到的那些配置类，不是随便写的，而是和 manager_based 这种环境风格对应的。

所以这一层的含义可以简单记成：

这个任务不是手写一个大 env 类，而是通过“配置 + manager”去组装环境

5. `agents/` 和 `mdp/` 说明这个项目已经开始有强化学习任务结构了

虽然现在项目还比较简单，但从目录上已经能看出强化学习任务的基本轮廓：

`agents/`

负责算法配置，例如：

skrl_ppo_cfg.yaml
skrl_amp_cfg.yaml

说明当前项目已经接入了 skrl 训练框架。

`mdp/`

负责任务逻辑的一部分，这里目前主要是：

rewards.py

说明这个项目已经把“环境配置”和“奖励逻辑”开始分开了。

虽然拆分还不算很多，但已经有了强化学习任务工程化的雏形。

6. `pycache` 不用重点关注

你目录里有很多：

__pycache__/

这些都是 Python 运行后自动生成的缓存目录。
它们不是你要重点学习或修改的内容。

当前学习阶段可以直接理解成：

这些是运行缓存，不是核心源码

四、当前阶段最值得关注的主线

如果你现在是从“新建外部项目”开始学习，我建议你把注意力集中到下面这条主线上：

setup.py / pyproject.toml  //项目怎么安装
        ↓
tasks/manager_based/ur10e_ocs_2/__init__.py //任务怎么注册
        ↓
ur10e_ocs_2_env_cfg.py //环境怎么创建
        ↓
mdp/rewards.py   //奖励怎么定义
        ↓
agents/skrl_ppo_cfg.yaml  //算法怎么训练

五、总结

你现在这个新建外部项目的结构，本质上是：

外层是标准 Python 工程包装，内层是一个 manager-based 的单任务强化学习项目。

对于当前阶段来说，不需要一开始把所有目录都研究得很细。
最应该重点看的，是：

tasks/manager_based/ur10e_ocs_2/__init__.py
ur10e_ocs_2_env_cfg.py
mdp/rewards.py
agents/*.yaml

因为这些文件才真正决定了你的机器人任务是怎么跑起来的。