UniLab 与 mjlab v1.6.0 Manager-Based API 完整设计与功能对比

[TATP-233]

总结论

当前 UniLab 的 Manager-Based API 是对 mjlab v1.6.0 “Manager 组合模型”的 NumPy/多后端迁移，不是 mjlab runtime 的 drop-in replacement。

可以概括为：

维度	结论
Manager 模块、类名、Cfg 名、term 顺序	高度兼容
func + params、function/class term、局部 reset	高度兼容
Torch term 直接复制	不兼容，需要 Torch→NumPy
ManagerBasedRlEnv.step() 返回值	不兼容，UniLab 保留 NpEnvState
Scene、Entity、Sensor、Viewer	设计不同，不是同一套 runtime
Domain Randomization	调度兼容，具体能力只有部分重叠
配置系统	mjlab Python dataclass；UniLab Hydra owner YAML
后端	mjlab MuJoCo/MuJoCo-Warp；UniLab SimBackend 多后端
生产任务数量	mjlab 12；UniLab 39，其中 36 Compatible、3 Adapted
性能	没有同硬件、同配置 benchmark，不能判断优劣

因此，“兼容”的准确含义是：熟悉 mjlab Manager API 的开发者可以沿用同样的 term/config/lifecycle 心智模型；但一个依赖 Torch、mjlab Scene/Entity、Warp model fields、IK、camera/raycast 或 viewer 的 task，不能只改 import 就迁移到 UniLab。

1. 对比基线

本次比较锁定：

• UniLab：dev/issue-1042-manager-based-api，e6f136d4ef9fb560b71aa7f738c80fc0b377d79f
• mjlab：v1.6.0 / main，0fb8a681136be94ffc636a3dd423cabb97d91f10

UniLab 的 ADR-0006 正好将这个 mjlab commit 固定为迁移基线，所以这不是泛泛比较，而是可以逐文件追溯的 source-aligned migration。

需要区分三层：

1. Manager 框架是否具备相同组合能力。
2. 仓库是否提供对应的 reusable MDP term。
3. production task/backend 是否已经注册并验证该能力。

后两层不能由第一层自动推出。

2. 总体架构

mjlab
Python dataclass / Tyro
        │
        ▼
SceneCfg + EntityCfg + SensorCfg
        │  动态组合 MjSpec
        ▼
MuJoCo + MuJoCo-Warp Simulation
        │
        ▼
Torch Managers
        │
        ▼
TensorDict / RSL-RL PPO

UniLab
Hydra owner YAML
        │
        ▼
typed config materialization + Registry
        │
        ▼
task-owned XML/fragment + Entity facade
        │
        ▼
SimBackend
(MuJoCo / Motrix / mjwarp / Drake)
        │
        ▼
NumPy Managers + NpEnvState
        │
        ▼
wrapper 边界转 Torch/TensorDict
(PPO / APPO / SAC / TD3 / FlashSAC 等)

mjlab 是纵向集成的 MuJoCo runtime：Scene、Entity、Sensor、Simulation、Viewer、训练栈彼此紧密配合。

UniLab 是横向分层的 infrastructure：Manager 不接触 backend 私有对象，场景资产由 task/XML 持有，物理能力必须经 SimBackend contract 暴露，训练框架在 NpEnv 边界之外适配。

3. 公共 API 兼容度

两边 canonical public surface 基本逐名一致：

• ManagerBase、ManagerTermBase、ManagerTermBaseCfg
• ActionManager、ActionTerm、ActionTermCfg
• ObservationManager、ObservationGroupCfg、ObservationTermCfg
• RewardManager、RewardTermCfg
• TerminationManager、TerminationTermCfg
• EventManager、EventMode、EventTermCfg
• CommandManager、CommandTerm、CommandTermCfg
• CurriculumManager、CurriculumTermCfg
• MetricsManager、MetricsTermCfg
• RecorderManager、RecorderTerm、RecorderTermCfg
• SceneEntityCfg
• 对应的 Null managers

可在两边的 exports 直接核验：

