PR 技能的目标是帮助用户打开一个拉取请求,但坚持一个核心原则:代码提交(commit)可以由大语言模型(LLM)生成,但 PR 描述必须由用户自己撰写。因为该 PR 最终会被压缩合并(squash-merged),其标题和正文将成为落在主分支上的唯一提交信息,所以这实际上是在用用户自己的话写一条需要经得起时间考验的提交信息。
该技能的职责是处理文字周围的一切:建议标题、校对、以及打开 PR 的机械操作。它明确避免的一个失败模式是:由技能自己起草描述,因为即使是一个“起点”也会把用户锚定在技能的版本上,导致描述不再属于用户。
使用流程分为六个步骤:
-
侦察(Recon):读取仓库状态、分支与基础分支之间的提交日志和差异统计、仓库的 PR 风格(通过查看最近合并的 PR 和提交历史)、PR 模板(在 .github/、仓库根目录或 docs/ 中查找)、以及分支所关联的 issue(从分支名、提交或 SPEC 中获取)。如果工作区有未提交的更改或当前在基础分支上,则停止并告知用户。
-
简要说明(Brief):由于用户并没有编写这些代码,技能会在用户撰写描述之前,用聊天形式快速给出一个两分钟的代码变更概览。内容分为三组:变更了什么(行为而非文件)、风险(可能出错或以后会带来麻烦的地方)、权衡(代码所做的选择以及未采用的替代方案)。只呈现代码或提交中显示的内容,不猜测原因。
-
建议标题并请求描述:在同一条消息中,技能会按照仓库风格建议一个标题(祈使句、约 65 个字符以内,命名可观察的变化而非机制),并至多提供一个备选。然后请用户撰写描述,提醒他们回答为什么做这个变更、为什么这样做、以及未来读者可能遇到的问题。如果有 PR 模板,会列出其标题;如果有 issue,会提醒用户链接(如 Closes #42)。之后技能停止并等待,不代写描述、模板或示例。
-
校对(Proof):修正错误(拼写、语法、损坏的 Markdown、不清晰的句子、应该用反引号包裹的代码名),但保留属于用户的内容(用词、语气、结构、长度、观点、幽默)。校对不能读起来像技能自己写的。同时检查描述中的声明是否与差异一致,若不一致则标记但不修正。将正文按 72 列换行,不添加章节、标题、总结或结尾行,也不添加署名。如果内容已经很干净,则不做任何更改。
-
确认(Sign-off):展示更改列表、标记但未更改的内容,以及最终标题和正文的完整内容(用围栏代码块)。请求用户确认。任何编辑请求都应应用并重新展示完整最终版本。只有对最后展示的确切文本给出“是”之后才继续。
-
打开(Open):只有在确认之后,如果分支没有上游则推送(git push -u origin HEAD),将正文写入临时文件并通过 --body-file 传递,然后执行 gh pr create --base <base> --title "<title>" --body-file <tmpfile>,并回复 PR URL。
此外,该技能还包含一个自主模式(Autonomous mode),仅在参数以 --auto 开头时启用。在该模式下,没有人会撰写或批准描述,因此由技能自己撰写描述和注释。技能会进行侦察(与步骤 1 相同),收集“为什么”(从提交正文、SPEC、差异中获取,未记录的原因写“未记录”而非猜测),用通俗英语撰写正文(面向使用产品但不读代码的人),并将风险、权衡、开放问题作为内联注释放在相关代码行上。每个注释都包含一个简单的段落解释,用日常类比说明,必要时附上小图。技能会署名所使用模型的名称和精确 ID。然后推送并以草稿模式创建 PR(gh pr create --draft),并通过 gh api 一次性提交所有内联注释作为一条审查。如果不在 GitHub 上、没有 CLI 或调用失败,则不寻找变通方法,回复中提供 PR URL 或未打开的原因以及标题和正文,以及未发布的注释(路径:行号格式),每条注释用 ~~~ 围栏。最后说明检查更改了什么。
语调方面,正文和注释应听起来像 thoughtbot 团队而非个人:使用“我们”,对话式而非学术或企业风格,使用缩写和短句,数字用阿拉伯数字(除非在句首),使用牛津逗号,不使用表情符号,每段最多一个感叹号。正文以引发变更的原因开头,然后说明变更内容,注意事项单独成段,短段落,不使用标题或粗体,链接放在底部用引用样式。注释像队友的审查评论:最多两句话,说明我们做什么以及为什么(用“因为”或“既然”),然后给出建议而非命令(如“我们可能想……”),开放问题以问句结尾。
该技能适用于 Rails 项目(从来源 thoughtbot/rails-consultant 推断),但描述中未明确说明限制,暂未提供其他平台或环境的具体要求。