git-ai：基于大语言模型自动生成规范Git提交信息的工程实践

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 正在渗透到开发流程的每个环节。但正因为参与者多，做得好的少，所以值得仔细研究一下其中的设计思路和工程细节。

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，接入成本低。缺点也很明显：代码要发到外部服务，有数据安全顾虑；每次调用有网络延迟；如果团队在私有化环境开发，可能根本访问不了外部 API。

本地模型的优势恰好是私密性和零网络依赖。但如果你试过跑本地模型做 commit 生成，你会发现两个尴尬的问题：一是模型参数量如果低于 7B，理解复杂 diff 的能力明显不够，经常把重构识别成新增功能；二是本地模型推理速度慢，生成一条信息可能要等十几秒甚至更久，体验大打折扣。

我的建议是：个人开发者优先用云端 API，省心且质量有保障；企业内网环境可以做一个可插拔的模型适配层，云端和本地都支持，用户通过配置文件自由切换。git-ai 这类工具的架构里，模型服务抽象层是不可省的模块，否则一旦换模型，整个工具的代码都得跟着改。

3. 工具选型与基础环境搭建

3.1 开发语言与依赖选择

实现 git-ai 项目，开发语言的选择会影响后续的工具分发、跨平台兼容性和维护成本。目前社区里的同类工具，主流方案是 Python 和 Node.js 各占半壁江山。两个选择都有道理：Python 生态里调用大模型 API 的库最成熟，写脚本类工具最顺；Node.js 则更贴合前端开发者的习惯，而且可以借助 npm 快速发布和安装。

我个人的偏好是 Python。原因不是 Node.js 不行，而是这类工具的核心是"文本处理 + HTTP 请求 + 命令行交互"，Python 在这个领域几乎没有样板代码。你不需要像 Node.js 那样关心异步回调，也不用处理各种回调地狱。写一个几千行的命令行工具，Python 的代码量通常比 Node.js 少三分之一左右。

具体依赖方面，核心库就两个：一个是调用大模型的 SDK（不同的模型服务对应不同的 SDK，也可以直接用 httpx 发请求，减少对特定厂商的绑定）；另一个是命令行交互库，比如 Python 的 click 或 argparse，用来解析参数和美化输出。如果你做的是交互式确认功能（就是生成完提交信息让用户选择"确认提交"还是"重新生成"），可以用 rich 库来实现终端 UI，效果会专业很多。

我给一个最小化依赖清单参考：

尽量控制依赖数量。命令行工具要做长期维护，依赖越少，将来升级折腾的空间越小。

3.2 环境准备与安装步骤

先说安装 git-ai 的前置条件。由于它本质上是"读取 git 信息 + 调用模型 API"的拼接工具，所以系统里必须已经装好 git，并且你需要在 git 仓库里执行命令。这个工具不会初始化仓库，它默认你已经在某个项目目录里进入工作状态了。

假设我们用的是 Python 方案，安装步骤通常是这样：

bash复制# 创建虚拟环境（推荐，避免污染系统 Python）
python3 -m venv .venv
source .venv/bin/activate

# 安装项目依赖
pip install -r requirements.txt

# 安装为命令行工具
pip install -e .

这里有个细节想提醒你：不要图省事直接全局 pip install。如果你同时维护多个 Python 项目，全局安装容易导致依赖冲突。创建一个项目专属的虚拟环境，或者用 pipx 安装这类命令行工具，是更稳妥的做法。

安装完成后，需要配置模型服务的 API Key 和相关参数。我建议在项目根目录创建一个 .git-ai.toml 配置文件，支持两种配置来源：环境变量优先级最高，其次是配置文件，最后是内置默认值。这样做的好处是方便 CI/CD 集成——在流水线里通过环境变量注入密钥，不用把密钥写死在文件里。

toml复制[model]
provider = "openai"          # 模型服务商
model_name = "gpt-4o-mini"   # 模型名称
temperature = 0.3            # 采样温度，提交信息生成建议偏低

[git]
diff_stat = true             # 是否使用 --stat 统计信息
max_diff_length = 12000      # 单次发送给模型的 diff 最大字符数

[output]
lang = "zh"                  # 提交信息语言

temperature 这个参数值得单独说一下。很多人在生成 commit message 时喜欢把 temperature 调到 0.8 甚至 1.0，希望模型"更有创意"。这其实是误区。提交信息是严肃的工程文档，要求的是准确、简洁、可复现，不是创意写作。建议调到 0.2 到 0.4 之间，让模型输出尽量稳定可控。

配置好之后，在 git 仓库里执行：

bash复制git add .
git-ai commit

