git-ai 项目详解

项目概述

git-ai 是一个开源的 Git 扩展（Rust 语言开发），用于追踪代码仓库中 AI 生成的代码，将每行代码与其对应的 AI Agent、模型和会话记录关联起来。

GitHub: https://github.com/git-ai-project/git-ai
官网: https://usegitai.com
Star : 1,438 | Fork: 113
许可证: Apache 2.0

核心价值

一旦安装，它自动将每行 AI 生成的代码链接到生成它的 Agent、模型和会话记录------让你永远不会丢失代码背后的意图、需求和架构决策。

核心功能

1. AI Blame

git-ai blame 是 git blame 的替代品，显示每行代码的 AI 生成者（Agent、模型、Session）。

bash 复制代码

git-ai blame /src/log_fmt/authorship_log.rs

bash 复制代码

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,
cb832b7 (Aidan Cunniffe      2025-12-13 08:16:29 -0500  135)     spec: DiffSpec,
cb832b7 (Aidan Cunniffe      2025-12-13 08:16:29 -0500  136)     format: DiffFormat,
cb832b7 (Aidan Cunniffe      2025-12-13 08:16:29 -0500  137) ) -> Result<String, GitAiError> {
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 {

2. Commit 时自动标注

在 git commit 输出中显示 human/AI 代码比例：

复制代码

[hooks-doctor 0afe44b2] wsl compat check
 2 files changed, 81 insertions(+), 3 deletions(-)
you  ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ai
     6%             mixed   2%             92%

3. 跨 Agent 可观测性

通过 git-ai stats 统计不同 Agent 的代码贡献量：

bash 复制代码

git-ai stats --json

json 复制代码

{
  "human_additions": 28,
  "mixed_additions": 5,
  "ai_additions": 76,
  "ai_accepted": 47,
  "total_ai_additions": 120,
  "total_ai_deletions": 34,
  "time_waiting_for_ai": 240,
  "tool_model_breakdown": {
    "claude_code/claude-sonnet-4-5-20250929": {
      "ai_additions": 76,
      "ai_accepted": 47,
      "total_ai_additions": 120,
      "total_ai_deletions": 34
    }
  }
}

统计字段详解

字段	含义	示例
`human_additions`	纯人类贡献的代码行数	28
`mixed_additions`	AI生成但被人修改过的行数	5
`ai_additions`	AI贡献的总行数 (mixed + accepted)	76
`ai_accepted`	AI生成且未被修改的"接受"行数	47
`total_ai_additions`	AI生成的总行数	120
`total_ai_deletions`	AI删除的总行数	34
`time_waiting_for_ai`	等待AI响应的累计时间（秒）	240

什么是 mixed_additions？

mixed_additions = AI 生成的代码被人修改过的那部分行数。

举例说明：

复制代码

1. AI 生成了一段代码 (第 10-15 行)
2. 人 review 后修改了第 12 行
3. 最终这 6 行 commit 进代码库

分类	行数	说明
ai_accepted	5	AI写的，人没改，直接用
mixed_additions	1	AI写的，但被人修改了

为什么要区分？

AI 写的代码被人修改了，说明人花了时间 review 和改进。这部分不完全算"AI写的代码"，也不完全算"人写的代码"，所以叫 mixed（混合）。

终端展示效果：

复制代码

you  ████████▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ai
     ████ = pure human (人自己写的)
     ▒▒▒ = mixed (AI写但人改过)
     ░░░ = ai accepted (AI写、人没动)

4. `/ask` 技能

可以直接向生成该代码的 Agent 提问，理解代码背后的意图：

复制代码

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

支持的 Agent

Claude Code、Codex、Cursor、Windsurf、Copilot、Continue、Gemini、Junie、Rovo Dev、Amp 等主流 AI 编程工具。

工作原理

核心源码结构

复制代码

src/
├── mdm/
│   ├── agents/
│   │   ├── claude_code.rs    ← Claude Code hook 安装器
│   │   ├── cursor.rs         ← Cursor hook 安装器
│   │   ├── windsurf.rs       ← Windsurf hook 安装器
│   │   └── ...               ← 其他 Agent 支持
│   └── hook_installer.rs     ← Hook 安装抽象接口 (HookInstaller trait)
├── commands/
│   ├── checkpoint.rs          ← Checkpoint 核心逻辑 (2000+ 行)
│   ├── git_ai_handlers.rs    ← CLI 命令分发
│   └── checkpoint_agent/
│       ├── agent_v1_preset.rs ← Hook input JSON 解析
│       └── agent_presets.rs  ← AgentRunResult 定义
└── authorship/
    ├── attribution_tracker.rs ← 行级别归属追踪
    ├── working_log.rs         ← Checkpoint 持久化
    └── authorship_log.rs      ← Authorship Log 格式

架构总览

查询层
存储层
git-ai 核心模块
Hook 系统
IDE / Agent 环境
git-ai checkpoint

--hook-input stdin
git-ai checkpoint

--hook-input stdin
git commit
👤 用户
🤖 Claude Code
Cursor
Windsurf
🪝 PreToolUse

写前
🪝 PostToolUse

写后
📥 解析 Hook Input
🧮 AttributionTracker

行归属计算
📦 Checkpoint 生成
💾 WorkingLog 持久化
📁 .git/ai/

working_log.json
📌 Git Note

refs/notes/ai
🔍 git-ai blame

行级别追溯
📊 git-ai stats

统计信息
📄 git-ai show

查看 Authorship

执行时序

📌 Git Note 📝 Git Commit 💾 文件系统 ⚙️ git-ai core 🪝 git-ai hook 🤖 Claude Code 👤 用户 📌 Git Note 📝 Git Commit 💾 文件系统 ⚙️ git-ai core 🪝 git-ai hook 🤖 Claude Code 👤 用户阶段 1: 编辑触发阶段 2: Commit 提交阶段 3: 查询追溯调用 Edit/Write PreToolUse Hook git-ai checkpoint --hook-input stdin 解析 JSON 记录编辑意图执行文件修改 PostToolUse Hook git-ai checkpoint --hook-input stdin 计算 diff attribution 写入 working_log.json git commit 创建 commit post-commit hook 处理 checkpoints 生成 Authorship Log git notes add refs/notes/ai git-ai blame file.rs 读取 note 每行 AI 作者 git-ai stats human/AI/mixed 比例

1. Hook 安装机制

每种 Agent 都有自己的 HookInstaller 实现。git-ai 通过修改 Agent 的配置文件来注册 hooks。

以 Claude Code 为例，安装到 ~/.claude/settings.json：

json 复制代码

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

关键设计：

HookInstaller trait ：抽象接口，每种 Agent 实现 check_hooks()、install_hooks()、uninstall_hooks()
matcher ：只对 Write|Edit|MultiEdit 工具触发，避免打扰其他操作
--hook-input stdin：从标准输入读取 Agent 传入的 JSON 数据

2. Hook 触发流程

复制代码

Claude Code 执行 Write/Edit/MultiEdit 操作
    ↓
触发 PreToolUse hook (写前)
    → git-ai checkpoint claude --hook-input stdin
    ↓
Claude Code 执行实际文件修改
    ↓
触发 PostToolUse hook (写后)
    → git-ai checkpoint claude --hook-input stdin

命令拆解：

部分	含义
`git-ai`	主程序
`checkpoint`	子命令，记录编辑检查点
`claude`	指定 Agent 类型
`--hook-input stdin`	从 stdin 读取 Hook 传入的 JSON 数据

Hook 配置在 ~/.claude/settings.json 中，指定 command: "git-ai checkpoint claude --hook-input stdin"。当触发时，Claude Code 通过管道将 JSON 数据传给 stdin，git-ai 解析后写入 .git/ai/working_log.json。

3. Hook Input 格式

Agent 通过 stdin 传入 JSON，git-ai 用 agent_v1_preset.rs 解析：

json 复制代码

// Human-initiated 模式（人触发的编辑，即claude -i 交互模式中手动编辑文件）
// 人在 Claude Code 里手动调用 Write/Edit/MultiEdit 工具
{
  "type": "human",
  "repo_working_dir": "/path/to/repo",
  "will_edit_filepaths": ["src/main.rs"],
  "dirty_files": {"src/main.rs": "file content..."}
}

// AI-initiated 模式（AI 触发的编辑） 
// AI Agent 内部决策调用的编辑
{
  "type": "ai_agent",
  "repo_working_dir": "/path/to/repo",
  "edited_filepaths": ["src/main.rs"],
  "transcript": {...},
  "agent_name": "claude_code",
  "model": "claude-sonnet-4-5",
  "conversation_id": "session-xxx",
  "dirty_files": {"src/main.rs": "new content..."}
}

注意：type: "human" 不等于"人在 IDE 里直接敲代码"，而是指"人在 Claude Code 里手动调用了 Edit/Write 工具"。直接在 IDE 编辑器里敲的代码不会触发 git-ai hooks。

4. Checkpoint 处理（checkpoint.rs 核心逻辑）

run() 函数接收 hook input 后：

复制代码

接收 hook input (JSON)
    ↓
resolve_live_checkpoint_execution() 确定修改了哪些文件
    ↓
对每个修改的文件：
    ├─ 读取当前内容 (dirty_files 或磁盘)
    ├─ 读取前一个 checkpoint 的 attribution
    ├─ 用 imara_diff 计算差异
    └─ AttributionTracker.attribute_unattributed_ranges() 计算行归属
    ↓
create Checkpoint 对象
    ├─ kind: AI / Human
    ├─ entries: 每个文件的 [Attribution]
    ├─ line_stats: 添加/删除行数
    └─ agent_id: tool + model + conversation_id
    ↓
写入 .git/ai/working_log.json

关键组件：

AttributionTracker：计算行级别的作者归属，处理重叠修改
imara_diff：Rust 实现的 diff 算法，与 git 内部算法兼容
WorkingLog ：存储在 .git/ai/，记录所有 checkpoint

5. Authorship Log 生成（Commit 时）

提交时，git-ai 处理所有 checkpoints，生成 Authorship Log，将行范围映射到 Agent Session。

6. Git Note 存储

git-ai 使用 Git Notes （refs/notes/ai 命名空间）存储 AI 作者信息，不修改 commit 历史。

Git Notes 简介

Git Notes 是 Git 的一个功能，允许在不修改 commit 的情况下为 commit 添加额外的元数据信息。

特性	说明
不修改 commit	Notes 存储在独立的引用空间，不影响原有 commit 历史
独立引用	存储在 `refs/notes/` 命名空间
可共享	可以推送到远程，和其他 Git 数据一起同步
灵活	每个 commit 可以有 0 个或 1 个 note

bash 复制代码

# 添加 note
git notes add -m "message" <commit-sha>

# 查看 note
git notes show <commit-sha>

# 列出所有 notes 引用
git notes list

4. Authorship Log 格式

Git Note 存储的 Authorship Log 格式示例：

复制代码

hooks/post_clone_hook.rs
  a1b2c3d4e5f6a7b8 6-8
  c9d0e1f2a3b4c5d6 16,21,25
---
{
  "schema_version": "authorship/3.0.0",
  "base_commit_sha": "f4a8b2c...",
  "prompts": {
    "a1b2c3d4e5f6a7b8": {
      "agent_id": { "tool": "copilot", "model": "codex-5.2" },
      "human_author": "Alice Person <alice@example.com>",
      "messages_url": "https://your-prompt-store.dev/cas/a1b2c3d4..."
    },
    "c9d0e1f2a3b4c5d6": {
      "agent_id": { "tool": "cursor", "model": "sonnet-4.5" },
      "human_author": "Jeff Coder <jeff@example.com>",
      "messages_url": "https://your-prompt-store.dev/cas/c9d0e1f2..."
    }
  }
}

格式规范定义在 Git AI Standard v3.0.0。

7. 历史变更追踪

git-ai 在以下操作时透明地重写 Authorship Log，保持 attribution 不丢失：

Rebases
Merges
Squashes
Cherry-picks
Stash/pops
Commit amends

设计哲学

原则	说明
无需改工作流	安装后即用，无需 per-repo 配置
不"检测"AI代码	Agent 主动报告写的行，不靠猜测
Local-first	100% 离线可用，无需登录
Transcript 不进 Git	敏感信息留在本地或云端 prompt store
Git 原生	利用 Git Notes，不污染 commit 历史

安装方式

Mac / Linux / Windows (WSL)

bash 复制代码

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

Windows (非 WSL)

powershell 复制代码

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

开放标准

git-ai 遵循 Git AI Standard v3.0.0，这是一个开放标准，其他项目也可以实现兼容的 AI 代码追踪方案。

标准核心要点

命名空间 : 使用 refs/notes/ai（不是默认的 refs/notes/commits）
Schema Version : authorship/3.0.0
Session Hash : 使用 SHA-256 of {tool}:{conversation_id} 的前 16 位十六进制字符
Line Range: 1-indexed，逗号分隔的单个行号和范围

本文档由 AI 生成，最后更新：2026-03-30

git-ai 项目详解