8天构建AI自动生成PR描述工具：从零到一的技术实战复盘

1. 项目缘起：一个让开发者“偷懒”的执念

我讨厌写 PR 描述。不是因为懒——代码是我改的，我比谁都清楚改了啥。真正让我头疼的，是每次都要花上额外的十分钟，从写代码的“心流”状态里硬生生切换出来，绞尽脑汁地把那些改动，用一种对审阅者友好的、结构化的方式重新组织一遍。这种重复的、打断性的上下文切换，日复一日，积少成多，成了开发流程里一个不大不小的痛点。

我相信不止我一个人有这种感觉。在快节奏的团队里，尤其是在需要频繁提交小改动或修复时，为每个 PR 都精心撰写一份描述，有时会让人觉得是一种负担。我们更希望把时间花在解决下一个问题上，而不是为已经解决的问题写“作文”。于是，一个想法冒了出来：能不能让机器来干这个“翻译”的活儿？让 AI 读取代码差异，自动生成一份清晰、结构化的 PR 描述初稿，开发者只需要在此基础上微调，甚至直接使用。

这个想法催生了PRDraft——一个 GitHub App。它的目标很简单：当你打开一个 Pull Request 时，它自动读取你的代码差异，并立即在 PR 讨论区发布一份由 AI 生成的、结构化的描述。整个过程，用户只需要两步点击完成安装，无需任何配置，也无需碰命令行。下面，我就来复盘一下，从零开始，一个人，在 8 天时间里把这个想法变成可运行产品的全过程。这不仅仅是一个技术构建记录，更是一次关于验证、执行和解决实际障碍的实战分享。

2. 核心思路与方案选型：为什么是这套组合拳？

在动手写第一行代码之前，明确“做什么”和“怎么做”同样重要。这个项目的核心价值在于“自动化”和“零摩擦”，这直接决定了技术栈和架构的选择。

2.1 产品定位与用户价值假设

首先，我需要验证这个痛点是否真实存在，还是仅仅是我个人的“矫情”。在真正投入开发前，我在 GitHub Discussions 和 Dev.to 社区提了一个简单直接的问题：“有多少人能始终如一地写出高质量的 PR 描述？”

收到的真实反馈给了我信心。有两个回复让我印象深刻：

1. “是的，这确实是个痛点，尤其是在快速迭代的团队中。”
2. “如果它能准确反映代码差异，并且允许我在提交前编辑，我会信任并使用它。”

这两点反馈至关重要。第一点验证了市场痛点，第二点则指明了产品的关键成功要素：准确性和可编辑性。PRDraft 的定位不是取代开发者，而是作为一个高效的“副驾驶”，提供一个优秀的起点，节省那“十分钟”的上下文切换时间。这个验证虽然简单，但足以让我确信，投入时间构建它是值得的。

2.2 技术栈决策：追求极致效率与零成本启动

确定了要做什么，接下来就是技术选型。我的原则是：使用我最熟悉、最能快速上手的工具，同时尽可能将初期成本降至零。对于一个验证阶段的产品来说，速度比完美的架构更重要。

• 前端/后端框架：Next.js (App Router) + Tailwind CSS

  • 为什么？Next.js 提供了全栈能力，从 API 路由（处理 GitHub Webhook）到前端页面（如仪表盘）都能在一个项目内搞定，极大地简化了部署和开发流程。App Router 模式对服务端组件的支持，使得构建需要服务端渲染的页面（如仪表盘）非常顺畅。Tailwind CSS 则能让我以惊人的速度构建出看得过去的 UI，无需在样式设计上花费过多时间。

• 数据库：Supabase

  • 为什么？我需要存储用户安装信息、PR 事件记录以及用量统计。Supabase 提供了基于 PostgreSQL 的托管数据库，有非常慷慨的免费额度，并且其 JavaScript/TypeScript 客户端与 Next.js 集成起来天衣无缝。它开箱即用的身份验证、实时订阅等功能虽然本项目暂未用到，但也为未来扩展留出了空间。

• AI 模型 API：Groq (llama-3.3-70b-versatile)

  • 这是最关键的选型之一。市面上主流的选择是 Anthropic 的 Claude 或 Google 的 Gemini。但我最终选择了 Groq，原因非常实际：
    1. 成本：Anthropic API 需要付费，没有免费额度。对于一个尚未验证付费意愿的产品，前期投入现金风险太高。
    2. 地域限制：Google Gemini 的免费配额（limit:0）在印度地区存在一个已被确认的 Bug，导致完全无法使用。这对于身处印度喀拉拉邦的我来说，是条死路。
    3. Groq 的优势：Groq 提供了每天 14,400 次请求的免费额度，速度极快（因其专有的 LPU 推理引擎），并且在印度可用。这完美契合了“零成本启动”和“快速响应”的需求。虽然模型能力可能略逊于顶尖模型，但对于“总结代码差异并结构化输出”这个明确任务，Llama 3.3 70B 模型已经绰绰有余。

