feat: package RL CLIs and deployment profile plugins

AGENTS.md

@@ -26,8 +26,9 @@ MotrixLab 是构建在 MotrixSim 仿真后端之上的强化学习框架，提
 - `motrix_deploy_unitree`：Unitree 硬件配置、sensor/actuation 接线与 SDK2 DDS 硬件后端插件
 - `motrix_deploy_tasks`：具体部署任务实现
 
-`scripts/` 提供训练、可视化、评估入口。内置环境由环境 package 注册并通过项目 registry 暴露；simulator backend
-通过项目 backend registry 选择，core package 不依赖任何具体 simulator 实现。
+`motrix_rl.commands.train` / `play` 提供安装后的 `mxtrain` / `mxplay` 入口，`scripts/` 保留可视化等工具。
+内置环境由环境 package 注册并通过项目 registry 暴露；simulator backend 通过项目 backend registry 选择，
+core package 不依赖任何具体 simulator 实现。
 
 ## 编码规范
 
@@ -88,7 +89,7 @@ Python 方法，由 manager 运行时契约定义（`wiki/design/manager/runtime
 ### RL 任务配置规范
 
 - RL provider 配置使用对应插件包的 `@dataclass` 配置类：SKRL 使用 `motrix_rl_skrl.config.SkrlCfg`，RSLRL 使用 `motrix_rl_rslrl.cfg.RslrlCfg`，FastSAC 使用 `motrix_rl_builtin.fastsac.config.FastSacCfg`。
-- provider 配置的字段结构必须与对应的 `configs/algo_base/*.yaml` 保持一致；不要使用已经删除的 `@rlcfg` 或旧的嵌套结构。
+- provider 配置的字段结构必须与对应的 `motrix_rl/src/motrix_rl/configs/algo_base/*.yaml` 保持一致；不要使用已经删除的 `@rlcfg` 或旧的嵌套结构。
 - 超参数在配置对象初始化或明确的配置组装流程中赋值；同一环境的多个变体应通过配置复用，子变体只覆写实际差异。
 - SKRL 和 RSLRL 的 provider 配置结构不同，不要为了统一接口强行增加无用的兼容层；框架通过 provider 的 `config_type` 和 trainer context 选择对应实现。
 
@@ -154,28 +155,28 @@ sh install.sh --python 3.11
 
 ## 常用命令
 
-train/play/view CLI 由 [Hydra](https://hydra.cc/) 驱动，参数使用 `key=value` 语法（不是 `--flag`）。可用选项见
-`configs/*.yaml`。
+train/play/view CLI 由 [Hydra](https://hydra.cc/) 驱动，参数使用 `key=value` 语法（不是 `--flag`）。
+CLI 用法与项目配置接入见 [motrix_rl/README.md](motrix_rl/README.md)。
 
 ### 训练
 
 SKRL（默认）：
 
 ```bash
-python scripts/train.py task=cartpole/skrl.ppo
+mxtrain task=cartpole/skrl.ppo
 ```
 
 RSLRL：
 
 ```bash
-python scripts/train.py task=cartpole/rslrl.ppo
+mxtrain task=cartpole/rslrl.ppo
 ```
 
 直接覆写框架运行时设置和类型化 RL 参数：
 
 ```bash
-python scripts/train.py task=cartpole/skrl.ppo num_envs=64 algo.agent.learning_rate=1e-3
-python scripts/train.py task=cartpole/skrl.ppo logging.interval=20 checkpoint.interval=100
+mxtrain task=cartpole/skrl.ppo num_envs=64 algo.agent.learning_rate=1e-3
+mxtrain task=cartpole/skrl.ppo logging.interval=20 checkpoint.interval=100
 ```
 
 ### 环境可视化
@@ -195,27 +196,33 @@ python scripts/view.py robot=g1-29dof
 ### 评估
 
 ```bash
-python scripts/play.py env=cartpole
+mxplay env=cartpole
 ```
 
 指定 policy 文件：
 
 ```bash
-python scripts/play.py env=cartpole policy=<path/to/best.[pickle/pt]>
+mxplay env=cartpole policy=<path/to/best.[pickle/pt]>
 ```
 
 ### ONNX 导出
 
 ```bash
-python scripts/export_onnx.py run_dir=<run-dir> output=/tmp/policy.onnx
+mxexport onnx run_dir=<run-dir> output=/tmp/policy.onnx
+```
+
+### 部署 artifact 导出
+
+```bash
+mxexport deploy run_dir=<run-dir> output=artifacts/policy.deploy
 ```
 
 ### 渲染
 
 训练时开启可视化：
 
 ```bash
-python scripts/train.py task=cartpole/skrl.ppo render=true
+mxtrain task=cartpole/skrl.ppo render=true
 ```
 
 ### TensorBoard

README.md

@@ -98,7 +98,7 @@ Activate the installed environment (Windows PowerShell: `.venv\Scripts\Activate.
 
 ```bash
 source .venv/bin/activate
-python scripts/train.py task=microduck-walk-flat/motrix.fastsac play=true
+mxtrain task=microduck-walk-flat/motrix.fastsac play=true
 ```
 
 While training, the built-in dashboard shows live run progress, episode statistics, throughput, rewards, and system health:
@@ -124,7 +124,7 @@ Training finishes in minutes: mean return and episode length typically converge
 Replay the latest trained policy without retraining (for example, after stopping training early with Ctrl+C):
 
 ```bash
-python scripts/play.py env=microduck-walk-flat
+mxplay env=microduck-walk-flat
 ```
 
 A trained microduck policy replayed in the viewer:

README.zh-CN.md

@@ -98,7 +98,7 @@ powershell -ExecutionPolicy Bypass -File install.ps1
 
 ```bash
 source .venv/bin/activate
-python scripts/train.py task=microduck-walk-flat/motrix.fastsac play=true
+mxtrain task=microduck-walk-flat/motrix.fastsac play=true
 ```
 
 训练过程中，内置面板会实时显示运行进度、回合统计、吞吐、奖励与系统健康状态：
@@ -124,7 +124,7 @@ microduck 的训练数分钟内即可完成：平均回报与回合长度通常
 无需重新训练即可回放最近一次训练得到的策略（例如提前 Ctrl+C 中断训练之后）：
 
 ```bash
-python scripts/play.py env=microduck-walk-flat
+mxplay env=microduck-walk-flat
 ```
 
 训练好的 microduck 策略在查看器中的回放效果：

bench/bench_wbt_kernel.py

@@ -19,7 +19,6 @@
 import numba
 import numpy as np
 
-import motrix_envs  # noqa: F401  registers built-in environments
 from motrix_env_core import registry
 from motrix_env_core.manager import ManagerEnv
 from motrix_env_core.numba.kernel import clone_kernel_value, get_num_threads, get_threading_layer

bench/env_benchmark/workload.py

@@ -17,7 +17,6 @@ def load_runtime():
     os.environ.setdefault("GOMP_SPINCOUNT", "0")
     import numpy as np
 
-    import motrix_envs  # noqa: F401  registers built-in environments
     from motrix_env_core import registry
 
     return np, registry

docker/docker-compose.yml

@@ -16,10 +16,10 @@ services:
               count: all
               capabilities: [gpu]
     command:
-      - scripts/train.py
-      - train_backend=${MOTRIX_TRAIN_BACKEND:-jax}
+      - mxtrain
+      - task=${MOTRIX_ENV:-cartpole}/skrl.ppo
+      - task.train_backend=${MOTRIX_TRAIN_BACKEND:-jax}
       - num_envs=${MOTRIX_NUM_ENVS:-2048}
-      - env=${MOTRIX_ENV:-cartpole}
     restart: no
 
   motrixlab-tensorboard:

docs/scripts/generate_env_docs.py

@@ -8,7 +8,6 @@
 import argparse
 from pathlib import Path
 
-import motrix_envs  # noqa: F401 registers built-in environments
 from motrix_env_core import registry
 
 REPO_ROOT = Path(__file__).resolve().parents[2]

docs/scripts/generate_env_snapshot.py

@@ -11,7 +11,6 @@
 
 import imageio.v2 as imageio
 
-import motrix_envs  # noqa: F401 registers built-in environments
 from motrix_env_core import registry
 from motrix_env_core.array.env import ArrayEnv
 from motrix_env_core.sim.backend import RenderConfig

docs/scripts/generate_video.py

@@ -4,9 +4,9 @@
 """Generate a documentation video from the latest playable environment policy.
 
 Examples:
-    uv run docs/scripts/generate_video.py cartpole
-    uv run docs/scripts/generate_video.py cartpole --output cartpole_demo.mp4 --force
-    uv run docs/scripts/generate_video.py g1-wbt-dance  # records one complete motion clip
+    python docs/scripts/generate_video.py cartpole
+    python docs/scripts/generate_video.py cartpole --output cartpole_demo.mp4 --force
+    python docs/scripts/generate_video.py g1-wbt-dance  # records one complete motion clip
 """
 
 from __future__ import annotations
@@ -17,7 +17,6 @@
 from dataclasses import dataclass, replace
 from pathlib import Path
 
-import motrix_envs  # noqa: F401 registers built-in environments
 from motrix_env_core import registry
 from motrix_env_core.renderer import RenderConfig
 from motrix_envs.locomotion.wbt.cfg import WbtEnvCfg
@@ -96,7 +95,7 @@ def _default_train_command(env_name: str) -> str | None:
         config = candidates[sorted(candidates)[0]]
     if config is None:
         return None
-    return f"uv run scripts/train.py task={env_name}/{config.stem}"
+    return f"python -m motrix_rl.commands.train task={env_name}/{config.name.removesuffix('.yaml')}"
 
 
 def _recording_path(env_name: str, output: Path | None) -> Path:

docs/source/en/user_guide/envs/ball_balance.md

@@ -25,13 +25,13 @@ python scripts/view.py env=microduck-ball-balance
 Train with the built-in Motrix FastSAC config (the only training config provided for this task; `num_envs=2048`, 20000 iterations):
 
 ```bash
-python scripts/train.py task=microduck-ball-balance/motrix.fastsac
+mxtrain task=microduck-ball-balance/motrix.fastsac
 ```
 
 Evaluate a trained policy:
 
 ```bash
-python scripts/play.py env=microduck-ball-balance
+mxplay env=microduck-ball-balance
 ```
 
 ## Action space

docs/source/en/user_guide/envs/basic/acrobot.md

@@ -70,13 +70,13 @@ python scripts/view.py env=acrobot
 
 ```bash
 # Train with default parameters
-python scripts/train.py task=acrobot/skrl.ppo
+mxtrain task=acrobot/skrl.ppo
 
 # Customize parallel environments
-python scripts/train.py task=acrobot/skrl.ppo num_envs=1024
+mxtrain task=acrobot/skrl.ppo num_envs=1024
 
 # Enable rendering during training
-python scripts/train.py task=acrobot/skrl.ppo render=true
+mxtrain task=acrobot/skrl.ppo render=true
 ```
 
 ### 3. View Training Progress
@@ -89,10 +89,10 @@ tensorboard --logdir runs/acrobot
 
 ```bash
 # Auto-discover best policy (recommended)
-python scripts/play.py env=acrobot
+mxplay env=acrobot
 
 # Manually specify a checkpoint from a metadata-backed run
-python scripts/play.py env=acrobot policy=/path/to/run/checkpoints/policy-file
+mxplay env=acrobot policy=/path/to/run/checkpoints/policy-file
 ```
 
 > **Tip**: Policies are auto-selected from `runs/acrobot/`. Use `policy=...` to select a checkpoint whose parent run contains `metadata.json`.

docs/source/en/user_guide/envs/basic/cartpole.md

@@ -21,7 +21,7 @@ python scripts/view.py env=cartpole
 ### 2. Start Training
 
 ```bash
-python scripts/train.py task=cartpole/skrl.ppo
+mxtrain task=cartpole/skrl.ppo
 ```
 
 ### 3. View Training Progress
@@ -33,7 +33,7 @@ tensorboard --logdir runs/cartpole
 ### 4. Test Training Results
 
 ```bash
-python scripts/play.py env=cartpole
+mxplay env=cartpole
 ```
 
 > **Tip**: The system finds the latest metadata-backed run under `runs/cartpole/` and loads its `best_policy` artifact. Use `policy=...` to select another checkpoint from a metadata-backed run.

docs/source/en/user_guide/envs/basic/pendulum.md

@@ -69,13 +69,13 @@ python scripts/view.py env=pendulum
 
 ```bash
 # Train with default parameters
-python scripts/train.py task=pendulum/skrl.ppo
+mxtrain task=pendulum/skrl.ppo
 
 # Customize parallel environments
-python scripts/train.py task=pendulum/skrl.ppo num_envs=1024
+mxtrain task=pendulum/skrl.ppo num_envs=1024
 
 # Enable rendering during training
-python scripts/train.py task=pendulum/skrl.ppo render=true
+mxtrain task=pendulum/skrl.ppo render=true
 ```
 
 ### 3. View Training Progress
@@ -88,10 +88,10 @@ tensorboard --logdir runs/pendulum
 
 ```bash
 # Auto-discover best policy (recommended)
-python scripts/play.py env=pendulum
+mxplay env=pendulum
 
 # Manually specify a checkpoint from a metadata-backed run
-python scripts/play.py env=pendulum policy=/path/to/run/checkpoints/policy-file
+mxplay env=pendulum policy=/path/to/run/checkpoints/policy-file
 ```
 
 > **Tip**: Policies are auto-selected from `runs/pendulum/`. Use `policy=...` to select a checkpoint whose parent run contains `metadata.json`.

docs/source/en/user_guide/envs/basic/stewart.md

@@ -163,8 +163,8 @@ python scripts/view.py env=stewart-disturb-xy
 ### 2. Start Training
 
 ```bash
-python scripts/train.py task=stewart-static/skrl.ppo
-python scripts/train.py task=stewart-disturb-xy/skrl.ppo
+mxtrain task=stewart-static/skrl.ppo
+mxtrain task=stewart-disturb-xy/skrl.ppo
 ```
 
 ### Training Notes
@@ -183,8 +183,8 @@ tensorboard --logdir runs/stewart-disturb-xy
 ### 4. Test Training Results
 
 ```bash
-python scripts/play.py env=stewart-static
-python scripts/play.py env=stewart-disturb-xy
+mxplay env=stewart-static
+mxplay env=stewart-disturb-xy
 ```
 
 ---

docs/source/en/user_guide/envs/dm_control/bring_ball.md

@@ -143,7 +143,7 @@ python scripts/view.py env=dm-manipulator-bring-ball
 ### 2. Start Training
 
 ```bash
-python scripts/train.py task=dm-manipulator-bring-ball/skrl.ppo.torch
+mxtrain task=dm-manipulator-bring-ball/skrl.ppo.torch
 ```
 
 ### 3. View Training Progress
@@ -155,7 +155,7 @@ tensorboard --logdir runs/dm-manipulator-bring-ball
 ### 4. Test Training Results
 
 ```bash
-python scripts/play.py env=dm-manipulator-bring-ball
+mxplay env=dm-manipulator-bring-ball
 ```
 
 ---

docs/source/en/user_guide/envs/dm_control/dm_cheetah.md

@@ -108,7 +108,7 @@ python scripts/view.py env=dm-cheetah
 ### 2. Start Training
 
 ```bash
-python scripts/train.py task=dm-cheetah/skrl.ppo
+mxtrain task=dm-cheetah/skrl.ppo
 ```
 
 ### 3. View Training Progress
@@ -120,7 +120,7 @@ tensorboard --logdir runs/dm-cheetah
 ### 4. Test Training Results
 
 ```bash
-python scripts/play.py env=dm-cheetah
+mxplay env=dm-cheetah
 ```
 
 ---

docs/source/en/user_guide/envs/dm_control/dm_finger.md

@@ -145,15 +145,15 @@ python scripts/view.py env=dm-finger-turn-hard
 ### 2. Start Training
 
 ```bash
-python scripts/train.py task=dm-finger-spin/skrl.ppo task.train_backend=torch
+mxtrain task=dm-finger-spin/skrl.ppo task.train_backend=torch
 ```
 
 ```bash
-python scripts/train.py task=dm-finger-turn-easy/skrl.ppo task.train_backend=torch
+mxtrain task=dm-finger-turn-easy/skrl.ppo task.train_backend=torch
 ```
 
 ```bash
-python scripts/train.py task=dm-finger-turn-hard/skrl.ppo task.train_backend=torch
+mxtrain task=dm-finger-turn-hard/skrl.ppo task.train_backend=torch
 ```
 
 ### 3. View Training Progress
@@ -164,10 +164,10 @@ tensorboard --logdir runs/dm-finger-spin
 
 ### 4. Test Training Results
 
-`scripts/play.py` auto-discovers the latest metadata-backed run under `runs/{env-name}/` and loads its `best_policy` artifact. Use `policy=...` to select a checkpoint explicitly:
+`mxplay` auto-discovers the latest metadata-backed run under `runs/{env-name}/` and loads its `best_policy` artifact. Use `policy=...` to select a checkpoint explicitly:
 
 ```bash
-python scripts/play.py env=dm-finger-turn-hard
+mxplay env=dm-finger-turn-hard
 ```
 
 ---