• UniLab managers exports
• mjlab managers exports

UniLab 的扩展：

• 额外 re-export 六类 noise cfg：NoiseCfg、NoiseModelCfg、NoiseModelWithAdditiveBiasCfg、ConstantNoiseCfg、UniformNoiseCfg、GaussianNoiseCfg。
• 提供 ManagerBasedRLEnv / ManagerBasedRLEnvCfg 大写 RL alias；它们和 ManagerBasedRlEnv 是同一对象，没有第二套实现。
• 提供通用 make_manager_based_rl_env() factory。

关键不兼容点：

• mjlab 的 ManagerBase、ManagerTermBase、env 都有 device contract。
• UniLab 完全删除 device，term 输入输出使用 np.ndarray，manager core 不允许依赖 Torch、learner 或 runner。
• import 路径从 mjlab.* 改为 unilab.*。
• 复制 class term 时，若内部使用 .to()、.cpu()、Torch indexing 或 Warp API，必须改写。

4. Env 配置设计

配置语义	mjlab	UniLab
物理步长	sim.mujoco.timestep	sim_dt
控制步长	timestep * decimation	ctrl_dt
子步数量	decimation	sim_substeps = ctrl_dt / sim_dt
步长校验	由具体配置负责	强制有限、正数、整数倍
并行环境数	scene.num_envs	Registry/factory 的 num_envs
episode 时间	episode_length_s，默认 0.0	max_episode_seconds，必须有限且大于零
Scene	完整 SceneCfg composer	task-owned XML/fragment 描述
Simulation	env cfg 内嵌 SimulationCfg	backend owner YAML + SimBackend
Viewer	env cfg 内嵌 ViewerConfig	backend/playback 层持有
reset 默认事件	默认注入 reset_scene_to_default	events={}，owner YAML 必须显式声明
observation 输出	保留任意 group 名	显式映射为 "obs" / "critic"
配置 owner	Python dataclass/factory	Hydra owner YAML
CLI overlay	Tyro	Hydra compose

UniLab 新增两个重要字段：

• policy_observation_group
• critic_observation_group

映射到 runner-facing：

policy group -> NpEnvState.obs["obs"]
critic group -> NpEnvState.obs["critic"]

被映射的 group 必须：

• concatenate_terms=True
• 是二维 batch 中的一维 feature vector
• 维度能写入 obs_groups_spec

mjlab 则可以直接返回任意 group 名，也支持 non-concatenated nested group。

UniLab production 配置路径是：

owner YAML
  -> DictConfig
  -> typed materialization
  -> Registry/backend factory
  -> ManagerBasedRlEnv

materializer 支持 _target_、dotted callable、typed overlay、None 禁用；未知字段、错误 target、错误 term 类型和缺少必填字段均 fail-closed。代表配置可见：

• Go1 base owner
• MuJoCo owner
• Motrix owner

后端切换必须选择对应 task=<task>/<backend> owner YAML；training.sim_backend 只是身份字段，不能单独 override 来切换后端。

5. Env 返回与终止契约

mjlab

obs_dict, reward, terminated, truncated, extras = env.step(action)

所有主要数据是 Torch tensor，group 名原样保留。

UniLab

state = env.step(action)

NpEnvState(
    obs={"obs": ..., "critic": ...},
    reward=...,
    terminated=...,
    truncated=...,
    info=...,
    final_observation=...,
)

核心差异如下：

行为	mjlab	UniLab
reset()	(torch obs dict, extras)	(numpy obs dict, info)
step()	五元组	NpEnvState
auto-reset 返回 obs	done row 返回 reset 后 obs	同样返回 reset 后 obs
terminal observation	auto-reset 时不计算、不返回	reset 前计算并保存
terminal obs 位置	无正式契约	state.final_observation、info["final_observation"]
terminal row mask	无	info["_final_observation"]
auto_reset=False	返回真实 terminal obs，下一步前必须 reset	相同约束
finite horizon timeout	raw env 仍放在 truncated	直接重映射为 terminated=True

