结论摘要

• 说法成立，但范围需要限定。 在本次审计范围内（conf/tasks/training/scripts/visualization，排除 RL 算法与 IPC 实现、多物理后端适配细节）：UniLab 为 100 个文件 / 23,157 行；mjlab 对应的任务、脚本、viewer 为 78 个文件 / 13,169 行（若只比较 tasks+scripts，则 61 个文件 / 8,151 行）。整个仓库 tracked Python+YAML 为 602 个文件 / 177,654 行，mjlab 为 301 个文件 / 74,625 行，约 2.4× 文件、2.38× 行。
• 不是单一批量拷贝。 配置矩阵是最大的确定性问题：47 个 YAML 中 13 个包含完整任务体，按“同名 task/backend 叶子最大文件”作保守下界估计，约 2,513 行属于跨算法重复/可合并。此外存在 3 个完全相同的 base YAML 和多组 0.94–0.98 近似副本。
• 文件数膨胀主要来自配置/入口的组织方式：算法目录 × 任务 × 后端叶子；每新增一个算法会把任务 YAML 数量再放大一倍。单个大文件则更多是功能聚合（MotionCommand 840 行、interactive play 1,261 行）和少量真实代码重复（render_many 两条 104–112 行渲染路径 0.817 相似）。
• mjlab 用 Python 工厂 + task registry + 两个通用 CLI 入口表达同类差异；UniLab 用 Hydra owner YAML + 每算法入口表达。二者产品目标不同，UniLab 的多后端/多算法 owner 语义本身不是冗余，但当前实现把“任务契约”和“算法超参”重新序列化在多个算法目录下，导致矩阵膨胀。

审计范围与口径

• UniLab HEAD: 47a6139 (2026-10-17)
• mjlab HEAD: c2e1e06 (2026-09-21)
• 行数按文本行统计；文件数排除 __pycache__。
• 相似度使用 difflib.SequenceMatcher 对源码行/AST ast.unparse 计算，是启发式指标而非语义等价证明。
• 依据仓库架构约束，未把 unilab.rl 算法和 IPC、unisim 后端适配代码作为膨胀归因；但 CLI/训练入口中为算法和 runtime 服务的胶水计入脚本/训练目录。

全仓库口径：

配置矩阵膨胀：最主要、最确定的冗余

现状

47 个 YAML = 4 个算法根配置 + 43 个 task/backend 叶子。结构呈 conf/{algo}/task/{task}/{backend}.yaml。

• 13 个 YAML 是完整任务声明（含 scene/observation/action/command/reward），合计 3,079 行；34 个是 override，合计 1,855 行。
• 同一 task/backend 名称在算法间重复：
  • g1_walk_flat/base.yaml: 4 份，共 1,109 行，最大 283 行
  • go2_joystick_flat/base.yaml: 4 份，共 855 行，最大 216 行
  • g1_motion_tracking/mujoco.yaml: 4 份，共 569 行，最大 240 行
  • g1_motion_tracking/base.yaml: 2 份，共 523 行，最大 269 行
  • g1_walk_flat/motrix.yaml: 3 份，共 241 行，最大 125 行
• 用“每个 task/backend 叶子组只保留最大一份”的保守下界估计，总重复至少 2,513 行 / 47 个 YAML 中的 43 个叶子里的 31 个跨算法副本。实际可合并量更大，因为每组最大文件也可拆为共享任务 profile + 少量算法差异。

完全相同与近似相同

完全相同（SHA-256 相同）：

近似重复（SequenceMatcher）：

为什么会这样

mjlab 的任务配置组织是：

• 基础任务用 Python 工厂（例如 make_velocity_env_cfg()）表达共享契约；
• 每个机器人只写 env 差异（tasks/velocity/config/{go1,g1}/env_cfgs.py）和 RL 差异（rl_cfg.py）；
• 通用 mjlab.scripts.train / play 从 task registry 读取差异；
• 只有一个物理后端（MuJoCo/MJX 技术栈），没有 backend owner YAML 维度。

UniLab 的 Hydra 选择有两个显式维度：算法 owner 和 backend owner。这满足了 owner YAML/registry 的架构约束，但当前默认包把三者相乘：

