---
name: triage
description: 对外部 issue 和 PR 进行分类、核实和必要的追问，补齐复现证据与验收条件，并整理成可由 agent 执行的说明。
disable-model-invocation: true
---

# 分诊

用一组分诊角色（标签）管理项目 issue 追踪器上的 issue，并在几个状态之间流转。

如果本仓库把外部 pull request 当作需求入口（见 issue 追踪器配置），分诊也覆盖这些 PR：**PR 就是附带代码的 issue**，使用相同的角色、相同的状态和相同的流转规则，差异之处在下文标注“对 PR”。按照追踪器配置，判断裸编号 `#42` 指的是 issue 还是 PR。

分诊期间发到 issue 追踪器上的每条评论或 issue，**开头都加上**这句声明：

```
> *本内容由 AI 在分诊过程中生成。*
```

## 参考文档

- [AGENT-BRIEF.md](AGENT-BRIEF.md)：如何编写能长期有效的 agent 简报
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)：`.out-of-scope/` 知识库如何运作

## 角色

两个**类别**角色：

- `bug`：功能出了问题
- `enhancement`：新功能或改进

五个**状态**角色：

- `needs-triage`：需要维护者评估
- `needs-info`：等待报告者补充信息
- `ready-for-agent`：描述完整，可以交给 agent 独立完成（AFK）
- `ready-for-human`：需要由人来实现
- `wontfix`：不会处理

对 PR，状态角色针对附带的代码理解：`ready-for-agent` 表示已附上简报，应由 agent 基于现有 diff 推进下一步；`ready-for-human` 表示可以由人合并。

每个分诊过的 issue 恰好带一个类别角色和一个状态角色。状态角色冲突时，先指出冲突并询问维护者，再做其他事。

这些是标准角色名，issue 追踪器中实际使用的标签文字可能不同。角色与标签的映射应该已经提供给你；如果没有，告诉用户运行 `/setup-dev-skills`。

状态流转：

- 未打标签的 issue 通常先进入 `needs-triage`。
- 从 `needs-triage` 可以转到 `needs-info`、`ready-for-agent`、`ready-for-human` 或 `wontfix`。
- 报告者回复后，`needs-info` 回到 `needs-triage`。
- 维护者可以随时手动指定状态；看起来不寻常的流转，先指出并询问。

## 调用

维护者运行 `/triage`，并用自然语言描述想做什么。理解请求后执行。例如：

- “给我看看需要我处理的”
- “看看 #42”（issue 或 PR）
- “把 #42 移到 ready-for-agent”
- “有哪些可以交给 agent 的？”

## 展示需要处理的 issue

查询 issue 追踪器，分三组展示，每组内最旧的在前：

1. **未打标签**：从未分诊过。
2. **`needs-triage`**：正在评估。
3. **`needs-info`，且上次分诊记录之后报告者有新回复**：需要重新评估。

PR 在分诊范围内时，把外部 PR 也放进这些分组，每行标注 `[PR]` 或 `[issue]`。汇总列表时只列*外部* PR（追踪器配置定义了谁算外部贡献者），协作者正在进行的 PR 不属于分诊工作。这个过滤只用于汇总列表；被明确点名的 PR，无论作者是谁都要分诊。

显示每组数量，每项一行摘要，让维护者选择。

## 分诊一个具体的 issue 或 PR

1. **收集上下文。** 完整阅读 issue 或 PR：正文、评论、标签、作者、日期；对 PR，还要阅读 diff。读取之前的分诊记录，不重复询问已经解决的问题。

   使用项目术语表中的词汇探索代码库，并遵守相关区域的 ADR。对代码库做两项检查：
   - **是否已实现**：按领域概念（而不只是请求中的字面词语）搜索被请求行为的现有实现，并报告你查了哪些地方。如果已经实现，按第 5 步以“已实现”关闭为 `wontfix`。
   - **是否曾被否决**：阅读 `.out-of-scope/*.md`，列出所有与本请求相似的记录。

2. **给出建议。** 告诉维护者你建议的类别和状态，以及理由，并附上与请求相关的简短代码库摘要（包括是否已实现）。等待指示。

3. **核实报告内容。** 追问之前，先确认报告的内容成立：
   - 对 bug，按报告者的步骤复现。
   - 对 PR，确认 diff 确实做到了它声称的事：检出代码，运行相关测试或命令。

   报告核实结果：已确认（附代码路径）、无法复现，或细节不足（强烈建议转为 `needs-info`）。经过核实的结论能让 agent 简报可靠得多。

4. **追问（如需要）。** 请求需要补充细节时，分别使用 `grilling` 和 `domain-modeling` skill，逐轮澄清需求。决策确定时，就地完善领域术语，更新 `CONTEXT.md` 和 ADR。

5. **应用结果：**
   - `ready-for-agent`：发布一条 agent 简报评论（见 [AGENT-BRIEF.md](AGENT-BRIEF.md)）。
   - `ready-for-human`：结构与 agent 简报相同，但写明为什么不能交给 agent（需要人工判断、需要外部访问权限、需要设计决策、需要手工测试）。
   - `needs-info`：发布分诊记录（模板见下文）。
   - `wontfix`：关闭 issue，评论内容取决于*原因*：
     - **已实现**：改动已经存在于代码库中。指出它在哪里；**不写入** `.out-of-scope/`，因为那个知识库记录的是*被否决*的请求，而不是已经实现的功能。
     - **否决（bug）**：礼貌说明原因，然后关闭。
     - **否决（enhancement）**：写入 `.out-of-scope/`，在评论中链接该文件，然后关闭（见 [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)）。
   - `needs-triage`：加上角色。有部分进展时，可以附一条评论。

## 快速修改状态

维护者说“把 #42 移到 ready-for-agent”时，信任维护者的判断，直接应用角色。先说明你要做的操作（角色变更、评论、关闭），然后执行，跳过追问。未经追问就移到 `ready-for-agent` 时，询问是否需要编写 agent 简报。

## needs-info 模板

```markdown
## 分诊记录

**目前已确认：**

- 要点 1
- 要点 2

**还需要你（@报告者）提供：**

- 问题 1
- 问题 2
```

追问中确认的所有内容都写进“目前已确认”，避免已完成的工作丢失。问题要具体、可操作，不要写“请提供更多信息”。

## 继续之前的分诊

issue 或 PR 上已有分诊记录时，先阅读记录，检查报告者是否回答了未决问题，向维护者说明更新后的整体情况，再继续。已经解决的问题不再重复询问。