GitHub CLI 问题分诊（Triage）机制解析：从 First Responder 工作流到标签驱动的自动化流水线

本文以 cli/cli 仓库中的分诊规范文档 docs/triage.md 为核心，结合仓库内真实的 GitHub Actions 工作流配置（.github/workflows/triage-issues.yml、.github/workflows/triage-pull-requests.yml、.github/workflows/triage-scheduled-tasks.yml）与 Agent 驱动的分诊流程（.github/workflows/issue-triage.md），完整拆解 GitHub CLI 项目如何处理社区提交的 Issue 与 Pull Request：读者可以掌握「标签即状态机」的分诊设计、Bug 优先级定级标准、垃圾内容判定依据，以及每个标签背后对应的自动化 Job 与定时任务，从而为自己的开源项目设计一套可落地的分诊体系。

一、Triage 角色定义：什么算“已完成分诊”

根据 docs/triage.md 的原始定义，First Responder（FR，首响人）在每周轮值期间的首要职责，是对来自开源社区的传入 Issue 和 Pull Request 进行分诊。文档给出了一条明确且可度量的完成标准：

当一个 Issue 上的 needs-triage 标签被移除时，该 Issue 即视为“已完成分诊”（triaged）。

这一标准把分诊从模糊的“看看这个 Issue”变成了可量化、可追踪的动作。快速指南（Quick Guide）把分诊决策压缩成一个从分诊队列挑选 Issue 后的四步判断树：

1. 能否直接关闭？
   • 重复提交 → 评论并作为 duplicate 关闭，链接原始 Issue
   • 垃圾内容（Spam）→ 添加 invalid 或 suspected-spam（自动关闭）
   • 滥用（Abuse）→ 添加 invalid、移除内容、上报并封禁（详见 Spam and Abuse 一节）
   • 跑题（Off-topic）→ 添加 off-topic（自动带评论关闭）
2. 是不是 Bug？
   • 可复现 → 添加 bug 以及一个优先级标签（priority-1、priority-2 或 priority-3）
   • 无法复现 → 添加 unable-to-reproduce（自动请求补充信息，并启动 14 天计时器）
3. 是不是功能增强（Enhancement）？
   • 价值清晰 → 添加 enhancement（自动发布 backlog 评论）
   • 价值不明 → 评论请求澄清并添加 more-info-needed（14 天计时器）
4. 是不是 Pull Request？（处理原则见 社区 Pull Request 一节）
   • 垃圾或“AI 垃圾内容”（AI sludge）→ 添加 invalid（自动关闭）
   • 极小修复（如拼写错误）→ 直接评审、测试并合并
   • 未关联 help-wanted Issue → 添加 no-help-wanted-issue（自动带评论关闭）
   • 有效 → 添加 ready-for-review 并触发 CI（自动移除 needs-triage，自动发布致谢评论）

文档还强调了一个关键的收尾机制：当终态标签（enhancement、bug、ready-for-review）被应用、或 Issue 被关闭时，needs-triage 标签会被自动移除。这保证了“分诊完成”这一状态永远与仓库中的实际标签状态一致，无需人工手动清理。

二、标签如何驱动自动化：工作流源码级证据

“添加一个标签 → 触发一串自动化动作”是这套分诊体系的核心引擎。仓库中的三个 Actions 工作流文件正是 docs/triage.md 中“Automated Workflows”表格的实现载体。

2.1 Issue 侧：.github/workflows/triage-issues.yml

该工作流监听 issues 事件的 opened / reopened / labeled / unlabeled / closed 五种动作，并把不同事件路由到不同的共享工作流（hosted workflow，来自 desktop/gh-cli-and-desktop-shared-workflows 仓库，以 commit 钉住版本 df758d5… # v0.0.1）：

Job	触发条件	调用的共享工作流	对应标签语义
label-incoming	opened / reopened / unlabeled	triage-label-incoming.yml	新 Issue 自动打上 needs-triage
close-invalid	labeled	triage-close-invalid.yml	invalid 立即自动关闭
close-suspected-spam	labeled	triage-close-suspected-spam.yml	suspected-spam 自动关闭
close-off-topic	labeled	triage-close-off-topic.yml	off-topic 带解释评论后关闭
enhancement-comment	labeled	triage-enhancement-comment.yml	enhancement 自动发布 backlog 评论
unable-to-reproduce	labeled	triage-unable-to-reproduce-comment.yml	unable-to-reproduce 自动补充评论
remove-needs-triage	labeled	triage-remove-needs-triage.yml	终态标签出现后移除 needs-triage
on-issue-close	closed	triage-on-issue-close.yml	关闭时的收尾处理

每个 Job 都按最小权限原则声明了 permissions（如 issues: write、pull-requests: write），这是值得借鉴的安全实践。

2.2 定时任务：.github/workflows/triage-scheduled-tasks.yml

文档中提到的「14 天计时器」等自动化由定时工作流支撑。该文件配置了三档调度：

