用本地 LLM 写 commit，不消耗云端 token：git-courer 是怎么做到的

大多数 AI 编程工具处理 git commit 的方式都差不多：把 git diff 的输出扔给 LLM，让它生成一条 commit 消息。这个方案能用，但有几个问题：commit 类型（feat/fix/refactor）由 LLM 猜，猜错了你得手动改；大型 diff 消耗大量 token；代码全部发到云端，有隐私顾虑。

git-courer 换了一种思路：用 Go 做 AST 解析和依赖图分析，commit 类型由代码决定，LLM 只负责写那条人类可读的消息。如果用本地 Ollama，整个流程不碰云端。

它做了什么

核心流程是这样的：

sql 复制代码

你说"commit 我的改动"
        ↓
AI 助手通过 MCP 调用 git-courer
        ↓
Go 读取 AST + 依赖图 → 确定 commit 类型
        ↓
本地 LLM 根据标注后的 diff 写消息
        ↓
5 层安全扫描 → 自动备份 → 提交
        ↓
"✓ feat(auth): add OAuth2 token refresh"

关键在中间那步：commit 类型不是 LLM 猜的，是 Go 用 go-enry 和 go-tree-sitter 解析 AST 后，按确定性规则判断的------新增公开函数、修改函数签名、删除符号、破坏性变更，每种情况对应固定的分类逻辑。LLM 收到的是已经标注好类型的结构化上下文，不是原始代码。

依赖图分析

提交前，git-courer 会构建一张图：staged 文件影响了哪些其他文件。

这解决了一个实际问题：你改了 auth/token.go，但调用它的 api/handler.go 也需要一起提交。传统工具只知道你 staged 了哪些文件，git-courer 知道这些文件在整个代码库里的影响范围。

基于这张图，它会把 staged 文件按依赖关系拆成多个原子 commit，每个最多 12 个文件。一次 git add . 之后，你可能得到三条结构清晰的 commit，而不是一条"update stuff"。

三阶段 commit 流程

复制代码

PREVIEW → 用户确认 → APPLY

调用 git-commit PREVIEW 后，git-courer 解析 AST、构建依赖图、生成 commit 计划。对于大型 diff，这个过程是异步的：

json 复制代码

{ "status": "processing", "job_id": "abc123" }

AI 助手不会阻塞等待，可以继续做其他事，然后用 git-commit STATUS 轮询。计划好了之后，展示给你看，确认没问题再 APPLY。

每次 APPLY 成功后，commit 消息会写入 .git-courer/branches/<branch>/commits.json。这个 CommitStore 的用处在后面的 release 流程里体现：即使后来做了 rebase 或 squash，历史记录被改写，这份本地存档还在，生成 changelog 时不依赖 git log。

安全扫描

每次写操作提交前，diff 会经过 5 层扫描：

Magic bytes：直接扫文件头，检测二进制可执行文件
统计审计：检测伪装成文本的二进制 payload
路径黑名单 ：按文件名拦截（.env、credentials 等）
内存正则：在内存里扫 staged diff，匹配密钥模式
AI 审计员：本地 LLM 做最后一道检查，处理前四层没覆盖到的情况

这 5 层是在 Go 里强制执行的，不依赖 LLM 判断前四层。

自动备份和 undo

每次写操作（commit、amend、revert、merge、rebase......）执行前，git-courer 自动保存当前状态。出了问题，一条命令恢复：

复制代码

git-undo RESTORE

不需要翻 reflog，不需要记住操作前的 commit hash。

22 个 MCP 工具

git-courer 作为 MCP 服务器运行，暴露 22 个工具，覆盖完整的 git 生命周期：

类别	工具
读取	status、diff、history、blame、pr-review
写入	commit、amend、revert、stage、reset、stash
分支	branch、merge、rebase、cherry-pick、tag
工具	sync、backup、undo、remotes、config、commit-jobs

所有工具返回结构化 JSON，没有分页器挂起，没有文本解析。status 一次调用返回完整仓库状态，替代原本需要 5 个以上 git 命令才能拼出来的信息。

pr-review 是个一次性 PR 前检查：跑测试、检测冲突（带 AST 标注的 hunk）、统计 diff、检查分支分叉情况。不绿不合并。

LLM 后端配置

git-courer 支持任何 OpenAI 兼容的服务器，不绑定 Ollama：

后端	provider 值
Ollama（推荐）	`ollama`
LM Studio	`lmstudio`
vLLM	`vllm`
LocalAI	`localai`
任意兼容服务器	`openai-compatible`

配置在 ~/.config/git-courer/config.yaml：

yaml 复制代码

llm:
  provider: ollama
  model: qwen3.5:latest

测试过的模型里，qwen3.5:latest（7b）性价比最高，commit 质量好，速度快。低配机器可以用 qwen3.5:0.8b，只有 1GB，基础 commit 够用。

没有配置 LLM 后端的情况下，读操作（status、diff、log）照常工作，AI 相关操作（commit 消息生成、release changelog、安全 AI 审计员）会报错。

安装

bash 复制代码

curl -fsSL https://raw.githubusercontent.com/Alejandro-M-P/git-courer/main/scripts/install.sh | sh

安装脚本会检测你机器上已有的 AI 工具并自动配置 MCP。支持 12 个客户端：Claude Code、Cursor、Windsurf、Gemini CLI、Codex、VS Code、Zed、Continue、Cline、Roo Code、OpenCode、Claude Desktop。

手动配置某个客户端：

bash 复制代码

git-courer mcp setup cursor

不带参数运行 git-courer 会启动交互式 TUI，可以选择要配置的客户端、设置 LLM 后端、预览配置后保存。

架构

bash 复制代码

┌─────────────────────────────────────┐
│     AI 助手（Claude、Cursor 等）      │
└──────────────┬──────────────────────┘
               │ MCP 协议（JSON-RPC）
┌──────────────▼──────────────────────┐
│    internal/delivery/mcp（MCP 层）   │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│   internal/workflow（统一引擎）       │
│   - 原子操作 + 自动备份                │
│   - 主动安全拦截                      │
│   - 统一 preview 生成                │
└──────┬───────┴──────────┬───────────┘
       │                  │
┌──────▼──────┐   ┌───────▼──────────┐
│ core/domain │   │ adapters         │
│（纯领域模型） │   │（git、llm 多后端） │
└─────────────┘   └──────────────────┘

六边形架构，所有需要 AI 或用户确认的 git 操作都经过 workflow 引擎，保证原子性和安全性。

适合谁用

几个场景下 git-courer 的优势比较明显：

代码隐私要求高：代码不出本地，LLM 在自己机器上跑。

频繁提交的项目：每次 commit 都走云端 LLM 的 token 成本会积累，本地模型没有这个顾虑。

多人协作项目 ：.git-courer/config.json 可以提交到仓库，团队共享 areas（模块划分）和 test_command 配置，release changelog 按模块分组生成。

有 release 流程的项目：CommitStore 保存每条 commit 消息，rebase/squash 不会破坏 changelog 数据源。

不适合的场景：没有本地 GPU 或内存不够跑 7b 模型，用 qwen3.5:0.8b 可以降低门槛，但 commit 质量会有差距。

项目地址：github.com/Alejandro-M...