Manager-based API：历史进展、当前状态与下一步需求征集

[TATP-233]

结论先行

截至 2026-08-17 的 main@21dbe464，UniLab 没有可用的通用 manager-based API，也没有已获实施授权的 manager roadmap。

历史上先后出现过三轮相关工作：

1. ManagedTaskPlan / TaskCompiler / PolicyABI 原型；
2. 可组合 Typed Term Function（TTF）设计；
3. 保留 NpEnv 的轻量 term plan + 自动 Numba fusion。

三轮都产出了有价值的设计和实验，但都没有成为当前主线能力。真正合入 main 的是从大分支中减法保留的独立 mjwarp host adapter；manager core、manager 专属训练 ABI、typed runtime 和后续 term-plan/Numba 路径均已删除、回滚或未合入。

本帖只做两件事：把历史事实放到一个地方，并征集真实使用需求。它不批准 roadmap，不授权恢复旧代码，也不把 mjwarp、Numba 或 backend 重构重新绑进 manager API。

历史时间线

时间	入口	实际进展	最终结果
2026-07-27	#702	提出 contract-first manager API：Hydra term、冷路径编译、不可变 plan、reference/fused executor、policy I/O signature；同时讨论了兼容 NpEnv 与 greenfield 两种方向	设计 issue，后被 #882 supersede
2026-07-28 至 08-03	#705、PR #847	在 feature branch 实现 manager/compiler、selector binding、fingerprint、host/device runtime、typed backend/mutation、G1 pilot，并把工作与 mjwarp production 化和大量 evidence/gate 绑定	PR #847 最终关闭、未合入 main；#883 记录该分支一度达到 304 commits、285 files、约 10 万行新增的 scope 失控
2026-08-01 至 08-03	#850、#852、#854、#866	复审确认原型在编译期 selector、ABI fingerprint、backend isolation、热路径预算等方面有价值；同时确认 TermDefinition 没有 callable、没有共享 term library，新增 reward 仍要修改 task kernel，因此不等同于 Isaac Lab / mjlab 语义下的 manager-based API；另有 CI、兼容性、证据比例和维护性 blocker	旧整改路线被 #882 取代
2026-08-03 至 08-06	#882、#902	先尝试收敛为统一 physics contract + manager API + 普通 mjwarp adapter，随后进一步做减法：删除 G1 manager pilot、manager 训练 ABI、通用 manager core、keyed RNG 和 typed batch/mutation 残留	PR #917 只把独立 mjwarp host adapter、PPO/SAC owner 和 offline record 合入 main；manager 不在交付中
2026-08-02 至 08-09	#868、#918	TTF 先提出 NumPy Tier 1 + Numba Tier 2；#918 又缩成两个 G1 pilot。PR #924–#928 曾合入 refactor 分支，但随后被逐项 revert；独立打包的 PR #929 在跨硬件/NUMA/规模复测后暴露 G1 回退与 motion e2e 配置缺口，最终未合入	#930 / PR #931 从 main 删除 Numba、相关执行路径、配置、benchmark 和 CI；完整因果链见 #932

历史工作真正留下了什么结论

已经有证据支持的结论：

• 配置可组合 term、共享 reward/observation 实现、稳定 policy I/O 描述，确实能改善 task authoring 和审计。
• selector 冷路径绑定、term 不接触 backend 私有对象、未知能力在 materialization 阶段 fail closed，这些方向符合 UniLab 的 contract-first 与 backend isolation。
• manager authoring 与高性能执行不是同一个问题；把两者和新 backend、runner、checkpoint、support、CI 一起做，会迅速失去可审查边界。
• 通用自动融合并不天然优于 task-specific kernel；局部热切片收益也不能替代 collector/training 端到端证据。

历史没有证明的结论：

• UniLab 当前必须拥有完整 Isaac Lab / mjlab 风格 manager runtime。
• 完整 Command/Event/Curriculum/Recorder manager 是现有用户问题的最小解。
• 旧 feature branch 中的 manager/compiler 可以直接恢复并生产化。
• manager API 必须绑定 Numba、mjwarp 或新的 backend contract。

当前主线基线

当前 main 的事实是：

• NpEnv 继续拥有 step/reset/autoreset/terminal observation 生命周期。
• reward 由 Hydra 配置注入；G1 walk 和 motion tracking 已有 task-owned callable reward dispatch（joystick.py、rewards.py）。
• SimBackend 仍是 env 可访问的物理边界。
• 当前 tree 中没有 src/unilab/manager、TermDefinition、CompiledTaskPlan、manager PolicyABI 或 Numba 执行面。
• #586（entity abstraction）、#627（mjlab raycaster rough task）和 #706（用户参考手册）是相邻的真实问题，但它们本身不自动构成“恢复完整 manager”的理由。

现在需要决定什么

建议先在下面三种方向中判断需求，不先写新架构：

0. 暂不重启通用 manager（默认建议）

继续使用 NpEnv + task-owned update_state + Hydra reward config，优先补参考文档、复用 helper 和具体任务迁移。适合当前痛点主要是“不会配置/缺文档”，而不是多个 task 持续复制同一套 observation/reward/termination 逻辑的情况。

永久维护成本最低，也不会新增公共 contract。

1. 只做窄的 task-authoring 层

只解决一个用户可见结果，例如“已注册 reward term 可由 owner YAML 选择、校验和记录”；保留 NpEnv 生命周期、task-owned command/reset/curriculum、NumPy 执行和现有 checkpoint。Observation、termination、action 分别等真实需求出现后再决定，不提前建设完整 manager 集合。

若选择这条路，第一个 implementation issue 仍应只有一个主要结果、一个 pilot、一个 PR，并遵守 ≤15 files / ≤800 行净手写改动；新增公共 contract 需单独确认。永久成本是 registry/schema、错误诊断、文档和跨 task 测试。

2. 重新讨论完整 manager runtime

只有当具体任务同时需要可组合 observation/action/reward/termination、command 重采样、event/DR、curriculum、entity/scene 寻址和稳定 policy ABI，而且现有 lifecycle 已明确成为阻塞时才进入。

这会是 env/config/backend/checkpoint 的跨层 umbrella，不是一个 implementation issue；需要逐项 child 授权，并接受长期维护 lifecycle、迁移工具、兼容策略和跨 backend 验证。旧 #705/#847 代码只能作为研究样本，不能默认恢复。

请按真实使用场景回复

如果你希望 UniLab 增加 manager-based 能力，请尽量提供：

1. 任务、论文或 benchmark 链接；
2. 目前必须复制或修改的具体文件/代码；
3. 真正需要的 term 类别：reward、observation、termination、action、command、event/DR、curriculum、metrics；
4. 需要的 backend 与典型 num_envs；
5. 是否必须兼容现有 owner YAML、checkpoint 和 task registration；
6. 最小能解除阻塞的结果是什么；
7. 为什么现有 task-owned callable dispatch + Hydra config 不够。

建议在至少出现两个独立、具体、可复现的使用场景前，不恢复通用 manager package。若需求集中在 reward/observation authoring，就从最窄的 authoring pilot 重新设计；若需求集中在 entity、sensor 或文档，则由对应 owner issue 解决，不把它们包装成 manager 重构。