执行摘要

• 一句话：修复并扩展 PR/Issue 自动打标签规则，新增防回归校验
• 推荐动作：值得精读，尤其是仓库维护者和 CI 负责人。本 PR 是“自动化配置治理”的范例：用数据（PR/Issue 数量统计）驱动规则审计，用可执行校验（check_label_rules.py）封堵静默失效，并在 review 中展示了对“标签语义准确性”（new-model 改为 added-files）与“维护者可扩展性”（labels.md 的三要素）的双重考量。重点学习点：(1) files= 与 files~= 的语义差异及锚定写法；(2) 用 added-files 表达“新增”语义而非“触碰”语义；(3) 用 pre-commit 对 YAML 配置做活校验——这是防止配置腐化的通用思路。对于一线工程师，该 PR 不涉及推理代码，可按需浏览。

功能与动机

PR body 明确指出：现有自动打标签规则与实际仓库脱节——deepseek 规则漏掉 vllm/models/deepseek_v4/ 下 64/99 的 PR；speculative-decoding 漏掉 6 个月内 94 个 PR 的 vllm/v1/worker/gpu/spec_decode/ 子树；4 条规则因 files= 误用正则语法或双反斜杠永远无法触发，13 条指向已移动或删除的文件。Issue 侧自动打标签仅覆盖 62 个标签中的 6 个。此外 new-model 规则在 25 个最近 PR 中误标了 15 个（含删除模型、registry typo 的 PR），而 GitHub 对不存在的标签会静默跳过——New Model 模板引用的 new-model 标签名不匹配导致 5 个月无人察觉的漏标。作者还强调：Mergify 静默忽略永远无法匹配的条件，规则失效不会报错，因此需要引入主动校验机制。

实现拆解

该 PR 的变更入口是 .github/mergify.yml 的规则审计与重写，核心配套是新增的 tools/pre_commit/check_label_rules.py 防回归脚本。实现过程按以下步骤拆解：

1. 修复失效的 Mergify 路径规则（.github/mergify.yml）：为 deepseek 规则补充 files~=^vllm/models/deepseek.*/ 分支，覆盖新模型目录；为 llama 移除已不存在的 vllm/reasoning/.*llama.* 等条件；gpt-oss/harmony 规则重指向 Rust 前端 rust/src/chat/src/.*/harmony/；将 files= 误用正则的 4 条条件改为 files~= 或删除。
2. 重构 new-model 规则：原来用 files（精确匹配）触发，只要 PR 触碰模型文件和 registry.py 就命中，导致删除模型、重构、typo 修复都被贴标签。改为 added-files 语义——只有“新增模型文件 + 触碰 registry.py”或“新增 vllm/models/(?!common/)[^/]+/__init__.py 顶级包”才命中，这是响应 mgoin review 的“保留但做准”的折中方案。
3. 新增标签与规则：新增 scheduler、kv-cache-manager、glm、minimax、inkling 等 PR 标签规则；glm 规则锚定文件名开头避免 midashenglm.py 误匹配；dflash 规则按 benchislett 反馈扩展覆盖 dspark 子树。
4. 扩展 Issue 自动打标签（.github/workflows/issue_autolabel.yml，+153 行）：从 6 个标签扩展到 31 个，覆盖模型（deepseek、llama、qwen、glm 等）、硬件后端（nvidia、tpu）和子系统（scheduler、kv-cache-manager、speculative-decoding、tool-calling 等）。刻意只匹配标题而不匹配 body，因为 body 常携带 collect_env 输出等环境信息会误导标签。
5. 新增防回归校验与文档：新增 tools/pre_commit/check_label_rules.py，遍历 mergify.yml 中所有 files=/files~= 条件并用 git ls-files 验证至少匹配一个真实文件，匹配不到即报错退出；在 .pre-commit-config.yaml 注册为 check-label-rules hook（仅当 mergify.yml 变更时运行）；新增 docs/contributing/labels.md 说明标签体系、新增标签的三要素和编写条件的最佳实践。
6. 删除 New Model Issue 模板（.github/ISSUE_TEMPLATE/600-new-model.yml，-40 行）：该模板引用不存在的 new model 标签（实际标签名为 new-model），GitHub 静默跳过导致请求一直漏标；且 2025 年 155 个 Issue 降至 2026 年仅 30 个，模型支持已转为计划性工作，故整体删除，相关请求导向 Feature Request。
7. 测试与验证：无单元测试文件，但 PR body 给出验证结果——check_label_rules.py 对 6430 个跟踪文件、44 条规则、154 个文件条件全部匹配，注入不存在路径时以退出码 1 报错；Issue 规则在 600 个真实 Issue 上回放，43% 至少获得一个标签，现有规则与手工标签一致（kimi 35/31、rocm 34/33、k3 27/26）；pre-commit ruff 检查与格式化通过。

