最近这半年我这边跑 AI 编程 Agent 的频率越来越高。Codex CLI、Claude Code、Gemini CLI 换着用单 Agent 干活确实能省不少事但我有一次尝试同时挂三个 Agent 处理同一个仓库的不同需求结果不到一个小时仓库就乱了两个 Agent 改到同一个文件第三个因为共享工作目录切分支把未提交的改动全搞丢了最后我根本说不清哪个工作区对应哪个任务整个下午都在收拾烂摊子。被这个场景反复折磨之后我抽空写了个小工具 Worktrunk——一个面向并行 AI Agent 工作流的 Git Worktree 管理 CLI。它的核心思路很简单让每个 Agent 在真正隔离的独立目录里干活同时把任务、分支、工作区的关系用命令管起来而不是靠人脑硬记。这篇文章就聊聊我为什么会做这个东西、它是怎么设计的以及在真实项目里跑并行 Agent 的完整过程和踩坑经验。1. 并行 Agent 的工作区失控增量收益变成增量混乱1.1 我遇到的三种典型翻车现场先说我最初“裸奔”并行跑 Agent 的失败经历。当时我用的是一个普通的 Python 微服务仓库任务分别是重构日志模块、新增一个 REST API 端点、修复一个内存泄漏 bug。我的做法特别朴素在同一个仓库目录里先让 Agent A 改日志模块等它跑起来之后又让 Agent B 直接开始加 APIAgent C 也顺手进来修 bug。第一个翻车现象是文件互相覆盖。Agent A 和 Agent B 都需要修改service.py这个文件A 在文件头部加了日志配置B 在文件中部加了新路由两个 Agent 都基于同一个原始版本操作后保存的一方直接把另一方改动覆盖了。这种冲突在 Git 层面根本看不出来因为文件还是那个文件但内容已经悄悄丢了。第二个翻车现象是分支切换灾难。为了让三个任务互不影响我一开始想用三个分支但因为没有独立工作目录切分支的时候只能把当前目录里所有未提交的改动带来带去。Agent 自己创建的文件、改了一半的代码全搅在一起git status输出乱七八糟我只能逐个文件手动挑拣。第三个翻车现象是上下文污染。Agent 读取代码时看到的不再是 main 分支的干净基线而是其他 Agent 改到一半的中间状态。它据此做出来的“正确修改”实际上是在错误的前提上打补丁。这比文件覆盖更隐蔽因为代码能跑但逻辑已经歪了。1.2 并行 Agent 工作流的本质需求经历过这几轮翻车之后我梳理了一下并行 Agent 场景真正的需求画出来其实特别清晰隔离维度为什么需要做不到的后果目录隔离每个 Agent 独立读写文件互不干扰文件覆盖、中间状态互相污染分支隔离每个任务有独立的 Git 历史提交混乱、无法独立审查回滚上下文隔离Agent 看到的是干净的基线代码基于错误的代码做“正确”的修改构建产物隔离测试、编译缓存不串台测试结果失真、缓存互相覆盖生命周期隔离任务完成可整体回收半成品文件堆积、工作区垃圾化所以并行 Agent 的正确姿势其实是一个等式并行度 隔离度 - 调度成本。隔离做得越好并行收益越高但调度越麻烦人就越不愿意用最后还是会退回串行。Worktrunk 这个工具就是为了把“调度成本”压到最低让隔离变得随时可用。1.3 Agent 并行和多人并行难点其实不一样可能有人会说这不就是多人协作嘛用 Git 分支不就够了但 Agent 并行和团队多人并行有个本质区别人之间能沟通Agent 只能通过文件系统状态“感知”环境。人发现自己要改的文件被同事改了会主动拉一下最新代码Agent 不会它只负责按 prompt 执行遇到目录里一堆奇怪的中间文件它会照单全收。另外AI 编程工具的行为模式和人不同Codex CLI、Claude Code 这类工具会生成大量临时文件、测试文件、注释动不动就自动 commit一个任务能留下几十次提交。如果没有独立工作区这些噪音会直接淹没主干历史。所以 Agent 场景需要的不是普通的多人分支策略而是一个按需创建、用完即焚的临时工作区机制。这正好是 Git Worktree 的强项。2. Git worktree 是天然候选但裸命令离“可编排”还差很远2.1 Worktree 原理一个仓库多个工作区Git Worktree 是 Git 2.5 引入的功能它的设计目标就是一个仓库同时存在多个工作目录。原理不复杂仓库的.git目录里存的是对象数据库、引用和配置而git worktree add会在另一个路径重新 checkout 出一份工作文件并生成一个独立的 HEAD、index 和 per-worktree 的引用。比如我在~/projects/myapp下执行git worktree add ../myapp-log-refactor -b refactor/logging就会在../myapp-log-refactor目录生成一份基于新分支的完整工作区。两个目录共享同一个.git对象库你不需要把远程仓库再 clone 一遍磁盘开销远小于复制仓库。我实测下来一个 200MB 的仓库创建一份新 worktree 后额外磁盘占用通常只有几 MB 到几十 MB取决于工作文件多大因为工作文件是真实副本。2.2 裸用 git worktree 命令的问题清单原理很顺但真要用命令行管理几个并行的 Agent worktree问题立刻冒出来。第一是命令繁琐。每个任务都要先git worktree add再记下路径然后去创建一个分支。任务一多命令越堆越长而且容易搞混哪个 worktree 对应哪个分支、哪个任务。第二是没有业务语义。git worktree list输出的只有路径、分支、commit它不知道这个 worktree 是给哪个任务用的、运行的是哪个 Agent、什么时候创建的。我需要的是“这张工作区清单”和“我的任务清单”能对得上。第三是清理有隐患。git worktree remove经常失败提示 worktree 包含修改或未跟踪文件。而 Agent 跑完的任务里往往到处是测试文件、构建产物你必须先手动收拾干净才能 remove非常破坏节奏。第四是git worktree prune不及时.git/worktrees下会堆积一堆失效元数据。长期用下来仓库内部会越来越脏。2.3 为什么 IDE 和常规 Git 工具没有解决这个问题我也尝试过用 IDE 的多窗口方案VS Code 对 worktree 有支持可以先打开主仓库再用 Remote 或 Workspace 方式打开多个 worktree 目录。问题在于 IDE 是给“人”用的你要手工一个个打开窗口、记住哪个窗口对应哪个任务。而 Agent 是无头的它根本不看 IDE它需要的是一套可以脚本化、可以程序调用的接口。常规 Git 图形工具和 Git alias 也只能解决“少打字”的问题管理不了任务状态、Agent 信息、生命周期。所以我的判断是这个场景需要一层薄薄的编排层长在 Git worktree 之上面向 Agent 而不是面向人。Worktrunk 就是把这一层补上。3. Worktrunk 的设计取舍把任务、分支、工作区绑成一条记录3.1 一份 manifest 搞定状态追踪Worktrunk 的核心模型特别朴素每次给 Agent 分配一个任务时它会做三件事——创建一个新分支、在一个独立目录创建 worktree、然后写一条任务记录。这条记录我放在仓库根目录的.worktrunk/manifest.json里内容包括{ tasks: [ { id: task-3f2a9c, name: refactor-logging, branch: refactor/logging, path: /home/user/projects/myapp/log-refactor, agent: codex, status: active, created_at: 2025-06-10T10:24:00Z, base: main } ] }为什么把状态存成文件而不是塞进数据库因为 manifest 文件本身可以被 Git 忽略、也可以被脚本一行jq读取最重要的是它可审计——任何时候打开这个文件就知道当前仓库有哪些 Agent 工作区、各自处于什么状态。这比用记忆或者终端历史可靠得多。3.2 命令设计让 Agent 和人用同一套工具Worktrunk 的命令我设计得尽量少核心就这几个命令作用关键参数wt init初始化仓库的 worktree 管理元数据--root指定主仓库路径wt spawn创建一个隔离任务工作区--name任务名、--agentAgent 类型、--base基线分支wt list列出所有任务工作区及状态--json输出机器可读格式wt switch在任务工作区之间切换当前上下文--task任务 IDwt reaper标记任务完成清理工作区--task、--forcewt merge把任务分支合回基线分支--task、--delete-branchwt spawn是最核心的命令。它一次完成创建分支、创建 worktree、写 manifest、然后输出一个可以直接交给 Agent 的工作目录路径。我不会让你先git worktree add再手动记路径那么干又退回裸命令了。3.3 状态流转从出生到回收每个任务工作区的生命周期有五个状态spawned刚创建、activeAgent 正在跑、reviewAgent 完成等人审查、merged已合回基线、pruned已清理。流转规则很直白spawn创建任务后进入spawnedAgent 第一次在该目录里执行命令Worktrunk 检测到工作区有改动就把状态推进到activeAgent 主动调用wt done或者你手动wt review后进入reviewwt merge成功后进入merged最后wt reaper删除分支和 worktree 目录变成pruned。这样做最直接的好处是任何时候wt list一眼就知道仓库里哪些事情还活着、哪些已经死透了。Agent 不是人它不会记得清理现场这些收尾工作必须交给工具。3.4 Agent 如何消费这个 CLI一个很容易忽略的设计点Worktrunk 的用户不只是人还有 Agent 本身。所以在命令输出上我同时保留了人眼友好的表格输出和机器可读的--json输出。这样你在 prompt 里可以让 Agent 自己去查该往哪个目录跑codex exec --json 运行 wt list 查看活跃任务然后进入 task-xxx 对应的目录开始修改Agent 拿到 JSON 后能自己解析路径然后cd过去干活。这个能力在跑多个 Agent 时特别有用——你不需要在 prompt 里硬编码完整路径Agent 自己会去看 worktree 清单。后续我还打算提供一个可选的 MCP server 包装让 Agent 通过 MCP 工具直接查询和创建工作区但目前 CLI 加 JSON 输出已经能覆盖大部分场景。3.5 为什么是 CLI而不是 GUI 或工作流平台我没做 GUI短期内也不打算做。原因很现实Agent 本身就是 CLI 消费者。Codex CLI、Claude Code、Gemini CLI这些 AI 编程前端全是命令行工具它们最容易消费的自然是命令行接口。GUI 看着好看但 Agent 无法操作最终你还是要留一层文本接口。工作流平台比如 n8n、Dify、Coze 这类流程编排工具倒是可以接但那是后话。Worktrunk 只负责解决“并行隔离工作区”这一层它应该像一个微服务一样被其他系统调用而不是把自己做成一个大而全的平台。保持薄是我刻意做的取舍。4. 实测用 Worktrunk 同时跑三个 Agent 的完整流程4.1 场景设定为了验证 Worktrunk 到底行不行我特意复现了之前翻车的那个场景一个 Python 微服务仓库三个并行任务任务 A重构日志模块涉及logging_utils.py、service.py任务 B新增/api/v2/report端点涉及routes.py、service.py任务 C修复内存泄漏 bug涉及cache.py。其中任务 A 和任务 B 都会碰service.py这正是上一轮失败的核心冲突点。4.2 完整命令流程第一步初始化wt init --root ~/projects/myapp第二步为三个任务分别 spawn 工作区wt spawn --name log-refactor --agent codex --base main wt spawn --name add-report-endpoint --agent codex --base main wt spawn --name fix-memory-leak --agent codex --base main每次 spawn 输出的都是一条 JSON包含 task id、分支名、绝对路径。我直接把这些信息写进三个终端窗口。比如任务 Acodex exec --cd ~/projects/myapp/log-refactor \ 重构此目录中的日志模块将 logging_utils.py 中的重复配置提取为统一函数任务 B 和任务 C 同理每个终端窗口的--cd指向各自独立的 worktree 目录。第三步中途查看状态。我随时可以跑wt list --json输出大概是[ {id: task-peg1a0, name: log-refactor, branch: wt/log-refactor, path: ~/projects/myapp/log-refactor, status: active}, {id: task-aoxf3k, name: add-report-endpoint, branch: wt/add-report-endpoint, path: ~/projects/myapp/report-endpoint, status: active}, {id: task-qs2cdn, name: fix-memory-leak, branch: wt/fix-memory-leak, path: ~/projects/myapp/memory-leak, status: review} ]任务 C 的 Agent 干完活我这边立刻能看到状态变成了review马上开始人工评审不用等另外两个任务。第四步评审通过后合并并清理wt merge --task task-qs2cdn --delete-branch wt reaper --task task-qs2cdn4.3 结果与收益量化这次三个 Agent 并行跑了大概一个半小时结果比预期好不少任务分支worktree 路径状态合并时冲突数日志重构wt/log-refactorlog-refactor/merged0新增 APIwt/add-report-endpointreport-endpoint/merged2手动解决修复内存泄漏wt/fix-memory-leakmemory-leak/merged0虽然任务 B 和任务 A 都动了service.py但因为它们是隔离工作区Git 显示两个分支有两位“修改作者”在同一区域做了不同改动需要手动合并。冲突只有 2 处而且都是因为同一函数签名被两个任务改了合起来比上一轮那种“悄悄覆盖”要可控得多。磁盘占用方面整个仓库原始大小约 180MB三个 worktree 额外占用了不到 60MB。原因是 Git 对象库完全共享只有 checkout 出的工作文件是独立副本所以并行环境的成本非常低。如果当时是三个git clone每个仓库就是 180MB加一起 540MBworktree 方案省了快八成的磁盘空间。4.4 一个失败的早期版本给我的教训其实 Worktrunk 本身也踩过一个坑。第一个版本我图省事没有强制每个任务独立分支而是允许 Agent 在同一个 worktree 目录里切分支。结果有一次两个 Agent 共用同一个目录A Agent 切到了分支 XB Agent 还留在分支 Y两边同时写文件把 switch 和 checkout 的文件状态搞出了一堆未跟踪文件。后来再也没人敢共用目录我也把“一个 worktree 只服务一个任务”写进设计约束。没有隔离就不叫并行只能叫排队浪费时间。5. 踩坑清单Agent 工具链和 Worktree 的边界处理5.1 Codex CLI 报“unable to locate the codex cli binary”这类环境问题把 Agent 放进新 worktree 目录后一个高频问题是它找不到 CLI 二进制。表象是 Agent 执行命令时提示chatgpt failed to start. unable to locate the codex cli binary or required runtime但实际上 codex 装得好好的只是PATH 环境变量没有正确继承。这类问题的根因通常是 worktree 目录里的 shell 环境不完全等价于你当前终端的环境尤其当 Agent 由某个守护进程或工作流平台拉起时环境变量被过滤了一部分。我的处理办法是在wt spawn的输出里除了路径还带上显式的调用命令用绝对路径指向 Agent 二进制比如/usr/local/bin/codex而不是裸写codex。如果你用的是 n8n、Dify 这类平台调用 Agent更要注意自己的工作流节点里有没有配置环境变量。5.2 Claude Code 的目录权限问题另一个常见的坑是权限。Claude Code 这类 CLI 工具首次进入一个新目录时会询问是否允许读取该目录原话类似“Allow access to this folder?”。在交互式终端里你手动允许就行但 Agent 在无人值守的 worktree 里开工时用户不在当场任务会直接卡住。在热搜里也能看到“claude code cli 如何给完全访问权限”是很多人搜的问题。我的建议是用目录级权限而不是全局权限。在 Worktrunk 的设计里每个任务 worktree 是独立目录你可以在第一次进入时允许该目录访问或者直接把权限配置放在全局配置文件中指明哪些根目录下的 worktree 可以被 Agent 访问。这样既不会让 Agent 拿到整个文件系统的钥匙也不会因为新目录权限卡住任务。5.3 MCP 配置共享还是隔离我吃了教训MCPModel Context Protocol是 Agent 获取外部工具和上下文的重要通道热搜里大家都在聊 Agent 组成结构里的 skill、memory、MCP。在使用 Worktrunk 时MCP 配置有一个边界问题MCP server 是共享的但工作目录必须跟随 worktree。我第一次跑并行 Agent 时给两个 Agent 配了同一个文件操作类 MCP server结果它们共享了一套 cwd直接导致两个 Agent 操纵同一批文件。后来我的做法是MCP server 本身保持全局注册比如文件读写、数据库查询这类通用能力但在启动 Agent 时把工作目录参数显式指向对应 worktree文件类 MCP 的 root 规则按每个 Agent 的任务工作区动态设置而不是固定成一个全局目录。5.4 node_modules、构建缓存和磁盘爆炸前端项目在这块最容易翻车。多个 worktree 目录是隔离的意味着每个 worktree 都会有自己的node_modules。仓库本身不大但 3 个 worktree 的 node_modules 加起来磁盘立刻紧张起来。处理办法可以参考 pnpm 的思路依赖存储全局化工作区只保留硬链接。如果你用 npm/yarn手动把公共依赖目录软链到某处或者用 monorepo 的 hoisting 策略。构建缓存如.pytest_cache、__pycache__、target/要确保已经写进.gitignore否则 Agent 跑完测试后一堆缓存文件会被当成未跟踪文件留在 worktree 里wt reaper都清理不干净。5.5 .git 锁文件冲突多个 Agent 并行时Git 自身的锁文件也可能打架。最常见的是.git/index.lock两个 Agent 同时git add或git commit后一个会报Unable to create .git/index.lock: File exists。不过我实测下来这种情况在 worktree 模式下反而没那么严重因为每个 worktree 有独立的 index只有涉及共享引用比如同时推进同一个分支的 fetch/push时才可能锁冲突。我的规避策略是给 Agent 的 prompt 里明确要求小步提交、不要频繁 fetch/push把远程同步集中在wt merge阶段做。Worktrunk 本身在 spawn 和 merge 时也会做必要的串行化避免多个 Agent 在同一时刻操作共享 Git 状态。5.6 提交信息要不要带任务标识Agent 自动产生的提交信息质量参差不齐有时甚至是“fixed bug”“update files”这种毫无信息量的内容。为了后期审查能对得上号我让 Worktrunk 在创建 worktree 时自动给仓库注入一段本地的 commit template要求每个 Agent 的提交信息带上 worktree 名和任务 ID。这样在git log里一眼就能看出哪次提交属于哪个任务合并回 main 后追溯起来省很多时间。6. 还能往后长的方向把 Worktrunk 嵌进更大的自动化系统Worktrunk 现在解决的是“单仓库内的并行 Agent 工作区管理”但它有一个更值钱的延伸方向作为工作流引擎的底层执行单元。我看到最近 n8n、Dify、Coze 这类平台上的 Agent 工作流越来越复杂尤其是“简历筛选工作流”“跨境电商订单抓取自动化”“多平台内容生产”这类典型场景本质上都是多个任务并发、各干各的、最后汇总。Worktrunk 完全可以被这类工作流节点调用工作流发一个 webhookWorktrunkspawn一个任务工作区Agent 干完活回调状态工作流汇总后mergereaper。等于把 Git 级别的隔离能力开放成一个可编程接口而不是只能人坐在终端前面敲。另一个我想做的方向是把任务之间的依赖关系显式化。现在三个任务完全独立但真实项目里任务 B 可能依赖任务 A 先合并的接口。下一版我想给wt spawn加上--depends-on参数让 Worktrunk 在检测到依赖未合并时自动从最新的基线分支给 Agent 创建新工作区避免 Agent 基于过时代码继续开发。不过这是后话当前版本把隔离和生命周期管理做好已经能覆盖绝大多数并行 Agent 的使用场景了。最后分享一个小经验不管用什么工具并行 Agent 之前先想清楚任务边界。如果两个任务改的是同一个模块的同一块逻辑它们本质上是串行的硬拆并行只会制造合并痛苦。Worktrunk 能保证“不互相干扰”但“任务是否真的该并行”这个问题还是要靠人想明白。工具只能把并行这件事变得安全不能替你把不合理的任务拆分变得合理。