Roadmap: 借鉴 mjlab 的性能机制与开发体验优势（7 个候选 sub-issue）

[TATP-233]

背景

对照参考仓库 mjlab v1.6.0（/home/user/ws/simulator/mjlab）做了完整架构对比。结论：mjlab 是"Isaac Lab API + MuJoCo-Warp 单后端"的垂直整合，UniLab 是"多后端契约 + 多算法 + 可观测性"的平台型架构。架构治理层面（SimBackend fail-closed 契约、sim2sim DENYLIST/ALLOWLIST 审计、Hydra owner YAML）UniLab 更成熟，方向不回退。

但 mjlab 在性能机制和开发体验两类局部点上有明确优势，且都能在不触动 UniLab 核心契约的前提下落到 backend 层或 tooling 层：

1. CUDA graph capture：mjlab Simulation.create_graph()（src/mjlab/sim/sim.py）把 step/forward/reset/sense 捕获成 CUDA graph 反复 replay，是其性能核心；UniLab mjwarp/backend.py（约 830 行）目前只是普通 batch 封装，无 graph capture。
2. DR 模型字段声明式展开：mjlab event 用 @requires_model_fields 声明随机化哪些 mjModel 字段，env 收集后 expand_model_fields() tile 成 per-world (nworld, ...) Warp 数组，再按 RecomputeLevel 分级重算常量（src/mjlab/envs/mdp/dr/、src/mjlab/sim/randomization.py）；UniLab DR 目前是 provider → capability 过滤 → set_state，缺少 per-world 模型字段展开的显式机制。
3. 标准化 play variant：mjlab 每个 task 工厂带 play=True 分支（剥掉 corruption/pushes/curriculum），registry 成对注册 env_cfg / play_env_cfg；UniLab play 靠 Hydra override 现场拼，五个 play 入口各自组装。
4. 第三方 task 包 entry-point 注册：mjlab 用 mjlab.tasks entry-point group 挂载外部 task 包；UniLab 靠 UNILAB_EXTRA_REGISTRY_PACKAGES 环境变量，对第三方包不友好。
5. viewer 体验：mjlab viser viewer 支持 checkpoint 热切换 + 每个 reward term 实时面板（src/mjlab/viewer/viser/）；UniLab 已有 viser 播放和 per-term reward extras 数据，缺前端呈现。
6. checkpoint 持久化 curriculum/step 计数器：mjlab MjlabOnPolicyRunner 把 common_step_counter 写进 checkpoint，resume 后 curriculum 状态正确恢复；UniLab 有 patch_rsl_rl_resume_state，但 curriculum manager 的 resume 完整性未审计。
7. CI 安装冒烟：mjlab CI build wheel/sdist 后用 tests/smoke_test.py 验证安装产物，防 package data（XML/资产）漏打包；UniLab 资产同样走包内分发，面临相同风险。

总目标与边界

做什么：从 mjlab 借鉴上述 7 个局部改进点，全部落在 backend 适配层、registry、visualization 或 CI 层，不触动 env / config / 训练语义契约。

不做什么：

• 不用 dataclass+tyro 替代 Hydra（与 config first 原则冲突，且 sim2sim 静态审计依赖 YAML）；
• 不向单后端垂直整合回退（多后端契约是差异化价值）；
• 不把 env 层改成 torch-native（违反 NpEnvState 不变量）；
• 不影响已完成的 manager-based API 移植（Roadmap: 将 UniLab 迁移为社区通用的 Manager-Based API #1042 系列），本 roadmap 只补移植范围之外的 mjlab 优势点。

预计总规模：7 个候选 sub-issue，各自独立、可独立取舍；单点净改动预计都在 15 文件 / 800 行以内（第 1、2 项接近上限，第 4、7 项很小）。

永久维护成本：低到中。第 1、2 项引入 mjlab 上游机制的本地适配，mjlab 升级时需要 diff 跟进（与 manager 移植的维护模式一致）；其余各项均为一次性收敛，之后维护成本持平或下降。

候选 Sub-issues（按投入产出排序，均需单独确认后才启动开发）

• mjwarp 后端引入 CUDA graph capture（只改 mjwarp/backend.py 内部实现，不动 SimBackend 契约；需 CUDA driver ≥12.4 + mempool 条件检测与降级路径）
• DR 声明式模型字段展开机制（@requires_model_fields + per-world 字段 tile + 分级 recompute，落在 backend 适配层，与现有 DomainRandomizationCapabilities 过滤衔接）
• 标准化 play variant 约定（owner YAML 增加标准 play profile 或 registry 成对注册 play cfg，统一"关闭 DR/noise/curriculum"入口，与 sim2sim WARNING_LIST 衔接）
• 第三方 task 包 unilab.tasks entry-point group 注册路径（保留环境变量方式作 fallback）
• viser viewer：checkpoint 热切换 + per-term reward 面板
• 审计并补齐 curriculum/step 计数器的 checkpoint resume 完整性
• CI 增加 wheel/sdist 安装冒烟 job

