1. 为什么AI Agent并行开发最终都得面对Worktree先聊一个我踩过的大坑。之前团队引入AI编程助手之后大家发现了一个尴尬的问题单条Agent会话写代码确实快但一旦同时开两三个会话让它们分别改不同模块灾难就来了。A会话刚改完server/api.go里的接口定义B会话在另一个任务里基于旧的接口签名写了一堆调用代码两个会话互相不知道对方干了什么最后合并的时候冲突多得让人崩溃。更离谱的一次两个Agent同时往同一个文件里追加代码后保存的那份直接把先保存的覆盖了几十行代码凭空消失git diff里都找不回来。当时我就在想这问题本质上不是AI的问题而是所有并行编辑任务在单工作目录下的天然缺陷。人写代码遇到这种情况第一反应是我们各开一个分支各改各的但没人会真的手动在多个git分支之间来回切——切换分支需要暂存或提交当前工作区代价太高。而AI Agent更麻烦它的上下文是跟着文件路径和工作目录走的你让它切分支它可能连当前改到哪了都记不清。后来我看到了Git Worktree这个原生功能。它允许你在同一个仓库里同时检出多个工作目录每个目录对应不同的分支互不干扰。这简直是给并行AI Agent工作流量身定做的基础设施。但用了几天原生git worktree命令之后我又发现了新问题原生命令太裸了它只管创建和删除工作目录完全不关心这个worktree正在跑什么任务、属于哪个Agent会话、上下文是什么。比如我开着三个worktree分别做三个功能过了两天回来一看每个目录里都有未提交的改动但我完全不记得哪个目录对应哪个任务了。这种状态管理成本最后又落到了人身上。2. Worktrunk的定位它不是Git命令的又一次封装所以要做的不是一个git worktree的糖衣包裹而是一个能真正管理Agent会话与Worktree生命周期的工具。这是Worktrunk和所有同类CLI最本质的区别。我的设计出发点很简单把任务/会话和工作目录绑定成一个整体来管理。每个Agent会话启动之前先让Worktrunk为它分配一个独立的工作区这个工作区自带分支名、目录名、任务描述、创建时间Agent干完活了Worktrunk负责把改动合并回主干然后回收这个工作区。整个过程中人只需要知道我这个任务叫什么不需要关心底层是哪个分支、哪个目录。这个工具我给它的名字叫Worktrunk核心思路借鉴了任务管理系统的概念——每个Worktree不是一个冰冷的目录而是一个有名字、有状态、有归属的任务上下文。你跑wt session list看到的不是一堆无意义的分支名而是清清楚楚的任务列表任务名称、负责人是哪个Agent会话、当前状态进行中/待合并/已合并、最后活动时间。这才是我觉得真正有价值的CLI工具该有的样子。为了说清楚这个设计先列一下我最初定的功能边界会话管理创建、查询、删除、回收Agent工作区自动起名带语义的工作目录和分支隔离执行在Agent工作区内执行命令所有文件读写都在独立目录里互不干扰安全合并把工作区改动合并回主分支冲突时自动暂停并提示而不是盲目覆盖状态追踪记录每个工作区的任务元数据、当前改动文件列表、与主干的分叉点环境同步从主干同步最新代码到工作区解决长生命周期Agent任务和主干代码漂移的矛盾命名和目录结构上我也做了设计。比如创建一个任务会生成这样的目录结构. ├── worktrunks/ │ ├── agent-fix-login-bug/ # 工作区目录 │ ├── agent-add-search-suggest/ # 另一个工作区目录 │ └── agent-refactor-auth/ # 第三个工作区目录 ├── server/ ├── web/ └── ...默认情况下所有Worktree统一放在仓库根目录的worktrunks/文件夹里一眼扫过去就知道机器上开了哪些并行任务。这个习惯用起来非常舒服尤其适合我这种同时开好几个实验任务的场景。3. 核心功能拆解从创建会话到合并回主干的完整闭环3.1 创建会话参数、命名规则和默认行为wt session new是使用频率最高的命令。它做的事情比表面上看起来多得多wt session new --name fix-login-redirect-bug --base main这条命令执行后Worktrunk依次做了以下事情校验传入的任务名自动格式化为合法的git分支名比如把中文名转拼音、把空格和特殊字符替换成连字符基于main分支创建一个新的工作树目录路径为worktrunks/fix-login-redirect-bug同时切换到新分支wt/fix-login-redirect-bug创建一个关联的元数据文件worktrunks/.wt/fix-login-redirect-bug.json记录任务的创建时间、基分支、当前状态输出一个摘要信息告诉用户当前工作区的完整路径和分支名这里有个细节值得展开为什么分支名要带wt/前缀因为我希望所有由Agent创建的分支能在日志里一眼识别出来同时避免和人工开发的分支混在一起。后续的CI/CD配置也可以针对这个前缀做特殊处理。类似这种为了可识别性做的小设计在工具里还有很多。来看一下元数据文件的内容示例{ name: fix-login-redirect-bug, branch: wt/fix-login-redirect-bug, baseBranch: main, createdAt: 2025-01-15T10:30:00Z, lastActiveAt: 2025-01-15T10:30:00Z, status: active, agent: codex-cli, description: 修复登录后302重定向丢失session参数的问题 }这些元数据不是摆设。后续wt session list、wt session status、wt session merge命令都依赖它来决策。比如合并前要检查baseBranch和当前主干的关系如果主干已经前进很多就需要先做同步而不是直接merge。3.2 在Agent工作区中执行隔离命令创建完工作区之后最自然的操作是告诉Agent你的工作区在worktrunks/fix-login-redirect-bug去干活吧。但AI Agent通常不知道自己当前在哪个目录也不知道自己应该把代码改到哪里。所以Worktrunk提供了一个执行器让你可以直接在指定工作区内跑任意命令wt exec --name fix-login-redirect-bug -- cd ~/project/worktrunks/fix-login-redirect-bug npm test有人可能会问这个和直接cd到那个目录再执行有什么区别区别在于wt exec会自动注入当前工作区的环境变量比如WORKTRUNK_NAME、WORKTRUNK_BRANCH并且可以配置统一的预处理命令比如自动切换到对应分支、自动安装依赖。这意味着Agent不管之前在哪、无论用什么方式调用都能稳定地落在正确的目录、正确的分支上。这个能力在和Claude Code、Codex这类CLI工具配合的时候尤其有用。你可以把Worktrunk作为它们的工作区调度层每次启动会话前先为它创建或者复用工作区再让CLI在这个工作区里运行。这样多个Agent会话可以共享同一份代码库的基础设施但互相之间在文件层面完全隔离。3.3 查询会话状态一眼看清所有Agent在干什么当并行Agent任务跑到一半你肯定想知道每个任务到底改了什么、卡在哪。wt session status就是干这个的wt session status --name fix-login-redirect-bug输出示例Worktree: worktrunks/fix-login-redirect-bug Branch: wt/fix-login-redirect-bug Base: main Status: active Changed files: server/handler.go (M, 12 -3) web/src/LoginRedirect.tsx (M, 5 -0) server/session_store.go (A, 89 -0) Last active: 2 minutes agosession list则是所有会话的概览wt session list这个命令的价值在于它把看代码状态从挨个进目录git status变成了一步到位。特别是当你同时管理三五个Agent任务的时候这个概览能帮你快速判断哪些任务快完成了、哪些卡在某个文件上、哪些已经跑偏需要人工介入。3.4 安全合并冲突处理的一等公民合并是并行开发里最容易翻车的环节。原生git merge在遇到冲突时会把冲突标记留在文件里如果Agent继续读这些文件继续改很可能把冲突语法当成合法代码越改越乱。Worktrunk在这里做了一个专门的设计冲突即暂停绝不盲改。wt session merge --name fix-login-redirect-bug执行时Worktrunk会检查工作区是否有未提交的改动有的话自动提交附上Worktrunk: auto-commit before merge的提交信息切换到主分支执行git merge wt/fix-login-redirect-bug如果合并产生冲突自动停车输出冲突文件清单和当前状态不会强制继续如果合并成功会清理已经完成的工作区目录和元数据保持仓库整洁这里有一个我特别坚持的设计合并成功后默认删除对应工作区。很多工具会因为害怕误删而保留一堆过期目录结果整个仓库越来越乱。Worktrunk默认在合并成功后自动清理如果用户想保留现场可以用--keep参数显式保留。这个默认行为帮我把存量的工作区数量控制在一个极少的范围内仓库永远干净清爽。4. 实战两个Agent在同一仓库里同时干活的完整流程光说理论不直观我拿一个真实的场景来演示——让两个Agent分别实现两个完全独立的功能一个在服务端加搜索接口一个在前端加仪表盘页面。它们同时工作互不干扰。首先创建两个会话工作区# 创建搜索接口任务 wt session new --name add-search-endpoint --base main # 创建仪表盘页面任务 wt session new --name add-dashboard-page --base main此时wt session list的输出NAME STATUS BRANCH LAST ACTIVE add-search-endpoint active wt/add-search-endpoint just now add-dashboard-page active wt/add-dashboard-page just now接下来我给Agent ACodex下达指令让它负责搜索接口工作目录指定到worktrunks/add-search-endpointAgent BClaude Code负责仪表盘页面工作目录指定到worktrunks/add-dashboard-page。它们在各自的目录里读代码、写代码、跑测试互相看不到对方的改动。因为两个工作区是独立的git工作树它们的git status互不影响git add、git commit也不会串到对方分支里。有一件特别值得注意的事这两个Agent在跑测试时可能会同时操作同一份依赖目录。比如它们都需要执行npm install如果共享同一个node_modules理论上可能产生竞争。用Worktree之后每个工作区默认有自己的node_modules除非你用符号链接共享这虽然占了些磁盘空间但换来了彻底的隔离我认为非常值得。实际项目中如果仓库很大依赖很重可以考虑用wt session new --link-deps复用一份依赖目录减少磁盘占用。等到两个Agent都干完活了分别提交代码然后按顺序合并# 先合并搜索接口没有冲突 wt session merge --name add-search-endpoint # 再合并仪表盘页面也没有冲突 wt session merge --name add-dashboard-page两条命令跑完主分支上两个功能都齐了没有人工干预。但真实世界很少这么完美——接下来聊聊我踩过的坑。5. 踩过的坑路径漂移、依赖抢占、上下文丢失与竞态合并5.1 坑一Agent记忆了错误路径导致跨目录操作这是我遇到最隐蔽的一个问题。Agent A在worktrunks/add-search-endpoint目录里工作了一段时间它可能已经在上下文里把/Users/me/project/server/handler.go这个绝对路径记住了。这时候如果你不小心让它去另外一个任务里帮忙它可能会直接操作/Users/me/project/server/handler.go——注意这是主仓库的文件路径不是它自己工作区的路径。一旦Agent在新任务中按照记忆里的路径做了修改改动会落在主仓库的工作目录里而不是对应的worktree目录里。解决办法是在启动Agent会话时用Worktrunk把工作区路径写入Agent的系统提示或者环境变量并且反复强调所有操作只能在当前工作区内进行。如果发现Agent开始引用工作区之外的绝对路径马上叫停。这个坑的本质是Agent的上下文上下文不像人脑那样有清晰的目录边界感路径记忆很容易跨会话泄漏所以工具层一定要做好范围约束。5.2 坑二共享node_modules的竞态噩梦前面提到--link-deps可以节省磁盘。我一开始也这么干把两个工作区的node_modules软链到同一个目录。结果跑测试的时候Agent A在install新依赖的同时Agent B正好在启动测试结果模块解析失败、版本不一致的问题一个接一个冒出来。排查了半天才意识到是两个Agent在抢同一份依赖目录。最后的结论是并行Agent工作流中省磁盘不如省心。我宁可多花几个GB硬盘空间也不愿意半夜起来处理依赖目录损坏的问题。如果必须共享依赖也要保证在同一时刻只有一个Agent在跑install类的命令并且在这个Agent运行期间其他Agent的测试进程要能容忍依赖缺失或临时不完整。5.3 坑三Agent上下文丢了工作区烂尾有一次一个Agent任务干到一半会话意外中断了。重新开一个会话让它继续干那个任务它却完全不记得之前改了什么、改到哪了。工作区里躺着一堆半成品修改既不能合并也不敢删除。这个问题的根源是Worktree只是隔离了文件并没有同步Agent的思维过程。文件里只是一些不完整的改动没有任何记录说明为什么要这么改下一步打算做什么。后来我给Worktrunk加了一个功能每次Agent提交时强制要求附带一份结构化的任务说明文件比如WORKTRUNK.md记录当前进度、待办、决策原因。这样就算会话中断新的会话读到这份文件就能快速恢复上下文。这让我意识到并行Agent工作流的真正难点往往不在技术而在于状态流转的完整性和可观测性。文件只是最终产物过程中的决策、尝试、回退都值得被记录工具要做的不只是隔离还包括串联记忆。5.4 坑四合并顺序导致的连锁冲突两个Agent修改了同一个文件的不同部分分开看各自都能合并但先合A再合B就会产生冲突。这种问题在并行开发里非常常见。Worktrunk目前的策略是合并前先检查目标工作区与当前主干的差异范围如果发现两个工作区改动了相同的文件但改动的行不重叠允许顺序合并一旦发现重叠在合并第二个任务前就主动提示风险而不是闷头merge然后抛出一堆冲突。这个检查基于git merge-tree的预演机制不需要真正改动工作区。实际用下来预警的效果比事后处理冲突好得多。因为大多数情况下遇到重叠改动时我会先停下第二个任务等第一个任务合并完再让Agent从最新主干重新拉取代码继续改。这绕开了两个人同时改同一行的物理约束也避免了Agent在合并冲突中迷失。6. 接下来的扩展方向从单机并行到仓库级Agent编排Worktrunk目前解决的是单台机器上多个Agent会话的工作区隔离与生命周期管理。但我也注意到如果需要编排的Agent不止一两个而是十几二十个分布在不同机器上的任务单靠CLI在单仓库上创建Worktree还不够还需要远程工作区协调让Worktrunk支持把某个Worktree推送到远程仓库并由远端执行实现跨机器的任务分配Agent能力注入在创建会话时工作区元数据可以转换成Agent可读的上下文文件让新的会话一启动就知道当前任务的全貌队列化合并把待合并任务做成一个有优先级的队列Worktrunk自动处理合理顺序减少人工干预按照目前社区对AI编程的探索速度我相信未来几个月内并行Agent协作会从人的玩具变成团队标配。而Git Worktree这类成熟可靠的原生能力恰恰是最适合承载这种并行的底座。做Worktrunk这段时间我最大的体会是工具做得再花哨也不如把一件基础的事情做到极致。隔离、同步、合并、回收这四件事做好并行Agent工作流运转起来就顺了。如果你也在折腾多Agent并行编程可以试着从git worktree这个基础能力开始思考自己的工作流需要什么样的状态管理和自动化——也许你会有比我更好用的设计。
