motrix 后端 base 相对 frame sensor 对 root body 退化恒零：get_body_*_vel_b 语义契约讨论

[TATP-233]

背景

MBA（Manager-Based API）迁移后，appo Go2JoystickFlat motrix 训练结果与 main 分支差异较大（final return 28.3 vs 39.9）。排查后确认根因是一个后端语义问题，目前已在 task 层止血（见下方"临时方案"），但结构性问题留待后续处理，先开此 discussion 记录。

问题

motrix 后端的 get_body_lin_vel_b / get_body_ang_vel_b（src/unilab/base/backend/motrix/backend.py）通过自动添加的 frame sensor（track_linvel_b_<link> / track_angvel_b_<link>，scene.py 中 add_motrix_tracking_frame_sensors）实现，这些 sensor 的 ref_frame 固定为 base link。

motrix 的 FrameSensor 返回的是相对运动：当 object 与 ref_frame 同为 base（即查询 root body 自身的机体系速度）时，读数恒为零。

实测：给 base 设世界系速度 [0.5, -0.2, 0.8] 并 step，track_linvel_b_base 读出 [0, 0, 0]（角速度同理）。

影响

MBA 迁移时 quadruped 的四个基座速度 reward 项（tracking_lin_vel / tracking_ang_vel / lin_vel_z / ang_vel_xy）从 legacy 的 IMU 传感器（local_linvel / gyro）改读 Entity.data.root_link_*_vel_b，在 motrix 上全部拿到恒零信号：

• lin_vel_z / ang_vel_xy 惩罚恒为 0（Tensorboard 全程精确 0.0）；
• tracking_lin_vel 退化为 exp(-cmd²/0.25)，与真实速度无关，无法学习跟踪（停在 0.44，policy entropy 全程 17 不收敛）。

G1 没踩坑是因为它的 manager terms 是 sensor-bound 的（pelvis_local_linvel / torso_gyro）。

临时方案（已随 dev/issue-1042 分支提交）

task 层对齐 legacy：四足各 owner 配置（go1/go2/go2w/a2/rough 全家族）的四个速度项切换到新增的 sensor-bound 实现（unilab.tasks.locomotion.common.manager_terms.track_lin_vel 等），绑定 XML 具名传感器；SensorTermBase 抽到 locomotion/common/sensor_terms.py 供 g1 与 quadruped 复用。修复后复跑 tracking_lin_vel 恢复 0.37→0.78 的正常学习曲线。

结构性问题

get_body_*_vel_b 的语义契约本身需要钉死。参考 mjlab（mjlab/entity/data.py）：

root_link_lin_vel_b = quat_apply_inverse(root_link_quat_w, root_link_lin_vel_w)

即"世界系速度 × 根姿态逆旋转"的解析式实现，对任意 body 都有良好定义。mjlab 是单后端所以可以一条路走通；UniLab 多后端下各后端自行实现该能力，motrix 选了 base 相对 frame sensor 这条路，对 root 退化。

待讨论的决策点

1. 语义契约：get_body_lin_vel_b(body) 应该定义为"世界系速度表达到该 body 坐标系"（mjlab/Isaac 风格解析式），还是"相对 base 的运动"（当前 motrix frame sensor 语义）？两者对非 root body（如足端）给出不同结果，需要盘点现有调用方依赖哪种语义。
2. 实现：若定为解析式，motrix 后端可用现成的 link 世界系速度 cache（_ensure_link_velocity_cache）+ get_body_quat_w 实现，同时需要审计 mujoco/drake 后端的一致性。
3. 回退临时方案：契约修正后，各家族的 sensor-bound reward 项是否回退到通用 entity-data 项（track_lin_vel_xy_exp 等），以恢复单份实现。

涉及范围

• src/unilab/base/backend/base.py（SimBackend 契约文档）
• src/unilab/base/backend/motrix/backend.py、scene.py
• mujoco/drake/mjwarp 后端的同名方法
• 调用方：Entity.data.root_link_*_vel_b 的所有 manager terms 与任务

欢迎讨论语义定义的选择，确认后我再开 implementation issue。