创建自己的项目或任务

创建自己的项目或任务#

模板生成器可搭建包结构，并按需生成 Isaac Lab 任务的注册代码和智能体配置。它既可创建 Isaac Lab 之外的独立项目，也可创建准备贡献给 Isaac Lab 仓库的任务。外部项目可从可运行的 Cartpole 示例、待实现的任务框架或空任务包开始；内部任务则从 Cartpole 示例开始。

选择要生成的内容#

第一个提示让你选择新任务放在哪里。

类型

适用情况

生成结果

External（外部，推荐）

在 Isaac Lab 仓库之外创建应用、实验或可复用项目。

使用 src 布局的独立、可安装 uv 项目。

Internal（内部）

准备将任务贡献给 Isaac Lab 仓库。

位于 source/isaaclab_tasks 下的任务包。

通过 wheel 安装的 Isaac Lab 只提供外部项目选项。内部选项会直接写入源码检出目录，因此只在源码安装中可用。

对于外部项目，填写一位或多位作者，并选择初始内容：

内容

生成结果

杆车

可运行示例，包含所选工作流、任务注册和智能体配置。

Stubbed（待实现框架）

相同的任务结构与智能体配置，但任务函数抛出 NotImplementedError ，必需的配置值设为 MISSING 。

Blank（空白）

包结构、项目资产路径、任务发现、测试和开发工具，不包含示例任务或智能体文件。

所填作者会写入 pyproject.toml 、按需生成的项目扩展元数据，以及 Isaac Lab 采用的 BSD-3-Clause LICENSE 。Blank 项目跳过任务系列、机器人、工作流和强化学习相关提示。Cartpole 和 Stubbed 项目接下来会询问一个或多个任务工作流。完整比较见 任务设计工作流程 。

工作流程

适合场景

Manager-based | single-agent（基于管理器，单智能体）

多数新任务。观测、动作、奖励、事件和终止条件保持模块化，便于替换。

Direct | single-agent（直接工作流，单智能体）

需要自定义步进与重置控制，或希望环境实现紧凑的任务。

Direct | multi-agent（直接工作流，多智能体）

包含多个策略，或具有各智能体专用观测、动作空间的任务。

对于 Cartpole 和 Stubbed 内容，最后选择要生成配置文件的强化学习库和算法。提示会根据所选工作流调整可用选项。框架比较见 强化学习 。

创建并运行外部项目#

首先 安装 Isaac Lab 。从 Isaac Lab 源码检出目录，或已安装 Isaac Lab 包的 uv 项目中运行生成器：

uv run isaaclab --new

命令使用当前 Isaac Lab 环境的依赖，不调用 pip ，也不另装一套模板依赖，因此可在 uv 创建的不含 pip 的虚拟环境中运行。从已安装 wheel 调用时，生成的 pyproject.toml 会将 Isaac Lab 及其可选依赖锁定到该确切版本，避免 uv sync 悄然解析到旧版本。从源码检出目录调用时，则记录该目录及其工作区包的可编辑安装路径。这使开发分支和发布分支在版本发布前即可使用，同时保留生成项目时使用的代码。源码路径相对于生成项目记录；如果任一目录移动，应重新生成项目或更新 [tool.uv.sources] 。

以下简写等价：

uv run isaaclab -n

首次创建小项目时，可选择以下选项：

  • External （外部）项目

  • 位于 Isaac Lab 仓库之外的父目录

  • 符合 Python 命名规则的项目名，例如 my_robot_project

  • 以个人或组织名称作为作者

  • Cartpole 初始内容

  • 任务系列名称，例如 balance

  • 机器人或配置名称，例如 cartpole

  • 无界面任务包不需要 Isaac Sim UI 扩展，选择 No

  • Manager-based | single-agent （基于管理器、单智能体）工作流

  • rsl_rl 库与 PPO 算法

提示会显示有效选项；允许多选时，输入以逗号分隔的选项编号。生成器在 <parent-directory>/<project-name> 下创建项目，并初始化 Git 仓库。

任务模板源码#

