UniLab vs pinned mjlab code-size/redundancy audit (excluding RL algorithms, RL IPC, and multi-physics backend implementations)

[TATP-233]

结论先行

“UniLab 比 mjlab 代码多很多”在整仓/全部 Python 口径下成立，但排除 RL 算法、RL IPC 和多物理后端实现后，核心源码的总量并没有同比例膨胀。 更准确的结论是：

1. UniLab 整仓 tracked Python 为 543 个文件 / 171,496 行；mjlab v1.6.0 为 288 个 / 73,725 行，约 2.33×。
2. 但排除 unilab.rl、RL/IPC 测试与 benchmark 后，UniLab 核心 src 为 127 个 Python / 45,751 行；mjlab 对应为 186 个 / 41,835 行。也就是说，非 RL 核心源码文件数反而少 59 个，物理行数只多约 9%。
3. 非 RL Python 的额外行数主要不在核心包：UniLab 非 RL tests +28,117 行、scripts +19,610 行，而 src 只多 +3,916 行。按这个口径，约 92% 的非 RL Python 增量来自 tests + scripts，核心 src 只占约 8%。
4. 没有证据支持“大批量复制粘贴式代码冗余”：同路径/显式来源迁移文件确实膨胀，但大多是重写后的 Torch/capability/transaction 契约；函数级 exact duplicate 很少。真实问题集中在：
   • Hydra 算法目录下的任务 YAML 矩阵重复；
   • 少数 owner module 过度聚合，形成 1k–4.4k 行大文件；
   • host/Tensor 或 individual/fused 等过渡期双路径；
   • 少量局部 helper 重复。
5. 最大单文件问题真实存在：非 RL src 中 10 个 ≥1000 行、13 个 ≥800 行，最大 base/entity.py 4,459 行；mjlab 对应为 5 个 ≥1000 行、7 个 ≥800 行，最大 1,932 行。

对比口径

• UniLab：47a61395bb66350e67a7975ac4c9f19e03a16f6b，2026-10-17。
• mjlab：仓库内派生标记明确的 pinned 版本 v1.6.0 / 0fb8a681136be94ffc636a3dd423cabb97d91f10，2026-08-08。所有 mjlab 数值均用 git ls-tree / git show <commit>:<path>，避免把 mjlab 工作区 .venv、缓存和日志算入源码。
• 行数是 tracked text line count；文件数来自 git tracked files。
• “排除 RL/IPC/多物理后端”不是完美逐行边界：backend 本体在 unisim-core，但 UniLab 核心中仍有公共 capability negotiation、device placement、sim2sim contract。因此下面同时给宽口径和更严格扣除明显 backend 面的口径。

1. 规模对比

全仓

口径	UniLab	mjlab pinned	结论
tracked files	916	513	1.79×
Python files	543	288	1.89×
Python lines	171,496	73,725	2.33×
src Python	214 / 66,588	192 / 42,558	1.56×

不建议用“所有文本行”直接比较：mjlab 有大量 STL/PNG/GIF/MP4 等资产，二进制按行统计没有工程意义。

排除 RL/RL IPC

UniLab 排除：

• src/unilab/rl/
• tests/rl/
• scripts/benchmark/rl/
• scripts/benchmark/ipc/

mjlab 对应排除 src/mjlab/rl/。

区域	UniLab	mjlab	差异
src Python	127 / 45,751	186 / 41,835	-59 files / +3,916 lines
tests Python	176 / 56,416	85 / 28,299	+91 / +28,117
scripts Python	73 / 22,174	9 / 2,564	+64 / +19,610
docs Python	1 / 441	1 / 200	+241
合计	377 / 124,782	282 / 72,898	+95 / +51,884

因此：文件数很多、Python 很多”主要来自测试、benchmark、工具链和文档，而不是非 RL 核心 owner 模块数量失控。

更严格地扣除明显 backend 面

在上述基础上再扣除：

• src/unilab/base/backend_factory.py（281）
• src/unilab/base/process_device.py（444）
• src/unilab/utils/sim2sim.py（258）
• backend/sim2sim 命名测试（约 1,587 行）
• scripts/benchmark/physics/（约 6,263 行）

得到：