关键文件：

• tools/pre_commit/check_label_rules.py（模块 预提交校验；类别 source；类型 dependency-wiring；符号 tracked_files, file_conditions, check, main）: 新增的防回归校验脚本，是本次变更的核心机制保障：遍历 mergify.yml 中所有文件类条件，验证每个条件至少匹配 git ls-files 中的一个真实文件，否则报错退出。它把“Mergify 静默忽略失效条件”这一系统性风险转化为 pre-commit 的硬性检查，并已在开发过程中抓到两个自身 bug。
• .github/mergify.yml（模块 Mergify配置；类别 infra；类型 infrastructure）: PR 打标签规则的主战场：修复 deepseek/speculative-decoding/llama/harmony 等失效规则，重构 new-model 为 added-files 语义，新增 glm/minimax/scheduler 等标签规则并扩展 dflash 覆盖 dspark。这是变更的核心业务配置。
• .github/workflows/issue_autolabel.yml（模块 Issue标签；类别 infra；类型 infrastructure）: Issue 自动打标签从 6 个扩展到 31 个标签，覆盖模型、硬件和子系统；明确只在标题中匹配关键词，避免 collect_env 等正文噪音造成误标，是 Issue 侧治理的主要载体。
• .github/ISSUE_TEMPLATE/600-new-model.yml（模块 Issue模板；类别 infra；类型 deletion）: 删除的 New Model 模板：因标签名（new model vs new-model）不匹配被 GitHub 静默跳过 5 个月，且使用量从 155 降至 30，认定模板已无价值，删除后新模型请求走向 Feature Request。
• docs/contributing/labels.md（模块 贡献文档；类别 docs；类型 documentation）: 新增标签体系文档，记录三大自动打标签系统、新增标签的三要素（受众/负责人/规则）与路径条件最佳实践，为后续维护提供依据。
• .pre-commit-config.yaml（模块 预提交配置；类别 config；类型 configuration）: 注册 check-label-rules 到 pre-commit，仅在 .github/mergify.yml 变更时触发，并声明 PyYAML 与 regex 依赖，是防回归机制能落地执行的关键配置。

关键符号：tracked_files, file_conditions, check, main

关键源码片段

.github/workflows/issue_autolabel.yml

Issue 自动打标签从 6 个扩展到 31 个标签，覆盖模型、硬件和子系统；明确只在标题中匹配关键词，避免 collect_env 等正文噪音造成误标，是 Issue 侧治理的主要载体。

// issue_autolabel.yml 中 labels 配置的关键片段（整理重排）：
// 设计原则：只匹配标题，不匹配正文。
// Issue body 常携带 collect_env 输出、traceback 和配置，
// 会点名无关的硬件、库和模型，匹配正文会打到 reporter 的环境而非主题。
{
  // 模型标签：关键词用边界匹配，避免长词内触发。
  deepseek: {
    keywords: [{ term: "DeepSeek", searchIn: "title" }],
  },
  DSv4: {
    keywords: [{ term: "DSv4", searchIn: "title" }],
    substrings: [{ term: "deepseek-v4", searchIn: "title" }],
  },
  glm: {
    keywords: [{ term: "GLM", searchIn: "title" }, { term: "ChatGLM", searchIn: "title" }],
  },
  minimax: {
    substrings: [{ term: "minimax", searchIn: "title" }],
  },
​
  // 子系统标签：多词短语用 substrings，避免边界匹配漏掉常见变体。
  "speculative-decoding": {
    keywords: [{ term: "eagle", searchIn: "title" }, { term: "medusa", searchIn: "title" }],
    substrings: [
      { term: "speculative decoding", searchIn: "title" },
      { term: "draft model", searchIn: "title" },
    ],
  },
  "kv-connector": {
    keywords: [{ term: "NIXL", searchIn: "title" }, { term: "LMCache", searchIn: "title" }],
    substrings: [{ term: "KV transfer", searchIn: "title" }, { term: "disaggregat", searchIn: "title" }],
  },
}

评论区精华

review 中核心讨论围绕 new-model 标签和 dflash/dspark 归属展开：

• mgoin 主张保留 new-model："I think this is still useful to keep, we should use the new models folder too though. Some rule for if you are adding a new top-level folder to vllm/models/"。作者回应称旧规则用 files 匹配导致删除模型的 PR 也被贴标签，已改为 added-files 并采纳 mgoin 建议增加顶级目录条件。结论：规则保留并改为按新增文件触发。
• benchislett 建议将 dspark 并入 dflash 标签：给出多行 suggestion 覆盖 vllm/v1/worker/gpu/spec_decode/dspark/、vllm/models/deepseek_v4/nvidia/dspark.py 等路径。作者确认后先应用了建议，随后追问 K3 侧文件（vllm/models/kimi_k3/nvidia/dspark_mla.py、vllm/transformers_utils/configs/k3_dspark.py）是否也要纳入，最终在后续提交中补上，并在 PR body 说明 "This also folds dflash and dspark under the umbrella label"。结论：dspark 统一归入 dflash 标签，覆盖 DSv4 与 K3。

