chore: release v0.0.1

docs/source/zh_CN/index.md

@@ -0,0 +1,66 @@
+# MotrixLab
+
+MotrixLab 是一个为机器人训练设计的机器学习通用架构。它基于 MotrixSim 仿真平台搭建，可以实现在 CPU 或 GPU 上的策略训练，为各类操作系统和硬件设备使用者，提供灵活易用的训练能力。
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 2 2
+
+:::{grid-item-card}
+
+```{video} _static/videos/cartpole.mp4
+:poster: _static/images/poster/cartpole.jpg
+:nocontrols:
+:autoplay:
+:playsinline:
+:muted:
+:loop:
+:width: 100%
+```
+
+:::
+
+:::{grid-item-card}
+
+```{video} _static/videos/go1_walk.mp4
+:poster: _static/images/poster/go1_walk.jpg
+:nocontrols:
+:autoplay:
+:playsinline:
+:muted:
+:loop:
+:width: 100%
+```
+
+:::
+
+:::{grid-item-card}
+
+```{video} _static/videos/dm_walker.mp4
+:poster: _static/images/poster/dm_walker.jpg
+:nocontrols:
+:autoplay:
+:playsinline:
+:muted:
+:loop:
+:width: 100%
+```
+
+:::
+::::
+
+## 主要特性
+
+-   **跨软件平台能力**: 支持 Windows 和 Linux 操作系统环境
+-   **支持 CPU 仿真**: 使用 MotrixSim 在 CPU 上进行物理仿真，对 GPU 的要求大幅降低
+
+## 适用场景
+
+-   机器人控制算法开发和测试
+-   强化学习环境构建
+-   教育和研究
+
+```{toctree}
+:maxdepth: 1
+
+user_guide/index
+```

docs/source/zh_CN/user_guide/demo/cartpole.md

@@ -0,0 +1,99 @@
+# 倒立摆训练示例
+
+倒立摆（CartPole）是强化学习中的经典控制任务，目标是通过控制小车左右移动来保持杆子平衡。
+![cartpole](/_static/images/poster/cartpole.jpg)
+
+## 任务描述
+
+-   **状态空间**：小车位置、小车速度、杆子角度、杆子角速度
+-   **动作空间**：向左或向右施加力
+-   **奖励函数**：每一步保持杆子不倒下获得+1 奖励
+-   **终止条件**：杆子角度超过 ±15 度或 episode 长度超过 10 秒
+
+## 快速开始
+
+### 1. 环境预览
+
+```bash
+uv run scripts/view.py --env cartpole
+```
+
+### 2. 开始训练
+
+```bash
+# 使用默认参数训练
+uv run scripts/train.py --env cartpole
+
+# 自定义环境数量
+uv run scripts/train.py --env cartpole --num-envs 1024
+
+# 启用渲染（训练时可视化）
+uv run scripts/train.py --env cartpole --render
+```
+
+### 3. 查看训练进度
+
+```bash
+uv run tensorboard --logdir runs/cartpole
+```
+
+### 4. 测试训练结果
+
+```bash
+# 自动寻找最佳策略测试（推荐）
+uv run scripts/play.py --env cartpole
+
+# 手动指定策略文件测试
+uv run scripts/play.py --env cartpole --policy runs/cartpole/nn/best_agent.pickle
+
+```
+
+> **提示**：系统会自动在 `runs/cartpole/` 目录下寻找最新、最佳的策略文件进行测试。您也可以通过 `--policy` 参数手动指定特定的策略文件。
+
+## 配置参数
+
+倒立摆环境的主要配置参数：
+
+```python
+@dataclass
+class CartPoleEnvCfg(EnvCfg):
+    model_file: str = "path/to/inverted_pendulum.xml"  # MJCF模型文件
+    reset_noise_scale: float = 0.01                    # 重置噪声
+    max_episode_seconds: float = 10.0                 # 最大episode长度
+```
+
+训练配置参数：
+
+```python
+@dataclass
+class CartPoleRLCfg(BaseRLCfg):
+    num_envs: int = 2048                    # 并行环境数量
+    learning_rate: float = 3e-4             # 学习率
+    batch_size: int = 2048                  # 批大小
+    max_epochs: int = 500                   # 最大训练轮数
+```
+
+## 自定义训练
+
+您可以通过命令行参数覆盖默认配置：
+
+```bash
+uv run scripts/train.py --env cartpole \
+  --num-envs 1024 \
+  --train-backend jax \
+  --sim-backend np
+```
+
+## 预期结果
+
+-   杆子角度大部分时间保持在 ±5 度以内
+-   小车位移范围适中
+
+## 故障排除
+
+如果训练效果不佳，可以尝试：
+
+1. 调整学习率（尝试 1e-4 到 1e-3）
+2. 增加环境数量（更多并行训练）
+3. 调整奖励函数权重
+4. 检查物理参数设置是否合理

docs/source/zh_CN/user_guide/demo/dm_walker.md

