执行摘要

• 一句话：重写 Fully Async 文档，对齐代码并重构四章结构
• 推荐动作：值得精读。该页面现已成为理解 fully async 架构的最完整入口，文档的组织方式（机制 + flag 配对、把评测的两个正交轴拆开、reuse 与 export 分离）有很强的借鉴价值。对使用 fully async 模式的工程师，可直接把文中的 flag 与指标清单当作与代码对照的 checklist；对文档维护者，本 PR 展示了如何系统性地消除文档与代码的漂移。

功能与动机

PR body 明确指出页面已与代码脱节："The fully async page had drifted from the code. The sequence diagram showed an enqueue step that no longer exists, 'Tuning knobs' listed --sglang-server-concurrency and --num-steps-per-rollout as fully-async knobs, and nothing shipped since — DataBuffer, the submission scheduler, --async-unused-samples-handler, --async-data-buffer-capacity-factor, --async-max-concurrent-samples — was covered at all." 重写的目标是把文档对齐到 upstream/main 的实际实现，并让 knob 紧挨其作用的机制，而不是堆在一个无差别的列表里。

实现拆解

1. 页面结构重写：docs/user-guide/fully-async.md 从"Enable it / Queue model / Tuning knobs / Evaluation"改为四章——The fully async schedule（持续 worker、提交粒度、driver step 调度、staleness 来源）、Data path（DataBuffer 的 put / get / get_metrics 契约、DefaultDataBuffer 与 buffer/staleness 相关 flag）、Evaluation（三种后端按 Mode 1/2/3 组织，权重快照的 export 与 reuse 两种模式分节展示）、Metrics（async rollout 指标、async eval 指标与 dashboard 性能分析）。
2. 事实纠错：删除不存在的 async/queue_depth、async/producer_throughput_qps、async/consumer_drain_seconds 指标，改为 DefaultDataBuffer.get_metrics() 实际输出的内容；将 aborted_groups_recycled / stale_groups_recycled 修正为代码中的 *_filtered 命名；移除 --sglang-server-concurrency 与 --num-steps-per-rollout 两个非 fully-async knob；补充 --eval-interval 及 reuse 模式要求的 eval_interval % save_interval == 0 硬性约束；注明 staging 目录大小仅适用于 export 模式，因为 EvalDispatcher._retire 会跳过 reuse 模式的快照。
3. 序列图重建：mermaid 图重画，put() / get() 作为箭头跨越 subgraph 边界——接口在框外、DefaultDataBuffer 在框内，直观体现 --custom-async-data-buffer-path 的替换点。
4. 导航与链接调整：docs/docs.json 将 user-guide/fully-async 从页面列表末尾移到 argument-groups 之后；docs/index.md、docs/user-guide/index.md、docs/user-guide/usage.md 同步更新页面名称与描述。
5. 迭代与验证：第二个 commit 放弃品牌色段落改用 bold（相应放弃 style.css 的 .rx-lead 类改动），第三个 commit 补充 metric logging hooks 的文档；作者以 mint dev 本地渲染并逐一核对锚点与代码路径，pre-commit run --all-files 与 docs.json 解析均通过。无自动化测试配套（纯文档变更）。

关键文件：

• docs/user-guide/fully-async.md（模块 用户指南；类别 docs；类型 documentation）: 核心变更文件，全面重写 fully async 文档为四章结构，修正与代码漂移的序列图、knob 列表、指标命名，并补充 DataBuffer、submission scheduler、eval 硬约束等新内容。
• docs/docs.json（模块 站点配置；类别 config；类型 configuration）: 调整 User Guide 侧边栏页面顺序，将 fully-async 移到 argument-groups 之后，是站点导航结构变化的关键配置。
• docs/user-guide/usage.md（模块 用法文档；类别 docs；类型 documentation）: 更新 Training Backend 页对 fully async 的入站链接与描述，保证导航文字与页面新定位一致。
• docs/index.md（模块 文档首页；类别 docs；类型 documentation）: 首页 Core features 中同步 fully async 的链接文案，保持入口一致性。
• docs/user-guide/index.md（模块 指南索引；类别 docs；类型 documentation）: 用户指南索引页更新条目位置与描述，把 fully async 提升为紧邻 Argument Groups 的核心条目。

关键符号：未识别

关键源码片段

docs/docs.json

调整 User Guide 侧边栏页面顺序，将 fully-async 移到 argument-groups 之后，是站点导航结构变化的关键配置。

{
  "tab": "User Guide",
  "groups": [
    {
      "group": "User Guide",
      "root": "user-guide/index",
      "pages": [
        "user-guide/concepts",
        "user-guide/argument-groups",
        // fully-async 从列表末尾移到 argument-groups 之后，
        // 与“连续生成解耦训练”的主题定位保持一致。
        "user-guide/fully-async",
        "user-guide/usage",
        "user-guide/training-script-walkthrough",
        "user-guide/monitoring",
        "user-guide/dashboard"
      ]
    }
  ]
}

评论区精华

该 PR 没有产生任何 review 评论，Shi-Dong 直接 APPROVED。设计取舍主要体现在提交历史中：作者在第二个 commit 主动放弃品牌色段落的 .rx-lead CSS 类，改为 bold 强调，避免引入新的样式代码；第三个 commit 又补记了 metric logging hooks 章节。整体属于作者自查自收敛的文档迭代，无公开争议。

• 暂无高价值评论线程

风险与影响

• 风险：风险集中在文档与代码的一致性与链接稳定性：1）文档内容以 upstream/main 为基准核对，但 rollout 代码仍在演进（DataBuffer、submission scheduler 均为较新机制），后续若接口或 flag 变化，本页存在再次漂移风险，建议将文中 flag 与指标清单纳入定期核对流程；2）页面改名（Fully Async Rollout → Fully Async RL）与章节重排可能使仓库外链接失效，仓库内锚点虽已逐一验证，但外部引用无法控制；3）docs.json 顺序调整影响侧边栏，若存在依赖旧顺序的缓存或文档快照，可能出现展示偏差。无运行时回归、性能或安全风险。
• 影响：对用户（工程团队）影响较大：fully async 是核心训练模式，重写后的页面首次系统覆盖 DataBuffer、提交调度、staleness 与评测模式等真实机制，修正了误导性 knob 与指标，学习与排障路径更清晰。对系统无运行时影响，仅文档站结构与侧边栏顺序变化。对团队的意义在于确立了一种文档范式：机制与配置配对、以代码为唯一事实源，同类页面（如 argument-groups、monitoring）可参照此结构。
• 风险标记：文档与代码同步风险, 页面改名影响外部链接, 侧边栏顺序调整, 无自动化文档校验

关联脉络

• PR #2220 Add the GLM-5.2 744B x terminal-bench-2 Daytona example: 重写后的 fully-async.md 将 examples/experimental/openenv/glm52_tbench2/run_glm5_2_744b_a40b_daytona.py 列为 16 节点 agentic 端到端示例，两个 PR 直接衔接，同属 fully async 与 agentic rollout 功能线。
• PR #2274 refactor(openenv): move duplicated sandbox helpers into the TB2 recipe: TB2 沙箱辅助函数上收共享 recipe，与 #2220 的 Daytona 示例共同构成文档所述 tbench2 工作负载的基础设施，且本 PR 引用同一示例文件。