roadmap: 将 Go2 arm manip-loco 与 HIM-PPO 完整拆分到 legged-manipulation_unilab

[TATP-233]

执行状态：A/B/C/D 已实现并合入各仓 dev/issue-1528-extract-go2-arm；联合验收通过；最终 PR 为新仓 #3、UniLab #1537、unilab_rl #15（均已提交，待 main 合并）。原仓版本号保持 1.1.0，不创建 release/tag、不进行 PyPI 发布；机器人 XML/mesh/texture 全部随新仓和安装包分发，运行时不从 HF 下载。此状态及下述更新覆盖原方案中的资源托管/版本选择。

目标与交付边界

将 UniLab 的 go2_arm_manip_loco / Go2ArmManipLoco 任务及 unilab_rl 中相关的 HIM-PPO 算法完整迁移到独立仓库 unilabsim/legged-manipulation_unilab。新仓成为任务、专属算法、配置、资产定义、工具、测试和使用文档的唯一维护位置。

推荐路径：先在新仓完成可安装、可训练和可回放的迁移闭环，再分别清理 UniLab 与 unilab_rl，最后在两个源仓清理后的版本上做联合验收。预计 4 个可独立评审的交付单元，跨 3 个仓库；不是仅复制任务目录。

硬性要求：两个原仓库的当前受维护代码树不保留任何本任务/HIM-PPO 的专属实现、配置、注册、资产条目、工具、测试或现行使用文档；不保留兼容转发、旧 import shim、可选回装依赖或双份实现。 历史 Git 提交不重写；必要的历史 changelog/迁移公告只记录事实，不承担运行或使用入口。共享代码仅在仍有其他消费者时留在原 owner，移除本任务专属分支。

长期责任：新仓维护 legged manipulation 任务与 HIM-PPO；UniLab 继续维护共享环境/配置/注册能力；unilab_rl 继续维护通用算法和 runtime；unisim 继续维护仿真后端。新仓可以依赖这些基础包，但不得要求用户保留旧源码 checkout、手动复制配置或修改 site-packages。

本 issue 为实施和验收依据。子任务：A #1529、B #1530、C #1531、D #1532；最终 PR 合并前保持 roadmap 开放。

仓库证据

核对基线：UniLab d9afc9656e63c82a64263f5a4dbd938ba1652af2；unilab_rl 801ab92328d892aa7a084a8217aee8cc16eb0e20。目标 GitHub 仓库已存在、为 public、目前为空。实施前重新核对最新 main。

来源	必须迁移的内容	连带清理 / 依赖
UniLab	src/unilab/tasks/locomotion/go2_arm/，包括 base.py、manip_loco.py	从 tasks/__init__.py、migration matrix、demo、任务列表、补全和支持矩阵清除专属项
UniLab	src/unilab/conf/ppo/task/go2_arm_manip_loco/{mujoco,motrix}.yaml，整个 src/unilab/conf/ppo_him/	HIM 配置树当前只有该任务；标准 PPO 及其他任务 owner 保留
UniLab	scripts/train_him_ppo.py、整个 scripts/manip_loco/	包含 IK 诊断、姿态校准、IK-only playback、site Jacobian benchmark；同步处理打包后的脚本入口
UniLab	src/unilab/assets/robots/go2_arm/ 内 XML/场景及专属资产解析责任	删除 hub 的 go2_arm 项、对应 .gitignore 和打包排除项；共享 Go2 mesh 与 G1 地面纹理仍有其他消费者
UniLab	tests/envs/locomotion/go2_arm/，混合测试文件中的专属用例	涵盖 train/play、配置、注册/包边界、资产、backend/Jacobian、demo/CLI 等；通用测试改用通用 fixture，不能整文件误删
UniLab	中英文 manip-loco、HIM-PPO 文档和有效使用说明	同步清理 toctree、API、算法索引、DR 示例、部署/ONNX、项目结构、支持矩阵及交叉链接
unilab_rl	src/uni_rl/algos/him_ppo/ 全部 6 个文件，tests/algos/test_him_ppo_runner.py	删除原算法 namespace，更新 README 中英文、AGENTS、包描述和现行算法列表

