feat: Manager-Based API 迁移与多后端/拆包收口（roadmap #1042）

.github/CODEOWNERS

@@ -4,11 +4,11 @@
 # Core algorithm and training flows
 /src/unilab/algos/ @TATP-233 @caozx1110
 /src/unilab/ipc/ @TATP-233
-/scripts/train_*.py @TATP-233 @caozx1110
+/src/unilab/scripts/train_*.py @TATP-233 @caozx1110
 
 # Task and environment ownership
-/src/unilab/envs/motion_tracking/ @caozx1110
-/src/unilab/envs/manipulation/ @Mingrui-Yu
+/src/unilab/tasks/motion_tracking/ @caozx1110
+/src/unilab/tasks/manipulation/ @Mingrui-Yu
 /scripts/motion/ @caozx1110
 
 # Project process and docs

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -37,7 +37,7 @@ body:
       label: Reproduction
       description: Exact command, config, or sequence that reproduces the issue.
       placeholder: |
-        uv run scripts/train_offpolicy.py algo=sac task=sac/g1_walk_flat/mujoco ...
+        uv run train --algo sac --task g1_walk_flat --sim mujoco ...
     validations:
       required: true
 

.github/workflows/ci.yml

@@ -33,6 +33,8 @@ jobs:
           persist-credentials: false
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
       - name: Install dependencies(only dev group)
         run: uv sync --only-group dev
       - name: Check
@@ -49,6 +51,8 @@ jobs:
           persist-credentials: false
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
       - name: Install dependencies(only dev group)
         run: uv sync --only-group dev
       - name: Check
@@ -65,6 +69,8 @@ jobs:
           persist-credentials: false
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
       - name: Install dependencies
         run: uv sync
       - name: Check
@@ -81,6 +87,8 @@ jobs:
           persist-credentials: false
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
       - name: Install dependencies
         run: uv sync
       - name: Check
@@ -98,6 +106,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
         with:
+          enable-cache: true
           python-version: '3.11'
       - name: Install dependencies
         run: |
@@ -124,7 +133,9 @@ jobs:
 
   test:
     if: github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request'
-    timeout-minutes: 15
+    # The merged manager-based suite needs ~20 min on ubuntu-slim; 15 min
+    # cancels the step at ~60%.
+    timeout-minutes: 30
     strategy:
       matrix:
         os: [ubuntu-slim]
@@ -138,6 +149,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
         with:
+          enable-cache: true
           # python-version: ${{ matrix.python-version }}
           python-version: '3.11'
       - name: Install system dependencies
@@ -162,5 +174,12 @@ jobs:
             --no-install-package nvidia-nvtx-cu12 \
             --no-install-package triton
           uv pip install torch==2.7.0 --index-url https://download.pytorch.org/whl/cpu
+      - name: Cache robot assets
+        uses: actions/cache@v4.2.3
+        with:
+          path: src/unilab/assets/robots
+          key: ${{ runner.os }}-robot-assets-v1-${{ hashFiles('src/unilab/assets/hub.py') }}
+      - name: Pull robot assets
+        run: uv run --no-sync unilab-pull-assets --robot all
       - name: Test with coverage
         run: uv run --no-sync pytest -m "not slow" --cov=src/unilab --cov-report "markdown-append:${GITHUB_STEP_SUMMARY:-/dev/null}" --cov-fail-under=25

.github/workflows/docs.yml

@@ -8,7 +8,7 @@ on:
       - "docs/README.md"
       - "src/unilab/**"
       - "scripts/generate_support_matrix.py"
-      - "conf/**"
+      - "src/unilab/conf/**"
       - "README.md"
       - "CONTRIBUTING.md"
       - "AGENTS.md"
@@ -21,7 +21,7 @@ on:
       - "docs/README.md"
       - "src/unilab/**"
       - "scripts/generate_support_matrix.py"
-      - "conf/**"
+      - "src/unilab/conf/**"
       - "README.md"
       - "CONTRIBUTING.md"
       - "AGENTS.md"

