sglang-humanize-review

SGLang Humanize Review

将历史证据应用于当前分支时，请使用维护中的源代码契约。评审／历史语料库会保留各自的采集日期；它们不能证明当前的调度逻辑或数值默认值。对于内核替换，在将端到端测试视为覆盖之前，请先确认真实模型会执行候选实现。

概述

当用户要求进行 SGLang 风格的代码评审，或希望评审反馈模仿 SGLang 维护者而非通用代码检查时，请使用此技能。

每次评审都会先进行 PR 理解环节：简要总结变更，并绘制 Mermaid 执行流程图（标出 PR 新增／修改的步骤），让评审者在阅读问题之前了解差异实际如何运行。请参阅PR 理解图。

随附语料库收集自 sgl-project/sglang 的 PR，范围从首个公开 PR 到 2026-07-27，旨在排除由机器人／Agent 撰写的 PR。历史快照包含 User 类型的机器人泄漏（59 个 sglang-bot PR／60 个行内讨论串）；其内容和计数均予以保留。未来的采集会排除 -bot、metamergebot 和 diffray 账号。镜像作者身份并不能证明设计意图出自人工。此技能涉及的公开框架知识于 2026-10-05 更新；该次更新并未重新抓取 gzip 语料库，因此必须从 GitHub 实时查看 2026-07-27 之后的评审。采集器会分页获取每个 PR 的完整对话和评审历史，因此会完整收录多轮长讨论，而非在前 100 条事件处截断。语料库按评审事件整理，而不仅仅是单条评论：

• inline_review_thread：针对特定文件／路径的 GitHub 拉取请求评审评论，包含 diff_hunk 上下文，并按讨论串归组回复。
• pr_conversation：PR 顶层对话评论，包括设计讨论、复现请求、基准测试协商和作者后续回复。
• review_submission：如 COMMENT 和 REQUEST_CHANGES 等评审摘要正文，并保留评审状态。

每个事件都会保留 PR 元数据、评审者身份、原始评论文本、原始评论语言、时间戳、类别，以及 GitHub 提供的多轮回复。请先阅读 references/corpus-summary.md，了解覆盖范围、计数、热门路径和类别分布。不要将原始 gzip 语料库粘贴到上下文中；请通过辅助脚本读取，这些脚本会以受内存限制的分段读取语料库并返回摘要。

语料库工具

共有两个工具。对于实际 PR 评审，必须运行下面的穷尽扫描（见工作流第 3 步）；前 N 项查询工具仅用于后续深入查询。

穷尽扫描与综合（每次评审都要先运行）

summarize_sglang_review_corpus.py 会以受内存限制的分段扫描整个语料库，将所有相关讨论串汇总（而不仅仅是前 N 个），并仅保留指定数量、按相关性排序的评审意见。传入所有受影响路径和 PR 风险关键词；--path 和 --query 可重复使用，并按 OR 组合。

python3 skills/sglang-humanize-review/scripts/summarize_sglang_review_corpus.py \
  --path python/sglang/srt/speculative --path python/sglang/srt/managers \
  --query eagle --query "cuda graph" --query verify --query logprob \
  --top 30

它会报告 Scanned N threads ... matched M threads across K PRs，明确显示覆盖范围。请阅读汇总结果和排名靠前的讨论串，然后在开始评审前简要总结反复出现的历史评审意见。如需阅读所有匹配的讨论串，请使用 --format jsonl 进行流式输出。

前 N 项查询（仅用于后续深入查询）

按主题、路径、类别或评审者搜索语料库：

python3 skills/sglang-humanize-review/scripts/query_sglang_review_corpus.py \
  --query cuda --limit 5

python3 skills/sglang-humanize-review/scripts/query_sglang_review_corpus.py \
  --path python/sglang/srt --category correctness --limit 8

python3 skills/sglang-humanize-review/scripts/query_sglang_review_corpus.py \
  --query server_args --format jsonl --limit 3

python3 skills/sglang-humanize-review/scripts/query_sglang_review_corpus.py \
  --kind pr_conversation --query benchmark --limit 5

python3 skills/sglang-humanize-review/scripts/query_sglang_review_corpus.py \
  --kind review_submission --query "request changes" --limit 5

