[lemon-star608]

范围

本 PR 只保留 UniLab 通用 bugfix 和框架扩展点，不包含 CHORD 任务、数据集、custom actor 或配方特判。CHORD 下游实现位于独立 chord_unilab 仓库，通过官方扩展点消费这些能力。

关联 Epic：#2528。

Bug 修复

• 修正 mapped Entity 的模型 body ID 与后端 state-row 绑定，避免组合场景中的错误校验和寻址。
• 修复 compiled + AMP 连续 update 中梯度 buffer 被替换的问题，保持梯度存储有效并原地复用。

通用能力补全

• state-feedback action 可在每个 physics substep 读取公开状态并更新控制，默认批量 step 行为不变。
• custom actor 可声明命名 optimizer parameter groups 和独立 LR multiplier，并保留 schedule/checkpoint 语义。
• viser.pause_on_done 支持完成后停止推进并继续显示末帧。
• Curriculum/* 标量可从 env info 经 collector 和 logger 写入 TensorBoard。

不在本 PR 范围内

按 review 意见，n-step、raw reward relabel、compact critic replay 及其训练时钟配套改动已移出本 PR，后续单独讨论归属和评审路径。whole-cycle/custom-actor FP16 等新增性能工作也未包含在本 PR。

下游边界

以下内容均由 chord_unilab 拥有，不放在 UniLab：

• CHORD 任务、环境子类、factory 注册、资产和 reset/step terms。
• custom actor、residual 参数及 optimizer group 配方。
• n_step=3、reward relabel、compact critic replay、AMP 等 owner 配置。
• reward terms、actor/critic observation 和评估语义。

验证

当前 HEAD：b5438e07。

• make check：通过（Ruff、mypy、pyright）。
• make test：2836 passed / 62 skipped / 374 deselected。

本次已缩减上游范围，下游 CHORD 配方需要在 replay 能力的归属确定后重新验证。短训练和可视化只验证执行链路，不宣称训练收敛。

[TATP-233]

下游新建独立仓库

[lemon-star608]

可以下移到 chord_unilab 的部分：

• CHORD custom actor、residual 参数及 optimizer group 的任务配置。
• n_step=3、reward relabel、compact critic replay、AMP 等 FlashSAC 配方配置。
• 任务自己的 reward terms、raw reward/curriculum 信号发布，以及 CHORD 所需的 post-dt、total/dense 日志格式。
• actor/critic observation、critic context 和评估配置。
• 对应的环境子类、factory 注册及任务侧测试。

建议保留在 UniLab 的部分：

• Bug 修复

  • mapped Entity 的模型 body ID 与后端 state-row 绑定错误。
  • compiled + AMP 连续 update 时梯度 buffer 的保留与复用。
  • warmup、collection iteration 和 optimizer update 混用导致的训练时钟问题。

• 通用功能补全

  • state-feedback action 的逐 physics substep 生命周期；现有接口已有能力声明，但缺少执行实现。
  • custom actor 的命名 optimizer parameter groups、LR schedule 和 checkpoint 支持。
  • off-policy n-step、final observation/timeout bootstrap 和 stage-change pending flush。
  • raw reward replay/relabel、compact critic replay 及相应的显存预算计算。
  • Viser pause_on_done 播放控制。
  • Curriculum/* 从 env info 经 collector 到 logger/TensorBoard 的通用透传。

这些 UniLab 改动均不包含 CHORD 任务名或数据集特判；下游只通过公共接口消费。拆分后，UniLab PR 保留通用 bugfix 和能力补全，CHORD 任务、actor、配置及评估语义全部放到 chord_unilab。

[lemon-star608]

已按上述边界落实并更新当前 HEAD 9f634813：UniLab src/ 和 tests/ 中不再保留 CHORD/Sharpa/CHORD 数据集专属命名；CHORD 环境子类、factory、reward 日志、actor、配方和评估语义由独立 chord_unilab 仓库拥有。通用 bugfix 与能力补全保留在本 PR。两仓库门禁及真实 Newton 测试结果已更新到 PR 正文。

[TATP-233]

发现两处会影响训练正确性的阻塞问题，建议修复后再合并。

1. [P1] 提前 timeout 的 n-step bootstrap 折扣错误

src/unilab/rl/algos/flash_sac/learner.py:694 对所有样本固定使用 gamma**self.n_step。但 accumulator 会在窗口未满 n_step 时因 timeout 提前结束，例如 n_step=3、第 2 步 timeout 时，回报只累计两步，目标应为 R_2 + gamma**2 * V(final_obs)，当前却使用 gamma**3。这会系统性低估所有提前 timeout 窗口的 bootstrap 值。请随 replay 样本保存实际窗口长度或逐行 bootstrap discount，并相应修改目标计算。现有 test_flashsac_shortened_n_step_window_keeps_fixed_bootstrap_discount 固化的是错误语义，也应一并修正。

2. [P1] resume 丢弃 checkpoint 中的 environment-step 时钟

src/unilab/rl/runtime/offpolicy/double_buffer_runner.py:992-1008 读取、校验并打印 environment_steps，但没有保存或恢复它。随后 logger 在 :1661 从 0 创建，新 collector 的 total_steps 也从 0 开始并覆盖 logger，因此续训后的 TensorBoard step 轴、run summary 和下一 checkpoint 都会丢失续训前的环境步数。请恢复统一的 collector/logger 环境步偏移，并增加“保存→续训→再次保存”的回归测试，验证环境步数连续累计。

[TATP-233]

补充一条范围/架构评审意见：建议本 PR 收敛为 UniLab 通用 bugfix 与框架扩展点，不要将 CHORD 所需的 FlashSAC 算法语义改进一并合入。

建议留在 UniLab：

• compiled + AMP 连续 update 的梯度 buffer 修复，这是现有 FlashSAC 核心路径的正确性 bug。
• warmup、collection iteration、optimizer update 的训练时钟统一，以及 resume 的 environment-step 时钟修复。
• mapped Entity body/state-row 绑定修复。
• Manager-Based substep state-feedback、Curriculum 标量日志、viser.pause_on_done 等通用能力。
• custom actor 的命名 optimizer parameter-group 扩展机制可以保留，因为 optimizer、schedule、CUDA graph 和 checkpoint 生命周期由 UniLab 管理；但具体参数分组和 LR multiplier 配方应留在下游。

建议移到 chord_unilab：

• relabel_rewards 以及按当前 stage 权重重组历史 replay 奖励的算法语义；尤其不应通过 relabel_rewards: auto 改变上游 FlashSAC 的默认奖励路径。
• CHORD 的 n_step=3 配方及对应算法变体。如果上游当前没有其他消费者，本 PR 不必同时引入 NStepAccumulator、FlashSAC n-step TD target 和 runner 调度的整套耦合改动。
• compact critic replay 的 CHORD 配置与使用配方。底层紧凑存储是否作为通用 replay 扩展点保留，可拆成独立 PR 评审。
• 对应的 CHORD stage-change、奖励重组和端到端 smoke 测试。

如果 n-step 要完全由下游拥有，需要由下游提供独立算法实现，或先在 UniLab 定义稳定的 learner/objective 扩展点；不建议下游复制 FlashSAC 私有方法。

因此建议先在本 PR 移除 n-step、reward relabel 和 CHORD replay 配方，再合入通用 bugfix 与扩展机制。这样也能缩小前面正确性 review 的处理范围：timeout discount 问题随 n-step 实现移至下游处理，而 resume 时钟问题仍需在上游修复。