mjlab 的 is_finite_horizon 主要影响 RSL-RL wrapper 是否提供 bootstrap 使用的 extras["time_outs"]；raw env 仍返回 timeout 为 truncated。

UniLab 在 env 层完成语义重映射：

• infinite horizon：timeout → truncated
• finite horizon：timeout → terminated

UniLab 的 final-observation contract 对 off-policy replay、正确 bootstrap 和异步采集尤其重要。NpEnvState 与 auto-reset 实现 可见其先复制 terminal observation，再执行局部 reset 和 obs scatter。

6. 初始化、step、reset 时序

初始化

mjlab：

1. 构造完整 Scene，组合 MjSpec。
2. 构造 Simulation 并初始化 Scene/Entity/Sensor。
3. 构造 managers。
4. EventManager 声明需要的 Warp model fields。
5. Simulation 扩展 per-world model fields。
6. 执行 startup events。
7. 初始化 viewer/debug visualizer。

UniLab：

1. 校验 typed cfg、num_envs 与 backend 一致性。
2. 建立 env-owned NumPy RNG。
3. 冷路径解析默认 keyframe、entity 名称与 ID。
4. 建立 EntityScene facade 和 ResetStateTransaction。
5. 按 mjlab 依赖顺序构造 managers。
6. 校验 observation mapping、substep action/metrics 能力。
7. 执行 startup events。
8. 恰好调用一次 SimBackend.materialize()。

单步时序

mjlab：

process action
  -> 对每个 decimation 子步：
       apply action
       scene.write_data_to_sim
       sim.step
       scene.update
       per-substep metrics
  -> termination
  -> reward
  -> metrics
  -> step/interval events
  -> auto-reset
  -> sim.forward（全环境一次）
  -> command
  -> sim.sense
  -> observation
  -> recorder
  -> 五元组返回

mjlab 源码明确说明：MuJoCo mj_step 的 placement 导致 termination、reward、event 所读的部分 derived quantity 落后最后一个 physics substep；随后统一 sim.forward()，保证 observation 刷新。

UniLab：

process action
  -> 无反馈依赖：一次写入控制目标
     有反馈依赖：backend pre-step callback 每子步执行
  -> SimBackend.step(ctrl, sim_substeps)
  -> update-phase backend state read cache
  -> termination
  -> reward
  -> metrics
  -> step/interval events + cache invalidation
  -> command transaction + commit/invalidation/post_compute
  -> terminal observation
  -> NpEnv 捕获 final_observation
  -> partial auto-reset
  -> 只 scatter reset rows 的新 observation
  -> NpEnvState 返回

UniLab 不在 env 内直接循环 backend 私有 physics API；子步生命周期由 SimBackend.step() 所有。

reset

mjlab reset 核心顺序：

curriculum
-> sim.reset
-> scene.reset
-> reset events
-> observation/action/reward/metrics/curriculum/command/event/termination reset
-> write_data_to_sim
-> forward
-> command(dt=0)
-> sense
-> observation

UniLab reset：

curriculum
-> reset events + command reset 写入 ResetStateTransaction
-> 所有写入成功后一次 SimBackend.set_state
-> manager-local buffer reset
-> command(dt=0, reset rows)
-> row-scoped observation rebuild
-> scatter reset rows

这种 transaction 设计是为了避免多个 reset/event term 各自直接写 backend，并确保 backend mutation 仍由 owner contract 控制。

7. 各 Manager 功能矩阵