1. 每个算法都有自己的 config.yaml，重复 training/interactive/viser/hydra 常量（4 份约 614 行）；
2. 每个算法重新声明同一任务体；
3. backend 叶子又按算法重复。

结果不是“每个算法×机器人×任务”都完全存在（目前约 3 个任务），但机制已经按这个矩阵扩展：新增第 5 个算法时，所有已支持任务的 YAML 至少再复制一份。

可行动建议

1. 把任务契约从算法目录上移为 task profile。

   • 新结构示例：conf/task/{task}/base.yaml + conf/task/{task}/{backend}.yaml；
   • conf/{algo}/config.yaml 只保留 training/algo 和算法超参；
   • 算法特化（如 actor/critic obs group、noise、不同 reward profile）放到 task profile 下的命名 override（如 conf/task/g1_motion_tracking/profile/flashsac.yaml），而不是整份任务体。
   • 预期收益：仅当前 13 份完整任务体中即可将约 2.5k–3k 行压到 1 份任务体 + 少量 profile；文件数可从 43 个 task 叶子降到约 15–20 个。

2. 消除完全相同的 base YAML。 上述 5 个 exact duplicate 可立即用 shared defaults 引用替代，不改变运行时语义。单独这一步减少约 1,195 行重复声明。

3. 合并 4 个根 config 的非算法部分。 training、interactive、viser、Hydra logging 可提取为 conf/base/runtime.yaml / conf/base/logging.yaml，各算法 root 只覆盖 logger、默认 task、算法字段。4 个根配置现为 614 行，预计可降到 250–350 行。

4. 用 schema/lint 防止矩阵回潮。 增加 CI 检查：

   • 禁止两个 YAML normalized YAML 结构完全相同；
   • 对同 task family 的完整任务体设置重复键阈值；
   • 新增 conf/{algo}/task/... 完整任务体时要求显式豁免/ADR。
   • 由于这是配置公共契约，按仓库规则应先在 issue/ADR 记录决策。

5. 保留真正的算法差异。 例如 FlashSAC 与 SAC 的 biased/unbiased joint observation、foot geom DR、DR-free baseline 不是可简单合并的重复；迁移时应显式保留为 profile 差异，避免为了去重改变学习语义。

任务 term：产品扩展为主，局部有基础类重复

数量与大文件

tasks/ 22 个文件 / 6,953 行，其中 ≥500 行 4 个，≥1000 行 2 个：

重复模式

• entity_name 同样 3 行实现出现 5 处；tensor_body_names 3 处（另有一处两重复）；tensor_sensor_names 在同一文件出现 3 处、G1 文件 2 处；tensor_state_entity 3 处。
• _FootContactTerm 体系在 locomotion/common/manager_terms.py、locomotion/common/gait_terms.py、locomotion/g1/manager_terms.py 中有三套相近绑定/接触读取逻辑，但它们分别服务 legacy equation、mjlab-aligned sensor-group、G1 legacy profile，不能机械合并。
• tasks/motion_tracking/g1/manager_terms.py 中的 joint_acc_l2、joint_torque_l2 当前在 src/tests/YAML 中无外部引用，疑似残余或为未来 API 保留，需要确认。

与 mjlab 的关系

locomotion/common/gait_terms.py 明确标注 derived from mujocolab/mjlab v1.6.0 (0fb8a681) 的 velocity rewards，并做了 NumPy/named sensor/entity facade 适配。motion tracking 中大量函数名与 mjlab tracking 相同（motion_anchor_*, robot_body_*, motion_global_*），但 UniLab 版本主要改为通过 MotionCommand 的 tensor carrier 属性读取，并新增编译 kernel/sampler/state store。因此这不是简单整文件拷贝；同源语义被重新绑定到 UniLab 的 tensor carrier 与跨后端合同上。

可行动建议