HIM-PPO 六个模块为 __init__、actor_critic、estimator、algorithm、storage、runner。当前其他算法没有引用它们；这些模块依赖 torch、tensordict、可选 TensorBoard。训练入口仍使用通用 uni_rl.algos.rsl_rl.RslRlVecEnvWrapper / get_policy_obs_dims，这些共享组件不随任务删除。通用 PPO/APPO/SAC/TD3/FlashSAC/HORA、IPC、日志、共享 locomotion rewards/commands/DR、backend Jacobian 能力维持原 owner。

关键迁移设计

1. 独立安装与命名空间。 新仓使用独立 Python 包（建议 legged_manipulation_unilab），拥有任务、算法、Hydra config、资产与训练/回放入口；不向 unilab 或 uni_rl namespace 写文件。wheel/sdist 必须包含运行所需配置和小型资产，记录源仓 commit 与文件来源。
2. 注册和配置。 UniLab 已有 unilab.tasks entry-point discovery 与 __unilab_registry_modules__ 契约，可直接接入，包括 spawn 子进程。现有 UniLab CLI 按本包内 conf/ 查 owner，不能把“任务注册成功”等同于“外部配置可路由”。由新仓提供读取自身 owner YAML 的训练/回放入口，复用既有公共能力；源仓不得加入本任务特判。保持 backend identity 和 reward/env 配置的单一 owner。
3. 算法与行为。 HIM-PPO 移到新包 namespace；复用通用 PPO 实现。保留现有 PPO MuJoCo/Motrix、HIM-PPO MuJoCo 组合及各 owner 的阶段设置，不借迁移统一奖励、DR、IK 或冻结机械臂参数，不新增后端支持承诺。核对当前 HIM actor 76 × 5 = 380、critic 79 的维度及 history 顺序。
4. 资产闭环。 新仓拥有机械臂 XML、场景及 mesh/texture 资源清单；机器人资产直接提交 Git 并随 wheel/sdist 分发，运行时无 HF 下载。迁移后解析 ../go2/assets、机械臂 mesh 及 Motrix play profile 的 G1 texture 依赖，全新缓存仅从安装包物化，支持离线复用。不得依赖 UniLab 被删除的 go2_arm hub 项或旧仓绝对路径。既有共享 HF 资产内容不在此工作中删除。
5. 现有工具缺口。 calibrate_go2_arm_ee_orientation.py 引用 scripts/play_go2_arm_onnx_sim2sim.py，当前 tracked tree 中不存在该文件。迁移前定位依赖并使校准工具形成可运行闭环；不能把断链脚本原样复制后宣称工具迁移完成。ONNX/JIT 导出和 sim2sim/checkpoint guard 也需重新验证。
6. 版本与来源。 新仓锁定在两个源仓清理后仍可用的依赖版本/commit；移除 uni_rl.algos.him_ppo 是公开 API 删除，记录影响并精确固定配套 Git commit；按维护者要求原仓版本号全部不变，不发布 PyPI、不创建 release/tag。保留迁入代码的版权、BSD-3-Clause SPDX 与所需许可证文本，记录源项目许可。历史 checkpoint 用新 namespace 验证；不通过原仓 shim 兜底。

交付拆分与依赖

执行时将下列交付单元落实为子 issue/PR 并回链本 roadmap；当前不将未开工事项标为完成。

• A（A：独立迁移 Go2 arm 任务、HIM-PPO 与运行入口 #1529，新仓 PR Feat/rsl rl v4 compat #1）：新仓完成独立任务 + 算法迁移。 初始化包、依赖和许可证；迁移上表所有专属内容；修复 import、资产路径、配置路径和工具依赖；提供可复现 train/eval/IK 命令与迁移后测试。产物应先在隔离环境中可安装、可运行，再允许源仓删除。
• B（B：从 UniLab 移除 Go2 arm 与 HIM-PPO 专属接入 #1530，UniLab PR refactor: extract Go2 arm task and dedicated locomotion helpers #1536）：UniLab 移除任务与所有专属接入。 依赖 A；删除环境、配置、HIM 训练入口、资产定义、工具和现行文档；清理混合测试及任务枚举。未安装新包时 UniLab 不再发现该任务；其余任务配置、注册、资产和训练回归通过。
• C（C：从 unilab_rl 移除 HIM-PPO 并记录 API 删除 #1531，unilab_rl PR Dev/go2&td3 #14）：unilab_rl 移除 HIM-PPO。 依赖 A，并与 B 协调合并顺序，避免 UniLab 仍导入已删除模块；删除算法/专属测试/现行支持声明，记录 API 删除及版本策略。其余算法与 uni_rl 不依赖 unilab / unisim 的边界测试通过。
• D（D：Go2 arm 拆分的三仓联合验收 #1532，新仓 PR Feat/appo #2）：三个仓库联合验收与交付文档。 依赖 A/B/C；新仓依赖清理后的源仓版本，运行安装、训练、保存/恢复、推理、回放、导出及残留审计；补齐依赖版本、后端验证结果和新旧命令对照。确认新仓为唯一 owner 后关闭 roadmap。

