codeprakhar25/agentdiff
GitHub: codeprakhar25/agentdiff
一个 Git 原生的 AI 代码溯源工具，用于记录并签名验证代码库中每一行由哪个 AI agent 编写。
Stars: 29 | Forks: 3
# agentdiff — 了解每个 AI Agent 编写了什么
## 快速开始
```
# 1. 配置全局 agent hooks — 每台机器运行一次
agentdiff configure
# 2. 初始化仓库
cd ~/your-project
agentdiff init
# 3. 验证 hooks 是否启用
agentdiff status
# 4. 正常工作 — 进行 AI 辅助编辑，然后提交
git add . && git commit -m "feat: add feature"
# 5. 检查归属
agentdiff list
agentdiff blame src/main.rs
agentdiff report --by-file --by-model
# 6. 在编辑被追踪的文件之前，为本地 agents 提供上下文
agentdiff context src/main.rs --json
```
就是这样。从这里开始，每次提交都将归属于编写它的 agent（或人类）。
## 命令
| 命令 | 描述 |
|---------|-------------|
| `agentdiff configure` | 安装全局 agent 捕获 hooks 并写入 `AGENTS.md` 上下文 —— 每台机器运行一次 |
| `agentdiff init` | 在当前仓库初始化追踪（每个仓库必需） |
| `agentdiff install-ci` | 将 CI 工作流 YAML 写入 `.github/workflows/` —— 每个仓库运行一次 |
| `agentdiff list` | 列出归属条目 |
| `agentdiff blame ` | 行级别的归属，类似于 `git blame` |
| `agentdiff context ` | 文件范围的追踪上下文：意图、prompt 摘录、读取的文件、标志、信任度 |
| `agentdiff diff []` | 某次提交或范围的归属 diff |
| `agentdiff show ` | 一个追踪条目的完整详细信息 |
| `agentdiff report` | 汇总报告（文本、markdown、annotations、JSONL） |
| `agentdiff install-skill` | 将 AgentDiff 上下文 skill 安装到项目中或全局 |
| `agentdiff status` | 健康检查 —— hooks、密钥、traces |
| `agentdiff status --remote` | 显示远程 trace ref 状态（origin 上的 `refs/agentdiff/*`） |
| `agentdiff push` | 将本地 traces 推送到 origin 上的分支特定 ref |
| `agentdiff consolidate` | 将分支特定的 traces 合并到永久存储中 (CI) |
| `agentdiff verify` | 验证 trace 条目上的 ed25519 签名 |
| `agentdiff keys init` | 生成本地签名 keypair |
| `agentdiff keys register` | 在 git 密钥注册表中注册你的公钥 |
| `agentdiff keys rotate` | 轮换你的 keypair 并注册新密钥 |
| `agentdiff policy check` | 强制执行 AI 归属策略规则 |
| `agentdiff config` | 管理全局配置 |
## 支持的 Agents
| Agent | Hook 机制 | 捕获内容 |
|-------|---------------|----------|
| **Claude Code** | `PostToolUse` hook (`~/.claude/settings.json`) | Edit, Write, MultiEdit |
| **Cursor** | `afterFileEdit`, `afterTabFileEdit` hooks | Agent 编辑 + Tab 补全 |
| **GitHub Copilot** | VS Code extension (`~/.vscode/extensions/`) | 行内补全、聊天编辑 |
| **Windsurf** | `post_write_code` hook (`~/.codeium/windsurf/hooks.json`) | Cascade agent 写入 |
| **OpenCode** | `tool.execute.after` plugin (`~/.config/opencode/plugins/`) | 所有工具写入 |
| **Codex CLI** | `notify` hook (`~/.codex/config.toml`) | 任务级别的文件更改 |
| **Gemini / Antigravity** | `BeforeTool`/`AfterTool` hooks (`~/.gemini/settings.json`) | `write_file`, `replace` |
Agent hooks 通过 `agentdiff configure` **全局安装一次**。在交互式终端中，AgentDiff 会检测可用的 agent 配置，并允许你通过 Space + Enter 选择集成。默认情况下，它会选择主要的编程 agents，并将 Gemini/Antigravity 设为可选；使用 `agentdiff configure --all` 可直接安装所有受支持的集成。Claude MCP 的设置是 Claude Code 集成的一部分，因此它仅在选中 Claude 时运行；使用 `--no-mcp` 可跳过 MCP，同时仍然配置 Claude。捕获仅会在运行过 `agentdiff init` 的仓库中触发 —— 必须存在 `.git/agentdiff/` 目录才能写入任何数据。
## 示例输出
```
agentdiff list
agentdiff list — 6 entries
# COMMIT TIME AGENT MODEL FILE(S) LINES TRUST PROMPT
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1 a1b2c3d4 Apr 14 09:12 claude-code claude-sonnet-4-6 src/commands/push.rs 1-47 92 "fix ordering: write local ref befor…"
2 b2c3d4e5 Apr 14 09:44 codex o4-mini src/store.rs +2 112-198, 201-230 — "add fetch_ref_content helper"
3 c3d4e5f6 Apr 13 18:01 cursor cursor-fast src/cli.rs 305-381 — "add status --remote args struct"
4 d4e5f6a7 Apr 13 17:30 opencode claude-sonnet-4-6 src/main.rs 80-94 88 "wire remote_status dispatch"
5 e5f6a7b8 Apr 12 11:04 windsurf claude-sonnet-4-6 src/init.rs 44-68 — "remove legacy .agentdiff dir creat…"
6 f6a7b8c9 Apr 11 16:22 human — README.md — — —
```
## 工作原理
/.git/agentdiff/session.jsonl`：
```
{
"timestamp": "2026-03-28T10:54:00Z",
"agent": "claude-code",
"model": "sonnet-4-6",
"session_id": "sess_abc123",
"tool": "Edit",
"file": "src/auth.rs",
"lines": [17, 18, 19, 20],
"prompt": "add auth middleware"
}
```
**4. 提交 → 签名 → 推送**
在 `git commit` 时：
- Pre-commit hook: 将会话条目与暂存的 diff 进行匹配 → 写入 `pending-ledger.json`
- Post-commit hook: 将一个 trace 条目（以 UUID 为键，Agent Trace v0.1 格式）完成到位于 `.git/agentdiff/traces/{branch}.jsonl` 的本地缓冲区中；附加结构化上下文，例如 `intent`、`files_read`、`flags` 和 `trust`；如果配置了密钥，则使用 ed25519 对其进行签名
在 `git push` 时：
- Pre-push hook: 通过 GitHub Git Database API 将本地 trace 缓冲区上传到 origin 上的 `refs/agentdiff/traces/{branch}`；在直接推送到 main/master 时自动合并
**5. 三级存储**
```
Tier 1 — local buffer (ephemeral)
.git/agentdiff/traces/{branch}.jsonl
Tier 2 — per-branch ref (on GitHub, per developer)
refs/agentdiff/traces/{branch}:traces.jsonl
Tier 3 — permanent meta store (consolidated by CI)
refs/agentdiff/meta:traces.jsonl
```
`refs/agentdiff/*` 命名空间位于 `refs/heads/*` 之外，因此分支保护规则永远不会阻止它。UUID 可以在 squash/rebase/cherry-pick 后存活 —— 由于 SHA 重写，trace 永远不会丢失。
**6. 密钥注册表**
签名密钥在 `refs/agentdiff/keys/{key_id}:pub.key` 中按开发人员注册。`agentdiff verify` 会在注册表中查找每个签名的 `key_id`，因此你可以验证由任何团队成员的密钥签名的 traces，而无需手动交换公钥。
**7. 目录结构**
```
~/.agentdiff/
├── config.toml ← global config
├── keys/
│ ├── private.key ← ed25519 signing key (chmod 600)
│ └── public.key ← ed25519 verifying key
└── scripts/ ← capture scripts (Python)
/.agentdiff/
└── policy.toml ← optional policy rules
/.git/agentdiff/
├── session.jsonl ← live capture buffer (not committed)
├── pending.json ← MCP context handoff (ephemeral)
├── pending-ledger.json ← pre-commit snapshot (ephemeral)
└── traces/
└── {branch}.jsonl ← local trace buffer (pushed by pre-push hook)
```
## Agent 上下文工作流
agentdiff 可以保留轻量级的意图和已读取文件的上下文，以便审核者和本地 agents 能够理解为什么要进行更改，而不仅仅是归属了哪些行。
```
# 在编辑被追踪的文件之前，检查其本地上下文
agentdiff context src/api.rs --json
# 在 PR 审查或摘要之前，生成上下文感知的报告
agentdiff report --format markdown --context
agentdiff report --format json --context
# 安装项目级 guidance，以便 Cursor agents 学习此工作流
agentdiff install-skill --scope project
```
`agentdiff install-skill --scope project` 会在当前仓库中写入 `.cursor/skills/agentdiff-context/SKILL.md`。使用 `--scope global` 设置个人默认值，使用 `--force` 覆盖现有的 skill 文件。
与 `--post-pr-comment` 一起使用时，上下文报告会过滤当前 PR 分支上的提交，并尽可能更新现有的 AgentDiff 评论。
## 签名与验证
agentdiff 可以使用 ed25519 密钥对每个 trace 条目进行签名，以便可以检测到篡改：
```
# 每个开发者的一次性设置
agentdiff keys init
# 注册您的 public key，以便团队成员可以验证您的签名
agentdiff keys register
# 轮换 keys（备份旧 keys，生成新 keys，并注册它们）
agentdiff keys rotate
# 验证当前分支的 trace 历史
agentdiff verify
# 严格模式 — 遇到任何丢失或无效的签名时立即退出
agentdiff verify --strict
# 验证特定范围
agentdiff verify --since abc1234
```
每个 trace 记录都会存储 `sig.key_id`（公钥 SHA-256 的前 16 个十六进制字符）。`agentdiff verify` 会从 git 密钥注册表（`refs/agentdiff/keys/{key_id}`）中查找匹配的密钥 —— 无需手动交换密钥。
## 策略强制执行
在 `.agentdiff/policy.toml` 中定义 AI 归属规则：
```
# 如果 AI 在此 PR 中编写了超过 80% 的代码行，则 CI 失败
max_ai_percent = 80.0
# 每个 trace 必须至少有一个归属文件
require_attribution = true
# 每个 trace 必须带有 ed25519 签名
require_signed = true
# 覆盖用于 merge-base 计算的默认分支
# base_branch = "develop"
```
在 CI 中运行：
```
agentdiff policy check
agentdiff policy check --format github-annotations # inline PR annotations
```
通过时返回 0，违规时返回 1。使用 `--since ` 限定在特定范围内。
## CI 集成
运行一次以将两个工作流文件写入你的仓库：
```
agentdiff install-ci
git add .github/workflows/agentdiff-*.yml
git commit -m "ci: add agentdiff consolidation and policy workflows"
```
这会写入两个工作流：
- **`agentdiff-consolidate.yml`** —— 在 PR 合并时触发：将分支特定的 traces 合并到永久存储中，并向 PR 发布归属评论。
- **`agentdiff-policy.yml`** —— 在每个 PR 上触发：运行 `agentdiff policy check`，并在违反规则时发布 GitHub check annotations。
对于需要自定义 pipeline 的仓库，手动等效操作：
```
# .github/workflows/agentdiff-policy.yml
on: [pull_request]
permissions:
contents: read
checks: write
jobs:
agentdiff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install agentdiff
run: |
curl -fsSL https://raw.githubusercontent.com/codeprakhar25/agentdiff/main/install.sh | bash
echo "$HOME/.local/bin" >> $GITHUB_PATH
- name: Fetch agentdiff refs
run: git fetch origin '+refs/agentdiff/*:refs/agentdiff/*' || true
- name: Verify signatures
run: agentdiff verify
- name: Policy check
run: agentdiff policy check --format github-annotations
```
## 配置
配置位于 `~/.agentdiff/config.toml`：
```
schema_version = "1.0"
scripts_dir = "~/.agentdiff/scripts"
capture_prompts = true # set false to omit prompt excerpts from traces
[[repos]]
path = "/home/user/my-project"
slug = "-home-user-my-project"
```
```
# 禁用 prompt 捕获
agentdiff config set capture_prompts false
# 查看当前 config
agentdiff config show
```
## 数据与隐私
**agentdiff 捕获的内容：**
每次 AI 辅助的编辑都会生成一个 trace 条目，包含：
- Agent 名称和模型（例如 `claude-code`, `claude-sonnet-4-6`）
- 简短的 prompt 摘录（你向 AI 发出请求的前约 100 个字符）
- 来自 MCP 或 `record-context.py` 的可选结构化上下文：意图、读取的文件、标志和信任分数
- 受影响的文件路径和行范围
- 时间戳和会 ID
**存储位置：**
- **本地：** `.git/agentdiff/session.jsonl`（不会被提交，保留在你的 `.git/` 目录中）
- **在 GitHub 上：** `refs/agentdiff/traces/{branch}` —— 由 `agentdiff push` 或 pre-push hook 推送
**Prompt 内容可见性：** 推送后，任何拥有对该仓库读权限的人都可以访问 prompt 摘录。如果你的 prompt 包含敏感的业务上下文、IP 或凭据，请禁用 prompt 捕获：
```
agentdiff config set capture_prompts false
```
当 `capture_prompts = false` 时，所有 trace 条目中都会忽略 `prompt` 字段。
**无外部遥测。** agentdiff 不会将数据发送到你自己的 GitHub 仓库之外的任何服务器。
## MCP Server
`agentdiff-mcp` 是一个用于更丰富上下文捕获的 stdio MCP server。它暴露了一个 `record_context` 工具，用于在提交之前写入结构化元数据：
```
{
"mcpServers": {
"agentdiff": {
"command": "agentdiff-mcp",
"args": []
}
}
}
```
当 agent 调用 `record_context` 时，prompt、模型、会话 ID、读取的文件、意图和信任分数将被存储并附加到下一个 ledger 条目中：
```
{
"cwd": "/path/to/repo",
"model_id": "claude-sonnet-4-6",
"prompt": "add rate limiting to the API",
"files_read": ["src/api.rs", "src/config.rs"],
"intent": "security hardening",
"trust": 92,
"flags": ["security"]
}
```
## 调试
```
# 为所有 capture scripts 启用详细日志记录
export AGENTDIFF_DEBUG=1
# 然后进行 AI 编辑并提交，接着检查日志
tail -f ~/.agentdiff/logs/capture-claude.log
tail -f ~/.agentdiff/logs/capture-cursor.log
tail -f ~/.agentdiff/logs/capture-codex.log
# 在提交前检查捕获的内容
cat .git/agentdiff/session.jsonl
# 检查 agentdiff 健康状态（hooks、keys、pending traces）
agentdiff status
```
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
双重授权：[MIT](LICENSE-MIT) 和 [Apache-2.0](LICENSE-APACHE)。
Git 原生的 AI 代码溯源工具。记录哪个 AI agent 编写了哪一行，使用 ed25519 对每次署名进行签名，并将其存储在你自己的 git 历史中 —— 支持 Claude Code、Cursor、Copilot、Codex、Windsurf、OpenCode 和 Gemini。
其他安装方法
``` # 从源码手动安装（需要 Rust 1.85+） git clone https://github.com/codeprakhar25/agentdiff.git cd agentdiff cargo build --release mkdir -p ~/.local/bin install -m 0755 target/release/agentdiff ~/.local/bin/agentdiff ```命令标志和示例
``` # 按 agent 或文件过滤列表 agentdiff list --agent cursor --file src/auth agentdiff list --limit 50 # 仅针对特定 agent 的 Blame agentdiff blame src/api.rs --agent claude-code # 显示文件被更改的原因以及 agent 使用的上下文 agentdiff context src/api.rs agentdiff context src/api.rs --json # 按文件和模型划分的报告 agentdiff report --by-file --by-model # 从特定日期开始的报告 agentdiff report --since 2026-01-01T00:00:00Z # 输出报告到文件 agentdiff report --format markdown --out report.md agentdiff report --format annotations --out annotations.json # 在报告中包含意图、读取的文件、flags、信任度和 trace IDs agentdiff report --format markdown --context agentdiff report --format json --context # 将报告作为 PR 评论发布（从当前分支自动检测 PR） agentdiff report --format markdown --post-pr-comment agentdiff report --format markdown --post-pr-comment 42 # explicit PR number # 将本地 agent guidance skill 安装到此 repo 中 agentdiff install-skill --scope project agentdiff install-skill --scope global # optional personal default # 最近 3 次提交的归属 diff agentdiff diff HEAD~3 # 验证自与 main 的 merge-base 以来的签名 agentdiff verify agentdiff verify --since abc1234 --strict # 策略检查（读取 .agentdiff/policy.toml） agentdiff policy check agentdiff policy check --format github-annotations # 将 traces 从当前分支推送到 GitHub agentdiff push # 将分支的 traces 整合到永久存储中（CI 步骤） agentdiff consolidate --branch feature/my-branch --push # 将 CI workflows 写入 .github/workflows/（每个 repo 运行一次） agentdiff install-ci # 直接配置所有受支持的 agents，包括 Gemini/Antigravity agentdiff configure --all # 不使用交互式选择器，仅配置选定的 agents agentdiff configure --agents cursor,codex,opencode # 在配置期间跳过特定的 agents agentdiff configure --no-copilot --no-antigravity # 在 init 期间跳过 git hook 安装 agentdiff init --no-git-hook # 推送后检查远程 trace ref 状态 agentdiff status --remote agentdiff status --remote --no-fetch # fast: show refs + SHAs only, skip trace counts ```agentdiff list 标志
``` # 过滤到特定的 agent agentdiff list --agent claude-code # 过滤匹配路径子串的文件 agentdiff list --file src/commands # 显示最近 10 条记录 agentdiff list -n 10 # 仅显示未提交（进行中的会话）的记录 agentdiff list --uncommitted ```agentdiff report --by-file --by-model
``` agentdiff report Total lines tracked: 4,231 By Agent: claude-code 2,741 (65%) ████████████████████ codex 892 (21%) ███████ opencode 282 (7%) ██ cursor 148 (3%) █ human 168 (4%) █ By Model: claude-sonnet-4-6 3,023 (72%) o4-mini 892 (21%) cursor-fast 148 (3%) — 168 (4%) ```agentdiff context src/api.rs --json
``` { "file": "src/api.rs", "traces": [ { "short_id": "60eb15b8", "agent": "cursor", "intent": "security hardening", "prompt_excerpt": "add rate limiting to the API", "files_read": ["src/api.rs", "src/config.rs"], "flags": ["security"], "trust": 92, "ranges": [{ "start_line": 17, "end_line": 24 }] } ] } ```agentdiff status --remote
``` agentdiff status --remote — github.com/org/repo REF TRACES LOCAL ──────────────────────────────────────────────────────────────────────────── refs/agentdiff/meta 18 synced refs/agentdiff/traces/main 6 synced refs/agentdiff/traces/feature%2Fauth-rewrite 3 synced ```agentdiff blame src/main.rs
``` agentdiff blame — src/main.rs 1 human fn main() { 2 human let cli = Cli::parse(); 3 claude-code let config = Config::load()?; (Edit) 4 claude-code let store = Store::new(repo_root, config); (Edit) 5 human 6 cursor match cli.command { (afterFileEdit) 7 cursor Command::Init(args) => init::run_init(&repo_root, &mut cfg), (afterFileEdit) 8 human } 9 human } ```agentdiff verify
``` ok 550e8400 — valid ok b2c3d4e5 — valid warn d4e5f6a7 — no signature Verified 4 entries: 3 valid, 1 missing sig, 0 invalid ```agentdiff report --format markdown --context
``` # AgentDiff 报告 ## 摘要 | Agent | Lines | % | |-------|-------|---| | claude-code | 2,741 | 65% | | cursor | 973 | 23% | | human | 164 | 4% | ## 审查上下文 - Intent: security hardening (17 lines, 1 file) - Agent/model: claude-code / claude-sonnet-4-6 - Files read: src/api.rs, src/config.rs - Prompt: add rate limiting to the API - Flags: security ## 优先审查的文件 | File | Lines | Dominant Agent | Intent | Context | |------|-------|----------------|--------|---------| | src/api.rs | 17 | claude-code | security hardening | trace 550e8400 | ```架构概述
**1. `agentdiff configure` —— 一次性全局设置** 将 Python 捕获脚本安装到 `~/.agentdiff/scripts/`，并向选定的 agents 注册 hooks。在交互式终端中，AgentDiff 显示一个 Space/Enter 多选选择器；在脚本中，使用 `--all` 或 `--agents cursor,codex` 以避免提示。Claude MCP server 仅在选中 Claude Code 时注册。 - Claude Code → `~/.claude/settings.json` (PostToolUse) - Cursor → `~/.cursor/hooks.json` (afterFileEdit, afterTabFileEdit) - Codex → `~/.codex/config.toml` (notify) - Gemini → `~/.gemini/settings.json` (BeforeTool, AfterTool) - Windsurf → `~/.codeium/windsurf/hooks.json` (post_write_code) - OpenCode → `~/.config/opencode/plugins/agentdiff.ts` (tool.execute.after) - Copilot → VS Code extension in `~/.vscode/extensions/agentdiff-copilot-0.1.0/` **2. `agentdiff init` —— 每个仓库的设置** 安装 git `pre-commit`、`post-commit` 和 `pre-push` hooks。配置 `refs/agentdiff/*` fetch refspec，以便在 `git fetch` 之后可以看到团队成员的 traces。 **3. 捕获流程** 当 AI agent 进行编辑时，其 hook 会触发并写入一条 JSON 条目到 `标签：AI辅助编程, CVE, Git工具, LNA, Rust, SOC Prime, 代码溯源, 可视化界面, 开发工具, 数字签名, 知识图谱, 网络安全研究, 网络流量审计, 逆向工具, 通知系统