@@ -0,0 +1,102 @@
+# 二维步行机器人训练示例
+
+二维步行机器人（Walker2D）是基于 DeepMind Control Suite 的经典机器人控制任务，目标是通过控制机器人关节来实现站立、行走和奔跑。
+
+```{video} /_static/videos/dm_walker.mp4
+:poster: _static/images/poster/dm_walker.jpg
+:nocontrols:
+:autoplay:
+:playsinline:
+:muted:
+:loop:
+:width: 100%
+```
+
+## 任务描述
+
+Walker2D 是一个二维平面的双足机器人，具有多个关节和执行器：
+
+-   **状态空间**：包括机器人各部位的旋转角度、角速度、躯干高度和速度等
+-   **动作空间**：控制各个关节的力矩
+-   **奖励函数**：主要由保持站立、前进速度等组成
+-   **终止条件**：机器人摔倒或关节达到极限位置
+
+### 三种任务模式
+
+1. **dm-stander**: 静止站立任务 (move_speed = 0.0)
+
+```bash
+uv run scripts/train.py --env dm-stander
+```
+
+2. **dm-walker**: 行走任务 (move_speed = 1.0)
+
+```bash
+uv run scripts/train.py --env dm-walker
+```
+
+3. **dm-runner**: 奔跑任务 (move_speed = 5.0)
+
+```bash
+uv run scripts/train.py --env dm-runner
+```
+
+## 配置参数
+
+### 环境配置
+
+```python
+@dataclass
+class WalkerEnvCfg(EnvCfg):
+    model_file: str = "walker.xml"           # MJCF模型文件
+    max_episode_seconds: float = 25.0        # 最大episode长度
+    sim_dt: float = 0.0125                   # 仿真时间步
+    ctrl_dt: float = 0.025                   # 控制时间步
+    move_speed: float = 1.0                  # 目标移动速度
+    stand_height: float = 1.2                # 目标站立高度
+```
+
+### 训练配置
+
+```python
+@dataclass
+class WalkerRLCfg(BaseRLCfg):
+    num_envs: int = 512                      # 并行环境数量
+    learning_rate: float = 3e-4              # 学习率
+    batch_size: int = 512                    # 批大小
+    max_epochs: int = 1000                   # 最大训练轮数
+```
+
+## 奖励函数设计
+
+Walker2D 的奖励函数由以下几个部分组成：
+
+### 基础站立奖励
+
+```python
+# 高度奖励：保持躯干在目标高度
+# 直立奖励：保持躯干直立
+```
+
+### 移动奖励（行走和奔跑任务）
+
+```python
+# 速度奖励：追踪目标速度
+# 总奖励 = 站立奖励 * 移动权重
+```
+
+## 预期结果
+
+1. **dm-stander**：
+
+    - 躯干高度保持在 1.0-1.4m 范围
+    - 躯干直立角度偏差小于 15 度
+
+2. **dm-walker**：
+
+    - 实际行走速度接近 1.0 m/s
+    - 步态协调，无明显摔倒
+
+3. **dm-runner**：
+    - 奔跑速度达到 4.0-5.0 m/s
+    - 出现飞行相（双脚同时离地）

docs/source/zh_CN/user_guide/demo/locomotion_unitree_go1.md