明确未授权、需单独确认的扩张点

• 上述每一项均为候选，批准本 roadmap 只授权规划；任何一项"开始开发"前需单独确认并拆成独立 implementation issue；
• 第 1 项若需要在 SimBackend 抽象接口新增 graph 相关声明，属新公共 contract，需单独确认；
• 第 3 项若引入新的 play 执行入口（而非复用现有 playback session 工厂），属新 execution path，需单独确认。

[TATP-233]

补充分析：从“用户如何找到、理解并运行一个 task”看 mjlab

审计基线：UniLab main@22d735d9（2026-08-27）与 mjlab v1.6.0@0fb8a681。这里只看 CLI、程序化 task 选择、train/play 和调试工具的使用接口；Manager/term authoring API 已由 #1042 负责，不在这里重复。

先说结论

mjlab 最值得借鉴的不是 Tyro，也不是把所有东西塞进一个 registry，而是：用户只选择一次 task，后续的 list/help/train/play/export 都消费同一个已解析对象。UniLab 是多算法、多后端平台，不能照抄 mjlab 的单一 task ID；对应做法应是让 algo × task × backend × profile 这组显式选择只解析一次，再由所有入口复用。

用户动作	mjlab v1.6.0	UniLab 当前事实	对 UniLab 的含义
发现 task	list-envs 直接调用 registry.list_tasks()；train/play 的 task choices 也来自同一 registry	train --help 只列通用 flag；shell completion 另行扫描 conf/ owner 文件	补全对交互式 shell 有用，但不能替代可脚本化的 catalog/list 接口
选择并检查配置	train <TASK> 先选 registry task，再由 Tyro 展开该 task 的 env/agent 专属 help	build_route() 按路径约定拼 owner YAML；无效组合只报告缺失文件路径	保留 Hydra，但应提供 route-specific explain/compose 结果和相邻合法组合
task 身份	一个 task_id 同时索引 train env、play env、RL cfg、runner	CLI 用 snake_case owner slug，例如 go2_joystick_flat；owner 内再映射到 registry 名 Go2JoystickFlat	两种名字可以保留，但必须由一个 resolver 显式关联，不能让用户或工具重复猜测
train/play	同一 task ID；load_env_cfg(task, play=True) 取成对注册的 play variant，并 deepcopy 后返回	已有 play_profile 和 BackendAdapter.build_play_env_cfg_override()，但 APPO/off-policy 及若干替代 playback 路径仍能看到 build_task_env_cfg_override()	#1252 第 3 项不是从零新增机制，而应收口成“所有 play 入口共享同一 variant 解析与优先级”的审计任务
第三方 task	mjlab.tasks entry-point 被加载后，外部包可向同一 registry 注册完整 task cfg bundle	UNILAB_EXTRA_REGISTRY_PACKAGES 只扩展 env registry；CLI/补全仍依赖 checkout 内 conf/，CLI 还显式要求 conf/ 与 scripts/ 存在	仅增加 entry-point import 不会形成可用的第三方 task 体验；第 4 项需要覆盖 registry 和 Hydra owner/config discovery
调试工具	export-scene 接受同一个 task ID，也接受 entity alias/import path	unilab-export-scene 要求用户先找到 MuJoCo XML/MJB 路径；task materialization 另走 visualize_task_env.py	task-aware inspect/export 可作为统一 route resolver 的后续消费者，但不能借此伪造跨 backend export 支持

仓库里已经有三块可复用证据，不需要另造一份静态任务表：src/unilab/base/registry.py::list_registered_envs() 提供 env/backend 注册事实，owner YAML 提供 algo/task/backend/profile 配置事实，src/unilab/utils/support_matrix.py 已把注册、配置、测试和 benchmark 分级拼接。现在缺的是供 CLI/工具共同消费的冷路径解析边界。当前 completion 自己扫描 owner tree、读取 YAML 标量，train/eval 又自己 build_route()，两者存在长期漂移风险。

建议新增 1 个候选项：统一 task route catalog + explain/list 接口（P0）

建议主要结果是一个 owner-layer、只读的 resolved route（名称待定），至少表达：

• 用户选择：algo、owner task slug、backend、可选 profile；
• 解析结果：owner config 路径、training.task_name、registry env/backend、实际 entrypoint，以及 play profile 是否存在；
• 证据结果：Registered / Configured / Tested / Benchmarked / Recommended 继续分开展示，owner 文件存在不得自动等价为 Tested；
• provenance：内置 package 或第三方 distribution/entry-point，供错误诊断使用。

