别让 AI 代码成为“黑盒“！这个 Git 插件能追溯到每一行的 Prompt

别让 AI 代码成为"黑盒"！这个 Git 插件能追溯到每一行的 Prompt

原文链接：git-ai-project/git-ai
项目版本：v1.5.3 | 许可证：Apache 2.0

一句话介绍：Git-AI 是一个开源 Git 扩展，能自动追踪仓库里每一行代码是谁写的——是人类还是 AI，用的是哪个 Agent、哪个模型、哪段 Prompt。

一、Git-AI 是什么？解决了什么痛点？

1.1 背景：AI 编程时代的"黑盒"问题

2025-2026 年，AI 辅助编程工具（Claude Code、Cursor、GitHub Copilot 等）已经成为开发者的日常。但随之而来的是一个巨大的痛点：

你知道仓库里哪些代码是 AI 写的吗？你知道这段代码背后的 prompt 是什么吗？

大多数团队目前对 AI 代码的态度是"猜猜看"——靠直觉判断某段代码是不是 AI 生成的。这种做法既不准确，也无法追溯代码背后的需求、意图和架构决策。

1.2 Git-AI 的定位

Git-AI是一个开源的 Git 扩展，核心能力就一句话：

自动追踪仓库中每一行 AI 生成代码的归属——包括是哪个 Agent、哪个模型、哪段对话生成的。

它通过git notes机制，在每次提交时自动附加 AI 作者信息，让 AI 代码的追踪贯穿整个软件开发生命周期（SDLC）。

1.3 核心特性一览

二、安装指南

⚠️ 前置条件

Git 版本必须 >= 2.50.1，否则git-ai stats等命令会直接报错。先检查你的 Git 版本：

git-v# 要求输出：git version 2.50.1 或更高

如果版本过低，请先升级 Git 再继续安装。

2.1 Mac / Linux

一行命令搞定（使用国内镜像源）：

sudocurl-sSLhttps://git.eminxing.com/ai/ai-code-metrics/raw/master/install.sh|bash

安装脚本会自动：

• 下载对应平台的二进制文件
• 设置git和git-ai的符号链接
• 配置 PATH 环境变量

2.2 Windows - WSL

前置条件：安装 PowerShell 7.x 或更高版本

如果还没有安装，先点击下载 PowerShell 7。

在 WSL 或 PowerShell 终端中执行：

powershell-NoProfile-ExecutionPolicy Bypass-Command"irm https://git.eminxing.com/ai/ai-code-metrics/raw/master/install.ps1 | iex"

⚠️注意：非 WSL 的 Windows 原生支持目前处于实验阶段，遇到问题建议优先使用 WSL2。

2.3 验证安装

1. 进入任意 Git 仓库目录，打开终端。
2. 执行以下命令：

git-ai stats

若正常输出如下进度条，则表示安装成功：

mac@GL001361 test0530 % git-ai stats you ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ai 0% 100%

也可以验证版本：

git-ai--version

安装完成后无需对仓库做任何额外配置，直接正常使用git commit即可，Git-AI 会自动追踪归因。

2.4 为 IDE 安装插件

如果你使用 VS Code 及其衍生版（Cursor、Windsurf、Antigravity），可以安装官方插件：

• 插件市场搜索：git-ai
• 或直接访问：VS Code Marketplace

安装后，IDE 中会用颜色标注 AI 代码，鼠标悬停可查看原始 prompt 或摘要。

三、兼容的 AI 工具与生态

3.1 官方支持的 Agent

Git-AI 目前支持以下 AI 编程工具（持续增加中）：

3.2 暂不支持的工具

根据 Issues 反馈，以下工具目前尚未支持：

如果你使用的是国内流行的 Trae、CodeBuddy 等工具，目前还需要等待官方接入，或者自行基于开放标准实现对接。

3.3 Claude Code 配置检查（重要）

使用 Claude Code 时，切换供应商后需要确认settings.json中包含以下两个 hooks。如果没有，请手动补上：

"PostToolUse":[{"hooks":[{"command":"git ai checkpoint claude --hook-input stdin","type":"command"}],"matcher":"Write|Edit|MultiEdit"}],"PreToolUse":[{"hooks":[{"command":"git ai checkpoint claude --hook-input stdin","type":"command"}],"matcher":"Write|Edit|MultiEdit"}]