• GitHub 集成：Octokit

  • 为什么？Octokit 是 GitHub 官方的 SDK，对 GitHub App 和 Webhook 的处理提供了最全面、最可靠的支持。用它来处理签名验证、API 调用等，能避免很多底层细节的坑。

• 部署：Vercel

  • 为什么？Next.js 的亲爹，部署体验无缝衔接。同样提供慷慨的免费额度，支持服务端函数，并且全球分发速度快。对于早期项目，这是不二之选。

最终，这套技术栈使得我的月度基础设施成本保持在：0 美元。这让我能毫无负担地进行试错和迭代。

2.3 核心流程设计

整个应用的核心逻辑是一条清晰的数据流水线：

1. 事件触发：用户在安装了 PRDraft 的仓库中打开一个 Pull Request。
2. 接收通知：GitHub 会向我在 Vercel 上配置的 Webhook 端点发送一个pull_request.opened事件。
3. 安全验证：我的服务端 API 路由使用 Octokit 和 GitHub App 的私钥，验证 Webhook 请求的签名，确保请求确实来自 GitHub，防止伪造攻击。
4. 获取数据：验证通过后，使用 GitHub API 并携带该次安装的认证令牌，获取这个 PR 的详细数据，特别是文件差异。
5. AI 处理：将获取到的代码差异（diff）作为提示词的一部分，发送给 Groq API。提示词经过精心设计，要求模型按照固定的模板（What, Why, How to test, Notes）进行总结。
6. 结果回写：收到 AI 生成的描述后，再通过 GitHub API 以评论的形式，发布到对应的 PR 中。

这个流程确保了从事件发生到生成描述，全程自动化，用户无感知。

3. 构建实录：从零到一的八天冲刺

3.1 第1-2天：验证与启动

这两天完全没有写代码。全部精力都放在了前面提到的“用户价值假设”验证上。在社区发帖，观察讨论，收集反馈。这个阶段的目标是避免“自嗨式开发”。当看到有开发者明确表示“这是个痛点”和“我会用”时，心里的石头才算落地。行动建议：在你有一个自认为绝妙的想法时，强迫自己先停下来，去目标用户聚集的地方问一问。哪怕只得到两三个正面反馈，也比闭门造车六个月后才发现没人需要强。

3.2 第3-5天：核心功能实现

这三天是密集的编码期，目标是跑通上述核心流程。

1. 项目初始化与基础架构：用create-next-app快速搭建项目，配置 Supabase 环境变量，建立基本的数据库表（installations,pr_events）。
2. GitHub App 配置：在 GitHub 上创建新的 GitHub App，配置 Webhook 地址（指向即将部署的 Vercel 域名），设置所需的权限（主要是对 Pull Request 的读写权限）。
3. Webhook 处理器：在 Next.js 的 App Router 下创建api/github/webhook/route.ts。这里是核心中的核心。首先要正确处理 GitHub 的签名验证，这是安全底线。然后解析事件，针对pull_request.opened事件进行后续处理。
4. Diff 获取与 AI 集成：在事件处理器中，调用 GitHub API 获取 PR 的 diff。然后，构建一个清晰的提示词模板，将 diff 和指令发送给 Groq API。这里提示词工程很关键，我迭代了几次，才让模型稳定输出我想要的四段式结构。
5. 回写 GitHub：最后，使用 Octokit 将 AI 返回的文本作为评论发布到 PR。

生成的描述格式示例：

## What changed - Added webhook signature verification using Octokit - Introduced free tier cap logic (5 PRs/month) checked before incrementing ## Why Prevents unauthorized webhook calls and limits free usage before billing is set up. ## How to test - Open a PR on a repo where PRDraft is installed - Check that the description is auto-populated within seconds ## Notes Free tier cap is checked BEFORE incrementing pr_count to avoid off-by-one errors.

这个结构清晰地区分了改动内容、原因、测试方法和注意事项，对审阅者非常友好。

实操心得：处理 GitHub Webhook 时，一定要考虑重试机制。GitHub 会在发送 Webhook 后，如果未收到2xx响应，进行多次重试。你的处理逻辑必须是幂等的，即同一事件处理多次的结果应与处理一次相同。否则会导致重复操作（比如给同一个 PR 发多条评论）。

3.3 第5天：第一个外部用户与产品时刻

代码跑通后，我立刻将应用安装到自己的几个测试仓库，确保基本流程无误。然后，我邀请了第一位外部测试者roshhellwett。当他安装应用，打开一个 PR，并在几秒内看到自动生成的描述时，那个时刻无比美妙。