区域	UniLab	mjlab	差异
src	44,768	41,835	+2,933
tests	54,829	28,299	+26,530
scripts	15,911	2,564	+13,347
合计	115,949	72,898	+43,051

该口径下约 91% 的额外 Python 行数仍来自 tests + scripts。但由于 capability negotiation 已内嵌在 entity.py / manager env 等文件中，无法做到无损逐行归属，所以这是保守口径而非完美口径。

2. 核心源码的公平比较

2.1 与 mjlab 同相对路径文件

src/unilab 与 src/mjlab 有 29 个同相对路径 Python 文件（排除 rl/__init__.py）：

• UniLab：10,831 行
• mjlab：6,813 行
• 差异：+4,018 行，约 +59%

最大膨胀点：

相对路径	UniLab	mjlab	差异
envs/mdp/events.py	2,139	605	+1,534
envs/manager_based_rl_env.py	1,789	618	+1,171
managers/observation_manager.py	955	515	+440
envs/mdp/rewards.py	427	159	+268
envs/mdp/observations.py	424	163	+261
managers/command_manager.py	564	373	+191
managers/reward_manager.py	347	175	+172
managers/action_manager.py	351	208	+143
envs/mdp/curriculums.py	312	187	+125

但也有反向例子：

相对路径	UniLab	mjlab
terrains/heightfield_terrains.py	640	982
terrains/config.py	169	354
managers/event_manager.py	314	390
managers/manager_base.py	140	147

2.2 显式标记 mjlab 来源的文件

仓库中有 27 个 Python 文件带 Derived from mujocolab/mjlab v1.6.0 (0fb8a681) 并能映射到 pinned 上游路径：

• UniLab：11,624 行
• mjlab 对应源：6,723 行
• 差异：+4,901 行

但行数差异不能直接等同于“冗余”。这些文件的增量主要来自：

• Torch-only public lifecycle；
• SimBackend capability / read plan / device boundary；
• fail-closed shape、dtype、device、mask、finite 校验；
• persistent scratch/carrier 热路径优化；
• Hydra/config materialization；
• selected-row reset 和 packed transaction。

2.3 静态重复检测

对非 RL src 做函数级 AST/token 检查的结果：

• UniLab 内部 exact normalized duplicate 只有 7 组 / 14 个函数定义，函数体长度大多 5–12 行，最大也较小；折算“多余副本”约几十行，远小于 1%。
• 跨 UniLab/mjlab exact normalized function clone 约 15 组，最大 22 行，集中在 delay buffer、small resolver、small terrain helper。
• 对 32 个非平凡对应文件做 token fingerprint/归一比较，UniLab 侧可识别重叠约为三分之一；大文件如 events.py、manager_based_rl_env.py、observations.py、rewards.py 的 token 相似度只有约 4–10%，说明当前实现已高度分化，不是大块拷贝。
• marker 搜索：非 RL src 中 TODO/FIXME/deprecated/workaround 为 0；legacy 多为解释历史任务语义，duplicate 多为检测 env_ids/actuator_ids 是否重复的错误信息，不是维护者承认代码重复。
• Vulture 高置信候选仅 5 个小项，且可能受解包变量/动态引用影响，不能当作删除结论。

结论：不支持“大批量代码冗余”；支持“局部结构性重复 + owner 文件过度聚合”。

3. 单文件为什么长：逐个归因

3.1 src/unilab/base/entity.py — 4,459 行

AST 结构：10 个 class、约 234 个 function/method。

类	行区间	规模	职责
EntityCfg / view types / SceneTensorReadSpec	63–259	~197	config 和 view carrier
SceneTensorReadPlan	262–752	491	packed device/host read plan、packet refresh、view
_EntityStateReadCache	755–784	30	phase cache
EntityData	794–1422	629	defaults、host/tensor state、control buffer
Entity	1425–4117	2,693	name/index、state read、control、reset/model-field writes
EntityScene	4120–4446	327	scene facade、tensor read compile、gravity/sensor binding

对比 mjlab entity package：

比较方式	UniLab	mjlab	结果
entity.py 对 entity/entity.py	4,459	1,341	3.32×
entity.py 对 mjlab entity package	4,459	3,421	1.30×
entity.py + reset_state.py 对 entity package	6,889	3,421	2.01×

膨胀来源：

