当你第一次克隆 ATOM01-Train 仓库时，面对分布在两个顶层目录下的数十个子模块，很可能会产生一个疑问："我应该从哪里开始阅读代码？" 本页面的目的正是为初学者建立一张清晰的代码地图。我们将从顶层仓库划分讲起，逐步拆解 robolab（环境与任务）和 rsl_rl（算法库）两大核心包的职责边界，并沿着一条典型的训练数据流梳理各组件的协作关系。阅读完本页后，你将能够根据需求快速定位到相关源码位置，为后续深入特定模块打下基础。

Sources: README_CN.md

顶层架构：双包协作设计

ATOM01-Train 采用物理环境与学习算法解耦的组织哲学。仓库根目录下有两个并列的 Python 包，分别承担截然不同的职责：

这种划分的直接好处是：你可以只修改 robolab 中的奖励函数或地形配置，而完全不用触碰 rsl_rl 中的算法代码。 反之，如果你想实验一种新的网络架构，也只需在 rsl_rl 的 modules/ 和 networks/ 中工作，环境侧不受影响。两者通过 Gymnasium 的环境注册机制与 RslRlVecEnvWrapper 完成对接。

以下 Mermaid 图展示了两个包与外部依赖（IsaacLab/IsaacSim）之间的宏观关系：

graph TB
    subgraph 外部依赖层
        ISAAC[IsaacSim / IsaacLab<br/>物理仿真与基础 API]
    end

    subgraph robolab 包
        ASSETS[assets/robots<br/>机器人 URDF 与关节配置]
        TASKS[tasks/<br/>direct & manager_based<br/>环境逻辑与 MDP]
        SCRIPTS[scripts/<br/>train.py / play.py]
        DATA[data/<br/>运动数据与地形资产]
    end

    subgraph rsl_rl 包
        NETS[networks/<br/>MLP / CNN / Attention]
        MODS[modules/<br/>ActorCritic / AMP / RND]
        ALGS[algorithms/<br/>PPO / PPOAMP / Distillation]
        RUNS[runners/<br/>OnPolicy / AMP / Distillation]
        STORE[storage/<br/>RolloutStorage]
    end

    ISAAC --> TASKS
    ASSETS --> TASKS
    DATA --> TASKS
    TASKS --> SCRIPTS
    SCRIPTS --> RUNS
    RUNS --> ALGS
    ALGS --> MODS
    MODS --> NETS
    RUNS --> STORE
    STORE --> ALGS

Sources: robolab/setup.py, rsl_rl/pyproject.toml

robolab：环境与任务定义

robolab 是你日常开发中最频繁接触的包。它的内部结构围绕**"资产 → 环境 → 脚本 → 数据"**这一链条展开。

1. 机器人资产（robolab/assets/）

assets/robots/roboparty.py 中定义了 ATOM01_CFG，它是一个 ArticulationCfg 对象，封装了 URDF 文件路径、碰撞属性、关节驱动参数等。所有任务共享这同一份机器人配置，因此如果你需要调整关节刚度或自碰撞设置，只需修改此处即可全局生效。

Sources: robolab/assets/robots/roboparty.py

2. 任务环境（robolab/tasks/）

这是代码量最大、层次最丰富的目录。IsaacLab 支持两种环境编写范式，本项目同时保留了两者：

在 direct/ 目录下，你又能看到三个子模块，它们对应不同的感知或控制增强：

• base/：最基础的 Direct RL 环境，包含 base_env.py（环境类）、base_config.py（配置基类）、mdp/（奖励与观测函数）、scene_cfg.py 与 terrain_generator_cfg.py（场景与地形）。后续衍生环境（如 attn_enc、interrupt）均继承自这里。
• attn_enc/：在基础环境之上引入了注意力编码器（Attention Encoder），用于处理高维感知输入（如高度扫描图）。
• interrupt/：支持中断与恢复训练的特殊环境变体。

在 manager_based/ 目录下：

• amp/：实现 AMP（Adversarial Motion Prior）对抗运动先验的模仿学习环境，包含 AmpEnv、AnimationEnv 以及专门的运动数据管理器 managers/。
• beyondmimic/：实现 BeyondMimic 框架的扩展模仿学习任务。

每个任务目录下的 agents/ 子文件夹存放着 RSL-RL 算法配置（如 atom01_agent_cfg.py），它们通过 Hydra 配置系统与训练脚本对接，定义了学习率、网络结构、PPO 超参数等。这其实是算法侧的配置，但放在环境目录中是为了遵循 IsaacLab 的注册惯例。

Sources: robolab/tasks/direct/base/base_env.py, robolab/tasks/manager_based/amp/amp_env.py, robolab/tasks/direct/base/agents/atom01_agent_cfg.py

3. 训练与部署脚本（robolab/scripts/）

脚本按用途被清晰地划分为三组：

初学者应重点关注 scripts/rsl_rl/train.py。它的执行逻辑非常清晰：解析命令行参数 → 启动 Isaac Sim → 通过 gym.make() 创建环境 → 包装为 RslRlVecEnvWrapper → 实例化 Runner → 调用 runner.learn() 开始训练。如果你想修改日志路径、添加视频录制或调整并行环境数量，都可以从这里入手。

Sources: robolab/scripts/rsl_rl/train.py, robolab/scripts/tools/list_envs.py

4. 数据资产（robolab/data/）