正常情况下，你会看到工具先展示生成的提交信息预览，接着询问是否确认。确认后工具会帮你执行 git commit，提交就完成了。

4. 核心实现与实操过程拆解

4.1 获取 git diff 的完整流程

实际写代码的时候，第一步永远是构造 git 命令，然后处理返回结果。我用的是 subprocess 模块来执行命令，这样最直接，不用额外引入 GitPython 这类库。GitPython 虽然封装了 Git 操作，但底层也是调命令行，反而多了一层复杂度。

在 git_commands.py 里定义一个执行命令的函数：

python复制import subprocess
import json

def run_git_command(args: list[str]) -> str:
    """执行 git 命令并返回标准输出，失败时抛出异常。"""
    result = subprocess.run(
        ["git", *args],
        capture_output=True,
        text=True,
        encoding="utf-8",
    )
    if result.returncode != 0:
        raise RuntimeError(f"git command failed: {result.stderr}")
    return result.stdout.strip()

获取暂存区的 diff，对应命令是：

bash复制git diff --cached --stat
git diff --cached

这里解释一下为什么两个命令都要执行。--stat 拿到的是变更统计信息，包括哪些文件有改动、增删了多少行。这个信息的特点是短小精悍，几十个文件的改动加起来也就几百个字符，不会撑爆 token 限制。而完整的 git diff --cached 输出才能提供真正的代码变化细节。在 prompt 中，我通常把两者结合使用：先用 stat 让模型了解整体变更范围，再用具体的 diff 片段让模型理解代码变化。

在实际拿到 diff 后，你可能需要对内容做清洗。比如有些仓库的 diff 里包含二进制文件的乱码标识，或者包含了大量的锁文件（package-lock.json、poetry.lock 这类）变化。这些内容既浪费 token，又严重干扰模型对真实改动的理解。在交给模型之前过滤掉这些噪音，是提升输出质量的重要技巧。

过滤的思路是维护一个忽略列表，把常见的生成文件、锁文件、编译产物排除在外。你可以在配置里增加一个 ignore_paths 字段，默认规则覆盖常见的 dist/、node_modules/、*.lock 等模式。注意，这里的忽略只是在生成 commit message 时忽略，并不会影响 git add 和 git commit 的实际行为，所以不会产生"漏提交"的安全风险。

4.2 prompt 构造与模型调用

拿到干净的 diff 之后，prompt 的构造逻辑就很关键了。我建议不要把整个 prompt 写死在代码里，而是拆成几个模板文件或函数，方便调试。

我的实现里有一个 build_prompt(diff_stat, diff_text, lang="zh") 函数，返回拼装好的完整 prompt 字符串。核心部分如下：

python复制SYSTEM_PROMPT = """你是一名经验丰富的软件工程师。你的任务是根据用户提供的 git diff 内容，生成符合规范、语义准确的 git commit message。

遵循以下规则：
1. 类型只能是 feat、fix、docs、refactor、perf、style、chore 之一
2. 标题不超过 50 字符，使用祈使句
3. 如果 diff 涉及多个关注点，使用正文逐条列出
4. 禁止使用 "update"、"fix bug"、"修改代码" 等模糊表述
5. 输出为纯文本，不要包含解释性前缀"""

def build_prompt(diff_stat: str, diff_text: str, lang: str = "zh") -> str:
    """根据 diff 统计信息和详细内容构造用户 prompt。"""
    lang_instruction = "使用中文生成提交信息。" if lang == "zh" else "Generate commit message in English."
    return f"""以下是本次代码变更的统计信息：
{diff_stat}

以下是变更的详细 diff（可能由于长度限制被截断）：
{diff_text}

{lang_instruction}
请分析这些变更并生成 commit message。"""

调用模型 API 的时候，你需要关注两个请求参数：max_tokens 和 temperature。max_tokens 决定了模型最多输出多少 token，我一般设成 500，足够覆盖标题加正文了。有些人会忽略这个参数，结果模型长篇大论地输出，还得在 post-processing 里截断，不如一开始就设上限。

网络请求超时也值得关注。云端 API 在高峰期响应可能很慢，一个完整的请求可能要十几秒。如果你只设置了 3 秒超时，那基本每次都会失败。建议设置 60 秒以上的超时时间，并且做一次失败重试。

python复制import httpx

def call_llm(prompt: str, config: dict) -> str:
    """调用大模型 API，返回模型生成的提交信息文本。"""
    headers = {
        "Authorization": f"Bearer {config['api_key']}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": config["model_name"],
        "messages": [
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": prompt},
        ],
        "temperature": config.get("temperature", 0.3),
        "max_tokens": config.get("max_tokens", 500),
    }
    with httpx.Client(timeout=60.0) as client:
        response = client.post(config["api_url"], json=payload, headers=headers)
        response.raise_for_status()
        data = response.json()
        return data["choices"][0]["message"]["content"].strip()