Manager	共同设计	UniLab 的适配或差异
Base/Term	func + params、function/class term、插入顺序、局部 reset	NumPy；无 device；加强 cfg、shape、dtype、finite 校验
Action	按 term 切分 action，维护 current/previous action，process/apply 分离	新增 requires_substep_state_feedback；无反馈时只 dispatch 一次
Observation	group、concat、noise、clip、scale、delay、history	默认 nan_policy="error"；runner boundary 只映射 policy/critic
Reward	加权和、可选 dt scaling、episode sum	非有限值直接报错；增加 reward/<term> runner log
Termination	普通 termination 与 time_out=True timeout 分离	强制 bool dtype；finite-horizon 在 env 层重映射
Event	startup/reset/interval/step、global/per-env timer、reset 最小间隔	不支持 Warp model_fields；mutation 走 backend capability
Command	timer、resample、counter、metrics、局部 reset	命令/metric shape 与 finite 校验；增加 post_compute()
Curriculum	reset 时更新 cfg/状态、class term reset	NumPy 化，并验证 curriculum state 为有限值
Metrics	last/max/mean/sum、per_substep	sim_substeps>1 时不支持 per_substep，构造阶段直接失败
Recorder	pre_reset/post_reset/post_step/close hooks	lifecycle 保留，但 terminal-observation 语义已因 NpEnv 改变

Observation 细节

两边 term pipeline 相同：

compute -> noise -> clip -> scale -> delay -> history

共同支持：term/group history、flatten 或保留 history 维、per-env 或共享 delay、hold probability、update period、per-env phase、partial reset history backfill、concatenated 或 term dict 输出。

差异：

• mjlab 默认 nan_policy="disabled"。
• UniLab 默认 "error"，并更严格检查数组类型、batch shape、dtype、range 和有限值。
• UniLab partial-reset observation 只重建目标 rows；为保持随机流一致，noise 仍按 full batch draw。
• mjlab partial compute 的 term 通常仍产生 full-batch tensor，只将 reset effects 作用到目标 rows。

Reward

mjlab 在 reward term 计算后执行 torch.nan_to_num(value, nan=0.0, posinf=0.0, neginf=0.0)，即异常 reward 会静默归零。

UniLab 在 Manager term 边界直接抛错，非法输出正常情况下不会到达 NpEnv 的通用最终 sanitize。这更符合 fail-closed，但意味着某些原来“带病训练”的 mjlab task 会在 UniLab 立即停止。

Command 的源兼容陷阱

mjlab 使用 _update_metrics(self)，UniLab 使用 _update_metrics(self, env_ids: np.ndarray | None = None)。

UniLab 这样做是为了 reset-row scoped 更新。因此直接复制一个覆盖零参数 _update_metrics() 的 mjlab command term，需要改签名。UniLab 还增加 post_compute()，用于 command transaction commit 后刷新派生状态。

mjlab 额外提供 DebugVisualizer、Viser GUI controls、viewer pause callback、GUI reset override、per-term debug checkbox。UniLab manager core 不拥有 viewer glue；debug_vis=True 会显式 NotImplementedError。

8. Reusable MDP term 覆盖

这里比较的是仓库共享 envs/mdp namespace，不代表 task-specific term 的总数。

Action

mjlab 内置 joint position、relative joint position、joint velocity、joint effort、tendon length/velocity/effort、site effort、Differential IK。

UniLab 共享 action namespace 目前只有 JointPositionAction。部分 production task 有自有 action term，例如 Allegro、Stewart 等，但它们不是上述通用 action API 的等价补齐。

Observation

共同项主要包括 base linear/angular velocity、projected gravity、relative joint position/velocity、last action、generated commands、built-in named sensor、sensor-derived projected gravity。

mjlab 共享层另外有 height_scan，并依赖完整 raycast sensor。UniLab named sensor term 在冷路径调用 backend bind_sensor_data(names)；热路径只读 immutable view，不重新解析 sensor 名称或 XML。

Reward

共同项包括 alive/terminated、joint velocity L2、action rate/acceleration、flat orientation。

mjlab 共享层额外包括 joint torque/acceleration、joint limits、posture、electrical power。UniLab 共享层额外包括 linear/angular velocity tracking、body angular velocity penalty。

大量 locomotion、motion tracking 和 manipulation reward 位于各自 task-owned manager term 模块，不能只看共享文件推断 production 覆盖。

Termination

共同项包括 timeout、bad orientation、root height below threshold。mjlab 额外有通用 nan_detection；UniLab 主要通过 manager/NpEnv 边界校验处理非法数值。

