Roadmap: Locomotion 具名 sensor terms 公共化与跨任务复用契约

[TATP-233]

Owner summary

Locomotion biped 族的具名 sensor 奖励 terms 目前存在三份拷贝：G1 模块内硬编码 sensor 名的私有实现；T800 把自家 XML 的 IMU sensor 起名为 G1 的名字，再在 owner yaml 里跨任务引用 g1.manager_terms.*；PR#1368 microduck 初版又逐字复制了一遍（542 行 manager_terms 中约 230 行重复）。推荐方案：具名 sensor terms 的 sensor 名下沉为 yaml 参数，公共实现收敛到 tasks/locomotion/common/ 并按数据源分文件；G1/T800 迁移到参数化实现并解除跨任务引用；把"跨任务复用必须经由 common"固化为 package boundary 测试。交付边界：不含 biped 步态 terms（G1GaitPhase、feet_phase 等）下沉，作为远期方向记录启动条件；不改变任何任务的奖励数值语义（microduck 的 lin_vel 两项保持 sensor 数据源，imu site 相对 body 原点有约 2.5 cm 偏移，velocimeter 读数含 ω×r 项，与 entity 数据不等价）。预计 3 个 child PR、约 8 文件、净删约 250 行手写代码。永久维护责任：common 层约 150 行公共 terms、一条 boundary CI 规则、"新任务在 yaml 显式声明 sensor 名"的约定。需要 maintainer 决定：公共文件命名、既有 G1/T800 owner yaml func 路径变更的接受度、远期步态下沉启动条件、declared base 确认。

背景与证据

• src/unilab/tasks/locomotion/g1/manager_terms.py:477-593：track_lin_vel 等 5 个 sensor-bound 类硬编码 pelvis_local_linvel / torso_gyro / torso_upvector。
• src/unilab/assets/robots/t800/t800.xml:390-392：T800 的 IMU sensor 起名为 G1 的名字；conf/ppo/task/t800_walk_flat/base.yaml:117-267 跨任务引用 g1.manager_terms.*（含 G1GaitPhase、g1_tilt_exceeded、5 个奖励类）。
• PR#1368 更新中：microduck 的公共部分已下沉至 common/，sensor 名走 yaml sensor_name 参数，任务内只保留 MicroDuck 特有 terms（manager_terms 由 542 行降至 373 行）。
• common/rewards.py、common/commands.py 仍被 legacy RewardContext 系统占用，manager-based 一代缺少按 kind 命名的文件位置。
• common/manager_terms.py docstring 自称 quadruped，内容实为家族无关的 entity 版 terms——文件名与内容漂移是既有累积问题。

推荐方案

1. common 层按数据源分文件，文件名与内容严格一致：
   • common/manager_terms.py：entity 数据源 terms（保留，修正 docstring 为 locomotion-wide）。
   • common/sensor_terms.py：收敛为 SensorTermBase 绑定契约（纯基类）。
   • common/sensor_reward_terms.py（新增）：具名 sensor 奖励 terms，sensor_name 经 yaml 参数声明。
2. G1 删除私有 sensor 版类；G1/T800 owner yaml 改指公共参数化实现并显式声明 sensor 名。奖励等式、sensor 名、权重均不变。
3. tests/tasks/test_package_boundary.py 增加规则：tasks/locomotion/<robot>/ 模块与其 owner yaml 禁止 import/引用兄弟任务模块。

备选方案与取舍

• A（推荐）：参数化下沉 + 迁移 G1/T800。净删代码、解除 XML 命名耦合；代价是触动两个既有任务的 owner yaml（仅路径与显式参数，无数值变化）。
• B：维持 G1/T800 现状，只约束新任务。改动最小，但 t800→g1 耦合与多份拷贝长期存在，boundary 规则需要永久 allowlist。
• C：sensor 版 terms 提升到 envs/mdp/。统一度最高，但污染 community 层（mjlab-derived）渊源，并与既有 std² 核 terms 形成同名近义对；不推荐。