每种初始内容的任务模块分别保存在一个 Jinja 模板中： tools/template/templates/tasks/cartpole.jinja 或 tools/template/templates/tasks/stubbed.jinja 。每个文件包含所有受支持工作流的环境、配置及基于管理器的 MDP 模块，包括 AMP 变体。Jinja 宏渲染模块， files 映射将相对任务系列的路径与内容关联。生成器将这些文件写入生成的包结构。

共享项目基础设施、任务注册和智能体配置仍采用独立模板。Blank 项目使用共享基础设施，但不生成任务模块。

自动生成项目#

默认仍采用交互式提示。脚本或持续集成中，可传入 --non_interactive ，改用参数驱动的生成方式。最简的外部 Cartpole 命令如下：

uv run isaaclab --new --non_interactive \
   --project_path /work/projects \
   --name my_robot_project \
   --author "Example Author"

它默认使用 cartpole 内容、 balance 任务系列、 cartpole 机器人配置、基于管理器的单智能体工作流、RSL-RL 和 PPO。添加 --initial_content stubbed 可创建 Stubbed 项目；添加 --initial_content blank 可创建 Blank 项目。Blank 项目不含示例任务，因此不接受任务、工作流、库或算法选项。

通过以下参数覆盖默认值：

参数

含义

--task_type external|internal

默认生成外部项目，也可从源码检出目录生成内部任务。

--project_path PATH

外部项目的父目录，非交互模式下必需。

--name NAME

外部项目名或内部任务目录名，非交互模式下必需。 --project_name 是别名。

--author NAME

外部项目作者，必需。多位作者可重复传入此参数。

--initial_content blank|cartpole|stubbed

外部项目内容，默认为 cartpole 。

--task_name NAME 和 --robot_name NAME

任务系列和机器人或配置名称，默认为 balance 和 cartpole 。

--include_ui_extension

包含通过 Isaac Sim Extension Manager 加载项目所需的文件。

--workflow WORKFLOW

可重复选择 manager-based:single-agent 、 direct:single-agent 或 direct:multi-agent 。

--rl_library LIBRARY

可重复选择 rsl_rl 、 rl_games 、 skrl 或 sb3 。

--rl_algorithm ALGORITHM

可重复选择 ppo 等算法。为多个库分别选择算法时，可添加所选库前缀，例如 skrl:ippo 。

例如，创建直接工作流的单智能体与多智能体变体，并选择 SKRL 算法：

uv run isaaclab --new --non_interactive \
   --project_path /work/projects \
   --name multi_workflow_project \
   --author "Example Author" \
   --workflow direct:single-agent \
   --workflow direct:multi-agent \
   --rl_library skrl \
   --rl_algorithm skrl:ppo \
   --rl_algorithm skrl:ippo

如果未提供 --non_interactive ，配置项目内容的参数会被拒绝，避免意外参数悄然改变交互流程。运行 uv run isaaclab --new --help 查看完整命令参考。

在源码检出目录中，也可不经提示创建内部任务：

uv run isaaclab --new --non_interactive \
   --task_type internal \
   --name my_internal_task

进入生成的项目并创建环境：

cd <parent-directory>/my_robot_project
uv sync

默认环境包含所选强化学习库和不依赖 Kit 的 Newton 后端， 不会 安装 Isaac Sim。

对于 Cartpole 内容，列出任务名及其可用预设：

uv run isaaclab list_envs --show_presets

Blank 项目在你向 src/<project-name>/tasks 添加并导入 Gymnasium 注册代码之前，不会列出任何项目任务。

从输出中复制任务名，再运行快速冒烟测试：

uv run isaaclab random_agent --task <TASK_NAME> --num_envs 16 --viz newton_gl

如果环境启动且小车移动，项目就可以开始编辑。随后可使用与 Isaac Lab 相同的命令接口训练、回放策略：

uv run isaaclab train --rl_library rsl_rl --task <TASK_NAME>
uv run isaaclab play --rl_library rsl_rl --task <TASK_NAME> --checkpoint latest --viz newton_gl

选择可选功能与仿真后端#

