SuperAPI AI 工具集

pr-description-writer

编程与开发

查看项目

更新于 11-09 12:10

技能介绍

PR Description Writer 是一个面向 PR 作者的技能,用于撰写、重写和校验 Pull Request 描述。它的核心目标是让评审者能够判断:需要多仔细地看、重点看哪里、以及这次合并能否被撤销。

用途

该技能用于在打开 PR 时生成正文,在描述薄弱时重写(如“修复这个 PR 描述”“让它可评审”),在请求评审前做机械式检查(证据、步骤、回滚是否齐全),以及处理包含迁移、API 或契约变更、删除操作的 PR——这些场景下合并风险判断错误可能引发事故。它还可以作为 CI 门禁,让正文声称“可逆”却触碰迁移的 PR 失败。

主要能力

技能将 PR 正文写成五个部分:摘要(summary)、原因(why)、证据(evidence)、如何验证(how to verify)、合并风险(merge risk)。它根据真实文件列表和 diff 对变更进行分类,并对结果进行 lint,从而强制实现诚实的分类,而不是寄希望于作者自觉。

提供的工具包括:

  • scripts/risk_classifier.py:对每个变更路径分类(schema 迁移、公共 API、持久化格式、数据删除、基础设施、认证、依赖、CI、配置、代码、测试/文档),扫描 diff 中的破坏性 SQL 和被移除的契约字段,计算 door 和影响范围,并起草 Merge risk 部分(--emit-section)。退出码:0 已分类,1 door 达到或超过 --fail-on,2 用法错误。
  • scripts/pr_body_lint.py:检查五个部分是否存在且已填写、证据是否具体、验证是否可运行、door 是否声明且单向变更是否有回滚、是否泄露凭据,以及(配合 --files)声称的 door 是否与文件相符。退出码:0 通过,1 错误(或配合 --strict 时的警告),2 用法错误。

两个工具都支持 --format text|json,都可用 - 读取标准输入,因此可与 git diff --name-only 和 gh pr view --json body 串联。

使用方式

工作流 1:撰写新的 PR 正文(推荐)。先获取相对真实基分支的文件列表和 diff;运行 risk_classifier.py --emit-section,阅读每个文件的分类,若某路径被误分类,正文必须说明原因;然后依据 assets/pr-body-template.md 起草正文,五个部分分别填写行为变更、用户视角的问题与工单链接、最强可用层级的证据(截图 > 测试输出 > 命令输出 > CI 链接)、带精确命令和预期结果的编号验证步骤、以及分类/影响范围/回滚计划;用 linter 配合 --files 和 --diff 校验,修复所有错误;删除模板注释后打开 PR。

工作流 2:修复已有正文。用 gh pr view 123 --json body -q .body > pr.md 和 gh pr diff 123 --name-only > changed.txt 拉取当前正文和文件列表;lint 后按发现项作为编辑清单;只重写失败的部分,保留通过部分的作者措辞;重新 lint 后用 gh pr edit 123 --body-file pr.md 更新。

工作流 3:在 CI 中门禁 PR 正文。在 PR 工作流中把正文和变更文件列表写入文件;运行 linter,退出码 1 使任务失败;可选要求单向 PR 带标签(risk_classifier.py --files changed.txt --fail-on one-way 退出 1,从而要求合并前有 one-way-reviewed 标签)。注意:正文必须通过文件传递,绝不能把 ${{ github.event.pull_request.body }} 插值进 shell 行,因为 PR 正文是攻击者可控文本。

决策规则

Door 分类:仅改动代码、测试、文档为 two-way;触碰基础设施、认证、依赖、CI 或配置默认为 conditional(需说明条件及为何不适用);新增或修改迁移、公共 API/契约、持久化格式,或删除数据为 one-way;包含 DROP、TRUNCATE、无范围 DELETE、重命名或移除契约字段时,无论路径如何均为 one-way。过度分类代价低,分类不足代价高。

回滚计划深度:two-way 为“回滚此 PR”加上必须同步执行的事项(关闭开关、清缓存);conditional 说明会使其变成单向的条件以及为何此处不成立;one-way 需写明触发条件、精确步骤、负责人、时长以及数据和客户端的最终状态。若写不出这些,应使用 expand/contract 拆分 PR。

证据按变更类型:UI 用前后截图或短录像;bug 修复用修复前失败、修复后通过的测试及两份输出;后端行为用真实运行的命令输出(curl、CLI);迁移用迁移计划输出、行数、预发环境耗时和锁等待;性能用前后数字及测量方法;纯重构用相同输入下前后输出一致。

适用场景与限制

适用:撰写、重写和 lint PR 描述;根据文件路径和 diff 内容做合并风险分类;在 CI 中门禁 PR 正文。

不适用:审查代码本身(正确性、安全性、测试覆盖率);生成证据(技能提出命令,由人或 CI 运行);生成变更日志或发布说明。

重要注意事项:路径分类是启发式的,存放 fixture 的 migrations/ 文件夹会被判为 one-way,应在正文中说明而不是削弱规则;diff 扫描覆盖常见 SQL 和迁移辅助形态,不覆盖所有 ORM;密钥扫描只捕获常见凭据格式,是兜底而非脱敏工具。