SuperAPI AI 工具集

pr-recap

编程与开发

查看项目

更新于 10-24 09:01

技能介绍

用途

pr-recap 用于为 GitHub 拉取请求撰写一份面向审查者的可视化摘要。目标读者是审查该 PR 的人,应能从摘要首屏理解:这项改动为何存在、改了什么、如何改。摘要会指向 diff 中的具体位置,但不替代阅读 diff。

主要能力

  • 生成一条 PR 评论形式的摘要,使用 GitHub Markdown,并可附带一张由 gh 上传的 PNG 示意图。
  • 首屏包含三部分:故事(最多两句、60 词内,第一句说明具体症状与原因,第二句说明改了什么及如何改)、机制示意图、以及一行“未覆盖”说明(如未测量的运行时、未测试路径或已发布结论中的注意事项)。
  • 其余内容放在一个折叠的 <details> 区块中:风险说明、基准与头 SHA、阅读顺序、改动区域简表和证据链接。不使用表格。
  • 在每次推送改变 diff 后重新生成摘要,并保持 PR 中只有一条摘要评论(发布新评论后删除旧的带 pstack-recap 标记的评论)。
  • 可跳过不适合摘要的 PR,例如仅版本锁定及其哈希、错字或措辞修正、纯格式改动、仅锁文件改动、单提交回滚等。跳过时不向 GitHub 发布任何内容,只在回复中写一行说明。

使用方式

该工作流在本地运行。需要 gh;绘制示意图还需要 Bun 及随技能附带的 sketch 工具。它不会向其他主机发布内容。

  1. 从 origin 的 fetch URL 解析 <host>/<owner>/<repo>,所有 gh pr 调用传 -R,所有 gh api 调用传 --hostname。
  2. 用 gh pr view <n> ... --json ... 读取 PR 记录,记录 baseRefOid 与 headRefOid;摘要中的每条事实都描述这两个 SHA 之间的 diff。
  3. 用 gh pr diff <n> 阅读完整 diff,并阅读每个描述 hunk 周围的代码、调用方和关联 issue。未读过的文件不得做任何断言。
  4. 阅读已发布的评审、结论评论和头提交上的 CI 运行;未发布在 PR 上的结论不算证据。
  5. 在笔记中回答三个问题:为什么(具体症状)、改了什么(一个机制)、如何改(修复动作)。只有 diff、PR 正文、关联 issue、提交信息或已发布评审给出理由时才陈述理由,否则标注为猜测。
  6. 按模板撰写 recap.md,发布命令为:gh pr comment <n> -R <host>/<owner>/<repo> --body-file recap.md --attach sketch.png。图片行须写作 ![<alt text>](./sketch.png)。
  7. 发布后删除旧的摘要评论,使 PR 只保留一条摘要。
  8. 回读新评论,确认包含两个标记以及记录的头部 SHA;若附了示意图,还要确认存在 user-attachments 图片链接。

示意图

在工作文件夹外使用一个可写工作目录存放 scene.json、sketch.png、story.txt 和 recap.md。从示意图目录中选择一个图形,写 scene.json,用 bun "<skill>/scripts/sketch/sketch.mjs" scene.json sketch.png 渲染,修正报告的问题,并在使用前亲自查看 PNG。若运行环境无法运行 Bun 或无法显示图片,则跳过示意图,发布故事、“未覆盖”行和详情区块,并在回复中说明跳过原因;不得用 Mermaid 图或表格替代。

事实核对

发布前列出摘要中每个事实句和示意图中每个标签,逐条对照 diff 的 hunk 或固定 SHA 的行,标记为已验证、已修正、无依据或无法验证。修正已修正项;删除无依据或无法验证项,或改写为猜测。若标签变更则重新渲染示意图。检查每个链接:源码链接固定到记录的头部 SHA;评审和 CI 链接必须指向该 PR 上、且 CI 运行于该头提交的记录。再次读取 headRefOid,若已移动则基于新 diff 重建摘要。核对标记保留在笔记中,不写入评论。

适用场景与限制

适用于需要让审查者快速理解一个有行为变更的 PR 的团队场景。它本地运行,仅发布到目标 PR 评论,不用于 PR 正文(在受 no-mistakes 管控的仓库中正文由门禁管理)。不对无行为需追踪的改动生成摘要。不得从 diff 复制密钥、令牌或类似凭证的值,应写 <redacted>。摘要会使用技术写作与 unslop 技能润色句子。CREDITS.md 列出了该技能改编的来源。