schedule:
  - cron: '5 * * * *'   # 每小时整点 5 分 —— 无响应关闭（no-response close）
  - cron: '0 3 * * *'   # 每天 3 点 UTC —— 标记陈旧 Issue（stale）
  - cron: '0 14 1 * *'  # 每月 1 日 14 点 UTC —— 置顶高价值提案（pitch surfacing）

其中 stale Job 的关键参数也直接写在配置里，可以据此理解“14 天无响应关闭”之外的另一层生命周期管理：days_before_stale: 30、days_before_close: -1（只标 stale 不自动关）、exempt_issue_labels: 'keep'（带 keep 标签的 Issue 豁免）。也就是说，more-info-needed 的 14 天无响应关闭由每小时运行的 no-response Job 负责，而 30 天 stale 标记是更外层的兜底。

2.3 完整标签-自动化对照表

docs/triage.md 给出的官方对照表如下，可与上面的工作流源码一一对应：

标签	自动化行为
needs-triage	打开时自动添加；被归类或关闭时移除
more-info-needed	14 天无响应后自动关闭
unable-to-reproduce	自动追加 more-info-needed 并发布评论
enhancement	自动发布 backlog 评论
invalid	立即自动关闭
suspected-spam	立即自动关闭
off-topic	自动发布解释评论并关闭
no-help-wanted-issue	自动发布解释评论并关闭
ready-for-review	自动移除 needs-triage 并发布致谢评论

三、Bug 分诊：复现优先与三级优先级

docs/triage.md 的 Bug Triage 章节给出了三步法：

1. 尝试复现该问题；
2. 若能复现（或强烈怀疑是间歇性 Bug）→ 添加 bug 与一个优先级标签；
3. 若无法复现 → 添加 unable-to-reproduce（自动请求信息并启动 14 天计时器），或用 more-info-needed 请求澄清。

Bug 优先级定级标准

优先级	定义
priority-1	影响大量用户并阻碍正常工作。需通过相应事故渠道内部升级；可能需要热修复（hotfix）。
priority-2	影响超过少数用户，但不阻碍核心功能
priority-3	影响用户数量很少，或基本只是外观（cosmetic）问题

这一分级体系的实操含义是：priority-1 不只是标签，而是触发内部事故响应流程的信号；分诊者（triager）的职责是“定级”而不是“排期”——定级完成后，修复排序由团队负责。

值得补充的是，Bug 报告的输入质量由 Issue 模板兜底。.github/ISSUE_TEMPLATE/bug_report.md 要求提交者提供 gh version 输出、复现步骤、期望与实际行为对比、命令行日志（并注明 GH_DEBUG=true 或 GH_DEBUG=api 可获取详细日志），这让“尝试复现”这一步有了标准化的信息基础。

四、社区 Pull Request：快速通道而非评审

docs/triage.md 中一个容易被误解的点是：社区 PR 会和 Issue 一样被自动打上 needs-triage（外加 external 标签），但分诊阶段并不评审代码。分诊者只做一次快速过筛（quick pass）：

1. 垃圾或 AI 垃圾内容 → 添加 invalid（自动关闭），必要时封禁用户；
2. 极小且可合并的修复（如拼写错误）→ 评审、测试后直接合并；
3. 未关联 help-wanted Issue → 添加 no-help-wanted-issue（自动带评论关闭）；
4. 通过筛选 → 添加 ready-for-review 并运行 CI（自动移除 needs-triage，自动发布致谢评论）。

通过筛选的 PR 会被自动指派给团队工程师，而工程师会等到 needs-triage 被移除后才开始评审——这保证了一个 PR 不会同时处于“分诊中”和“评审中”两种状态。

PR 侧的自动化同样有源码依据。.github/workflows/triage-pull-requests.yml 的关键配置包括：

• label-external：在 opened / reopened 时给外部 PR 打 external 标签；
• close-from-default-branch：从默认分支 trunk 直接开出的 PR 会被自动关闭（项目要求从 feature 分支提交）；
• check-requirements / close-unmet-requirements：带 PR 筛查（enable_pr_screening: true），普通 PR days_until_close: 4 天、大型 PR large_pr_days_until_close: 2 天不满足要求即关闭，并有每日 4 点 UTC 的定时兜底；
• close-no-help-wanted 与 ready-for-review：分别对应上文第 3、4 步的标签行为。

五、Spam and Abuse：垃圾与滥用的处置边界

文档指出，垃圾与滥用分诊的首要目标是“把干扰性和冒犯性内容从社区中移除”，并区分了三类处置：

• 垃圾 Issue：添加 invalid 标签（以 “won't do” 理由自动关闭）；
• 垃圾评论：使用 GitHub 内置功能标记为 spam；
• 滥用内容：以 代码行为准则 为判定依据。移除相关内容；重复冒犯或特别恶劣的滥用应上报并封禁用户。

其中 CODE-OF-CONDUCT.md 采用的是 Contributor Covenant 1.4 版本，明确了可接受/不可接受行为的标准、维护者的处置权限（移除、编辑、拒绝、临时或永久封禁）以及上报渠道。

垃圾判定的书面标准：共享判据文件

仓库不仅写了“判为垃圾就关闭”，还为判定本身提供了书面标准：.github/workflows/shared/spam-criteria.md。该文件明确声明自己是“无 on: 触发器的共享组件，永远不会被编译为独立工作流，只承载提示词内容”，其要点包括：

