用途
pr-recap 用于为 GitHub 拉取请求撰写一份面向审查者的可视化摘要。目标读者是审查该 PR 的人,应能从摘要首屏理解:这项改动为何存在、改了什么、如何改。摘要会指向 diff 中的具体位置,但不替代阅读 diff。
主要能力
- 生成一条 PR 评论形式的摘要,使用 GitHub Markdown,并可附带一张由 gh 上传的 PNG 示意图。
- 首屏包含三部分:故事(最多两句、60 词内,第一句说明具体症状与原因,第二句说明改了什么及如何改)、机制示意图、以及一行“未覆盖”说明(如未测量的运行时、未测试路径或已发布结论中的注意事项)。
- 其余内容放在一个折叠的
<details>区块中:风险说明、基准与头 SHA、阅读顺序、改动区域简表和证据链接。不使用表格。 - 在每次推送改变 diff 后重新生成摘要,并保持 PR 中只有一条摘要评论(发布新评论后删除旧的带 pstack-recap 标记的评论)。
- 可跳过不适合摘要的 PR,例如仅版本锁定及其哈希、错字或措辞修正、纯格式改动、仅锁文件改动、单提交回滚等。跳过时不向 GitHub 发布任何内容,只在回复中写一行说明。
使用方式
该工作流在本地运行。需要 gh;绘制示意图还需要 Bun 及随技能附带的 sketch 工具。它不会向其他主机发布内容。
- 从 origin 的 fetch URL 解析
<host>/<owner>/<repo>,所有gh pr调用传-R,所有gh api调用传--hostname。 - 用
gh pr view <n> ... --json ...读取 PR 记录,记录baseRefOid与headRefOid;摘要中的每条事实都描述这两个 SHA 之间的 diff。 - 用
gh pr diff <n>阅读完整 diff,并阅读每个描述 hunk 周围的代码、调用方和关联 issue。未读过的文件不得做任何断言。 - 阅读已发布的评审、结论评论和头提交上的 CI 运行;未发布在 PR 上的结论不算证据。
- 在笔记中回答三个问题:为什么(具体症状)、改了什么(一个机制)、如何改(修复动作)。只有 diff、PR 正文、关联 issue、提交信息或已发布评审给出理由时才陈述理由,否则标注为猜测。
- 按模板撰写
recap.md,发布命令为:gh pr comment <n> -R <host>/<owner>/<repo> --body-file recap.md --attach sketch.png。图片行须写作。 - 发布后删除旧的摘要评论,使 PR 只保留一条摘要。
- 回读新评论,确认包含两个标记以及记录的头部 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 列出了该技能改编的来源。