他的反馈非常宝贵：“按预期工作——结构很扎实，确实节省了时间。Groq 速度明显很快。对于改动分散的复杂 PR，生成的内容可能感觉有点泛泛而谈——但作为一个可以在此基础上编辑的起点？绝对有用。”

这个反馈精准地命中了产品的核心价值：不是完美无缺的最终答案，而是一个高质量的初稿。同时，他也指出了边界情况下的局限性，这为后续优化指明了方向。从这一刻起，PRDraft 从一个“ side project ”变成了一个真正的“产品”。

3.4 第6-7天：修复漏洞与启动分发

有真实用户后，问题开始暴露。这几天主要在和 Bug 作斗争，并开始尝试推广。

遇到的 Bug 及修复：

1. 免费额度计数错误：逻辑原本是“先增加计数，再判断是否超限”，这导致用户实际上可以生成 6 个 PR 描述，而不是 5 个。这是一个经典的“差一错误”。修复方法是先检查，后递增。
2. 用户信息丢失：在记录 PR 事件时，account_login字段每次都被覆盖为‘unknown’。原因是数据库的upsert操作匹配了错误的字段，导致总是插入新记录而非更新。修复方法是确保upsert使用正确的唯一约束字段。
3. Webhook 重复处理：由于一次网络超时，GitHub 在 15 秒内重试了 38 次，导致同一个 PR 事件被处理了 38 次，生成了 38 条相同的评论。这是最严重的一个 Bug。修复方法是在pr_events表中，为(installation_id, pr_number)组合添加唯一约束。这样，当数据库尝试插入重复事件时，会直接报错，我们的代码可以安全地忽略这个错误，从而实现幂等性。

分发渠道尝试：

• Dev.to & Indie Hackers:完全开放，立即发帖。这里是开发者社区，获得了不错的初始关注和反馈。
• GitHub Marketplace:提交审核。这是最重要的分发渠道，因为用户可以直接在 GitHub 内发现和安装。
• Reddit & Hacker News:遭遇当头一棒。我的 Reddit 账号只有 3 Karma，发帖直接被屏蔽。Hacker News 账号更是因为早期一些不当互动，Karma 是负数。这让我意识到，不要假设所有推广渠道都是随时可用的。很多平台对新账号或低信誉账号有严格限制。你需要提前培养账号信誉。

3.5 第7-8天：构建仪表盘与支付困境

产品基本可用后，我需要一个地方让用户管理他们的安装和查看使用情况。

仪表盘开发：在/dashboard路径下，我快速构建了一个管理面板，包含：

• 当前计划标识（免费版/专业版）。
• 用量进度条（已用 PR 数 / 免费额度），用颜色直观提示。
• 最近的 PR 活动列表（仓库名、PR 号、时间）。
• 升级到专业版的呼吁按钮。
• 安装信息展示。
  • 一个巧妙的点：在 GitHub App 配置中，可以设置一个Setup URL。用户安装应用后，GitHub 会自动将用户的浏览器重定向到这个 URL。我将其设置为/dashboard，这样用户安装后能无缝跳转到仪表盘，无需复杂的 OAuth 流程。

第8天的改进：

1. 活动列表增强：不仅显示仓库和 PR 号，还加上了 PR 的标题，信息更完整。
2. 增加仪表盘链接：在每个自动生成的 PR 描述底部，添加一个指向该安装仪表盘的链接。这样，团队中的任何成员（不仅仅是安装者）都可以轻松点击查看当前用量，无需费力寻找管理入口。
3. 友好的额度提示：当用户达到免费额度上限时，不再静默失败，而是直接在 PR 下发布一条友好评论，提示额度已用尽并引导升级。

“无人提及”的支付困局：这是本次构建过程中最令人沮丧、也最现实的一部分。产品做好了，收费功能开发完了，却发现收钱的管道堵住了。

• Stripe：从 2024 年起，在印度对个人开发者实行邀请制，我无法直接注册。
• Lemon Squeezy：明确禁止印度个人账户接收国际支付。
• Gumroad：在设置印度银行账户收款时遇到问题，流程不顺畅。
• Paddle：正在尝试中，看起来最有希望。

这个教训非常深刻：对于全球化的 SaaS 产品，尤其是身处特定地区的独立开发者，支付供应商的选择不是一个简单的技术集成问题，而是一个受地缘政策限制的商业合规问题。它可能比构建产品本身更耗时、更不可控。务必尽早开始调研和尝试。

4. 数据、反思与避坑指南

4.1 第8天数据快照

数据很寒酸，但真实。这是一个从零开始的、8天龄产品的真实写照。13个自动生成的 PR 描述，意味着至少为这2位用户节省了十几段上下文切换的时间。

4.2 常见问题与排查实录

在实际开发和运营中，会遇到一些典型问题。这里记录下我的排查思路：

问题一：Webhook 发送失败，GitHub 显示“Deliveries”报错。