Event 与 Domain Randomization

mjlab 的完整 model-field DR namespace 覆盖 actuator、body、camera、geom、joint、light、material、contact pair、site、tendon。

其核心设计包括 requires_model_fields、RecomputeLevel、MuJoCo-Warp per-world model-field expansion，以及修改后按 recompute level 更新 derived model data。

UniLab 发现携带 model_fields metadata 的 event 会直接报 NotImplementedError，不会绕过 backend contract。

UniLab 当前共享 reusable event/DR 包括 reset scene/default/root state、geom friction、joint armature、PD gains、rigid-body mass、rigid-body COM、scene gravity、velocity push。

限制包括：

• capability 是否可用取决于具体 SimBackend。
• body mass 的 recompute_inertia=True 当前不支持。
• velocity push 当前正式支持 linear delta，angular range 不支持。
• unsupported capability 是异常，不会 warning 后 skip。

mjlab 共享 events 还覆盖 terrain patch reset、joint offset reset、external force/torque 和 body impulse 等。

9. Scene、Entity、Sensor 与 keyframe

能力	mjlab	UniLab
Scene 定位	完整 composer	已有 task scene 的描述/facade
Scene 输入	terrain、entities、sensors、spacing、extent、spec_fn	model_file、fragments、terrain slot、entity partitions
Entity 构造	EntityCfg.spec_fn() 生成/编辑 MjSpec	不构造机器人，只声明已有 scene 中的名称分区
actuator/material/geom 编辑	Entity build 阶段支持	必须由 asset/backend owner 提供
keyframe	从 Entity XML 提取并在 Scene 合并	default_keyframe_name 引用 task-level XML
state view	完整 Torch/Warp EntityData	最小正式 NumPy facade
sensor	builtin、camera、raycast、contact、terrain-height	backend-owned named sensor view
model/data 暴露	Entity/Simulation 内部直接持有	manager 不可接触 backend model/data

mjlab 的 EntityData 提供很宽的状态面，包括 root/body/COM/geom/site pose 与 velocity、joint position/velocity/acceleration/force、tendon state/target、site effort target、external wrench、actuator state、camera/light/material indexing。

UniLab 当前正式 facade 主要覆盖 root/body pose 与 velocity、joint position/velocity/default/soft limits、joint-position target、reset/DR 所需正式写入口、named sensor view，以及 projected gravity 等可由正式状态派生的值。

SceneEntityCfg 的 selector 表面仍与 mjlab 基本一致，包括 joint/body/geom/site/actuator/tendon/camera/light/material/texture/pair，且保留 regex、preserve_order、names/IDs 一致性检查和全选压缩。

但若 UniLab Entity/backend 没有正式暴露 tendon、camera、light 等能力，resolve 阶段会 fail-closed；selector 字段存在不等于 capability 已实现。

keyframe 所有权也完全不同：

• mjlab 允许 Entity/robot 生成 keyframe，再由 Scene 合并。
• UniLab 要求 keyframe 属于 task/scene fragment；robot XML 保持纯机器人描述。Motrix 需要时通过 scene.fragment_files 引入。

相关实现：

• UniLab SceneCfg
• UniLab Entity facade
• mjlab Scene composer
• mjlab Entity

10. Backend 与 Viewer

mjlab runtime 固定为 MuJoCo + MuJoCo-Warp，device 可配置，但 Manager、Entity、Sensor 与物理实现都围绕这套技术栈设计。

UniLab factory 可识别 mujoco、motrix、mjwarp、drake。这表示存在 backend 路由，不表示每个 task 或 manager capability 都在四个 backend 上支持。

当前 Registry 路由统计：

项目	数量
production tasks	39
MuJoCo registrations	39
Motrix registrations	38
mjwarp registrations	1
Drake registrations	8

UniLab 的 viewer/playback 由 backend 和 visualization/ 层拥有，不属于 Manager API。因而不能将“UniLab 能播放或渲染”理解为“具备 mjlab Manager DebugVisualizer/Viser GUI API”。