这段代码有一个值得注意的点：messages 里同时放了 system 和 user 两个角色。system prompt 用来设定模型的全局行为规范，user prompt 用来放具体的 diff 内容。很多初学者习惯把所有指令塞进 user prompt，这也能运行，但把"角色设定"分离出来，模型遵循规则的稳定性会好很多。

4.3 智能拆解超长 diff

真实项目的 diff 经常超长，这是必然会遇到的问题。前面提到两种思路，我把更实用的那一种展开讲。

我把超长 diff 的处理拆成三个层级：

第一层，按文件拆分。对每个文件单独分析，生成该文件的简要描述。这需要把 diff 文本按文件分割，正则匹配 diff --git a/xxx b/xxx 即可。

第二层，对单文件超出长度的 diff，做基于时间或基于行号的截断。因为 diff 的每一行都带 + 和 - 前缀，我们可以统计新增和删除的行，优先保留新增的函数体，忽略删除部分。删除的代码在语义分析上价值较低，除非涉及函数签名变化。

第三层，多轮摘要合并。如果单文件 diff 还是超过限制，可以把它拆成多个片段分别请求模型生成摘要，再把所有摘要合并成一个大摘要，最后提交给最终生成。这个方法最耗时，但也是处理大型重构时唯一能保住质量的办法。

具体切分逻辑在代码里可以这样实现：

python复制def split_diff_by_file(diff_text: str) -> list[dict]:
    """将完整 diff 文本按文件切分成多个 block。"""
    files = []
    current_file = None
    current_lines = []

    for line in diff_text.splitlines():
        if line.startswith("diff --git "):
            if current_file is not None:
                files.append({"header": current_file, "content": "\n".join(current_lines)})
            # 解析文件名，忽略 a/ b/ 前缀
            parts = line.split(" b/")[-1]
            current_file = parts
            current_lines = []
        else:
            current_lines.append(line)

    if current_file is not None:
        files.append({"header": current_file, "content": "\n".join(current_lines)})

    return files

一个经验值是：当文件数量超过 10 个，或者总 diff 超过 15000 字符时，就应该启动分片逻辑，而不是等到 API 报错再补救。提前分片还能显著降低单次请求的延迟——大模型的响应时间和输入长度并非线性关系，输入越长，生成前的计算等待越久。

4.4 生成结果的解析与提交

