工作汇总：UniSim #154 MJCF-first 可信场景组合与操作闭环（最终集成前）

[TATP-233]

结论

unilabsim/unisim#154 已经完成了一轮规模很大的 MJCF-first portable scene / trusted composition / operation loop 集成，但 roadmap 仍保持开放，尚不宣称全部完成。

当前状态：

• 最终待合并集成分支：dev/issue-154-mjcf-portable-scenes
• 当前集成 head：0e691db0b8e4495b2804b865a7e98c2cad207c1e
• 对比 main：162 个提交、86 个文件变更，约 26k 行新增 / 843 行删除
• 集成方式：73 个子 PR（Work: 收敛 registry bootstrap 到单一实现，并定义 optional import 策略 #156–infra: inhand_rot_allegro 架构落后于核心层，SAC obs_groups_spec 使用错误 key #229 中对应本分支的 73 个）逐项合入 dev/issue-154-mjcf-portable-scenes；开发期间未把子 PR 直接合入 UniSim main
• UniSim main 当前仍为 f271b7907a86409a5a34eae5f037916226b04a6d
• Work: 将 backend 兼容补丁从脚本和 worker 收回 owner layer #154 与 docs: remove en, ja, ko language docs, keep only zh_CN #124 均保持 open，等待剩余 SuperDex 范围和最终 roadmap 审计

下游消费已经进入 UniLab main：

• UniSim 发布 unisim-core==1.7.1
• Motphys/UniLab#1610 已合并，UniLab main head 为 a27bace3fc48009531b14dbbdb43a6ce07ccaa3a
• UniLab 依赖提升到 unisim-core>=1.7.1
• 下游消费 issue #1609 已按验收关闭

工作内容汇总

1. 公共 MJCF profile、编译契约与 UniLab 消费

#155 / PR #156 建立了 portable MJCF scene profile v1 的公共基础：

• 受限 MJCF 作为物理 authoring source of truth；
• 公共 Scene 组合、名称限定、编译表示、冻结 layout 与 source/intent report；
• MuJoCo compilation 作为 canonical structural oracle；
• 公共实体身份、variant 身份与内容身份边界；
• unsupported 语义在构造 / materialization 阶段 fail closed，而不是由 adapter 各自发明兼容层。

UniLab 侧的 #1609 / PR #1610 完成 released-package 消费验证：

• Manager-Based entity/reset/control 消费路径对齐公共 layout；
• 默认 control、局部 reset、mirror 身份、playback source 不依赖 backend 私有模型；
• MuJoCo fixture 覆盖 robot + passive articulation + static table + collision-free mirror，N5/K2 assignment [1,1,0,1,0]；
• IsaacSim 消费只声明已验收的 bounded profiles，不把拒绝测试或 mock 当支持。

2. IsaacSim 操作闭环与真实证据

#72 已关闭，相关子 PR 覆盖：

• body property / geometry readback；
• selected property mutation；
• collision-pair force reporting；
• staged world-frame body wrench；
• host pre-step control；
• dual-backend MJCF-only 操作验收；
• worker import isolation，避免宿主 site-packages 污染外部 IsaacSim Python worker。

最终 #72 验收用同一受限 MJCF 场景验证构造、身份、状态、局部 reset、控制、接触区分、属性、wrench 与 playback。native camera / RGB 继续由 #133 独立跟踪，不冒充物理验收的一部分。

3. IsaacSim 缓存、role bake 与精确 assignment

#80、#81、#82 已关闭：

• ToReal：G1 joystick #80：规范化 MJCF → raw USD 的内容寻址转换缓存，identity 包含场景源、资源、compiler/profile、importer 与 runtime 版本；
• Infra：MotrixSim timestep 优化 #81：raw convert-once、copy-per-role，role identity 追加 collision/visual/mirror/bake 参数，避免镜像角色串写；
• Tracking：M1 - Motrix / G1 / ToReal Phase 1 #82：entity-bound immutable 任意 assignment，支持非 round-robin、重复、不均衡与顺序反转，并通过 K 原型精确 spawner 控制原型数。

4. 五后端 bounded portable profiles