PR base：两个源仓各以实施时最新 main 为 declared base，建立 dev/issue-1528-extract-go2-arm 集成分支，子 PR 指向各自集成分支，最终 PR 指向 main；新仓以初始化后的 main 为 declared base，并按同样原则记录实际分支。A 先就绪，B/C 配套交付，D 必须使用最终清理后的提交。未获得验证前不先删除唯一可运行副本。

验收标准

• 新仓 wheel/sdist 在无 UniLab/unilab_rl 源码 checkout 的隔离环境可安装；配置/脚本/XML 齐全；从任意工作目录运行，不依赖 PYTHONPATH 补丁；空缓存资产解析与复用缓存均通过。
• 外部任务 entry point 能在主进程和 spawn 子进程确定性注册；所有承诺的 owner 能 compose，backend 身份不可被错误覆盖。
• 迁移前后固定 seed/action 的 reset/step、obs/history、reward、termination、IK/Jacobian 与 DR 关键契约在同一后端保持一致；短程 PPO 与 HIM-PPO rollout/update 产生有限结果。迁移不以重新训练达到收敛为必要条件。
• checkpoint 保存/恢复、已有格式加载、inference、playback、ONNX/JIT 导出及 checkpoint/sim2sim guard 通过；记录 MuJoCo、Motrix 实测平台/命令/结果，未运行不能记为已支持或已通过。
• 两源仓以 git ls-files 路径检查和 git grep -n -i -E 'go2.?arm|manip.?loco|him.?ppo|ppo_him|HIMActorCritic|HIMOnPolicyRunner|HIMEstimator|HIMRolloutStorage' 内容审计覆盖 tracked tree；每个剩余命中逐项分类，任何专属可执行代码、配置、测试或现行文档残留均阻止关闭。历史记录例外明确列出。
• UniLab 的通用 backend/Jacobian 等测试使用保留资产或专用 fixture，继续保护共享行为；文档中英文导航与交叉引用无悬空链接。
• UniLab：make check、make test，创建/更新 PR 前 make test-all；unilab_rl：ruff lint/format、uv run mypy src/uni_rl、uv run pyright、uv run pytest --cov=src/uni_rl。新仓运行迁入任务/算法测试、配置/安装/资产/训练回放 smoke。记录最终 head 的准确命令与结果；最终 PR 合入 main 前等待对应 head 适用远程 CI 通过。

契约依据与实施前需落实的事项

• ADR-0001：runtime 与分层边界
• ADR-0003：task owner / config compose
• ADR-0004：registry bootstrap
• ADR-0005：obs / critic / env / IPC

新仓初始化 PR 记录这次独立 owner 决策，并落实包名、依赖版本、随包资产策略、固定提交依赖和各交付负责人。范围内复用现有注册/配置/后端契约；若实现需要扩展这些公共契约，再在对应子 issue/ADR 中明确新增范围。此 roadmap 不包含改写 Git 历史、删除共享资产托管内容、扩展新算法/后端、常态化性能 benchmark 或自动 PyPI 发布。

[TATP-233]

已获授权开发，开始执行。

交付追踪：A #1529；B #1530；C #1531；D #1532。

两个源仓 declared base 为最新 main：UniLab d9afc96、unilab_rl 801ab923；各建立 dev/issue-1528-extract-go2-arm。新仓先初始化 main，再建立同名集成分支。子 PR 指向集成分支，最终 PR 指向 main。

