使用 Fabric `write_pull-request` Pattern：从 git diff 一键生成专业 PR 描述

本指南围绕 Fabric 仓库中的 write_pull-request 模式展开，它是 Fabric 众多社区贡献 Pattern 之一，专门用于把 git diff 的原始输出自动转化为结构清晰、可直接提交的 Pull Request 描述。读完本文，你将理解该 Pattern 的输入/输出契约、七段式 PR 描述结构，以及如何在 Fabric CLI 中组合 git diff 管道完成端到端的 PR 撰写流程，并可从源码层面理解 Pattern 的加载与执行机制。

一、Pattern 的设计定位：让工程师以"开 PR 的心态"审视变更

在 Fabric 框架中，一个 Pattern 就是一对定义 AI 角色、任务与输出格式的提示词（通常存放在 data/patterns/<pattern_name>/system.md），配合 user.md 之类的用户输入模板使用。write_pull-request 的 system.md 开篇即定义了 AI 的身份与目的：

You are an experienced software engineer about to open a PR. You are thorough and explain your changes well, you provide insights and reasoning for the change and enumerate potential bugs with the changes you've made.

也就是说，该 Pattern 不是简单地"翻译 diff"，而是让模型代入一位资深工程师的角色，在开 PR 之前通读全部变更，给出充分的解释、变更理由，并主动列举本次改动可能引入的潜在 Bug。这是一种"先批判后总结"的工程化写作姿态，也是它与单纯代码摘要类 Pattern 的本质区别。

二、输入格式契约：理解 git diff 的语法

Pattern 的输入约定非常明确：输入必须是 git diff 命令行输出，用于对比当前分支与主分支之间的全部变更。system.md 中花了相当篇幅教模型识别 diff 的五种典型语法形态，这也是使用本 Pattern 前值得掌握的基础知识：

1. 新增文件（Adding a file）

+++ b/newfile.txt
@@ -0,0 +1 @@
+This is the contents of the new file.

+++ b/newfile.txt 表示新增了文件；@@ -0,0 +1 @@ 表示该文件从 0 行变为 1 行；带 + 前缀的行是新文件内容。

2. 删除文件（Deleting a file）

--- a/oldfile.txt
+++ b/deleted
@@ -1 +0,0 @@
-This is the contents of the old file.

--- a/oldfile.txt 表示被删除的旧文件；@@ -1 +0,0 @@ 表示从 1 行变为 0 行；- 前缀行是被删除的内容。

3. 修改文件（Modifying a file）

--- a/oldfile.txt
+++ b/newfile.txt
@@ -1,3 +1,4 @@
 This is an example of how to modify a file.
-The first line of the old file contains this text.
 The second line contains this other text.
+This is the contents of the new file.

@@ -1,3 +1,4 @@ 表示旧文件 3 行被替换为新文件 4 行，其中未带前缀的行是上下文，- 行为删除内容，+ 行为新增内容。

4. 移动文件（Moving a file）

--- a/oldfile.txt
+++ b/newfile.txt
@@ -1 +1 @@
 This is an example of how to move a file.

5. 重命名文件（Renaming a file）

--- a/oldfile.txt
+++ b/newfile.txt
@@ -1 +1,2 @@
 This is an example of how to rename a file.
+This is the contents of the new file.

理解这五类语法是模型正确解读变更的基础：只有先识别"新增 / 删除 / 修改 / 移动 / 重命名"，才能准确回答"改了哪些文件、改了什么、为什么改"。

三、处理流程：从 diff 到 PR 描述的四步推理

Pattern 的 OUTPUT INSTRUCTIONS 规定了模型必须按顺序完成以下推理链：

1. 分析输入的 git diff 输出；
2. 识别代码中的变更，包括新增、修改、删除的文件；
3. 理解这些变更的目的——通过阅读代码本身与注释推断意图；
4. 撰写一份 Markdown 格式的详细 PR 描述。

语言风格上，Pattern 明确要求使用 "matter of fact"（就事论事）、清晰、简洁 的表述，并在必要时用 Markdown 代码块引用具体代码行，最终只输出 PR 描述本身，不附带任何多余解释。

四、输出格式：七段式 PR 描述模板

这是整个 Pattern 的核心资产，也是可直接复用到任何 PR 写作场景的结构化模板。它要求输出按以下七部分组织：

段落	内容要求
1. Summary	先给出整体变更的简明摘要，是对全部改动的一句话级概括
2. Files Changed	列出所有变更/新增/删除的文件，逐个说明改了什么、为什么改
3. Code Changes	对每个文件突出最重要的代码变更，必要时用 Markdown 代码块引用关键代码行
4. Reason for Changes	解释变更原因：修复 Bug、新增特性、提升性能等
5. Impact of Changes	讨论变更对整体项目的影响：潜在性能提升、功能变化等
6. Test Plan	简述已执行的测试方式，或应当如何测试
7. Additional Notes	任何有助于他人理解本次变更的补充说明