它应被 train、eval、shell completion、可脚本化的 task list 和无效组合诊断共同复用。命令名无需现在锁定，可以是 uv run unilab-tasks，也可以是现有 train/eval 的 --list / --explain；接口行为比拼写更重要。最低验收建议：

1. 可按 algo/backend/profile 过滤并输出机器可读结果；未安装 shell completion 也能发现合法组合。
2. train --help 至少指向 list、completion 与 Hydra --cfg job；选定 route 后可查看 owner/provenance，而不是只看到通用 argparse help。
3. 拼错 task 或选择不存在的 tuple 时，错误列出该维度的合法邻接值；不只打印一个磁盘路径。
4. resolver/list 只做 config/registry 冷路径工作，不构造 backend/env，不解析 XML/asset，也不因为缺少可选 physics runtime 而无法列举配置。
5. route 可用性与 support 等级分离测试；completion、CLI 和 support-matrix 的 task/backend 映射发生漂移时 fail closed。

这比重新设计 CLI 小得多：预计 6–10 个文件、约 300–600 行净手写改动、1 个 PR，永久维护成本低到中。若只作为内部 owner helper + read-only CLI，不需要改变 env/runner lifecycle；若把 resolved route 暴露成第三方公共 Python API，则属于新公共 contract，需 maintainer 单独确认。#136 曾记录过 list/help 缺口，但本候选应只收口仓库拥有的 route/query 边界，不恢复其宽泛 docs scope。

对现有候选项的两处修订

第 3 项（play variant）：保留，但改成 closeout/audit。现有 play_profile 是正确的 Hydra 形态，不建议再复制 mjlab 的“registry 保存两个 mutable cfg 对象”。验收应固定为 train owner → play_profile → 用户显式 override 的优先级，train/eval 使用同一 resolved route，所有受支持的 play/playback 入口统一消费该结果，并能显示最终 play diff/provenance；不新增第二套 play task 或 execution path。

第 4 项（第三方 task entry-point）：扩大“交付完整性”，而不是扩大运行时。mjlab 能只靠 entry-point，是因为一次注册同时带齐 env/play/RL cfg；UniLab 的 task 还必须带 Hydra owner。建议第三方 package contract 显式声明 registry bootstrap modules 与 packaged config/search-path 元数据，并由上面的 catalog 发现。不要复制 mjlab 的递归 pkgutil 扫描和 package import 时的全局副作用；继续遵守 ADR-0004 的显式 module list。已安装且被用户选中的 plugin 加载失败时，诊断至少包含 distribution、entry-point、module 和原始异常，不能退化成“task 未注册”。

这一项还受 #1326 的 package-owned conf//scripts 与仓外 CLI 决策约束。在 self-contained config discovery 尚未确定前，仅接入 unilab.tasks entry-point 会产生“registry 中看得到、train/eval 仍跑不到”的半支持状态，不应对外宣称第三方 task support。它也不再是原正文所估计的“小改动”：涉及公共 plugin/config contract 时，应重新估算并单独确认。

可选后续：让调试工具也按 route 工作（P1）

catalog 稳定后，可让 scene inspect/export 接受与 train/eval 相同的 task route，而不是要求用户手工反查 model_file。首个切片可只覆盖已有 MuJoCo materialization/export 事实；其他 backend 没有正式能力时在构造前明确报 unsupported。若必须新增 SimBackend export/materialization 方法，按新公共 backend contract 单独确认，不放进纯 tooling PR。

明确不照搬的部分

• 不用 Tyro/dataclass CLI 替换 Hydra，也不把算法/backend 隐藏进单一 task ID。
• 不在 registry 保存已实例化配置再依赖 deepcopy；UniLab 的 factory + Hydra compose 更适合多 owner，继续保持每次冷路径新物化。
• 不递归扫描 task package，不在 import unilab 时静默加载所有 plugin，也不 warning 后跳过用户已选择的损坏 plugin。
• 不让新的 catalog 成为第二份 support 声明；它只聚合现有 registry/config/test/benchmark 证据。

因此，从使用接口角度我建议 #1252 新增 1 个 route catalog/query 候选，重写第 4 项的完整边界，并把第 3 项改为现有机制的全入口收口；其余 CLI 美化不应扩进本 roadmap。

[TATP-233]

再补一条：从 Python/代码接口看 mjlab（不替换上一条 CLI 评论）

这条评论专门补充 task author / library user 如何通过 Python 使用 UniLab 的分析。上一条 CLI 评论（#issuecomment-5474306627 保留原样，本条不修改、不删除它。

审计基线仍是 UniLab main@22d735d9 与 mjlab v1.6.0@0fb8a681。#1042 已经把 Manager-Based 的主要 manager、term config、func + params 和生命周期接到 UniLab 的 NumPy runtime；因此这里不建议再次“引入一套 Manager API”。真正影响代码使用体验的差距，是 如何拿到一个完整且可验证的 task，以及 task 作者需要依赖哪些公开类型。

