# feat(sim2sim): 跨后端契约 guard + train/play 配置解耦(关于pr #660)

[LeeLeno]

概述

为双后端 task(MuJoCo ↔ Motrix)引入 sim2sim 契约守卫机制,在跨后端 play/eval 时自动检测策略 I/O 不兼容,并通过 play_profile 实现 train/play 配置逻辑解耦。

核心变化:

• ✅ 训练时自动快照策略契约字段(obs/action/网络结构)至 run_config.json
• ✅ 跨后端 play 时强制校验契约一致性,不兼容即报错 CrossBackendIncompatibleError
• ✅ 36 个 task 支持 play_profile 块,渲染/scene 配置只在 eval 生效、train 路径零污染
• ✅ 配置从「共享 base.yaml + 继承」重构为「自包含 owner + 内联契约」(文件数 -23)

---

1. 守卫机制:拦截跨后端不兼容

DENYLIST(7 个):差异即报错

影响策略 I/O 的核心字段,训练与播放必须完全一致:

字段	守卫理由
algo.obs_groups	策略输入分组,影响观测维度
env.control_config.action_scale	动作缩放,改变物理执行范围
algo.policy.actor_hidden_dims	actor 网络结构,checkpoint 加载会 shape mismatch
algo.policy.critic_hidden_dims	critic 网络结构
algo.empirical_normalization	观测归一化,改变输入预处理
algo.obs_normalization	另一种归一化实现
env.sampling_mode	privileged obs 等,影响观测维度

WARNING_LIST(6 个):差异仅告警

不影响策略加载,但可能影响指标显示:

• reward.scales, reward.base_height_target, reward.max_tilt_deg, reward.min_base_height(eval 不训练,reward 只影响指标)
• env.control_config.simulate_action_latency, env.ctrl_dt(仿真细节)

ALLOWLIST(6 个):自由覆盖

渲染/播放专属,或训练时就允许随机化:

• 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 字段)
• Eval 时:5 个 play 入口(rsl_rl / appo / offpolicy / mlx_ppo / him_ppo)调 resolve_sim2sim_config 比对目标配置 vs 源快照
• 跨后端差异:DENYLIST 不匹配 → raise CrossBackendIncompatibleError(默认);设 training.sim2sim_strict=false 可降级为 warning

---

2. play_profile:train/play 逻辑解耦

机制

同一 owner 配置(mujoco.yaml / motrix.yaml)内,通过 play_profile 块 + training.play_only 标志区分:

• train:play_only=false → play_profile 被短路忽略,训练契约生效
• eval:play_only=true(cli 自动注入)→ 训练契约 + 叠加 play_profile

play_profile 可覆盖的内容

A. play_profile.env.* — 任意 env 层字段

直接 dict.update 叠加到 env_cfg_override,喂给 create_env:

• ✅ ALLOWLIST 字段:如 scene、domain_rand、noise_config — 写了就生效
• ✅ 任意其他 env 配置:如 render_spacing(当前 36 个 task 在用)、reset_base_qvel_limit、curriculum 等
• ⚠️ DENYLIST env 子集:如 action_scale — 可写,本后端 play 会生效,但跨后端时 guard 拦截
• ❌ reward/algo:不在 env_override 管辖,写了无效

B. play_profile.scene.* — scene 重建(纯视觉层)

play_profile:
  scene:
    enabled: true
    source_model_file: assets/robots/xxx.xml
    ground_texture_file: assets/textures/floor.png  # 可选
    skybox_rgb1: [0.9, 0.9, 0.91]
    ground_texrepeat: [4, 4]