执行摘要

• 一句话：内联 extend_range 访问器并删除 fill_len/extend_input_len
• 推荐动作：该 PR 值得仔细阅读，展示了如何安全地进行大规模属性替换，以及如何系统性处理由重构触发的连锁问题。特别是作者使用 Claude Code 协助根因分析的做法值得借鉴。对于技术管理者：可以观察团队在重构中维护 CI 通过率的策略。

功能与动机

PR body 指出两个属性都是 extend_range 的确切别名，替换后删除冗余，简化 API，且“每处更改都是1:1替换，无行为变更”。此外，早期 commit 记录了为解决 extend_input_len 生命周期中的双重语义而统一到 extend_range 的动机。

实现拆解

1. 引入 extend_range 复合结构（前置 PR #27610）：在 Req 上新增 extend_range（Range 类型）字段，同时保留 fill_len 和 extend_input_len 只读属性作为别名实现渐进迁移。

2. 全局替换属性读取：在所有文件中将 req.fill_len 替换为 req.extend_range.end，将 req.extend_input_len 替换为 req.extend_range.length，涉及 19 个文件的纯机械替换。

3. 删除属性定义：在 schedule_batch.py 中移除 fill_len 和 extend_input_len 属性，更新相关注释（如 kv_send 的注释）。

4. 更新测试 double：删除 _FakeReq 类（直接使用 SimpleNamespace），删除 MockReq.fill_len 属性，确保测试能适配新 API。

5. 修复回归和隐藏 bug：内联暴露了之前被掩盖的问题：cache_unfinished_req 的 assert 在 extend_range 为 None 时触发，EAGLE3 的 test double 缺少 extend_range 属性，以及 chunked prefill radix 命中计数回归。这些在贡献者讨论中定位并修复于关联 PR（#27610、#27573、#27611 本身）中。

关键文件：

• python/sglang/srt/managers/schedule_batch.py（模块 调度核心；类别 source；类型 core-logic；符号 fill_len, extend_input_len）: 核心变更文件：删除了 fill_len 和 extend_input_len 属性，将所有内部引用替换为 extend_range.end 和 extend_range.length，同时更新了注释和 get_fill_ids 方法。
• test/registered/unit/managers/test_hisparse_unit.py（模块 HiSparse测试；类别 test；类型 test-coverage；符号 _FakeReq, fill_len, extend_input_len）: 测试配套：删除了 _FakeReq 类，将 mock 直接改为 SimpleNamespace；更新了断言检查点。
• python/sglang/srt/managers/scheduler.py（模块 调度引擎；类别 source；类型 core-logic）: 调度器中多处使用了 extend_input_len 和 fill_len，全部替换为 extend_range.length 和 extend_range.end。
• python/sglang/srt/disaggregation/decode_schedule_batch_mixin.py（模块 分离部署；类别 source；类型 core-logic）: 分离部署解码批处理 mixin 中使用 extend_input_len，全部替换为 extend_range.length。
• python/sglang/benchmark/one_batch.py（模块 基准测试；类别 source；类型 core-logic）: 基准测试中使用 fill_len 和 set_extend_input_len，替换为 extend_range.end 和 set_extend_range。

关键符号：fill_len, extend_input_len, set_extend_range, get_fill_ids, _recompute_extend_logprob_start_len

关键源码片段

python/sglang/srt/managers/schedule_batch.py

核心变更文件：删除了 fill_len 和 extend_input_len 属性，将所有内部引用替换为 extend_range.end 和 extend_range.length，同时更新了注释和 get_fill_ids 方法。

# schedule_batch.py (head 版本 ) – 删除 fill_len/extend_input_len 属性后
class Req:
    # ... 其他字段 ...
​
    def set_extend_range(self, start: int, end: int) -> None:
        """设置 extend_range 并重算 logprob 起始位置"""
        self.extend_range = Range(start, end)
        self._recompute_extend_logprob_start_len()
