Git-AI：追踪 AI 生成代码的实用工具

支持的 AI 编程工具

Git-AI 采用厂商无关的设计，目前支持主流的 AI 编程工具：

技术原理剖析

工作流程

Git-AI 的工作原理可以分为三个阶段：

1. 代码生成阶段：当你使用 Claude Code、Cursor 等工具生成代码时，这些工具会调用 Git-AI 的 API，标记插入的行为为 AI 生成。
2. 提交阶段：在 git commit 时，Git-AI 会收集所有 AI 归属标记，将归属信息保存到 Git Note 中。Git Note 与 commit 绑定，但不影响 commit 本身。
3. 查询阶段：通过 git-ai blame 等命令，读取 Git Note 中的归属信息，展示给用户。

Git Note 机制

Git-AI 选择使用 Git 原生的 Note 机制存储归属信息，这是一个精妙的设计：

• 不污染 commit 历史
• 可以独立同步/备份
• 向后兼容，不影响现有工作流

标准规范

Git-AI 制定了开放标准 Git AI Standard v3.0.0，定义了归属信息的格式，便于第三方工具集成、跨平台数据交换和生态系统扩展。

快速上手

安装

Mac / Linux / Windows (WSL)：

curl -sSL https://usegitai.com/install.sh | bash

Windows (非 WSL)：

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm http://usegitai.com/install.ps1 | iex"

安装完成后会看到类似输出：

Successfully installed git-ai into /Users/xxx/.git-ai/bin ✓ 
Claude Code: Hooks updated ✓ 
Cursor: Hooks updated ✓ 
VS Code: Hooks already up to date ✓ 
Gemini: Hooks updated 

重要：安装完成后，需要重启终端或执行以下命令使 PATH 生效：

source ~/.zshrc

如果看到提示无法自动安装扩展，需要手动安装：

• Cursor：在扩展商店搜索 git-ai-vscode
• VSCode：访问 https://marketplace.visualstudio.com/items?itemName=git-ai.git-ai-vscode

使用前提

Git-AI 需要在有提交历史的仓库中才能正常工作：

# ❌ 新仓库直接使用会报错
git init
git-ai stats # 报错：unknown revision

# ✅ 正确流程：先有提交，再查看统计
git init
git add .
git commit -m "initial commit"
git-ai stats # 正常工作

零配置使用

安装完成后，无需任何配置，Git-AI 会自动与支持的 AI 工具集成。

# 正常使用你的 AI 编程工具
# 例如使用 Claude Code 生成代码
# 正常提交
git add .
git commit -m "feat: add user authentication"
# 查看 AI 归属 
git-ai blame src/auth.py 

常用命令

命令格式说明：git ai 和 git-ai 两种写法都可以执行命令，但推荐统一使用 git-ai（带连字符）。

# 查看文件的 AI 归属
git-ai blame <file>
# 查看仓库 AI 代码统计（需要有提交历史）
git-ai stats 
# 查看特定 commit 的统计
git-ai stats <commit-hash>
# 查看 diff 的 AI 归属注解
git-ai diff<commit-hash>
# 查看某个 prompt 的详情
git-ai show-prompt <prompt-id>
# 查看归属日志（Git Note 内容）
git-ai show <commit-hash>
# 查看未提交的 AI 编辑状态
git-ai status 
# 安装/更新 Agent hooks
git-ai install-hooks 
# 查看帮助
git-ai --help 

企业级应用场景

代码审计与合规

对于企业来说，Git-AI 可以回答关键问题：

• 代码库中有多少比例是 AI 生成的？
• 哪些模块 AI 参与度最高？
• AI 代码的质量如何？（通过 bug 率关联分析）

团队协作洞察

通过 Stats Bot（早期访问阶段），可以获得：

• PR 级别的 AI 代码占比
• 不同 Agent+Model 组合的代码接受率
• AI 代码的'半衰期'（被修改/删除的速度）

最佳实践沉淀

高质量的 prompt 会被保留，团队可以建立 prompt 知识库，新人快速学习有效的 AI 协作方式，持续优化 AI 使用策略。

与传统 git blame 的对比

实战踩坑指南

在实际使用 Git-AI 的过程中，可能会遇到一些问题，这里整理出来供大家参考。

安装后命令不生效

现象：安装完成后执行 git-ai 提示 command not found。