默认 uv sync 安装不依赖 Kit 的 Newton 后端，不安装 Isaac Sim。生成项目的 [project.optional-dependencies] 表对应创建它时所用 Isaac Lab 包声明的所有可选依赖组，使后端、可视化器、强化学习、遥操作等功能依赖与该 Isaac Lab 版本保持一致。当前 Isaac Lab 包提供 rerun 、 viser 或 all 时，也会包含这些依赖组。

传入命令所需的各个可选依赖组。例如：

uv run --extra isaacsim isaaclab random_agent \
   --task <TASK_NAME> physics=isaacsim_physx

uv run --extra isaacsim --extra rerun isaaclab play \
   --rl_library skrl --task <TASK_NAME> --viz rerun

将 --extra 放在 isaaclab 前；命令需要多种功能时，重复传入。生成的 all 依赖组转交到 Isaac Lab 自身的 all ，其具体内容仍由对应版本定义。完整的版本专用列表见生成的 pyproject.toml 。后端与预设模型见 后端与预设 ；受支持的物理、渲染器、可视化器组合见 快速入门 。

理解生成的项目#

外部项目是一个可安装的 Python 包，采用持续维护的下游示例所用的标准 uv src 布局。根 pyproject.toml 声明包、开发工具、后端可选依赖和 isaaclab.tasks 入口。

项目名标识仓库和 Python 包。任务通用的 MDP 项位于单独命名的任务系列下；机器人专用场景、注册和智能体配置位于 config/<robot-name> 。这样，项目可以添加机器人配置而不复制任务 MDP，也可以添加任务系列而不新建仓库。

项目自己的 USD 文件和相关数据位于 src/<project-name>/assets/data 。项目的 assets 模块提供相对于包的 <PROJECT_NAME>_ASSETS_DIR 路径，使任务和资产配置无论在可编辑安装还是已安装 wheel 中，都能找到这些文件。生成的 .gitattributes 将 USD 文件交给 Git LFS 管理。

多个任务系列共享的代码可放在 tasks/mdp 等包中。生成的任务导入器在寻找任务注册时跳过名为 mdp 的包，因此共享模块不会被注册为任务系列。

Cartpole 项目结构如下：

my_robot_project/
├── LICENSE
├── pyproject.toml
├── README.md
├── scripts/
│   └── list_envs.py
├── src/
│   └── my_robot_project/
│       ├── __init__.py
│       ├── assets/
│       │   ├── __init__.py
│       │   └── data/
│       └── tasks/
│           ├── __init__.py
│           └── balance/
│               ├── mdp/
│               └── config/
│                   └── cartpole/
│                       ├── agents/
│                       └── env_cfg.py
└── tests/
    └── test_registration.py

生成的包 __init__.py 有意不主动执行注册。安装项目后，通过 isaaclab.tasks 入口提供 my_robot_project.tasks ，因此仅为使用工具而导入包时，不会立即注册任务。对于 Blank 内容，在添加并导入任务包之前， tasks 目录只包含 __init__.py 。

选择 Isaac Sim UI 扩展时，生成器还会创建 config/extension.toml 和 src/my_robot_project/ui_extension_example.py 。使用时，选择生成的 isaacsim 可选依赖组启动 Isaac Sim。默认是无界面任务包，不包含这些文件。

从项目根目录运行命令，使 uv 能找到包和任务入口。将 pyproject.toml 与 uv.lock 提交到版本控制，让协作者使用同一依赖解析结果。对于关联源码检出目录的项目，协作者还必须把该目录放在所记录的相对路径，或更新源码条目。

开发生成的任务#

训练前，先运行简单智能体。零动作智能体有助于检查重置与被动动力学；随机动作智能体还会运行动作和观测路径：

uv run isaaclab zero_agent --task <TASK_NAME> --num_envs 16
uv run isaaclab random_agent --task <TASK_NAME> --num_envs 16

两个命令都会运行到达到步数上限、可视化器关闭或按下 Ctrl+C。Ctrl+C 会关闭环境并退出，不打印异常堆栈。

编辑 src/<project-name>/tasks 下生成的环境配置和任务项。生成的包采用可编辑安装，无需每次修改后重新安装。

