SuperAPI AI 工具集

open-a-pr

编程与开发

查看项目

更新于 11-05 07:35

技能介绍

用途

open-a-pr 是一个面向 Pull Request(PR)创建的技能,目标是让 PR 正文在读者打开 diff 之前的三十秒内把必要信息说清楚。它同时适用于撰写 PR 描述、重写已有 PR 描述、判断 PR 正文是否过长,以及检查 PR 描述是否可读。

主要能力

该技能规定 PR 正文使用 .github/pull_request_template.md 的结构:填满每个标题、不新增标题、总字数约 250 词以内。各段落分别对应:

  • What is this about?用一两句平实的话说明涉及的表层和改动。
  • What problem does it solve?说明人感受到的痛点或承担的风险,而不是机制;并描述改动前的具体状况,例如人看到什么或无法做什么。
  • How is this implemented?用两到五条要点向评审者说明主要改动部分及其连接方式,文件路径、工具名、路由和开关放在这里。
  • What else changed?逐条列出不属于主任务的附带改动,如顺手修复、重构、重命名、依赖升级、测试或工具调整;没有则写 none。
  • Release note:给使用 OpenWork 的人一句话,或写 none。该说明会直接进入变更日志收集流程;面向 CI、测试、评审工具或无人注意的重构写 none,此类 PR 将不进入变更日志;删除或改变用户依赖的功能必须写说明。
  • Evidence:指出证明改动的 spec,并用一行说明其 before → after 展示什么;不复制结论、SHA、截图或链接。没有 spec 改动时需用一行说明原因,例如仅做类型检查和构建。UI 改动需在末尾写一行 Design: P3, S4, C6。

标题需使用 conventional commit 风格、祈使语气、不超过 70 个字符。

使用方式

发起 PR 前应自行运行相关 spec(run-tests),或让 CI 在 PR 头部运行 PR 变更的 spec 并保留记录作为产物:

gh workflow run pr-proof.yml --ref <branch> -f pr=<number>

创建和编辑 PR 的命令为:

gh pr create --base dev --title "<type>(<scope>): <change>" --body-file /tmp/pr-body.md gh pr edit <n> --body-file /tmp/pr-body.md

建议先写好正文文件,再以评审者视角通读;如果某段落让人需要滚动,就删减。合并后,开发推送会运行新增或改动的每项证明以及每个核心旅程。证据绑定到具体提交:rebase 或 cherry-pick 后需在新头部重跑 spec,不能引用旧运行结果。红色证据应通过修正 spec 或代码并重跑解决,而不是在正文中叙述。

适用场景

适用于创建新 PR、重写 PR 描述、评估 PR 正文是否过长或不可读,以及需要控制 PR 描述信息密度、突出改动前状况与证据的团队协作场景。

限制

该技能面向特定仓库的模板与工作流,资料未提供通用化配置或跨平台适配说明。正文不应包含根因叙述、套件计数与 CI 矩阵、镜像摘要、worktree 设置、凭证说明、其他 PR 的失败、风险与回滚等模板化内容。关于收费、价格、平台支持等事实,资料暂未提供。