原因：安装脚本修改了 ~/.zshrc，但当前终端会话没有加载新配置。

解决：

# 方法 1：重新加载配置
source ~/.zshrc 
# 方法 2：重启终端

Cursor/VSCode 扩展需要手动安装

现象：安装日志显示警告：⚠ Cursor: Unable to automatically install extension

原因：git-ai 无法自动在 GUI 编辑器中安装扩展。

解决：

1. 打开 Cursor/VSCode
2. 按 Cmd+Shift+X 打开扩展面板
3. 搜索 git-ai 或 git-ai-vscode
4. 点击安装
5. 重启编辑器（很重要！）

安装扩展后 AI 代码仍然不被追踪

现象：用 Cursor AI 改了代码，提交后 git-ai stats 显示 100% 人工。

原因：

1. 扩展安装后没有重启 Cursor
2. 之前的提交不会被追溯标记

解决：

# 1. 完全退出 Cursor (Cmd+Q)，重新打开
# 2. 用 AI 做一些修改
# 3. 提交前检查 git-ai 是否捕捉到
git-ai status 
# 应该能看到类似：
# you ███████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ai
# 18% 82%
# 4. 确认有捕捉到后再提交
git add . && git commit -m "test"

SourceTree 等 GUI 工具提交后丢失 AI 追踪

现象：用 SourceTree 提交后，git-ai stats 显示 0% AI。

原因：Git-AI 依赖 Git Hooks 机制，某些 GUI 工具可能跳过 hooks、使用不同的 git 环境或有禁用 hooks 的设置。

解决：

1. 检查 SourceTree 设置，确保 hooks 未被禁用
2. 推荐使用命令行或 Cursor/VSCode 内置 Git 面板提交

git ai --help 不工作

现象：git ai --help 输出：No manual entry for git-ai

原因：git ai --help 会被 git 解释为查看 man page，而不是执行 git-ai --help。

解决：使用连字符写法：

git-ai --help # ✅ 正确

Git Hook 原理详解

什么是 Git Hooks？

Git Hooks（钩子）是 Git 内置的一套事件触发机制。简单来说，当你执行某个 Git 操作时，Git 会检查 .git/hooks/ 目录下有没有对应名字的脚本，如果有，就自动执行它。

这就像游戏里的'触发器'——走到某个位置就会触发剧情。Git 操作就是'位置'，Hook 脚本就是'剧情'。

常见的 Git Hooks 类型

Git-AI 使用了哪些 Hooks？

Git-AI 主要依赖两个 Hook：

• pre-commit：在 commit 前准备和验证 AI 归属数据
• post-commit：在 commit 后将 AI 归属信息写入 Git Note

查看 Hook 脚本内容

安装 git-ai 后，你可以查看它创建的 hook 脚本：

# 查看 post-commit hook
cat .git/hooks/post-commit 

典型输出：

#!/bin/sh
# git-ai post-commit hook
exec git-ai hook post-commit "$@"

这个脚本非常简洁——它只是调用 git-ai hook post-commit 命令，真正的逻辑在 git-ai 程序内部处理。

为什么 SourceTree 等工具可能不触发 Hook？

这是最容易踩的坑。原因如下：

SourceTree 不触发的典型原因：

1. SourceTree 使用的是内嵌的 Git，而不是系统安装的 Git
2. 某些版本为了'加速'会跳过 hooks
3. SourceTree 可能使用 --no-verify 参数跳过 hooks

解决方案：

# 方案 1：使用命令行提交
git add . && git commit -m "your message"
# 方案 2：使用 VSCode/Cursor 的 Git 面板提交
# （这些编辑器会正确触发 hooks）
# 方案 3：配置 SourceTree 使用系统 Git
# SourceTree → 偏好设置 → Git → 使用系统 Git

手动检查 Hooks 是否正常

# 1. 检查 hooks 目录
ls -la .git/hooks/ 
# 2. 确认 hook 脚本存在且可执行
ls -la .git/hooks/post-commit 
# 输出应该包含 -rwxr-xr-x（x 表示可执行）
# 3. 如果没有执行权限，添加权限
chmod +x .git/hooks/post-commit 
# 4. 手动测试 hook
.git/hooks/post-commit 
# 应该看到 git-ai 的输出（如果 hook 工作正常）

常见问题排查

问题 1：提交后没有 AI 归属信息