Child issues 与集成顺序

• Declared base branch：dev/issue-1042-manager-based-api（G1/T800 的 manager terms 只存在于该分支；microduck 经 PR#1368 合入）。
• Child 1（依赖 PR#1368 合入）：sensor_reward_terms.py 命名拆分 + G1 迁移。约 5 文件、净删约 200 行。验证：G1 owner contract 测试数值不变 + slow env 构建。
• Child 2（依赖 Child 1）：T800 迁移，解除 t800_walk_flat/base.yaml 对 g1.manager_terms 的全部引用。约 2 文件、30 行。T800 XML sensor 名自由化作为可选项单独评估（涉及 asset 与观测契约）。
• Child 3（可与 Child 2 并行，建议在其后收尾）：package boundary 契约测试（代码 import + yaml func 路径双侧扫描）+ 各任务 sensor_name 参数与 XML <sensor name> 一致性静态测试。约 1 个测试文件、120 行。

最终验收

• 三个 biped 任务（G1/T800/MicroDuck）的具名 sensor 奖励 terms 全部指向 common 参数化实现，G1 私有拷贝删除。
• CI 强制：不存在 tasks.locomotion.<robot> → 兄弟任务模块的代码 import 或 yaml func 引用。
• 所有任务既有 contract 测试通过且奖励数值语义不变；每个 child PR 在最终 head 通过 make test-all。

远期方向（记录启动条件，不属本 roadmap 交付）

• biped 步态 terms（G1GaitPhase、feet_phase、feet_air_time 等）参数化下沉 common。启动条件：第三个 biped 任务接入，或 G1/T800 的 Motrix 移植需要共享步态实现。
• legacy RewardContext 系统（common/rewards.py、common/commands.py）随 Roadmap: 将 UniLab 迁移为社区通用的 Manager-Based API #1042 迁移收尾退役后，按 split-by-kind 惯例回收文件名。

需要 maintainer 决定

1. 公共文件命名 common/sensor_reward_terms.py（vs 保留在 sensor_terms.py）。
2. 接受 G1/T800 owner yaml 的 func 路径变更（无数值变化）。
3. 远期步态下沉的启动条件是否认可。
4. Declared base 确认为 dev/issue-1042-manager-based-api。

[TATP-233]

调查结论：legacy 模式与 collector 吞吐（仅基于历史提交与开发记录，未做新 benchmark）

Q1：legacy 模式是否因优化 collector 性能而引入？——不是。

• legacy（单体 task 类 + RewardContext dispatch）是 UniLab 最初的 task 系统，早于全部 collector 性能工作。
• 与 legacy 架构绑定的性能产物是 Numba 路线（perf: 定位 Env overhead 并行化实测天花板 — Numba prange 融合 kernel 在 Xeon 8568Y+ 到 31x #665/bench: add env overhead parallelization probe #666/benchmark: add numba env overhead profile #676/perf: accelerate G1 locomotion hot paths with numba #695，加速 legacy update_state 的 per-env 单线程循环）；chore: remove Numba dependency and acceleration paths #930 已正式定性"Numba 不再作为支持执行路径"，PR chore: remove Numba dependency and acceleration paths #931 删除 58 文件 / 9,796 行。
• Roadmap: 将 UniLab 迁移为社区通用的 Manager-Based API #1042 owner summary 明确"最终不能长期保留新旧双实现"；chore: close the #1042 registry, documentation, and performance acceptance #1228/chore: close the #1042 registry, documentation, and performance acceptance #1237 closeout 已删除 unilab.envs.{locomotion,manipulation,motion_tracking} 包并冻结 compatibility seam。
• 现存 legacy seam（LegacyFactoryAdapter）精确限于 3 个 Adapted family（Go2ArmManipLoco / SharpaInhandRotation / SharpaInhandRotationGrasp）；migration_matrix 记录的保留原因是 "Custom IK/history or tactile/contact/cache behavior … migrate only when the formal capability exists"——能力缺口，不是性能。

