背景
Roadmap #1476 将算法层拆分为独立包 unilab-rl（仓库 unilabsim/unilab_rl，namespace uni_rl）后，针对三类下游场景做了一轮架构评估（本地调研：mjlab、holosoma、FlashSAC、microduck_rl、simtoolreal 分支 feat/simtoolreal-sapg-core-cleanup）。总体结论：拆分边界对三类场景都正确；但学术场景（改算法/发论文的用户）存在真实摩擦，核心诉求是：尽量避免跨双仓（unilab_rl + UniLab）的改动。
本 issue 记录评估结论与待实施的缓解措施。
学术用户的算法创新形态（调研证据）
- holosoma（Amazon FAR）：918 LOC 手写 PPO（对称性增强/一致性 loss、跨 GPU all-reduce 的 EmpiricalNormalization、KL 自适应 LR）+ ~1900 LOC 定制 FastSAC（distributional critic、CNN 视觉变体、per-joint action scaling）。
- FlashSAC（arXiv 2604.04539）：zeta 分布探索噪声、fused double-Q 分类 critic、BC 正则 actor loss、UnitLinear/UnitRMSNorm 网络族、自有 n-step replay buffer。
- 共性：论文级创新 = 改 learner 内部（loss/网络/buffer/探索），不涉及 async/IPC 协议（两个仓库都没有 collector/learner 分离）。工作流是 editable install / fork 后在
algos/<name>/ 下加改子包，与其原生仓库布局同构，本身不算困难。
识别出的摩擦点（按严重度）
- 跨双仓变更：当创新涉及观测语义时（holosoma 式 symmetry maps 需读
robot_config.dof_names、per-joint action scaling、FlashSAC 式 asymmetric actor/critic obs dims），改动横跨 unilab_rl（算法）与 UniLab（env 契约）两个仓库。holosoma 式 env 内部窥探（observation_manager、episode_length_buf 直写）违反 EnvProtocol，必须迁入契约字段或 env 侧。
- runner 拥有 loop：holosoma 的 algo 自有 learn loop / checkpoint / ONNX / logging；uni_rl 中 runner 与 learner 分离，移植需适配 runner 契约。
- 新增算法 checklist 跨仓：加一个新算法目前要动 unilab_rl（实现）+ UniLab（
conf/<algo>/ Hydra 树、structured_configs、CLI 路由、train 入口）。
已存在的缓解机制（未成文）
runtime_resolver + class_name dotted-path：研究者可在自己的仓库实现算法（import uni_rl 作为库、子类化 runner/learner），owner YAML 写 runtime_resolver: my_repo.algos.myppo:resolve_runtime，无需 fork unilab_rl。EnvFactory 注入（uni_rl.env_contract）：外部包可自行组装 env。- simtoolreal 案例验证了适配器路线：接入全新 RL 栈（vendored rl_games + 9 文件胶水包）对已有算法零修改。
建议行动项（按性价比排序）
非目标 / 已确认无需动作
- ipc/offpolicy 归属：维持在 unilab_rl（algos 对它们是硬依赖；学术用户不碰 collector 协议，调研两个样本仓库均无 async 机制）。分层契约已写入 unilab_rl AGENTS.md，保留未来沿缝再拆的选项（YAGNI，现在不动）。
- 主机厂分发模式（vendor repo 只依赖 unilab + registry seam）：拆分对这类用户是纯收益，无需动作。
背景
Roadmap #1476 将算法层拆分为独立包 unilab-rl（仓库 unilabsim/unilab_rl，namespace
uni_rl）后，针对三类下游场景做了一轮架构评估（本地调研：mjlab、holosoma、FlashSAC、microduck_rl、simtoolreal 分支feat/simtoolreal-sapg-core-cleanup）。总体结论：拆分边界对三类场景都正确；但学术场景（改算法/发论文的用户）存在真实摩擦，核心诉求是：尽量避免跨双仓（unilab_rl + UniLab）的改动。本 issue 记录评估结论与待实施的缓解措施。
学术用户的算法创新形态（调研证据）
algos/<name>/下加改子包，与其原生仓库布局同构，本身不算困难。识别出的摩擦点（按严重度）
robot_config.dof_names、per-joint action scaling、FlashSAC 式 asymmetric actor/critic obs dims），改动横跨 unilab_rl（算法）与 UniLab（env 契约）两个仓库。holosoma 式 env 内部窥探（observation_manager、episode_length_buf直写）违反EnvProtocol，必须迁入契约字段或 env 侧。conf/<algo>/Hydra 树、structured_configs、CLI 路由、train 入口）。已存在的缓解机制（未成文）
runtime_resolver+class_namedotted-path：研究者可在自己的仓库实现算法（import uni_rl 作为库、子类化 runner/learner），owner YAML 写runtime_resolver: my_repo.algos.myppo:resolve_runtime，无需 fork unilab_rl。EnvFactory注入（uni_rl.env_contract）：外部包可自行组装 env。建议行动项（按性价比排序）
runtime_resolver指向外部包（不 fork）/ fork unilab_rl 改uni_rl/algos/。这是降低学术摩擦的最便宜手段。train_custom入口 + resolver 约定）。非目标 / 已确认无需动作