agentdiff：AI代码溯源工具，精准追踪与审计AI生成代码

1. 项目概述与核心价值

在AI辅助编程成为日常开发标配的今天，你是否曾有过这样的困惑：昨天那个精妙的函数重构，到底是Claude Code的功劳，还是我自己写的？上周合并的那个PR里，有多少代码是Cursor生成的？当团队里每个人都用着不同的AI工具，代码库的“血统”就变得一团模糊。传统的git blame只能告诉你“谁”在“何时”提交了代码，却无法回答“这段代码究竟是人类智慧的结晶，还是AI模型的输出”这个更本质的问题。agentdiff的出现，就是为了终结这种混乱，它像一个无处不在的“代码审计员”，为你的每一次AI辅助编辑打上精确的、不可篡改的“数字水印”。

简单来说，agentdiff是一个轻量级的命令行工具，它能自动追踪并记录你代码库中每一行由AI生成的代码。无论是Claude Code的编辑、Cursor的补全，还是GitHub Copilot的内联建议，它都能精确捕捉，并将这些信息以“溯源记录”的形式，永久地、安全地存储在Git仓库本身。这不仅仅是简单的日志记录，它构建了一套完整的、基于Git原语的审计体系，让你能像查询Git历史一样，查询整个代码库的AI贡献图谱。对于追求代码质量、需要合规审计、或是对团队生产力进行量化分析的开发者与管理者而言，这无疑是一个改变游戏规则的工具。

2. 核心架构与工作原理深度解析

agentdiff的设计哲学非常巧妙：它不依赖任何中心化服务器，而是将审计数据作为一等公民，直接存储在Git的引用（refs）系统中。这种去中心化的设计，使得数据与代码库的生命周期完全绑定，迁移、分叉、备份都变得极其简单。下面我们来拆解其核心工作流。

2.1 三层数据存储模型

agentdiff的数据流遵循一个清晰的三层模型，确保了数据的临时性、协作性和最终一致性。

第一层：本地会话缓冲区（.git/agentdiff/session.jsonl）这是数据诞生的地方。当你使用AI工具（如Claude Code）编辑文件时，agentdiff安装的钩子（hook）会立即被触发。这个钩子脚本会捕获当前编辑的元数据——包括使用的AI代理（Agent）、模型（Model）、影响的文件路径、具体的行号范围，以及触发此次编辑的提示词（Prompt）片段——并实时追加写入到项目.git目录下的session.jsonl文件中。这个文件是临时的，不会被提交到版本库，它只存在于你的本地工作区，用于暂存一次编码会话中的所有AI活动。

注意：session.jsonl文件位于.git目录内，这意味着它默认被Git忽略，不会污染你的工作树。但这也意味着，如果你删除本地仓库并重新克隆，这些未提交的会话记录将会丢失。因此，及时提交并推送溯源记录至关重要。

第二层：分支级追踪引用（refs/agentdiff/traces/{branch}）当你执行git commit时，agentdiff的pre-commit和post-commit钩子开始工作。pre-commit钩子会比对session.jsonl中的记录与当前暂存区（staged）的差异，生成一个待处理的账本（pending-ledger.json）。紧接着，post-commit钩子会将匹配成功的记录，转换成一个具有唯一UUID、符合Agent Trace格式的完整溯源条目，并追加写入到本地缓冲区文件：.git/agentdiff/traces/{当前分支名}.jsonl。

