refactor(robots): extract reusable model configurations and assets

AGENTS.md

@@ -9,12 +9,13 @@ MotrixLab 是构建在 MotrixSim 仿真后端之上的强化学习框架，提
 
 ## Workspace 结构
 
-项目使用 UV workspace，包含十二个 package：
+项目使用 UV workspace，包含以下 package：
 
-- `motrix_env_core`：backend 无关的环境框架（不依赖任何 simulator）
+- `motrix_env_core`：backend 无关的环境框架，拥有 robot registry 与 `motrix_env_core.robots` entry-point discovery（不依赖任何 simulator 或 `motrix_robots`）
 - `motrix_env_motrixsim`：MotrixSim 仿真后端（SimBackend、scene compiler、renderer、torch frontend）
 - `motrix_env_mujoco`：仅用于编译的 MuJoCo scene 后端
-- `motrix_envs`：内置环境、机器人模型与任务资产
+- `motrix_robots`：仿真 `RobotCfg`、模型自有关键姿态及模型 MJCF/URDF、mesh 与模型纹理资产，仅依赖 core；模型定义模块与 `assets/` 位于 package 根目录，任务场景、地面与 terrain 资产属于 `motrix_envs`。根 package 以显式 `__all__` 提供模型类和类型化 humanoid/quadruped helper 的公共 API；框架内部从定义模块导入。注册回调由首次 robot registry 查询惰性调用；导入 package 或模型类不触发 discovery、注册、资产扫描或读取，也不加载 simulator 或训练环境
+- `motrix_envs`：内置环境与任务资产
 - `motrix_rl`：RL 控制平面、训练编排与稳定 contracts（runner、run/checkpoint、backend 选择、`motrix_rl.frameworks` discovery、provider/trainer 接口）
 - `motrix_rl_builtin`：内置 Motrix FastSAC provider 插件
 - `motrix_rl_skrl`：SKRL PPO provider 插件（Torch 必需，额外 JAX runtime 可选）
@@ -99,7 +100,7 @@ Python 方法，由 manager 运行时契约定义（`wiki/design/manager/runtime
 
 ### 版本与依赖一致性
 
-- 所有 workspace package（见上文 Workspace 结构，共十二个）的 `pyproject.toml` 中 `version` 字段必须保持一致。
+- 所有 workspace package（见上文 Workspace 结构）的 `pyproject.toml` 中 `version` 字段必须保持一致。
 - MotrixSim 相关依赖版本必须在使用该依赖的 workspace package 之间保持一致。
 - 关键第三方依赖使用精确版本锁定（`===`）；新增或升级依赖时同步更新 `uv.lock`。
 

README.md

@@ -161,22 +161,32 @@ Seven reusable robot models are registered out of the box and can be combined in
 python scripts/view.py robot=go2
 ```
 