这两个 hooks 确保 Claude Code 在执行 Write/Edit/MultiEdit 操作前后，正确调用git-ai checkpoint记录 AI 归属信息。

四、核心命令实战

4.1git-ai stats— 查看 AI 代码统计

# 当前提交的 AI 占比git-ai stats# 输出 JSON 格式（方便脚本处理）git-ai stats--json# 查看某段范围的统计git-ai stats abc123..def456--json

示例输出：

you ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ai 6% mixed 2% 92%

JSON 输出包含更详细的指标：

• human_additions：人类编写的行数
• ai_additions：AI 生成的行数
• ai_accepted：AI 生成且未经人类修改直接提交的行数
• mixed_additions：AI 生成但被人类修改过的行数
• tool_model_breakdown：按工具/模型细分的统计

4.2git-ai blame— AI 代码溯源

增强版的git blame，可以查看每行代码是 AI 写的还是人类写的：

git-ai blame src/main.rs

输出示例：

cb832b7 (Aidan Cunniffe 2025-12-13 08:16:29 -0500 133) pub fn execute_diff( cb832b7 (Aidan Cunniffe 2025-12-13 08:16:29 -0500 134) repo: &Repository, fe2c4c8 (claude [session_id] 2025-12-02 19:25:13 -0500 138) // Resolve commits to get from/to SHAs fe2c4c8 (claude [session_id] 2025-12-02 19:25:13 -0500 139) let (from_commit, to_commit) = match spec {

4.3git-ai diff— 带归属标注的 diff

# 查看最近一次提交的 AI 标注 diffgit-aidiffHEAD# 查看两个提交之间的差异git-aidiffmain..feature-branch

每行变更后会标注🤖cursor、👤alice或[no-data]。

4.4git-ai status— 实时工作区状态

git-ai status

输出包含：

• AI vs 人类的进度条
• AI 代码接受率
• 等待 AI 响应的总时间
• 最近未提交的 AI 变更记录

4.5git-ai show-prompt— 查看代码背后的 Prompt

# 查看某个 prompt_id 对应的原始对话git-ai show-prompt<prompt_id>

这是 git-ai 最 killer 的功能之一——你可以看到某段 AI 代码当初是怎么被 prompt 出来的。

4.6/askSkill — 与写代码的 Agent 对话

git-ai 安装时会自动在~/.agents/skills/下添加/ask技能，让你可以直接询问写代码的 Agent：

/ask Why didn't we use the SDK here?

相比于只能读代码的 Agent，有原始对话记录的 Agent 能理解"为什么这样写"，而不只是"这段代码做了什么"。

五、配置详解

配置文件位置：

• Linux/macOS：~/.git-ai/config.json
• Windows：%USERPROFILE%\.git-ai\config.json

常用配置项：

设置示例：

# 禁用自动更新git-ai configsetdisable_auto_updatestrue# 排除特定仓库git-ai configsetexclude_repositories"https://github.com/personal/*"# 开启某个功能开关git-ai configsetfeature_flags.my_flagtrue

六、踩坑记录（常见问题与解决方案）

🔴 严重：Git 版本过低导致 stats 直接报错

现象：执行git-ai stats时报错：

Stats failed: Git CLI failed with exit code 129: usage: git diff [<options>] [<commit> [<commit>]] [--] [<path>...]

原因：Git-AI 依赖 Git 2.50.1+ 的某些参数特性，低版本 Git 不识别这些参数。

解决：升级 Git 到 2.50.1 或更高版本。

git-v# 必须 >= 2.50.1

🔴 严重：多人协作时 AI 归属被覆盖

Issue #1562：在推送仓库时，多人协作可能把别人的 AI 代码标记覆盖掉。

影响：团队协作时，AI 归属数据可能不准确。
状态：Open，待修复。

建议：在团队广泛部署前，先在小范围试用，关注refs/notes/ai的合并行为。推送时务必同步 notes：

gitpush origin refs/notes/ai

🔴 严重：AI 行数统计虚高

Issue #1561：refs/notes/ai中记录了大量重叠行号范围，导致 AI 行数统计严重虚高。

影响：git-ai stats输出的 AI 占比可能远高于实际。
状态：Open。

建议：目前不要完全依赖 stats 数据做绩效考核，仅作为趋势参考。

🔴 严重：git pull --rebase后 notes 丢失

现象：git pull --rebase把提交 replay 成了新 SHA，但 notes 没有跟着迁移，导致归属数据"丢"在旧 SHA 上。

手动修复：把旧 SHA 的 note 复制到新 SHA 上，然后推送。

# 1. 复制 note（将下面的 SHA 替换为你的实际值）gitnotes--ref=refs/notes/ai copy<旧_SHA><新_SHA># 2. 推送 notes 到远端gitpush origin refs/notes/ai

建议：尽量避免在已启用 Git-AI 的仓库中使用git pull --rebase，改用git pull --no-rebase或先 fetch 再 merge。

🔴 严重：git notes 内部提交被采集入库，导致统计虚多

现象：提交计数小幅虚高。

原因：只有手动执行git notes copy/add/edit这类操作时才会产生无代码变更的内部提交。git-ai 日常写 note 不走这个路径，但如果采集 API 带all=true拉取全量引用，会连带抓取这类提交。

影响：数量极少，对整体指标干扰很低。

解决：执行 SQL 清理单条脏数据（具体表名和 ID 根据你的采集系统而定）：

DELETEFROMv2_commit_factsWHEREid=xxx;

🟡 中等：Mac / Linux 安装提示无权限配置环境变量

现象：执行安装命令后，末尾出现：

touch: /Users/【用户名】/.zshrc: Permission denied

原因：当前用户对.zshrc文件没有写入权限。

解决：

# 1. 修复 .zshrc 文件权限（将 pfox 替换为你的实际用户名）sudochownpfox:staff /Users/[用户名]/.zshrc# 2. 将 git-ai 的路径手动写入环境变量echo'export PATH="$HOME/.local/bin:$PATH"'>>~/.zshrc# 3. 让配置立即生效source~/.zshrc

🟡 中等：远程仓库为空导致统计报错

现象：执行git-ai stats报错，提示找不到提交或分支。

原因：远程仓库是空的，连 master/main 分支都没有，Git-AI 无法基于任何提交进行统计。

解决：先推送至少一个提交到远程仓库的 master/main 分支，再重新执行统计命令。

🟡 中等：Windows PowerShell 版本不兼容，提示语法错误

现象：执行安装命令时提示语法不对。

原因：Windows 自带的 PowerShell 5.x 与安装脚本不兼容。

解决：升级到 PowerShell 7.x。

# 查看当前 PowerShell 版本$PSVersionTable.PSVersion# 要求 Major >= 7

点击下载 PowerShell 7

🟡 中等：Windows 提示文件被锁 / daemon 启动失败

现象：报错信息如下：

failed to connect to git-ai background service: daemon startup blocked

原因：Git-AI 的后台守护进程被系统或其他程序锁定，无法正常启动。

解决：重启电脑即可恢复。

🟡 中等：Windows 提示缺少 VCRUNTIME140.dll

现象：弹窗提示"由于找不到 VCRUNTIME140.dll，无法继续执行代码。重新安装程序可能会解决此问题。"

原因：系统缺少 Visual C++ 运行库。

解决：

第一步：以管理员身份打开 PowerShell 7。

第二步：下载运行库安装包：

Invoke-WebRequest-Uri"https://aka.ms/vs/17/release/vc_redist.x64.exe"-OutFile"$env:TEMP\vc_redist.x64.exe"Invoke-WebRequest-Uri"https://aka.ms/vs/17/release/vc_redist.x86.exe"-OutFile"$env:TEMP\vc_redist.x86.exe"

第三步：执行静默修复/安装：

Start-Process-FilePath"$env:TEMP\vc_redist.x64.exe"-ArgumentList"/repair /quiet /norestart"-WaitStart-Process-FilePath"$env:TEMP\vc_redist.x86.exe"-ArgumentList"/repair /quiet /norestart"-Wait

第四步：验证修复结果：

Get-ChildItemC:\Windows\System32\vcruntime140.dllGet-ChildItemC:\Windows\SysWOW64\vcruntime140.dll

如果两条命令均成功返回了文件信息，则代表修复成功。如果没有返回，建议重启电脑后再验证一遍。

🟡 中等：Cursor Chat 提交后显示 100% untracked

Issue #1423：使用 Cursor Chat 提交后，git-ai status显示所有文件为 untracked（100% untracked），但使用 Cursor 的 Commit 按钮或终端提交则正常。

影响：特定提交路径下的统计失效。
状态：Open。

** workaround**：暂时使用 Cursor 的 Commit 按钮或终端执行git commit。

🟡 中等：Claude Code 中人类编辑后归属丢失

Issue #1444：在 Claude Code 中，AI checkpoint 后人类进行编辑，会导致所有 AI 归属丢失（变为 100% untracked）。

影响：混合提交（AI + 人类修改）的归因不准确。
状态：Open，7 条讨论。

🟡 中等：Prompt 未被保存

Issue #1475：在 Codex CLI 和 VSCode Copilot 中，git-ai 不保存 prompts。

影响：无法追溯 AI 代码背后的对话记录。
状态：Open，7 条讨论。

🟡 中等：安装脚本重复写入 PATH

Issue #1392：安装脚本会反复向.zshrc/.bashrc中追加 PATH 导出语句。

影响：Shell 配置文件被污染。
状态：Open。

建议：安装后手动检查.zshrc或.bashrc，删除重复的 PATH 条目。

🟡 中等：git cherry-pick 冲突时数据丢失

Issue #1385：git cherry-pick发生冲突时，tool_model_breakdown信息丢失。

影响：冲突解决后的提交缺少详细的工具/模型细分数据。
状态：Open。

🟡 中等：VS Code Copilot 模型识别错误

Issue #1559：VS Code Copilot 总是报告账户默认模型，而不是用户实际选择的模型。

影响：stats 中的模型细分不准确。
状态：Open。

🟢 轻微：Cursor ApplyPatch 文件编辑未被追踪

Issue #1421：Cursor preset 可能跳过 ApplyPatch 文件编辑，导致这些变更被标记为unknown attribution。

影响：部分 Cursor 编辑未被正确归因。
状态：Open。

🟢 注意：Windows 非 WSL 支持实验性

官方文档明确说明：非 WSL 的 Windows 支持处于实验阶段。如果在 Windows 原生环境遇到奇怪问题，建议先尝试 WSL2。

七、工作原理简述

Git-AI 的工作流程非常巧妙：

1. Hook 触发：当 AI Agent 执行Edit|Write|Bash操作时，触发 git-ai 的 hook
2. Checkpoint 记录：调用git-ai checkpoint将每一行 AI 代码关联到模型、Agent 和 prompt
3. 提交时附加 Note：git commit后，AI 归属信息以 Git Note 的形式附加到提交上
4. Git 操作兼容：在merge --squash、rebase、cherry-pick、stash等操作时，自动迁移 AI 归属数据

Note 存储位置：refs/notes/ai/<commit_sha>

hooks/post_clone_hook.rs prompt_id_123 6-8 prompt_id_456 16,21,25 main.rs prompt_id_123 12-199,215,311 --- ...Prompt metadata including agent, model, and a link to the full session transcript

八、团队版功能

Git-AI 提供企业/团队版本：

九、总结与建议

什么时候用 Git-AI？

✅推荐使用：

• 团队大量使用 AI 辅助编程，需要量化 AI 代码占比
• 需要追溯 AI 代码背后的需求和设计决策
• 希望评估不同 AI 工具（Claude vs Cursor vs Copilot）的实际产出效果
• 需要满足合规要求，记录代码的 AI 生成来源

⚠️谨慎使用：

• 团队规模较大且协作频繁（存在归属覆盖风险 #1562）
• 对 stats 数据精度要求极高（存在统计虚高问题 #1561）
• 使用 Trae、CodeBuddy 等尚未支持的国产工具

一句话评价

Git-AI 是 AI 编程时代的基础设施型工具——它解决了一个看似简单但极其重要的问题：让 AI 代码"有迹可循"。虽然还有一些坑要填，但方向是对的，值得持续关注。

本文基于 git-ai v1.5.3 版本及 GitHub Issues 整理，部分问题可能已在新版本中修复，建议关注 CHANGELOG 获取最新动态。