[Roadmap] 拆分 RL 算法层为独立包 uni-rl（unilabsim/uni_rl + TestPyPI 发布）

[TATP-233]

背景与目标

UniLab 的 RL 算法层 src/unilab/algos/（约 14.7k LOC，59 个 py 文件）目前内嵌在主包中，包含 PPO（rsl_rl 适配）、APPO、FastSAC、FastTD3、FlashSAC、HIM-PPO、HORA（含蒸馏）以及 off-policy 异步运行时。参考 mjlab 的做法（算法层只依赖一个最小 env 契约，runner/wrapper 子类化第三方库）与本仓库 ADR-0007（unisim-core 拆分先例），将算法层拆分为独立仓库 unilabsim/uni_rl：

• distribution name：uni-rl，import namespace：uni_rl
• 打包：uv_build + src layout + 静态版本（沿用本仓库版本策略）
• 发布：本 roadmap 期间仅发布到 TestPyPI（凭证在本机 ~/.pypirc）

交付边界（In Scope）

1. 新建 unilabsim/uni_rl 仓库，建立打包与 TestPyPI 发布管线。
2. 迁移以下内容到 uni_rl（代码 + 对应测试）：
   • src/unilab/algos/ 全部（含 rsl_rl.py / rsl_rl_ppo.py / rsl_rl_runtime.py）
   • 算法运行强依赖的运行时设施：src/unilab/ipc/（AsyncRunner、shm rollout/replay buffer、replay pipelines、dp_sync、memory_budget）、src/unilab/logging/（OffPolicyLogger / TraceRecorder 等）、src/unilab/utils/ 中 algos 实际使用的子集（seed / nan_guard / device / tensor 等）
3. 解耦：uni_rl 不 import unilab。env 侧契约（obs dict / reset() -> (obs, info) / step / final-observation 语义 / obs dims）以最小 protocol 在 uni_rl 内表达；目前 algos 内直接构造 env 的点（registry.make 探测 env、create_env、double-buffer builder、hora appo play）改为由调用方注入 env factory / dims。
4. UniLab 侧适配：依赖 uni-rl；删除已迁移代码；更新 import、conf/**/*.yaml 中的 class_name / runtime_resolver 字符串（unilab.algos.* → uni_rl.*）、structured_configs.py 默认值、sim2sim 引用、visualization/interactive_playback.py 及全部相关测试；make test-all 通过。
5. 文档与 AGENTS.md 更新（新架构边界、指针、发布说明）。

不做（Out of Scope）

• 不改动 main 与 declared base 分支本身（最终 PR 保持未合入，由 maintainer 决策）。
• 不发布到正式 PyPI，仅 TestPyPI。
• 不改变任何算法行为、超参默认值与 checkpoint 格式。
• 不重构训练脚本流程与 Hydra 配置组织方式（仅做 import/字符串重定向）。
• uni_rl 仓库的远程 CI / 正式 PyPI trusted publishing 留待后续 roadmap。

预计规模

• 迁移：algos ~14.7k LOC + ipc/logging/utils 子集（数千 LOC）+ 测试（tests/algos ~6.9k LOC、tests/ipc、相关 utils/logging 测试）。
• UniLab 侧改动面：6 个训练/play 入口脚本、visualization/interactive_playback.py（约 15 处 lazy import）、structured_configs.py、约 10 处 conf YAML 字符串、utils/sim2sim.py、多个测试文件中的字符串断言。
• 共 5 个 child issue，每个都是可独立审查/回退的纵向切片。

永久维护成本

• 新增一个仓库与一条独立版本线；UniLab 通过 PyPI(Test) 依赖消费 uni-rl（同 unisim-core 模式）。
• 双仓发布纪律：uni_rl 变更需先发版、UniLab 侧升级 pin。
• 上游 rsl-rl-lib 等算法依赖的 API 漂移跟踪转移到 uni_rl。
• env 契约 protocol 成为跨仓公共接口，变更需双侧同步评审。