实施选择：包名 legged-manipulation-unilab，namespace legged_manipulation_unilab；现有 task entry point 接入，新仓维护自身配置和命令；机械臂与共享 mesh 在用户缓存物化，继续使用现有 HF 数据集；通用 PPO 与 runtime 留在原包。unilab_rl 的公开 HIM-PPO namespace 删除按 2.0.0 breaking change 准备（不自动发布），新仓验收依赖最终清理提交。历史提交和 changelog 保留；不留下可运行 shim。实际验证结果将回填。

[TATP-233]

维护者补充要求，覆盖此前实施选择：

1. 机器人 XML、mesh 和所需纹理直接提交至新仓并打入 wheel/sdist；运行时不访问 Hugging Face。仅为临时场景物化建立本地可写缓存，数据来自安装包。
2. 所有原仓库版本号保持不变（UniLab 1.1.0、unilab_rl 1.1.0）；撤回此前 2.0.0 准备方案，不创建 release/tag。配套依赖通过最终清理 commit 精确锁定，文档明确旧发布包与迁移后提交的区别。

进一步依赖审计确认原 locomotion/common 下五份 legacy 模块已仅剩 Go2 arm 消费者，它们及专属 geometry/interval-push helpers 也迁入新仓；仍被 rough/Sharpa 等任务使用的共享模块留在 UniLab。

[TATP-233]

开发和联合验收完成，四个子交付已合入各自的 dev/issue-1528-extract-go2-arm 集成分支。

最终 PR（均目标 main，尚未合并）：

• 新仓： feat: deliver standalone Go2 arm manipulation with bundled assets unilabsim/legged-manipulation_unilab#3
• UniLab 清理： refactor: move Go2 arm manipulation into its standalone repository #1537
• unilab_rl 清理： refactor: move HIM-PPO into the legged manipulation repository unilabsim/unilab_rl#15

子 PR：新仓 #1/#2、UniLab #1536、unilab_rl #14，已合入开发集成分支。

主要验收：

• UniLab make test-all：1589 passed，20 skipped、884 deselected、1 xfailed；格式/类型检查、benchmark smoke 均通过；修改范围额外 242 passed，文档 20 passed/Sphinx 无 warning。
• unilab_rl：380 passed、8 skipped、3 deselected；ruff/mypy/pyright 通过。
• 新仓：33 passed；wheel 安装后同样 33 passed。
• 三个现有 owner 的实际短程训练/回放通过；HIM checkpoint 恢复至迭代 2，PPO/HIM ONNX/JIT 导出通过。
• 固定 seed/actions 与原代码比较：每个组合 74 组数组完全一致。
• 从 /tmp 使用非 editable 安装包、空资产缓存、禁止网络连接，模型加载/reset/step 通过。模型/mesh/纹理约 37 MB 已直接纳入新仓和 wheel/sdist。
• 源仓残留仅 changelog 历史和迁移公告，无运行时专属实现/配置/资产/注册/工具/测试/现行使用页。其他任务使用的共享代码保留。

完整记录与复现脚本： https://github.com/unilabsim/legged-manipulation_unilab/blob/dev/issue-1528-extract-go2-arm/docs/VALIDATION.md

原仓版本号均保持 1.1.0，依赖固定配套 Git commit；未创建 release/tag，未进行任何 PyPI 发布。roadmap 在最终 PR 合并完成前保持开放。

[TATP-233]

最终远程 gate 已通过：

• UniLab PR refactor: move Go2 arm manipulation into its standalone repository #1537，head 679825b035856fdacb3e237f288c7834147074ef：ruff、mypy、pyright、测试、benchmark smoke、Sphinx 全部成功；PR 场景下文档部署按规则跳过。
• unilab_rl PR Dev/g1 sac #15，head 6cd6ffbd4a04dc76bbd1fa1b0a26026a1c09d143：全部 5 个 CI job 成功。
• 新仓 PR fix go2 reward #3，head d147559097f559b75659862176d950be8da2caf2：本地完整 gate 33 passed，安装包及离线验证通过；本仓没有新增常态 CI。

三个最终 PR 均可合并，尚未合入 main。四个开发子 issue 已完成关闭；roadmap 保持开放用于跟踪最终配套合并。所有工作区干净，原仓版本号不变，没有任何 PyPI 发布、release 或 tag。