1. 建立 mixin/protocol for tensor contract adapters。 将 entity_name、tensor_body_names、tensor_sensor_names、tensor_state_entity、tensor_carrier 这类纯协议方法提取为 TensorTermMixin 或基类，减少 14+ 个 3-line duplicate，并统一错误信息。
2. 拆分两个 >1000 行文件，不是单纯去重。
   • motion_tracking/common/manager_terms.py 可按 owner 拆为 motion_command.py、motion_kernels.py、motion_action.py、motion_observations.py、motion_rewards.py、motion_terminations.py；
   • locomotion/g1/manager_terms.py 可拆为 gait、legacy sensor rewards、velocity command/curriculum、reward/termination packs。
   • 拆分需保持 import path 或提供一次性 re-export，避免 YAML _target_/func 破坏。
3. 审计未引用 term。 对 joint_acc_l2、joint_torque_l2、motion loader/rotation 中无外部引用的 API 建立保留/删除决策；若为兼容 API，应加 __all__ 和测试。
4. 不要把 G1 legacy 与 mjlab-aligned term 强行统一。 两者语义相近但数学和 sensor contract 不同；可共享底层 adapter，不可共享 reward 语义。

训练入口：薄包装少，但有结构性胶水重复

scripts/ 8 个文件 / 3,422 行：

• 只有 2 个真正薄训练包装（SAC/FlashSAC），说明“每个算法一个入口文件”不是主要行数来源；大文件来自算法 runtime 差异 + 播放/设备/日志胶水。
• PPO/APPO/off-policy 三个入口的整体文本相似度低（0.17–0.26），但存在重复生命周期：build env override、build play override、play mode branching、log dir naming、checkpoint resolution、camera config、viser branch、run summary/playback sequencing。
• run_motrix_play_loop、_get_log_root 等同名/同职责 helper 在 APPO/PPO 中分别实现；off-policy 另有一套。
• train_sac.py/train_flashsac.py 可以由一个参数化 Hydra 入口替代，但如果保留用户体验上的稳定命令名，薄包装本身合理且成本仅 30 行。

可行动建议

1. 提取 training/playback_flow.py / training/run_lifecycle.py。 统一：
   • log root/run dir；
   • env/train/play override 构造；
   • checkpoint resolve；
   • play_render_mode → native/viser/offscreen 分支；
   • playback camera 与 debug overlay getter 组合。
     预计可从三个入口中移除约 300–600 行重复生命周期，并让新算法入口从 500+ 行降到配置差异。
2. 合并 SAC/FlashSAC 薄包装为一个内部 Hydra target。 保留外部 train 子命令映射即可。
3. 把 APPO/PPO 的 Motrix playback loop 合并到 visualization owner。 两个函数均包装 wrapped_env/policy/state obs，差异只是 policy closure 与 checkpoint 类型。
4. 将 PPO/APPO 分布式/DP 细节留在 training owner，不放进 scripts。 这符合“scripts as orchestration”约束，也能降低入口文件行数。

可视化/播放：确定重复点集中在 render_many 与三个播放家族

visualization/ 10 个文件 / 3,400 行，scripts/play_interactive.py 1,261 行。

重复/近似重复

与 mjlab 比较

mjlab 将 viewer 明确分层：viewer/base.py、native/、viser/、offscreen_renderer.py、model_sync.py，合计 5,018 行；通用 play.py 331 行负责 CLI/registry/checkpoint/选择 viewer。UniLab 的 visualization 3,400 行加 play_interactive 1,261 行，大体也为分层设计，但 interactive overlay/keyboard/model loading 仍集中在 script，而不是 visualization owner。

可行动建议

1. 立即提取 render_many.set_state。 两个完全相同的 42-line nested helper 可合并，render_frame_job 与 tracking 版本再提取公共 render_frame_with_markers(..., marker_hook=...)。保守估计可减少 80–140 行，并消除两个渲染路径未来漂移的风险。
2. 把 play_interactive.py 的非 CLI 逻辑移入 visualization owner。 建议：
   • visualization/viewer_model.py: model load/resolved visual model；
   • visualization/play_overlays.py: motion/reward/velocity primitives；
   • visualization/keyboard_command.py: keyboard commander/key mapping；
   • scripts/play_interactive.py: 只保留 CLI/compose/session 装配。
     这不会减少很多总行数，但能把 1,261 行拆成可测模块，符合 owner module 规则。