+Use the public configuration API to compose a model directly:
+
+```python
+from motrix_robots import Microduck, UnitreeGo2Robot
+
+microduck = Microduck()
+go2 = UnitreeGo2Robot()
+```
+
 See [Supported Robots](https://motrixlab.readthedocs.io/en/latest/user_guide/robots.html) for configuration details and how to add your own model.
 
 ## 🏗️ What's Inside
 
-MotrixLab is a [uv](https://docs.astral.sh/uv/) workspace of twelve packages:
+MotrixLab is a [uv](https://docs.astral.sh/uv/) workspace with the following packages:
 
 | Package | PyPI name | Description |
 | --- | --- | --- |
 | **motrix_deploy** | `motrix-deploy` | Framework-independent artifacts, runtime contracts, deployment registry, and CLI |
 | **motrix_deploy_mujoco** | `motrix-deploy-mujoco` | MuJoCo deployment backend plugin |
 | **motrix_deploy_unitree** | `motrix-deploy-unitree` | Unitree SDK2 DDS hardware backend plugin |
 | **motrix_deploy_tasks** | `motrix-deploy-tasks` | Versioned deployment tasks and executable bootstrap |
-| **motrix_env_core** | `motrix-env-core` | Backend-agnostic environment framework, configuration, registry, lifecycle, and rendering |
+| **motrix_env_core** | `motrix-env-core` | Backend-agnostic environment framework, configuration, registry, robot entry-point discovery, lifecycle, and rendering |
 | **motrix_env_motrixsim** | `motrix-env-motrixsim` | Live MotrixSim backend, renderer, and Torch frontend |
 | **motrix_env_mujoco** | `motrix-env-mujoco` | Compile-only MuJoCo scene backend |
-| **motrix_envs** | `motrix-envs` | Built-in environments, robot models, data, and deployment-profile compilers |
+| **motrix_robots** | `motrix-robots` | Simulation robot configs, model-owned poses, and model MJCF/URDF, meshes, and model textures; core-only dependency |
+| **motrix_envs** | `motrix-envs` | Built-in environments, task assets, data, and deployment-profile compilers |
 | **motrix_rl** | `motrix-rl` | RL control plane, provider/trainer contracts, run/checkpoint handling, and discovery |
 | **motrix_rl_builtin** | `motrix-rl-builtin` | Built-in Motrix FastSAC provider |
 | **motrix_rl_skrl** | `motrix-rl-skrl` | Required SKRL PPO Torch provider; optional JAX extra |

README.zh-CN.md

@@ -161,22 +161,32 @@ python scripts/view.py env=go2-walk-rough
 python scripts/view.py robot=go2
 ```
 
+通过公共配置 API 直接构造模型，用于场景组合：
+
+```python
+from motrix_robots import Microduck, UnitreeGo2Robot
+
+microduck = Microduck()
+go2 = UnitreeGo2Robot()
+```
+
 机器人配置细节与自定义新模型的方法见[支持的机器人](https://motrixlab.readthedocs.io/zh-cn/latest/user_guide/robots.html)。
 
 ## 🏗️ 项目组成
 
-MotrixLab 是一个由十二个 package 组成的 [uv](https://docs.astral.sh/uv/) workspace：
+MotrixLab 是一个 [uv](https://docs.astral.sh/uv/) workspace，包含以下 package：
 
 | Package | PyPI 名称 | 说明 |
 | --- | --- | --- |
 | **motrix_deploy** | `motrix-deploy` | 框架无关 artifact、运行时契约、部署 registry 与 CLI |
 | **motrix_deploy_mujoco** | `motrix-deploy-mujoco` | MuJoCo 部署 backend plugin |
 | **motrix_deploy_unitree** | `motrix-deploy-unitree` | Unitree SDK2 DDS 硬件 backend plugin |
 | **motrix_deploy_tasks** | `motrix-deploy-tasks` | 带版本的部署任务与可执行入口 bootstrap |
-| **motrix_env_core** | `motrix-env-core` | backend 无关的环境框架、配置、registry、生命周期与渲染 |
+| **motrix_env_core** | `motrix-env-core` | backend 无关的环境框架、配置、registry、robot entry-point discovery、生命周期与渲染 |
 | **motrix_env_motrixsim** | `motrix-env-motrixsim` | MotrixSim 实时仿真 backend、renderer 与 Torch frontend |
 | **motrix_env_mujoco** | `motrix-env-mujoco` | 仅负责编译场景的 MuJoCo backend |
-| **motrix_envs** | `motrix-envs` | 内置环境、机器人模型、数据及部署 profile 编译实现 |
+| **motrix_robots** | `motrix-robots` | 仿真机器人配置、模型自有姿态及 模型 MJCF/URDF、mesh 与模型纹理资产；仅依赖 core |
+| **motrix_envs** | `motrix-envs` | 内置环境、任务资产、数据及部署 profile 编译实现 |
 | **motrix_rl** | `motrix-rl` | RL 控制平面、provider/trainer contract、run/checkpoint 管理与 discovery |
 | **motrix_rl_builtin** | `motrix-rl-builtin` | 内置 Motrix FastSAC provider |
 | **motrix_rl_skrl** | `motrix-rl-skrl` | 必需的 SKRL PPO Torch provider；可选 JAX extra |

THIRD_PARTY_NOTICES.md

@@ -17,10 +17,10 @@ separately downloaded optional asset.
 | Franka Emika Panda MJCF and meshes | `motrix_envs/src/motrix_envs/manipulation/franka_lift_cube/xmls/`; `motrix_envs/src/motrix_envs/manipulation/franka_open_cabinet/xmls/` | [frankarobotics/franka_ros](https://github.com/frankarobotics/franka_ros/tree/develop/franka_description), see each directory README | The public source repository declares Apache-2.0; local model licenses are present. Record the exact imported revision and preserve attribution for all derived meshes |
 | Shadow Hand E3M5 description | `motrix_envs/src/motrix_envs/manipulation/shadow_hand/xmls/` | Record the exact upstream source and revision before release | A local Apache-2.0 file is present; upstream provenance still needs to be recorded |
 | RM65 descriptions and meshes | `motrix_envs/src/motrix_envs/manipulation/rm65_open_cabinet/xmls/`; `motrix_envs/src/motrix_envs/common/rm65/` | Record the exact upstream source and revision before release | A local Apache-2.0 file is present for the cabinet scene; verify every shared mesh |
-| Unitree G1, Go1 and Go2 assets | `motrix_envs/src/motrix_envs/robot/assets/`; `motrix_envs/src/motrix_envs/locomotion/go1/` | Record the exact Unitree source and model terms | Release approval required from the rights holder; trademarks and model terms are separate from the code license |
-| ANYmal-C assets | `motrix_envs/src/motrix_envs/robot/assets/anymal_c/`; `motrix_envs/src/motrix_envs/locomotion/anymal_c/` | Record the exact upstream source and model terms | Release approval and attribution required |
-| Booster K1 assets | `motrix_envs/src/motrix_envs/robot/assets/k1/` | [BoosterRobotics/booster_assets K1 model](https://github.com/BoosterRobotics/booster_assets/blob/main/robots/K1/K1_22dof.xml) | The public repository declares BSD-3-Clause and the local XML identifies this source. Record the exact imported revision and confirm that the derived XML and meshes may be redistributed |
-| Dex-EVT assets | `motrix_envs/src/motrix_envs/robot/assets/dex_evt/` | Record the exact upstream source and model terms | No public provenance or redistribution permission is documented in this checkout; release approval and attribution are required |
+| Unitree G1, Go1 and Go2 assets | `motrix_robots/src/motrix_robots/assets/g1/`; `motrix_robots/src/motrix_robots/assets/go1/`; `motrix_robots/src/motrix_robots/assets/go2/` | Record the exact Unitree source and model terms | Release approval required from the rights holder; trademarks and model terms are separate from the code license |
+| ANYmal-C assets | `motrix_robots/src/motrix_robots/assets/anymal_c/`; `motrix_envs/src/motrix_envs/locomotion/anymal_c/` | Record the exact upstream source and model terms | Release approval and attribution required |
+| Booster K1 assets | `motrix_robots/src/motrix_robots/assets/k1/` | [BoosterRobotics/booster_assets K1 model](https://github.com/BoosterRobotics/booster_assets/blob/main/robots/K1/K1_22dof.xml) | The public repository declares BSD-3-Clause and the local XML identifies this source. Record the exact imported revision and confirm that the derived XML and meshes may be redistributed |
+| Dex-EVT assets | `motrix_robots/src/motrix_robots/assets/dex_evt/` | Record the exact upstream source and model terms | No public provenance or redistribution permission is documented in this checkout; release approval and attribution are required |
 | LAFAN1 input data and converter | `motrix_envs/src/motrix_envs/motion/converters/`; downloaded inputs are not part of the repository | [LAFAN1 Retargeting Dataset](https://huggingface.co/datasets/lvhaidong/LAFAN1_Retargeting_Dataset) | CC BY-NC-ND 4.0 is documented by the user guide; retain attribution and state the non-commercial/no-derivatives limits before redistributing any converted output |
 | Bundled whole-body-tracking motion clips | `motrix_envs/src/motrix_envs/locomotion/wbt/assets/motion/` | Record the source, revision, author, and terms for each `*.npz` clip | Provenance and redistribution permission are not yet documented for every clip; do not publish until cleared |
 | Documentation videos, posters and benchmark figures | `docs/source/_static/` | Record whether each item is original, generated, or derived from a third-party asset | Verify the rights for the source material and the resulting media independently; retain attribution where required |

bench/bench_physics.py

@@ -40,7 +40,6 @@
 import numpy as np
 from report import render_table
 
-import motrix_envs  # noqa: F401  registers robots and scene assets
 from motrix_env_core import registry
 from motrix_env_core.base import SimCfg
 from motrix_env_motrixsim.compiler import MotrixSimSceneCompiler

docs/scripts/generate_robot_docs.py

@@ -12,7 +12,6 @@
 import motrixsim as mtx
 from motrixsim.render import RenderApp, RenderSettings
 
-import motrix_envs  # noqa: F401 registers built-in robots
 from motrix_env_core import registry
 from motrix_env_core.config.scene import MjcfFileCfg, SystemCameraCfg, UrdfFileCfg
 from motrix_env_motrixsim.compiler import build_scene_model

docs/source/en/user_guide/envs/humanoid_velocity_tracking/adding_robot.md

@@ -38,13 +38,12 @@ nested config overrides, field details, and tuning guidance.
 Use the following layout:
 
 ```text
-motrix_envs/src/motrix_envs/
-├── robot/
-│   ├── <robot>.py                # RobotCfg, including its default key pose
-│   └── assets/<robot>/           # Reusable robot assets
-└── locomotion/
-    └── humanoid/
-        └── <robot>.py            # Flat/terrain configs and environment registration
+motrix_robots/src/motrix_robots/
+├── <robot>.py                    # RobotCfg and default key pose
+└── assets/<robot>/               # Reusable robot assets
+
+motrix_envs/src/motrix_envs/locomotion/humanoid/
+└── <robot>.py                    # Flat/terrain configs and environment registration
 
 configs/task/
 ├── <robot>-walk-flat/

docs/source/en/user_guide/envs/quadruped_velocity_tracking/adding_robot.md

@@ -8,13 +8,12 @@ construction, diagonal-trot rewards, reset, and termination.
 Use the following layout:
 
 ```text
-motrix_envs/src/motrix_envs/
-├── robot/
-│   ├── <robot>.py                # QuadrupedRobotCfg and default key pose
-│   └── assets/<robot>/           # Robot assets reusable across tasks
-└── locomotion/
-    └── quadruped/
-        └── <robot>.py            # Flat/rough configs and environment registration
+motrix_robots/src/motrix_robots/
+├── <robot>.py                    # QuadrupedRobotCfg and default key pose
+└── assets/<robot>/               # Robot assets reusable across tasks
+
+motrix_envs/src/motrix_envs/locomotion/quadruped/
+└── <robot>.py                    # Flat/rough configs and environment registration
 
 configs/task/
 ├── <robot>-walk-flat/
@@ -43,7 +42,7 @@ foot in front-left, front-right, rear-left, rear-right order:
 ```python
 from motrix_env_core.config import configclass
 from motrix_env_core.config.scene import KeyPoseCfg, MjcfFileCfg
-from motrix_envs.robot import QuadrupedLegCfg, QuadrupedLegsCfg, QuadrupedRobotCfg
+from motrix_robots import QuadrupedLegCfg, QuadrupedLegsCfg, QuadrupedRobotCfg
 
 
 @configclass(kw_only=True)

docs/source/en/user_guide/robots.md

@@ -1,7 +1,6 @@
 # Supported Robots
 
-MotrixLab exposes reusable robot models through the robot registry. A registered robot has a public `RobotCfg` and can
-be composed into different scenes and tasks. The table below is generated directly from the registry and robot configs.
+`motrix_robots` provides reusable robot models that you can preview independently or use in tasks from `motrix_envs`.
 
 ## Built-in robots
 
@@ -20,6 +19,38 @@ be composed into different scenes and tasks. The table below is generated direct
 
 <!-- ROBOT_TABLE_END -->
 
+## Preview a robot
+
+Use `view.py` to inspect a registered robot in its default pose without creating an RL environment:
+
+```bash
+python scripts/view.py robot=go2
+```
+
+Robot view mode builds a static standard scene. It does not sample actions or run a physics rollout.
+
+## Python API
+
+Import reusable configurations directly from `motrix_robots`:
+
+```python
+from motrix_robots import Microduck, UnitreeGo2Robot
+
+microduck = Microduck()
+go2 = UnitreeGo2Robot(prefix="robot_")
+```
+
+You can also select a robot by its registry name and place it in a standard scene:
+
+```python
+from motrix_env_core import registry
+from motrix_envs.config.scene import StandardSceneCfg, StandardSceneObjsCfg
+
+print(registry.list_registered_robots())
+robot = registry.make_robot_config("go2")
+scene = StandardSceneCfg(objs=StandardSceneObjsCfg(robot=robot))
+```
+
 ## Define a new robot
 
 A reusable robot should be defined as a `RobotCfg` that describes only the robot model and how it is instantiated.
@@ -31,7 +62,7 @@ markers, and task-created sensors belong to `SceneCfg` or the task configuration
 Use the following layout for a built-in robot:
 
 ```text
-motrix_envs/src/motrix_envs/robot/
+motrix_robots/src/motrix_robots/
 ├── my_robot.py
 └── assets/my_robot/
     ├── my_robot.xml              # or my_robot.urdf
@@ -45,7 +76,7 @@ Import `ActuatorCfg`, `PositionActuatorCfg`, and `MotorActuatorCfg` from `motrix
 
 ### 2. Declare the `RobotCfg`
 
-Define the configuration in `robot/my_robot.py` with `@configclass(kw_only=True)`. This is a minimal MJCF example:
+Define the configuration in `motrix_robots/src/motrix_robots/my_robot.py` with `@configclass(kw_only=True)`. This is a minimal MJCF example:
 
 ```python
 from pathlib import Path
@@ -88,7 +119,7 @@ robot joint poses here; ground names, task sensor names, and other scene semanti
 A humanoid robot should inherit `HumanoidRobotCfg` and define its left and right foot links:
 
 ```python
-from motrix_envs.robot import HumanoidRobotCfg
+from motrix_robots import HumanoidRobotCfg
 
 
 @configclass(kw_only=True)
@@ -138,18 +169,28 @@ Set `inherit_joint_range=True` to use imported joint limits as the control range
 
 ### 3. Register the robot
 
-Import and register a built-in robot in `motrix_envs/robot/__init__.py`:
+Register a built-in robot inside the `register()` callback in
+`motrix_robots/src/motrix_robots/registration.py`. Import the new class from its defining module
+and add its registration to the callback:
 
 ```python
 from motrix_env_core import registry
-from motrix_envs.robot.my_robot import MyRobot
+from motrix_robots.my_robot import MyRobot
 
-registry.robotcfg("my-robot")(MyRobot)
+
+def register() -> None:
+    # Keep the other built-in model registrations here.
+    registry.robotcfg("my-robot")(MyRobot)
 ```
 
-Also add `MyRobot` to that module's `__all__`. The registry name is the stable ID used by the CLI and
-`registry.make_robot_config()`. The class must be constructible without arguments; alternatively, register a typed
-zero-argument factory.
+Installed robot packages are discovered automatically; no manual registration import is needed.
+For a separate package, define the same `register()` callback using your own model import and declare it in that
+package's `pyproject.toml`:
+
+```toml
+[project.entry-points."motrix_env_core.robots"]
+my_robot = "my_robot_package.registration:register"
+```
 
 ### 4. Validate
 
@@ -172,32 +213,3 @@ To include the robot in the generated table above, add its type and screenshot p
 python docs/scripts/generate_robot_docs.py --screenshots my-robot
 python docs/scripts/generate_robot_docs.py --check
 ```
-
-## Preview a robot
-
-Use `view.py` to inspect a registered robot in its default pose without creating an RL environment:
-
-```bash
-python scripts/view.py robot=go2
-```
-
-Robot view mode builds a static standard scene. It does not sample actions or run a physics rollout.
-
-## Python API
-
-Importing `motrix_envs` registers the built-in robots. You can inspect the registry, create a fresh config, and compose
-it into a standard scene:
-
-```python
-import motrix_envs  # noqa: F401 registers built-in robots
-from motrix_env_core import registry
-from motrix_envs.config.scene import StandardSceneCfg, StandardSceneObjsCfg
-
-print(registry.list_registered_robots())
-
-robot = registry.make_robot_config("go2")
-scene = StandardSceneCfg(objs=StandardSceneObjsCfg(robot=robot))
-```
-
-`make_robot_config()` returns a new validated config on every call, so callers can safely customize placement, naming
-prefixes, or other instance-level fields.