最近把 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任务已创建尚未分配给 Agentworktrunk task newrunning任务对应的工作目录已就绪Agent 正在执行worktrunk task assignreadyAgent 已完成修改等待人工验收或自动检查worktrunk task syncmerged分支已合并回主干任务完成worktrunk task mergeabandoned任务废弃分支与目录被回收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 CLIAgent 跑完之后脚本再调用 Worktrunk 做合并。整个过程走的是标准输入输出和退出码没有任何图形界面依赖。如果是 IDE 插件反而没法被这些自动化流程方便地调用。另外CLI 也方便在 CI/CD 里用。比如我可以在 CI 里跑一套“并行代码评审”任务用 Worktrunk 把每个 Agent 的改动拆到独立 worktree在一个干净的集成环境里分别跑测试、跑静态检查然后把结果汇总出来。这些都是纯命令就能完成的。2.3 技术选型为什么选择“包装 Git 命令”而不是用 Git 库Worktrunk 底层我最终选择了直接调用系统 Git 命令并通过解析输出来获取状态而没有选择用 go-git 或 libgit2 这类 Git 库。核心原因有三个。第一是兼容性。直接调 git 命令只要系统里有 GitWorktrunk 就能跑不需要关心实现细节。而 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 Agent3.1 安装与初始化目前 Worktrunk 的直接安装方式是通过 Go 工具链安装安装后需要先用 init 命令在仓库里建立配置文件go install github.com/yourname/worktrunklatest 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# 终端窗口 1Agent A 处理修复登录 worktrunk task assign fix-login --cmd codex exec --sandbox off 修复登录页面的空指针异常并补充对应测试 # 终端窗口 2Agent 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 的无缝衔接如果你想把并行任务检查接入 CIWorktrunk 也提供了一条干净的路径。在 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 命令里给不同任务设置不同的环境变量比如 PORT3001、PORT3002或者在任务指令里明确要求 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 时代的“工地调度台”。