执行摘要

• 一句话：保留引擎启动前的延迟解析声明，防止 Dynamo 配置被丢弃
• 推荐动作：值得精读。虽然 diff 极小，但它定义了一个重要的状态语义契约：_resolved_overrides 不再是解析管线的内部临时变量，而是 launcher 与引擎之间的声明通道。阅读重点：run_resolution_pipeline() 的初始化顺序、declare_late_resolution() 的 append 语义、以及 dummy 路径下声明跨多次解析存活的隐式不变量。对维护配置解析、launcher 集成的工程师有直接参考价值。

功能与动机

SGLang #36255 让 ServerArgs 保留原始 operator 输入（raw input），Dynamo 随之改用 declare_late_resolution() 在引擎启动前声明 pre-engine 设置。但 run_resolution_pipeline() 一开始就把 _resolved_overrides 重置为空列表，第一次解析便将 launcher 的声明清空，导致 Dynamo 的 snapshot、GPU-memory-service、forward-pass-metrics 设置被静默丢弃。PR body 明确说明这是 Dynamo 集成审计中暴露的第二个失败（第一个是 page_size=None 的 TypeError，由 Dynamo #13905 修复），并要求“让下游 launcher 保留其预期的有效配置，同时 raw ServerArgs 值保持不变”。

实现拆解

1. 变更入口：python/sglang/srt/arg_groups/pipeline.py 的 run_resolution_pipeline()，这是所有 ServerArgs 解析路径的单一入口，任何 server/engine 启动都会经过这里。
2. 核心逻辑变更：在快照 _raw_input 之后，原代码无条件执行 server_args._resolved_overrides = [] 来重置声明栈；现改为 list(getattr(server_args, "_resolved_overrides", ()))，即复制既有声明而不清空。getattr 默认空元组保证属性尚未初始化时行为不变；list() 复制保证后续 handler append 的声明跟在 launcher 声明之后。
3. 顺序语义：launcher 声明保留在前，pipeline 内各 handle_* 阶段通过 declare_late_resolution() 产生的声明追加在后，维持原有的 last-writer-wins 行为——同一字段若 pipeline 也声明，则 pipeline 胜出，与修复前一致。
4. 配套测试：test/registered/unit/server_args/test_resolution_declarations.py 新增 test_pre_engine_late_resolution_reaches_the_projection，用 ServerArgs(model_path="dummy") 构造实例，在 resolve_once() 前声明 enable_forward_pass_metrics=True，断言 resolution_result() 可见该声明而 raw 字段仍为 False。注意 dummy 模型路径下 resolve_once() 会重新执行完整 pipeline，因此该用例同时验证了声明在多次解析之间持续存活的不变量。
5. 验证情况：完整测试文件 17 个用例通过，pre-commit 通过，作者在 issue 评论中确认相关 a-stage 测试已通过。

关键文件：

• python/sglang/srt/arg_groups/pipeline.py（模块 配置解析；类别 source；类型 core-logic；符号 run_resolution_pipeline）: 修复的核心：run_resolution_pipeline() 不再重置 _resolved_overrides，而是保留 launcher 在引擎启动前写入的声明；这是所有 ServerArgs 解析路径的必经入口。
• test/registered/unit/server_args/test_resolution_declarations.py（模块 解析声明；类别 test；类型 test-coverage；符号 test_pre_engine_late_resolution_reaches_the_projection）: 新增回归测试，覆盖“launcher 声明在引擎首次解析后仍可见”的核心场景，防止 _resolved_overrides 被重置的回归再次发生。

关键符号：run_resolution_pipeline, test_pre_engine_late_resolution_reaches_the_projection

关键源码片段

python/sglang/srt/arg_groups/pipeline.py

修复的核心：run_resolution_pipeline() 不再重置 _resolved_overrides，而是保留 launcher 在引擎启动前写入的声明；这是所有 ServerArgs 解析路径的必经入口。

def run_resolution_pipeline(server_args: Any) -> None:
    # 先快照调用方传入的原始输入。此后 raw 字段不再改写，
    # 解析结果由 raw_input 与声明栈（declaration stash）共同决定。
    server_args._raw_input = {
        field.name: getattr(server_args, field.name)
        for field in dataclasses.fields(server_args)
    }
​
    # 修复点：此前这里直接重置为 []，会把 Dynamo 等 launcher 在
    # Engine 启动前通过 declare_late_resolution() 写入的声明全部清空，
    # snapshot、GPU-memory-service、forward-pass-metrics 等 pre-engine
    # 设置因此被静默丢弃。现在改为复制既有声明，launcher 声明在前，
    # pipeline 后续产生的声明 append 在后，保持 last-writer-wins 顺序。
    server_args._resolved_overrides = list(
        getattr(server_args, "_resolved_overrides", ())
    )