Backend	主要交付	当前状态
Genesis / #120	固定/浮动/被动/静态实体、异构 fixed variants、属性与 reset randomization、site/body sensors、geom-pair contacts、world-frame force/torque、collision-free visual mirrors、batch-vs-N1 parity	已关闭；CPU native 证据，不声明 GPU
Motrix / #121	immutable variant contexts、固定/浮动/被动/静态实体、selected reset/control/keyframe、site Jacobians、site/body/contact sensors、body force/torque、shared-scene interaction、kinematic mirrors、batch-vs-N1 parity	已关闭
Drake / #122	multi-root MJCF、被动关节、局部 reset、fixed variants、assignment、playback 与公开 DrakeUni 依赖	已关闭
Newton / #123	multiple articulation/world maps、fixed variants、具名 found contact、逐世界隔离与 assignment	已关闭
SuperDex / #124	superdex-uni 1.1.0 / ABI 2 的多 actor portable executor、固定/浮动/静态实体、selected control restoration、same-layout fixed variants、collision-free mirrors	仍开放

这些实现的共同原则是：公共 compiler 负责 profile、身份与 layout；adapter 只做 owner 内物化和 native binding；能力声明必须来自实际 native readback / 物理响应测试；不支持的能力显式 fail closed。文档与 support matrix 同步区分“已验证”“bounded”“unsupported”，避免把跨后端公共接口误读成九后端完全等价。

版本与集成状态

已发布：

• UniSim 1.7.0
• UniSim 1.7.1
• UniLab main 已消费 unisim-core>=1.7.1

最终集成分支上还有 Unreleased 项，主要是 #124 的 SuperDex same-layout fixed variants、selected control restoration 与 collision-free mirrors。它们在 0e691db 集成 head 中，但尚未随新的 UniSim 版本发布；UniLab 当前 1.7.1 消费面不包含这些 Unreleased 项。

验证证据

UniSim 治理记录中，每个子 PR 均要求：

• exact child head 的 current-head CI；
• merge parents 与 child/integration tree identity audit；
• focused native / contract / config tests；
• 需要时执行 support docs、mypy、pyright、packaging / lock checks；
• main 在子 PR 阶段保持不变。

最新集成 head 0e691db 的完整 make check 记录为：

• Ruff passed
• mypy passed
• Pyright 0 errors（已知 optional runtime warnings）
• pytest 1026 passed, 61 skipped

UniLab PR #1610 的最终 released-package 验收包括：

• focused consumer tests：148 passed, 2 skipped
• public IsaacSim acceptance：2 passed
• make check passed
• make test / make test-all：1491 passed, 28 skipped, 601 deselected，benchmark imports 通过
• exact-head CI 与 Docs workflow 均 passed

真实 IsaacSim 证据使用 RTX 4090、driver 595.84、IsaacSim 5.1.0.0、IsaacLab 0.47.2、外部 Python 3.11 worker 与 unisim-core==1.7.1。

尚未完成 / 不应过度解读的边界

1. Work: 将 backend 兼容补丁从脚本和 worker 收回 owner layer #154 保持 open，尚无 dev/issue-154-mjcf-portable-scenes → main 的最终集成 PR。
2. docs: remove en, ja, ko language docs, keep only zh_CN #124 保持 open，剩余重点是：
   • SuperDex physical kinematic roots；
   • portable world-body plane contact sensors；
   • docs: remove en, ja, ko language docs, keep only zh_CN #124 final native acceptance audit。
3. 当前 SuperDex 集成 profile 基于 superdex-uni==1.1.0 / ABI 2。physical roots 的既定前置是上游打包并公开发布包含 SceneBatchExecutorV3 ABI 3 的 1.2.0 wheel；在 exact public wheels 验证前不会改 UniSim 依赖或实现。
4. Work: 提取 LocomotionBaseEnv — 消除 G1/Go1/Go2 三重代码复制 #133 native camera / RGB 独立开放，不属于本轮物理闭环完成声明。
5. Work: 增加 repo hygiene 检查并清理遗留 .bak 资产 #152 MJWarp device-resident pre-step control 独立开放。
6. Genesis 证据是 CPU native 证据；Drake / Newton / SuperDex / IsaacSim 的支持范围以各自 support matrix 和验收硬件为准，不做统一 GPU 或 renderer 等价声明。

关键链接

• Roadmap: roadmap: MJCF-first 可信场景组合与操作闭环（#91 后续） unilabsim/unisim#154
• 公共契约 owner: feat: 公共 MJCF 场景 profile、编译表示与内容身份（#154 A） unilabsim/unisim#155
• SuperDex owner: [#154 D] SuperDex: multi-actor scene plans and a public batch state contract unilabsim/unisim#124
• UniSim 最终集成分支 compare: unilabsim/unisim@main...dev/issue-154-mjcf-portable-scenes
• UniLab 消费 issue: test: UniSim 公共场景契约的消费兼容与操作 smoke #1609
• UniLab 消费 PR: fix: consume released unisim portable scenes #1610
• UniSim 1.7.1 API 记录: https://pypi.org/pypi/unisim-core/1.7.1/json