把三个AI编程Agent同时放出去改一个仓库听起来很美真正跑起来之后最先崩溃的往往不是模型而是Git。我最近把一套叫 Worktrunk 的 CLI 工具接到了自己的并行 AI Agent 工作流里顺手把之前乱成一锅粥的多分支开发流程彻底理顺了。这篇东西我想把 Worktrunk 的设计思路、实际用法、以及我在多 Agent 并行场景下踩过的坑完整梳理一遍给同样在用 Codex CLI、Claude Code 这类工具的开发者一个可以直接抄作业的参考方案。1. 并行AI Agent时代为什么Git Worktree突然成了刚需1.1 多Agent并行不是简单的“多开几个终端”2025年之后AI编程Agent工具已经多到数不过来了。Codex CLI、Claude Code、Gemini CLI、Trae CLI加上各种Harness封装每个模型背后几乎都有一套能自己读代码、改文件、跑测试的命令行工具。于是很自然会出现一个操作同一个仓库开三个终端分别让Claude改登录模块让Codex改支付回调让Gemini改管理后台。听起来是“并行开发”实际上互相踩脚踩得厉害。我最早就是这么干的结果Claude在feature/auth分支上改到一半我切到feature/payment分支让Codex继续写。等Codex提交完我再切回feature/auth的时候工作区里的文件全变了Claude之前记录的上下文全部失效。更离谱的一次某个Agent把另一个分支已经提交的文件当成了自己的工作成果在代码里引用了根本不存在的函数最后合并时冲突叠着冲突光解决冲突就花了一个下午。问题本质不是Agent能力不行而是“一个工作区同时服务多个任务”这个模型本身是串行的。工作区永远只能显示一个分支的内容Agent的上下文却要跨越多个分支去记忆状态。模型上下文窗口再大也扛不住这种来回切换造成的语义撕裂。1.2 传统checkout/switch模型的硬伤深入看传统git checkout/git switch切换分支的模式在并行Agent场景下有四个硬伤工作区共享导致状态污染。所有Agent共用同一份工作目录A Agent生成的临时文件、缓存、未提交修改对B Agent来说都是不可控变量。AI Agent不像人那样会刻意忽略这些文件它很可能在git status里看到一堆不属于自己的变更然后做出错误判断。上下文断裂。切换分支后文件内容整体变化Agent需要对当前分支重新建立认知。代码量一大Agent经常会把“其他分支进入工作区的内容”误解为“当前分支应该有的内容”接着基于错误前提生成代码。缓存和依赖反复失效。切分支意味着node_modules里的部分编译产物可能需要重建Python的__pycache__、TypeScript的.tsbuildinfo全部失效。每次切换都是时间成本并行Agent的数量一多这个损失会被放大。分支被占用时无法切换。工作区有未提交修改时切换分支经常报Your local changes would be overwritten by checkout。强行stash或者commit又会把不同任务的中间状态混在一起。如果多个功能的进度等于最慢的那个任务那串行checkout就注定只能一次跑一个Agent。想让两个Agent真正同时干活必须给每个任务一个独立工作区。1.3 Worktrunk解决的核心问题Worktrunk的定位很直接一个面向并行AI Agent工作流的Git Worktree管理CLI。它不试图替代Git也不试图替代Agent工具而是把git worktree从一条“偶尔用一下”的高级命令变成一套可以编排AI任务的工作区资源管理方案。具体来说Worktrunk解决三件事工作区生命周期管理。创建、列出、删除、整理worktree全部通过wt task系列子命令完成不用再手写一长串git worktree add参数。任务与分支、目录、Agent的绑定关系。每个worktree对应一条任务记录记录里有分支名、工作区路径、关联的Agent、创建时间和状态。想查“现在哪些任务还活着、各自在哪个目录”一条命令搞定。合并与清理的标准化。任务完成后Worktrunk负责把feature工作区合并回目标分支并且把已经合并或者废弃的worktree清理干净避免仓库散落一堆没人记得的目录。2. Git Worktree机制拆解它到底是怎么工作的2.1 一个仓库多份可同时操作的工作目录要理解Worktrunk必须先理解git worktree本身。网上很多资料把worktree说成“多个工作目录”这句话对但不完整。一个正常克隆下来的Git仓库通常只有一份工作目录、一份索引、一个HEAD指针都指向当前分支。用git worktree add之后仓库会多出第二份工作目录、第二份索引、第二个HEAD它们可以指向完全不同的分支。所有工作区共享同一个.git目录也就是共享同一套对象数据库、引用、远程配置。可以用一个生活类比普通git checkout就像一个人站在一间办公室里反复换桌面上的文件git worktree则是给这间办公室开了好几扇门每扇门进去看到的是完全不同的文件摆放方式但背后用的都是同一个档案柜。档案柜里的资料是共享的桌面上摆什么各门各户互不影响。对于AI Agent来说这个机制的杀手级价值在于每个Agent可以拥有一个完全独立、干净的工作目录里面只有当前任务对应的那个分支的文件。Agent不会看到其他任务的分支内容也不会被其他Agent的临时修改干扰。2.2 add/list/remove/prune四条命令的本质Git原生的worktree核心命令有四个Worktrunk底层都是围绕它们做封装命令作用底层要点git worktree add path branch在指定路径新建工作区并检出分支会在.git/worktrees/下注册该工作区元数据同时锁定对应分支git worktree list列出所有工作区展示路径、分支、提交点是排查占用关系的第一入口git worktree remove path删除一个工作区要求工作区必须是干净的不干净会拒绝删除git worktree prune清理失效工作区元数据手动删除工作区目录后用它清理.git/worktrees/里的残留条目这几个命令单独用不难难在“和任务关联起来”。比如团队有20个worktree每个对应一个Agent任务想找“哪个目录属于feature/payment-webhook”就得先跑git worktree list再肉眼匹配。Worktrunk的价值就在这里它给每个worktree加上了任务语义。2.3 并行工作区之间共享什么、不共享什么很多人在多worktree并行时会困惑我在A工作区改了个文件B工作区为什么看不到这是因为worktree之间并不是共享工作区内容的。具体来说多个worktree共享这些内容对象数据库所有提交和历史、分支引用和标签引用、仓库配置文件.git/config、默认共享的钩子脚本。不共享的内容包括工作目录里的实际文件、暂存区索引、HEAD指针、部分per-worktree引用、以及git status看到的未提交状态。一个容易混淆的场景A工作区提交了一个文件B工作区不会自动出现这个文件。因为提交只是把对象写进了共享的对象库B工作区的HEAD没有指向这个提交自然也就不会在工作目录里展开。只有当你在B工作区执行git merge或者git rebase拉取A的提交后文件才会出现。理解这个“共享仓库、隔离工作区”的模型再去看Worktrunk的合并逻辑就会清晰很多所有Agent提交的内容最终都要经过merge才能进入彼此的视野Worktrunk做的就是把合并时机和合并方式管起来。3. Worktrunk的命令设计与实际用法3.1 初始化与接入现有项目第一次使用Worktrunk时在项目根目录执行wt init这个命令会做两件事检查当前目录是否是一个合法的Git仓库然后读取默认分支通常是main或master和远程仓库信息在.git/wt/目录下建立一个任务状态库。为什么把状态存在.git/wt/而不是项目根目录因为任务状态是每个开发者本地的个人数据不应该混进业务代码库里。如果放在项目根目录等于要求所有协作者都装Worktrunk还会污染代码提交记录。放在.git/下Git天然会忽略它其他开发者没装这个工具也不受影响。初始化之后可以用wt config查看当前配置。我习惯把worktree的根目录统一放到仓库目录之外比如克隆目录是~/projects/myapp那么worktree都放到~/projects/myapp-worktrees/下。这样主目录和任务目录互不干扰git status也不会因为子目录里的worktree而变慢。3.2 创建任务工作区创建一条AI Agent任务工作区的命令是这样wt task create --name feature/payment-webhook --base main --agent claude各参数含义--name是分支名和任务名同时会作为工作区目录名的来源--base指定基于哪个分支创建--agent记录这次任务交给哪个Agent信息会写进任务状态方便后续按Agent维度筛选。执行这条命令后Worktrunk内部会按顺序做几件事执行git fetch --prune确保本地分支不是落后于远程的陈旧状态。基于--base创建并切换到新分支。在配置的工作区根目录下查询对应的worktree路径执行git worktree add ../myapp-worktrees/payment-webhook -b feature/payment-webhook main。在任务状态库写入一条记录任务名、分支、工作区路径、Agent、状态为active、创建时间。出于安全考虑如果分支已经存在Worktrunk会拒绝创建避免误操作覆盖已有工作。这个限制在多人协作时很有用防止两个开发者不小心往同一个分支上开工作区。3.3 查看任务状态开发过程中最常用的命令是wt task list。输出会是类似这样的表格任务名分支工作区路径Agent状态最后活动payment-webhookfeature/payment-webhook../myapp-worktrees/payment-webhookclaudeactive5分钟前auth-ssofeature/auth-sso../myapp-worktrees/auth-ssocodexactive2小时前admin-dashboardfeature/admin-dashboard../myapp-worktrees/admin-dashboardgeminiactive昨天这个表格解决了一个很实际的痛点当你开了五六个worktree每个目录长得很像时git worktree list只能告诉你“某个路径对应某个分支”而wt task list会把“这条任务归谁管、Active多久了、该不该清理”全部讲清楚。Worktrunk还支持wt task list --agent claude和wt task list --json。--json输出特别适合CI脚本或者Agent自己调用因为AI Agent对结构化文本的解析能力远强于对纯表格的解析。3.4 任务完成后的合并与清理Agent在对应的worktree里完成开发、提交、甚至已经推送到远程后就可以走收尾流程了。Worktrunk提供了两条命令wt task merge --name feature/payment-webhook --into main wt task prune --name feature/payment-webhookmerge的核心逻辑是先检查目标分支main和任务分支的合并基线然后执行git merge --no-ff feature/payment-webhook。之所以强制--no-ff而不是快进合并是为了保留一条清晰的任务合并记录。对于AI Agent开发来说可追溯性非常重要。将来想回看“这个支付Webhook是哪次合并进来的”一眼就能定位到合并提交。prune的作用是删除该任务对应的worktree。在删除之前Worktrunk会做几项检查工作区是否有未提交的修改、是否还有未合并的提交、当前HEAD有没有停在非活动分支上。全部干净才会真正执行git worktree remove。如果合并完成但prune时发现工作区里有未提交修改Worktrunk会给出具体文件列表而不是强行删除。这个设计很关键毕竟AI Agent可能会留下一些没写完的调试代码直接删除会损失信息。3.5 其他命令switch、sync、archive除了上面几个主干命令Worktrunk还提供几个适合日常流转的子命令wt task switch name在已登记的worktree之间切换。本质上是让开发者快速定位并进入对应目录避免每次都要输入一长串绝对路径。wt task sync name把任务分支重新基于最新的base分支同步一次。用于任务拖了很久、base已经前进了很多需要先对齐的情况。wt task archive name把已完成且不再活跃的任务归档。归档后不会再出现在默认的list输出里但任务状态依然保留方便审计。这几个命令不是必须用的但在复杂的多任务并行中能显著降低手动操作的频率。4. 实战用Worktrunk编排三个AI Agent同时开发4.1 场景设定与任务拆分直观感受Worktrunk的价值最好配合一个具体场景。假设有一个中等规模的Web应用现在需要同时推进三个功能登录模块改造成SSO单点登录。支付回调增加Webhook验签逻辑。管理后台增加用户列表导出功能。三个功能之间没有强耦合适合并行。传统的串行做法是三个任务排队每个任务都从main拉分支、开发、合并、清理再开始下一个。用Worktrunk可以一次性把三个任务的工作区全部创建出来让三个Agent在各自独立的空间里同时跑。4.2 从克隆到三个工作区落地的完整命令完整操作链路如下git clone gitgithub.com:example/myapp.git cd myapp wt init wt config set worktree_root ../myapp-worktrees wt task create --name feature/auth-sso --base main --agent claude wt task create --name feature/payment-webhook --base main --agent codex wt task create --name feature/admin-export --base main --agent gemini执行完这三条task create之后仓库目录结构大概是这样的~/projects/ ├── myapp/ # 主工作区停在 main 分支 └── myapp-worktrees/ ├── auth-sso/ # Claude 的工作区检出 feature/auth-sso ├── payment-webhook/ # Codex 的工作区检出 feature/payment-webhook └── admin-export/ # Gemini 的工作区检出 feature/admin-export每个Agent都能通过自己的终端进入对应目录直接开始工作。主工作区始终保持干净停留在main上随时可以跑集成测试或者看CI状态。4.3 如何给每个Agent限定边界工作区创建之后关键的一步是给Agent设定明确的边界。如果只让Agent“开始开发”它很可能会在当前目录里乱跑尤其当你同时开了几个工作区Agent的上下文里又混入了其他目录的路径时很容易出现“在错误的仓库里改代码”的惨案。我给每个Agent的初始提示词里会固定包含这段约束你正在开发的项目位于/absolute/path/to/myapp-worktrees/payment-webhook 请始终在这个目录下执行所有操作只修改这个目录里的文件。 不要搜索、读取或修改 /absolute/path/to/myapp-worktrees/ 下的其他子目录。 当前分支是 feature/payment-webhook所有提交都提交到这个分支。 开始前先执行 git status 确认工作区状态。这样配置之后Agent的活动范围被限定在独立工作区内。即使它同时在其他目录看到了一些信息提示词也会强制它回到自己负责的区域。实测下来这个Bug的概率大幅降低。使用wt task list还能在Agent启动前快速确认工作区路径避免把绝对路径写错。4.4 集成验证与冲突处理三个Agent开发完成后收尾阶段的合并顺序是有讲究的。我习惯先让改动范围最独立、最不容易产生冲突的任务先合并。例如先合并admin-export再合并payment-webhook最后合并涉及公共认证逻辑的auth-sso。每个任务合并的流程是wt task merge --name feature/admin-export --into main wt task prune --name feature/admin-export如果合并过程中出现冲突Worktrunk会停留在冲突状态并把冲突文件信息打印出来。这个状态下Worktrunk不会擅自做任何合并策略需要人工介入。我的处理方式是先让本地的Agent来处理或者如果冲突很小就手动改掉。这里有一个值得强调的操作不要把三个分支的冲突一次全解决完。每合并一个分支跑一遍测试确认main仍然是健康的再继续合并下一个。并行开发的任务之间可能存在隐藏依赖——比如支付模块改了用户模型认证模块也改了用户模型两个单独合并都没问题但第三个一合并就爆冲突。分阶段合并可以把问题隔离到最早出现的节点。5. 使用Worktrunk和Git Worktree容易踩的坑5.1 分支被占用的高频报错git worktree机制里有一个硬性限制同一个分支在同一时间只能被一个worktree检出。如果你在三个终端里用普通方式git checkout feature/auth-sso而Worktrunk已经把feature/auth-sso绑定到了../myapp-worktrees/auth-sso那么第二个工作区会直接报错fatal: feature/auth-sso is already checked out at ../myapp-worktrees/auth-sso遇到这个报错不要慌。先跑wt task list确认这个分支被哪个任务占用了再决定是要wt task switch进入那个工作区还是等任务结束后prune掉。千万不要用git worktree remove --force去强删很容易把未同步的提交搞丢。5.2 看不到其他分支文件的误解并行使用多个worktree时最常见的一种困惑是“我明明在另一个工作区提交了代码这边怎么没有”。原因其实很简单每个worktree的工作目录只对应一个分支你在这个目录里看到的永远只是当前分支的内容。另一个分支的改动必须通过merge或者rebase才会出现。这个误解在AI Agent之间可能造成连锁反应。比如Agent A在feature/auth-sso里修改了api/client.tsAgent B在feature/payment-webhook里运行测试发现缺少Agent A定义的接口可能会擅自把api/client.ts重新写一份造成重复劳动。解决方式是给每个Agent明确提示你的工作区里看不到的内容不代表不存在只代表还没有合并到当前分支。需要依赖就用git fetch origin feature/auth-sso拉取后查看而不是在本地重新实现一遍。5.3 未提交变更会卡住删除wt task prune执行时如果目标worktree里有未提交的修改会直接拒绝删除。这是保护机制但在并行Agent场景下这个提示会频繁出现因为Agent经常会在工作区里留下各种临时文件、调试输出甚至node_modules/.cache里的内容。我的建议是不要一看到报错就--force。先看一眼git status里的文件到底是什么如果是Agent生成的临时调试文件可以直接清理后删除如果是任务相关的半成品代码说明任务其实还没完成应该把它提交到分支上继续推进而不是急着清理。为了一点磁盘空间把未提交的工作丢掉成本太高。5.4 磁盘占用翻倍与缓存共享worktree共享的是Git对象库不共享工作目录。这意味着node_modules、vendor、dist这些依赖和构建目录在每个worktree里都会有一份独立的副本。如果项目依赖特别重三个worktree一开磁盘可能直接多占几GB到几十GB。针对这个问题有几个实操优化手段使用pnpm这类支持内容寻址存储的包管理器它的全局store天然支持多个项目共享依赖文件硬链接到每个工作区磁盘占用会大幅下降。对纯前端项目把node_modules加入.git/info/exclude避免git status在多个worktree里扫描大量无关注文件而变慢。如果项目里有大型构建产物放在主工作区统一构建或者用CI构建不要在每个worktree里各跑一遍。定期wt task list检查有没有长期闲置的任务该prune就prune别让废弃工作区一直占着磁盘。5.5 路径长度、IDE索引和钩子脚本问题最后说几个零碎但真实的问题。路径长度。在Windows上worktree如果放在路径很深的目录里加上项目内部结构再嵌套几层很容易触碰到260字符的路径上限。解决办法是把worktree根目录放在浅路径下比如C:\wt\这种级别或者在系统里开启长路径支持。IDE索引。VS Code这类编辑器如果不加限制会同时索引所有已经打开的worktree目录CPU和内存消耗明显上升。建议只打开当前正在操作的worktree目录不要把所有worktree都拖进同一个工作区窗口。钩子脚本。Git hooks默认是所有worktree共享的。如果你的仓库配置了比较重的post-checkout或者post-merge钩子每个worktree的创建和合并都会触发一次。钩子脚本如果假设“当前目录就是仓库根目录”在worktree下可能会出错。多检查一次钩子里的路径假设避免在多个worktree里反复踩同一个坑。6. 配置优化与进阶玩法6.1 通过配置文件固化团队约定Worktrunk支持通过配置文件固化项目级约定。在项目根目录放一个.worktrunkrc内容类似worktree_root: ../myapp-worktrees default_base: main agents: claude: claude-code codex: codex gemini: gemini-cli hooks: after_create: git fetch --prune before_merge: npm run lintdefault_base和worktree_root的作用前面已经说过。agents字段把Agent名称和启动命令绑定起来这样团队里每个人用wt task create --agent claude时拿到的都是同一套命令约定。hooks字段可以对Worktrunk的事件做扩展比如在创建worktree之后自动fetch或者在合并之前跑一遍lint检查。配置文件的另一个好处是可以提交到仓库里成为团队规范的一部分。新同事加入后只要执行wt init就能自动读取这些约定不用再靠口头传递“咱们的worktree都放在上级目录”这种信息。6.2 把Worktrunk接进CI/CDWorktrunk不只是本地工具也可以接进CI/CD流程。一个典型的用例是开发者在本地用Worktrunk开了一堆任务工作区推送到远程后CI里用wt task list --json读取所有任务的合并状态然后统一执行验证。比如用GitHub Actions做一套“所有feature分支合并前自动检查”的流程- name: List active tasks run: wt task list --json tasks.json - name: Run checks on each task branch run: | for task in $(jq -r .[] | .name tasks.json); do git checkout $task npm run lint npm test done更激进的用法是做完wt task merge之后直接在CI里跑wt task prune把已经合并的worktree从仓库里清理掉。这样整个“创建任务、并行开发、合并、清理”的闭环完全自动化。但需要注意的是CI里的Worktrunk对worktree的路径配置、以及执行权限都应该和本地环境隔离好避免CI机上一次跑多个worktree时相互干扰。6.3 命名规范与定期GC用了Worktrunk一段时间之后我最大的体会是如果没有命名规范所有优秀的工具都会被打回原形。目前我执行的规范是分支名统一用feature/短描述格式短描述统一用连字符分隔不超过35个字符比如feature/payment-webhook-verify。一个工作区对应一个Agent任务禁止把两个无关功能塞进同一个工作区。每天下班前跑一次wt task list看一眼有没有已经合完但没清理的任务。每周跑一次wt task prune把所有已经合并到主分支的worktree清理掉。这套规范配合Worktrunk的archive功能可以让仓库长期保持整洁。也建议在团队内部约定只有main和正在活跃开发的feature分支会出现在wt task list里其他归档任务一律隐藏。6.4 下一步从工作区管理走向Agent编排Worktrunk目前做的是工作区管理但我更看好它往Agent编排方向演进的潜力。现在AI Agent的能力越来越强底层已经可以通过MCP协议调用各种工具。如果Worktrunk暴露一套MCP接口让Agent自己通过工具调用来申请工作区、提交变更、触发合并整个开发流程就真正闭环了。到时候Agent自动执行wt task create申请一块独立空间改完代码自己wt task merge再wt task prune把工作区清理掉——人只负责最终审查合并结果。这听起来很未来但技术栈上已经没有障碍了缺的只是像Worktrunk这样把Git操作封装成语义化、可编程接口的工具层。我个人在实际使用中最直接的体会是跑通这套流程之后我再也不用手工切分支了。更意外的是并行Agent带来的最大收益不是节省那几秒切换时间而是上下文隔离带来的确定性。每个Agent看到的都是一个干净、稳定、只属于自己的工作区它对仓库状态的理解就不会再有偏差代码质量和任务完成度都明显提升。如果你正在折腾多Agent并行开发建议先别急着上各种花哨的编排框架老老实实把Worktree管理做好收益会更直接。
Git Worktree管理实战：用Worktrunk编排多Agent并行开发
把三个AI编程Agent同时放出去改一个仓库听起来很美真正跑起来之后最先崩溃的往往不是模型而是Git。我最近把一套叫 Worktrunk 的 CLI 工具接到了自己的并行 AI Agent 工作流里顺手把之前乱成一锅粥的多分支开发流程彻底理顺了。这篇东西我想把 Worktrunk 的设计思路、实际用法、以及我在多 Agent 并行场景下踩过的坑完整梳理一遍给同样在用 Codex CLI、Claude Code 这类工具的开发者一个可以直接抄作业的参考方案。1. 并行AI Agent时代为什么Git Worktree突然成了刚需1.1 多Agent并行不是简单的“多开几个终端”2025年之后AI编程Agent工具已经多到数不过来了。Codex CLI、Claude Code、Gemini CLI、Trae CLI加上各种Harness封装每个模型背后几乎都有一套能自己读代码、改文件、跑测试的命令行工具。于是很自然会出现一个操作同一个仓库开三个终端分别让Claude改登录模块让Codex改支付回调让Gemini改管理后台。听起来是“并行开发”实际上互相踩脚踩得厉害。我最早就是这么干的结果Claude在feature/auth分支上改到一半我切到feature/payment分支让Codex继续写。等Codex提交完我再切回feature/auth的时候工作区里的文件全变了Claude之前记录的上下文全部失效。更离谱的一次某个Agent把另一个分支已经提交的文件当成了自己的工作成果在代码里引用了根本不存在的函数最后合并时冲突叠着冲突光解决冲突就花了一个下午。问题本质不是Agent能力不行而是“一个工作区同时服务多个任务”这个模型本身是串行的。工作区永远只能显示一个分支的内容Agent的上下文却要跨越多个分支去记忆状态。模型上下文窗口再大也扛不住这种来回切换造成的语义撕裂。1.2 传统checkout/switch模型的硬伤深入看传统git checkout/git switch切换分支的模式在并行Agent场景下有四个硬伤工作区共享导致状态污染。所有Agent共用同一份工作目录A Agent生成的临时文件、缓存、未提交修改对B Agent来说都是不可控变量。AI Agent不像人那样会刻意忽略这些文件它很可能在git status里看到一堆不属于自己的变更然后做出错误判断。上下文断裂。切换分支后文件内容整体变化Agent需要对当前分支重新建立认知。代码量一大Agent经常会把“其他分支进入工作区的内容”误解为“当前分支应该有的内容”接着基于错误前提生成代码。缓存和依赖反复失效。切分支意味着node_modules里的部分编译产物可能需要重建Python的__pycache__、TypeScript的.tsbuildinfo全部失效。每次切换都是时间成本并行Agent的数量一多这个损失会被放大。分支被占用时无法切换。工作区有未提交修改时切换分支经常报Your local changes would be overwritten by checkout。强行stash或者commit又会把不同任务的中间状态混在一起。如果多个功能的进度等于最慢的那个任务那串行checkout就注定只能一次跑一个Agent。想让两个Agent真正同时干活必须给每个任务一个独立工作区。1.3 Worktrunk解决的核心问题Worktrunk的定位很直接一个面向并行AI Agent工作流的Git Worktree管理CLI。它不试图替代Git也不试图替代Agent工具而是把git worktree从一条“偶尔用一下”的高级命令变成一套可以编排AI任务的工作区资源管理方案。具体来说Worktrunk解决三件事工作区生命周期管理。创建、列出、删除、整理worktree全部通过wt task系列子命令完成不用再手写一长串git worktree add参数。任务与分支、目录、Agent的绑定关系。每个worktree对应一条任务记录记录里有分支名、工作区路径、关联的Agent、创建时间和状态。想查“现在哪些任务还活着、各自在哪个目录”一条命令搞定。合并与清理的标准化。任务完成后Worktrunk负责把feature工作区合并回目标分支并且把已经合并或者废弃的worktree清理干净避免仓库散落一堆没人记得的目录。2. Git Worktree机制拆解它到底是怎么工作的2.1 一个仓库多份可同时操作的工作目录要理解Worktrunk必须先理解git worktree本身。网上很多资料把worktree说成“多个工作目录”这句话对但不完整。一个正常克隆下来的Git仓库通常只有一份工作目录、一份索引、一个HEAD指针都指向当前分支。用git worktree add之后仓库会多出第二份工作目录、第二份索引、第二个HEAD它们可以指向完全不同的分支。所有工作区共享同一个.git目录也就是共享同一套对象数据库、引用、远程配置。可以用一个生活类比普通git checkout就像一个人站在一间办公室里反复换桌面上的文件git worktree则是给这间办公室开了好几扇门每扇门进去看到的是完全不同的文件摆放方式但背后用的都是同一个档案柜。档案柜里的资料是共享的桌面上摆什么各门各户互不影响。对于AI Agent来说这个机制的杀手级价值在于每个Agent可以拥有一个完全独立、干净的工作目录里面只有当前任务对应的那个分支的文件。Agent不会看到其他任务的分支内容也不会被其他Agent的临时修改干扰。2.2 add/list/remove/prune四条命令的本质Git原生的worktree核心命令有四个Worktrunk底层都是围绕它们做封装命令作用底层要点git worktree add path branch在指定路径新建工作区并检出分支会在.git/worktrees/下注册该工作区元数据同时锁定对应分支git worktree list列出所有工作区展示路径、分支、提交点是排查占用关系的第一入口git worktree remove path删除一个工作区要求工作区必须是干净的不干净会拒绝删除git worktree prune清理失效工作区元数据手动删除工作区目录后用它清理.git/worktrees/里的残留条目这几个命令单独用不难难在“和任务关联起来”。比如团队有20个worktree每个对应一个Agent任务想找“哪个目录属于feature/payment-webhook”就得先跑git worktree list再肉眼匹配。Worktrunk的价值就在这里它给每个worktree加上了任务语义。2.3 并行工作区之间共享什么、不共享什么很多人在多worktree并行时会困惑我在A工作区改了个文件B工作区为什么看不到这是因为worktree之间并不是共享工作区内容的。具体来说多个worktree共享这些内容对象数据库所有提交和历史、分支引用和标签引用、仓库配置文件.git/config、默认共享的钩子脚本。不共享的内容包括工作目录里的实际文件、暂存区索引、HEAD指针、部分per-worktree引用、以及git status看到的未提交状态。一个容易混淆的场景A工作区提交了一个文件B工作区不会自动出现这个文件。因为提交只是把对象写进了共享的对象库B工作区的HEAD没有指向这个提交自然也就不会在工作目录里展开。只有当你在B工作区执行git merge或者git rebase拉取A的提交后文件才会出现。理解这个“共享仓库、隔离工作区”的模型再去看Worktrunk的合并逻辑就会清晰很多所有Agent提交的内容最终都要经过merge才能进入彼此的视野Worktrunk做的就是把合并时机和合并方式管起来。3. Worktrunk的命令设计与实际用法3.1 初始化与接入现有项目第一次使用Worktrunk时在项目根目录执行wt init这个命令会做两件事检查当前目录是否是一个合法的Git仓库然后读取默认分支通常是main或master和远程仓库信息在.git/wt/目录下建立一个任务状态库。为什么把状态存在.git/wt/而不是项目根目录因为任务状态是每个开发者本地的个人数据不应该混进业务代码库里。如果放在项目根目录等于要求所有协作者都装Worktrunk还会污染代码提交记录。放在.git/下Git天然会忽略它其他开发者没装这个工具也不受影响。初始化之后可以用wt config查看当前配置。我习惯把worktree的根目录统一放到仓库目录之外比如克隆目录是~/projects/myapp那么worktree都放到~/projects/myapp-worktrees/下。这样主目录和任务目录互不干扰git status也不会因为子目录里的worktree而变慢。3.2 创建任务工作区创建一条AI Agent任务工作区的命令是这样wt task create --name feature/payment-webhook --base main --agent claude各参数含义--name是分支名和任务名同时会作为工作区目录名的来源--base指定基于哪个分支创建--agent记录这次任务交给哪个Agent信息会写进任务状态方便后续按Agent维度筛选。执行这条命令后Worktrunk内部会按顺序做几件事执行git fetch --prune确保本地分支不是落后于远程的陈旧状态。基于--base创建并切换到新分支。在配置的工作区根目录下查询对应的worktree路径执行git worktree add ../myapp-worktrees/payment-webhook -b feature/payment-webhook main。在任务状态库写入一条记录任务名、分支、工作区路径、Agent、状态为active、创建时间。出于安全考虑如果分支已经存在Worktrunk会拒绝创建避免误操作覆盖已有工作。这个限制在多人协作时很有用防止两个开发者不小心往同一个分支上开工作区。3.3 查看任务状态开发过程中最常用的命令是wt task list。输出会是类似这样的表格任务名分支工作区路径Agent状态最后活动payment-webhookfeature/payment-webhook../myapp-worktrees/payment-webhookclaudeactive5分钟前auth-ssofeature/auth-sso../myapp-worktrees/auth-ssocodexactive2小时前admin-dashboardfeature/admin-dashboard../myapp-worktrees/admin-dashboardgeminiactive昨天这个表格解决了一个很实际的痛点当你开了五六个worktree每个目录长得很像时git worktree list只能告诉你“某个路径对应某个分支”而wt task list会把“这条任务归谁管、Active多久了、该不该清理”全部讲清楚。Worktrunk还支持wt task list --agent claude和wt task list --json。--json输出特别适合CI脚本或者Agent自己调用因为AI Agent对结构化文本的解析能力远强于对纯表格的解析。3.4 任务完成后的合并与清理Agent在对应的worktree里完成开发、提交、甚至已经推送到远程后就可以走收尾流程了。Worktrunk提供了两条命令wt task merge --name feature/payment-webhook --into main wt task prune --name feature/payment-webhookmerge的核心逻辑是先检查目标分支main和任务分支的合并基线然后执行git merge --no-ff feature/payment-webhook。之所以强制--no-ff而不是快进合并是为了保留一条清晰的任务合并记录。对于AI Agent开发来说可追溯性非常重要。将来想回看“这个支付Webhook是哪次合并进来的”一眼就能定位到合并提交。prune的作用是删除该任务对应的worktree。在删除之前Worktrunk会做几项检查工作区是否有未提交的修改、是否还有未合并的提交、当前HEAD有没有停在非活动分支上。全部干净才会真正执行git worktree remove。如果合并完成但prune时发现工作区里有未提交修改Worktrunk会给出具体文件列表而不是强行删除。这个设计很关键毕竟AI Agent可能会留下一些没写完的调试代码直接删除会损失信息。3.5 其他命令switch、sync、archive除了上面几个主干命令Worktrunk还提供几个适合日常流转的子命令wt task switch name在已登记的worktree之间切换。本质上是让开发者快速定位并进入对应目录避免每次都要输入一长串绝对路径。wt task sync name把任务分支重新基于最新的base分支同步一次。用于任务拖了很久、base已经前进了很多需要先对齐的情况。wt task archive name把已完成且不再活跃的任务归档。归档后不会再出现在默认的list输出里但任务状态依然保留方便审计。这几个命令不是必须用的但在复杂的多任务并行中能显著降低手动操作的频率。4. 实战用Worktrunk编排三个AI Agent同时开发4.1 场景设定与任务拆分直观感受Worktrunk的价值最好配合一个具体场景。假设有一个中等规模的Web应用现在需要同时推进三个功能登录模块改造成SSO单点登录。支付回调增加Webhook验签逻辑。管理后台增加用户列表导出功能。三个功能之间没有强耦合适合并行。传统的串行做法是三个任务排队每个任务都从main拉分支、开发、合并、清理再开始下一个。用Worktrunk可以一次性把三个任务的工作区全部创建出来让三个Agent在各自独立的空间里同时跑。4.2 从克隆到三个工作区落地的完整命令完整操作链路如下git clone gitgithub.com:example/myapp.git cd myapp wt init wt config set worktree_root ../myapp-worktrees wt task create --name feature/auth-sso --base main --agent claude wt task create --name feature/payment-webhook --base main --agent codex wt task create --name feature/admin-export --base main --agent gemini执行完这三条task create之后仓库目录结构大概是这样的~/projects/ ├── myapp/ # 主工作区停在 main 分支 └── myapp-worktrees/ ├── auth-sso/ # Claude 的工作区检出 feature/auth-sso ├── payment-webhook/ # Codex 的工作区检出 feature/payment-webhook └── admin-export/ # Gemini 的工作区检出 feature/admin-export每个Agent都能通过自己的终端进入对应目录直接开始工作。主工作区始终保持干净停留在main上随时可以跑集成测试或者看CI状态。4.3 如何给每个Agent限定边界工作区创建之后关键的一步是给Agent设定明确的边界。如果只让Agent“开始开发”它很可能会在当前目录里乱跑尤其当你同时开了几个工作区Agent的上下文里又混入了其他目录的路径时很容易出现“在错误的仓库里改代码”的惨案。我给每个Agent的初始提示词里会固定包含这段约束你正在开发的项目位于/absolute/path/to/myapp-worktrees/payment-webhook 请始终在这个目录下执行所有操作只修改这个目录里的文件。 不要搜索、读取或修改 /absolute/path/to/myapp-worktrees/ 下的其他子目录。 当前分支是 feature/payment-webhook所有提交都提交到这个分支。 开始前先执行 git status 确认工作区状态。这样配置之后Agent的活动范围被限定在独立工作区内。即使它同时在其他目录看到了一些信息提示词也会强制它回到自己负责的区域。实测下来这个Bug的概率大幅降低。使用wt task list还能在Agent启动前快速确认工作区路径避免把绝对路径写错。4.4 集成验证与冲突处理三个Agent开发完成后收尾阶段的合并顺序是有讲究的。我习惯先让改动范围最独立、最不容易产生冲突的任务先合并。例如先合并admin-export再合并payment-webhook最后合并涉及公共认证逻辑的auth-sso。每个任务合并的流程是wt task merge --name feature/admin-export --into main wt task prune --name feature/admin-export如果合并过程中出现冲突Worktrunk会停留在冲突状态并把冲突文件信息打印出来。这个状态下Worktrunk不会擅自做任何合并策略需要人工介入。我的处理方式是先让本地的Agent来处理或者如果冲突很小就手动改掉。这里有一个值得强调的操作不要把三个分支的冲突一次全解决完。每合并一个分支跑一遍测试确认main仍然是健康的再继续合并下一个。并行开发的任务之间可能存在隐藏依赖——比如支付模块改了用户模型认证模块也改了用户模型两个单独合并都没问题但第三个一合并就爆冲突。分阶段合并可以把问题隔离到最早出现的节点。5. 使用Worktrunk和Git Worktree容易踩的坑5.1 分支被占用的高频报错git worktree机制里有一个硬性限制同一个分支在同一时间只能被一个worktree检出。如果你在三个终端里用普通方式git checkout feature/auth-sso而Worktrunk已经把feature/auth-sso绑定到了../myapp-worktrees/auth-sso那么第二个工作区会直接报错fatal: feature/auth-sso is already checked out at ../myapp-worktrees/auth-sso遇到这个报错不要慌。先跑wt task list确认这个分支被哪个任务占用了再决定是要wt task switch进入那个工作区还是等任务结束后prune掉。千万不要用git worktree remove --force去强删很容易把未同步的提交搞丢。5.2 看不到其他分支文件的误解并行使用多个worktree时最常见的一种困惑是“我明明在另一个工作区提交了代码这边怎么没有”。原因其实很简单每个worktree的工作目录只对应一个分支你在这个目录里看到的永远只是当前分支的内容。另一个分支的改动必须通过merge或者rebase才会出现。这个误解在AI Agent之间可能造成连锁反应。比如Agent A在feature/auth-sso里修改了api/client.tsAgent B在feature/payment-webhook里运行测试发现缺少Agent A定义的接口可能会擅自把api/client.ts重新写一份造成重复劳动。解决方式是给每个Agent明确提示你的工作区里看不到的内容不代表不存在只代表还没有合并到当前分支。需要依赖就用git fetch origin feature/auth-sso拉取后查看而不是在本地重新实现一遍。5.3 未提交变更会卡住删除wt task prune执行时如果目标worktree里有未提交的修改会直接拒绝删除。这是保护机制但在并行Agent场景下这个提示会频繁出现因为Agent经常会在工作区里留下各种临时文件、调试输出甚至node_modules/.cache里的内容。我的建议是不要一看到报错就--force。先看一眼git status里的文件到底是什么如果是Agent生成的临时调试文件可以直接清理后删除如果是任务相关的半成品代码说明任务其实还没完成应该把它提交到分支上继续推进而不是急着清理。为了一点磁盘空间把未提交的工作丢掉成本太高。5.4 磁盘占用翻倍与缓存共享worktree共享的是Git对象库不共享工作目录。这意味着node_modules、vendor、dist这些依赖和构建目录在每个worktree里都会有一份独立的副本。如果项目依赖特别重三个worktree一开磁盘可能直接多占几GB到几十GB。针对这个问题有几个实操优化手段使用pnpm这类支持内容寻址存储的包管理器它的全局store天然支持多个项目共享依赖文件硬链接到每个工作区磁盘占用会大幅下降。对纯前端项目把node_modules加入.git/info/exclude避免git status在多个worktree里扫描大量无关注文件而变慢。如果项目里有大型构建产物放在主工作区统一构建或者用CI构建不要在每个worktree里各跑一遍。定期wt task list检查有没有长期闲置的任务该prune就prune别让废弃工作区一直占着磁盘。5.5 路径长度、IDE索引和钩子脚本问题最后说几个零碎但真实的问题。路径长度。在Windows上worktree如果放在路径很深的目录里加上项目内部结构再嵌套几层很容易触碰到260字符的路径上限。解决办法是把worktree根目录放在浅路径下比如C:\wt\这种级别或者在系统里开启长路径支持。IDE索引。VS Code这类编辑器如果不加限制会同时索引所有已经打开的worktree目录CPU和内存消耗明显上升。建议只打开当前正在操作的worktree目录不要把所有worktree都拖进同一个工作区窗口。钩子脚本。Git hooks默认是所有worktree共享的。如果你的仓库配置了比较重的post-checkout或者post-merge钩子每个worktree的创建和合并都会触发一次。钩子脚本如果假设“当前目录就是仓库根目录”在worktree下可能会出错。多检查一次钩子里的路径假设避免在多个worktree里反复踩同一个坑。6. 配置优化与进阶玩法6.1 通过配置文件固化团队约定Worktrunk支持通过配置文件固化项目级约定。在项目根目录放一个.worktrunkrc内容类似worktree_root: ../myapp-worktrees default_base: main agents: claude: claude-code codex: codex gemini: gemini-cli hooks: after_create: git fetch --prune before_merge: npm run lintdefault_base和worktree_root的作用前面已经说过。agents字段把Agent名称和启动命令绑定起来这样团队里每个人用wt task create --agent claude时拿到的都是同一套命令约定。hooks字段可以对Worktrunk的事件做扩展比如在创建worktree之后自动fetch或者在合并之前跑一遍lint检查。配置文件的另一个好处是可以提交到仓库里成为团队规范的一部分。新同事加入后只要执行wt init就能自动读取这些约定不用再靠口头传递“咱们的worktree都放在上级目录”这种信息。6.2 把Worktrunk接进CI/CDWorktrunk不只是本地工具也可以接进CI/CD流程。一个典型的用例是开发者在本地用Worktrunk开了一堆任务工作区推送到远程后CI里用wt task list --json读取所有任务的合并状态然后统一执行验证。比如用GitHub Actions做一套“所有feature分支合并前自动检查”的流程- name: List active tasks run: wt task list --json tasks.json - name: Run checks on each task branch run: | for task in $(jq -r .[] | .name tasks.json); do git checkout $task npm run lint npm test done更激进的用法是做完wt task merge之后直接在CI里跑wt task prune把已经合并的worktree从仓库里清理掉。这样整个“创建任务、并行开发、合并、清理”的闭环完全自动化。但需要注意的是CI里的Worktrunk对worktree的路径配置、以及执行权限都应该和本地环境隔离好避免CI机上一次跑多个worktree时相互干扰。6.3 命名规范与定期GC用了Worktrunk一段时间之后我最大的体会是如果没有命名规范所有优秀的工具都会被打回原形。目前我执行的规范是分支名统一用feature/短描述格式短描述统一用连字符分隔不超过35个字符比如feature/payment-webhook-verify。一个工作区对应一个Agent任务禁止把两个无关功能塞进同一个工作区。每天下班前跑一次wt task list看一眼有没有已经合完但没清理的任务。每周跑一次wt task prune把所有已经合并到主分支的worktree清理掉。这套规范配合Worktrunk的archive功能可以让仓库长期保持整洁。也建议在团队内部约定只有main和正在活跃开发的feature分支会出现在wt task list里其他归档任务一律隐藏。6.4 下一步从工作区管理走向Agent编排Worktrunk目前做的是工作区管理但我更看好它往Agent编排方向演进的潜力。现在AI Agent的能力越来越强底层已经可以通过MCP协议调用各种工具。如果Worktrunk暴露一套MCP接口让Agent自己通过工具调用来申请工作区、提交变更、触发合并整个开发流程就真正闭环了。到时候Agent自动执行wt task create申请一块独立空间改完代码自己wt task merge再wt task prune把工作区清理掉——人只负责最终审查合并结果。这听起来很未来但技术栈上已经没有障碍了缺的只是像Worktrunk这样把Git操作封装成语义化、可编程接口的工具层。我个人在实际使用中最直接的体会是跑通这套流程之后我再也不用手工切分支了。更意外的是并行Agent带来的最大收益不是节省那几秒切换时间而是上下文隔离带来的确定性。每个Agent看到的都是一个干净、稳定、只属于自己的工作区它对仓库状态的理解就不会再有偏差代码质量和任务完成度都明显提升。如果你正在折腾多Agent并行开发建议先别急着上各种花哨的编排框架老老实实把Worktree管理做好收益会更直接。