分支与流程

• Declared base：dev/issue-1042-manager-based-api（冻结，不直接改动）。
• 集成分支：dev/issue-<roadmap#>-uni-rl-split，从 declared base 最新 head 创建。
• 每个 child issue 从集成分支建分支并以 PR 合回；roadmap 完成后由集成分支向 declared base 发最终 PR（保持未合入）。
• 每个 PR 在最终 head 运行本地 make test-all（base 非 main，远程 CI 在后续入 main 的边界执行）。

Child Issues（计划）

1. uni_rl 仓库初始化与发布管线：建仓、uv_build 骨架、静态版本、README/LICENSE、TestPyPI 首发验证（预发布版本号）。
2. 代码迁移：algos + ipc + logging + utils 子集与对应测试迁入 uni_rl，内部 import 重写为 uni_rl.*，uni_rl 测试独立通过。
3. env 契约解耦：protocol 下沉 + env 构造注入，uni_rl 对 unilab 的 import 清零。
4. UniLab 侧适配：依赖 uni-rl、删除已迁移代码、import/配置字符串/测试全面重定向，make test-all 通过。
5. 发布与收尾：uni-rl 0.1.0 发 TestPyPI、UniLab 从 TestPyPI 消费验证、文档/AGENTS.md 更新、最终 PR。

验收标准

• pip install -i https://test.pypi.org/simple/ uni-rl 可安装并 import uni_rl 成功。
• uni_rl 仓库测试全绿，且全仓不存在 import unilab / from unilab。
• UniLab 集成分支 make test-all 通过，unilab.algos 不再存在。
• 所有 child issues 关闭，最终 PR（集成分支 → declared base）已创建。

[TATP-233]

Child issues 已创建：

• [uni-rl] 初始化 unilabsim/uni_rl 仓库与 TestPyPI 发布管线 #1477 uni_rl 仓库初始化与 TestPyPI 发布管线
• [uni-rl] 迁移 algos/ipc/logging/utils 代码与测试到 uni_rl #1478 迁移 algos/ipc/logging/utils 代码与测试
• [uni-rl] env 契约解耦：uni_rl 对 unilab 的 import 清零 #1479 env 契约解耦（uni_rl 对 unilab import 清零）
• [uni-rl] UniLab 侧适配：依赖 uni-rl 并重定向全部引用 #1480 UniLab 侧适配
• [uni-rl] TestPyPI 发布 uni-rl 0.1.0 与 roadmap 收尾 #1481 TestPyPI 发布 0.1.0 与收尾

集成分支：dev/issue-1476-uni-rl-split（基于 dev/issue-1042-manager-based-api@3ba89e35）。

开发授权已由 maintainer 在任务下达时给出（全自主执行直到 roadmap 完成），开始连续推进 child issues。

[TATP-233]

命名偏差记录（重要）：目标 distribution name uni-rl 在 PyPI 与 TestPyPI 均无法注册——按 PEP 503 ultranormalization（去除全部 -_.）与现有项目 unirl（Unified multimodal RL training framework，PyPI 与 TestPyPI 均存在）冲突，上传被 400 拒绝。

处置：distribution name 改用 unilab-rl（两个 index 均可用），import namespace 保持 uni_rl 不变，仓库名保持 unilabsim/uni_rl。如 maintainer 坚持 uni-rl，需向 PyPI 申请名称或另选名称，可在最终 PR 评审时决策。

[TATP-233]

Roadmap #1476 最终状态汇总 —— 全部 child issue 已关闭，工作完成。

交付物