• 可能原因 1：Vercel 服务未启动或 API 路由路径错误。
  • 排查：检查 Vercel 部署是否成功，并确保api/github/webhook/route.ts文件存在且路径正确。本地测试时，注意 GitHub 无法向localhost发送 Webhook，需要使用ngrok或localtunnel等工具暴露本地服务到公网。
• 可能原因 2：Webhook 密钥配置错误。
  • 排查：对比 GitHub App 设置中的 Webhook Secret 和环境变量中配置的是否完全一致。一个字符的差错都会导致签名验证失败。
• 可能原因 3：服务器端代码未在收到 Webhook 后及时返回200 OK响应。
  • 排查：确保你的 Webhook 处理函数是异步的，并且在完成主要逻辑前就先返回响应。长时间的处理（如调用较慢的 AI API）应该放在后台任务中，避免 HTTP 请求超时。

问题二：AI 生成的描述质量不稳定，有时偏离主题。

• 可能原因 1：提示词不够精确。
  • 排查与优化：迭代你的提示词。明确指令格式，提供更具体的例子。例如，除了要求“结构化输出”，还可以指定“如果改动主要是修复拼写错误，请在‘What changed’中简要说明，并在‘Notes’中注明无需测试”。给模型划定更清晰的边界。
• 可能原因 2：代码 Diff 过长或过于复杂。
  • 排查与优化：Groq 等 API 有上下文长度限制。对于超大的 Diff，可以考虑只截取关键文件的改动，或者在提示词中要求模型“总结最主要的三个改动”。在仪表盘中可以加入一个“重新生成”按钮，让用户手动触发。

问题三：数据库中出现重复的 PR 事件记录。

• 原因：Webhook 重试机制导致。
• 解决方案（必须实施）：如前所述，在存储事件的数据库表中，设置一个由installation_id和pr_number组成的联合唯一约束。这是实现处理逻辑幂等性的最有效、最根本的方法。代码中在插入数据时捕获唯一冲突错误并忽略即可。

4.3 独家避坑技巧与心得

1. “先检查，后操作”原则：对于任何涉及状态变更和限额检查的逻辑（如“免费额度是否用完”），务必遵循“先检查条件，条件通过后再执行操作并更新状态”的顺序。这能避免许多隐蔽的并发和差一错误。
2. 尽早引入幂等性设计：在处理第三方 Webhook、消息队列等可能重复发送事件的系统时，从一开始就要假设“同一条消息可能会来多次”。在数据库层用唯一约束来防御，是最可靠的手段。
3. 推广渠道有门槛：不要等到产品上线才去注册社区账号。提前数月，以真实参与者的身份在你目标用户所在的社区（如 Reddit 相关板块、Hacker News、专业论坛）活跃起来，积累信誉和 Karma。临时抱佛脚行不通。
4. 支付供应商是“基础设施”：如果你打算做付费产品，在技术选型的同时，就要开始研究支付方案。特别是对于国际业务和特定地区的开发者，这其中的合规复杂性远超想象，可能成为产品上市的最大瓶颈。
5. 用“产品时刻”定义成功：不要只关注代码是否运行。你的第一个外部用户，他/她使用产品并给出反馈的那个瞬间，才是产品真正的起点。用心收集这些早期反馈，它们比任何数据分析都更直接、更有价值。

5. 后续规划与迭代方向

目前，PRDraft 还是一个非常早期的产品。基于这8天的经验，接下来的路线图大致清晰：

1. 解决支付瓶颈：全力攻克 Paddle 或其他可用支付渠道的集成，这是开启收入测试的前提。
2. 扩大测试范围：邀请更多早期用户，特别是来自不同团队背景、代码库复杂度的用户，收集更多场景下的反馈。
3. 优化 AI 提示与模型：针对“复杂 PR 描述泛泛”的反馈，可以尝试更精细的提示工程，或者对于专业版用户，提供选择不同 AI 模型（如 Claude Haiku）的选项，以平衡成本与质量。
4. 解锁推广渠道：继续在 Reddit 和 Hacker News 上合规地提升账号信誉，为后续正式发布做准备。
5. 功能深化：考虑添加“自定义描述模板”、“支持.prdraftrc配置文件进行仓库级规则设置”、“与 Jira/Linear 等 issue 关联”等高级功能，这些将是专业版的核心价值。

构建一个工具，从解决自己的一个小烦恼开始，看着它被另一个人使用并认可，这种体验无与伦比。即使前路还有支付、增长、竞争等诸多挑战，但这8天从零到一的旅程，已经验证了最初那个“偷懒”想法的价值。如果你也厌倦了重复撰写 PR 描述，不妨试试 PRDraft ，免费额度足够你体验它的核心价值。任何反馈，都是这个产品继续成长最重要的养分。