当一个 AI 编程 agent 需要同时改动多个代码仓库时它最常出现的症状不是报错而是“自信地乱改”以为字段在 A 仓库定义了就直接在 B 仓库引用把本地未构建的旧版本当成最新代码甚至在错误的分支上提交。问题的根源不是大模型不够聪明而是我们给 agent 准备的“工作台”错了。Orbit 这个项目在 Hacker News 上的标题很短信息量却很大One agent across many repos: real worktrees, no index。翻译过来就是用同一个 agent 横跨多个仓库给它的不是一份拼接出来的假仓库而是真实可用的 git worktree同时不建任何代码索引。这个选择乍看像退步——别的工具都在卷代码索引和向量检索你却说不要索引但仔细看它恰好戳中了多仓库 AI 编程里最容易被忽视的一个事实agent 写代码需要的是确定性不是相似性。本文会沿着“为什么要跨仓库”“worktree 是什么”“不建索引靠什么”这条线展开最后给出一套可以在本地跑通的多仓库工作区搭建方案并讨论生产环境落地时的权限、回滚和验证问题。无论你是正在做 agent 工具开发的人还是想在团队里用 AI 助手处理跨仓重构这篇文章都值得收藏备用。1. 这篇文章真正要解决的问题先说一个具体场景。假设你所在的服务端项目拆成了五个仓库网关用 Go用户服务用 Java订单服务用 Python另外还有一个共享 SDK 仓库、一个 protobuf 协议仓库。现在产品提了一个需求“订单增加一个新的超时时间字段网关要把这个字段透传给前端SDK 要暴露对应的常量。”如果靠人来做这个过程是清晰的先改协议仓再改 SDK再改订单服务再改网关最后联调。但交给 AI agent 做难度一下子被放大了。绝大多数编程 agent 都是以“当前工作目录”为边界来理解项目的。它打开一个仓库时看不到另外四个仓库的存在它要修改的字段定义在协议仓调用方在 SDK消费方在网关。任何一个环节的信息缺失都会导致它写出“看起来合理但编译不过”的代码。这就是多仓库 agent 真正要解决的问题跨仓库的修改闭包change closure。所谓闭包是指完成一个任务所需要修改和验证的所有文件、依赖和构建步骤的总和。单仓库时代闭包通常落在同一棵目录树下agent 只要会读目录和搜索文件就能闭环。多仓库时代闭包横跨多个 git 仓库agent 需要一个能同时看到、能同时构建、能同时提交的真实工作区而不是把几个仓库的历史快照拼在一起。除此之外还有一层问题很多团队为了解决“跨仓”会先引入代码索引系统把符号、调用关系、向量化语义存进数据库再让 agent 基于索引回答。但索引方案在工程上有隐蔽成本——它需要建设、需要同步、需要信任。Orbit 的“no index”正是针对这一点提出来的相反方案。这篇文章会把这几类权衡摊开讲清楚并给出一个不依赖索引也能让 agent 高效工作的完整路径。2. 基础概念worktree、index 与 agent 的工作台模型在继续之前必须先澄清一个非常容易被混淆的词index。Git 里确实有一个“index”中文一般叫暂存区。你执行 git add 之后、git commit 之前文件就到暂存区里这是 git index。而 Orbit 标题里的“no index”显然不是在说不让 agent 用 git add——它否定的是另一类东西代码索引code index也就是 IDE、代码搜索引擎和一部分 AI 编程工具用来加速定位代码的“符号表 向量库”。前者是 git 三区模型的一部分后者是代码分析工具的地图。文章后面提到“不建索引”指的都不是 git 暂存区而是后者。区分这两层含义非常重要否则你会误以为某类工具连 git 基本功能都不支持。接下来是 worktree。git worktree 是一个非常实用、但很多开发者没系统性用过的功能。它允许你在同一个仓库下创建多个工作目录每个目录可以检出不同的分支这些目录共用同一个对象数据库。通俗地说一个仓库可以在磁盘上有多个“分身”每个分身处于不同的分支状态你可以在分身 A 改特性分支在分身 B 修线上 bug互不干扰只需要考虑磁盘上的文件本身。对于人类开发者worktree 是节省切换成本的小技巧。但对于 AI agentworktree 的意义完全不同。agent 没有“人类记忆”它理解项目的唯一方式就是看文件系统读文件、执行命令、看输出。所以文件系统长什么样直接决定了 agent 的能力边界。我们可以把 agent 可以看到、可以操作的那片文件系统称为它的“工作台”。单仓库单目录是一张单人的小桌子跨仓库多 worktree是一间能同时展开多个仓库的办公室。Orbit 选择的工作台形态就是后一种。这里还要引入 agent 的“闭环”概念。agent 完成任务不是靠记住一行行代码而是靠最小化的感知—执行—验证循环感知当前状态执行修改动作构建或测试验证根据结果修正。这个循环要求工作区必须是真实的、可构建的、可回滚的。任何一层是虚拟的、快照式的、拼接式的都会在“验证”环节产生假象agent 就会拿着假验证结果继续往后走直到把错误扩散到多个仓库。3. 为什么“real worktrees”比虚拟合并更可靠既然要跨仓库一个最朴素的想法是把多个仓库的文件拷贝到一个大目录里假装是一个大项目。这种方案确实简单但有两个致命问题。一是丢失了 git 元数据每个文件都不知道自己属于哪个仓库agent 无法在正确的仓库里提交变更无法查看 blame无法切换分支二是路径语义被破坏仓库里的相对引用、模块路径、构建脚本里的相对路径全部失效构建大概率直接挂掉。比拷贝更“高级”一点的做法是做虚拟文件系统合并层比如在内存或 FUSE 层面把多个仓库映射成一个合成目录。这个方案的诱惑在于“对 agent 透明”而坑也恰恰在这里。编译器不认合成目录语言服务器不认合成目录测试框架不认合成目录。你确实给 agent 造出了一个“看起来完整”的项目但一旦 agent 要真正执行构建和测试它就会撞上合成层与真实工具链之间的裂缝。更危险的是某些合成层为了让 agent“看起来顺利”会返回假路径或映射后的路径agent 拿到错误信息却找不到对应文件直接在幻觉里越陷越深。real worktrees 的方案没有这些中间层。每个仓库在磁盘上就是一个普通目录目录里就是一个完整的、合法的 git 仓库。agent 在这个目录里跑 go build、mvn test、python -m pytest跟人类开发者在一模一样的环境里执行没有任何虚拟层需要维护。它的可靠性来自一个朴素原则不给 agent 造一个简化的世界直接让它操作真实世界。real worktrees 还有几个工程上的附带优势。第一隔离与并行你可以在同一个仓库上同时开三个 worktree分别对应特性开发、bug 修复和实验性改动agent 不用担心把一个分支改到一半又切走。第二对象共享多个 worktree 共享同一份 git 对象数据库不会因为多开几个目录就让磁盘翻倍这对动辄几个 GB 的大仓库很关键。第三回滚能力每个 worktree 都有完整的分支和提交历史agent 改坏了直接 git reset 或切一个新分支重来不需要重新拉代码。类比一下索引方案像是在给 agent 发一张精度不错但可能过期的地图虚拟合并像是在给 agent 发一张看起来很美的沙盘模型而 real worktrees 是直接把 agent 送到真实街区里让它自己走路、自己看路牌。对写代码这种对确定性要求极高的工作真实环境带来的收益远超“看起来方便”的虚拟层。4. 为什么“no index”值得认真对待先说 index 方案在 AI 编程工具里为什么流行。代码索引本质上解决的是“找得准”的问题扫描全部代码抽取出类、函数、变量、调用关系再做符号解析或向量化存储agent 提问时通过搜索快速定位相关代码从而弥补大模型上下文窗口有限的短板。这个概念很自然Sourcegraph、OpenGrok、各类 IDE 已经把这条路走通了很多 AI 编程工具也都默认接入了某种索引。但索引的工程成本被严重低估了。一是建设成本全量扫描、解析、写入数据库仓库越大越费时增量更新又要处理分支、历史、未提交改动。二是同步延迟代码是高频变化的索引再快也永远落后于磁盘上正在编辑的代码。三是查询失真索引只记录它建好的内容新创建的文件、未提交的改动、临时排查用的脚本索引里都没有agent 基于索引回答问题时容易把“索引里查不到”误判成“代码里不存在”。四是信任问题索引错误比没有索引更糟因为 agent 会带着错误信息去写代码最后连开发者也难以判断哪些错误来自模型、哪些来自索引。Orbit 的“no index”本质是把信息源从“间接的索引”切换回“直接的文件系统”。在 real worktrees 构成的工作区里代码的真相就是磁盘上的文件。agent 要找符号就用 ripgrep 或 git grep 精确搜索搜到的结果永远是当前状态要理解调用关系就沿着 import 链和函数定义一级一级读文件要确认改动影响面就编译一次、跑一遍测试。整个过程不依赖任何中间存储因此不存在同步问题也不存在“索引说有一套、磁盘上是另一套”的错位。这带来的另一个好处是省成本。索引通常需要独立的存储、计算和刷新管道跨多个仓库时还要处理权限和租户问题。对于几十个仓库的中型团队维护一套索引基础设施的隐性开销可能比 agent 本身还要高。不建索引意味着 agent 的基础设施可以极其轻量一个能运行 agent 的运行时、一组仓库的 worktree、一个沙箱权限层就够了。当然“no index”不是万能解。在超大单体仓库、需要跨项目语义检索、或者希望给整个代码库做安全审计的场景里索引的累计收益仍然很难替代。但对大多数跨仓写代码的场景agent 需要的不是“找到相似代码”而是“找到确切符号并确认当前状态”。在这个维度上文件系统 精确检索是目前性价比最高、也最诚实的信息来源。所谓诚实是指它不会给 agent 一个关于代码现状的虚假承诺——这一点恰恰是写代码任务里最稀缺的品质。5. 环境准备与前置条件在动手搭建
