执行摘要

• 一句话：修正 offload 参数帮助文案，与真实行为对齐
• 推荐动作：不值得精读：单文件 3 行帮助文案修复，几分钟可看完。值得借鉴的是作者的校验方式——不凭印象改文案，而是对照 validate_args 的真实默认填充逻辑（None 判断）来校正 help 表述，并把“显式 --no- 会被尊重”这一行为写进文案；同时刻意不动正确的 --offload-rollout 阶段描述，变更面控制得很小，是“文档与实现互相校验”的小型范本。

功能与动机

PR body 说明：help 字符串是用户最先读到的文档，而两处文案都会误导用户——一处描述了错误的 offload 阶段，另一处告诉用户一个实际存在（却宣称不存在）的逃生通道。作者在核对 Training Backends 文档重写（#2375）时发现，文档的 “both implied by --colocate” 措辞与 validate_args 的实际默认行为一致，反而是代码自身的 help 文案偏离了实现。本 PR 的目标是让 CLI 帮助文本与真实语义对齐：offload 发生在生成阶段，以及 if args.offload_train is None 时 colocate 才补默认值。

实现拆解

1. 阶段语义修正（核心）：在 miles/utils/arguments.py 的 add_cluster_arguments(parser) 中，把 --offload-train 的 help 从 “during training” 改为 “while the rollout engines generate”。该 flag 的价值就在于生成阶段把训练 actor 腾出显存（门控 sleep/wake_up），与 --offload-rollout（训练期间 offload 生成器）互补，两个阶段描述必须区分清楚；--offload-rollout 的阶段表述原本正确，特意保持不动。
2. colocate 表述修正：两个 flag 的 help 均去掉 “This will always be true when --colocate is set.”，改为 “Defaults to true when --colocate is set; an explicit --no-offload-train/--no-offload-rollout is respected.”。这与 validate_args 中 colocate 分支仅在 if args.offload_train is None、if args.offload_rollout is None 时才补默认值的行为完全对应——显式传 --no- 形式的用户意图会保留。
3. 验证与配套：纯 help 文本变更，无测试、配置或部署配套改动；作者用 python3 -m py_compile 验证语法、仓库锁定的 black==24.3.0 --check --line-length 119 验证格式。现有测试不覆盖 help 文案，本 PR 也未新增断言。

关键文件：

• miles/utils/arguments.py（模块 参数解析；类别 source；类型 help-text；符号 add_cluster_arguments）: 唯一变更文件。add_cluster_arguments 中 --offload-train 与 --offload-rollout 的 help 文案被修正，使 CLI 帮助与真实 offload 阶段语义及 colocate 默认填充行为一致。

关键符号：add_cluster_arguments

关键源码片段

miles/utils/arguments.py

唯一变更文件。add_cluster_arguments 中 --offload-train 与 --offload-rollout 的 help 文案被修正，使 CLI 帮助与真实 offload 阶段语义及 colocate 默认填充行为一致。

# miles/utils/arguments.py，add_cluster_arguments() 中两个 offload 参数的连续定义区。
# `--offload-train` 的 offload 阶段是“rollout 引擎生成期间”，而非“training 期间”：
# 该 flag 通过控制训练 actor 的 sleep / wake_up，在生成阶段把训练参数腾出显存，
# 与 `--offload-rollout`（训练期间 offload 生成器）正好互补。
parser.add_argument(
    "--offload-train",
    action=argparse.BooleanOptionalAction,
    help=(
        "Whether to offload the training actor to CPU while the rollout engines generate. "
        "Defaults to true when --colocate is set; an explicit --no-offload-train is respected."
    ),
)
​
# `validate_args` 中的 colocate 分支只在 flags 为 None（即用户未显式设置）时才补默认值，
# 所以显式的 `--no-offload-*` 会被保留；两处 help 因此去掉了 “always true” 的绝对化表述。
parser.add_argument(
    "--offload-rollout",
    action=argparse.BooleanOptionalAction,
    help=(
        "Whether to offload the rollout generator to CPU during training. "
        "Defaults to true when --colocate is set; an explicit --no-offload-rollout is respected."
    ),
)

评论区精华

该 PR 没有任何 review 评论，Zhichenzzz 直接 APPROVED（无批注），comments_count 与 review_comments_count 均为 0，不存在设计争议或未决问题。值得注意的只有 PR body 中的事实核对说明：作者明确指出 --offload-rollout 的阶段描述原本正确、故未改动，属于有意识的最小化变更。

• 暂无高价值评论线程

风险与影响

• 风险：
  • 回归风险极低：改动局限于 add_cluster_arguments 中两个参数对象的 help 字符串，action、default、类型均未动，集群参数解析行为（含 offload 相关默认填充逻辑）完全不变。
  • 隐式耦合：新 help 文案断言“显式 --no- 形式会被尊重”，该断言依赖 validate_args 中 colocate 分支的 if args.offload_train is None / if args.offload_rollout is None 补齐逻辑；若未来有人把该分支改为无条件覆盖，帮助文案会再次失真。
  • 测试缺口：仓库现有测试不覆盖 help 文本，本次也未新增断言，help 文案退化无法被 CI 拦截。
• 影响：
  • 用户侧：--help 输出更准确，消除两类误解——offload 发生在哪个阶段（training 还是 rollout 生成期间），以及 --colocate 是否会覆盖显式 --no- 参数。
  • 系统侧：无行为变更，不影响训练、rollout、显存调度或配置解析。
  • 团队侧：与 #2375 Training Backends 文档重写的措辞（both implied by --colocate）保持一致，消除了“文档对、help 错”的偏差，为文档与 CLI 一致性维护提供了范例。
  • 风险标记：仅 help 文案变更, help 断言依赖 validate_args 补齐逻辑, 无 help 文案测试覆盖

关联脉络

• PR #2382 fix: drop duplicated rematerialize validation call: 同样修改 miles/utils/arguments.py 的 validate_args 区域，与本 PR 同属参数校验与 CLI 语义维护线；后续改动该校验逻辑时需注意与这段 help 文案的表述保持一致性。
• PR #2375 docs: Training Backends 文档重写（PR#2390 body 引用，历史列表未收录详情）: PR#2390 的 body 明确说明是在核对 #2375 文档重写时发现 help 文案错误——文档的 “both implied by --colocate” 措辞与实现一致，反而是代码 help 偏离，本 PR 可视作该文档线的配套校正。