最近我在折腾 AI Agent 编程这件事发现日常开发模式发生了很大变化。以前开一个分支切来切去还能勉强应付现在我的终端里同时挂着 Codex CLI、Claude CLI一个在加新接口一个在修历史 bug还有一个在处理重构落地。三个任务同时转代码仓库就变成了灾难现场——不是 checkout 被未提交的修改挡住就是分支一换上下文全部乱套。后来我把 Git Worktree 的能力抽出来做了个专门管理并行 Agent 工作流的 CLI 工具也就是本文要聊的 Worktrunk。这篇内容主要围绕 Worktrunk 的设计思路、核心功能、实操流程和实战排查展开。如果你正在用 AI Agent 辅助开发或者团队里已经在同时跑多个编码智能体这篇文章能帮你把并行开发这件事从互相打架变成各干各的。如果你只是听说过 Git Worktree 但一直没搞明白能用来干嘛这篇文章也能给你一个非常具体的落地场景。1. 并行 Agent 工作流到底遇到了什么问题1.1 多个 Agent 同时改代码仓库为什么会崩先描述一个我再熟悉不过的场景。周一早上我接到三个任务给支付模块加一个回调接口修复登录页在 Safari 下的样式异常把老项目中一个工具函数重构成 TypeScript 版本。按照以前的习惯我会一个个来但既然有 AI Agent 帮忙我自然想同时开工。于是我在三个终端里分别启动了三个 Codex 会话让它们各自工作。不到半小时问题就来了。Agent A 在feature/payment-callback分支上添加文件Agent B 在fix/safari-login分支上修改同一个组件的样式Agent C 在refactor/ts-utils分支上改动工具函数。问题是这三个分支都在同一个工作目录里。每当我切换分支Git 就会因为当前工作目录有未提交的变更而拒绝操作。我只能先把一个 Agent 的改动 commit 掉再切到另一个分支等它跑完再切回来。这一通操作下来不仅浪费了大量时间还经常出现两个 Agent 改到同一个文件、互相覆盖的情况。这就是并行 Agent 工作流的第一个痛点同一个工作目录只能对应一个分支状态而 Agent 是自动运行的它不会像人类一样先 stash 再 checkout也不理解你先把当前工作让出来这种指令。它只会僵在那里或者直接把改动写到当前目录里把现场搞得一团糟。1.2 分支、工作目录与 checkout 的本质要理解 Worktrunk 的解法得先把 Git 的底层原理理清楚。很多人把分支理解成代码的一个版本实际上分支只是一个指向某个 commit 的轻量指针。真正存储代码内容的是 commit 对象和目录树对象分支只是一个会移动的标签。而工作目录working directory才是你真正看到和编辑文件的地方。当你运行git checkout切换分支时Git 做的事情其实是把目标分支指向的 commit 中的文件内容解压出来覆盖到当前工作目录中。如果工作目录里有未提交的改动覆盖就会产生冲突所以 Git 会拦下你提醒你先提交或者存储起来。这里的关键限制在于一个仓库默认只有一个工作目录。也就是说不管你有多少个分支同一时刻只有一个分支的内容能在磁盘上展开。对于串行开发来说这没什么问题但到了多个 Agent 并行的场景这个单工作目录的设计就成了最大的瓶颈。你总不能让一个 Agent 先停下来等另一个 Agent 跑完再继续吧1.3 Worktree 为什么是答案Git 原生提供了一个解决这个问题的能力git worktree。它的核心思想是允许你为同一个仓库创建多个工作目录每个工作目录可以 checkout 不同的分支而这些工作目录共享同一个.git对象数据库。用人话说就是你可以在同一个项目的不同文件夹里同时存在多个不同分支的代码副本。比如/project # 主工作目录对应 main 分支 /project/.worktrees/auth # 另一个工作目录对应 feature/payment-callback 分支 /project/.worktrees/fix # 第三个工作目录对应 fix/safari-login 分支这三个工作目录互不干扰任何一方 checkout 分支、修改文件、提交 commit都不会影响另外两个。Agent A 在.worktrees/auth里干活Agent B 在.worktrees/fix里干活它们永远不会碰面也永远不会改到同一个文件——至少在文件系统层面是隔离的。Git Worktree 的这个特性和 AI Agent 的工作方式非常契合。Agent 通常是在一个目录里读代码、改代码、运行测试它并不关心你用的是哪个分支只要当前目录里的代码是正确的目标状态就行。Worktree 正好提供了这种每个目录一个独立世界的隔离环境。不过原生的git worktree命令用起来有几个问题命令参数比较繁琐目录管理需要自己规划分支名和目录名靠人工约定时间一长目录里堆了一堆 worktree 根本分不清哪个对应哪个任务。Worktrunk 就是在这个基础上做的封装和管理层。2. Worktrunk 的核心设计Agent 任务与 Worktree 生命周期绑定2.1 设计原则一个任务等于一个 WorktreeWorktrunk 最重要的设计决策是把一个 AI Agent 任务与一个 Worktree强制绑定起来。在使用 Worktrunk 之前我见过很多人用原生 worktree 做并行开发但最终都失败了原因就是没有建立清晰的映射关系worktree 目录名叫什么、对应哪个分支、服务于哪个任务全靠记忆一旦任务多了立刻混乱。Worktrunk 的做法是收起这些决策用约定来取代配置。当你执行worktrunk create agent-a --base main时它会自动帮你做这么几件事在约定的工作区目录下比如.worktrunk/agent-a创建新的 worktree从指定的基准分支这里是main拉出一个新的功能分支分支名默认与任务名一致记录这条 worktree 的元信息包括创建时间、基准分支、关联的任务描述。这样一来目录名、分支名、任务名三者完全一致。你不需要去记agent-a 的任务分支叫什么因为所有东西都有一个唯一的、可预测的命名规则。这在同时管理十个以上 Agent 任务时尤其重要。2.2 Worktrunk 的状态机设计光有命名规则还不够还得管理 worktree 的生命周期。Worktrunk 内部为每个 worktree 维护了一个简单的状态机状态包括created刚创建Agent 还没开始工作activeAgent 正在或已经在该 worktree 中修改代码merged该 worktree 的分支已经合并回主分支cleanedworktree 目录已被移除元信息保留用于追溯。这个状态机的价值在于它能让你在一堆 worktree 里快速识别哪些任务还没完成、哪些已经合并但忘了清理目录、哪些处于中间状态。我实际使用中发现AI Agent 任务经常出现代码写完了但忘了合并的情况Worktrunk 在显示列表时会用状态列直接标出来比我一个个git branch --merged去查要直观得多。状态切换的规则也很直接。worktrunk list会读取 git 的分支信息与 worktree 配置文件自动计算每个 worktree 的分支是否已经包含在主分支的历史中。如果包含了就将状态标记为merged。这个检测不依赖任何外部服务完全是纯本地的 git 操作所以速度很快几百个 worktree 的场景也能在毫秒级完成状态刷新。2.3 与 Agent 工具的集成方式Worktrunk 本身是一个 CLI它的集成方式非常灵活。最简单的方式是在 shell 里手动操作worktrunk create agent-a cd .worktrunk/agent-a codex但这还不够自动化。我的习惯是写一个简单的包装脚本把启动 Agent 并指定任务目录变成一条命令。脚本的逻辑大致是worktrunk create $1 cd .worktrunk/$1 codex $2这样每次开新任务只需要agent-start task-42 为支付模块添加回调接口脚本会自动创建 worktree、切换目录、启动 Codex。Agent 看到的代码就是干净的目标分支状态任务结束之后我只要回到主目录执行worktrunk merge task-42就能完成合并和清理。更进一步Worktrunk 还支持在创建时设置环境变量。比如worktrunk create agent-b --env-file .env.agent-b它会把指定的环境变量注入到后续启动的 Agent 进程中。这个能力在调试多 Agent 协作时很有用因为不同 Agent 可能需要访问不同的 API Key 或者配置不同的模型参数而这些配置不需要写进代码里。3. Worktrunk 实操从零搭建并行 Agent 工作流3.1 安装与初始化Worktrunk 是 Go 写的编译出来是单个二进制文件所以安装非常省事。我这边用的是 Homebrewbrew install worktrunk或者直接从 GitHub Releases 页面下载对应平台的二进制丢到$PATH里。没有 Node 依赖没有 Python 运行时也没有环境变量要配。这一点对于我这种经常在 Mac 和 Linux 服务器之间切换的人来说特别重要因为我不想在每个环境里都折腾一套依赖。安装完之后先进入你的项目仓库执行初始化cd /path/to/your/project worktrunk init这个命令会检查当前目录是否是一个 Git 仓库如果是就在仓库根目录下创建一个.worktrunk/元数据目录并把你的主分支设定为默认基准分支。它不会改动你现有的任何代码也不碰你的.gitignore除非你让它托管。初始化之后整个项目的 worktree 管理就可以交给 Worktrunk 了。3.2 创建任务并启动 Agent假设现在来了一个新任务给订单模块加一个导出 Excel 的功能。我执行worktrunk create order-export --base develop --desc 订单导出Excel功能Worktrunk 会做下面这些事在.worktrunk/order-export下创建新的 worktree从develop分支拉出worktrunk/order-export分支并 checkout 到新 worktree 中在.worktrunk/元数据中记录任务描述和创建时间。创建完成后终端会输出类似这样的信息worktree created at .worktrunk/order-export branch: worktrunk/order-export status: created然后我可以从多个终端同时启动多个任务# 终端1 worktrunk create order-export cd .worktrunk/order-export codex # 终端2 worktrunk create login-password-migration cd .worktrunk/login-password-migration trae_cli # 终端3 worktrunk create dashboard-performance-fix cd .worktrunk/dashboard-performance-fix claude三个 Agent 现在各自在独立的目录里跑互不干扰。这是整个工具最核心的价值并行但没有冲突。3.3 并行执行期间的主分支同步策略并行跑了一段时间后你很快会遇到一个新问题Agent A 已经完成并合并回主分支了而 Agent B 的 worktree 还是基于旧的主分支创建的它后续如果涉及修改同一个文件就可能产生上下文过期的问题。比如 Agent A 改了src/utils/date.ts的接口签名Agent B 还在用旧的签名写代码等到合并时就会出现大量冲突。解决这个问题的方式是定期让每个 worktree 把主分支的最新改动拉进来。Worktrunk 提供了一个sync命令worktrunk sync agent-b这个命令会在agent-b的 worktree 中执行git fetch origin然后尝试把主分支并入当前分支。如果 Agent B 已经修改了文件并且产生了冲突sync会把冲突标记暴露出来但不会擅自帮你解决。你可以在 Agent B 的对话上下文里告诉它主分支有更新sync 出了冲突你检查一下src/utils/date.ts这个文件以新接口为准调整逻辑。Agent 处理这种局部冲突通常很高效。要注意的是sync不应该开太频繁。如果主分支还在快速变更你让 Agent B 每十分钟就同步一次它反而会因为代码版本总在变而失去稳定性。我习惯的节奏是Agent 完成一个独立的功能模块后或者它明确报告我改完了准备写测试时才做一次 sync。过早同步是并行开发中容易出现的问题。3.4 任务合并与清理当一个 Agent 完成工作后合并流程应该是这样先检查 Agent 在 worktree 里的改动是否符合预期。你可以自己跑一遍测试或者把改动 diff 出来审一遍cd .worktrunk/order-export git log --oneline develop..HEAD git diff develop...HEAD确认没问题后回到主仓库目录执行合并worktrunk merge order-export --deletemerge内部做的事情包括确保 worktree 分支上没有未提交的改动执行 checkout 到主分支如果当前在主仓库目录把 worktree 分支 merge 进来并且如果有--delete参数就顺手把 worktree 目录和对应分支删掉。清理这一步很容易被忽略。原生git worktree remove有时候会因为 worktree 里有未提交文件而报错Worktrunk 在删除前会做一次检查如果有未提交修改会先警告你并提示先提交或丢弃避免误删数据。4. 实际项目中的常见问题与排查方案4.1 worktree 删除失败目录不是空的这是新手最容易遇到的问题。git worktree remove对非空目录是直接拒绝的报错信息大概是 contains modified or untracked files。Worktrunk 的做法是删除前先尝试执行git clean -fd和git reset --hard HEAD把 worktree 里残留的未跟踪文件和未提交修改清掉然后再删除。但这里有个坑如果你用了 Docker 或者构建工具worktree 目录里可能有构建产物或者.env文件这些文件并不是 git 跟踪的git clean也不会误删它们。我在第一次清理时就吃过亏因为 worktree 里跑过测试生成了一个node_modules目录删除时磁盘占用极大还花了不少时间。后来我在.gitignore中把构建产物目录排除并在创建 worktree 时用--skip-clean跳过不必要的清理动作情况才好转。4.2 分支被 Agent 提交信息搞乱Agent 提交代码的习惯不太一样有的工具喜欢在提交信息里加上模型名称和日期比如feat: add excel export (claude-3.7, 2025-06-01)。这些信息本身没啥问题但如果你用git log --format做自动化分析或者通过 commit 信息做 CI 关联就会遇到混乱。我的建议是在 Worktrunk 的create命令里通过--commit-template指定一个统一的提交信息模板让 Agent 在 commit 时遵循团队规范。Worktrunk 会在创建 worktree 时把模板写入仓库的 git config 中这样 Agent 无论用什么方式提交都至少会被模板约束住。如果 Agent 不遵守模板你可以在审查阶段用git rebase -i批量改写提交信息但那就得靠人工了我一般只在任务合并前做一次。4.3 多个 worktree 的磁盘占用和构建缓存很多人会忽略一个问题每个 worktree 是一份完整的代码目录。如果一个项目有 3 万个文件每个 worktree 都会把这 3 万个文件展开到磁盘上。虽然 Git 对象是共享的但 working tree 是实打实占用空间的。我维护过一个大项目同时开了 8 个 worktree磁盘占用轻松超过 20GB。如果项目里再有node_modules或者构建缓存这个数字会更离谱。解决方案是让每个 worktree 共享构建缓存目录。前端项目可以把 npm 的缓存目录指向全局路径npm config set cache /shared/.npm-cache或者直接用 pnpm 的全局 store 机制。对于 Python 项目可以创建虚拟环境时复用已有的 pip 缓存。Worktrunk 在创建新的 worktree 时不会自动配置这些所以我习惯在init阶段写好一个.worktrunk/profile.sh里面定义好缓存路径相关的环境变量每次创建 worktree 后 source 一下。这个脚本不是 Worktrunk 强制的是我自己的实践但效果非常好。4.4 合并冲突多个 Agent 仍然可能改到同一个文件虽然 worktree 在工作目录层面完全隔离但 git merge 时仍然可能产生代码冲突。比如 Agent A 和 Agent B 都改了config.py里的配置项但各自基于不同的主分支版本。这种冲突不会在开发时暴露只会在 merge 时爆发。处理这种冲突的关键在于不要试图在命令行里手动把几百行的冲突文件一点点改好。我建议把冲突文件丢回给 Agent 处理。具体做法是git merge之后如果发现冲突文件是 Agent 擅长处理的类型直接用codex --task resolve conflicts in config.py, keep both settings, follow the new structure让它去解决。因为 Agent 有上下文记忆它知道自己的改动意图处理冲突的速度比人肉快得多。如果冲突规模很大比如两个 Agent 改了同一个模块不同的十几个文件我通常会先中止合并重新评估任务的拆分粒度。并行任务在文件层面应该尽量不重叠这是任务拆分时就要想清楚的而不是等 merge 之后再亡羊补牢。Worktrunk 在这方面帮不上忙它只负责隔离不负责替你设计任务边界。4.5 Worktrunk 与 CI 系统的配合还有一个容易被忽略的场景CI 系统会监听分支的 push 事件。当 Agent 在各 worktree 中提交代码并 push 分支时CI 可能会疯狂触发构建。对于小项目来说无所谓对大型项目来说这会浪费大量算力。我的经验是在 Worktrunk 创建 worktree 时通过--skip-ci参数在推送的 commit message 中加上[skip ci]标记。或者反过来在 CI 配置里只监听合并到主分支的构建不监听功能分支的构建。前者更简单因为不用改 CI 配置缺点是会在提交历史里留下一堆[skip ci]标记。后者更干净但对团队协作是一个约束所有人的功能分支都不会触发 CI只有最终合并到 main 时才会构建。我倾向于后者Worktrunk 本身的定位是个人开发者工具但也支持多人协作只是需要约定好 CI 策略。5. 最后我的一些使用体会5.1 别一上来就开十个 worktreeWorktrunk 把创建 worktree 的成本降得非常低命令行敲一下一秒钟就能开一个新任务。但低成本的另一面是容易滥用。我试过同时开 10 个 Agent 任务结果发现第二天有 4 个 Agent 都处于半完成状态每个都在等我把测试用例补齐或者等我回答一个设计问题。并行本身不是目的把手头的任务约束在我能在半天内审查完的范围内才是正确的使用姿势。我现在基本控制在 3 到 5 个并行任务再多就不太管得过来了。如果你的团队有专职的 review 人员可以适当放宽但不要指望 Agent 之间能自己协调依赖关系至少在目前这个阶段它们还没有这个能力。5.2 Agent 的上下文管理比 worktree 管理更难最后再分享一个我的观察。Worktrunk 解决了工作目录隔离的问题但并行跑多个 Agent 时真正让人头疼的其实是上下文管理。比如你让 Agent A 修改了一个公共组件的接口然后 Agent B 正在用这个组件写新的页面Agent B 不会自动知道接口已经变了。良好的任务拆分和定期的sync能缓解这个问题但最终还是要靠人来把控全局。如果你要用这套流程请记住一条铁律每个 Agent 任务的描述里一定要写清楚它依赖哪些模块、这些模块可能正在被其他 Agent 修改以及它应该优先保证自己负责的代码是正确的而不是试图去修复其他 Agent 正在改的代码。有了这条约束再加上 Worktrunk 的隔离能力并行 AI Agent 工作流才能真正跑得起来。