小丸子书单1. 项目背景与核心问题
1.1 为什么需要 git-ai
先聊聊写 commit message 这件事。我做了十多年开发，带过不少团队，见过太多提交记录了："fix bug"、"update"、"改了点东西"、"commit"。你翻三个月前的代码，看到这种提交信息，基本上只能靠猜。要是赶上重构或者 bug 修复，那排查起来更是欲哭无泪。
其实大家心里都清楚，规范提交信息很重要，但真正做到的人凤毛麟角。原因很简单：写一条好的 commit message 需要时间。你得回顾自己改了哪些文件、每个文件动了什么逻辑、这次改动解决了什么问题、有没有连带影响。这些事做完，少说三五分钟，多的可能要十来分钟。手头正写着代码，思路不能断，谁会愿意停下来花十分钟写这个？
git-ai 项目解决的正是这个问题。它利用大语言模型的能力，自动分析你暂存区的代码变更，生成结构清晰、语义准确的提交信息。说白了，就是把"写提交信息"这件事从"人肉苦力活"变成了"AI 一键生成"。开发者的思路不被中断，提交记录的质量反而更高了，这两全其美的事，就是 git-ai 存在的核心价值。
有人可能会说，这不就是套壳调用 ChatGPT 吗？真要上手做你会发现，事情没这么简单。一个能落地的 git-ai 工具，要处理的问题远比想象中多得多。
1.2 这个项目适合谁参考
我写这篇文章，想覆盖三类读者：
第一类是普通开发者，每天都要用 git 提交代码，被提交信息折磨过，想找一个提升效率的工具。这类读者可以直接跳到第 3 节的安装配置和实操部分，照着步骤走就能用起来。
第二类是想自己实现类似工具的技术爱好者。他们可能好奇 git-ai 内部是怎么工作的，比如如何获取 diff、如何构造 prompt、如何处理超长 diff、如何调用模型 API。这类读者可以重点看第 2 节的设计拆解和第 4 节的实现细节。
第三类是团队技术负责人或工具链开发者。他们关注的是如何在团队里推广这类工具、如何保证生成质量稳定、如何与企业内部的代码托管平台集成。这类读者建议通读全文，尤其是最后的踩坑经验部分。
git-ai 这个方向准确来说是"AI 辅助开发工具链"中的一个细分场景。这类工具这两年发展很快，从代码补全到自动修 bug，再到提交信息生成，AI 正在渗透到开发流程的每个环节。但正因为参与者多，做得好的少，所以值得仔细研究一下其中的设计思路和工程细节。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 整体设计与技术选型分析
2.1 git-ai 的工作流程拆解
一个完整的 git-ai 工具，工作流程大致是：读取暂存区 diff → 对 diff 进行预处理和截断 → 构造 prompt → 调用大模型 API → 解析模型返回结果 → 以交互方式确认或直接写入提交信息。
这个流程听起来简单，但每一步都有不少细节要考虑。我先按模块拆开来讲。
获取 diff 这一步，核心是执行 git diff --cached 命令。--cached 参数的意思是只看暂存区（也就是你已经 git add 过的内容）和当前 HEAD 之间的差异。这里有一个很重要的设计决策：是分析暂存区的 diff，还是分析工作区的 diff？
我见过一些早期版本的同类工具选择分析工作区全部改动，结果生成的信息经常包含调试代码、临时文件之类的噪音。相比之下，只分析暂存区是更合理的做法，因为"暂存"这个动作本身就带有意图——你决定把哪些改动放进这次提交，AI 只需要理解这个意图就够了。这也是 git-ai 和很多同类工具保持一致的原则。
diff 数据拿到之后，紧接着就是模型调用前的预处理。绝大多数大模型 API 有 token 限制，而一个大型重构的 diff 可能轻松超过几万 token。如果不做处理，直接一股脑丢给模型，大概率会报错。常见的处理策略有几种：按文件拆分成多条请求，每条请求只分析一个文件的改动；按 diff 的统计信息做摘要，比如只保留新增函数名和修改文件列表；或者用滑动窗口截取关键片段。
实践下来，按文件拆分是最实用的方案。理由很简单：一条 commit message 通常需要概括多个文件的改动，而单个文件的 diff 往往相对可控。更聪明的做法是对每个文件生成一句摘要，再让模型基于所有文件的摘要生成最终的整体提交信息。这种两阶段的思路，既解决了超长问题，又提升了信息浓缩的准确度，代价是多了一次 API 调用。
再往后就是 prompt 设计。不要小看这一步，同样的模型，prompt 写得好不好，生成质量可以差出一大截。
2.2 prompt 设计的关键经验
我给 git-ai 类工具写 prompt 的经验总结成一句话：让模型"先理解、再概括、后规范"。
所谓"先理解"，是让模型先看到具体的 diff 内容，理解这次改动的真实意图。很多 AI 生成 commit message 的翻车案例，问题都出在模型根本没有理解代码层面的变化，只是拿着文件名硬编。所以 prompt 里一定要包含完整的 diff 片段，而且最好按照"每个文件的变更独立分段"的方式来组织。
"再概括"是让模型先把每个文件的改动用一两句自然语言描述出来，再做整体归纳。这一步的作用是降低模型的认知负担。你让模型直接从一个 500 行的 diff 里提炼出 10 个词以内的 commit message，它往往顾此失彼；但如果让它先写每个文件的改动摘要，再基于摘要汇总，准确性会提升很多。这个概念在学术上叫 chain of thought，用在 commit 生成上同样有效。
"后规范"是最后要求模型按照指定格式输出。格式可以是 Conventional Commits 规范（就是 feat、fix、docs 这种前缀），也可以是团队自定义的格式。在 prompt 中给出模板和示例是最有效的手段，模型对示例的模仿能力比纯规则描述强得多。我还建议在 prompt 里明确禁用某些词，比如"update"、"fix"这种过于宽泛的描述，强制模型给出具体说明。
这里给一个参考 prompt 骨架：
code复制你是一名资深工程师。请根据以下代码变更（git diff）生成一条简洁清晰的提交信息。
变更内容：
{diff_content}
要求：
1. 先分析每个文件改动的目的
2. 使用 Conventional Commits 规范，类型限定为 feat/fix/docs/refactor/perf/style/chore
3. 第一行为标题，不超过 50 个字符
4. 如有必要，空一行后写正文，说明改动的影响范围
5. 禁止使用 "update"、"fix bug" 这类模糊描述
这种结构化的 prompt 生成效果相对稳定。如果你想让模型输出 JSON，方便程序解析，可以在 prompt 里指定输出格式。
2.3 模型选型：本地模型还是云端 API
模型选型是 git-ai 类工具最核心的技术决策之一。当前主要分两个阵营：云端大模型 API，比如 OpenAI 的 GPT 系列、通义千问、文心一言等厂商服务；本地模型，比如通过 Ollama 运行的 Qwen、Llama 系列。
云端 API 的优势是理解能力强，git diff 这种代码理解任务对模型的逻辑推理要求不低，体型较小的本地模型容易生成似是而非的描述。而且云端 API 基本都有现成的 SDK，接入成本低。缺点也很明显：代码要发到外部服务，有数据安全顾虑；每次调用