接口对照

使用面	mjlab v1.6.0 的代码接口	UniLab 当前事实	判断
取得 task	load_env_cfg(task_id, play=...)、load_rl_cfg(task_id)，再 ManagerBasedRlEnv(cfg, device=...)	registry.materialize_env_config(name) 只得到注册的 config factory 结果；Manager-Based 任务的 scene、manager dictionaries 和 term 参数由 Hydra owner YAML 补齐，调用者还要自己做 compose → BackendAdapter.build_*_env_cfg_override() → registry.make()	最大的剩余摩擦，应提供 owner-aware 的程序化解析/物化入口
注册边界	register_mjlab_task() 一次登记 train/play env cfg、RL cfg、runner	UniLab 刻意拆成 registry env/config/backend 与算法 owner YAML，以支持多算法、多 backend	不要复制可变 config bundle；应提供只读 resolved view 把这些 owner 关联起来
term/config authoring	Observation/Action/Reward/...TermCfg、func + params、SceneEntityCfg 和有序字典	同名 manager 模块/类、参数形态、字典顺序、selector/query 方法和 None 禁用语义已基本对齐；差异是 NumPy + Hydra	已对齐；无需另造 UniLab 方言
类型与 import	mjlab.envs、mjlab.entity、mjlab.scene、mjlab.managers 公开导出 env、Entity、EntityData、Scene 和 config	manager context protocol 在 unilab.managers._types，实体实现主要在 unilab.base.entity；仓库 source/test 中分别有 40、29 个文件直接依赖这些深层/私有路径	提供小而稳定的 task-author typing/import facade；不把 backend 私有对象变成公共 API
读实体状态	常见写法是 env.scene["robot"].data.joint_pos 等	env.scene["robot"].data.*、冷路径 name→ID selector、root/joint/body state view 已可用	已对齐的高价值表面，继续保持缓存 ID、NumPy 热路径
写实体/控制	mjlab 另有 COM/geom/site/tendon 状态、velocity/effort/tendon/site target、external wrench、mocap 等较宽 MuJoCo surface	UniLab 已有 joint state、root pose/velocity、joint position target、部分模型随机化写入；迁移 fixture 的 JointEffortActionCfg 和 reset adapter 仍是 fixture-local	不做批量 API 平移；按真实迁移需求逐项补，并在 SimBackend/conformance test 形成正式能力
传感器	scene 持有 sensor objects，term 直接读 sensor data	env.scene.bind_sensor_data(names) 返回 backend-owned view，读取接口在冷路径绑定、热路径只读缓存 view	这是有意的 backend isolation 适配，应保留，不为名称/XML 探测再造 scene sensor composer
生命周期/数值	Gym/Torch/device 语义，torch.Tensor buffer	单一 NpEnv lifecycle、NpEnvState、reset() -> (obs_dict, info_dict)、np.ndarray、显式 obs_groups_spec	有意差异，不复制 Torch/device 或改变 runner/IPC contract

一个可复现的仓库事实是：在 registry.ensure_registries() 后直接物化

Go2JoystickFlat -> ManagerBasedRlEnvCfg(scene=None, observations=0, actions=0, rewards=0)
G1WalkFlat      -> ManagerBasedRlEnvCfg(scene=None, observations=0, actions=0, rewards=0)

这不是 task 缺失，而是当前 registry 只登记了 config class；没有再经过 Hydra owner 和 BackendAdapter，ManagerBasedRlEnvCfg.validate() 必然在必需字段处失败。对库用户而言，必须知道并复制训练脚本里的组装顺序，才有一个“可用 task”。相关 owner 分工可在 src/unilab/base/registry.py、src/unilab/base/config_adapter.py、src/unilab/envs/manager_based_rl_env.py 看到；这也是代码接口层最值得收口的地方。

建议的代码接口结果（优先级 P0）

建议新增一个 owner-layer、只读的 ResolvedTask/TaskSpec（名称待定），与上一条评论建议的 route resolver 共用同一实现，而不是 CLI 和 Python 各自再拼一次路径。典型使用形态应接近：

task = resolve_task(
    algo="ppo",
    task="go2_joystick_flat",
    backend="mujoco",
    profile=None,
)
env = task.make_env(num_envs=8)
# task.env_cfg / task.rl_cfg / task.provenance / task.explain()

最低字段/行为建议：

