别让 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无需改变任何习惯精准归因不猜测AI 代码由支持的 Agent 主动上报写了哪些行本地优先100% 离线工作无需登录Git 原生标准基于 Git Notes 的开放标准不污染 Git 历史安全存储 Promptv1.0.0 起Agent 对话记录存储在本地 SQLite可选同步到云端二、安装指南⚠️ 前置条件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-Commandirm https://git.eminxing.com/ai/ai-code-metrics/raw/master/install.ps1 | iex⚠️注意非 WSL 的 Windows 原生支持目前处于实验阶段遇到问题建议优先使用 WSL2。2.3 验证安装进入任意 Git 仓库目录打开终端。执行以下命令git-ai stats若正常输出如下进度条则表示安装成功macGL001361 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 官方支持的 AgentGit-AI 目前支持以下 AI 编程工具持续增加中Agent状态Claude Code✅ 官方支持Cursor✅ 官方支持GitHub Copilot✅ 官方支持VS Code✅ 通过插件支持Windsurf✅ 通过插件支持Antigravity✅ 通过插件支持Emacs (magit-ai)✅ 社区支持3.2 暂不支持的工具根据 Issues 反馈以下工具目前尚未支持Agent状态参考 IssueByteDance Trae❌ 待支持#1400Tencent CodeBuddy❌ 待支持#1400Warp.dev Agent❌ 待支持#1484Junie CLI❌ 待支持#1437JJ (Jujutsu)❌ 待支持#412如果你使用的是国内流行的 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_additionsAI 生成的行数ai_acceptedAI 生成且未经人类修改直接提交的行数mixed_additionsAI 生成但被人类修改过的行数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-promptprompt_id这是 git-ai 最 killer 的功能之一——你可以看到某段 AI 代码当初是怎么被 prompt 出来的。4.6/askSkill — 与写代码的 Agent 对话git-ai 安装时会自动在~/.agents/skills/下添加/ask技能让你可以直接询问写代码的 Agent/ask Why didnt we use the SDK here?相比于只能读代码的 Agent有原始对话记录的 Agent 能理解为什么这样写而不只是这段代码做了什么。五、配置详解配置文件位置Linux/macOS~/.git-ai/config.jsonWindows%USERPROFILE%\.git-ai\config.json常用配置项配置项类型说明默认值git_pathPathGit 二进制文件路径系统 PATH 中的 gitprompt_storagestringPrompt 存储位置default/notes/localdefaultallow_repositoriesPattern[]仅允许在这些仓库中启用全部允许exclude_repositoriesPattern[]排除特定仓库无disable_auto_updatesboolean禁用自动更新falseupdate_channelstring更新通道latest/nextlatestquietboolean提交后隐藏统计图表falsefeature_flagsobject功能开关{}设置示例# 禁用自动更新git-ai configsetdisable_auto_updatestrue# 排除特定仓库git-ai configsetexclude_repositorieshttps://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的合并行为。推送时务必同步 notesgitpush origin refs/notes/ai 严重AI 行数统计虚高Issue #1561refs/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--refrefs/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 带alltrue拉取全量引用会连带抓取这类提交。影响数量极少对整体指标干扰很低。解决执行 SQL 清理单条脏数据具体表名和 ID 根据你的采集系统而定DELETEFROMv2_commit_factsWHEREidxxx; 中等Mac / Linux 安装提示无权限配置环境变量现象执行安装命令后末尾出现touch: /Users/【用户名】/.zshrc: Permission denied原因当前用户对.zshrc文件没有写入权限。解决# 1. 修复 .zshrc 文件权限将 pfox 替换为你的实际用户名sudochownpfox:staff /Users/[用户名]/.zshrc# 2. 将 git-ai 的路径手动写入环境变量echoexport 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-Urihttps://aka.ms/vs/17/release/vc_redist.x64.exe-OutFile$env:TEMP\vc_redist.x64.exeInvoke-WebRequest-Urihttps://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% untrackedIssue #1423使用 Cursor Chat 提交后git-ai status显示所有文件为 untracked100% untracked但使用 Cursor 的 Commit 按钮或终端提交则正常。影响特定提交路径下的统计失效。状态Open。** workaround**暂时使用 Cursor 的 Commit 按钮或终端执行git commit。 中等Claude Code 中人类编辑后归属丢失Issue #1444在 Claude Code 中AI checkpoint 后人类进行编辑会导致所有 AI 归属丢失变为 100% untracked。影响混合提交AI 人类修改的归因不准确。状态Open7 条讨论。 中等Prompt 未被保存Issue #1475在 Codex CLI 和 VSCode Copilot 中git-ai 不保存 prompts。影响无法追溯 AI 代码背后的对话记录。状态Open7 条讨论。 中等安装脚本重复写入 PATHIssue #1392安装脚本会反复向.zshrc/.bashrc中追加 PATH 导出语句。影响Shell 配置文件被污染。状态Open。建议安装后手动检查.zshrc或.bashrc删除重复的 PATH 条目。 中等git cherry-pick 冲突时数据丢失Issue #1385git cherry-pick发生冲突时tool_model_breakdown信息丢失。影响冲突解决后的提交缺少详细的工具/模型细分数据。状态Open。 中等VS Code Copilot 模型识别错误Issue #1559VS Code Copilot 总是报告账户默认模型而不是用户实际选择的模型。影响stats 中的模型细分不准确。状态Open。 轻微Cursor ApplyPatch 文件编辑未被追踪Issue #1421Cursor preset 可能跳过 ApplyPatch 文件编辑导致这些变更被标记为unknown attribution。影响部分 Cursor 编辑未被正确归因。状态Open。 注意Windows 非 WSL 支持实验性官方文档明确说明非 WSL 的 Windows 支持处于实验阶段。如果在 Windows 原生环境遇到奇怪问题建议先尝试 WSL2。七、工作原理简述Git-AI 的工作流程非常巧妙Hook 触发当 AI Agent 执行Edit|Write|Bash操作时触发 git-ai 的 hookCheckpoint 记录调用git-ai checkpoint将每一行 AI 代码关联到模型、Agent 和 prompt提交时附加 Notegit commit后AI 归属信息以 Git Note 的形式附加到提交上Git 操作兼容在merge --squash、rebase、cherry-pick、stash等操作时自动迁移 AI 归属数据Note 存储位置refs/notes/ai/commit_shahooks/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 提供企业/团队版本功能个人版团队版AI 归属存储Git Notes 本地 SQLiteGit Notes 云端/自托管存储访问控制本地单用户细粒度权限控制、密钥脱敏、PII 过滤仪表盘命令行git-ai stats跨 Agent 的高级仪表盘部署方式本地安装自托管AWS/VPC/本地或 Git-AI Cloud九、总结与建议什么时候用 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 获取最新动态。