# 检查 hook 是否存在
ls .git/hooks/post-commit 
# 如果不存在，重新初始化 git-ai
git-ai hooks install

问题 2：hook 存在但不执行

# 检查执行权限
ls -la .git/hooks/post-commit 
# 添加执行权限
chmod +x .git/hooks/post-commit 

问题 3：hook 执行但报错

# 手动执行查看错误信息
.git/hooks/post-commit 
# 检查 git-ai 是否在 PATH 中
which git-ai 

问题 4：使用了 --no-verify 跳过 hooks

# 这个命令会跳过所有 hooks！
git commit --no-verify -m "message"
# ❌ AI 归属不会被记录
# 正确做法：不要使用 --no-verify
git commit -m "message"
# ✅ hooks 正常触发

Prompt 存储详解

两个存储位置

Git-AI 的数据存储在两个地方：

Git Commit 与 Git Note 的关系

核心区别：

一句话总结：Git Note 是'贴'在 Commit 上的便签纸——不改变 commit 本身，但可以附加额外信息。

查看 Git Note 中的归属信息

方法 1：使用 git-ai 命令

git-ai show <commit-hash>

方法 2：使用原生 git 命令

# 列出所有带 AI 归属的 commits
git notes --ref=refs/notes/ai list 
# 查看某个 commit 的 note 内容
git notes --ref=refs/notes/ai show <commit-hash>

方法 3：在 git log 中直接显示（推荐）

配置一次，永久生效：

git config notes.displayRef refs/notes/ai 

然后 git log 就能直接看到 AI 归属信息：

commit a2e58cb (HEAD -> main)
Author: MacBookPro <[email protected]>
Date: Tue Jan 27 15:15:54 2026 +0800 test after extension 2
Notes (ai): ClipMind/ContentView.swift cce7dc1177030070 13-14,16,20-22,29,33-34 0fd5eeb3d01edae0 15,17-19,26-28,35
--- { "schema_version": "authorship/3.0.0", "prompts": { "0fd5eeb3d01edae0": { "agent_id": { "tool": "claude", "model": "claude-opus-4-5-20251101" }, ... } } }

取消显示 Notes：

# 删除配置，git log 不再显示 notes
git config --unset notes.displayRef 

临时控制显示/隐藏（不改配置）：

# 临时显示 notes（即使没配置）
git log --notes=refs/notes/ai 
# 临时隐藏 notes（即使配置了也不显示）
git log --no-notes 

多人协同：Git Notes 的推送与同步

理解 Commit 与 Note 的推送机制

这是最容易混淆的地方，请仔细理解：

一句话总结：

• git commit 时 Note 自动附加（不需要额外操作）
• git push 时 Note 不会自动推送（需要配置或手动推送）

Notes 的存储位置详解

查看本地 Notes 存储：

# 查看 refs/notes/ai 指向哪个对象
cat .git/refs/notes/ai 
# 输出：f3abc123456789...
# 查看这个对象的内容
git cat-file -p $(cat .git/refs/notes/ai)

手动推送和拉取 Notes

# 推送你的 notes 到远程
git push origin refs/notes/ai 
# 从远程拉取 notes
git fetch origin refs/notes/ai:refs/notes/ai 

配置自动推送/拉取（推荐）

配置一次，以后每次 push/fetch 自动包含 Notes：

# push 时自动包含 notes
git config --add remote.origin.push refs/notes/ai 
# fetch 时自动拉取 notes
git config --add remote.origin.fetch +refs/notes/ai:refs/notes/ai 

或者直接编辑 .git/config：