@@ -0,0 +1,139 @@
+# Unitree GO1 机器人行走训练示例
+
+Unitree GO1 是一个四足机器人平台，本示例展示了如何训练 GO1 在平坦地形上实现稳定的步态行走。
+
+```{video} /_static/videos/go1_walk.mp4
+:poster: _static/images/poster/go1_walk.jpg
+:nocontrols:
+:autoplay:
+:playsinline:
+:muted:
+:loop:
+:width: 100%
+```
+
+## 任务描述
+
+GO1 四足机器人具有 12 个自由度（每条腿 3 个关节），需要通过深度强化学习学习协调的步态控制：
+
+-   **状态空间**：48 维，包含机器人线速度、角速度、姿态、关节角度、关节速度、动作和命令等
+-   **动作空间**：12 维，控制各个关节的目标位置（通过 PD 控制器转换为力矩）
+-   **奖励函数**：复合奖励，包含速度跟踪、姿态稳定、能量效率等多个组件
+-   **终止条件**：机器人躯干接触地面或其他不稳定状态
+
+### 训练任务
+
+```bash
+uv run scripts/train.py --env go1-flat-terrain-walk
+```
+
+## 配置参数
+
+### 环境配置
+
+```python
+@dataclass
+class Go1WalkNpEnvCfg(EnvCfg):
+    max_episode_seconds: float = 20.0      # 最大episode长度
+    model_file: str = "scene_motor_actuator.xml"
+    sim_dt: float = 0.01                   # 仿真时间步
+    ctrl_dt: float = 0.01                  # 控制时间步
+```
+
+### 控制配置
+
+```python
+@dataclass
+class ControlConfig:
+    stiffness = 80                         # PD 控制器刚度 [N*m/rad]
+    damping = 1                            # PD 控制器阻尼 [N*m*s/rad]
+    action_scale = 0.05                    # 动作缩放因子
+```
+
+### 初始关节角度
+
+```python
+default_joint_angles = {
+    "FL_hip": 0.0,      # 前左髋关节
+    "RL_hip": 0.0,      # 后左髋关节
+    "FR_hip": -0.0,     # 前右髋关节
+    "RR_hip": -0.0,     # 后右髋关节
+    "FL_thigh": 0.9,    # 前左大腿
+    "RL_thigh": 0.9,    # 后左大腿
+    "FR_thigh": 0.9,    # 前右大腿
+    "RR_thigh": 0.9,    # 后右大腿
+    "FL_calf": -1.8,    # 前左小腿
+    "RL_calf": -1.8,    # 后左小腿
+    "FR_calf": -1.8,    # 前右小腿
+    "RR_calf": -1.8,    # 后右小腿
+}
+```
+
+## 奖励函数设计
+
+GO1 的奖励函数是一个复杂的复合函数，包含多个组件：
+
+### 主要奖励组件
+
+```python
+reward_config.scales = {
+    "tracking_lin_vel": 1.0,      # 线速度跟踪奖励
+    "tracking_ang_vel": 0.5,      # 角速度跟踪奖励
+    "feet_air_time": 1.0,         # 足部空中时间奖励
+    "lin_vel_z": -2.0,            # Z轴线速度惩罚
+    "ang_vel_xy": -0.05,          # XY轴角速度惩罚
+    "orientation": -0.0,          # 姿态偏离惩罚
+    "torques": -0.00001,          # 力矩消耗惩罚
+    "dof_acc": -2.5e-7,           # 关节加速度惩罚
+    "action_rate": -0.001,        # 动作变化率惩罚
+    "hip_pos": -1,                # 髋关节位置惩罚
+    "calf_pos": -0.3,             # 腿关节位置惩罚
+}
+```
+
+### 关键奖励函数
+
+#### 速度跟踪奖励
+
+```python
+# 跟踪线速度命令（xy平面）
+def _reward_tracking_lin_vel(self, data, commands):
+
+# 跟踪角速度命令（偏航）
+def _reward_tracking_ang_vel(self, data, commands):
+```
+
+#### 足部空中时间奖励
+
+```python
+def _reward_feet_air_time(self, commands, info):
+```
+
+## 观察空间构成
+
+GO1 的观察空间为 48 维，包含以下信息：
+
+```python
+obs = np.hstack([
+    noisy_linvel,        # 3维：局部坐标系线速度
+    noisy_gyro,          # 3维：陀螺仪数据
+    local_gravity,       # 3维：局部重力方向
+    noisy_joint_angle,   # 12维：关节角度（相对于默认值）
+    noisy_joint_vel,     # 12维：关节速度
+    last_actions,        # 12维：上一帧动作
+    command,             # 3维：速度命令 [vx, vy, vyaw]
+])
+```
+
+## 运动速度命令生成
+
+训练过程中随机生成速度命令，确保智能体能够跟踪不同的移动速度：
+
+```python
+def resample_commands(self, num_envs: int):
+```
+
+## 预期训练结果
+
+1. 稳定的四足步态
+2. 良好的速度跟踪

docs/source/zh_CN/user_guide/getting_started/hello_motrixlab.md

@@ -0,0 +1,84 @@
+# 快速入门：Hello MotrixLab
+
+本教程通过演示一个简单例子 - 加载倒立摆并进行训练，以此来展示 MotrixLab 工作流程：
+
+## 环境预览
+
+我们提供了一个简单的脚本，用于可视化一个环境，而不执行任何训练，这可以帮助您检测系统的环境依赖是否配置正确：
+
+```bash
+uv run scripts/view.py --env cartpole
+```
+
+这将打开一个可视化窗口，显示倒立摆的物理仿真环境，使用随机动作进行演示。
+
+## 训练模型
+
+开始训练倒立摆平衡任务：
+
+```bash
+uv run scripts/train.py --env cartpole
+```
+
+训练过程会自动：
+
+1. 根据硬件环境自动选择训练后端（JAX 或 PyTorch）
+2. 创建训练环境
+3. 开始 PPO 算法训练
+
+训练结果会保存在 `runs/cartpole/` 目录下，包含：
+
+-   训练检查点（checkpoint）
+-   TensorBoard 日志文件
+
+## 可视化训练过程
+
+如果您想要在训练过程中观察模型的学习过程，可以启用可视化渲染：
+
+```bash
+uv run scripts/train.py --env cartpole --render
+```
+
+### 🎮 交互式渲染控制
+
+> **重要提示**：可视化会显著降低训练速度，建议主要用于调试和演示。
+
+在可视化训练过程中，您可以使用**空格键**来动态控制渲染：
+
+-   **开启渲染**：按下空格键开启可视化，观察机器人行为
+-   **关闭渲染**：再次按下空格键关闭渲染，提升训练速度
+-   **随时切换**：无需重新启动程序，可以在训练过程中随时切换
+
+这种交互式控制让您可以在需要时观察训练效果，在不需要时享受快速训练。这项功能在运行推断时也能生效。
+
+## 查看训练结果
+
+使用 TensorBoard 查看训练进度：
+
+```bash
+uv run tensorboard --logdir runs/cartpole
+```
+
+## 测试训练好的模型
+
+训练完成后，使用训练好的策略进行测试：
+
+```bash
+# 自动寻找最佳策略测试（推荐）
+uv run scripts/play.py --env cartpole
+
+# 手动指定策略文件测试（如果需要特定版本）
+uv run scripts/play.py --env cartpole --policy runs/cartpole/YOUR_RESULT_NUMBER/best_agent.pickle
+```
+
+> **提示**：系统会自动在 `runs/cartpole/` 目录下寻找最新、最佳的策略文件。通常情况下，使用自动发现功能即可。
+
+## 至此我们完成了整个示例
+
+接下来可以尝试修改参数，观察不同设置下的物理效果，或者尝试其他环境。
+
+## 下一步
+
+-   了解 [基础框架](../tutorial/basic_frame.md)
+-   学习 [物理环境配置](../tutorial/physics_environment.md)
+-   查看更多 [训练示例](../demo/cartpole.md)