1. mjlab EntityData 在独立文件（631 行），UniLab 合并进 entity.py；
2. UniLab 新增 SceneTensorReadPlan / state view / host-cache / device packet 语义；
3. Entity 中约 38 个 bind_* / write_* / record_* 字段包装方法，约 820 行，是最明显的结构性重复；
4. fail-closed validation 很多：该文件约 268 个 raise，而 mjlab entity/entity.py 只有 4 个；
5. host path 和 tensor/mask path 并存。

判断：拆分缺失 + 字段 wrapper 手工展开 +公共契约显式化，不是 mjlab 复制冗余。

3.2 src/unilab/base/reset_state.py — 2,430 行

只有一个主 class ResetStateTransaction，79–2427，约 2,349 行、近 100 个方法。它同时承担：

• host reset transaction；
• Torch/packed reset transaction；
• owner-subset mask transaction；
• root/joint/motion/mocap writes；
• model-field DR writes；
• startup baseline 与 default materialization；
• shape/dtype/device/quaternion/finite validation；
• commit/abort 和 timing。

其中约 36 个 bind_* / write_* 字段包装方法占 1,056 行，覆盖 geom size/solref/solimp、damping/friction/armature、body mass/ipos/inertia、gravity、actuator gain、root/joint/motion 等。这些方法多数只是字段常量、tail shape、错误 label、backend API 名称不同。

这是全文件中最明显的结构性重复点，适合引入 field descriptor/table：

field -> reset term constant, value tail, backend label, write capability

但不能直接改成动态 getattr 或吞掉显式类型签名；应先拆文件，再用契约测试推进收敛。

3.3 src/unilab/envs/mdp/events.py — 2,139 行

只比较 mjlab envs/mdp/events.py 会得出 3.54× 的结论，但这不公平：

mjlab 范围	行数
envs/mdp/events.py	605
envs/mdp/dr/ package	3,007
合计	3,612

UniLab把 DR/event/reset 相关实现集中在一个 events.py（2,139 行），部分 transaction 和字段适配又移到 base/reset_state.py 与 base/entity.py。因此更公平的说法是：

• 功能范围不是 3.54×；UniLab 实际比 events+DR 合计少约 1,473 行；
• 但把 12 个 class、distribution helper、model-field randomizer、body dynamics、root reset Torch kernels 放进一个文件，造成可读性负债。

可确认的局部重复：

• PdGains.reset() 与 PdGains.__call__() 重复 kp/kd 采样、默认值组合、scale、dtype/device 转换，差异主要是写入边界；
• PushBySettingVelocity._host_uniform 与 ApplyBodyImpulse._host_uniform 重复；
• reset_root_state_uniform / reset_root_state_uniform_tensor、reset_scene_to_default / reset_scene_to_default_tensor 是 host/Tensor 双路径，当前配置确实同时使用，不能直接删除。

3.4 src/unilab/envs/manager_based_rl_env.py — 1,789 行

对比 mjlab同名文件 618 行。

新增/膨胀职责：

• _compile_tensor_read_plan()；
• action / observation / manager term / task / command tensor read specs；
• device-resident 与 host-bridge sensor 解析；
• runtime device resolution；
• backend materialization；
• Torch public state carrier；
• reward/metric/observation publication；
• selected reset 和 packed transaction ownership；
• policy/critic observation mapping；
• timing diagnostics；
• seed/training state/close/playback debug。

reset() 约 158 行，_update_state_in_read_phase() 约 126 行，__init__() 约 100 行。

判断：这是新的 runtime owner，不是 mjlab env 的复制膨胀；但 tensor read planning、runtime、step、reset、factory 可以拆分。

3.5 src/unilab/managers/observation_manager.py — 955 行

mjlab为 515 行。格式差异（2-space vs 4-space/ruff）只解释约 20–30 行，不是主因。

主要增量：

• persistent noise carriers；
• persistent finite scratch；
• group output carriers；
• reset mask validation；
• dtype/device public Torch boundary；
• arbitrary concatenate dim；
• non-concatenate group；
• named sensor/backend view；
• timing counters；
• deferred NaN diagnostics。

compute_group() 从 mjlab 约 78 行变成 265 行，_prepare_terms() 从约 104 行变成 192 行。这是热路径 pipeline、校验、诊断全部写进单方法导致的复杂度，不是简单重复。

