triage

分流

通过一个由分流角色构成的小型状态机，在项目问题跟踪系统中推进问题。

分流期间，发布到问题跟踪系统的每条评论或问题都必须以此免责声明开头：

> *This was generated by AI during triage.*

参考文档

Agent 简报

Agent 简报是发布到问题中的结构化评论，为离线 Agent 提供实现修复或功能所需的一切信息，无需人工指导。一份好的 Agent 简报包含：

• 背景：此问题的重要性、相关背景、相关问题或 ADR 的链接
• 范围：需要修改的具体内容——不多也不少
• 验收标准：用于定义“完成”的可验证条件清单
• 相关文件：优先阅读的关键文件或模块（并非详尽列表，只需列出入口）
• 限制：Agent 绝不能做的事（例如，不要重构无关代码，不要更改公共 API）

简报应简洁。Agent 简报不是教程，而是一份规范。假设 Agent 能够阅读代码；不要在简报中复述整个代码库。

范围外知识库

.out-of-scope/ 目录是一个记录已拒绝功能的知识库。每个文件都是一篇简短的 Markdown 文档，说明某项增强为何被拒绝。处理方式如下：

• 关闭 wontfix 增强问题时，在 .out-of-scope/<slug>.md 中创建文件，记录请求和拒绝理由。
• 在问题的关闭评论中链接该文件，方便未来的报告者了解原因。
• 分流新问题时，阅读 .out-of-scope/*.md，并指出与当前问题相似的既往拒绝记录，避免重新争论已作出决定的问题。

每个 .out-of-scope/ 文件应包含：对功能请求的一句话概述、拒绝日期、理由（技术、产品或战略方面），以及原始问题的链接。

角色

两个类别角色：

• bug — 某项功能无法正常工作
• enhancement — 新功能或改进

五个状态角色：

• needs-triage — 维护者需要进行评估
• needs-info — 等待报告者提供更多信息
• ready-for-agent — 规格完整，可交由离线 Agent 处理
• ready-for-human — 需要人工实现
• wontfix — 不会处理

每个已分流的问题都应恰好有一个类别角色和一个状态角色。如果状态角色冲突，请标记冲突，并在进行其他操作前询问维护者。

这些是规范角色名称——问题跟踪系统中实际使用的标签字符串可能有所不同。请查看项目的 AGENTS.md 或现有问题标签，了解对应关系。

状态转换：未加标签的问题通常先进入 needs-triage；之后可转为 needs-info、ready-for-agent、ready-for-human 或 wontfix。报告者回复后，needs-info 会回到 needs-triage。维护者可以随时覆盖状态——遇到看起来不寻常的转换时，请标记出来并先行询问。

调用方式

维护者通过调用 /triage 并用自然语言描述需求。理解请求并执行操作。例如：

• “显示所有需要我关注的问题”
• “我们来看看 #42”
• “将 #42 转为 ready-for-agent”
• “有哪些问题已准备好让 Agent 处理？”

显示需要关注的内容

查询问题跟踪系统，并按时间从早到晚列出三个类别：

1. 未加标签 — 从未分流。
2. needs-triage — 正在评估。
3. needs-info 且报告者在上次分流备注后有新活动 — 需要重新评估。

显示数量，并为每个问题提供一行摘要。由维护者选择。

对特定问题进行分诊

1. 收集上下文。 阅读完整的问题（正文、评论、标签、报告者、日期）。解析之前的分诊记录，避免重复询问已解决的问题。使用项目的领域术语表探索代码库，并遵循相关领域的 ADR。阅读 .out-of-scope/*.md，并指出与此问题类似的任何既往拒绝记录。

2. 提出建议。 告知维护者问题类别和状态建议，并说明理由，同时简要总结与该问题相关的代码库情况。等待指示。

3. 复现（仅限 Bug）。 在追问之前，先尝试复现：阅读报告者提供的步骤、追踪相关代码、运行测试或命令。报告结果——成功复现及对应代码路径、复现失败，或信息不足（这强烈表明需要补充信息）。确认复现能让 Agent 简报更有说服力。

4. 追问（如有需要）。 如果问题需要进一步明确，且有追问技能可用，请使用该技能：如果已安装 /grill-me，则调用它；如果没有可用的追问技能，则直接提出探究性问题。

5. 落实结果：

   • ready-for-agent — 发布 Agent 简报评论（参见上文的 Agent 简报部分）。
   • ready-for-human — 使用与 Agent 简报相同的结构，但说明为何无法委派（需要判断、外部访问、设计决策或手动测试）。
   • needs-info — 发布分诊记录（使用下方模板）。
   • wontfix（Bug）— 礼貌说明原因，然后关闭。
   • wontfix（增强功能）— 写入 .out-of-scope/，在评论中链接该文件，然后关闭（参见上文的范围外知识库部分）。
   • needs-triage — 应用该角色。如有部分进展，可选择发布评论。

快速状态覆盖

如果维护者说“将 #42 移至 ready-for-agent”，请信任他们并直接应用该角色。确认你将要执行的操作（更改角色、发表评论、关闭问题），然后执行。跳过追问。如果要在没有追问会话的情况下移至 ready-for-agent，请询问他们是否希望撰写 Agent 简报。

需要补充信息模板

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1
- question 2

将追问过程中确认的所有内容记录在“已确认事项”下，以免丢失。问题必须具体且可执行，不要只说“请提供更多信息”。

恢复之前的会话

如果问题中已有之前的分诊记录，请阅读这些记录，检查报告者是否已回答任何待解决的问题，并在继续前提供最新情况。不要重复询问已解决的问题。