模型返回的文本通常需要做清洗，才能拿来做最终的 commit message。清洗包括：去掉首尾的空白、去掉可能产生的 Markdown 代码块标记（有些模型会把输出包在 ``` 里）、检查标题是否超长。如果标题超过了 50 个字符，可以取模型返回的前半段，或者直接截断。更稳妥的方式是借鉴 angular commit 规范的 type(scope): subject 格式，让模型输出这种结构。

处理完成的提交信息，我建议不要让工具直接执行 git commit，而是进入一个"预览确认"的交互环节。原因有二：一是模型偶尔会生成和代码实际意图不符的描述，直接提交了会污染历史；二是这个确认动作能帮助用户建立信任感，用过几次确认交互之后，用户会更放心地接受 AI 的生成结果。

交互可以用 rich 库的 prompt 功能实现：

python复制from rich.prompt import Confirm

def interactive_confirm(commit_message: str) -> bool:
    """展示生成的提交信息，让用户选择确认、重新生成或取消。"""
    print("\n[bold green]生成的 commit message 如下：[/bold green]")
    print("-" * 60)
    print(commit_message)
    print("-" * 60)
    choice = input("确认提交？[y]es / [r]egenerate / [n]o (默认 y): ").strip().lower()
    if choice == "r":
        return "regenerate"
    if choice == "n":
        return "cancel"
    return "confirm"

用户确认之后，工具需要执行最终的提交。提交时可以附带一个环境变量，标记这次提交是 AI 生成的，方便将来统计工具的使用效果。

bash复制git commit -m "$COMMIT_MESSAGE"

如果你希望提交正文（body）里包含更详细的内容，可以分成多个 -m 参数传给 git，或者用 -m "标题" -m "正文" 的方式。注意 shell 转义问题——如果提交信息里包含引号或特殊字符，最好是通过环境变量传入，而不是拼在命令字符串里。

5. 从命令行工具到 git 原生集成

5.1 注册为 git 子命令

当你把工具做完，会希望它能用更优雅的方式调用。直接在终端里执行 git-ai commit 已经不错了，但如果你想让使用者执行 git ai-commit 或者跟 git commit 无缝衔接，可以把脚本注册为 git 的子命令。

git 支持自定义子命令的机制：你只需要在 PATH 里放一个名为 git-gpt-commit 的可执行文件，用户就可以在任意仓库目录执行 git gpt-commit 来调用它。这比 git-ai commit 这样的独立命令更像"原生 Git 工具"。

实现方式很简单：写好 Python 脚本后，加一个可执行权限，放到 /usr/local/bin/ 或者某个已经加入 PATH 的目录：

bash复制chmod +x git-gpt-commit
mv git-gpt-commit /usr/local/bin/

之后在任意 git 仓库里执行：

bash复制git gpt-commit

输出效果和直接执行是一样的，但从使用体验上说，git gpt-commit 这个形态明显更贴近 Git 用户的直觉。

5.2 通过 Git Hook 实现半自动提交

再进阶一步，可以通过 Git Hook 实现更自动化的流程。

这里要分清两个 hook：一个是 prepare-commit-msg，它在提交信息编辑器打开之前执行，适合往提交信息里注入内容；另一个是 commit-msg，它在提交信息写完之后执行，适合做校验。对于 git-ai 的使用场景，prepare-commit-msg 是天然的接入点——当用户执行 git commit 时，这个 hook 被触发，我们可以调用 git-ai 生成初始提交信息，然后让用户在编辑器里调整后再确认。

在 .git/hooks/prepare-commit-msg 里写一段脚本：

bash复制#!/bin/sh
# 第一个参数是提交信息文件路径
# 第二个参数是提交类型（message/template/merge/squash/commit）
if [ "$2" = "message" ]; then
  exit 0
fi

# 调用 git-ai 生成提交信息写入文件
git-gpt-commit --write-to "$1"
exit 0

这段脚本的意思很明确：只有当用户是手动执行 git commit 时才触发 AI 生成（通过 -m 指定消息时不触发，因为此时用户已经有了明确的提交意图）；生成的提交信息直接写到 hook 传入的文件路径里，用户在 vim 等编辑器里看到的初始内容就是 AI 生成的结果，可以随时修改。

不过我要提醒一下，hook 在团队中推广是有难度的——每个开发者的 .git/hooks 目录是本地文件，不会跟随仓库走。要让全体成员统一启用 hook，需要配合初始化脚本（比如 make setup 里执行一段复制 hook 的脚本）或者 Git 2.9 之后支持的 core.hooksPath 配置，指向仓库内的 hooks/ 目录。这方面实现时留意就行，不是核心难点。

5.3 与代码评审流程结合

工具做出来不只是为了自动提交，更大的想象空间在代码评审环节。我在使用中发现，git-ai 生成的提交信息其实可以当作评审者的"第一份阅读材料"。

一种可行的扩展是：基于提交信息生成一个简短的变更说明，挂到 Merge Request / Pull Request 的标题或描述里。这样评审者一打开 MR，就看到一个结构化的变更树："feat: 新增用户登录接口" 下面列出了涉及的核心文件和改动要点，比直接看几百行 diff 舒服得多。

如果你在做企业内部的工具链，这还可能和持续集成流水线打通。提交代码后自动触发一个任务，调用模型分析本次提交的关键改动，把结果推送到 IM 群里。这个方法在团队协作中很实用，我见过不少团队用类似方式做"MR 摘要助手"，大大缩短了 code review 前的上下文准备时间。

6. 踩坑实录与参数调优经验

6.1 高频问题排查速查

实际使用和开发过程中，我收集了一些典型问题。整理成速查表，方便你遇到问题时快速定位：

最容易被忽视的问题是编码。如果你在 Windows 或特殊终端环境下开发，git 命令输出默认可能是 GBK 编码，而 Python 的 text=True 默认用系统编码解码，容易导致乱码或报错。最稳妥的方案是显式指定 encoding="utf-8"。

6.2 质量调优的实战心得

生成质量不好是这类工具最普遍的抱怨。我在实际调优中发现，作用从大到小排序大概是：prompt 结构、单次输入长度、模型选择、temperature 参数。

先说 prompt 结构。我最初把一堆规则塞进 user prompt，效果很飘忽。换成 system / user 分离的方式之后，稳定度提升明显。system 部分设定角色和格式规范，user 部分专注放 diff 内容，模型会更明确"我是谁、我要做什么"。这一点一定要自己动手试一次，对比一下就知道差别。

其次是输入长度控制。我观察到一个现象：同样一个模型，输入 3000 字符的 diff 和输入 12000 字符的 diff，生成质量差距极大。当 diff 过长时，模型会出现"首尾效应"——只关注开头和结尾的文件，中间的木已成舟根本顾不上。所以宁可多做几次请求，也不要一次性把超长 diff 塞给模型。

再次是模型选择。如果你的工具面向个人使用，直接选当前性价比最高的商用模型就行。如果是企业内部使用，需要自建或私有化部署，建议优先选对中文理解好、代码理解能力强的模型，不要只看榜单分数。

最后是 temperature。很多人忽略这个参数对提交信息质量的影响。我测试过多次，0.3 以下生成的提交信息通常直接可用，0.7 以上就会开始出现"标题越来越华丽，内容越来越空洞"的情况。如果你发现生成的信息花里胡哨但没什么实际信息量，先看看是不是 temperature 设高了。

6.3 安全与隐私的注意事项

代码是一种很敏感的数据。使用 git-ai 类工具时，信息安全和隐私是绕不开的话题。

如果企业内部开发涉及核心业务代码，将所有 diff 发送给外部大模型 API，数据合规风险值得认真评估。即便服务商承诺"数据不用于训练"，在合规审查严格的公司里，这条路径也很难通过。解决方案主要有两种：一是用私有化部署的开源模型，例如通过 Ollama 部署 Qwen-Coder 系列，完全内网运行；二是对 diff 做脱敏处理，比如把包名、类名、关键路径替换成通用标识，再把脱敏后的文本发给模型。后者在自动化工程上更复杂，但相比私有化模型，能保留更好的生成效果。

我开发时有一个默认策略：不发送未暂存的改动，不用工具的进程去读取工作区之外的任何文件，只在命令执行目录内读取 git 元信息。这样能把数据暴露面控制到最小。

提醒：如果你在接入 CI/CD 流水线时使用 git-ai，要特别注意不要在日志里打印 API Key 或完整 diff 内容。CI 日志很容易被不小心分享出去，这属于低级但常见的泄露路径。

7. 项目未来的扩展方向与个人建议

7.1 可以扩展的应用场景

git-ai 做出来之后，最好的验证方式就是把它嵌入日常开发流程。用了一段时间后，我发现它还可以往几个方向扩展，而且难度都不大。

第一个方向是支持代码变更的语义分类。现在的工具只是生成描述，但如果能让模型额外输出"变更类型"（比如：新增功能、修复缺陷、性能优化、重构调整），就能自动打标签。这些标签可以进一步用于统计团队代码活动的类型分布，帮管理者了解团队的工作重心，甚至联动 issue 跟踪系统。

第二个方向是生成 changelog。Git 仓库的提交历史在语义化之后，就可以按版本号聚合生成规范的 changelog。这个功能本质上是"读取提交历史 + 按版本过滤 + 模型归纳总结"。对于需要定期发版的团队来说，自动生成 changelog 能省去大量重复劳动。

第三个方向是自动生成周报或日报。许多开发者每周都要写工作总结，如果能把一周内所有 AI 生成的提交信息汇总一下，再做一次润色，一份像样的周报草稿就出来了。这个功能对有些团队来说是刚需。

第二个和第三个扩展方向的工程难度都不高，核心是复用已有的 AI 能力和 Git 数据，难点在于输出格式要适应团队已有的工具链。如果你打算在团队中推广，建议先做代码审查摘要这个方向，收益最直接。

7.2 给开发者的一条实话

最后说点掏心窝的话。做 git-ai 这类工具，技术难点从来不在"调用大模型"本身，而是在"怎么把工具嵌入一个真实且稳定的开发流程"。你要处理的是 git 命令的各种边缘情况、diff 文本的编码和截断、模型输出的不确定性和不可解释性，以及用户对 AI 生成内容天然的信任门槛。

我实际使用过程中的体会是：与其追求"一次全自动、完全不需要人看"，不如接受"AI 生成草稿、人来确认"的半自动模式。这不仅是在工具交互上更现实的选择，也是在开发流程中建立信任的必要步骤。拿 git-ai 来说，如果生成的信息直接提交，用户很容易在遇到一次质量不佳时就把工具卸载；而加一步确认交互，用户逐渐会发现 AI 生成的内容大多数时候比自己写的更规范、更完整，信任感是这样一点点积累起来的。

这个项目从想法到落地，最值得借鉴的经验就是：不要追求 AI 一步到位，把 AI 定位成"帮你把最费神的一步做完"，剩下的交给人。这个思路放在代码提交里适用，放在其他 AI 辅助工具里同样适用。如果你正在做类似的项目，希望这篇文章的思路能帮你少走一些弯路。