3.6 其他 >800 行文件

文件	行数	判断
tasks/motion_tracking/common/manager_terms.py	1,892	MotionCommand 单 class约 840 行；还聚合 action/reward/termination/observation/tensor runtime/kernels
tasks/locomotion/g1/manager_terms.py	1,423	gait、sensor、curriculum、reset owner、individual terms、fused pack 并存
scripts/play_interactive.py	1,261	CLI、checkpoint、viewer、debug overlay、keyboard、session 混合
training/cuda_mps_cli.py	1,221	daemon record、GPU discovery、topology、start/stop/status/doctor、parser
visualization/interactive_playback.py	1,173	多算法回放 session factory；与 RL 边界相关
training/soak.py	1,016	/proc、nvidia-smi、process tree、manifest、failure replay、runner
scripts/train_offpolicy.py	811	用户排除边界内的 RL/IPC 入口，不计入核心结论

4. 为什么文件数量显得特别多

4.1 测试面

典型大测试：

文件	行数
tests/envs/test_manager_based_rl_env.py	4,048
tests/scripts/test_train_scripts.py	3,302
tests/envs/mdp/test_events.py	1,759
tests/test_cli.py	1,205
tests/base/test_sim_backend.py	1,161
tests/base/test_reset_state.py	1,003

mjlab也有大测试，例如 test_domain_randomization.py 2,515 行、test_variants.py 1,772 行，但总量小很多。

4.2 benchmark / 运维工具

UniLab非 RL scripts 约 22,174 行 Python，包含 compute、core、env、physics、torch_env 等 benchmark 和训练/评测/运维工具。mjlab scripts 只有 9 个 Python / 2,564 行。

这带来一个治理问题：部分耐久行为可能仍留在 scripts 中，与 AGENTS.md 中“scripts 只做 orchestration，耐久行为归 owner module”的目标存在张力。

4.3 双语文档

UniLab docs 有：

• en/：100 个文件；
• zh_CN/：101 个文件；
• 两者基本成对维护。

这天然使 docs 文件数接近翻倍。mjlab docs结构不是双语镜像。

4.4 Hydra 算法 × 任务 × 后端 YAML

src/unilab/conf 目前 47 个 YAML。结构是：

conf/{algo}/task/{task}/{backend}.yaml

其中 go2_joystick_flat/base.yaml 在 PPO/SAC/FlashSAC 三份完全相同（213×3），g1_walk_flat/base.yaml 在 SAC/FlashSAC 两份完全相同（278×2）。

按相同 task/backend 叶子做 SequenceMatcher，主要近似重复包括：

组	相似度
APPO vs PPO g1_motion_tracking/mujoco.yaml	0.975
APPO vs PPO g1_walk_flat/base.yaml	0.973
APPO vs PPO/SAC/FlashSAC go2_joystick_flat/base.yaml	0.984
FlashSAC vs SAC g1_motion_tracking/base.yaml	0.937

按“每个同名 task/backend 叶子只保留最大一份”的保守下界估算，约 2.5k 行是跨算法重复或可合并。这是本次审计中最确定、收益最大的冗余。

建议方向：

conf/task/{task}/base.yaml
conf/task/{task}/{backend}.yaml
conf/{algo}/config.yaml      # 只保留算法超参与 runtime owner

算法特化用 task profile 下的命名 override 表达。这属于公共配置契约变化，应走 issue/ADR，而不是机械搬文件。

5. 历史演化原因

关键commit：

64c7f8b833759e69ca310578049ba11faf4a2075
2026-09-05
feat: Manager-Based API 迁移与多后端/拆包收口（roadmap #1042） (#1497)

本地 first-parent diff：1062 files / +72,626 / -72,268。PR body 明确说明以 mjlab 1.6.0 0fb8a681 为迁移源，并集成了 Manager-Based API、多后端、unisim-core 拆包、任务迁移和性能系列。

多个当前巨型文件都在该 commit 引入，初始规模已经很大：

文件	PR #1497 引入时	当前
base/entity.py	2,344	4,459
base/reset_state.py	1,271	2,430
envs/mdp/events.py	1,486	2,139
tasks/motion_tracking/common/manager_terms.py	1,119	1,892
envs/manager_based_rl_env.py	764	1,789
tasks/locomotion/g1/manager_terms.py	839	1,423

