执行摘要

• 一句话：清理 srt/managers 冗余注释，重写评论风格规则
• 推荐动作：值得精读 .claude/rules/comment-style.md 与提交序列。规则中“成本恢复”测试（删掉注释后，熟悉仓库的人能否从周围代码加 grep 恢复该事实）和“写作 vs 编辑”的决策不对称，是注释管理的实用框架；提交序列展示了“先删后补”的收敛过程，对评审者判断注释清理 PR 的边界有参考价值。若团队计划继续推广该风格，建议参照本 PR 的亮线规则，避免在后续清理中误删承载跨文件契约的注释。

功能与动机

PR body 声明本次变更的目标是落实已有 comment style 规则：删除复述下一行、字段名或函数名的注释，压缩只复述签名的私有 helper docstring，同时保留 IPC wire-schema contracts、cross-rank invariants 与 sentinel meanings。作者希望让核心调度路径上的注释回归“提供代码看不见的事实”这一职责，减少大文件中的阅读噪音，并把执行中沉淀的判断标准固化回规则文档。

实现拆解

1. 源头删除（首个 commit 2d333e7）：在 tokenizer_manager_score_mixin.py、tokenizer_manager.py、schedule_batch.py 中删除所有与函数名、字段名或下一行重复的多行注释。典型对象包括 score_prompts、_build_multi_item_token_sequence、_batch_tokenize_query_and_items 的 Args/Returns 块，_detect_input_format、_tokenize_texts、_resolve_embed_overrides 的完整 docstring，以及 set_pad_value、merge、check_match_stop_str_prefix 的说明性 docstring。

2. 按约束恢复（提交 1b188b3 至 dcfbc39）：作者在自审/再评审中逐步恢复“承载事实”的注释——ScoreResult.pooled_hidden_states 的字段语义（CPU/GPU 张量、HTTP 路径转换位置）、IPC schema 字段注释、哨兵值说明、长函数中的分支/步骤标记、调度器的路由与空闲循环标记、评分模式分支横幅。这一步表明删除标准并非“能删就删”，而是“事实无法从代码恢复时保留”。

3. 收敛为亮线规则（提交 030fd58、2dedcc8）：将操作原则明确为“comment-only diff 不碰单行注释，只修剪多行散文块”，并重写 .claude/rules/comment-style.md：区分 Writing（作者掌握上下文，判断可靠）与 Editing（判断不可靠且错误单向）两种场景；编辑场景下删除一行无用注释的收益极小，而误删承载跨文件事实的注释损失不可逆，因此需要用亮线而非逐条判断。

4. 验证与配套：仓库内没有新增测试文件——纯注释变更不需要测试；PR body 声明所有文件在剥离 docstring 后与 main AST 逐字节一致（.claude/rules/comment-style.md 虽非源码，但也同步列入变更）。CI 状态显示 Base/Extra/AMD 三个任务失败，但 PR 仍被合入，失败原因未在材料中说明。

关键文件：

• python/sglang/srt/managers/tokenizer_manager_score_mixin.py（模块 评分请求；类别 source；类型 comment-cleanup；符号 score_prompts, _build_multi_item_token_sequence, _batch_tokenize_query_and_items, _process_multi_item_scoring_results）: 删除量最大的源码文件（+7/-116），清理 score_prompts、_build_multi_item_token_sequence 等函数的 Args/Returns 块，同时保留 pooled_hidden_states 字段约束注释。
• python/sglang/srt/managers/tokenizer_manager.py（模块 请求入口；类别 source；类型 comment-cleanup；符号 _detect_input_format, _tokenize_texts, _resolve_embed_overrides, _handle_abort_finish_reason）: 请求入口核心文件，删除 60 行冗余 docstring（_tokenize_texts、_detect_input_format 等），保留 rid_to_state 泄漏处理的长注释与长函数 Step 标记。
• python/sglang/srt/managers/schedule_batch.py（模块 批调度；类别 source；类型 comment-cleanup；符号 set_pad_value, merge, update_spec_correct_drafts_histogram, check_match_stop_str_prefix）: 调度批处理核心数据结构文件，删除 set_pad_value、merge 等函数的说明性 docstring，并压缩 update_spec_correct_drafts_histogram 的注释。
• .claude/rules/comment-style.md（模块 代码规范；类别 docs；类型 code-style）: 规则文档重写是本 PR 的方法论沉淀：区分写作与编辑、定义 comment-only diff 允许删除的内容、引入成本恢复判据。

关键符号：score_prompts, _build_multi_item_token_sequence, _batch_tokenize_query_and_items, _process_multi_item_scoring_results, _process_single_item_scoring_results, _detect_input_format, _tokenize_texts, _resolve_embed_overrides, _handle_abort_finish_reason, _discard_pending_req_states, set_pad_value, merge, update_spec_correct_drafts_histogram, check_match_stop_str_prefix

关键源码片段

python/sglang/srt/managers/tokenizer_manager_score_mixin.py

删除量最大的源码文件（+7/-116），清理 score_prompts、_build_multi_item_token_sequence 等函数的 Args/Returns 块，同时保留 pooled_hidden_states 字段约束注释。