• 评审流程：njhill 与 tjtanaa 均 APPROVED，njhill 触发 Buildkite CI 验证。作者在 Issue 评论中列出 aardvark、codex、claude-code-assisted 等 6 个拟退役标签征求反馈，并强调这与本 PR 无关、不阻塞合并。

  • new-model 标签去留与规则准确性 (design): 保留 new-model 标签，规则从 files 改为 added-files，同时覆盖 vllm/model_executor/models/ 下新增文件与 vllm/models/ 下新增顶级包两种情形。
  • dspark 是否并入 dflash 标签 (design): DFlash 与 DSpark 视为同一工作流，统一归入 dflash 标签，覆盖 DSv4 与 K3 两侧文件。
  • 拟退役标签征求反馈 (question): 等待更多反馈，退役标签的决定独立于本 PR，不阻塞合并。

风险与影响

• 风险：主要风险集中在标签配置的准确性、合并顺序和工具健壮性上：

• 新标签未创建导致 Mergify 报错（PR body 明确提示）：Mergify 对不存在的标签会报错，而 scheduler、kv-cache-manager、glm、minimax、inkling 这 5 个标签的创建是合并前置条件，不能由 PR 本身完成。作者在合并前已确认创建完毕，但若未来有人复用该模式需留意时序。

• 正则规则误匹配/漏匹配：glm 规则刻意锚定文件开头（避免 midashenglm.py），但 44 条规则、154 个文件条件下仍存在类似“名字包含名字”的隐患（如 cuda 与 requirements/cuda.txt 的教训），新模型目录 vllm/models// 仍在演进，规则需要持续维护。
• check_label_rules.py 的覆盖盲区：脚本显式排除 removed-files 属性和以 - 开头的否定条件；若未来有人用 removed-files 写正向规则或改变 YAML 结构，校验可能失效。此外脚本依赖 git ls-files，在 submodule 或非 git 工作区中无法运行。
• 删除模板的连带影响：600-new-model.yml 删除后，新模型请求全部路由到 Feature Request 模板，可能带来 Issue 分类习惯的变化；且 new-model 标签仍保留在 917 个 PR 和 304 个 Issue 上，无人再负责打该标签，未来需要单独决策标签去留。
• Issue 标签仅匹配标题：作者明确这是有意设计（避免 collect_env 干扰），但代价是标题未提及关键词但内容相关的 Issue 会漏标，需要人工兜底。

• 影响：影响集中在仓库协作流程而非运行时行为：

• 对维护者与贡献者：PR 和 Issue 的自动标签覆盖从 6 个标签扩展到 31 个，显著提高 issue/PR 检索与分类效率；新增标签规则让 deepseek、glm、scheduler、dflash 等主题的 PR 能被自动归组，减少手工打标签负担。

• 对 CI 体系：新增 pre-commit hook 使 mergify.yml 的每次变更都会自动校验规则是否仍匹配真实文件树，从机制上杜绝“规则静默失效”问题，降低未来维护成本。
• 对 Issue 流程：删除了几乎无人使用且已失效 5 个月的 New Model 模板，新模型请求统一走 Feature Request，等待人工打 new-model 标签（目前无人负责），存在短期标签覆盖空缺。
• 对文档体系：新增 labels.md 提供“新增标签三要素”（受众、负责人、规则）和路径匹配最佳实践，帮助后续贡献者正确维护标签。
• 无运行时影响：PR body 明确声明不涉及推理、模型输出、精度或 serving，影响面严格限定在 GitHub 协作与 CI 配置范畴。
• 风险标记：新标签需提前创建, 正则路径匹配易失效, 配置校验覆盖盲区, 依赖 git 工作区, 标签语义需人工维护

关联脉络

• PR #50082 [Bugfix] Add Kimi K3 MoE support to benchmark_moe.py: 涉及 kimi/K3 模型文件路径（vllm/models/kimi_k3/），与本 PR 中 dflash 规则扩展覆盖 K3 dspark 文件直接相关。
• PR #52987 Revert "[Kernel] Gemma-4 FA4 FP8 Kernel": 涉及 vllm/v1/worker/gpu/spec_decode/gemma4/speculator.py，位于本 PR 修复的 speculative-decoding 标签漏标的 Model Runner V2 子树内。
• PR #52281 [ROCm] Give EngineCore cleanup grace after request abort: 涉及 vllm/v1/engine 与 v1 相关路径，作为标签规则覆盖范围验证的典型 PR 之一；同时其关闭逻辑与本 PR 的 CI 稳定性主题同属协作基础设施治理。