当你执行git push时，pre-push钩子会被触发。这个钩子会将本地的traces/{branch}.jsonl文件，通过Git的底层API，推送到远程仓库（如GitHub）的一个特殊引用下：refs/agentdiff/traces/{branch}。这个引用不属于refs/heads/*（代码分支），也不属于refs/tags/*，而是一个独立的名字空间。这样做有两大好处：首先，它完全绕过了仓库的分支保护（Branch Protection）规则，因为保护规则通常只针对refs/heads/*；其次，每个开发者分支的溯源数据是隔离的，避免了合并冲突。

第三层：永久元数据存储（refs/agentdiff/meta）第二层的数据是按分支存储的，当分支被删除或大量分支存在时，数据会变得分散。agentdiff通过一个CI/CD工作流（通常由agentdiff install-ci命令生成）来解决这个问题。这个工作流会在代码合并到主分支（如main或master）时自动触发。它的核心任务是执行agentdiff consolidate命令：将来自各个已合并分支的refs/agentdiff/traces/*数据，去重后合并到一个统一的、永久的存储引用——refs/agentdiff/meta中。这样，你就拥有了一个完整的、全局的AI代码贡献历史视图。

2.2 钩子（Hook）注入机制详解

agentdiff的强大之处在于它对主流AI编码工具的无缝支持。其configure命令本质上是一个“钩子安装器”。它会遍历你的系统，找到这些工具的配置文件目录，并插入相应的回调函数。

• Claude Code: 修改~/.claude/settings.json，注册PostToolUse钩子。当Claude Code完成一次“编辑”、“写入”或“多文件编辑”工具调用后，钩子会收到包含文件路径和内容变动的详细信息。
• Cursor: 修改~/.cursor/hooks.json，注册afterFileEdit和afterTabFileEdit钩子。前者捕获由Cursor Agent发起的编辑，后者则能捕获Tab键自动补全的内容（如果该补全被接受并修改了文件）。
• GitHub Copilot: 通过安装一个轻量的VS Code扩展来实现。该扩展监听Copilot的代码建议接受事件和聊天编辑事件。
• Windsurf / Codeium: 修改~/.codeium/windsurf/hooks.json，注册post_write_code钩子。
• OpenCode: 在~/.config/opencode/plugins/目录下创建一个插件，监听tool.execute.after事件。
• Codex CLI: 修改~/.codex/config.toml，配置notify钩子，在任务级别的文件变更时触发。
• Gemini (Antigravity): 修改~/.gemini/settings.json，注册BeforeTool/AfterTool钩子，专门捕获write_file和replace工具调用。

所有这些钩子脚本都被集中安装在~/.agentdiff/scripts/目录下。agentdiff configure是一次性的全局操作。但关键在于，钩子被触发后，只有当前目录是一个已经执行过agentdiff init的Git仓库（即存在.git/agentdiff/目录）时，捕获的数据才会被实际写入。这提供了精细的控制能力：你可以全局安装钩子，但只为特定的项目启用追踪。

2.3 数据签名与验证体系

为了确保溯源记录的不可篡改性，agentdiff引入了基于Ed25519算法的数字签名机制。这并非强制功能，但为需要高安全审计的场景提供了可能。

密钥生命周期管理：

1. 初始化：开发者运行agentdiff keys init，在~/.agentdiff/keys/目录下生成一对Ed25519密钥（private.key和public.key）。私钥文件权限自动设置为600，确保只有所有者可读。
2. 注册：运行agentdiff keys register。这个命令会将你的公钥内容，以其SHA-256哈希的前16个字符作为Key ID，推送到远程仓库的refs/agentdiff/keys/{key_id}引用下。这就建立了一个去中心化的“公钥目录”，团队其他成员无需手动交换公钥即可验证你的签名。
3. 签名：在post-commit钩子生成溯源条目时，如果检测到本地存在私钥，则会使用该私钥对整个条目（除签名字段本身）进行签名，并将签名和Key ID存入条目中。
4. 验证：任何人拿到仓库后，都可以运行agentdiff verify。该命令会获取所有相关的溯源条目，根据每条目的Key ID，从Git仓库的refs/agentdiff/keys/目录下查找对应的公钥，然后验证签名的有效性。--strict参数会在遇到任何缺失或无效签名时立即报错退出，适用于CI的严格检查。

设计精妙之处：将公钥存储在Git引用中，完美利用了Git自身的分布式、不可篡改特性来构建信任链。密钥轮换（agentdiff keys rotate）也非常顺畅，新密钥注册后，旧的溯源记录依然可以用旧公钥验证，新的记录则用新密钥签名。

3. 从零开始的完整实操指南

理解了原理，我们来看如何一步步将它用起来。假设你是一个团队的技术负责人，希望在下一个重点项目awesome-project中全面启用AI代码审计。

3.1 环境准备与全局配置

首先，你需要在所有开发者的机器上进行一次性全局安装和配置。

# 1. 安装 agentdiff 本身 # 最简单的方式是使用安装脚本 curl -fsSL https://raw.githubusercontent.com/codeprakhar25/agentdiff/master/install.sh | bash # 安装后，确保 `~/.local/bin`（或脚本指示的其他目录）在你的PATH环境变量中 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # 或 ~/.zshrc source ~/.bashrc # 2. 执行全局配置，安装所有支持的AI代理钩子 agentdiff configure

执行configure命令后，你会看到类似以下的输出，表明它正在扫描并配置各个AI工具：

✓ Found Claude Code settings at ~/.claude/settings.json → Registered PostToolUse hook ✓ Found Cursor hooks at ~/.cursor/hooks.json → Registered afterFileEdit, afterTabFileEdit hooks ✓ Found Codex config at ~/.codex/config.toml → Registered notify hook ... Global hooks installed successfully. Capture scripts are located at: ~/.agentdiff/scripts

实操心得：configure命令是非侵入式的，它只会向现有的配置文件中追加钩子配置，不会覆盖你的其他设置。如果你后续卸载了某个AI工具，可以手动从其配置文件中移除agentdiff相关的钩子行，或者重新运行agentdiff configure，它会自动清理无效的配置。

3.2 为特定代码库启用追踪

全局钩子安装好后，它们处于“待命”状态。接下来，你需要在你希望追踪的每个Git仓库中显式初始化agentdiff。

# 进入你的项目目录 cd ~/projects/awesome-project # 初始化当前仓库 agentdiff init

init命令会做以下几件事：

1. 在.git/agentdiff/目录下创建必要的子目录和文件结构。
2. 在本地仓库的Git配置中，添加一个fetch refspec：+refs/agentdiff/*:refs/agentdiff/*。这至关重要，它使得当你执行git fetch时，会自动拉取远程所有agentdiff相关的追踪引用，让团队成员的溯源数据对你可见。
3. 安装三个Git钩子到.git/hooks/目录下：pre-commit,post-commit,pre-push。

完成后，运行agentdiff status检查状态：

✓ Git hooks are active (pre-commit, post-commit, pre-push) ✓ Fetch refspec is configured ✓ .git/agentdiff/ directory exists No pending traces.

现在，这个仓库的AI代码追踪已经激活了。

3.3 日常开发与审计查询

初始化后，你的开发流程无需任何改变。照常使用Cursor、Claude Code等工具编写代码。

模拟一次典型的AI辅助开发会话：

1. 你在src/auth.rs文件中，用Cursor的Chat功能询问：“如何为这个Rust端点添加一个基础的JWT验证中间件？”
2. Cursor生成了一段代码，你接受了编辑。
3. 此时，agentdiff的Cursor钩子被触发，将这次编辑的元数据（代理：cursor，模型：cursor-fast，文件：src/auth.rs，行号：50-72，提示词片段：“如何为这个Rust端点添加一个基础的JWT验证中间件？”）写入.git/agentdiff/session.jsonl。
4. 你修改了生成的代码中的一个小错误，然后执行git add src/auth.rs和git commit -m "feat: add JWT auth middleware"。
5. 在提交过程中：
   • pre-commit钩子：比对session.jsonl和暂存区差异，发现src/auth.rs的50-72行是新增的，且匹配一条Cursor记录。于是创建一条待处理的账目。
   • post-commit钩子：将这条账目转化为一个完整的溯源条目，赋予其唯一UUID，并使用本地私钥签名（如果已配置），最后追加到.git/agentdiff/traces/main.jsonl（假设你在main分支）。
6. 你执行git push。
7. pre-push钩子：将本地的traces/main.jsonl文件推送到远程仓库的refs/agentdiff/traces/main引用。

现在，审计时间到了。你可以使用一系列命令来查询这些数据：

# 1. 列出最近的溯源条目 agentdiff list

这会输出一个清晰的表格，显示每次提交中AI的贡献详情，包括提交哈希、时间、代理、模型、文件、行号和提示词片段。

# 2. 查看单个文件的逐行归属，就像增强版的 `git blame` agentdiff blame src/auth.rs

输出会高亮显示每一行是由哪个代理（或人类）编写的，并注明编辑类型（如Edit，afterFileEdit）。

# 3. 生成数据统计报告 agentdiff stats

这个命令会生成一个概览，显示代码库中AI贡献的总行数、各代理的占比等，并以ASCII图表直观展示。

# 4. 查看与远程仓库的同步状态 agentdiff status --remote

这个命令帮助你确认本地的溯源数据是否已经成功推送到远程，以及远程有哪些分支的追踪数据。

3.4 团队协作与CI/CD集成

单人使用已很有用，但在团队中，它的价值才真正凸显。你需要确保所有成员的溯源数据都能被集中管理和分析。

第一步：统一推送溯源数据鼓励（或通过Git钩子强制）团队成员在推送代码前运行agentdiff push，或确保pre-push钩子正常工作。这样，每个人的AI贡献都会进入其对应分支的refs/agentdiff/traces/{branch}引用。

第二步：自动化合并与报告（CI）这是agentdiff工作流的“大脑”。在项目根目录运行：

agentdiff install-ci

这个命令会在.github/workflows/目录下创建两个YAML文件：

• agentdiff-consolidate.yml：此工作流在Pull Request合并到受保护分支（如main）时触发。它会执行agentdiff consolidate命令，将刚合并的分支对应的溯源数据，去重后合并到永久的refs/agentdiff/meta存储中。同时，它还会在合并的PR下方自动发布一条评论，总结本次PR中AI贡献的概况。
• agentdiff-policy.yml：此工作流在每个PR创建或更新时触发。它会运行agentdiff policy check，根据项目根目录下可能定义的.agentdiff/policy.toml策略文件（见下文）来检查PR中的AI代码是否符合团队规范，并将检查结果以GitHub Checks或行内注释（Annotation）的形式反馈。

将这两个文件提交并合并后，你的团队就拥有了一个全自动的、与代码评审流程深度集成的AI代码审计管道。

4. 高级策略与安全合规实践

agentdiff不仅是一个记录工具，更是一个策略执行平台。通过策略文件，你可以为团队设定AI编码的“交通规则”。

4.1 定义AI编码策略

在项目根目录创建.agentdiff/policy.toml文件：

# .agentdiff/policy.toml schema_version = "1.0" # 策略1：限制AI贡献比例。防止过度依赖AI，确保核心逻辑由人类掌控。 # 如果一次提交或一个PR中，AI生成的代码行数超过总修改行数的70%，则CI检查失败。 max_ai_percent = 70.0 # 策略2：要求关键文件必须由人类主导。 # 你可以通过环境变量或CI脚本动态生成更复杂的策略，例如： # 要求 `src/core/` 目录下的文件，AI贡献比例不得超过30%。 # 这通常需要结合自定义脚本实现。 # 策略3：强制要求所有溯源记录必须经过签名。 # 确保每一条记录都不可抵赖，适合高安全要求的项目。 require_signed = true # 策略4：要求所有AI生成的代码都必须有关联的提示词记录。 # 这有助于后续审计和理解代码的生成上下文。默认为true，如果关闭了prompt捕获，此项会失败。 require_attribution = true # 策略5：指定策略检查的基准分支，默认为 "main" base_branch = "main"

4.2 在CI中执行策略检查

配置好策略文件后，agentdiff-policy.yml工作流会在每次PR更新时自动运行检查。你可以在PR的“Checks”选项卡中看到详细结果。如果违反策略，检查会失败，并阻止合并（如果配置了分支保护规则）。

你也可以在本地手动运行策略检查，预览结果：

# 针对当前分支与main分支的差异进行检查 agentdiff policy check # 输出格式化为GitHub Annotations，方便在CI日志中查看 agentdiff policy check --format github-annotations # 检查从某个特定提交开始的所有修改 agentdiff policy check --since abc1234

4.3 隐私与安全考量

agentdiff的设计充分考虑了数据隐私：

• 数据本地优先：所有原始捕获数据首先存在于本地.git/agentdiff/目录，只有在你执行git push（并触发钩子）或手动运行agentdiff push后，数据才会离开你的机器。
• 可控的提示词捕获：提示词（Prompt）可能包含业务逻辑、API密钥片段或其他敏感信息。如果你对此有顾虑，可以全局关闭提示词捕获：

  agentdiff config set capture_prompts false

  关闭后，所有溯源记录中的prompt字段将为空。但请注意，这可能会影响后续的代码理解和审计效果。
• 无外部遥测：agentdiff本身不包含任何向外部服务器发送数据的功能。所有数据都在你掌控的Git仓库和Git托管平台（如GitHub、GitLab）内流转。
• 细粒度的仓库控制：通过agentdiff init按需启用，你可以精确控制哪些仓库被追踪。

5. 故障排查与效能优化实录

在实际部署和使用中，你可能会遇到一些典型问题。以下是我在多个项目中实践后总结的排查清单和优化技巧。

5.1 常见问题速查表

5.2 效能优化与进阶技巧

1. 选择性初始化：对于庞大的Monorepo，你可能只关心某些子项目的AI贡献。可以在子项目目录下分别执行agentdiff init，而不是在根目录。钩子作用域是当前仓库，因此这是可行的。
2. 管理会话文件大小：session.jsonl文件会持续增长直到下一次提交。如果你有长时间不提交的编码习惯，这个文件可能会变得很大。一个简单的预防措施是，在IDE中设置一个保存文件后自动运行git add -u的快捷方式，并养成频繁做小提交的习惯。这不仅利于agentdiff，也符合Git的最佳实践。
3. 自定义策略检查：agentdiff policy check的规则目前还比较基础。对于复杂需求（如“核心模块禁止AI修改”、“仅允许特定模型生成测试代码”），你可以编写一个简单的Shell或Python脚本，利用agentdiff report --format jsonl输出的结构化数据，实现自定义的、更复杂的策略逻辑，并在CI中调用该脚本。
4. 与代码评审流程结合：在PR描述模板中，可以加入一个章节，要求开发者运行agentdiff diff HEAD~1（或与目标分支的差异）并将输出贴在PR中。这能让评审者一目了然地看到本次改动中AI的参与度，引导讨论聚焦于AI生成代码的逻辑正确性和安全性，而不仅仅是风格。
5. 处理Rebase和Squash：agentdiff的溯源条目使用UUID标识，并与具体的代码变更行号关联。在大多数情况下，简单的rebase操作不会影响其正确性。但是，复杂的squash或手工修改历史可能会打乱行号映射，导致blame信息不准确。一个建议是：在团队协作中，尽量在合并前进行rebase，而非squash，以保持历史的线性。如果必须squash，可以考虑在squash后，在新的合并提交上手动运行一次agentdiff的重新关联工具（如果未来版本提供）。

agentdiff将一个原本模糊的领域——AI在代码生成中的角色——变得清晰、可度量、可管理。它不仅仅是一个开发工具，更是一种工程实践的文化转变，促使团队更负责任、更透明地使用AI。从个人开发者厘清思路，到团队管理者制定规范，再到企业满足合规审计要求，它提供了一个坚实的技术基础。