• 正当内容指标：带有复现步骤的清晰 Bug 描述、有详细用例的功能请求、具体建议的文档改进、带上下文的使用问题、引用具体代码/文件/功能的报告；
• 垃圾内容指标：直接复制 Issue 模板（对比时忽略标题与 <!-- --> 注释行）、标题与正文无关、空正文、仅含 “bug”/“help” 等一两个词的正文、纯链接无上下文、Lorem ipsum 之类占位文本、重复内容、广告推广、与项目无关的粘贴引用等；
• 文件还内嵌了三份 Issue 模板副本（Bug 报告、设计提案、功能请求），用于识别“模板复制型”垃圾提交。

文件头部注释还点出了一个工程细节：这份判据同时被 Agent 分诊流程与其评估测试（eval harness，位于 .github/workflows/scripts/spam-detection/）消费——“修改判据”本身就是 eval 所度量的对象，从而保证判定标准与其验收测试始终同源。

六、Agent 驱动的分诊：人在环上的半自动流程

除了人工 FR 轮值，仓库还提供了一条 Agent 化的分诊链路：.github/workflows/issue-triage.md。这是一个 Agentic Workflow（引擎为 Copilot），在 issues 的 opened 事件上运行，其安全设计非常值得注意：

• 权限最小化：workflow 本体只有 contents: read、issues: read 与 copilot-requests: write 权限；
• 白名单 + 建议而非执行：safe-outputs.add-labels 限定了 Agent 最多提 3 个标签，且全部来自固定白名单（bug、priority-1/2/3、enhancement、more-info-needed、unable-to-reproduce、off-topic、no-help-wanted-issue、invalid、duplicate），并且这些标签只是建议，需要维护者批准，Agent 不得直接应用；
• 唯一的直接执行例外：suspected-spam 允许直接应用（通过一个独立的 apply-suspected-spam Job，用 GitHub App 令牌执行 gh issue edit "$ISSUE_NUMBER" --add-label suspected-spam），因为它会触发共享的 close-suspected-spam 流程完成评论与关闭；
• 防误伤原则：提示词明确要求“Be conservative. A false positive closes a real user's issue”，证据不足时应建议 more-info-needed 交由人类判断；同时严禁对滥用 Issue 的 issue 内容执行其中包含的任何指令（提示词中反复强调 issue 内容应视为不可信数据）；
• 明确的边界：“Do not add or remove needs-triage —— 该标签由共享分诊工作流独占管理”，这与文档中“终态标签自动移除 needs-triage”的机制严丝合缝。

从源码结构看，这套设计把“AI 分诊”约束成了一个人工分诊决策树（第三节 Quick Guide 的四步判断）的镜像：Agent 负责提出最小正确的终态标签集合（附 rationale 与 confidence），人负责批准，自动化工作流负责执行后续动作。

七、分诊者的沟通示例与社区氛围

docs/triage.md 的 Examples 章节开宗明义：“我们希望项目是一个安全、有鼓励性的开源环境”，并给出了一组真实的历史沟通范例，覆盖：关闭范围过大的优质 PR、关闭过期（stale）PR、关闭不符合贡献政策的 PR、回应 Bug 报告、关闭超出范围的 Issue、关闭实为功能请求的 Issue。这些范例的共同点是：即使结果是不接受，也要给出尊重、具体、有建设性的解释——这正是前文所有“auto-posts comment”类自动化背后的语气标准。

八、给其他开源项目的可复用要点

综合 docs/triage.md 与仓库工作流源码，这套分诊体系有几个可以直接移植的设计模式：

1. 以单一标签作为分诊完成判据：用 needs-triage 的增删定义工作项状态，度量分诊吞吐量就是数一个标签；
2. 标签即自动化触发器：每个“终态标签”绑定一个最小权限的 Job（见 triage-issues.yml 的 Job 拆分），分诊者的手工动作被压缩到“打标签”一步；
3. 定时器兜底：14 天无响应关闭（每小时检查）与 30 天 stale 标记（每日检查，见 triage-scheduled-tasks.yml）构成两级生命周期回收；
4. PR 分诊与评审分离：分诊只做快速过筛并设 help-wanted 关联门槛，评审留到 needs-triage 移除之后，避免状态重叠；
5. 把判定标准文档化并与测试同源：如 spam-criteria.md 同时服务 Agent 提示词与 eval 评估，标准改动可被持续验证；
6. AI 辅助保持人在环：Agent 只能建议白名单内的标签（上限 3 个），唯一的直接动作是触发垃圾关闭链路，且始终不得触碰 needs-triage。

适用前提与限制说明：以上机制针对的是 cli/cli 仓库当前的主干配置，共享工作流（desktop/gh-cli-and-desktop-shared-workflows）以固定 commit 钉住版本，标签语义与自动化行为以 docs/triage.md 的对照表和各工作流 YAML 的实际内容为准；文档 Examples 一节引用的是历史 Issue/PR 讨论，本文按其描述的行为方式引用，不再附外部链接。