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

AGENTS.md

@@ -34,7 +34,7 @@ UniLab 是一个 **高性能、模块化、contract 驱动** 的 RL infrastructu
 - **WARNING_LIST**：`reward.*`、`env.control_config.simulate_action_latency`、`env.ctrl_dt`。
 - **ALLOWLIST**（自由覆盖）：`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`（不改 checkpoint 格式，旧 run 无 snapshot 时 fallback + warning）；五个 play 入口在建 env 前调用 `resolve_sim2sim_config` 校验，并用 `policy_load_dim_guard` 包裹 checkpoint 加载以把维度不匹配的隐晦报错重抛为显式诊断。设 `training.sim2sim_strict=false` 可把 DENYLIST 差异降级为 warning（默认 `true`）。DENYLIST 字段应通过 task 的 `base.yaml` 共享（范例：`conf/ppo/task/g1_walk_flat/{base,mujoco,motrix}.yaml`）；跨后端契约审计见 `scripts/audit_sim2sim_contracts.py`。
+训练时 `ExperimentTracker.start()` 把上述字段写入 `run_config.json` 的 `contract_snapshot`（不改 checkpoint 格式，旧 run 无 snapshot 时 fallback + warning）；五个 play 入口在建 env 前调用 `resolve_sim2sim_config` 校验，并用 `policy_load_dim_guard` 包裹 checkpoint 加载以把维度不匹配的隐晦报错重抛为显式诊断。设 `training.sim2sim_strict=false` 可把 DENYLIST 差异降级为 warning（默认 `true`）。DENYLIST 字段在每个后端 owner 配置中显式声明并保持跨后端一致（范例：`conf/ppo/task/g1_walk_flat/{mujoco,motrix}.yaml`）；跨后端契约审计见 `scripts/audit_sim2sim_contracts.py`。
 
 ## Pointers
 

README.md

@@ -132,7 +132,7 @@ uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1
 uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1 --render-mode record
 ```
 
-This routes through the `go2_joystick_flat/motrix` task owner config and keeps backend selection explicit.
+This routes through the `go2_joystick_flat/motrix` task owner config and keeps backend selection explicit. Each backend owner carries an optional `play_profile` block that layers render-only overrides at eval time (`training.play_only=true`) without affecting training.
 
 On macOS / MacBook, the UniLab CLI routes Motrix interactive playback through `mxpython` when needed. Motrix defaults to interactive playback; use `--render-mode record` for headless video export or `--render-mode none` to skip playback. Detailed script-level commands are in the [Training Guide](https://unilabsim.github.io/UniLab-doc/en/2-user_guide/1-training/0-index.html).
 

README_zh.md

@@ -134,7 +134,7 @@ uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1
 uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1 --render-mode record
 ```
 