11. RNG 与可复现性

mjlab：

• seed() 重置 Torch、NumPy、Python、Warp 等进程级/global RNG。
• term 通常通过 Torch 全局随机函数采样。
• cfg.seed=None 的 docstring 声称会生成 seed 并写回，但当前 env 源码只在 seed 非空时调用 seed()；这是源码与文档不一致。

UniLab：

• seed=None 时用 secrets.randbits(63) 生成实际 seed，并写回 cfg。
• 每个 env 持有自己的 np.random.Generator。
• events、noise、delay、commands 共用该 env-owned generator。
• seed() 只替换该 generator 的状态，不重置整个进程的随机状态。

所以两边即使使用相同整数 seed，也不能期待 Torch 与 NumPy 随机序列逐样本一致。

12. Registry、训练和 Sim2Sim

mjlab

Task registry 一次保存 training env cfg、play env cfg、RSL-RL cfg 和 optional runner class，加载时 deep copy。训练入口主要围绕 RSL-RL PPO，raw Torch observation 可以直接包装为 TensorDict。CLI 通过 Tyro overlay Python dataclass。

参见 mjlab task registry。

UniLab

Registry 分离 env config 类型/factory、每个 backend 的 env factory、Hydra task/backend owner 和 algorithm owner 配置。

NumPy env 在 wrapper 边界转换为 Torch/TensorDict。仓库提供 PPO、APPO、SAC、TD3、FlashSAC 等入口，但这不表示每个 task 都支持所有算法，实际支持必须由对应 YAML、注册和测试证明。

Sim2Sim

UniLab 独有跨 backend contract snapshot 和 checkpoint dimension guard。

当前 DENYLIST 为：

algo.obs_groups
env.control_config.action_scale
env.observations
env.actions
env.policy_observation_group
env.critic_observation_group
algo.policy.actor_hidden_dims
algo.policy.critic_hidden_dims
algo.empirical_normalization
algo.obs_normalization
env.commands.motion.params.sampling_mode

这些字段不一致时默认抛 CrossBackendIncompatibleError。其中 env.* structural 字段只在一侧出现也会 fail-closed。

WARNING_LIST 包括 reward tuning、action latency、ctrl_dt；ALLOWLIST 包括 backend identity、scene、play steps、domain randomization、noise 等。

其他行为：

• 训练时写入 run_config.json.contract_snapshot。
• 旧 run 没有 snapshot 时发出 warning 并跳过 enforcement。
• checkpoint shape mismatch 被重新解释为显式 sim2sim 诊断。
• training.sim2sim_strict=false 可将 DENYLIST 差异降为 warning。

实现见 sim2sim.py。mjlab 当前没有对应的 repository-level 跨物理后端契约，因为其 runtime 本身不是多 backend 抽象。

13. Production task 覆盖

mjlab：12 个静态注册 task

• Cartpole：Balance、Swingup，共 2
• Yam manipulation：lift RGB/depth/segmentation 等，共 4
• G1 tracking：普通、No-State-Estimation，共 2
• G1/Go1 velocity：flat/rough，共 4

UniLab：39 个 production task

迁移矩阵划分为：

• 8 个 canonical manager-based：A2JoystickFlat、AllegroInhandRotation、AllegroInhandRotationGrasp、Go1JoystickFlat、Go2FootStand、Go2JoystickFlat、Go2WJoystickFlat、StewartBalance
• 3 个 rough：Go1JoystickRough、Go2JoystickRough、Go2WJoystickRough
• 4 个 G1 locomotion：G1WalkFlat、G1WalkRough、G1Walk23DofFlat、G1Walk23DofRough
• 6 个 motion core
• 15 个 motion tracking/profile task
• 3 个 Adapted compatibility seam：Go2ArmManipLoco、SharpaInhandRotation、SharpaInhandRotationGrasp

总计：

Compatible: 36
Adapted:     3