# 源码：python/sglang/srt/managers/tokenizer_manager_score_mixin.py
# 本 PR 的清理对象：长 docstring 中的 Args/Returns 被删去，只保留“这个函数做什么”的描述。
​
async def score_prompts(
    self,
    prompts: Union[str, List[str], List[List[int]]],
    label_token_ids: List[int],
    apply_softmax: bool = False,
    request: Optional[Any] = None,
) -> ScoreResult:
    """
    Score probabilities of specified token IDs after each *full prompt*.
​
    This is a thin wrapper over `score_request` that treats `prompts` as
    already-composed inputs (i.e., no query/item concatenation needed).
    """
    # 单条文本：走空 query + 字符串 items 的路径
    if isinstance(prompts, str) or (
        isinstance(prompts, list) and (not prompts or isinstance(prompts[0], str))
    ):
        return await self.score_request(
            query="",
            items=prompts, # type: ignore[arg-type]
            label_token_ids=label_token_ids,
            apply_softmax=apply_softmax,
            item_first=False,
            request=request,
        )
​
    # 已分词的 prompt：query 置空，items 为 token 序列列表
    if isinstance(prompts, list) and (not prompts or isinstance(prompts[0], list)):
        return await self.score_request(
            query=[],
            items=prompts,
            label_token_ids=label_token_ids,
            apply_softmax=apply_softmax,
            item_first=False,
            request=request,
        )
​
    raise ValueError("Invalid prompts type for score_prompts.")

python/sglang/srt/managers/tokenizer_manager.py

请求入口核心文件，删除 60 行冗余 docstring（_tokenize_texts、_detect_input_format 等），保留 rid_to_state 泄漏处理的长注释与长函数 Step 标记。

# 源码：python/sglang/srt/managers/tokenizer_manager.py
# _detect_input_format 的 docstring 被整体删除：返回值枚举可以从 InputFormat
# 枚举名和分支条件中恢复，属于“cost-of-recovery 为零”的典型删除对象。
​
def _detect_input_format(
    self, texts: Union[str, List[str]], is_cross_encoder: bool
) -> InputFormat:
    # 单条字符串：无歧义地归为单文本
    if isinstance(texts, str):
        return InputFormat.SINGLE_STRING
​
    # cross-encoder 场景：首元素必须是 [query, document] 二元组，且长度恰好为 2
    if (
        is_cross_encoder
        and len(texts) > 0
        and isinstance(texts[0], list)
        and len(texts[0]) == 2
    ):
        return InputFormat.CROSS_ENCODER_PAIRS
​
    return InputFormat.BATCH_STRINGS

评论区精华

本 PR 的 comments_count 与 review_comments_count 均为 0，没有可引用的 reviewer 原话。但从 14 个提交的演进序列可以读出一次完整的“先删后补”自我修正：1b188b3 恢复承载约束的字段注释、ecd850b 将 io_struct 字段注释视为 IPC schema 文档保留、f77f0e6 恢复哨兵值与字段用途尾注释、1180319 恢复长函数中的分支与步骤标记、d9e849d 恢复调度器路由与空闲循环标记、1d420a2 恢复评分模式分支横幅与章节标题；最终在 030fd58 收敛为“不碰单行注释，只修剪多行散文块”，并在 2dedcc8 将规则文档重构为写作/编辑双模式。这一序列比任何 review 评论都更直接地展示了“注释清理”的边界在哪里。

• 暂无高价值评论线程

风险与影响

• 风险：注释信息丢失风险：删除 244 行注释意味着若判断失误，某些跨模块事实（如 IPC schema、rank 间不变量）可能消失。本 PR 通过显式保留这些类别来缓解，但同类后续 PR 需要同样的谨慎。核心路径文件变更：tokenizer_manager.py 与 schedule_batch.py 是请求处理与调度主路径，即便 AST 相同，也会增加这些文件在历史 blame/合并中的噪音，且可能与其他正在改动这些文件的 PR 产生冲突。CI 状态不明：三个 CI run 显示为失败但 PR 已合入，虽然注释变更不太可能引起运行时失败，但失败原因未在材料中交代，建议合入后留意后续 CI。
• 影响：对用户与系统：无任何运行时影响，AST 与 main 一致。对团队与可维护性：核心大文件的注释噪音显著减少，后续阅读与 review 的注意力可以集中在真正的逻辑上；同时 .claude/rules/comment-style.md 的更新为 AI 辅助编码（Claude Code）和人工 review 提供了一致、可执行的判断标准，影响后续所有文件的注释风格。对协作：本次改动涉及多个核心文件，与其他进行中的功能 PR 可能产生合入冲突，需要团队注意合并顺序。
• 风险标记：注释信息丢失风险, 核心调度文件改动, CI 失败已合入, 无测试配套（纯注释变更）

关联脉络

• PR #34829 📝 [NPU] Clean up quantization comments: 同为注释清理类 PR，说明仓库在系统性推进注释规范化，与本 PR 属于同一工作线。