-这会路由到 `go2_joystick_flat/motrix` 任务 owner 配置，并保持后端选择显式化。
+这会路由到 `go2_joystick_flat/motrix` 任务 owner 配置，并保持后端选择显式化。每个后端 owner 带一个可选的 `play_profile` 块，在 eval 时（`training.play_only=true`）叠加仅渲染相关的覆盖，不影响训练。
 
 在 macOS / MacBook 上，UniLab CLI 在需要时会通过 `mxpython` 路由 Motrix 交互式回放。Motrix 默认使用交互式回放；要导出无头视频请使用 `--render-mode record`，要跳过回放请使用 `--render-mode none`。更细的脚本级命令请参阅 [训练指南](https://unilabsim.github.io/UniLab-doc/zh_CN/2-user_guide/1-training/0-index.html)。
 

conf/ppo/task/allegro_inhand/motrix.yaml

@@ -50,3 +50,7 @@ env:
     joint_noise: 0.0
     ball_vel_noise: 0.0
     ball_z_offset: 0.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/allegro_inhand/mujoco.yaml

@@ -54,3 +54,7 @@ env:
     joint_noise: 0.0
     ball_vel_noise: 0.0
     ball_z_offset: 0.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/allegro_inhand_grasp/motrix.yaml

@@ -31,3 +31,7 @@ env:
     push_robots: false
     ball_vel_noise: 0.0
     joint_noise: 0.25 # random sampling of the grasp poses
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/allegro_inhand_grasp/mujoco.yaml

@@ -31,3 +31,7 @@ env:
     push_robots: false
     ball_vel_noise: 0.0
     joint_noise: 0.25 # random sampling of the grasp poses
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_box_tracking/mujoco.yaml

@@ -42,3 +42,7 @@ reward:
   std_joint_vel: 1.0
   std_object_pos: 0.2
   std_object_ori: 0.3
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_climb_tracking/motrix.yaml

@@ -78,3 +78,7 @@ reward:
   std_body_ang_vel: 3.14
   std_joint_pos: 0.2
   std_joint_vel: 1.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_climb_tracking/mujoco.yaml

@@ -78,3 +78,7 @@ reward:
   std_body_ang_vel: 3.14
   std_joint_pos: 0.2
   std_joint_vel: 1.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_flip_tracking/motrix.yaml

@@ -32,3 +32,7 @@ reward:
   std_body_ang_vel: 3.14
   std_joint_pos: 0.2
   std_joint_vel: 1.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_flip_tracking/mujoco.yaml

@@ -78,3 +78,7 @@ reward:
   std_body_ang_vel: 3.14
   std_joint_pos: 0.2
   std_joint_vel: 1.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_motion_tracking/mujoco.yaml

@@ -32,3 +32,7 @@ reward:
   std_body_ang_vel: 3.14
   std_joint_pos: 0.2
   std_joint_vel: 1.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_walk_flat/motrix.yaml

@@ -1,10 +1,7 @@
 # @package _global_
-# Inherits base.yaml, then overrides contract fields for Motrix-specific tuning
+# Standalone Motrix owner config: carries the shared contract inline, then
+# overrides contract fields for Motrix-specific tuning
 # (intentionally non-transferable from MuJoCo; drop overrides to restore parity).
-defaults:
-  - /task/g1_walk_flat/base
-  - _self_
-
 training:
   task_name: G1WalkFlat
   sim_backend: motrix
@@ -18,6 +15,8 @@ algo:
     critic:
       - critic
   policy:
+    actor_hidden_dims: [512, 256, 128]
+    critic_hidden_dims: [512, 256, 128]
     init_noise_std: 0.5
   algorithm:
     learning_rate: 3.0e-4
@@ -67,3 +66,7 @@ reward:
   min_forward_speed_for_gait_reward: 0.05
   min_base_height: 0.5
   max_tilt_deg: 35.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_walk_flat/mujoco.yaml

@@ -1,16 +1,22 @@
 # @package _global_
-# Inherits the shared contract from base.yaml; backend-specific tuning only.
-defaults:
-  - /task/g1_walk_flat/base
-  - _self_
-
+# Standalone MuJoCo owner config: carries the shared cross-backend contract inline
+# (formerly base.yaml), plus backend-specific tuning.
 training:
   task_name: G1WalkFlat
   sim_backend: mujoco
 algo:
   num_envs: 2048
   max_iterations: 2200
+  empirical_normalization: false
+  obs_groups:
+    actor:
+      - actor
+  policy:
+    actor_hidden_dims: [512, 256, 128]
+    critic_hidden_dims: [512, 256, 128]
 env:
+  control_config:
+    action_scale: 0.25
   curriculum:
     enabled: false
   noise_config:
@@ -37,3 +43,7 @@ reward:
   min_base_height: 0.55
   max_tilt_deg: 25.0
   pose_weights: [0.01, 1.0, 5.0, 0.01, 5.0, 5.0, 0.01, 1.0, 5.0, 0.01, 5.0, 5.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0, 50.0]
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/g1_wall_flip_tracking/mujoco.yaml

@@ -78,3 +78,7 @@ reward:
   std_body_ang_vel: 3.14
   std_joint_pos: 0.2
   std_joint_vel: 1.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go1_joystick_flat/motrix.yaml

@@ -43,3 +43,7 @@ reward:
     swing_feet_z: 4.0
   tracking_sigma: 0.25
   base_height_target: 0.3
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go1_joystick_flat/mujoco.yaml

@@ -34,3 +34,7 @@ reward:
     swing_feet_z: 4.0
   tracking_sigma: 0.25
   base_height_target: 0.3
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go1_joystick_rough/motrix.yaml

@@ -115,3 +115,7 @@ reward:
   feet_gait_max_err: 0.2
   feet_gait_velocity_threshold: 0.5
   feet_gait_command_threshold: 0.1
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go1_joystick_rough/mujoco.yaml

@@ -116,3 +116,7 @@ reward:
   feet_gait_max_err: 0.2
   feet_gait_velocity_threshold: 0.5
   feet_gait_command_threshold: 0.1
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2_arm_manip_loco/mujoco.yaml

@@ -106,3 +106,7 @@ env:
     freeze_arm_joints: false
     disable_ee_goal_trajectory: false
     fixed_ee_goal_cart: [0.15, 0.0, 0.25]
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2_joystick_flat/motrix.yaml

@@ -35,3 +35,7 @@ reward:
     swing_feet_z: 4.0
   tracking_sigma: 0.25
   base_height_target: 0.3
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2_joystick_flat/mujoco.yaml

@@ -27,3 +27,7 @@ reward:
     swing_feet_z: 4.0
   tracking_sigma: 0.25
   base_height_target: 0.3
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2_joystick_rough/motrix.yaml

@@ -114,3 +114,7 @@ reward:
   feet_gait_max_err: 0.2
   feet_gait_velocity_threshold: 0.5
   feet_gait_command_threshold: 0.1
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2_joystick_rough/mujoco.yaml

@@ -116,3 +116,7 @@ reward:
   feet_gait_max_err: 0.2
   feet_gait_velocity_threshold: 0.5
   feet_gait_command_threshold: 0.1
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2w_joystick_flat/motrix.yaml

@@ -45,3 +45,7 @@ reward:
     upward: 1.0
   tracking_sigma: 0.25
   base_height_target: 0.4
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2w_joystick_flat/mujoco.yaml

@@ -44,3 +44,7 @@ reward:
     upward: 1.0
   tracking_sigma: 0.25
   base_height_target: 0.4
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2w_joystick_rough/motrix.yaml

@@ -93,3 +93,7 @@ reward:
   tracking_sigma: 0.25
   base_height_target: 0.4
   only_positive_rewards: false
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/go2w_joystick_rough/mujoco.yaml

@@ -93,3 +93,7 @@ reward:
   tracking_sigma: 0.25
   base_height_target: 0.4
   only_positive_rewards: false
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/sharpa_inhand/motrix.yaml

@@ -20,3 +20,7 @@ env:
     randomize_gravity: false
     randomize_gravity_direction: true
     randomize_pd_gains: true
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/sharpa_inhand/mujoco.yaml

@@ -99,3 +99,7 @@ env:
     joint_noise_scale: 0.02
     contact_latency: 0.005
     contact_sensor_noise: 0.01
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/sharpa_inhand_grasp/motrix.yaml

@@ -12,3 +12,7 @@ env:
   domain_rand:
     randomize_gravity: false
     randomize_gravity_direction: false
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/sharpa_inhand_grasp/mujoco.yaml

@@ -100,3 +100,7 @@ env:
       - contact_right_pinky_elastomer_force
   disable_tactile_ids: []
   grasp_collection_target: 10000
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/stewart_balance/motrix.yaml

@@ -46,3 +46,7 @@ reward:
     progress: 0.6
     still: 3.0
   fall_penalty: -6.0
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

conf/ppo/task/stewart_balance/mujoco.yaml

@@ -11,3 +11,7 @@ defaults:
 training:
   task_name: StewartBalance
   sim_backend: mujoco
+play_profile:
+  enabled: true
+  env:
+    render_spacing: 2.0

docs/sphinx/source/en/3-deployment/2-sim_to_sim/0-index.md

@@ -42,6 +42,12 @@ Understand renderer and snapshot capability differences.
 Document unsupported backend features with evidence.
 :::
 
+:::{grid-item-card} Config guard
+:link: 7-config_guard
+:link-type: doc
+Auto-check policy contract compatibility on cross-backend replay.
+:::
+
 ::::
 
 ```{toctree}
@@ -53,4 +59,5 @@ Document unsupported backend features with evidence.
 4-reward_parity
 5-playback_and_snapshot_differences
 6-capability_gaps
+7-config_guard
 ```