完整语料库位于：

references/sglang-review-corpus.jsonl.gz

仅当用户要求更新证据时才重新生成（将 --end-year 提升至当前年份；采集器会将事件时间范围截断至“现在”，并分页获取每个 PR 的完整对话／评审历史）：

python3 skills/sglang-humanize-review/scripts/collect_sglang_review_corpus.py \
  --repo sgl-project/sglang \
  --from-beginning \
  --end-year 2026 \
  --out-dir skills/sglang-humanize-review/references

评审工作流

1. 先检查实际差异。
   • 使用 git diff、gh pr diff 或用户提供的补丁。
   • 确定发生变更的 SGLang 子系统：服务端参数、调度器、内存/缓存、 模型运行器、注意力后端、量化、内核、OpenAI API、 指标、文档或测试。
2. 阅读 references/corpus-summary.md。
   • 留意重点审查领域以及与差异重合的类别。
   • 检查案例覆盖情况。针对文件内发现，内联证据最合适；针对设计、基准测试、复现步骤和作者后续跟进，PR 对话证据最合适；针对阻止合并的审查意见和维护者级总结，审查提交最合适。
   • 保留相关语料示例的原始语言；除非用户要求，否则不要翻译面向用户的评论。
3. 穷尽扫描语料，然后综合历史审查意见。必须先完成此步骤，才能开始撰写任何发现——不要只看前几个结果就开始审查。
   • 针对所有变更路径（--path，可重复指定）和 PR 的风险关键词（--query，可重复指定；例如 cuda、kv cache、server_args、openai、logprob、tp、dp、eagle、fp8、benchmark、pytest）运行 summarize_sglang_review_corpus.py。该脚本会以受内存限制的分段扫描所有讨论串，并汇总所有相关匹配项，而不是只看前 N 条。
   • 根据脚本输出中的 Scanned N ... matched M across K PRs 确认覆盖情况。如果 matched 为 0，请扩大路径或关键词范围后重新运行；如果匹配数量非常大，请阅读汇总内容和排名靠前的讨论串，必要时使用 --format jsonl 流式读取完整结果。
   • 阅读匹配到的讨论串——尤其是当 PR 会改变行为、测试、文档、基准测试、部署默认值或模型支持时，至少阅读一个非内联来源（pr_conversation 或 review_submission），并撰写简短综合总结：反复出现的顾虑、审查者阻止合并与仅提出小建议的事项、他们要求的复现步骤/基准测试，以及该子系统通常如何解决问题。优先采用同一子系统的证据，而非宽泛的关键词匹配。发现必须以此总结为依据。
   • 仅在完成扫描后，使用 query_sglang_review_corpus.py 深入查看扫描中发现的特定讨论串或审查者。
4. 如果差异涉及本仓库中其他技能涵盖的领域，请补充跨技能证据。
   • 模型系列实现或优化：针对模型标识查询 model-pr-optimization-history，判断此变更是否重复或与过往 PR 冲突。
   • 性能声明或热点路径：使用 llm-torch-profiler-analysis、llm-pipeline-analysis 或 model-compute-simulation 中的证据，而不是笼统要求“进行基准测试”。
   • 内存/KV/缓存容量变更：参考 llm-serving-capacity-planner 对启动日志和容量核算的要求。
   • 服务事故、挂起或分布式回归：遵循 sglang-prod-incident-triage 风格的重放要求。
5. 先解释 PR，再进行评判（PR 理解阶段）。
   • 此步骤为必做项，且必须始终置于任何审查发现之前。
   • 目标：通过简短的文字总结和 Mermaid 图，让审查者无需通读整个差异，便能在一分钟内理解变更内容以及变更后的代码如何运行。请遵循下方的 PR 理解图规范。
   • 沿着变更行追踪实际执行路径：入口、控制流、数据流、修改过的分支/调用，以及新行为与旧行为的分歧点。突出显示变更节点。
   • 阅读足够多的上下游代码（调用方、被调用方、配置接线代码），确保流程准确。不要编造差异或其涉及文件中不存在的函数或调用关系。