这里的 Compatible 表示使用 canonical NumPy Manager-Based runtime，不表示与旧 env 或 mjlab task 数值行为完全相同。

例如 rough migration matrix 明确记录以下 legacy reward 尚未 manager port：

• feet_gait
• feet_air_time 及 variance
• feet_contact_without_cmd
• feet_height_body
• feet_slide
• contact_forces
• undesired_contacts
• joint_mirror
• joint_power
• joint_torques_l2
• joint_acc_l2 及 wheel variant

完整事实边界见 migration_matrix.py。

14. 实际迁移成本

mjlab term 类型	迁移到 UniLab 的预计成本
纯 observation/reward/termination function，只读共同 entity fields	低到中：import、Torch→NumPy、Hydra 配置
class term，包含 buffer/history/RNG	中：改 NumPy buffer、env-owned RNG、partial reset
使用 device、.to()、Torch indexing	中：机械改写并重新验证 shape/dtype
使用 mjlab 完整 EntityData 字段	中到高：先确认 UniLab facade/backend capability
joint velocity/effort、tendon/site action	高：缺少通用 action term 或 backend contract
Differential IK	高：需要单独的正式 IK/action capability
camera/raycast/contact sensor	高：不是当前 named-sensor facade 的机械迁移
requires_model_fields DR	高或当前 unsupported
Scene composer、MjSpec editor、Entity material editor	高：与 UniLab asset ownership 冲突
DebugVisualizer、Viser GUI	高或当前 unsupported

最容易迁移的例子是纯数值 term：

# mjlab
return torch.square(x).sum(dim=1)

# UniLab
return np.square(x).sum(axis=1)

如果迁移需要在 term 中加入 backend 分支、访问 model/data 私有对象，说明缺的是 owner-layer contract，不能在 task term 内绕过。

15. 选型判断

如果目标是：

• 最大化复用 mjlab 上游 Scene、Entity、Warp DR、IK、camera/raycast 和 viewer；
• backend 明确只使用 MuJoCo/MuJoCo-Warp；
• 希望 term 保持 Torch/device-native；

那么 mjlab 的完整 runtime 更直接，内置功能也更宽。

如果目标是：

• 进入 UniLab 的 NpEnvState、async/off-policy/training contract；
• 由 Hydra owner YAML 管理 task、reward 和 backend；
• 需要 MuJoCo/Motrix/mjwarp/Drake 路由；
• 需要 sim2sim 配置审计和 final-observation contract；
• 要求 backend isolation、cold-path asset access 和 unsupported capability fail-closed；

那么应使用 UniLab Manager-Based runtime，但把它视为“mjlab 风格组合 API + UniLab runtime”，而不是 mjlab runtime 的替身。

若要继续提高两者功能覆盖，优先级应是：

1. 为 SimBackend 增加正式 post-substep hook，解除 metrics 限制。
2. 单独扩展通用 velocity/effort/tendon/site/IK action contract。
3. 扩展 camera/raycast/contact sensor facade。
4. 设计跨 backend 的 model-property DR 与 recompute contract。
5. 再考虑 manager debug visualization，而不是把 viewer 逻辑带入 manager core。

这些都属于新公共 contract 或 backend production 能力，按当前仓库治理规则应拆成独立 issue，不适合顺手补齐。

16. 已知文档漂移与验证

发现两处值得单独记录的源码/文档差异：

• mjlab seed=None docstring 与实际初始化行为不一致。
• UniLab RecorderTerm.record_pre_reset docstring 仍沿用 mjlab 语义，声称看不到 post-action terminal observation；但当前 NpEnv 已先计算并保存 terminal observation，再进入 reset hook。这更像文档尚未同步，不宜直接判定为实现缺陷。

验证结果：

uv run pytest tests/managers tests/envs/test_manager_based_rl_env.py -q
111 passed in 0.52s

最终状态：

• UniLab 工作树干净。
• mjlab 工作树干净。
• 对比过程未修改任何文件。
• 没有同硬件、同配置 benchmark，因此本文不作吞吐量、训练速度或显存效率优劣结论。