​
    # 解析视图：后续 handler 的读写都经过 resolving_view，
    # 声明栈的保留保证 resolution_result() 能投影出 launcher 的意图。
    cfg = resolving_view(server_args)
​
    # ... 后续 handler 按依赖域顺序执行，handle_* 产生的新声明
    # 通过 declare_late_resolution() append 到 _resolved_overrides 末尾。

test/registered/unit/server_args/test_resolution_declarations.py

新增回归测试，覆盖“launcher 声明在引擎首次解析后仍可见”的核心场景，防止 _resolved_overrides 被重置的回归再次发生。

def test_pre_engine_late_resolution_reaches_the_projection(self):
    """launcher 声明在引擎首次解析后仍应可见。"""
​
    from sglang.srt.arg_groups.overrides import declare_late_resolution
​
    # 模拟 Dynamo launcher：引擎启动解析前声明 pre-engine 设置。
    server_args = ServerArgs(model_path="dummy")
    declare_late_resolution(
        server_args,
        "launcher",
        enable_forward_pass_metrics=True,
    )
​
    server_args.resolve_once()
​
    # 注意：dummy 模型路径下 resolve_once() 会重新执行完整 pipeline，
    # 因此该用例同时验证了声明在多次解析之间持续存活的不变量。
​
    # 投影必须看到 launcher 的声明：这是修复前被静默丢弃的部分。
    self.assertTrue(resolution_result(server_args, "enable_forward_pass_metrics"))
    # raw 字段保持 operator 的原始输入：声明不会回写记录本身。
    self.assertFalse(server_args.enable_forward_pass_metrics)

评论区精华

该 PR 没有任何 review 评论线程，设计权衡全部由作者在 PR body 中说明。关键结论：

1) ServerArgs 现在存在两种有意分离的状态——record 上的 raw operator 输入，与 declaration stash 中的有效配置；解析管线必须把 launcher 声明当作与内部派生的声明同等的输入。
2) 顺序保证——launcher 声明保留在前，pipeline 声明 append 在后，继续沿用 last-writer-wins。
3) 边界限定——不把默认值 materialize 回 raw 字段，不改 post-publish 变更规则，declare_late_resolution() 仍仅限 publish 前使用；page_size 的 resolved-view 交接由 Dynamo #13905 处理，不在本 PR 范围。

• 暂无高价值评论线程

风险与影响

• 风险：
  1. run_resolution_pipeline() 是所有 ServerArgs 解析路径的唯一入口（含 dummy/none 模型 short-circuit），该行为变化作用于所有 server 启动流程，虽然 diff 极小但处于核心路径。
  2. _resolved_overrides 的语义从“每次解析开始即为空”变为“跨 resolve 调用保留”；dummy 模型路径会重新执行 pipeline，launcher 声明因此跨多次解析存活——这是修复目标，但任何依赖“stash 必然为空”的调用方（例如对同一实例重复 resolve_once()）需要重新审视。
  3. 原代码注释强调 stash 在 short-circuit 前设置以保证 run_post_process_pass 和直接 handler 调用可用；现在 stash 可能携带 launcher 数据进入这些路径，none/dummy 模型分支对残留声明的容忍度需要确认。
  4. 测试仅覆盖 enable_forward_pass_metrics 一个字段，而 Dynamo 实际声明了 snapshot、GPU-memory-service、forward-pass-metrics 三项；缺少“launcher 与 pipeline 声明同一字段”的冲突测试，last-writer-wins 的顺序保证目前只有代码层面依据。
     - 影响：影响集中在配置解析语义层：launcher（当前主要是 Dynamo）在引擎启动前声明 pre-engine 设置的能力从“无效”恢复为“有效”，且无需改写 raw 输入记录，对用户传入参数的可见行为没有变化。对系统而言，ServerArgs 完成从单一状态到 raw/declaration 双状态的过渡，_resolved_overrides 升级为跨调用方的协议通道而非内部临时变量。对团队而言，后续修改解析管线时需理解该双状态模型；由于改动在核心入口上，虽小但需通过 CI 全量回归确认没有其他 launcher 受影响。
     - 风险标记：核心路径变更, 声明状态生命周期语义变化, 依赖外部 launcher 集成, 测试仅覆盖单一字段

关联脉络

• PR #36255 Preserve raw operator input in ServerArgs: PR body 明确引用 #36255 为本次回归的引入方：它让 ServerArgs 保留 raw operator 输入，Dynamo 随之改用 declare_late_resolution() 声明 pre-engine 设置；本 PR 是该变更的直接补丁。
• PR #36897 Decouple speculative draft capacity from runtime state: 同一时期 arg_groups 家族（overrides.py、runtime_context.py）的声明/状态解耦演进，与本 PR 将 _resolved_overrides 提升为跨调用方协议通道的设计主线一致。