6. 生成代码审查回复。
   • 先列出具体发现，并按严重程度排序。
   • 包含所审查差异中的文件和行号引用。
   • 说明故障方式，而不只是偏好哪种代码风格。
   • 对可采取行动的问题，建议修复方案或验证步骤。
   • 将小问题与正确性、性能或兼容性风险分开。
   • 任何依赖差异之外代码的论断，都必须根据 PR 分支进行核实。 有关调用点覆盖、方法遮蔽/MRO、“没有其他调用方”或精确行号的发现，取决于基准版本：本地仓库若处于不同提交，可能会产生看似可靠的误报（例如，根据过时的 EagleVerifyInput 断言存在 PR 分支上并不存在的方法冲突）。请使用 gh pr diff、gh api .../contents/<path>?ref=<pr-sha> 或 git show <pr-sha>:<path> 进行确认。如果只有版本不匹配的检出，请将该发现标记为“需要在 PR 分支上核实”，不要直接断言。
7. 如果未发现问题，请明确说明。
   • 提及主要剩余风险，以及哪些测试或基准测试覆盖可以提高可信度。

基于语料的 SGLang 审查启发式

优先关注以下风险，因为它们在语料中的人工审查讨论串里反复出现：

• 模型和量化行为：模型配置漂移、分词器假设、FP8/INT4 量化路径、MoE 路由、推测解码，以及注意力后端兼容性。
• 正确性优先于风格：边界情况、断言失败、意外错误代码、形状/数据类型不匹配、状态清理，以及静默行为变更。
• GPU 和内核路径：CUDA 图捕获、Triton/CUDA 内核、FlashInfer 和 FlashAttention 行为、启动条件、SM 兼容性，以及回退行为。
• 服务端 API 兼容性：兼容 OpenAI 的请求/响应形状、server_args、CLI 默认值、端点行为、流式传输，以及向后兼容性。
• 内存和缓存生命周期：KV 缓存核算、基数缓存重置、内存池所有权、驱逐、碎片化，以及 OOM 行为。
• 分布式运行时：TP/DP/PP/EP 的秩假设、NCCL 路径、同步、工作进程状态、竞态条件，以及挂起风险。
• 测试和基准测试：行为发生变化时，要求提供有针对性的测试；如果变更声称能提升性能或涉及热点路径，则要求提供基准测试证据，并注明工作负载、模型、硬件、精度、框架提交版本，以及变更前后的命令。
• 文档和示例：确保文档与 CLI 默认值、端点名称、模型支持情况、安装步骤以及特定版本的行为保持一致。
• 可观测性：当运行行为发生变化时，审查指标、日志、警告级别、可追踪性和错误消息。

PR 理解图

在列出审查发现之前，先输出一个理解模块，让审查者一眼看懂 PR 的原理。该模块包含两部分：

1. 变更摘要（2-6 条）。 使用通俗语言说明：涉及哪个子系统、PR 改变的核心机制，以及承载实际行为变更的一两行代码。注明入口点和涉及的文件。
2. Mermaid 流程图，展示与 PR 相关路径的执行逻辑，并用视觉标记标出变更步骤，每张图后立即附上详细的文字说明。

图表规则：

• 使用带围栏的 ```mermaid 代码块，并采用 flowchart TD（短线性流程可用 LR）。这样可以在 GitHub PR 评论和大多数 Markdown 查看器中渲染。
• 描绘运行时执行路径，而非文件树：入口点 → 控制流（分支/循环）→ PR 新增或变更的调用和数据转换 → 返回值/副作用。读者应能看清请求/张量/批次如何实际流经变更代码。
• 为 PR 新增或修改的节点标记 changed 类，未改动的上下文节点保持普通样式，以清楚展示新旧行为差异。始终包含图例节点。
• 在分支处发生行为变更时，用条件或沿边传递的数据标注边（-->|fp8 path|、-->|cache miss|）。
• 控制在约 6-14 个节点。如果 PR 涉及彼此独立的代码路径，每条路径各自输出一个小流程图，用单独的 ```mermaid 代码块垂直排列（一个接一个，绝不并排）——不要把两个 subgraph 塞进同一个代码块，这会使它们水平排列并缩小到难以辨认。对于没有控制流变化的纯重构，用两个简短分支展示新旧方案，并说明这一点。
• 优先使用 flowchart TD（自上而下），让图表纵向展开，保持易读；只有真正短小的线性链路才使用 LR。
• 每张图后立即附上简短的文字说明，讲解该图：入口点是什么、各分支/条件代表什么，以及 PR 修改了哪些节点、原因是什么。图表用于建立整体概念；审查者会阅读文字说明。绝不要只放图表而不加解释。
• 在节点标签中引用真实符号（function、ClassName.method、file:line），以便对照 diff 验证。不要编造边。
• 语法安全：确保代码块能在 GitHub 固定版本的 Mermaid 中渲染，而不只是最新 CLI 版本。任何包含 ()、,、:、=、>、& 或 / 的节点或边标签都要用双引号括起来——C["down_proj(x, skip_all_reduce=rs)"]、B -->|"id < 0 or id >= vocab"| N。标签内的换行使用 <br/>，绝不要使用字面量 \n。在末尾放置一次 classDef changed stroke-dasharray:5 5,stroke-width:2px;。无条件使用引号是最安全的做法。