3. 统一 session action builder。 保留 on-policy/off-policy 语义差异，但把 reset/step/advance/info/physics state 生命周期放到共享 base；对 action_mode policy/random/zero 建立单个 builder。
4. 统一 viewer 模型加载和 state application。 native/viser/offscreen 都应有同一 owner API，避免每个 backend 分支私自探测模型。

产品功能扩展 vs 可参数化冗余

不是冗余（应保留）

• 多算法 owner 的算法超参、checkpoint 语义、obs group 语义。
• FlashSAC 与 SAC 的 biased/unbiased observation 差异、DR-free baseline、foot geom DR。
• Motion tracking 的 tensor carrier、kernel binding、sampler/state store：这是性能/后端合同扩展。
• G1 legacy reward pack 与 mjlab-aligned gait terms：语义不同，不能因公式相似合并。
• backend owner 中的 capacity、device、renderer、play_profile 差异。
• CUDA MPS/soak/tensor diagnostics 等 training 运维功能：虽然不在本次重点，不能因行数大删除。

可参数化/可合并冗余（优先处理）

1. exact duplicate YAML（5 个文件 / 约 1,195 行重复）。
2. 同一 task 的完整任务体跨算法复制（保守下界 2,513 行）。
3. 4 个算法 root config 的 training/interactive/viser/hydra 常量。
4. tensor adapter 的 3-line protocol methods。
5. render_many 两条渲染路径与 100% same nested set_state。
6. APPO/PPO/off-policy入口中的 playback/log/run lifecycle。
7. 无外部引用的 motion/G1 helper API。

建议的分阶段落地

1. P0（低风险、立即）

   • shared YAML defaults 替代 5 个 exact duplicate；
   • 提取 render_many nested set_state；
   • 添加 YAML duplicate CI guard；
   • 删除/确认无引用 task helpers。

2. P1（配置结构重构，需 issue/ADR）

   • 设计 task profile 与 algo profile 正交组合；
   • 迁移 g1_walk_flat 作为试点；
   • 保持现有 CLI override 兼容或一次性迁移文档；
   • 更新 sim2sim contract/config tests 和 docs。

3. P2（入口生命周期去重）

   • 提取 playback/run lifecycle；
   • 合并 APPO/PPO Motrix loop；
   • SAC/FlashSAC 参数化内部入口。

4. P3（大文件拆分）

   • motion_tracking/common/manager_terms.py 按 command/kernels/obs/reward/termination/action 拆分；
   • locomotion/g1/manager_terms.py 按 gait/reward/curriculum/pack 拆分；
   • play_interactive.py 拆 CLI 与 visualization owner；
   • 全部保持 re-export 或同步更新 YAML 函数引用。

结论

“UniLab 比 mjlab 多很多”在文件数和行数上都成立，但原因分层明确：

1. 最大且最确定的膨胀是 YAML 配置矩阵：算法目录重复任务体，已经产生 2.5k+ 行保守重复，且会随算法数量线性放大。
2. 文件数多来自维度化组织：Hydra 算法 owner × task × backend，加上每算法入口；这与 mjlab 的 Python factory + registry + 通用入口形成结构性差异。
3. 单文件大主要来自功能聚合：MotionCommand、interactive play、CUDA/训练运维、renderer。其中只有部分是实际重复；直接“按行数切文件”不会降低复杂度。
4. 确有可行动冗余：exact duplicate YAML、近似任务体、render_many 复制、entrypoint 生命周期、tensor adapter 小方法。先做 P0，再用 ADR 推动配置结构重构，能在不大改产品语义的情况下显著降低文件数和重复行数。

附：审计方法

• find + wc -l 统计文件/行数，排除 __pycache__。
• SequenceMatcher 计算 YAML 行相似度与 Python 函数 AST 相似度。
• SHA-256/MD5 识别 exact duplicate。
• ast 遍历识别同名/同体函数与顶层 class/function 行数。
• rg 检查 UniLab 与 mjlab provenance/函数名/调用点。
• GitHub GraphQL 查询 discussion category。
• 未修改仓库文件；本报告由只读审计生成。