Q2：移除 legacy 是否导致 collector 吞吐下降？——历史记录中没有支持该担心的证据。

• collector 面向 NpEnv/NpEnvState obs-dict 契约；Roadmap: 将 UniLab 迁移为社区通用的 Manager-Based API #1042 已把"保留 NumPy 热路径、NpEnvState、IPC 数据面"列为外部不变量，manager-based env 满足同一契约。
• chore: close the #1042 registry, documentation, and performance acceptance #1237 性能验收（同 commit / 同硬件，manager-based）：G1WalkFlat mujoco 48,693 steps/s、motrix 87,345 steps/s（4096 envs）。
• 评估：Manager-based API 下用 Numba 加速 collector 后处理与 reset 的可行性（基于 #932 复盘） #1292 实测表：locomotion 的 manager host 相（update_state 12–15 ms）仅占 env.step 约 6–8%（物理 51–181 ms）；roadmap: collector host 相吞吐优化——update_state/reset_done 串行热点收敛（含 reset RNG 流一致契约移除） #1348 host 相优化 roadmap 已合入（perf(collector): host 相吞吐优化——update_state/reset_done 串行热点收敛（roadmap #1348） #1362）。
• LegacyFactoryAdapter 只在构造期校验（冷路径），不进入任何热路径；移除它移除的是 3 个注册（support 面），不是吞吐。
• 诚实的限制：历史记录中没有 legacy-vs-manager 同配置 A/B 吞吐对比（closeout 表只有迁移后数字）；但全部既有治理结论、验收数字与后续优化方向都指向 manager-based，无任何记录表明保留 legacy 出于吞吐考虑。

真正的成本是 support 面：无条件移除 legacy 等于从 registry 删除 3 个 Adapted family；legacy RewardContext（tasks/locomotion/common/rewards.py）仅剩的消费者是 go2_arm/manip_loco.py。

据此补充 roadmap 决策

1. 终态形态：locomotion / manipulation / motion_tracking 三族只保留 manager-based 一种 task 模式。"移除旧模式"的完成条件：3 个 Adapted family 的形式能力（IK/history、tactile/contact/cache）具备并迁移，或 maintainer 显式放弃这些 support claim。与 Roadmap: 将 UniLab 迁移为社区通用的 Manager-Based API #1042"不能长期保留新旧双实现"的既有决策一致；该迁移/放弃决策本身是独立 roadmap 级事项，不在本 roadmap 交付范围内。
2. 交付顺序：契约重构（Child 1/2）先行；MicroDuck 引入（PR#1368）暂存独立分支，待契约重构合入后再 rebase 引入。
3. 命名已获 maintainer 认可：公共 sensor 奖励 terms 文件为 common/sensor_reward_terms.py；common/sensor_terms.py 收敛为纯 SensorTermBase 绑定契约模块。

[TATP-233]

收尾状态

• Child 1(sensor_reward_terms 命名拆分 + G1 迁移)：✅ 已由 PR#1374 交付(2026-08-31 合入 dev/issue-1042-manager-based-api)。
• Child 2(T800 迁移):✅ 同名具名 sensor terms 已由 PR#1374 一并迁移(两者必须同 PR);T800 对 g1.manager_terms 的步态/指令/课程类 7 处引用按本 roadmap 记录保留,归入远期方向(启动条件:第三个 biped 任务接入,或 G1/T800 的 Motrix 移植需要共享步态实现)。
• Child 3(package boundary 契约测试 + sensor_name 一致性静态测试):➡️ 拆出为后续 issue Locomotion package boundary 契约测试与跨任务引用强制（#1371 child 3） #1418。

前置依赖 PR#1368(MicroDuck MBA 移植)亦已合入。

剩余交付与验收在 #1418 跟踪,本 roadmap 关闭。