后续主要增长来自连续 tensor 化、packed reset、device reset DR、sensor/body tensor reads、persistent scratch、性能和诊断功能，例如：

• 6cbac6b9：entity.py +564，scene-owned packed tensor read plan；
• 34cb90b5：+232，sensor/body tensor reads；
• 1c13f7d6：events.py +327，device reset DR；
• f8fbc4eb：reset_state.py +261，owner tensor reset transaction；
• 多个 perf(obs/reward/termination/command) commit 持续加入 persistent carriers。

因此，大文件的形成模式是：大迁移一次性成型 → 后续 tensor/perf/device 功能继续堆到同一 owner 文件，而不是长期无意识复制。

6. 冗余/非冗余分层判断

类别	判断	置信度
精确函数级重复	“多余副本”约几十行，<1% 非 RL src	高
明显死代码	仅 5 个 Vulture 小候选，未见大模块死代码	中高
YAML 跨算法重复	约 2.5k 行保守可合并，是最大确定冗余	高
字段 wrapper / 双路径 / task helper 近似重复	数百到低千行级，集中在 Entity、ResetStateTransaction、events、task terms	中
非冗余功能/架构膨胀	大部分非 RL 核心增量来自 Torch/capability/transaction/perf 契约	中高
非 RL Python 总量差值	约 92% 来自 tests + scripts	高

不建议把这理解为“没有重构空间”。准确说法是：没有大批量可直接删除的复制代码，但有明显的结构性重复、职责聚合和配置矩阵重复。

7. 建议优先级

P0：低风险、高确定性

1. 处理 5 个完全相同 YAML（go2_joystick_flat/base 3 份、g1_walk_flat/base 2 份），改为 shared defaults。
2. 为 conf/ 增加 duplicate/near-duplicate CI guard，防止算法维度继续复制任务体。
3. 删除或确认未引用的小 helper / unused import / unused local。
4. 统一明显的小 helper：_host_uniform、task-local _real/_command/_asset/_torch_*、quaternion/math helper owner。

P1：结构收敛，需要 issue/ADR

1. 将任务契约从算法目录上移为 task profile：
   • conf/task/{task}/base.yaml
   • conf/task/{task}/{backend}.yaml
   • 算法目录只保留算法超参与 runtime owner。
2. 拆分 base/entity.py，保留 public re-export：
   • entity config/types；
   • tensor read plan；
   • EntityData；
   • Entity core；
   • Entity writes；
   • EntityScene。
3. 拆分 base/reset_state.py：
   • transaction API；
   • validation；
   • defaults/randomization；
   • model fields；
   • packed commit。
4. 拆分 envs/mdp/events.py：
   • sampling/validation；
   • model-field randomizers；
   • body dynamics events；
   • root reset；
   • Torch kernels。
5. 拆分 envs/manager_based_rl_env.py：
   • config；
   • tensor read planner；
   • manager runtime；
   • step；
   • reset/factory。

P2：需要 parity/perf gate 的语义收敛

1. host reset 与 tensor reset 双路径建立 parity matrix，再逐步收敛。
2. G1 individual terms 与 fused reward/termination pack 建立语义 owner，避免两套公式漂移。
3. PdGains 提取公共采样/默认值组合。
4. joint_pos_limits 双实现共享底层公式或明确不可合并原因。
5. 统一 reset mask validation，同时保留 owner-specific 错误语义。
6. 训练入口 / playback session 提取公共生命周期，避免每个算法重复 log root、checkpoint resolve、camera、viewer routing。

P3：测试与 benchmark 治理

1. 拆大测试：test_manager_based_rl_env.py 4k、test_train_scripts.py 3.3k。
2. 审计非 RL benchmark 中哪些 harness、plotting、诊断逻辑应进入 owner package。
3. 为 YAML 和 source duplicate 增加轻量静态 guard。

8. 不建议做的事