docs/source/zh_CN/user_guide/getting_started/installation.md

@@ -0,0 +1,57 @@
+# 安装环境
+
+## 安装要求
+
+-   **Python 版本**：{bdg-danger-line}`3.10.*`
+
+    | Python 版本 | 支持状态 |
+    | :---------: | :------: |
+    |    ≤ 3.9    |    ❌    |
+    |    3.10     |    ✅    |
+    |   ≥ 3.11    |    ❌    |
+
+-   **包管理器**：{bdg-danger-line}`UV`
+    [UV 安装参考](https://docs.astral.sh/uv/getting-started/installation/)
+
+-   **系统及架构**：
+
+    -   {bdg-danger-line}`Windows(x86_64)`
+    -   {bdg-danger-line}`Linux(x86_64)`
+
+    ```{note}
+    各平台支持的功能如下：
+
+    | 操作系统 | CPU 仿真 | 交互式查看器 | GPU 仿真 |
+    | :------: | :------: | :----------: | :------: |
+    |  Linux   |    ✅    |      ✅      |    🛠️ 开发中    |
+    | Windows  |    ✅    |      ✅      |    🛠️ 开发中    |
+    ```
+
+## 安装方法
+
+### 克隆项目
+
+```bash
+git clone https://github.com/Motphys/MotrixLab.git
+cd MotrixLab
+```
+
+### 安装依赖
+
+使用 UV 安装项目依赖：
+
+```bash
+# 安装所有依赖
+uv sync --all-packages --all-extras
+```
+
+如果只需要安装一种训练后端，可以选择单独安装指定的后端类型：
+
+```bash
+
+# 安装 SKRL JAX （仅支持 Linux 平台）
+uv sync --all-packages --extra skrl-jax
+
+# 安装 SKRL PyTorch
+uv sync --all-packages --extra skrl-torch
+```

docs/source/zh_CN/user_guide/index.md

@@ -0,0 +1,32 @@
+# 用户指南
+
+```{toctree}
+:caption: 入门指南
+:maxdepth: 1
+
+getting_started/installation
+getting_started/hello_motrixlab
+
+```
+
+```{toctree}
+:caption: 使用教程
+:maxdepth: 1
+
+tutorial/basic_frame
+tutorial/physics_environment
+tutorial/training_environment_config
+tutorial/rewards
+tutorial/training_and_result
+
+```
+
+```{toctree}
+:caption: 训练示例
+:maxdepth: 1
+
+demo/cartpole
+demo/dm_walker
+demo/locomotion_unitree_go1
+
+```

docs/source/zh_CN/user_guide/tutorial/basic_frame.md

@@ -0,0 +1,149 @@
+# 基础框架
+
+MotrixLab 是一个机器人强化学习平台，这一节我们会介绍 MotrixLab 的框架设计以及各个组成部分之间的关系。如果您已经熟悉强化学习的内容，可以直接跳转至下一节，了解如何开发自己的训练环境。
+
+## MotrixLab 的框架设计
+
+MotrixLab 采用分层架构设计，将训练环境与训练逻辑进行了清晰拆分：
+
+```
+MotrixLab/
+├── motrix_envs/               # 环境层：物理仿真和任务定义
+│   ├── basic/                  # 基础环境（cartpole、walker等）
+│   ├── locomotion/             # 运动环境（GO1机器人等）
+│   ├── np/                     # NumPy仿真后端框架
+│   ├── base.py                 # 环境基类
+│   └── registry.py             # 环境注册系统
+├── motrix_rl/                # 训练层：RL算法和配置
+│   ├── skrl/                   # SKRL框架集成（JAX/PyTorch）
+│   ├── base.py                 # RL配置基类
+│   └── registry.py             # RL配置注册系统
+└── scripts
+    ├── train.py                # 训练入口脚本
+    ├── play.py                 # 测试入口脚本
+    └── view.py                 # 可视化脚本
+```
+
+## 核心组件架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        用户接口层                                │
+│                    train.py │ play.py │ view.py                   │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      训练算法层 (SKRL)                          │
+│                    PPO训练器 │ 网络架构 │ 优化器                 │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      环境实现层                                  │
+│  环境配置(EnvCfg) │ 环境实现(Env) │ 奖励函数(Reward)            │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    物理仿真层 (MotrixSim)                       │
+│                    MJCF模型 │ 物理引擎 │ 碰撞检测                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 核心组件详解
+
+### 1. 训练环境 (Training Environment)
+
+**位置**：环境实现层
+
+训练环境是 MotrixLab 的核心组件，包含三个关键部分：
+
+-   **环境配置 (EnvCfg)**：定义物理仿真参数（模型文件、时间步长、episode 长度等）和任务特定参数
+-   **环境实现 (Env)**：继承基础环境类，实现具体的任务逻辑、物理仿真交互和终止条件检查
+-   **奖励函数 (Reward)**：在环境的 step 方法中实现，根据当前状态和动作计算奖励值
+
+环境通过装饰器注册到系统中。
+
+### 2. 奖励函数 (Reward Function)
+
+**位置**：配置管理层 + 环境实现层
+
+奖励函数在 MotrixLab 中采用双重结构设计：
+
+-   **配置层面**：在配置类中定义奖励权重、奖励组件类型和缩放参数
+-   **实现层面**：在环境的 `_compute_reward` 方法中根据配置参数计算具体奖励值
+
+这种设计使得奖励函数既可以通过配置文件灵活调整，又能在代码中实现复杂的计算逻辑。
+
+### 3. 配置参数 (Configuration Parameters)
+
+**位置**：配置管理层
+
+配置参数采用分层管理结构：
+
+-   **环境配置 (EnvCfg)**：控制物理仿真和任务行为，包括仿真参数、重置噪声、时间限制等
+-   **训练配置 (RLCfg)**：控制强化学习算法，包括网络结构、学习率、批次大小、训练步数等
+
+配置类支持继承、参数验证和运行时覆盖，确保参数的合理性和灵活性。
+
+### 4. 注册系统 (Registry System)
+
+**位置**：连接各组件的枢纽
+
+注册系统通过装饰器模式实现组件的自动注册：
+
+-   环境配置类通过 `@registry.envcfg()` 注册
+-   环境实现类通过 `@registry.env()` 注册，支持多后端
+-   RL 配置类通过 `@rlcfg()` 注册
+
+注册系统实现了组件的解耦，使得新增环境或修改配置变得简单快捷。
+
+## 数据流和工作流程
+
+### 训练流程概览
+
+```
+用户命令 → 配置解析 → 环境创建 → 训练循环 → 模型保存
+   ↓
+train.py --env cartpole
+   ↓
+查找配置类 → 创建环境 → 启动PPO训练 → 保存模型
+```
+
+### 核心工作流程
+
+1. **环境定义**：在 `/motrix_envs/` 中创建环境配置类和实现类
+2. **自动注册**：通过装饰器将组件注册到系统中
+3. **配置加载**：命令行启动时，系统自动查找并加载对应的配置
+4. **环境创建**：工厂模式创建环境实例，支持参数覆盖
+5. **训练执行**：PPO 算法与环境交互，收集数据并更新策略
+6. **结果保存**：定期保存检查点和最终模型
+
+### 配置参数的作用
+
+配置参数在整个流程中起到关键的连接作用：
+
+-   **环境配置**决定物理仿真行为（时间步长、模型文件、噪声等）
+-   **奖励配置**影响学习信号（奖励权重、计算方式等）
+-   **训练配置**控制算法行为（网络结构、学习率、批次大小等）
+
+## 多后端支持
+
+MotrixLab 的分层设计天然支持多种后端：
+
+-   **仿真后端**：MotrixSim
+-   **训练后端**：JAX 和 PyTorch，支持 GPU 加速
+-   **算法框架**：主要集成 SKRL，易于扩展其他算法
+
+## 设计优势
+
+这种架构设计带来了以下核心优势：
+
+1. **模块解耦**：环境开发与训练逻辑完全分离
+2. **配置灵活**：支持分层配置和运行时参数覆盖
+3. **扩展性强**：通过注册系统轻松添加新组件
+4. **多后端兼容**：同一环境可使用不同仿真和训练后端
+5. **实验友好**：配置可保存、比较，确保实验可重现
+
+通过这个框架设计，MotrixLab 为机器人强化学习提供了一个清晰、灵活且易用的开发平台。

docs/source/zh_CN/user_guide/tutorial/physics_environment.md

@@ -0,0 +1,61 @@
+# 物理环境配置
+
+物理环境配置定义了强化学习训练中的仿真参数和模型文件设置。
+MotrixLab 使用了[MotrixSim](https://motrixsim.readthedocs.io/zh-cn/latest/user_guide/index.html)作为物理仿真后端。
+
+## 支持的文件格式
+
+-   [**MJCF**](https://mujoco.readthedocs.io/en/stable/XMLreference.html)(MuJoCo XML 格式) - 提供丰富的物理特性和仿真配置
+
+## 模型文件配置
+
+需要在环境配置类中指定模型文件路径：
+
+```python
+@registry.envcfg("my-task")
+@dataclass
+class MyTaskEnvCfg(EnvCfg):
+    # 模型文件路径（必需）
+    model_file: str = "my_model.xml"
+
+    # 仿真时间参数
+    sim_dt: float = 0.002      # 仿真时间步
+    ctrl_dt: float = 0.02      # 控制更新频率
+```
+
+### 推荐目录结构
+
+```
+motrix_envs/my_task/
+├── __init__.py          # 模块初始化
+├── cfg.py               # 环境配置
+├── my_model.xml         # 物理模型文件
+└── my_env.py            # 环境实现
+```
+
+对于结构复杂，引用文件较多的模型，推荐使用文件夹管理。
+
+## 常见配置问题
+
+### 文件路径问题
+
+-   使用相对路径时，确保路径相对于配置文件位置
+-   避免使用硬编码的绝对路径
+-   检查文件权限和可访问性
+-   确保所有引用的子文件都存在
+
+### 时间步设置
+
+-   `ctrl_dt` 应该是 `sim_dt` 的整数倍
+-   `sim_dt` 过小会影响仿真性能
+-   `ctrl_dt` 过大会影响控制精度
+-   推荐 `sim_dt` 在 0.001-0.02 秒之间
+
+### 仿真稳定性
+
+-   避免过大的时间步长
+-   合理设置接触参数避免穿透
+-   质量和惯性分布要合理
+-   关节限制要符合实际情况
+
+通过合理的物理环境配置，您可以为强化学习训练创建准确且高效的仿真环境。

docs/source/zh_CN/user_guide/tutorial/rewards.md

@@ -0,0 +1,50 @@
+# 奖励函数设计
+
+奖励函数告诉智能体什么样的行为是期望的，是强化学习环境设计中的核心部分。
+
+## 奖励函数在训练循环中的位置
+
+在 MotrixLab 的 NpEnv 中，奖励计算发生在 `step` 函数的 `update_state` 阶段：
+
+```python
+# NpEnv.step() 的执行流程
+def step(self, actions: np.ndarray) -> NpEnvState:
+    # 1. 准备阶段：清空奖励和状态
+    self._prev_physics_step()  # reward = 0.0, terminated = False, truncated = False
+
+    # 2. 应用动作
+    self._state = self.apply_action(actions, self._state)
+
+    # 3. 物理仿真
+    self.physics_step()  # 执行物理仿真
+
+    # 4. 更新状态 ← 奖励函数在这里计算
+    self._state = self.update_state(self._state)  # 计算奖励和观察值
+
+    # 5. 后续处理
+    self._update_truncate()  # 检查时间截断
+    self._reset_done_envs()  # 重置完成的环境
+
+    return self._state
+```
+
+您需要在子类的 `update_state` 方法中实现奖励计算逻辑，具体奖励函数设计思路请参考训练示例。
+
+### 奖励组件设计原则
+
+1. **分离关注点**：每个奖励函数负责一个特定的目标
+2. **权重配置**：通过配置文件管理不同组件的权重
+3. **归一化**：保持奖励值在合理的范围内
+4. **平滑性**：避免硬性阈值，使用指数函数等平滑过渡
+
+这种方法使得奖励函数模块化，便于调试和调整各个组件的权重。
+
+## 设计原则
+
+1. **明确的目标导向**：奖励函数应该直接反映任务目标
+2. **合理的奖励范围**：避免过大或过小的奖励值，保持训练稳定
+3. **平衡探索与利用**：适当奖励接近目标的行为，避免稀疏奖励
+4. **避免奖励漏洞**：检查智能体是否可能通过不期望的方式获得高奖励
+5. **调试友好**：在开发阶段输出奖励分解信息，便于调优
+
+通过在 `update_state` 方法中正确实现奖励计算，您可以为各种机器人任务设计有效的学习信号。

docs/source/zh_CN/user_guide/tutorial/training_and_result.md

@@ -0,0 +1,79 @@
+# 训练执行和结果分析
+
+本节介绍如何执行强化学习训练，以及如何分析和使用训练结果。
+
+## 启动训练
+
+### 基本训练命令
+
+```bash
+# 使用默认参数训练
+uv run scripts/train.py --env cartpole
+
+# 指定仿真后端
+uv run scripts/train.py --env cartpole --sim-backend np
+
+# 指定训练后端
+uv run scripts/train.py --env cartpole --train-backend jax
+uv run scripts/train.py --env cartpole --train-backend torch
+```
+
+### 高级训练配置
+
+```bash
+# 自定义训练参数
+uv run scripts/train.py --env cartpole \
+  --num-envs 1024 \
+  --train-backend jax \
+  --sim-backend np
+
+# 注意：学习率等参数需要通过配置文件或代码覆盖设置
+
+# 启用渲染监控训练过程
+uv run scripts/train.py --env cartpole --render
+```
+
+### 支持的命令行参数
+
+| 参数              | 说明                 | 默认值     |
+| ----------------- | -------------------- | ---------- |
+| `--env`           | 环境名称             | `cartpole` |
+| `--sim-backend`   | 仿真后端 (np)        | 自动选择   |
+| `--train-backend` | 训练后端 (jax/torch) | 自动选择   |
+| `--num-envs`      | 并行环境数量         | 2048       |
+| `--render`        | 启用渲染             | False      |
+
+> **注意**: 其他参数如学习率、网络结构等需要通过单独文件设置。
+
+## 训练过程监控
+
+### TensorBoard 监控
+
+启动 TensorBoard 查看训练进度：
+
+```bash
+uv run tensorboard --logdir runs/{env-name}
+```
+
+例如：
+
+```bash
+uv run tensorboard --logdir runs/cartpole
+```
+
+## 模型评估和测试
+
+### 使用训练好的策略
+
+```bash
+# 自动寻找最佳策略测试（推荐）
+uv run scripts/play.py --env cartpole
+
+# 手动指定策略文件测试
+uv run scripts/play.py --env cartpole --policy runs/cartpole/nn/best_agent.pickle
+
+# 指定测试环境数量
+uv run scripts/play.py --env cartpole --num-envs 100
+```
+
+> **说明**：系统会自动在 `runs/cartpole/` 目录下寻找最新、最佳的策略文件进行测试。

docs/source/zh_CN/user_guide/tutorial/training_environment_config.md

@@ -0,0 +1,178 @@
+# 训练环境配置
+
+MotrixLab 提供了灵活的配置系统，允许用户自定义强化学习训练参数。本节介绍如何配置训练环境和强化学习算法参数。
+
+## RL 训练配置 (PPOCfg)
+
+训练配置定义了基于 PPO 算法的强化学习算法的参数。MotrixLab 现在支持为不同训练后端配置不同的参数。
+
+### 完整配置示例
+
+```python
+@dataclass
+class CompletePPOConfig(PPOCfg):
+    """
+    完整的强化学习训练配置示例
+    包含了从基础到高级的所有配置参数
+    """
+
+    # ===== 基础训练参数 =====
+    seed: Optional[int] = None         # 随机种子
+    num_envs: int = 2048               # 训练时并行环境数量
+    play_num_envs: int = 16            # 评估时并行环境数量
+    max_env_steps: int = 2_048_000     # 最大训练步数
+    check_point_interval: int = 1000   # 检查点保存间隔
+
+    # ===== PPO算法核心参数 =====
+    learning_rate: float = 3e-4        # 学习率
+    rollouts: int = 32                 # 经验回放轮数
+    learning_epochs: int = 2           # 每次更新的训练轮数
+    mini_batches: int = 32             # 小批量数量
+    discount_factor: float = 0.99      # 折扣因子
+    lambda_param: float = 0.95         # GAE参数
+    grad_norm_clip: float = 1.0        # 梯度裁剪
+
+    # ===== PPO裁剪参数 =====
+    ratio_clip: float = 0.2            # PPO裁剪比率
+    value_clip: float = 0.2            # 价值裁剪
+    clip_predicted_values: bool = True # 裁剪预测值
+
+    # ===== 损失函数参数 =====
+    entropy_loss_scale: float = 0.0    # 熵损失系数
+    value_loss_scale: float = 2.0      # 价值损失系数
+    kl_threshold: float = 0            # KL散度阈值
+
+    # ===== 学习率调度器 =====
+    learning_rate_scheduler_kl_threshold: float = 0.008  # 自适应学习率KL阈值
+
+    # ===== 网络架构配置 =====
+    # 小型网络（适合简单任务如 CartPole）
+    # policy_hidden_layer_sizes: tuple[int, ...] = (128, 64)
+    # value_hidden_layer_sizes: tuple[int, ...] = (128, 64)
+
+    # 中型网络（默认配置，适合大部分任务）
+    policy_hidden_layer_sizes: tuple[int, ...] = (256, 128, 64)
+    value_hidden_layer_sizes: tuple[int, ...] = (256, 128, 64)
+
+    # 大型网络（适合复杂任务如机器人控制）
+    # policy_hidden_layer_sizes: tuple[int, ...] = (512, 256, 128)
+    # value_hidden_layer_sizes: tuple[int, ...] = (512, 256, 128)
+
+    # ===== 网络共享配置 =====
+    share_policy_value_features: bool = True  # 策略和价值网络共享特征提取层
+
+    # ===== 训练控制参数 =====
+    random_timesteps: int = 0          # 随机步数
+    learning_starts: int = 0           # 开始学习的步数
+    time_limit_bootstrap: bool = True  # 时间限制引导
+
+    # ===== 奖励整形 =====
+    rewards_shaper_scale: float = 1.0  # 奖励缩放因子
+```
+
+## 配置使用方法
+
+### 1. 默认配置使用
+
+```bash
+# 使用代码中给定的配置
+uv run scripts/train.py --env my-task
+
+# 指定训练后端，系统会自动选择对应的后端配置
+uv run scripts/train.py --env my-task --train-backend jax
+uv run scripts/train.py --env my-task --train-backend torch
+```
+
+### 2. 命令行参数覆盖
+
+```bash
+# 覆盖支持的命令行参数
+uv run scripts/train.py --env my-task \
+  --num-envs 1024 \
+  --train-backend jax \
+  --sim-backend np
+
+# 系统会自动选择JAX后端对应的配置
+```
+
+### 3. 配置优先级
+
+系统按以下优先级选择配置：
+
+1. **后端特定配置**: 如果存在 `@rlcfg(env_name, backend="jax/torch")` 装饰的配置
+2. **通用配置**: 如果存在 `@rlcfg(env_name)` 装饰的配置（无 backend 参数）
+
+例如：
+
+```python
+# 最高优先级 - 后端特定配置
+@rlcfg("my-task", backend="jax")
+@dataclass
+class MyTaskJAXCfg(PPOCfg):
+    mini_batches: int = 4
+
+# 次优先级 - 通用配置
+@rlcfg("my-task")
+@dataclass
+class MyTaskRLCfg(PPOCfg):
+    mini_batches: int = 32
+
+# 当使用 --train-backend jax 时，系统会选择 MyTaskJAXCfg
+# 当使用 --train-backend torch 时，系统会选择 MyTaskRLCfg
+```
+
+## SKRL 框架配置映射
+
+在 MotrixLab 中，用户通过 `PPOCfg` 配置类设置参数，这些参数会被映射到 SKRL 框架的配置字典中。
+
+### 用户可配置参数
+
+| MotrixLab 配置类                       | SKRL 框架参数                                 | 说明                 |
+| -------------------------------------- | --------------------------------------------- | -------------------- |
+| `learning_rate`                        | `learning_rate`                               | 学习率               |
+| `rollouts`                             | `rollouts`                                    | 经验回放轮数         |
+| `learning_epochs`                      | `learning_epochs`                             | 训练轮数             |
+| `mini_batches`                         | `mini_batches`                                | 小批量数量           |
+| `discount_factor`                      | `discount_factor`                             | 折扣因子             |
+| `grad_norm_clip`                       | `grad_norm_clip`                              | 梯度裁剪             |
+| `lambda_param`                         | `lambda`                                      | GAE 参数             |
+| `ratio_clip`                           | `ratio_clip`                                  | PPO 裁剪比率         |
+| `value_clip`                           | `value_clip`                                  | 价值裁剪             |
+| `clip_predicted_values`                | `clip_predicted_values`                       | 裁剪预测值           |
+| `entropy_loss_scale`                   | `entropy_loss_scale`                          | 熵损失系数           |
+| `value_loss_scale`                     | `value_loss_scale`                            | 价值损失系数         |
+| `kl_threshold`                         | `kl_threshold`                                | KL 散度阈值          |
+| `random_timesteps`                     | `random_timesteps`                            | 随机步数             |
+| `learning_starts`                      | `learning_starts`                             | 开始学习的步数       |
+| `time_limit_bootstrap`                 | `time_limit_bootstrap`                        | 时间限制引导         |
+| `learning_rate_scheduler_kl_threshold` | `learning_rate_scheduler_kwargs.kl_threshold` | 自适应学习率 KL 阈值 |
+| `check_point_interval`                 | `experiment.write_interval`                   | 日志写入间隔         |
+| `check_point_interval`                 | `experiment.checkpoint_interval`              | 检查点保存间隔       |
+| `rewards_shaper_scale`                 | `rewards_shaper`                              | 奖励缩放函数         |
+
+### 预处理器参数
+
+| SKRL 框架参数        | 类型                  | 说明       |
+| -------------------- | --------------------- | ---------- |
+| `state_preprocessor` | RunningStandardScaler | 状态标准化 |
+| `value_preprocessor` | RunningStandardScaler | 价值标准化 |
+
+### 配置层次总结
+
+```
+用户配置类 (PPOCfg)
+    ↓ 后端特定选择
+后端配置 (JAX/Torch)
+    ↓ 参数映射
+SKRL 框架配置字典
+    ↓ 传递给
+PPO Agent
+    ↓ 执行
+强化学习训练
+```
+
+这种设计允许用户：
+
+1. 通过简单的配置类来控制复杂的训练参数
+2. 为不同训练后端配置不同的参数以获得最佳性能
+3. 保持与 SKRL 框架的完全兼容性