这套模板的价值在于：它强制 PR 作者同时回答"改了什么、为什么改、影响什么、怎么验证"四个问题，让不熟悉项目的读者也能快速理解变更全貌——这正是 system.md 末尾强调的"output should be clear, concise, and understandable even for someone who is not familiar with the project"。

五、实战用法：在 Fabric CLI 中运行该 Pattern

Pattern 文档末尾给出了标准的输入占位符：

$> git --no-pager diff main

在 Fabric 中，Pattern 通过 --pattern（短选项 -p）参数调用，输入内容经由标准输入管道传入。因此最直接的用法是：

git --no-pager diff main | fabric --pattern write_pull-request

--no-pager 的作用是禁止 Git 进入分页器，确保 diff 完整、无分页地输出到管道，避免截断——这是与本 Pattern 配合时的关键细节。

进一步地，你可以借助 README 中展示的组合用法将输出直接落盘或流式展示（参见 README.md 中关于 --output 与 --stream 的说明）：

# 将生成的 PR 描述保存到文件
git --no-pager diff main | fabric --pattern write_pull-request -o pr_description.md

# 流式输出，逐 token 实时查看生成结果
git --no-pager diff main | fabric --pattern write_pull-request --stream

从 CLI 实现看，--pattern 参数定义在 internal/cli/flags.go，同时该文件还提供 -l/--listpatterns 列出全部可用 Pattern、--readpattern 在终端打印指定 Pattern 的完整内容（internal/cli/flags.go）。想随时回顾本 Pattern 的原文，可运行：

fabric --readpattern write_pull-request

需要说明的是：write_pull-request 面向代码变更的 PR 描述撰写，其输入是 diff；如果你的场景是"把当前工作区的所有变更整理成提交信息或更新说明"，仓库中还提供了语义相近的 summarize_git_diff（面向 Git diff 的变更摘要，要求使用 conventional commits 前缀，如 feat:、fix:、chore:）与 summarize_git_changes（面向最近 7 天项目变更的公告式更新）。三者定位互补，可按需选择。

六、源码级支撑：Pattern 如何被加载与执行

理解 Pattern 的底层机制有助于更可靠地使用它。从源码结构看，Fabric 的 Pattern 加载链路如下：

• 模式仓库：Pattern 默认存放于仓库根目录的 data/patterns/（代码常量 DefaultPatternsGitRepoFolder = "data/patterns"，见 internal/tools/patterns_loader.go），每个 Pattern 目录内通常包含 system.md 与可选的 user.md；
• 加载器：internal/tools/patterns_loader.go 中的 PopulateDB() 会从 Git 仓库克隆 Pattern 数据到本地配置目录，movePatterns()（同文件 L174）负责落盘并写入 loaded 标记文件，createUniquePatternsFile()（同文件 L319）会汇总生成唯一的 Pattern 名称清单；
• 执行入口：internal/cli/cli.go 中的 Cli() 是 CLI 主控，负责初始化注册表（registry）、加载数据库后分发到各功能处理器，Pattern 选择与消息组装随后进入 chat 处理流程。

也就是说，write_pull-request 的 system.md 作为提示词模板被加载进数据库后，CLI 在运行时把管道传入的 diff 文本作为用户消息拼接，一并提交给配置好的 AI 模型（可通过 fabric --setup 配置 OpenAI 等提供商）。整个流程可以概括为：git diff 输出 → 标准输入 → CLI 组装（system.md + 输入文本）→ LLM 推理 → 七段式 PR 描述。

七、使用建议与注意事项

• 保持 diff 范围可控：建议在干净的 feature 分支上执行 git --no-pager diff main，避免把无关提交混入同一份 PR 描述；若只关注未提交的改动，可用 git diff（工作区）或 git diff --cached（暂存区）自行替换输入命令。
• 人工复核"Potential Bugs"部分：Pattern 要求模型列举潜在 Bug，但这属于模型推断，提交前务必人工核对关键逻辑与测试结果，勿把 AI 生成的"可能性"当成事实写入 PR。
• 结合 Test Plan 段落实：将 go test ./...（Go 项目）等实际执行过的测试命令与结果写入 Test Plan 段落，能让 PR 描述更具说服力。
• 输出即最终产物：Pattern 规定"只输出 PR 描述"，因此可直接将结果粘贴到 PR 提交框，无需二次加工。

综上，write_pull-request 是一个输入输出契约清晰、模板质量高、可直接落地的工程化 Pattern。配合 Fabric 的管道式 CLI 设计，它把"读懂 diff → 组织 PR 文案"这一高频重复劳动交给了 AI，而把代码审查与决策判断留给了工程师本人。