.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  build-dist:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: false
+      - name: Verify tag matches project version
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        run: |
+          project_version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          tag_version="${GITHUB_REF_NAME#v}"
+          test "$tag_version" = "$project_version" || {
+            echo "Tag v$tag_version does not match pyproject.toml version $project_version" >&2
+            exit 1
+          }
+      - name: Verify CI passed for tagged commit
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          successful_runs="$(gh api \
+            "/repos/${GITHUB_REPOSITORY}/actions/workflows/ci.yml/runs?head_sha=${GITHUB_SHA}&status=completed&per_page=100" \
+            --jq '[.workflow_runs[] | select(.conclusion == "success")] | length')"
+          test "$successful_runs" -gt 0 || {
+            echo "No successful ci.yml run found for tagged commit $GITHUB_SHA" >&2
+            echo "ci.yml only runs on pull_request and workflow_dispatch; dispatch it on the commit to release, then tag." >&2
+            exit 1
+          }
+      - name: Build source distribution and wheel
+        run: uv build --out-dir dist
+      - name: Check distribution metadata
+        run: uvx --from twine twine check dist/*
+      - name: Install the freshly built wheel
+        run: |
+          uv venv .release-venv
+          uv pip install --python .release-venv/bin/python --reinstall --no-deps \
+            --no-binary unilab --no-cache --find-links dist --no-index unilab
+      - name: Smoke test installed wheel
+        shell: bash
+        run: |
+          tag_version=""
+          case "$GITHUB_REF" in
+            refs/tags/v*) tag_version="${GITHUB_REF_NAME#v}" ;;
+          esac
+          .release-venv/bin/python -c "
+          import unilab
+          assert unilab.ROOT_PATH.is_dir()
+          assert (unilab.ROOT_PATH / 'conf').is_dir()
+          version = unilab.__version__
+          assert version != '0.0.0', version
+          ref = '$tag_version'
+          if ref:
+              assert version == ref, f'{version} != {ref}'
+          print('installed unilab', version)
+          "
+      - uses: actions/upload-artifact@v4.2.3
+        with:
+          name: release-dist
+          path: dist/*
+
+  publish:
+    needs: build-dist
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4.2.3
+        with:
+          name: release-dist
+          path: dist
+      - name: Publish distributions to PyPI with trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          skip-existing: true

.gitignore

@@ -58,7 +58,6 @@ run_summary.json
 src/unilab/assets/checkpoints/
 
 scripts/benchmark/outputs/
-src/unilab/algos/torch/rsl_rl
 
 third-party
 temp/
@@ -81,6 +80,13 @@ src/unilab/assets/motions/x2/*.csv
 
 # Robot mesh assets (downloaded from HF at runtime)
 src/unilab/assets/robots/x2/meshes/*.STL
+src/unilab/assets/robots/g1/assets/
+src/unilab/assets/robots/g1/textures/
+src/unilab/assets/robots/go2/assets/
+src/unilab/assets/robots/a2/assets/
+src/unilab/assets/robots/allegro_hand/assets/
+src/unilab/assets/robots/sharpa_wave/meshes/
+src/unilab/assets/robots/go2_arm/assets/
 
 # Grasp cache assets (downloaded from HF at runtime)
 src/unilab/assets/caches/*.npy

AGENTS.md

@@ -4,6 +4,8 @@
 
 UniLab 是一个 **高性能、模块化、contract 驱动** 的 RL infrastructure 仓库。
 
+RL 算法与异步 runtime（PPO/APPO/SAC/TD3/HORA 的 runner、learner、collector、IPC、训练日志）由独立包 **uni_rl**（仓库 [unilabsim/unilab_rl](https://github.com/unilabsim/unilab_rl)，distribution 名 `unilab-rl`，发布在 PyPI）承载；UniLab 不构造 uni_rl 消费的 env，而是通过注入式 env contract 对接：`uni_rl.env_contract.EnvFactory = Callable[[int, Mapping | None], EnvProtocol]`（必须可被 pickle 引用，collector 跑在 spawn 子进程），UniLab 侧适配器为 `src/unilab/base/env_factory.py` 的 `registry_env_factory`，mjwarp 设备绑定经 `src/unilab/base/process_device.py` 的 `bind_backend_process_device` 注入。unilab 可以 import uni_rl；uni_rl 永远不 import unilab / unisim。
+
 ## Core Principles
 
 1. **Contract first**: 不为了一次通过绕过 env / backend / runner contract。
@@ -32,34 +34,40 @@ UniLab 是一个 **高性能、模块化、contract 驱动** 的 RL infrastructu
 | Env  | `NpEnvState.obs` 必须是 dict；`reset()` 返回 `(obs_dict, info_dict)`；`obs_groups_spec` 影响 wrapper 和 learner 维度。 |
 | Config / Reward | reward 通过 Hydra 注入；后端切换必须通过 `task=<task>/<backend>` 选择 owner YAML，`training.sim_backend` 只是 owner YAML 的身份字段，不能单独 override 来切后端。算法超参数直接走 YAML compose，不经 Python 层解释。 |
 | Backend | backend-specific 逻辑留在 backend / env 适配层，不向训练脚本扩散。env 层只能调用 `SimBackend`（`base.py`）中已声明的方法；若某方法只在 MuJoCo 或 Motrix 中存在，必须先将其加入 `SimBackend` 抽象接口（可抛 `NotImplementedError`），禁止直接在 env 里调用 backend 子类的私有方法（即"功能泄漏/feature leakage"）。新增 backend 专有能力时，需同步更新 `SimBackend`。 |
-| Asset / Metadata | `ASSETS_ROOT_PATH`、`model_file`、XML / asset 元数据只允许在 init / materialization / cache 等低频路径访问；`step/reset/domain randomization` 等热路径不得解析 asset 或基于 asset 元数据做运行时分支。 |
+| Asset / Metadata | `ASSETS_ROOT_PATH`、`model_file`、XML / asset 元数据只允许在 init / materialization / cache 等低频路径访问；`step/reset/domain randomization` 等热路径不得解析 asset 或基于 asset 元数据做运行时分支。机器人 mesh/纹理不入 git：托管在 HF 数据集 `unilabsim/unilab-robots`，注册表为 `src/unilab/assets/hub.py` 的 `ROBOT_ASSET_SPECS`，由 `create_backend` 冷路径自动下载（也可 `unilab-pull-assets` 预拉取），落盘回原路径使 XML `meshdir` 引用不变；这些目录在 `.gitignore` 与 `pyproject.toml` 的 `tool.uv.build-backend.source-exclude` 中同步排除。 |
 | Asset / XML structure | `<keyframe>` 必须放在 task-level XML（`scene_*.xml` 或 `locomotion_task.xml` 等 fragment），**禁止放进 robot.xml**。robot.xml 是纯机器人描述（body / joint / actuator / sensor），跟 task / 场景无关；keyframe 是 task 起始姿态，属于场景或 task 资源。motrix 后端需要 keyframe 时通过 `scene.fragment_files` 引用 fragment XML。 |
-| Async | 不绕开 runner lifecycle，也不另起 collector / learner 同步协议。 |
+| Async | 不绕开 runner lifecycle（实现在 uni_rl 仓库的 `uni_rl.ipc.async_runner`），也不另起 collector / learner 同步协议。 |
 | Sim2Sim 契约 | 跨后端 play 时，影响策略 I/O / 网络结构的字段必须跨后端一致；不一致即 `CrossBackendIncompatibleError`。详见下方 Sim2Sim 章节。 |
 
 ## Sim2Sim 跨后端配置契约
 
-`src/unilab/training/sim2sim.py` 按 dotted path 维护三类字段：
+`src/unilab/utils/sim2sim.py` 按 dotted path 维护三类字段：
 
 - **DENYLIST**（差异即 `CrossBackendIncompatibleError`）：`algo.obs_groups`、`env.control_config.action_scale`、`algo.policy.actor_hidden_dims` / `critic_hidden_dims`、`algo.empirical_normalization` / `algo.obs_normalization`、`env.sampling_mode`。`env.*` 子集对**任一方向**的不对称出现也 fail-closed；`algo` 专属字段目标缺省时按设计跳过（跨算法合法）。
 - **WARNING_LIST**：`reward.*`、`env.control_config.simulate_action_latency`、`env.ctrl_dt`。
 - **ALLOWLIST**（自由覆盖）：`training.sim_backend`、`env.scene`、`training.play_steps`、`env.domain_rand`、`env.noise_config`、`env.commands.vel_limit`。
 
-训练时 `ExperimentTracker.start()` 把上述字段写入 `run_config.json` 的 `contract_snapshot`（不改 checkpoint 格式，旧 run 无 snapshot 时 fallback + warning）；五个 play 入口在建 env 前调用 `resolve_sim2sim_config` 校验，并用 `policy_load_dim_guard` 包裹 checkpoint 加载以把维度不匹配的隐晦报错重抛为显式诊断。设 `training.sim2sim_strict=false` 可把 DENYLIST 差异降级为 warning（默认 `true`）。DENYLIST 字段在每个后端 owner 配置中显式声明并保持跨后端一致（范例：`conf/ppo/task/g1_walk_flat/{mujoco,motrix}.yaml`）；跨后端契约审计见 `scripts/audit_sim2sim_contracts.py`。
+训练时 `ExperimentTracker.start()` 把上述字段写入 `run_config.json` 的 `contract_snapshot`（不改 checkpoint 格式，旧 run 无 snapshot 时 fallback + warning）；五个 play 入口在建 env 前调用 `resolve_sim2sim_config` 校验，并用 `policy_load_dim_guard` 包裹 checkpoint 加载以把维度不匹配的隐晦报错重抛为显式诊断。设 `training.sim2sim_strict=false` 可把 DENYLIST 差异降级为 warning（默认 `true`）。DENYLIST 字段在共享 base owner 与后端 owner 配置中显式声明并保持跨后端一致（范例：`src/unilab/conf/ppo/task/g1_walk_flat/{base,mujoco,motrix}.yaml`）；跨后端契约审计见 `scripts/audit_sim2sim_contracts.py`。
 
 ## Pointers
 
-- PPO: `scripts/train_rsl_rl.py`
-- APPO: `scripts/train_appo.py`
-- SAC / TD3: `scripts/train_offpolicy.py`
+- PPO: `src/unilab/scripts/train_rsl_rl.py`
+- APPO: `src/unilab/scripts/train_appo.py`
+- SAC / TD3 / FlashSAC: `src/unilab/scripts/train_sac.py` / `src/unilab/scripts/train_td3.py` / `src/unilab/scripts/train_flashsac.py`
 - env contract: `src/unilab/base/np_env.py`
-- backend contract: `src/unilab/base/backend/base.py`
+- backend contract: `unisim.backend.base.SimBackend`（由 `unisim-core` 仓库维护）
+- UniLab backend owner factory: `src/unilab/base/backend_factory.py`
+- isaacgym subprocess 后端（Python 3.8 worker + shm 协议）: `unisim.backend.isaacgym`（由 `unisim-core` 仓库维护）
 - training run helpers: `src/unilab/training/run.py`
 - visualization helpers: `src/unilab/visualization/`
 - shared numeric helpers: `src/unilab/utils/rotation.py`, `src/unilab/utils/geometry.py`
 - config schema: `src/unilab/structured_configs.py`
-- async runner: `src/unilab/ipc/async_runner.py`
-- sim2sim 跨后端契约: `src/unilab/training/sim2sim.py`
+- async runner: `uni_rl.ipc.async_runner`（独立 uni_rl 仓库 / `unilab-rl` 包）
+- algo 实现（runner / learner / collector）: uni_rl 包（独立仓库，distribution 名 `unilab-rl`）；UniLab 只保留入口脚本与 play 编排
+- uni_rl env factory 适配: `src/unilab/base/env_factory.py`
+- HORA APPO play 编排: `src/unilab/scripts/play_hora_appo.py`；HORA distill 配置组合: `src/unilab/training/hora_distill_config.py`
+- sim2sim 跨后端契约: `src/unilab/utils/sim2sim.py`
+- new algorithm recipe（三档扩展方式 + 约定式 CLI 路由 footprint）: `docs/sphinx/source/zh_CN/4-developer_guide/3-extending/3-new_algorithm.md`
 
 ## GitHub CLI (gh) 速查
 
@@ -101,6 +109,17 @@ git push -u origin fix/issue-174-ppo-config-alignment
 gh pr create --title "fix: xxx" --body "Fixes #174" --base <target-branch>
 ```
 
+## PyPI Release
+
+`.github/workflows/release.yml` 是生产发布路径，由 `v*` tag 推送触发（`workflow_dispatch` 只做构建与验证，不发布）：
+
+1. 更新 `pyproject.toml` 的 `[project].version`（版本单一来源）及相关文档，本地 `make test-all` 与 `uv build` 通过。
+2. 确认目标 commit 有成功的 `ci.yml` 运行：ci.yml 只在 PR 与 `workflow_dispatch` 上运行，若目标 commit 没有记录，先对该 commit 手动 dispatch 一次 ci.yml 再发 tag。
+3. 推送与 `[project].version` 完全一致的 annotated tag（如 `v0.1.0`）。release workflow 会校验 tag 与版本一致、该 commit CI 已通过，然后构建 sdist + wheel、twine check、`--no-deps` 安装 wheel 并做 import / 版本 smoke test。
+4. 构建验证通过后，`publish` job 通过 trusted publishing（OIDC，`environment: pypi`）上传到 PyPI，无 token 入仓；`skip-existing: true` 支持安全重跑。
+
+发布失败时：产物未变可用同一 tag 修复重跑；改了代码必须升级版本与新 tag，绝不覆盖已发布版本。
+
 ## Context
 
 - 架构标准与验证详情：[docs/sphinx/source/zh_CN/4-developer_guide/0-index.md](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md)

CONTRIBUTING.md

@@ -6,10 +6,13 @@ Languages: English | [简体中文](docs/sphinx/source/zh_CN/4-developer_guide/4
 
 1. Fork and clone the repository.
 2. Install dependencies for your platform:
-   - macOS (MPS, installs PyPI torch wheels): `uv sync`
-   - Linux default (installs PyTorch cu128 wheels; requires an NVIDIA GPU/driver supported by current PyTorch cu128 wheels): `uv sync`
+   - macOS (MPS, installs PyPI torch wheels): `make setup-motrix` (or `make setup-mujoco`)
+   - Linux default (installs PyTorch cu128 wheels; requires an NVIDIA GPU/driver supported by current PyTorch cu128 wheels): `make setup`
    - Linux AMD / ROCm workstation: `make sync-rocm`, then run commands with `uv run --no-sync ...`
-   - When you need Motrix, append `--extra motrix`
+   - For direct uv setup, use `uv sync --extra mujoco --extra motrix`; replace it
+     with `--extra mujoco` or `--extra motrix` for a single backend
+   - Physics adapters are supplied by the production PyPI package
+     `unisim-core>=0.1.14` (import namespace `unisim`).
 3. Create a branch such as `git checkout -b docs/improve-readme` or `git checkout -b fix/backend-bug`.
 
 ## Development Rules

Makefile

@@ -24,6 +24,17 @@ setup-mujoco:
 	uv sync --extra mujoco
 	uv run --no-sync unilab-complete install
 
+# Installs the Python extra and builds DrakeUni's native extension. By default
+# the host-compatible official tarball is downloaded; use DRAKE_HOME=<prefix>
+# to build against an existing installation.
+.PHONY: setup-drake
+setup-drake:
+	@ if [ -n "$(DRAKE_HOME)" ]; then \
+		bash scripts/tools/setup_drake_env.sh --drake-home "$(DRAKE_HOME)"; \
+	else \
+		bash scripts/tools/setup_drake_env.sh --download-drake; \
+	fi
+
 .PHONY: setup-motrix
 setup-motrix:
 	uv sync --extra motrix
@@ -56,7 +67,11 @@ type:
 	uv run pyright
 
 .PHONY: check
-check: format type
+check: format type check-tests
+
+.PHONY: check-tests
+check-tests:
+	uv run ruff check tests --select F401,F821,F811,F841 --output-format concise
 
 .PHONY: test
 test:
@@ -88,7 +103,7 @@ clean:
 	find . -type d -name ".ruff_cache" -exec rm -rf {} +
 	find . -type d -name "htmlcov" -exec rm -rf {} +
 	find . -type f -name ".coverage" -delete
-	rm -f train_appo.log train_offpolicy.log train_rsl_rl.log MUJOCO_LOG.TXT
+	rm -f train_appo.log train_sac.log train_flashsac.log train_rsl_rl.log MUJOCO_LOG.TXT
 	find src/unilab/assets/.cache -type f ! -name '.gitkeep' -delete 2>/dev/null || true
 	find src/unilab/assets/caches -type f ! -name '.gitkeep' -delete 2>/dev/null || true
 	find src/unilab/assets/checkpoints -type f ! -name '.gitkeep' -delete 2>/dev/null || true