最近把 Codex CLI 和 Claude Code 这类编程 Agent 真正并行起来跑的时候，我发现 Git 分支切换很快就成了最大的瓶颈。两个 Agent 同时开工，每个都要在同一个仓库里“写自己的那部分”，但大家都挤在主分支的工作目录里，结果就是代码相互覆盖、生成的文件互相污染，甚至一个 Agent 刚把测试跑过，另一个 Agent 一保存就把上下文全弄碎了。Git Worktree 本身是解决这个问题的标准答案，但裸用命令行管理一堆 worktree 又很容易失控。所以我把这套流程做成了一个叫 Worktrunk 的 CLI 工具，专门把“创建任务、分配 Agent、隔离工作目录、合并回主干”这件事变成一条命令。这篇文章就把这个项目的来龙去脉、设计取舍和实操过程完整拆给你看，适合正在折腾并行 AI Agent 工作流、想给团队搭一套可复用流程的人参考。
1. 为什么并行 AI Agent 会把 Git 工作流逼到墙角
1.1 串行开发的“单线程”方式，根本喂不饱多个 Agent
刚开始用 AI 编程 Agent 的时候，套路很简单：给 Codex 或者 Claude 一个任务，它在一个工作目录里改代码，你等它跑完，验收，然后给下一个任务。这是一个典型的串行流水线，一个时刻只有一个 Agent 在动仓库，Git 分支随便怎么切都不会互相踩脚。
但问题在于，现在 Agent 的执行效率其实相当高，一个任务的周期往往从几分钟到几十分钟不等。真正稀缺的反而是我作为“调度者”的时间和注意力。当你想同时塞给它三个互不相关的任务——比如一个修登录页的样式，一个补后端接口的参数校验，一个重构某个工具类的日志输出——如果还是按照传统方式一个个排队跑，浪费的其实是整个工作流的上限。
于是很自然就会想到并行：几个 Agent 同时跑。但一旦并行，Git 的“单工作目录”模型就出问题了。两个 Agent 同时 checkout 到同一个分支，各自在同一个工作目录里改文件，结果几乎必然是灾难：A 写的文件被 B 的格式化操作覆盖，B 生成的临时配置文件被 A 的清理逻辑删掉，两个人的构建产物混在一起，报错都不知道是谁造成的。
1.2 Git Worktree 是答案，但裸命令的心智负担太重
Git 其实早就提供了一个非常适合并行场景的原生能力：Git Worktree。它允许你在同一个仓库上维护多个工作副本，每个副本 checkout 到不同的分支，共享同一个 .git 目录。也就是说，你可以在一个仓库的根目录旁边再拉出一个新的目录，专门给某个分支使用，两边互不干扰。
这个机制用来做并行 Agent 隔离非常合适。但如果你直接用原生的 git worktree 命令，很快就会觉得别扭。比如你想为某个任务建一个独立目录、关联一个新分支，你需要记住一整套命令组合：
git worktree add ../task-fix-login -b feat/fix-login cd ../task-fix-login # 写代码、跑测试 git add . git commit -m "fix login bug" cd .. git worktree remove ../task-fix-login单看一次操作似乎不复杂，但任务一多就麻烦透了：你根本记不住哪个目录对应哪个分支、哪个分支对应哪个任务，清理的时候还容易删错目录，留下孤儿 worktree。更麻烦的是，每次启动一个新的 AI Agent，你都得把一堆命令拼成一段长脚本，传给它一堆环境变量和路径信息。这个“上下文切换”的成本，恰好抵消了并行带来的收益。
1.3 从“命令操作”到“任务操作”的思维转变
我做了 Worktrunk 之后最大的体会是，问题不在于 Git Worktree 不好用，而在于原生命令的抽象层级太低。你需要的不是“给我建一个 worktree 并切换到分支”，而是“我有个任务要处理，你帮我把隔离环境准备好，Agent 跑完之后告诉我怎么合并”。
这就是 Worktrunk 的核心设计思路：把“任务的整个生命周期”作为抽象单元，而 worktree、分支、目录这些技术细节全部封装在内部。你只需要告诉它“我要新建一个叫 fix-login 的任务”，它自动创建分支、创建 worktree、返回一个可执行目录；你告诉它“fix-login 做完了”，它自动提交、切回主仓库、合并分支、清理目录。
这种思维转变是我在实际使用中一步一步被逼出来的。最初我写了一段 bash 脚本，后来发现脚本越来越长，里面有各种异常处理、状态检查、并发控制，再后来觉得这已经不是一个“脚本”能装得下的东西了，就干脆做了一个真正的 CLI 工具。
2. Worktrunk 项目整体设计与思路拆解
2.1 核心抽象：任务状态机与命名规则
Worktrunk 在最底层依然是调用 Git 原生的 worktree 能力，但它在上层加了一套任务状态机。整个生命周期围绕以下状态流转：
| 状态 | 含义 | 对应操作 |
|---|---|---|
| pending | 任务已创建，尚未分配给 Agent | worktrunk task new |
| running | 任务对应的工作目录已就绪，Agent 正在执行 | worktrunk task assign |
| ready | Agent 已完成修改，等待人工验收或自动检查 | worktrunk task sync |
| merged | 分支已合并回主干，任务完成 | worktrunk task merge |
| abandoned | 任务废弃，分支与目录被回收 | worktrunk task cleanup |
这个状态机的好处是，你在任何时刻用 worktrunk list 看一眼，就知道当前有几个任务在跑、几个任务可以验收、哪些任务已经合并但还没有清理目录。比起在终端里反复敲 git branch -a 和 git worktree list 来对照判断，要直观得多。
命名规则也很重要。Worktrunk 默认使用“任务名 + 时间戳”的方式生成分支名和目录名，避免两个同名任务撞车。比如你新建一个 fix-login 任务，生成的分支可能是 feat/worktrunk/fix-login_20250615_1430，工作目录则是 .worktrunk/tasks/fix-login_20250615_1430。这个目录统一放在主仓库根目录下的隐藏目录里，方便集中管理，不会散落得到处都是。
强调一下，分支名里带上时间戳是很有必要的，因为并行任务很可能出现同名任务。如果只按任务名建分支，第二次新建同名任务时 Git 会直接拒绝，或者被迫加后缀，很容易引起混乱。
2.2 为什么做成 CLI 而不是 IDE 插件
其实一开始我也考虑过做成 VS Code 插件，或者配合某个 IDE 的扩展面板。但冷静想了一下，AI Agent 的使用场景和普通 IDE 插件场景差异很大：Agent 本身是跑在命令行里的，它需要的是干净、可编程、可脚本化的接口。CLI 工具反而能更好地融入整个自动化链路。
拿我现在的工作流举例。我会用一个任务编排脚本来调度多个 Agent，脚本里调用 Worktrunk 创建任务、拿到任务目录，然后把目录路径作为 Agent 的工作目录传给 Codex CLI 或 Claude CLI，Agent 跑完之后脚本再调用 Worktrunk 做合并。整个过程走的是标准输入输出和退出码，没有任何图形界面依赖。如果是 IDE 插件，反而没法被这些自动化流程方便地调用。
另外，CLI 也方便在 CI/CD 里用。比如我可以在 CI 里跑一套“并行代码评审”任务：用 Worktrunk 把每个 Agent 的改动拆到独立 worktree，在一个干净的集成环境里分别跑测试、跑静态检查，然后把结果汇总出来。这些都是纯命令就能完成的。
2.3 技术选型：为什么选择“包装 Git 命令”而不是用 Git 库
Worktrunk 底层我最终选择了直接调用系统 Git 命令，并通过解析输出来获取状态，而没有选择用 go-git 或 libgit2 这类 Git 库。核心原因有三个。
第一是兼容性。直接调 git 命令，只要系统里有 Git，Worktrunk 就能跑，不需要关心实现细节。而 Git 类库对某些较新特性的支持往往滞后，Worktrunk 需要依赖的 worktree 特性尤其如此。第二是行为一致性。Worktrunk 本质上是一个编排工具，它需要和用户平时用 Git 的习惯保持一致，直接包装 git 命令可以确保任何细微的 Git 行为都被原样保留。第三是代码复杂度。用 Git 库等于重新维护一层抽象，出问题的时候还得多一层排查，没必要。
至于实现语言，Worktrunk 用 Go 写的。选 Go 主要看中它编译成单文件、分发方便、并发模型顺手，而且写 CLI 的生态成熟，比如 cobra 这种命令行框架用起来非常省事。如果你想自己折腾一个类似的工具，Rust 或者 Go 都可以，但我不推荐 Python，因为分发时需要处理依赖，不够干净。
2.4 并行数量的控制逻辑
并行 Agent 不是越多越好。Worktrunk 本身不限制并发，但我在实际使用中摸索出一个经验：默认情况下，同时跑 2 到 4 个 Agent 是最舒服的区间。超过这个数量，Agent 之间的资源竞争会明显加剧，尤其是它们同时跑构建、同时吃 CPU 和内存的时候，机器很容易被拖垮。
所以在 Worktrunk 里，我加了一个并发槽位的概念。你可以为整个仓库配置最大并行任务数，新任务分配时会检查当前 running 状态的任务数量，满了就排队。这个机制看起来不起眼，但它能防止你自己手滑一次性启动十个 Agent 把机器搞崩。
3. 实操：用 Worktrunk 并行跑起两个 AI Agent
3.1 安装与初始化
目前 Worktrunk 的直接安装方式是通过 Go 工具链安装，安装后需要先用 init 命令在仓库里建立配置文件：
go install github.com/yourname/worktrunk@latest cd your-git-repo worktrunk initinit 命令会在仓库根目录生成一个 .worktrunk.yaml 配置文件，里面记录主分支名、任务目录位置、默认并发数等信息。默认情况下，主分支自动识别为当前所在分支。这里我建议你先把主分支切到 main 或 master，再执行 init，避免把配置绑定到临时分支上。
init 之后会创建一个 .worktrunk 目录（和 .git 同级），所有的任务工作副本都会放在这个目录下。在 .gitignore 里加上 .worktrunk 也可以，但默认情况下 Worktrunk 创建的目录不会干扰 Git 状态，因为每个 worktree 都有自己的 .git 文件，指向主仓库的 .git 目录，主仓库不会把这些目录当作普通文件来跟踪。
3.2 创建任务并启动 Agent
初始化之后，我实际操作中最常用的就是 task new 和 task assign 这一对命令。
worktrunk task new fix-login创建任务后，Worktrunk 会输出一个任务目录路径。然后我可以把两个不同的任务分别交给两个 Agent：
# 终端窗口 1：Agent A 处理修复登录 worktrunk task assign fix-login --cmd "codex exec --sandbox off '修复登录页面的空指针异常，并补充对应测试'" # 终端窗口 2：Agent B 处理接口校验 worktrunk task new add-api-validation worktrunk task assign add-api-validation --cmd "codex exec --sandbox off '给用户接口增加参数校验逻辑'"assign 命令做的事情很简单：在任务对应的工作目录里，以该目录作为当前工作路径执行你传入的命令。这样 Agent 看到的是一个完全隔离的目录，它在里面创建文件、修改代码、运行测试，都不会影响主仓库或其他任务目录。
这里有个重要的细节：传给 Agent 的任务指令里，最好明确告诉它“你当前的工作目录就是仓库根目录”。因为 Agent 本身对自己运行在哪个目录是有感知的，你给它一个完整路径，它读代码、写文件的逻辑就都会落在正确的位置。如果你的任务需要它参考主分支的最新代码，可以在 assign 之前先跑 worktrunk task sync，把主分支的最新改动同步到任务分支上。
3.3 查看任务状态与同步最新代码
并行跑起来之后，随时可以用 worktrunk list 查看整体状态，输出大概是这样：
ID STATUS BRANCH DIRECTORY fix-login running feat/worktrunk/fix-login_20250615_1430 .worktrunk/tasks/fix-login_20250615_1430 add-api-validation running feat/worktrunk/add-api-validation_.. .worktrunk/tasks/add-api-validation_20250615_1431当某个 Agent 任务做了一半，你想让它基于主仓库最新的提交继续修改时，可以在主仓库执行 worktrunk task sync，它会把主分支更新到任务分支的基础提交，然后在对应 worktree 里执行 git merge 或 git rebase，让任务分支包含主分支的最新代码。默认我用 merge 而不是 rebase，因为 Agent 的现代码和主分支更新通常不会冲突，merge 的冲突解决过程更简单。
不过我得提醒自己一条经验：在 Agent 运行过程中频繁执行 sync 未必是好事。每次同步都可能让工作区发生剧烈变化，Agent 如果不理解这次变更，可能会在错误的基础上继续开发。我通常只在 Agent 停下来不跑的时候才做同步，或者明确让 Agent 自己执行“拉取最新代码”的动作。
3.4 合并与清理：验收之后的收尾动作
Agent 跑完后，任务状态变成 ready。这时我先自己看一眼改动，或者跑一遍测试，确认没问题，然后执行合并：
worktrunk task merge fix-loginmerge 命令会把任务分支合并回主分支，并自动切换到主仓库。默认策略是只合并任务分支上的提交，不做特殊处理。如果你希望合并后自动删除远程分支，可以加 --delete-remote 参数，不过我觉得保守一点更好，远程分支先留着，确认没问题再手动清理。
合并完成后，任务目录还在，方便继续检查。等你确认一切都干净了，再执行：
worktrunk task cleanup fix-logincleanup 会删除对应的 worktree 目录、本地分支，并更新任务状态为 abandoned。这里我踩过一个坑：如果任务目录里有未提交的改动，git worktree remove 会直接报错退不出来。所以 cleanup 之前 Worktrunk 会先检查是否有未提交改动，如果有，它会拒绝执行并提示你先处理。这个保护逻辑在并行情境下尤其重要，因为多个任务同时跑，很容易搞不清楚哪个目录还有未保存的东西。
3.5 与 CI/CD 的无缝衔接
如果你想把并行任务检查接入 CI，Worktrunk 也提供了一条干净的路径。在 CI 脚本里你可以这样用：
worktrunk task new pre-merge-check worktrunk task assign pre-merge-check --cmd "./scripts/check_all.sh" worktrunk task merge pre-merge-check这样 CI 里的并行检查任务就被隔离到独立 worktree 里，不会和主流水线互相干扰。如果需要检查多个分支，可以在 CI 里循环创建多个任务，每个任务对应一个分支，最后统一合并或统一上报。这种用法特别适合处理“同一仓库多个 MR 同时做集成验证”的场景。
4. 常见问题与排查技巧实录
4.1 worktree 状态显示错乱，分支对不上目录
症状是执行 worktrunk list 时，某个任务的 BRANCH 和实际目录显示不一致，或者 Git 里报 “git-worktree: directory is already registered” 之类的错。
这种问题八成是之前手动操作过 git worktree，或者任务目录被手动删除过，导致 Worktrunk 的配置文件里的记录和 Git 自身状态不同步。排查顺序是：先跑 git worktree list 看 Git 自己怎么认为，再检查 .worktrunk 目录下的任务记录文件，两边对照就能看出谁出了偏差。
如果确认某个任务目录已经不存在了，但 Git 还记录着，可以用 git worktree prune 清理无效记录，再跑 worktrunk task cleanup --force 清理 Worktrunk 的元数据。这里建议不要用 --force 覆盖异常情况，最好先 manual 把目录处理干净，再用 force 收尾，不然容易误删别的任务的状态。
4.2 合并冲突：并行任务改到同一个文件的相邻位置
并行最怕的就是两个 Agent 改了同一个文件的相近区域。比如 Agent A 修复登录接口时调整了 user.go 的校验逻辑，Agent B 给同一段逻辑加了日志，两边都修改了 user.go 的同一段代码，合并时就必然冲突。
Worktrunk 不会帮你自动解决冲突，因为冲突的内容只有人能判断。但它做了一个我觉得很实用的设计：合并冲突时，它会把冲突文件的路径和当前状态打印成一个清单，并且提示你“此时主仓库还处于 merge 状态，你需要先处理冲突再提交”。
实操上，我的处理方法是先看冲突文件的 diff，理解两个改动各自的意图，然后再手动保留合理部分。如果你发现某个 Agent 的改动和另一个 Agent 的改动本质上是在做同一件事，那你可能应该在分配任务之前就拆得再清楚一些。从根上避免冲突，比解决冲突成本低得多。
4.3 关于“Agent 在工作目录里生成的临时文件污染主仓库”
这是最容易被忽略的一个坑。有些 Agent 会生成临时文件、缓存文件，或者往项目根目录写一些配置文件（比如 .env、node_modules 的一部分），如果 Agent 在共享主仓库里跑，这些文件就直接污染了主分支。Worktrunk 的隔离机制天然规避了这个问题：Agent 的整个写入空间都在任务自己的 worktree 目录里。
但如果任务目录是直接从主分支复制出来的，Agent 又往里装了依赖（比如 npm install），最后合并回主分支时，这些 node_modules 或 vendor 目录要不要提交？我的建议是在任务分支的 .gitignore 里统一排除这些目录，或者在 merge 前先让 Agent 主动清理。Worktrunk 在 merge 时会默认跳过那些在 .gitignore 里的文件，避免把不必要的依赖打包进来。
4.4 多个 Agent 并发跑测试时端口冲突
两个 Agent 同时在自己的 worktree 里跑起测试服务，默认监听同一个端口，必然打架。这个问题 Worktrunk 层面解决不了，但你在分配任务时可以提前预防：在 assign 命令里给不同任务设置不同的环境变量，比如 PORT=3001、PORT=3002，或者在任务指令里明确要求 Agent 使用特定端口。另外，如果测试用到数据库，也要给不同任务配置不同的测试库或模式，否则并行测试的数据会互相污染。
我自己的经验是，先把这些隔离要求写进一个 task 模板里，每个新任务创建时自动附带这些环境配置，省得每次手动写。
4.5 磁盘空间与 worktree 数量失控
每个 worktree 都是一份完整的工作副本，如果项目体积大（比如 node_modules 几 GB），同时跑五六个 Agent 会把磁盘撑爆。Worktrunk 做了一个 worktrunk doctor 命令，可以列出所有任务目录占用的磁盘空间，并提示你清理已合并、未清理的任务。我通常每周跑一次 doctor，看看有没有堆积的旧任务目录，该清理就清理。
如果你经常遇到磁盘吃紧的问题，还有一个更激进的做法：任务目录采用共享依赖的方式，比如把 node_modules 软链到主仓库的一份公共缓存。这个方案能大幅减少单任务体积，但它也会带来新的问题——Agent 如果安装不同版本的依赖，共享目录会互相覆盖，所以只适合依赖相对固定的场景。
4.6 与 Agent CLI 的集成陷阱：目录与上下文隔离
最后说一个和 Codex CLI、Claude Code 这类工具直接相关的坑。这些 Agent CLI 往往会在运行的工作目录里创建自己的状态文件、会话历史或者缓存。如果多个 Agent 共用同一个目录，会话状态就会串味。Worktrunk 为每个任务分配独立目录，这个问题自然就解决了。
但你要注意一件事：有些 Agent 支持指定一个“项目级上下文目录”，用来读全局规范文档。如果你都设置了同一个上下文目录，那这个目录会被多个 Agent 同时读，没问题；但如果某个 Agent 在上下文目录里写缓存，就可能出现并发写冲突。我的做法是给每个任务复制一份上下文目录到任务目录内部，Agent 读自己的副本，这样最稳妥。
5. 一些我在实际操作中沉淀下来的体会
Worktrunk 做到现在，最大的收获不是“多了一条命令”，而是整个工作流的心智模式变了——从“我为 Agent 准备一个目录，盯着它跑”变成“我描述任务，给它一个隔离环境，然后同时验收多个结果”。Git Worktree 是这个模型的地基，Worktrunk 只是把这个地基平整好、画好格子，让并行不再是偶然能成，而是稳定的可循环过程。
如果让我给刚开始用并行 Agent 工作流的人提一条建议，那就是不要一开始就追求多而全。先串行跑通一个任务，再尝试用 Worktrunk 跑两个并行任务，先搞明白目录隔离的逻辑，再逐步加并发数。另外一定要养成及时清理任务目录的习惯，不然跑了几周之后，.worktrunk 下会堆出几十个副本，看到都会头痛。
最后分享一个小技巧：把 Worktrunk 的命令封装成你们团队自己的快捷键，或者写进一个 Makefile。比如 make task-new、make task-merge 之类的别名，团队成员不需要记太多命令，也能享受并行 Agent 工作流带来的效率提升。这个工具目前还在持续迭代，我也在考虑把任务模板、Agent 技能接入、自动验收这些能力加进去，让它真正成为并行 Agent 时代的“工地调度台”。