• 明确保存用户选择的 algo × owner task slug × backend × profile，以及映射后的 training.task_name、registry env/backend factory、owner config 路径和最终 composed config；snake_case owner slug 与 registry 名可以并存，但关联必须由 resolver 显式给出。
• 提供 load_env_cfg()/load_rl_cfg() 等 fresh-materialization 视图和 make_env()；make_env() 内部仍走 registry.make() 与现有 BackendAdapter，不引入第二套 env/runner/lifecycle。
• 记录 config/registry provenance（内置包或第三方 distribution/entry-point）和 Registered / Configured / Tested / Benchmarked / Recommended 证据，但不把“有 owner YAML”冒充 Tested，也不创建第二份 support matrix。
• 将 train、所有 play/playback 入口、可脚本化 list/explain 和 shell completion 连接到同一 resolved object；play_profile 优先级（owner → play profile → 用户显式 override）只实现一次。
• 把“解析配置”与“构造 backend/env”分开：list/resolve 只做冷路径 config/registry 工作，不解析 XML/asset、不要求 physics runtime；真正 make_env() 才做 materialization，并在最近边界 fail-closed。
• 对非法 tuple 报出各维度的合法邻接值、owner 路径和 provenance，而不是只显示一个猜出来的文件路径。

这项应被视为一个新的公共 Python contract，开始实现前需要 maintainer 确认；若只保留为内部 helper + read-only CLI，公共承诺可以更小。预计是一个纵向切片（约 6–12 个文件、300–800 行手写改动，具体以 resolver 复用程度为准），不应顺带改 runner、IPC 或 backend execution path。第三方 task 若要使用这个入口，必须同时声明 registry bootstrap 与 packaged Hydra config/search-path 元数据；仅增加 entry-point 而没有 owner config 会形成“registry 看得到、Python/train 跑不到”的半支持状态（还受 #1326 决策约束）。

建议的公共 task-author 类型门面（P1，可与 P0 分开）

目前 unilab.managers._types 中的 ManagerBasedRlEnv、ManagerScene、ManagerEntity、ManagerSensorView 是很好的隔离 seam，但下划线路径不应成为迁移文档的长期入口。可以在一个稳定的 public namespace（例如 unilab.managers.api 或 unilab.envs.types，名称由 ADR 固定）导出 task 作者真正需要的 protocol/config：

• ManagerBasedRlEnv、scene/entity/sensor protocol，以及 Entity/EntityData/EntityCfg 和 SceneEntityCfg 的 typing/import facade；
• 只描述 num_envs、dt、manager、NumPy state/view 和 selector 能力，不暴露 SimBackend、MuJoCo/Warp model/data 或 viewer；
• 迁移示例与 fixture 改用该门面，避免新 task 再复制私有 import。若需兼容旧 import，生命周期和删除点应在 ADR 中明确，不能无限期维持第二套类型表面。

内置能力与实体 API 的取舍

mjlab 的 action catalog 还包括 effort、velocity、relative-position、tendon、site 和 differential-IK 等；UniLab 的通用 action 目前主要公开 JointPositionActionCfg，而两个迁移 fixture 各自带有 JointEffortActionCfg/reset adapter。这说明的是可观测的 portability backlog，不是要求一次性实现 mjlab 全 catalog。建议按下列顺序处理：

1. 从已注册 task 或真实迁移中出现的 term 开始，逐项定义 cfg、shape、reset 和 backend capability；
2. 缺能力在 init/materialization 处明确指出 manager、term、backend 和 capability，禁止 warning+skip/零值/fallback；
3. 每个新增实体读写或 SimBackend 方法配最小跨 backend conformance test，并确认不把 asset/XML 解析带入热路径。

明确不照搬

• 不把 Scene.write_data_to_sim()、sim.forward()、直接 MuJoCo model/data mutation 暴露给 manager term；所有写入继续经过 UniLab entity/SimBackend contract。
• 不复制 Torch tensor/device、Gym/Torch step return、mjlab scene composer 或 registry 中保存可变且需 deepcopy 的 config 对象。
• 不把 viewer/debug 依赖塞进 manager core；调试工具消费 resolved task 即可。
• 不为了表面兼容而批量搬运 MuJoCo 专有 COM/site/tendon/mocap API；没有迁移证据就留在 Unsupported 矩阵。

建议验收

至少应有一个不需要调用者手工 compose/BackendAdapter 的 Python 示例和测试：解析一个 PPO task、切换一个已注册 backend、拿到完整 ManagerBasedRlEnvCfg 后由 registry 创建 env，并核对 obs_groups_spec/action dimension 与 owner 配置一致；同一 resolver 还应被 play 和 list/explain 测试复用。类型门面、能力缺口和第三方 packaged-config 情形分别做 import/fail-closed 测试。

综上，从代码接口角度 #1252 更适合新增“owner-aware programmatic task resolution/materialization”这一候选；Manager API 本身按 #1042 现状视为已对齐，公共类型门面和 built-in/entity capability 作为证据驱动的后续切片。这样能借鉴 mjlab 的“一次加载、处处复用”设计思路，同时保留 UniLab 的 Hydra、多 backend、NumPy 和单一 lifecycle 契约。

