AGENT SKILL

triage

让议题与外部 PR 走过一台由分诊角色组成的状态机:分类、核实、必要时盘问,最后写出代理可以直接上手的简报。

License 许可
MIT
最近更新
2026-11-14
Stars
★ 363
Forks
33

01 前言 Front Matter

name
triage
description
让议题与外部 PR 走过一台由分诊角色组成的状态机:分类、核实、必要时盘问,最后写出代理可以直接上手的简报。
disable-model-invocation
true

02 资源文件 2

03 SKILL.md 正文

分诊

让项目议题跟踪器上的议题走过一台由分诊角色构成的小状态机。

如果这个仓库把外部 PR 也当作一种请求入口(见 issue-tracker 配置),分诊也要管它们:一个 PR 就是一份附带代码的议题,用的是同一套角色、同一批状态、同一台状态机,只有少数差异,下面用「对 PR 而言」标出。遇到一个单独的 #42,按跟踪器配置判断它指议题还是 PR。

分诊期间发到议题跟踪器上的每一条评论或议题,开头必须是这段免责声明:

> *This was generated by AI during triage.*

参考文档

角色

两个类别角色:

  • bug:有东西坏了
  • enhancement:新功能或改进

五个状态角色:

  • needs-triage:需要维护者评估
  • needs-info:在等报告者补充信息
  • ready-for-agent:已经完全写清楚,可以交给 AFK 代理
  • ready-for-human:需要人来实现
  • wontfix:不会被处理

对 PR 而言,同一批状态要对着所附的代码来读:ready-for-agent 表示已经附上简报、应当由代理对这份 diff 走下一步;ready-for-human 表示已经可以由人来合并。

每一份分诊过的议题都应当恰好带一个类别角色和一个状态角色。如果状态角色互相冲突,先把冲突标出来,问过维护者之后再做别的。

这些是角色的规范名称。议题跟踪器里实际使用的标签字符串可能不同。这份对照关系应该已经提供给你了。如果没有,请告诉用户运行 /setup-matt-pocock-skills。

状态流转:没有标签的议题通常先进入 needs-triage;从那里出发,它可以走到 needs-info、ready-for-agent、ready-for-human 或 wontfix。报告者回复之后,needs-info 回到 needs-triage。维护者随时可以覆盖这些判断;遇到看起来不寻常的流转,先标出来、问过之后再做。

调用方式

维护者调用 /triage,用自然语言说明他们想要什么。理解这个请求并动手。例子:

  • 「给我看看有什么需要我处理的」
  • 「我们来看看 #42」(议题或 PR)
  • 「把 #42 移到 ready-for-agent」
  • 「有什么是代理可以接手的?」

展示需要关注的事项

查询议题跟踪器,分成三堆呈现,最老的排在前面:

  1. 没有标签:从未分诊过。
  2. needs-triage:正在评估中。
  3. 自上一条分诊备注以来报告者有活动的 needs-info:需要重新评估。

当 PR 也在范围内时,把外部 PR 也放进这三堆,并给每一行标上 [PR] 或 [issue]。发现环节只会挑出外部 PR(谁算外部由跟踪器配置定义),所以协作者正在推进的 PR 不算分诊工作。这个过滤只用于发现环节;被明确点名的 PR,无论作者是谁都要分诊。

给出每一组的数量,以及每一项的一行摘要。让维护者来挑。

分诊某个具体的议题或 PR

  1. 收集上下文。 读完整的议题或 PR(正文、评论、标签、作者、日期;如果是 PR,还要读 diff)。解析此前的分诊备注,避免重复问已经解决的问题。用项目的领域词汇表探索代码库,并遵守该领域的 ADR。对代码库跑两项检查:(a) 重复实现:按领域概念(而不只是请求里的措辞)搜索所要求的行为是否已经有实现,并报告你找过哪些地方。如果找到,它就是一个已经实现的 wontfix(见第 5 步)。(b) 先前已被否决:读 .out-of-scope/*.md,把任何与这个请求相似的条目摆出来。

  2. 给出建议。 告诉维护者你建议的类别与状态并说明理由,另外附一小段与请求相关的代码库概况(包括它是否已经实现)。等待指示。

  3. 核实说法。 在任何盘问之前,先检查这个说法站不站得住。如果是 bug,按报告者的步骤复现它。如果是 PR,确认这份 diff 确实做到了它声称的事:把它检出,跑相关的测试或命令。报告结果:核实成立(附代码路径)、核实不成立,还是细节不足(这是要 needs-info 的强信号)。核实通过能让代理简报有力得多。

  4. 盘问(如果需要)。 如果这个请求还需要展开,就调用 Skill 工具两次,分别传入 "grilling" 和 "domain-modeling",一轮一轮地问,把它盘问成型;每当有决定定下来,就顺手打磨领域术语、就地更新 GLOSSARY.md/ADR。

  5. 落实结果:

    • ready-for-agent:发一条代理简报评论(AGENT-BRIEF.md)。
    • ready-for-human:结构与代理简报相同,但要点明为什么它不能被委派出去(需要人为判断、需要外部访问、涉及设计决策、需要人工测试)。
    • needs-info:发分诊备注(模板见下)。
    • 对于 wontfix,关闭议题,评论内容取决于为什么:
      • 已经实现:改动已经存在于代码库里。指出它在哪里;不要往 .out-of-scope/ 里写(那个知识库是给被否决的请求用的,不是给已经做出来的改动用的)。
      • 否决(bug):礼貌地解释,然后关闭。
      • 否决(enhancement):写进 .out-of-scope/,在评论里链接过去,然后关闭(OUT-OF-SCOPE.md)。
    • needs-triage:打上这个角色。如果有部分进展,可选发一条评论。

快速覆盖状态

如果维护者说「把 #42 移到 ready-for-agent」,就相信他们,直接打上这个角色。先确认你打算做什么(改角色、发评论、关闭),然后动手。跳过盘问。如果要在没有盘问环节的情况下移到 ready-for-agent,问一下他们是否想写一份代理简报。

needs-info 模板

## Triage Notes

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

- point 1
- point 2

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

- question 1
- question 2

盘问期间解决掉的一切,都要记到模板里 What we've established so far(目前已经确定)那一节下面,别让这些工作丢掉。问题必须具体、可执行,不能只是「请提供更多信息」。

恢复此前的会话

如果议题或 PR 上已有此前的分诊备注,读它们,检查报告者是否已经回答了悬而未决的问题,并先呈现一幅更新过的图景,再继续往下做。已经解决的问题不要重复问。

04 同仓库更多 Skills