[remote "origin"]
url = [email protected]:xxx/xxx.git
fetch = +refs/heads/*:refs/remotes/origin/*
fetch = +refs/notes/ai:refs/notes/ai # 添加这行
push = refs/notes/ai # 添加这行

配置后的效果：

git push # 代码和 notes 一起推送
git fetch # 代码和 notes 一起拉取

多人协同完整流程

场景：团队 3 人协作，都使用 AI 辅助编程，想要共享 AI 代码统计。

Step 1：每个成员配置自动同步（每人执行一次）

git config --add remote.origin.push refs/notes/ai 
git config --add remote.origin.fetch +refs/notes/ai:refs/notes/ai 

Step 2：日常开发流程

# 开发者 A
git add .
git commit -m "feat: 新功能"
# Hook 自动附加 AI 归属
git push # 代码 + Notes 一起推送

# 开发者 B
git pull # 代码 + Notes 一起拉取
git-ai stats # 能看到 A 的 AI 代码贡献

Step 3：新成员加入项目

git clone <repo-url>
cd <project>
# 配置自动同步
git config --add remote.origin.push refs/notes/ai 
git config --add remote.origin.fetch +refs/notes/ai:refs/notes/ai 
# 首次拉取历史 notes
git fetch origin refs/notes/ai:refs/notes/ai 
# 查看整个项目的 AI 统计
git-ai stats 

不配置同步会怎样？

各工具对 Git Notes 的支持

Git Notes 是'隐藏'的元数据，专门给工具（如 git-ai）使用，大多数 GUI 工具看不到。这也是为什么 git-ai 提供了专门的命令来读取和展示这些信息。

查看使用了哪些 AI 工具

git-ai stats 只显示整体的 AI 代码比例，如果想知道具体使用了哪些 AI 工具（Claude、Cursor、Copilot 等），有以下方法：

方法 1：查看某个文件的 AI 归属详情

git-ai blame <文件名>

输出会显示每一行是哪个 AI 生成的，包括工具和模型信息。

方法 2：查看某个 commit 的 AI 信息

# 查看指定 commit
git-ai show <commit-hash>
# 查看最新 commit
git-ai show HEAD 

方法 3：通过 prompts 数据库查询

# 先生成/更新 prompts 数据库
git-ai prompts 
# 列出所有 prompts（会显示 agent_id 包含工具和模型）
git-ai prompts list 
# 用 SQL 统计使用了哪些 AI 工具和模型
git-ai prompts exec"SELECT DISTINCT json_extract(agent_id, '$.tool') as tool, json_extract(agent_id, '$.model') as model FROM prompts"

方法 4：直接查看 Git Note 原始内容

# 查看最近 commit 的 note
git notes --ref=refs/notes/ai show HEAD 

输出示例：

{"schema_version":"authorship/3.0.0","prompts":{"0fd5eeb3d01edae0":{"agent_id":{"tool":"claude", ← AI 工具名称 "model":"claude-opus-4-5-20251101" ← 具体模型版本 }},"cce7dc1177030070":{"agent_id":{"tool":"cursor","model":"gpt-4"}}}}

常见 AI 工具标识

查看完整的 Prompt 对话

Git Note 里只有精简的元数据，完整的 prompt 对话存储在全局数据库：

# 生成/更新 prompts 数据库
git-ai prompts 
# 列出所有 prompts
git-ai prompts list 
# 用 SQL 查看完整对话
git-ai prompts exec"SELECT messages FROM prompts WHERE"

完整对话包括：

• 用户输入的 prompt
• AI 的回复
• 工具调用记录（Read、Edit 等）

全局数据库文件说明

~/.git-ai/
├── bin/ # git-ai 可执行文件
├── config.json # 配置文件
└── internal/
    ├── db # SQLite 数据库（无后缀，但就是 .db）
    ├── db-shm # SQLite 共享内存文件
    └── db-wal # SQLite 预写日志

用图形化工具查看数据库：

# 安装 DB Browser for SQLite
brew install --cask db-browser-for-sqlite 
# 或者复制一份带后缀的
cp ~/.git-ai/internal/db ~/Desktop/git-ai-prompts.db 

项目目录下的 prompts.db

运行 git-ai prompts 会在项目目录生成 prompts.db，这是临时分析文件，建议加入 .gitignore：

echo"prompts.db">> .gitignore 

总结

Git-AI 填补了 AI 编程时代的一个重要空白：追踪和管理 AI 生成的代码。

它的核心价值在于：

1. 透明性：清晰知道代码的来源
2. 可追溯：保留生成代码的上下文（prompt、模型等）
3. 工程化：与 Git 深度集成，支持真实工作流
4. 标准化：厂商无关的开放标准

对于正在大规模采用 AI 编程工具的团队来说，Git-AI 不是一个"nice to have"，而是即将成为"must have"的基础设施。

🔗 相关链接： GitHub：https://github.com/git-ai-project/git-ai 官方文档：https://usegitai.com/docs 标准规范：https://github.com/git-ai-project/git-ai/blob/main/specs/git_ai_standard_v3.0.0.md