• robots/roboparty/：存放 ATOM01 的 URDF 文件、网格模型等静态资产。
• motions/：存放 AMP/BeyondMimic 所需的参考运动数据（如 atom01_gmr、atom01_lab）。这些数据通常通过 GMR 工具链预先处理，并在训练前进行关节顺序重定向。

Sources: robolab/data/

rsl_rl：算法与网络实现

rsl_rl 是一个独立安装的 Python 包（rsl-rl-lib），基于 ETH Zürich 的原始 RSL-RL 库进行了扩展。它的内部按数据流方向组织：网络层 → 模块层 → 算法层 → 调度层。

1. 基础网络（rsl_rl/networks/）

这里存放最底层的可复用网络组件：

• mlp.py：多层感知机
• cnn.py：卷积网络
• attn_encoder.py：注意力编码器
• memory.py：循环记忆网络（GRU/LSTM）
• normalization.py：观测归一化层（Running Mean/Std）

Sources: rsl_rl/networks/

2. 策略-价值模块（rsl_rl/modules/）

modules/ 将基础网络组装成完整的策略架构。初学者需要熟悉以下关键类：

Sources: rsl_rl/modules/init.py

3. 学习算法（rsl_rl/algorithms/）

目前包含三种算法实现：

• ppo.py：标准近端策略优化（PPO）
• ppo_amp.py：结合 AMP 判别器损失的 PPO 变体
• distillation.py：学生-教师策略蒸馏

算法类由 Runner 持有并调用，负责计算损失、执行梯度更新。

Sources: rsl_rl/algorithms/init.py

4. 训练调度器（rsl_rl/runners/）

Runner 是连接环境与算法的"胶水层"。它负责收集 Rollout、调用算法更新、记录日志、保存检查点。三种 Runner 对应三种训练模式：

• OnPolicyRunner：标准 on-policy 训练（PPO）
• AMPRunner：AMP 模仿学习训练
• DistillationRunner：学生-教师蒸馏训练

Sources: rsl_rl/runners/init.py

5. 数据存储（rsl_rl/storage/）

• rollout_storage.py：存储 on-policy 的 trajectory 数据（观测、动作、奖励、价值估计等），供 PPO 的批次采样使用。
• circular_buffer.py：AMP 中用于存储参考运动与策略历史的循环缓冲区。

Sources: rsl_rl/storage/

一条训练指令的数据流

为了帮助你建立端到端的结构认知，以下是一张展示从命令行到策略更新的完整数据流图。这张图涵盖了本页介绍的所有关键组件：

graph LR
    CLI[python train.py<br/>--task=Atom01-Direct-v1] --> REG[Gymnasium Registry<br/>robolab/tasks/__init__.py]
    REG --> ENV[IsaacLab Env<br/>BaseEnv / AmpEnv]
    ENV --> WRAP[RslRlVecEnvWrapper]
    WRAP --> RUNNER[Runner<br/>OnPolicy / AMP]
    RUNNER --> ALG[Algorithm<br/>PPO / PPOAMP]
    ALG --> NET[ActorCritic<br/>+ 可选 Attention/RND]
    NET --> ACT[动作输出]
    ACT --> ENV
    RUNNER --> STORE[RolloutStorage<br/>收集 trajectory]
    STORE --> ALG
    ALG --> UPD[梯度更新<br/>保存 checkpoint]

Sources: robolab/scripts/rsl_rl/train.py

环境注册机制：任务名是如何被识别的？

IsaacLab 使用 Gymnasium 的注册系统来管理环境。当你执行 python train.py --task=Atom01-Direct-v1 时，以下步骤在幕后发生：

1. train.py 通过 import robolab.tasks 触发各子包的 __init__.py 加载。
2. robolab/tasks/__init__.py 调用 import_packages()，自动扫描所有子目录下的配置文件。
3. 每个环境配置类（如 atom01_env_cfg.py）通过装饰器或入口点字符串向 Gymnasium 注册一个任务 ID（如 Atom01-Direct-v1）。
4. gym.make() 根据任务 ID 找到对应的入口点，实例化环境类与配置对象。

你可以随时运行 python robolab/scripts/tools/list_envs.py 查看当前所有已注册的环境名称、入口点和配置文件路径。

Sources: robolab/tasks/init.py, robolab/scripts/tools/list_envs.py

给初学者的代码阅读路线图

项目结构导读的目标是帮你建立"在哪里找什么"的直觉。以下是一条按优先级排序的推荐阅读路径，每个链接对应导航目录中的独立详解页面：

1. 理解训练入口：先通读 robolab/scripts/rsl_rl/train.py，建立端到端概念。
2. 选择你的环境范式：
   • 如果你想快速理解环境逻辑，阅读 Direct RL 环境架构。
   • 如果你更习惯 IsaacLab 的管理器模式，阅读 Manager-based 环境架构。
3. 查看机器人配置：了解 robolab/assets/robots/roboparty.py 中的 ATOM01_CFG。
4. 运行第一个训练：跟随 训练你的第一个策略 的逐步指引。
5. 按需深入算法：当需要调整网络结构或理解损失计算时，再进入 RSL-RL 算法库 相关章节。

记住，不要试图在第一天就读懂所有文件。ATOM01-Train 的模块化设计允许你每次只聚焦一个包、一个目录、一个文件，逐步构建对整个系统的完整认知。