git-ai实战：用大模型自动生成规范的Git提交信息

1. 先说说我为什么会对 git-ai 这类工具“上头”

如果你打开自己几年前项目的 git log，看到一整屏只有 “update”“fix”“ 1” 这样的提交记录，大概就能理解我在看到 git-ai 项目时为什么有点反应。提交信息这件事，看起来是小事，却在每次回溯版本、写周报、做 Code Review 的时候反复惩罚你。git-ai 并不是某个新语言或新框架，它是把 LLM 的能力接到 Git 工作流里的小工具，核心功能听起来很简单：自动分析你改动的代码，然后生成符合规范的提交信息。但它实际能覆盖的场景远不止 commit message。

我最早注意到这类项目，是因为自己维护一个小开源仓库。那段时间状态差，提交记录大概是这样的：

code复制$ git log --oneline -8
a1f2b3c fix bug
d4e5f6a update
7b8c9d0 update
e1f2a3b fix bug

虽然只有我自己一个人看，但真到了要准备 release note 的时候，我完全不记得哪次提交干了什么，只能逐个 commit 打开 diff 重新回忆。那一下午我大概明白了一个道理：提交信息本质上是在给未来的自己写注释，而大多数开发者包括我都欠下了不少“注释债”。git-ai 这类工具之所以有价值，不是因为它会用 AI 替你打字，而是它逼着整个工作流变成一个可回溯、可理解、可审查的结构化过程。如果你也在维护长期项目、和团队协作，或者只是受不了自己懒散的提交记录，这篇文章里的思路可以直接拿来用。

2. 先说运作逻辑：git-ai 到底“看”了什么，又是怎么开口的

2.1 为什么很多这类工具要求你先 git add

我用 git-ai 这类命令行工具时注意到的第一件事是：它通常要求你先 git add 暂存文件，然后才分析改动。这不是故意折腾人，背后是 Git 工作区模型的差异。普通 git diff 对比的是工作区和暂存区之间的改动，而 git diff --cached 对比的才是暂存区与最近一次提交之间的改动，也就是你明确告诉 Git“这次我要提交这些”的那部分内容。工具读取后者的原因很简单：一个干净、边界清晰的输入，比让 AI 自己猜哪些文件要进这次提交靠谱得多。

我在项目里有过一次很直观的教训。当时同时改了两个需求：一个给用户接口加了鉴权，另一个重构了日志工具。如果直接对整个工作区的 diff 跑自动提交信息，LLM 很可能把两件事揉成一个“refactor: improve auth and logging”这种四不像描述。但先逐个文件 git add，再分别生成提交信息，得到的就是两条干净的 feat(auth): add JWT validation 和 refactor(logging): extract LoggerFactory utility。这其实是把“控制提交粒度”这个原本就属于 Git 基本素养的动作，从自觉变成了流程约束。

2.2 输入与输出：一次标准调用的内部路径

如果你好奇一条提交信息到底是怎样生成的，可以把这类工具的内部流程拆成四步。第一步是收集三块信息：diff 内容、仓库中已有的提交历史样本、当前分支名称；第二步是把它们套进一个提示词模板，模板会规定输出格式；第三步是调用 LLM 拿到候选提交信息；第四步是解析结果并展示给用户确认。

这里有一个很容易被忽略的细节：提示词模板里写了什么，决定了生成质量的下限。我见过的优秀实现对 commit message 的格式约束非常细，比如类型必须从 feat / fix / refactor / docs / test / chore / perf 这些 Conventional Commits 类型里面选，scope 不能超过一定长度，正文要用祈使句开头，且必须解释“为什么改”而不是复述代码。相比之下，如果用一句话“帮我写个提交说明”这种裸提示词，模型确实也会写，但风格全看命，可能出来一句完全没有信息的 “update code”。

很多 git-ai 类工具默认不是让模型自由发挥文本，而是要求它输出 JSON，例如：

json复制{
  "type": "feat",
  "scope": "auth",
  "subject": "add JWT-based session validati