企业官网建设流程全解析

如何在 git-ai 中开发 AI 代码追踪功能：Rust 新手完整贡献指南（附 TDD 工作流）

【免费下载链接】git-aiA Git extension for tracking the AI-generated code in your repos项目地址: https://gitcode.com/gh_mirrors/git/git-ai

git-ai是一个开源的 Git 扩展，用于追踪仓库中每一行 AI 生成代码的来源——它会把 AI 代码关联到生成它的 Agent、模型和 Prompt，让你通过git ai blame看到每一行代码是"人写的"还是"AI 写的"。本文将带你以贡献者身份参与这个 Rust 项目：从环境搭建、理解核心架构，到掌握项目强制要求的TDD（测试驱动开发）工作流，最后顺利提交 PR。

一、开始之前：5 分钟搭好开发环境 🛠️

git-ai 使用Rust 2024 版（要求 Rust 1.93.0+）编写，并用 Taskfile 统一管理构建、测试和格式化命令。

1. 安装两个必备工具

• Rust 编译器（rustup 安装）
• Taskfile CLI（task命令，负责项目的所有开发动作）

2. 克隆仓库并构建

git clone https://gitcode.com/gh_mirrors/git/git-ai cd git-ai task build # 编译，确认项目能构建通过

3. 安装本地开发版（关键一步）⚠️

git-ai 的特殊之处在于它会代理 git 命令，所以普通cargo run是测不出效果的。项目提供了task dev命令，它会：

• 编译 debug 版并安装到~/.git-ai/bin/git-ai（覆盖系统已安装的版本）
• 自动执行git-ai install并重启后台守护进程（daemon）

task dev

官方 CONTRIBUTING.md 特别提醒：本地测试只能使用task dev，其他运行方式都会互相干扰、导致测试结果失真。

二、理解核心架构：checkpoint → working log → authorship note

在写任何代码前，先理解 git-ai 追踪 AI 代码的数据流。这是整个项目的心脏，所有功能开发都围绕它展开：

checkpoint 分三种类型，测试时可用 mock 命令模拟：

• human（未追踪）：AI Agent 编辑前的"前快照"，测试时用git-ai checkpoint human调用
• known_human（真实人类）：由 IDE 扩展在检测到人手输代码时调用，测试用git-ai checkpoint mock_known_human
• ai_agent（AI 检查点）：关联特定 Agent 和会话，测试用git-ai checkpoint mock_ai

💡 详细架构说明见 AGENTS.md 的 "Core data flow" 章节。

三、项目铁律：6 条不可触碰的硬性规则 🚨

AGENTS.md 开篇就列出了"违反任何一条都会导致 PR 直接被拒"的规则，贡献前务必熟读：

1. 一切基于 trace2 驱动——不包装 git 二进制，所有处理必须完全异步
2. 关键摄取路径禁止新增工作——daemon 的 trace2 摄取路径对延迟极度敏感，毫秒级开销都不能加
3. 禁止非恒定时间的 git 操作——不能"对每个提交/文件/ref 各调用一次 git"
4. 无限制的 git 进程调用 = 自动拒 PR
5. 复用已有代码——大项目里几乎任何操作都有现成的、已测试的 helper
6. 严格执行 TDD——没有高质量TestRepo测试的 PR 立即被拒

其中第 6 条是本文的重点，下面展开讲。

四、TDD 工作流详解：用 TestRepo 编写集成测试

git-ai 的测试基础设施位于 tests/integration/repos/，三大核心文件：

1. 最小测试模式（推荐先跑一遍）

#[test] fn test_using_test_repo() { let repo = TestRepo::new(); let mut file = repo.filename("test.txt"); file.set_contents(lines!["Line 1", "AI line".ai()]); repo.stage_all_and_commit("Initial commit").unwrap(); file.assert_lines_and_blame(lines!["Line 1".human(), "AI line".ai()]); }

这段测试完整走了一遍真实流程：set_contents内部会模拟 AI Agent 的前后 checkpoint，assert_lines_and_blame则同时校验文件内容和 AI/人类归因——这正是 git-ai 测试"测试即归因验证"的精髓。

2. TDD 循环

1. 先写失败的测试：用TestRepo描述你期望的归因行为
2. 运行看它失败：task test TEST_FILTER=你的测试名
3. 实现功能，让测试通过
4. 每次提交后都断言行级归因（这是 AGENTS.md 强调的"CRUCIAL"要求）

⚠️ 注意：如果你测试的是 checkpoint 或归因的内部细节，不要用file.set_contents（它的 checkpoint 流程过于简化），而应该用fs::write手写文件，再显式调用mock_known_human/human/mock_ai三种 checkpoint 模拟真实的前后快照流程。参考 AGENTS.md 中的完整示例。

3. 测试常用命令

task test # 跑全部测试 task test TEST_FILTER=foo # 只跑名字含 foo 的测试 task test NO_CAPTURE=true # 显示测试输出 task lint # clippy 检查（警告视为错误） task fmt # rustfmt 格式化 cargo insta review # 交互式审查快照测试变更

测试隔离由框架自动处理：每个TestRepo拥有随机临时目录和独立的GIT_AI_TEST_DB_PATH，所以你的测试不会污染其他测试。

五、提交 PR 的标准流程 📤

1. 开发前：先在 issue 区确认没有重复需求；新功能或架构改动建议先与维护者沟通，避免方向跑偏
2. 创建分支：git checkout -b my-feature-branch，写清晰、有描述性的提交信息
3. 提交前必跑：task lint和task fmt，CI 中格式不合规会直接失败
4. PR 描述中引用 issue（如Fixes #123）
5. 优先盯 Ubuntu CI（约 15 分钟出结果）：失败就快速迭代直到全绿
6. 处理自动 review 反馈：PR review bot 会留下反馈，需要逐条评估——该修就修，不该修就评论说明理由
7. Ubuntu 任务全绿且反馈处理完后，Mac/Windows 的慢速 CI（最长 3.5 小时）可以不必死等，除非你在修特定系统的 bug

代码风格上，项目强调"为人类评审而优化"：清晰的命名、最小且简单的改动、DRY 原则——没有代码能跳过人类评审被合并。

六、常见坑位：踩过的都是前人留下的 🕳️

七、延伸阅读资料 📚

• CONTRIBUTING.md — 官方贡献指南
• AGENTS.md — 硬性规则、架构说明与测试基础设施详解
• Taskfile.yml — 所有task命令的定义
• specs/git_ai_standard_v3.0.0.md — git-ai 制定的 AI 代码追踪开放标准
• docs/rewrite-ops-spec.md — rebase/reset 等改写操作的归因迁移规范
• docs/daemon-trace2-ingestion-spec.md — 守护进程 trace2 事件摄取规范
• src/mdm/agents/ — 已支持的 16 个 Agent 的 MDM 集成（想接入新 Agent 就从这里学起）
• tests/integration/repos/test_repo.rs — TestRepo 测试框架源码

动手吧！建议新手从"为某个 Agent 补一个 checkpoint 测试"或"修复一个小归因 bug"这类小 PR 开始，跑通task dev→ TDD 写测试 →task lint→ PR 全流程，你就正式成为 git-ai 的贡献者了 🎉

【免费下载链接】git-aiA Git extension for tracking the AI-generated code in your repos项目地址: https://gitcode.com/gh_mirrors/git/git-ai