• 不建议以“删除 mjlab 派生代码”为目标清理：manager API 兼容性是明确设计选择。
• 不建议直接删除 host reset path 或 legacy __call__ path：当前 owner YAML 仍在使用，需要先迁移和 parity 验证。
• 不建议为了缩短文件把 fail-closed 校验换成泛化错误：这些错误信息对 capability/shape/device 诊断有实际价值。
• 不建议把 Entity / ResetStateTransaction 字段 API 直接改成动态 getattr：会损失类型签名和跳转可读性；应先做 field descriptor + 契约测试。
• 不建议机械按行数拆文件：拆分应按生命周期和 owner 边界，否则只是把复杂度搬到更多文件。

9. 可复核命令

规模统计基于以下命令模式：

git -C /home/user/Desktop/UniLab rev-parse HEAD
git -C /home/user/ws/simulator/mjlab show -s --format='%H %cs' 0fb8a681

git -C <repo> ls-files '*.py'
git -C <repo> ls-files -z -- src tests scripts docs | xargs -0 wc -l

git -C /home/user/ws/simulator/mjlab ls-tree -r --name-only 0fb8a681 src/mjlab
git -C /home/user/ws/simulator/mjlab show 0fb8a681:<path> | wc -l

来源标记：

rg -l 'Derived from mujocolab/mjlab v1\\.6\\.0 \\(0fb8a681\\)' \
  src/unilab -g '*.py'

大文件：

git ls-files 'src/unilab/**/*.py' |
  grep -v '^src/unilab/rl/' |
  xargs wc -l | sort -nr | head -50

git -C /home/user/ws/simulator/mjlab ls-tree -r --name-only 0fb8a681 src/mjlab |
  grep '\.py$' |
  while read f; do
    git -C /home/user/ws/simulator/mjlab show 0fb8a681:$f | wc -l |
      xargs -I{} echo "{} $f"
  done | sort -nr | head -50

历史：

git show --stat --summary 64c7f8b8
git log --follow --date=short --pretty='%h %ad %s' -- src/unilab/base/entity.py

死代码候选（需人工确认）：

uvx vulture src/unilab --exclude src/unilab/rl --min-confidence 80

10. 局限性

1. 版本时点不完全对称：UniLab是 2026-10-17 HEAD，mjlab是 2026-08-08 v1.6.0。选择 v1.6.0 是因为 UniLab 源码和 PR feat: Manager-Based API 迁移与多后端/拆包收口（roadmap #1042） #1497 明确 pin 了该 commit；mjlab工作区 HEAD 为 c2e1e0640。
2. 排除边界有灰区：RL 算法/IPC 可按目录排除；多物理 backend 本体在 unisim-core，但 UniLab 内仍有 capability、device、sim2sim 公共面，只能给宽/严两个口径。
3. 文件对应不是功能等价证明：例如 events.py 必须连同 mjlab mdp/dr/ 一起看；entity.py 必须连同 mjlab entity/data.py 和 UniLab reset_state.py 一起看。
4. 相似度是启发式指标：SequenceMatcher/token fingerprint/AST exact clone 不能证明语义等价，也不能发现所有重命名后的重复。
5. LOC 受格式影响：mjlab使用 2-space 缩进，UniLab使用 ruff 4-space/100 列。对 observation_manager.py 做格式归一后格式差异只解释约 20–30 行，但未对所有文件逐一归一。
6. 未做行为验证：这是只读审计，没有运行 make check / make test / benchmark，因此不能对性能路径或拆分后的兼容性下结论。
7. 行数不可直接换算为可删除行数：配置、task helper、双路径均有现网使用；安全清理需要 parity/perf gate。

最终判断

• 整仓 Python 确实约 2.33×，文件数约 1.8×，用户直觉在整仓层面成立。
• 排除 RL/IPC 后，核心 src 只多约 9%，且文件数更少；约 92% 的非 RL Python 增量来自 tests + scripts。
• 没有大批量复制粘贴冗余。显式 mjlab 来源文件约 11.6k 行，其中大文件已经高度重写，函数级 exact duplicate 很少。
• 最确定的可合并冗余是 Hydra YAML 算法矩阵，保守约 2.5k 行。
• 最大的架构负债是单文件职责聚合：entity.py、reset_state.py、events.py、manager_based_rl_env.py、motion tracking/G1 task owner 文件。
• 清理方向应是：先去配置重复，再按 owner/lifecycle 拆大文件，最后用 parity/perf gate 收敛双路径；不应把行数下降本身当目标。