[TATP-233]

再修正关注点：代码接口应服务于算法改进、开发与调试

上一条虽然从 CLI 转到了 Python，但仍把“代码接口”主要理解成 task resolution/materialization，关注点还是偏了。那两条评论保留作为 task 使用体验的补充，但在本 roadmap 中应降为次要项；这里重新给出面向算法开发者的优先级结论。

审计基线：UniLab dev/issue-1042-manager-based-api@01f939ed（包含 #1042 已落地的 manager 接口；main 基线同前两条评论）与 mjlab v1.6.0@0fb8a681。

算法开发者真正需要的闭环

这里的“使用接口”不是“怎么找到 task”，而是开发者能否用一条短、可验证的代码路径完成：

1. 修改 observation/reward、policy/critic 结构、loss、target/normalization 或 update schedule；
2. 用固定 seed 构造一个短 rollout 或固定 batch；
3. 在单进程内执行一次 learner update，检查 batch contract、loss/gradient finite、哪些参数发生了变化；
4. 跑很短的训练，关联查看逐 term reward/termination/curriculum、算法指标和 collector/learner timing；
5. 做 checkpoint save/load round-trip，确认 optimizer、normalizer、scheduler/counter 和策略输出恢复一致；
6. 在同一 playback/viewer 上切换 checkpoint，暂停、单步、reset，比较策略行为和逐 term 指标。

如果这些步骤必须先复制完整训练脚本、启动 collector 子进程、猜 loose dict key，并分别适配 logger/checkpoint/playback，那么“算法能跑”并不等于“算法可开发”。

UniLab 当前接口：基础能力很强，但开发接缝是割裂的

开发动作	当前仓库事实	对算法开发者的影响
组装算法 runtime	RslRlPPORuntime 只暴露 wrapper_cls；APPORuntime 暴露 runner_cls + play_fn；OffPolicyRuntime 暴露可选 learner_cls/algo_type/actor_kwargs，且当前主要由 SAC builder 消费。TD3、FlashSAC builder 仍直接构造各自 learner；HIM-PPO 有独立 train_him_ppo.py	不适配已有 seam 的新算法/变体通常要同时改 script dispatch、builder、runner、playback 和 checkpoint 分支，没有一个一致的 owner 接口
独立修改并验证 update	APPO 的 process_batch()/update()、FastSAC/TD3/FlashSAC 的 update 已能被单测直接调用；但 batch 主要是约定 key 的 mutable dict，APPO 还会写入 _critic_obs_flat/_old_mu/... 等内部 key，HIM/RSL-RL 又使用各自 storage	已有算法各自能测，但没有稳定的 family-level batch schema、统一校验入口或 one-update 开发夹具；错误常在训练 loop 深处才暴露
定位数值与训练问题	manager 已有 active_terms、get_term()/get_term_cfg()、get_active_iterable_terms()；reward 有逐 term step 值与 reward/<term>；metrics 支持 last/max/mean/sum；term shape/finite、obs NaN、backend capability 能 fail closed。ExperimentTracker 已保存完整 config、git/hardware/seed 和 sim2sim snapshot；off-policy 还有 runtime manifest、细粒度 timing 和 Perfetto trace	数据并不缺，但 env term、learner metrics、trace、logger、viewer 尚未形成同一套可消费的诊断接口。另一个具体差异是 FastSAC 部分路径遇到 non-finite loss 会跳过 optimizer step；开发/测试模式应能立即失败并指出 batch、loss 和参数组，而不是只留下训练曲线异常
验证 resume	RSL-RL 通过 patch_rsl_rl_resume_state() monkeypatch save/load 补 logger counter；APPO、HIM、FastSAC/TD3/FlashSAC 各自定义 state dict，字段和 progress 语义不同	“能加载 policy”与“能等价恢复训练”目前不是同一 contract；新增算法需要再次决定 optimizer/normalizer/counter/RNG/env curriculum 如何保存
行为调试与 A/B	UniLab 已有统一 PlaybackSession、pause/single-step 控制、NanGuard 和 state dump；manager 也已有 viewer 所需的逐 term iterable 数据，但当前 UniLab viewer 没有把它们组合成逐 term 面板和 checkpoint 热切换	训练数值与策略行为仍要靠不同工具手工对齐，算法迭代反馈回路偏长

这不是要求把现有算法重写成一个基类。PPO/APPO/off-policy 的 rollout、bootstrap、replay 和并发语义本来就不同；真正需要统一的是组装边界、开发验证入口和诊断输出，算法数学与 family-specific lifecycle 继续留在各自 owner 层。

从 mjlab 借什么