• uni_rl 仓库：https://github.com/unilabsim/uni_rl （main @ v0.1.0 / 615c0a5）
• TestPyPI 发布：unilab-rl==0.1.0 — https://test.pypi.org/project/unilab-rl/0.1.0/ （隔离安装验证通过）
• 最终 PR（保持 UNMERGED 待 review）：feat: split RL algorithm layer into standalone uni_rl package (roadmap #1476) #1484 — dev/issue-1042-manager-based-api ← dev/issue-1476-uni-rl-split（198 files，+695/−28,112）

Child issues（全部 closed）

• [uni-rl] 初始化 unilabsim/uni_rl 仓库与 TestPyPI 发布管线 #1477 初始化 unilabsim/uni_rl 仓库与 TestPyPI 发布管线
• [uni-rl] 迁移 algos/ipc/logging/utils 代码与测试到 uni_rl #1478 迁移 algos/ipc/logging/utils 代码与测试 → feat: migrate RL algorithms and runtime from UniLab (issue #1478) unilabsim/unilab_rl#1 (merged)
• [uni-rl] env 契约解耦：uni_rl 对 unilab 的 import 清零 #1479 env 契约解耦（uni_rl 对 unilab import 清零，EnvFactory 注入） → refactor: decouple uni_rl from unilab via env contract and dependency injection (issue #1479) unilabsim/unilab_rl#2 (merged)
• [uni-rl] UniLab 侧适配：依赖 uni-rl 并重定向全部引用 #1480 UniLab 侧适配（依赖 uni-rl、删除迁移层、重定向引用） → feat: consume uni-rl package and remove migrated algorithm layer (issue #1480) #1482 (merged)
• [uni-rl] TestPyPI 发布 uni-rl 0.1.0 与 roadmap 收尾 #1481 0.1.0 发布与收尾（builder backend_device_binder 透传 + 测试补齐 + pin 0.1.0） → build: release 0.1.0 with backend_device_binder builder forwarding (issue #1481) unilabsim/unilab_rl#3 + build: pin uni-rl 0.1.0 from TestPyPI (issue #1481) #1483 (both merged)

命名偏差

请求的 distribution 名 uni-rl 在 PyPI/TestPyPI 均不可注册（与既有 unirl 项目 ultranormalized 冲突）；实际 distribution 名为 unilab-rl，import namespace 保持 uni_rl。两处 pyproject 均有注释记录。

Validation

• uni_rl：pytest 369 passed / 8 skipped；ruff clean；build + 隔离 smoke install 通过。
• UniLab（集成分支 head f760162）：make test-all 全绿 —— pytest 2234 passed / 20 skipped / 319 deselected / 1 xfailed；mypy 156 files clean；pyright 0 errors；benchmark smoke 36/37。每个 child PR 均在各自最终 head 通过完整本地 gate。

已知后续项（留待 maintainer 决策）

1. uni_rl 尚无远程 CI（无 .github/workflows），当前 gate 依赖本地全量测试。
2. unilab-rl 仅发布于 TestPyPI；正式 PyPI 发布需 maintainer 决策与凭据。
3. rsl-rl-lib / tensordict 仍被 UniLab 未迁移代码直接依赖，可后续评估收敛。
4. 最终合入边界 PR feat: split RL algorithm layer into standalone uni_rl package (roadmap #1476) #1484 按"不修改 declared base branch"约束保持 UNMERGED，等 maintainer review 后合入。

[TATP-233]

后续跟进（#1485 / unilabsim/unilab_rl#4，均已 closed）：仓库更名 unilabsim/uni_rl → unilabsim/unilab-rl；算法包迁入 uni_rl.algos.* 子目录（runtime infra ipc/logging/offpolicy/utils/env_contract 保留顶层）；补充 CI（ruff/mypy/pyright/pytest+cov，CPU torch）与 tag 触发的 TestPyPI release 自动化；发布 unilab-rl==0.2.0（https://test.pypi.org/project/unilab-rl/0.2.0/ ，隔离安装验证通过）。UniLab 侧经 PR #1486（merged）适配，集成分支 head b25daf4 make test-all 全绿。最终 PR #1484 已自动更新，仍保持 UNMERGED 待 review。

[TATP-233]

后续架构评估（学术场景跨双仓摩擦）结论与行动项已记录于 #1487。