​
    def get_fill_ids(self) -> array:
        """返回已填充 token 的 ID 序列"""
        # 以前 : return self.full_untruncated_fill_ids[: self.fill_len]
        return self.full_untruncated_fill_ids[: self.extend_range.end]
​
    def _recompute_extend_logprob_start_len(self) -> None:
        # 以前 : min(..., self.extend_input_len)
        self.extend_logprob_start_len = min(
            logprob_start_len - len(self.prefix_indices),
            self.extend_range.length,
        )

test/registered/unit/managers/test_hisparse_unit.py

测试配套：删除了 _FakeReq 类，将 mock 直接改为 SimpleNamespace；更新了断言检查点。

# test_hisparse_unit.py (head 版本 ) – _FakeReq 已删除
def _make_req(rid="test-req-0", origin_input_ids=None, output_ids=None):
    """创建最小 mock Req 对象"""
    # 以前使用 _FakeReq(SimpleNamespace) 子类提供 fill_len / extend_input_len 属性
    req = SimpleNamespace(
        rid=rid,
        origin_input_ids=origin_input_ids,
        output_ids=output_ids,
        fill_ids=origin_input_ids + output_ids,
        # ... 其他字段 ...
    )
    req.finished = lambda: req.finished_reason is not None
    req.set_extend_range = lambda start, end: setattr(
        req, "extend_range", Range(start, end)
    )
    return req
​
# 在断言中：
# 以前 : self.assertEqual(req.extend_input_len, fill_len)
self.assertEqual(req.extend_range.length, fill_len)

评论区精华

作者利用 Claude Code 自动分析 CI 失败，确认了三个根因：生产代码 cache_unfinished_req assert、EAGLE3 的 test double 缺少 extend_range、test_prefill_adder mock 缺失。随后在堆叠的 PR 中分别修复。还发现一个 chunked prefill radix 命中计数回归，根因定位到 cache_unfinished_req 缓存语义分歧，修复在 #27573。讨论主要来自 issue comment，无 reviewer 直接介入。

• CI 失败根因分析 (correctness): 在引入 PR #27610 中增加 assert 保护，在测试中补充 mock。
• chunked prefill radix 回归 (correctness): 通过将缓存范围限制到 origin_input_ids 长度修复，修复在 #27573。
• test double 更新 (testing): 在本 PR 中更新了 _FakeReq（删除）和 MockReq，修复了 test_prefill_adder 和 test_hisparse_unit。

风险与影响

• 风险：
  • python/sglang/srt/managers/schedule_batch.py：属性删除可能遗漏外部引用，但已通过全局搜索替换覆盖。
  • test/registered/unit/managers/test_hisparse_unit.py：mock 未及时更新导致测试失败，但已修复。
  • python/sglang/srt/managers/scheduler.py：多个控制流依赖 fill_len/extend_input_len，替换后需确保逻辑一致。
  • python/sglang/srt/disaggregation/prefill.py：分离部署逻辑中使用了 fill_len 的注释和代码，已对应更新。
  • 回归风险：内联后 extend_range 为 None 时未保护，后续通过 assert 修复；radix 命中计数回归已由 #27573 解决。
  • 影响：对用户无影响，纯内部重构。对调度器和分离部署模块的开发者：API 简化，减少认知负担。对测试维护者：mock 层简化。影响范围：19 个文件，涉及调度、分离部署、基准测试、HiSparse 等功能路径。
  • 风险标记：核心路径变更, 测试覆盖风险, 回归风险

关联脉络

• PR #27610 引入 extend_range 字段替代 fill_len/extend_input_len: 前置 PR，引入了 extend_range 字段和两个兼容属性，本 PR 在此基础上进行内联和删除。
• PR #27573 修复 cache_unfinished_req 缓存语义和 test double: 修复了本 PR 内联后暴露的 radix 命中计数回归和部分 test double 缺失问题。