mjlab 的优势不是它有更通用的算法插件系统。它只有一条 RSL-RL 垂直栈，通用性反而低于 UniLab。值得借的是这条栈形成的短反馈路径：

• typed TrainConfig(env, agent) 可直接交给 run_train()，训练构造过程是一条可从测试/代码调用的普通函数路径；
• task 可以显式提供 runner subclass，train/play 都从同一处取得它，扩展点不会散落在多个脚本分支；
• viewer 用 CheckpointManager(fetch_available, load_checkpoint) 这样的回调边界做 checkpoint 热切换，而不是理解 runner/checkpoint 内部格式；
• viewer 直接消费 reward/metrics manager 的 get_active_iterable_terms()，并把 pause、single-step、reset、命令控制、逐 term 曲线和 reward bar 放在同一调试会话；
• MjlabOnPolicyRunner 明确把 common_step_counter 纳入 checkpoint，resume 语义由 runner owner 负责。

UniLab 应借鉴这些边界和闭环，不应复制 mjlab 的“task registry + 单一 RSL-RL runner”绑定。

建议新增候选一（P0）：统一最小 AlgorithmRuntime/ExperimentContext 组装契约

建议收敛现有三个形态不同的 runtime bundle，而不是再增加第四种。名称可以调整，关键行为是：

• Hydra owner 解析出一个 typed runtime；共享 train/play 入口只创建 ExperimentContext（resolved cfg、env factory/obs-action contract、device/topology、seed、run dir、tracker/diagnostic sink），不再按算法解释超参数或维护 algo-specific dispatch；
• runtime 提供 training session 与 playback session 的 factory，并声明 checkpoint adapter、policy loader 和可选 developer harness；共享入口只依赖 learn/close/summary 这一层薄 session protocol；
• on-policy、APPO、off-policy 通过 family adapter 复用现有 runner/IPC lifecycle，不要求 learner/storage/update 签名完全相同，也不新建第二套 collector 协议；
• 新增一个不适配现有实现的算法时，主要新增 algorithm package + Hydra owner + runtime registration/conformance test，而不是修改多个共享脚本的 if algo == ...；
• resolver 在 init 边界验证所声明的 runner、learner、playback、checkpoint 能力，缺能力 fail closed，不能运行到训练末尾才发现无法 save/play。

最低验收可用一个小算法变体证明：共享 train/play 脚本无新增算法分支，runtime 能独立构造 training/playback session，错误 runtime 在构造阶段给出缺失 capability。该项是新的公共 algorithm/runner contract，需 maintainer 确认。全算法首轮收口预计 10–18 个文件、约 700–1200 行净手写改动，永久维护成本中等；若超过单 PR 可先收口一个 family，但最终 protocol 必须由至少 on-policy 与 off-policy 两端共同校验，避免只为单一实现定形。

建议新增候选二（P0）：确定性的 one-update 算法开发夹具

这是比 task loader 更直接的开发体验改进。建议提供 family-specific schema，而不是伪造一个万能 batch：

• on-policy fixture 生成短 rollout/returns；APPO fixture 包含 behavior log-prob、last obs/critic；off-policy fixture 包含 actor/critic obs、terminated/truncated 与 terminal bootstrap 语义；
• validate_batch() 在 update 前验证 key、shape、dtype、device、finite 和 bootstrap contract，错误同时报告 algorithm、字段、期望与实际值；
• update_once() 返回结构化 UpdateReport：namespaced losses、entropy/KL/Q statistics、gradient norms、被更新/未更新的参数组、target update 与 non-finite 诊断；
• 固定 seed 下检查指标 finite、预期参数确实变化、冻结/target 参数按 schedule 变化，并做 learner checkpoint round-trip；开发模式遇到 non-finite 应严格失败；
• fixture 可在不启动 collector 子进程和完整 logger 的情况下运行。CPU 可支持的算法作为快速测试；CUDA graph/AMP/DP 等能力另做对应设备测试，不让 CPU fixture伪造支持。

仓库现有 APPO/TD3/FlashSAC learner 单测已经证明这条路径可行；这里是整理成稳定开发接口与 conformance helper，不是重写算法。首个 family 预计 6–10 个文件、约 350–700 行，后续每个算法增加小 adapter/contract test，永久维护成本低到中。

重写现有第 5 项（P1）：viewer 是诊断接口的消费者

“viser 增加 reward 面板”不应只是前端读取 info["log"] 的一次性功能。建议先把现有 manager iterable 数据整理成 backend-neutral、按需采样的 diagnostic snapshot/stream，至少包含 reward、metrics、termination、curriculum、command/action 摘要；算法侧消费上面的 UpdateReport/namespaced metrics。logger、测试和 viewer 复用同一数据，viewer 再增加：