任务逐步完善后，可使用其余项目命令：

uv run isaaclab train_multigpu --rl_library <RL_LIBRARY> \
   --task <TASK_NAME> --num_gpus 2
uv run isaaclab benchmark runtime --task <TASK_NAME> \
   --num_envs 16 --num_steps 1000
uv run pre-commit run --all-files

生成器提供 tests/test_registration.py ，验证任务 ID、环境入口和默认智能体。 pyproject.toml 为开发安装 pytest，并注册 unit 、 integration 、 smoke 和 kitless 标记。在 tests 下添加项目自己的行为测试，再通过以下命令运行：

uv run pytest tests

source/isaaclab_tasks/test 下看似可复用的辅助工具属于 Isaac Lab 仓库测试套件，不随 isaaclab_tasks 安装。外部项目应使用公共 API 构建环境测试框架，并维护本地测试夹具。将 env_test_utils.py 复制到项目属于内置第三方代码，项目必须跟踪该副本对应的上游变更。

配置 VS Code 或 Cursor 时，运行生成的配置任务，或直接调用：

uv run isaaclab --editor

命令选择当前解释器，并创建由 Git 忽略的 pyrightconfig.json 。这个子配置继承 pyproject.toml 中已纳入版本控制的 Pyright 配置，并添加项目 src 导入根目录、已安装 Isaac Lab 包及发现的 Isaac Sim 扩展。使用 isaacsim 可选依赖组时，生成配置也应包含它：

uv run --extra isaacsim isaaclab --editor

VS Code 使用 Pylance，并选择执行配置命令的解释器。Cursor 则安装 detachhead.basedpyright 扩展替代 Pylance，选择同一解释器并重新加载窗口。两个语言服务器都读取生成的 pyrightconfig.json 。

创建内部任务#

只有在 Isaac Lab 源码检出目录中工作时，才选择 Internal 。生成器将新任务写入 source/isaaclab_tasks ，而不是创建独立项目。从 Isaac Lab 仓库根目录列出并测试任务：

uv run isaaclab list_envs --show_presets
uv run isaaclab random_agent --task <TASK_NAME> --num_envs 16
uv run isaaclab train --rl_library <RL_LIBRARY> --task <TASK_NAME>

如果生成任务对某个强化学习库只有一个入口，训练命令会自动选择对应智能体配置。如果生成了多个算法，或希望显式选择配置，则传入其注册的入口名称。非 PPO 入口包含算法名，例如：

uv run isaaclab train --rl_library rsl_rl --task <TASK_NAME> \
   --agent rsl_rl_distillation_cfg_entry_point

故障排除#

项目路径被拒绝

外部项目必须位于 Isaac Lab 仓库之外。输入父目录即可，生成器会自动追加项目名。

项目名被拒绝

使用由字母、数字和下划线组成的有效 Python 标识，不含空格或连字符，且不能以数字开头。

任务系列或机器人、配置名称被拒绝

每个名称都必须是有效 Python 标识，它们会成为 src/<project-name>/tasks 下的包目录。

命令行找不到生成的任务

运行 uv sync ，并从生成项目的根目录调用命令。确认任务出现在 uv run isaaclab list_envs 中。传入 --all 可包含所有已安装任务包中的任务，而不只列出当前项目 isaaclab.tasks 入口中的任务。

非交互参数被拒绝

在 --new 后加入 --non_interactive 。默认初始内容为 Cartpole；Blank 内容不接受任务、工作流、库和算法选项。错误消息会指出缺失的必需参数或不兼容的选择。

缺少可选后端模块

在命令前添加对应可选依赖组，例如 uv run --extra ovphysx isaaclab ... 或 uv run --extra isaacsim --extra rerun isaaclab ... 。当前 Isaac Lab 包提供的每个依赖组，都会复制到生成项目的可选依赖中。

生成器报告缺少模板依赖

当前版本从 Isaac Lab 环境获取模板渲染器和提示组件，无需手动 pip install 。更新 Isaac Lab 检出目录或已安装包，再次运行生成器。

生成的 README.md 包含同样的项目本地命令，应随项目发展保持更新。

目录