使用 gitai 构建适合 AI 智能体的版本控制服务器

什么是 gitai？

gitai 是一个专为 AI 编程代理设计的开源版本控制系统。它采用以服务器为中心的架构：客户端保持在线，仅获取所需的对象和路径，并将源代码管理操作发送到服务器。

该项目受 Anthropic 公开描述的 Scion 设计启发，但 gitai 是独立实现。它采用 MIT 许可证，与供应商无关，并且不要求服务器调用语言模型。AI 驱动的操作可以使用任意提供商、确定性工具，或完全不使用 AI 提供商。

在底层，gitai 使用普通 Git 仓库，同时将历史查询、落地、变更集跟踪和仓库协调转移到服务器。这种模型适用于包含大量短生命周期任务的工作负载，这些任务需要在共享分支上快速落地变更。

主要功能

• 选择性数据访问：对象服务提供单个对象和稀疏树。graft clone 和 graft sparse 命令只物化请求的路径。
• 服务器端历史记录：责任追踪、路径历史、祖先关系和代码搜索均在服务器上运行，并作为派生数据进行记忆化。
• 并发落地：UserLand 将变更变基到当前分支顶端，并使用比较并交换更新，而不是传统的合并队列。并发落地可以批量合并为一次引用更新。
• 冲突解决：发生冲突的落地操作可以通过版本化、与供应商无关的协议使用指定的解析器。
• 变更集日志：已接受的引用更新会在有序日志中记录其操作和执行者，客户端可以列出或监听该日志。
• 可扩展存储：SQLite 或 PostgreSQL 用于存储变更集、引用、评审和预写日志，而内容寻址的数据包可以存放在文件存储、S3、GCS 或 Azure 中。
• 代理控制：每个代理的令牌、RPC 允许列表和分支策略决定代理可以执行哪些操作。
• 验证和监控：graft-verify 可以测试顶端提交、二分定位故障，并回滚导致问题的变更。名为 superfans 的监控代理会跟踪变更集流，并可通过 Slack 报告。
• 严格缓存：graft-cache 可以在守护进程和区域层级缓存不可变对象，同时验证每个对象。

架构如何工作

代理、CI 作业和稀疏工作区通过 Graft CLI 或 Go SDK，经由 gRPC 与 gitai 服务器通信。可选的 graft-cache 守护进程位于服务器前端，用于提供额外的缓存层。

服务器负责落地、对象访问、变更集、派生数据、搜索和评审。其写入路径会将一个变更集与每个引用的比较并交换操作结合起来。数据库存储变更集预写日志、引用、变更日志和评审。对象存储则保存内容寻址的数据包。

服务器节点被设计为可重建的无状态缓存。随着部署规模扩大，可以添加更多节点。本地 Git 仓库仍作为缓存可用，任何节点都可以重建这些缓存。

如需了解更多详情，请阅读项目的架构文档和存储文档。

安装和构建 gitai

1. 安装前置依赖

gitai 目前需要 Linux 或 macOS、Go 1.26、C 工具链、Meson 和 Ninja。构建过程会编译内置版本的 Git，因此请在开始前确保所需的本机构建工具已准备就绪。

2. 克隆仓库

git clone https://github.com/feder-cr/git-ai.git
cd git-ai

3. 构建二进制文件

运行 Make 目标以构建服务器、CLI 和辅助工具：

make build

生成的二进制文件位于 _build/bin。要查看 CLI 及其可用命令，请运行：

./_build/bin/graft

运行快速入门

仓库包含一个示例，可以启动临时 gitai 环境，其中包括服务器、缓存守护进程、两个代理和一个落地操作：

examples/graft/quickstart.sh

这是无需准备永久数据库、对象存储或部署环境即可了解核心工作流的最快方式。由于该示例使用临时目录，因此最适合学习和实验。

运行自己的服务器

1. 从示例配置开始

使用 examples/graft/config.toml 作为自定义服务器配置的起点。可以使用构建好的二进制文件启动服务器：

_build/bin/gitaly serve config.toml

在源代码树中，服务器端扩展称为 Graft。你会在 [graft] 配置部分、graft CLI、internal/graft 包以及 Graft 文档中看到这个名称。

2. 添加数据库和对象存储

如果要将仓库状态存储在数据库和对象存储中，请在配置中添加 [graft.storage] 部分。文档规定的迁移流程是先以 shadow 模式启动，导入仓库，然后切换到 authoritative 模式。

请参阅存储指南，了解确切的配置和迁移详情。支持的存储模型使用 SQLite 或 PostgreSQL 存储协调数据，并使用文件、S3、GCS 或 Azure 存储内容寻址的数据包。

处理代理变更

在传统的 Git 工作流中，每个工作者都可以克隆一个仓库，在本地开发，然后推送到共享分支。gitai 则允许代理保持与服务器的连接，并仅请求所需的数据。

代理可以使用稀疏工作区来限制实际生成的路径。相关命令包括：

• graft clone：生成仓库的选定视图。
• graft sparse：仅请求或调整任务所需的路径。

代理准备好贡献代码时，UserLand 会将更改变基到当前最新提交，并尝试执行比较并交换更新。如果多个代理在同一分支上并发提交更改，gitai 可以将这些操作批量合并为一次引用更新，而不必让每个代理分别经过合并队列。

如果提交过程产生冲突，请根据冲突解决文档配置解析器。解析器可以基于 LLM 提供商、确定性工具，或完全不使用外部 AI 提供商。

探索变更集、审查与验证

变更集历史

每次接受的引用更新都会成为变更集日志中的一条记录。记录包含操作和执行者，为客户端提供有序记录，客户端可以列出这些记录或实时监视它们。此流还可以驱动监控代理，以跟踪与特定组件相关的更改。

审查与策略

gitai 提供适合代理使用的审查功能，以及基于语义的批准规则。例如，仅包含评论的更改所需的批准数可以少于逻辑更改。代理安全控制还包括每个代理的令牌、RPC 允许列表和分支策略。

在向自动化用户开放服务器之前，请阅读审查文档和代理安全文档。

提交后的验证

graft-verify 工作流会在更改提交后测试分支最新提交。如果测试失败，它可以对更改进行二分查找，并撤销引入该失败的更改。这支持持续集成的工作流，使系统能够识别导致最新提交损坏的具体更改。

有关支持的工作流和配置，请参阅验证指南。

高级部署提示

• 有目的地使用缓存：当代理或 CI 任务需要跨守护进程或区域缓存层快速访问不可变对象时，添加 graft-cache。
• 将协调与对象存储分离：使用 SQLite 或 PostgreSQL 存储变更集和引用，并为仓库包配置对象存储后端。
• 通过增加节点进行扩展：服务器节点设计为可重建缓存，因此添加节点不要求每个节点都保存独立的权威状态。
• 阅读提交文档：提交与批处理指南解释了比较并交换工作流及并发更新。
• 查看当前限制：当前版本为 0.1.0，接口可能会在 1.0 之前发生变化；包的垃圾回收等已知缺口记录在 LIMITATIONS.md 中。
• 使用设计文档：PLAN.md 至 PLAN6.md 解释了实现的设计依据和演进过程。

结语

gitai 将以服务器为中心的源代码控制模型应用于由多个并发编码代理共同维护的仓库。其 Graft CLI 和服务器提供稀疏数据访问、服务器端历史记录、比较并交换式提交、冲突解决、变更集日志、审查、验证以及可扩展存储。

先运行 make build 和 examples/graft/quickstart.sh，了解工作流后，再使用已配置的服务器和持久化存储。有关更深入的实现与运维指导，请参阅项目的 Quickstart、配置参考以及架构文档。