• 逐 term 曲线/bar、termination/curriculum 状态；
• 复用现有 pause/single-step/reset；
• 类似 mjlab 的 checkpoint loader callback，在同一 task/viewer context 中热切换策略；
• backend 声明支持 state playback 时才提供固定状态 A/B；否则用固定 seed/reset 并明确能力边界，不能假装是完全相同轨迹。

snapshot 只读 manager 已缓存的运行数据，不解析 asset/XML，不通过 getattr/hasattr 探测 backend 私有能力，也不把 viewer 依赖放进 manager core。预计 6–10 个文件、约 300–650 行，永久维护成本低。

扩大现有第 6 项（P1）：common checkpoint envelope + algorithm-owned payload

第 6 项不应只审计一个 common_step_counter。建议定义小的公共 envelope（format version、algorithm/runtime id、progress、provenance）和 algorithm-owned payload/adapter；不要强迫所有算法使用相同内部字段。每个 runtime 必须声明并测试：

• policy/critic/target、optimizer/scaler/scheduler、normalizer 和算法内部 update counter；
• iteration、env step、curriculum/common counters；
• 若宣称 deterministic/exact resume，则还包括必要 RNG 与可恢复 env state；backend 不支持时显式声明较弱的 resume 等级；
• training resume 与 playback policy load 分开验证，legacy checkpoint 通过显式 migration/compat path 处理。

这样第 5 项的热切换只依赖 policy loader，第 1 个 P0 候选只依赖 checkpoint adapter，runner 不再各自向 shared script 暴露格式细节。预计 8–15 个文件、约 500–900 行，永久维护成本中等，也属于需 maintainer 确认的长期 contract。

明确边界

• 不做一个统一的 LearnerBase.update(dict) 来抹平 PPO/APPO/off-policy 差异；只统一 schema validation、report 和 orchestration seam。
• 不复制 mjlab 的 Tyro/Torch env、单一 RSL-RL registry，也不把算法/backend 隐藏进 task ID。
• 不在 scripts/ 承载算法 builder、checkpoint 字段或业务规则；scripts 只组装 context 并调用 runtime。
• 不新建第二套 runner/IPC lifecycle，不让 viewer 直接接触 MuJoCo/Motrix model/data。
• 上述 runtime、batch/report、checkpoint envelope 都是新的长期公共责任，必须在开发前由 maintainer 确认；可以分 issue 纵向交付，但不能只实现一个算法后就宣称平台 contract 完成。

因此，对 #1252 的优先级修正是：新增 AlgorithmRuntime 收口和 deterministic one-update harness 两个算法开发候选；把 viewer 与 checkpoint 两项改写成同一调试闭环；task route/Python materialization 仅作为次要使用体验，不再作为本轮“代码接口”的主结论。

[TATP-233]

关闭前对第 2、3、4 点做了现状核查（2026-09-05，对照 dev/issue-1042-manager-based-api 已合入 main 的状态）：

• 第 1 点（CUDA graph capture）：已完成（复选框已勾）。
• 第 2 点（DR 声明式模型字段展开）：部分落地。mjlab expand_model_fields() 机制已移植进 unisim mjwarp 后端（PR mjwarp: DR 消费能力（per-world model mutation + payload 消费） #1401，unisim/backend/mjwarp/randomization.py:47，构造期展开 + 分级 set_const* 重算 + graph-safe 原地写）；遗留的是 @requires_model_fields 风格的 per-term 声明层、更宽的字段 schema、更细的重算分级 → 拆出 DR 声明式模型字段声明层：requires_model_fields 风格的 per-term 声明与需求驱动展开（roadmap #1252 第 2 点遗留） #1498。
• 第 3 点（标准化 play variant）：部分落地。组装侧已收敛（BackendAdapter.build_play_env_cfg_override + 共享 playback session 工厂，约 46 个 owner 声明 play_profile），但 play_profile 仅渲染语义、无一 owner 在 play 时剥离 DR/noise/push/curriculum，且 play_interactive / play_hora_appo / play_viser 三个入口未消费 play profile → 拆出 标准化 play variant：play_profile 扩展到 DR/noise/push/curriculum 剥离并覆盖全部 play 入口（roadmap #1252 第 3 点遗留） #1499。
• 第 4 点（entry-point 注册）：未实现，UNILAB_EXTRA_REGISTRY_PACKAGES 仍是唯一缝，改动面已查明（集中在 registry.py 的 ensure_registries()）→ 拆出 第三方 task 包 unilab.tasks entry-point group 注册路径（roadmap #1252 第 4 点） #1500。
• 第 5、6、7 点（viser viewer 面板、curriculum resume 审计、CI 安装冒烟）：本期不推进，如需要请单独提案。

Roadmap 的治理职能完成，遗留工作以独立 implementation issue 跟踪，故关闭本 roadmap。