周末好不容易把一个功能写完本地一跑测试全绿心里那块石头刚落地结果手放到键盘上准备git commit脑子突然一片空白——提交信息写什么“fix bug”“update code”还是干脆来一串省略号这种场景我太熟了甚至见过不少同事在提交信息里只打一个“。”。社区里大家管这叫“提交信息尴尬症”症状是代码写得越漂亮提交信息越敷衍。这篇文章就是聊怎么用AI自动生成Git提交信息把“fix bug”这种无效信息彻底从提交历史里扫出去。我会把背后的技术原理、可复制的完整脚本、以及本地模型、钩子校验这类进阶玩法一次讲透适合所有用Git做版本管理的开发者——不管你是刚入行的新手还是被烂提交历史折磨了多年的老油条。1. 提交信息为什么重要先算一笔“烂历史”的账1.1 一条fix bug让三天的排查白费很多人觉得提交信息是给Git看的、是走个流程其实它是写给人看的——给三天后的自己给半年后接手项目的同事。我印象最深的一次线上接口突然500第一反应就是git log看最近动了什么结果满屏的fix bug、update、again根本分不清哪条挨着哪条。最后只能靠git blame逐行比对代码硬生生把三分钟能定位的问题拖成了三个小时。提交历史就是一个项目的黑匣子里面记录着每一行代码为什么存在。git revert想回滚某个功能得先知道哪条提交对应哪个功能git bisect想二分定位回归版本得先能读懂提交粒度代码review时评审人看你的commit理解了你的意图信息不到位他只能去猜。这些场景全都依赖同一个东西提交信息写得清楚不清楚。说白了提交信息是廉价的文档。代码注释容易被删、文档容易过期但提交历史永久跟着仓库走。你花十秒钟写清楚一条信息未来能替整个团队省下大量翻代码的时间。这笔账怎么看都划算。1.2 Conventional Commits规范到底在规范什么既然提交信息这么重要业内当然早就给出了一套标准最主流的就是Conventional Commits规范。它的核心格式很简单type(scope): description也就是“类型(影响范围): 描述”。常见的type大概有下面这些type含义示例feat新功能feat(user): 增加用户注册功能fix修复bugfix(order): 修复订单金额精度丢失问题docs文档变更docs(readme): 补充安装说明style格式调整style(auth): 调整登录页代码缩进refactor重构不改功能refactor(api): 抽取统一请求封装perf性能优化perf(list): 优化长列表滚动卡顿test测试相关test(cart): 补充购物车结算用例build构建系统build(deps): 升级打包依赖ciCI配置ci: 增加构建缓存chore其他杂项chore: 清理无用注释很多人会问fix bug也算fix开头为什么不合格因为它只说了“我修了bug”没说清了什么bug、在哪个模块、怎么修的。规范的核心不是形式而是信息量。fix(user): 修复用户名含空格时无法登录的问题和fix bug之间的差距就是规范存在的意义。1.3 写不出好提交信息不全是懒的问题我观察了很久团队里不是大家不想写规范提交信息而是有几个很现实的原因。第一个是认知负担代码刚写完大脑还在处理“怎么实现”的细节突然要切换到“怎么总结”的频道切换成本很高。第二个是语言组织能力用中文怕不专业用英文怕语法错最后干脆放弃治疗。第三个是缺少反馈机制——项目里没有强制校验写什么都照样能提交那谁还愿意动脑。这三个原因凑在一起导致了经典的“提交信息摆烂循环”写得越烂越不想写越不想写历史越烂历史越烂越觉得提交信息不重要。要打破这个循环靠自觉基本不可能得靠工具。而这恰恰是LLM最擅长的事情给它一段git diff让它用规范的格式总结出人话比让一个刚写完代码、脑子还处于“编译器模式”的人自己组织语言靠谱得多。2. AI怎么理解你的代码变更生成提交信息的技术原理2.1 核心链路diff提取、提示词构造、模型调用AI自动生成提交信息听起来很玄乎拆开看核心链路就三步。第一步拿到“变更了什么”。Git里最直接表达变更的东西就是diffgit diff --cached能输出暂存区相对当前HEAD的所有改动包括改了哪个文件、哪一行、从什么变成了什么。第二步把diff塞进提示词里让大模型根据diff生成提交信息。第三步调用大模型的API拿到结果解析成正式的commit message。这里有个关键细节为什么用的是--cached而不是直接git diff因为git commit默认提交的本来就是暂存区里的内容AI生成信息的依据必须和最终提交的东西一致。否则你这边diff是工作区全部改动那边commit只提交了暂存区一部分生成的信息和实际提交对不上反而更乱。提示词构造是这个链路里最考功夫的地方。一段合格的提示词至少要包含几个要素明确角色你是一名资深开发者、明确格式第一行必须是type(scope): description、明确禁止项不允许出现“fix bug”“update”这类无效描述、以及一个few-shot示例。模型看到这样的提示词才知道你要的不是聊天式回复而是一条可直接落地的提交信息。2.2 三个绕不开的工程难点原理听起来简单真正实现的时候改文件数量上去了问题就来了。第一个难点是diff太长。一个改动涉及几十个文件、上万行diff时模型上下文窗口根本装不下即使装得下模型也会“迷失”在细节里生成的总结反而抓不住重点。后面我会细讲应对策略核心就四个字截断、压缩。第二个难点是上下文不足。大模型只看到代码层面的变化并不知道你为什么要改。比如你为了修一个线上bug把某个接口的超时时间从3秒改成了10秒模型从diff里只能看到“修改了超时时间”很难推断出“修复了弱网环境下接口频繁超时的问题”。解决办法是在prompt里补充历史提交信息作为风格参考或者让模型结合函数名、注释来推断意图。第三个难点是输出不可控。同一个模型这次可能给你输出中文下次可能输出英文甚至可能输出一堆解释性废话。想要稳定就得在提示词里反复强调“只输出提交信息本身”加few-shot示例约束格式再把temperature调低让模型尽量少自由发挥。2.3 现成工具与自建脚本我为什么选后者现在想用AI生成提交信息现成方案其实不少。很多AI编程助手内置了生成commit message的功能GitHub上也有不少开源CLI工具装一下就能用。这些方案的优势是开箱即用适合不想折腾、一个人写项目的场景。但我最后还是选择了自己写脚本原因是现成工具普遍有几个痛点一是绑定特定模型厂商想换成团队内部部署的大模型得看工具脸色二是提示词不可控生成风格和团队规范经常对不上三是把代码发送到外部API的隐私透明度不明确很多开发者心里没底。自建脚本虽然前期要花半小时写代码但换来的是完全可控我可以自定义提示词、切换任意模型、在发请求前做敏感信息检查、挂到Git钩子上做自动化校验。对于团队使用来说自建方案的可维护性和可解释性都更胜一筹。3. 手写AI提交助手从diff到commit的完整实现3.1 环境准备与最小依赖在动手写代码之前先确认三件事。第一机器上装了Python 3.9以上版本这个基本都满足。第二有一个大模型API的访问密钥当前市面上主流的模型服务商基本都提供OpenAI兼容接口这让我下面的脚本可以通吃。如果你不想用云端API后面第4章会讲怎么接本地模型代码完全不用改。第三装一个Python的requests库这是唯一的第三方依赖用来发HTTP请求。脚本我建议放在~/scripts/ai-commit/目录下面文件名就叫ai_commit.py。以后不管在哪个项目里都能用alias直接调用不用每个项目复制一份。这个目录结构就是为了让脚本变成你日常开发的“基础设施”而非某个项目的一次性工具。3.2 核心代码实现与解析下面是一份完整的实现我强烈建议你亲自跑一遍边跑边改。脚本的逻辑分四块提取暂存区diff、构造请求、调用模型、交互确认后提交。我逐段解释关键点。#!/usr/bin/env python3 import argparse import os import re import subprocess import sys import requests SYSTEM_PROMPT 你是一名资深开发者专门帮团队写规范、清晰的Git提交信息。 请根据用户提供的git diff生成一条符合Conventional Commits规范的提交信息。 严格遵循以下要求 1. 第一行是提交主题格式为type(scope): description 2. type只能从以下范围选择feat、fix、docs、style、refactor、perf、test、build、ci、chore 3. description使用中文控制在50个汉字以内禁止出现fix bugupdate这类无信息量描述 4. 如果diff体现不出明确的业务场景就根据代码变更推断一个合理的描述 5. 不要解释、不要自我介绍只输出提交信息本身 USER_PROMPT_TEMPLATE 以下是最新的git暂存区diff {diff} 请根据该diff生成提交信息。 def run_git(*args: str) - str: result subprocess.run( [git, *args], capture_outputTrue, textTrue, encodingutf-8, checkFalse, ) return result.stdout def get_staged_diff() - str: stat run_git(diff, --cached, --stat) diff run_git(diff, --cached, --unified3) if not diff.strip(): return return stat \n diff def truncate_diff(diff: str, max_chars: int 12000) - str: if len(diff) max_chars: return diff return diff[:max_chars] \n\n[diff过长已截断请基于可见部分生成提交信息] def call_llm(prompt: str, base_url: str, api_key: str, model: str) - str: url base_url.rstrip(/) /chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: model, messages: [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: prompt}, ], temperature: 0.2, } try: resp requests.post(url, jsonpayload, headersheaders, timeout30) resp.raise_for_status() data resp.json() return data[choices][0][message][content].strip() except Exception as e: print(f[error] 调用模型失败: {e}) sys.exit(1) def parse_message(text: str) - str: # 去掉可能的包裹避免模型把结果包进markdown代码块 text re.sub(r^[a-zA-Z]*\n, , text.strip()) text re.sub(r\n$, , text) lines [line.rstrip() for line in text.splitlines() if line.strip()] return \n.join(lines) def main() - None: parser argparse.ArgumentParser(descriptionAI自动生成Git提交信息) parser.add_argument(--model, defaultos.getenv(AI_COMMIT_MODEL, gpt-4o-mini)) parser.add_argument(--base-url, defaultos.getenv(AI_COMMIT_BASE_URL, https://api.openai.com/v1)) parser.add_argument(--api-key, defaultos.getenv(AI_COMMIT_API_KEY)) parser.add_argument(--max-chars, typeint, default12000) args parser.parse_args() if not args.api_key: print(未找到API Key请设置AI_COMMIT_API_KEY环境变量后再运行。) sys.exit(1) diff get_staged_diff() if not diff.strip(): print(暂存区没有发现变更请先执行 git add 把改动加入暂存区。) sys.exit(1) diff truncate_diff(diff, args.max_chars) prompt USER_PROMPT_TEMPLATE.format(diffdiff) print(正在根据暂存区diff生成提交信息...) message parse_message(call_llm(prompt, args.base_url, args.api_key, args.model)) print(\n生成的提交信息如下\n) print(message) print() answer input(是否确认提交[Y/n] ).strip().lower() if answer in (n, no): print(已取消提交信息已保留在上方。) sys.exit(0) proc subprocess.run([git, commit, -F, -], inputmessage, textTrue, capture_outputTrue) print(proc.stdout) if proc.returncode ! 0: print(proc.stderr) sys.exit(proc.returncode) if __name__ __main__: main()代码里有两个用了之后回不去的细节。第一个是--unified3它控制diff里每个改动块上下各保留几行上下文。默认值通常也是3但显式写出来更稳妥这个参数直接决定了diff的信息密度上下文太少模型看不懂太多又浪费token。第二个是提交时用git commit -F -而不是-m-F -表示从标准输入读取提交信息这样多行message能原样保留不会因为Shell的引号转义问题被截断。temperature0.2是我实测下来比较稳定的设置。生成提交信息不是创作类任务不需要太多随机性温度越低模型越倾向于输出保守、规范的文本反复生成的结果一致性也越高。想让模型更有“创意”地描述你的改动没必要提交信息要的是准确不是文采。3.3 接入日常流程alias与git钩子脚本写得再漂亮如果每次都要敲一长串python命令你也坚持不了几天。接入日常流程第一步是配alias把核心命令缩短。alias ai-commitpython3 ~/scripts/ai-commit/ai_commit.py再把环境变量写进shell配置文件.zshrc或.bashrc这样就不用每次export了export AI_COMMIT_API_KEYsk-你的密钥 export AI_COMMIT_API_BASEhttps://api.deepseek.com/v1 export AI_COMMIT_MODELdeepseek-chat我日常的使用流程基本是三条命令git add -A把改动全部加入暂存区ai-commit唤起脚本生成提交信息确认后自动commit。如果你连add都想省可以在shell配置里加个函数function gac() { git add -A python3 ~/scripts/ai-commit/ai_commit.py }我自己习惯保留“确认提交”这一步不做全自动。AI生成的提交信息偶尔会有偏差尤其在改动比较复杂、涉及多个业务点的时候生成的信息可能只覆盖了其中一部分。多花两秒钟扫一眼能避免把一个糟糕的提交信息写进永久历史。进阶一点你还可以把脚本接到Git的prepare-commit-msg钩子上。这个钩子会在提交信息编辑器打开之前被调用你把AI生成的内容写入提交信息文件打开编辑器时就已经自动填好了你只需要改改不满意的地方再保存。不过这属于锦上添花我建议先跑熟命令行版本再加钩子。4. 进阶玩法本地模型、强校验与changelog自动化4.1 接本地模型Ollama代码不出本机前面讲到的方案默认是把diff发给云端API很多团队会担心代码安全性尤其是还没公开的产品功能或者包含敏感算法的仓库。解决这个顾虑的思路很简单用本地模型让代码不出本机。当前比较成熟的本地模型运行方式是Ollama装好之后直接在终端拉取一个代码模型比如qwen2.5-coder:7b然后它会在本地起一个兼容OpenAI格式的接口。这意味着我前面写的脚本完全不用改只要把AI_COMMIT_BASE_URL指向本机地址、把模型名换成本地模型就行export AI_COMMIT_API_BASEhttp://localhost:11434/v1 export AI_COMMIT_MODELqwen2.5-coder:7b实测下来的感受是本地7B模型生成的提交信息在“规范化”这个层面完全不输大厂的旗舰模型type选得准、格式稳定只是对复杂业务逻辑的概括能力稍微弱一点偶尔会漏掉一些改动点。但大多数提交场景的diff并没有那么复杂本地模型完全能扛住。如果你机器显存足够推荐至少8GB以上这是一个兼顾隐私和成本的优秀方案。4.2 commit-msg钩子烂信息直接拒收AI帮你生成好提交信息只是第一步整个团队如果还有人继续写“fix bug”你的提交历史依然会慢慢腐烂。治本的办法是在commit发生的那一刻就做校验——用Git的commit-msg钩子拦截不符合规范的提交信息。钩子的逻辑很简单读取提交信息的第一行用正则判断是否符合type(scope): description格式不符合就直接返回非零状态码Git会拒绝这次提交。我在团队里实践过一个Python版本#!/usr/bin/env python3 import re import sys msg_file sys.argv[1] with open(msg_file, encodingutf-8) as f: first_line f.readline().strip() pattern r^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\(.\))?: . if not re.match(pattern, first_line): print([blocked] 提交信息不符合Conventional Commits规范) print(请使用格式type(scope): description) print(例如feat(user): 增加用户注册功能) sys.exit(1)默认情况下Git项目里的hooks目录.git/hooks是不跟着仓库走的团队协作时想要共享钩子需要把钩子放到项目内的一个目录比如.githooks然后执行git config core.hooksPath .githooks。这样每个克隆了仓库的人都会自动使用这套校验规则。嫌手动配置麻烦的话前端项目可以用husky、Python项目可以用pre-commit框架这些工具的底层都是同一个机制。有了这层强制校验AI生成的信息质量就有了制度保障——毕竟AI可以按规范输出人却不一定。4.3 规范提交历史的“复利”自动生成changelog提交信息规范化最大的复利是它能让changelog自动生成。当我们把每一笔提交都写成feat(user): xxx、fix(order): xxx这种格式后Git提交历史本质上就变成了一个结构化的变更日志剩下的事情只需要交给工具去归纳。后端工具里我用过git-cliff前端生态里更常见的是standard-version或semantic-release。它们做的事情类似读取两个版本标签之间的所有提交按照type分类自动生成一个CHANGELOG.mdfeat开头的进“新功能”板块fix开头的进“Bug修复”板块其他类型归到对应分类。整个过程中你不需要手工维护任何文档发版前跑一条命令就够了。这个效果对个人项目可能不明显但对商业项目意义很大。产品经理看changelog能知道这个版本到底加了什么能力运维看changelog能评估升级风险测试看changelog能圈定回归范围。所有这些都建立在提交信息足够规范的基础上。AI把“写规范提交信息”这件事的成本降到了零changelog自动化才有了真正落地的可能。5. 实操踩坑与问题排查速查5.1 diff太大把模型打爆怎么办AI提交助手用起来最头疼的一个问题是改动一大diff就会超长轻则模型报错“超出上下文长度”重则脚本直接超时崩溃。我自己的项目曾经一次改了两百多个文件diff几万行发出去直接被API拒绝。对付这个问题有几个实用的手段可以叠加使用。第一在diff超长时优先截断只把前面一部分发给模型并在prompt末尾加一句“diff过长已截断请基于可见部分总结”实测效果比不截断但模型崩溃要好得多。第二调整--unified1把上下文行数从3行压缩到1行能显著减小diff体积。第三把大改动拆成多个逻辑单元分别提交这本身也符合“原子提交”的最佳实践每个小提交分别生成信息质量反而更高。如果你经常遇到超大diff建议在脚本里把--max-chars调低一些。我更推荐从一开始就养成“小步提交”的习惯一次提交只解决一个问题这样不仅AI生成信息更准确代码review也更舒服。5.2 生成的type选错了、语言飘了怎么办模型生成的信息稳定运行一段时间后你可能会发现偶尔有type选错的情况比如把一次重构写成了feat把文档更新写成了chore。这类问题根源一般在提示词上type之间的边界对模型来说本来就是模糊的需要更明确的规则。解决办法是在system prompt里补充更细的判定标准例如“改动涉及对外功能变化时用feat修复已有功能缺陷时用fix不改变行为的代码整理用refactor”。如果你发现自己团队的场景比较特殊完全可以定制一套自己的type词汇表只要钩子和changelog工具同步调整就行。还有一个更隐蔽的问题是语言风格漂移。模型偶尔会混着英文和中文输出或者把描述写得像散文。这时候可以把最近5条提交记录加到prompt里作为风格参考让模型模仿团队的历史风格。同时也推荐把--max-chars和temperature固定下来减少生成结果的随机波动。5.3 隐私安全代码真的要发给云端吗这个问题的答案取决于你的仓库性质但我强烈建议在方案里加上一道“安全检查闸门”。最基础的做法是在发送diff之前用一组敏感词正则去匹配diff内容比如密码、密钥、Token、私钥头等关键词一旦命中就立刻终止发送提示开发者先处理敏感信息。SENSITIVE_WORDS [password, secret, api_key, token, BEGIN RSA PRIVATE KEY] def has_sensitive(diff: str) - bool: return any(word in diff.lower() for word in SENSITIVE_WORDS)即使程序里有这道闸门也不代表你可以放心往云端API里传所有代码。公司的核心算法、未上市的版本功能、包含用户隐私的代码段这些内容严格来说都不应该出现在第三方服务的日志里。实在需要AI辅助、又对隐私极度敏感的场景就老老实实用本地模型方案这是当下最稳妥的解。5.4 断网、误改暂存区、脚本出错的兜底自动化流程最怕的就是跑着跑着出错尤其是断网或者API限流可能导致脚本报错退出。但这里有个容易被忽略的点脚本在任何一步出错时都没有自动提交兜底的逻辑所以即使模型挂了你也只是回到了手动git commit的状态不会把一份没经过确认的信息强行写进历史。这种“失败放行”的设计在开发工具里往往比“失败拦截”更安全。遇到过几次API超时后我总结出的一个经验是不要依赖AI处理紧急提交。线上hotfix、临时的配置调整、需要马上提交的改动直接用编辑器手写提交信息反而更快。AI提交助手适合日常开发节奏不适合救火场景。还有一个小坑提醒一下如果你在脚本运行前已经执行过git add但后来又改了工作区文件脚本读取的暂存区diff和当前文件内容可能不一致。所以别在git add之后继续改文件要改就改完再add。这些细节平时不太起眼但踩过一次之后就会记得特别牢。我个人用这套方案半年后的最大感受是提交历史终于变成了一份能看的项目日志。回看三个月前的提交每一条都能快速知道当时做了什么、为什么做配合自动生成的changelog发版说明再也不用靠回忆去凑。AI不是万能的它偶尔也会漏掉改动的深层意图但至少它帮我守住了“提交信息必须可读”这条底线。如果你也想告别满屏的 “fix bug”我的建议是先从今天的一次提交开始用这个脚本跑一次你会立刻发现原来提交信息写得清楚并不难难的是你一直以为这事只能靠自觉。