根据实际情况调整以下框架（将标签替换为 PR 中真实的符号和路径）：

flowchart TD
    A["Entry: forward / handler / scheduler step"] --> B{"Branch the PR changes"}
    B -->|"new condition"| C["New/changed call or transform"]:::changed
    B -->|"existing path"| D["Unchanged path"]
    C --> E["Downstream effect: KV write / output / metric"]:::changed
    D --> E
    E --> F["Return / response / side effect"]

    L["Legend: dashed border = added or modified by this PR"]:::changed
    classDef changed stroke-dasharray:5 5,stroke-width:2px;

请将此理解模块放在回复开头，然后再列出审查发现。保持简洁；其目的是帮助读者快速理解，而不是代替代码审查本身。

审查风格

遵循 SGLang 人工审查的习惯：

• 简洁，但要具体。
• 意图不明确时，优先用提问的方式表达。
• 明确指出面向生产环境的行为变更。
• 不要虚构语料库先例；引用语料库作为证据时，先查询语料库。
• 将语料库示例用于培养审查直觉、识别风险，而不是替代对当前 diff 的阅读。
• 保留多语言评论原文。如果相关讨论使用中文或其他语言，证据中应原样保留，并使用用户的语言作答，除非用户另有要求。
• 避免盲目套用旧评论。用语料库示例来完善对当前改动的审查，而不是强行套用旧模板。

输出规范

对于常规评审，返回：

• 首先提供 PR 理解区块：变更摘要，以及标记出变更节点的 Mermaid 执行流程图；每张图后立即附上详细说明的文字讲解（参见 PR 理解图）。
• 接下来简要总结历史评审综合情况：说明扫描覆盖情况（scanned / matched / PRs），并概述基于详尽语料库扫描（工作流第 3 步）得出的该子系统反复出现的评审意见，这些意见是各项发现的依据。
• 接下来按严重程度排序列出发现，注明文件/行号；如有适用先例，明确说明其与上述综合情况的关联。
• 尚待解答的问题或假设。
• 测试或基准测试方面的缺口。
• 仅在列出发现后提供简短总结。

对于用户创建 PR 前的评审准备，返回：

• PR 理解区块（变更摘要和 Mermaid 执行流程图）
• 评审者可能关注的问题
• 缺失的测试或基准测试证据
• 建议的补丁清理工作
• 使用的语料库查询
• 适用时使用的跨技能证据

对于基于语料库的说明，需包含查询词，并总结匹配到的评审行为，避免大段照搬评论内容。

路径别名与语料库截止时间

语料库早于当前路径重构。查询受影响路径时，也需包含其历史所属路径：

当前差异范围	额外的 --path 查询
python/sglang/srt/arg_groups/**	python/sglang/srt/server_args.py
python/sglang/kernels/**	python/sglang/jit_kernel/、sgl-kernel/
.agents/skills/**	.claude/skills/

采集器没有增量/续传模式，并会覆盖全部三个输出文件。--end-year 默认为 2025：如需在未来进行完整重抓取，请显式传入 2026。此次更新未重新抓取或重新标注 2026-07-27 的语料库。 已保存的采集策略现在会记录排除登录项的模式。