1. 并行 AI Agent 工作流的致命痛点工作目录互踩最近我在帮团队搭建并行 AI Agent 流水线Node、Python、Go 各路的 Agent 都试过一轮Codex CLI、Claude Code 这类工具用起来确实爽代码唰唰地写。但我很快发现一个绕不开的坑多个 Agent 同时在一个仓库里干活时工作目录会互相踩踏。这个问题不解决后面全是乱账。先说场景。你有一个电商后台仓库想并行跑两个 Agent一个做订单导出功能一个重构登录鉴权。正常人的第一反应是开两个终端各跑一个 Agent指向同一个仓库目录。然后热闹了——Agent A 在读代码的时候Agent B 已经改了同一个文件Agent A 基于改了一半的状态分析业务逻辑得出来的结论全是错的两个 Agent 都在同一分支上提交git log 乱成一锅粥。更麻烦的是很多 Agent 会自己执行git add、git commit你根本拦不住。最后你会发现不是 Agent 不够聪明是它们生存的“环境”根本不支持并行。我试过几套所谓的“隔离方案”都不尽如人意。最土的办法是多克隆几份仓库每个 Agent 一份。但这是磁盘杀手一个带 node_modules 的仓库动辄几个 G克隆三份就没地方了而且每个副本要各自 pull、各自同步远端Agent 之间看不到对方的改动合并的时候冲突能堆成山。还有人用 Docker 容器跑 Agent隔离是彻底但也重——镜像构建、目录挂载、文件回传每一步都有摩擦Agent 写完代码你还要想尽办法把产物拷出来。所谓“轻量级”根本谈不上。这个问题的本质是“同一份代码基线”并行展开时需要多个互相隔离、又能随时合并的工作区。Git 本身其实早就提供了一个机制只是很多人没用过那就是 Git Worktree。而本文要聊的 Worktrunk就是把这个机制封装成一个面向并行 AI Agent 工作流的 CLI让“多 Agent 并行开发”变得真正可控、可复用、可清理。你不需要去记那一堆git worktree原生命令也不需要手工管理分支和目录的对应关系一条命令解决一个环节。这篇文章里我会先把“为什么 worktree 是并行开发的天然底座”讲透再把 Worktrunk 的核心设计、安装配置、实操流程完整过一遍最后附上我实际跑多个 Agent 时踩过的坑和排查技巧。不管你是刚接触 AI Agent 编程的新手还是已经在用 Codex、Claude Code 跑自动化任务的老手这套工作流都值得你搭起来试试。2. Git Worktree 为什么是并行 Agent 开发的天然底座2.1 Worktree 的核心原理共享数据库隔离工作区Git Worktree 这个概念简单说就是同一个仓库可以有多个工作目录每个目录对应一个不同的分支但它们共享同一个.git对象库。很多人第一次听到会懵这不就是把仓库复制了多份吗其实不是。复制仓库是“复制”worktree 是“分身”。它们共享的是同一套 commit 对象、同一个 remote 配置、同一个 reflog。你在 worktree A 里提交了一个 commit在 worktree B 里马上就能git log看到——因为它们本来就在同一个仓库里。而 worktree 之间隔离的是“工作目录中的文件内容”和“当前检出的分支”。用生活类比来说你的电脑是一个项目仓库普通工作方式是开一个桌面窗口所有任务都在这个桌面上铺开干一件事要先把另一件事的文件收拾干净。而 Worktree 像是给你开了多个虚拟桌面每个桌面上可以独立摆文件、独立干活但它们共用同一块硬盘对象库和同一个电源remote 配置。桌面之间互不干扰想合并成果的时候把文件整理一下推进主仓库就行。这个机制对 AI Agent 工作流来说太契合了。每个 Agent 拥有一个完全独立的工作目录里面的代码状态、未提交的修改、依赖安装结果都互不影响Agent 可以任意 checkout 分支、提交代码、跑测试不会污染其他 Agent 的现场而它们之间的代码同步只需要走一次git fetchgit merge本质还是同一个仓库内部的合并比多克隆方案轻量得多。2.2 原生命令的痛点裸用 Git Worktree 很难受既然 Git 原生就支持 worktree为什么还要再做一个 Worktrunk我实操下来原生命令在并行 Agent 场景下有四个明显的“难受点”。第一命令冗长且容易拼错。git worktree add ../feat-auth -b feat-auth main这条命令要指定路径、要指定分支、要指定基线分支。如果你有 8 个 Agent 并行跑你要人工记住每个目录对应的分支是什么、基线是什么。Agent 是并行了人先累了。第二目录命名和分支命名完全靠自觉。没有统一规范有的人用feat-auth有的人用auth-refactor还有人直接test。到了要清理的时候你根本不知道哪个目录对应哪个任务也不敢乱删怕删掉正在跑的 Agent 的工作现场。第三清理残留太麻烦。Agent 跑完或跑崩后worktree 不会自动收拾。你还要手动git worktree remove如果目录里有未提交的改动命令会直接报错你得先git stash或者强制删除。来回折腾几次你就会产生“不如老老实实多克隆几份”的念头。第四任务和 worktree 之间没有元数据关联。Agents 管理的描述、任务编号、负责人、创建时间这些信息原生命令一概不知道。你只能靠目录名硬记时间一长全部混乱。Worktrunk 要解决的就是把这四个痛点全部抹平。它把“创建一个 worktree 给某个 Agent 干活”这件事变成一条带任务语义的命令并把任务和 worktree 的对应关系持久化记录。你看到的不是一堆裸目录而是一张清晰的任务工作区清单。3. Worktrunk 核心设计面向任务而非面向目录3.1 设计思路任务 ID 驱动而非路径驱动Worktrunk 最核心的设计思路是“面向任务”而不是“面向路径”。你不需要关心 worktree 目录到底放在哪里、分支名是什么你只需要告诉它“我要为 refactor-auth-jwt 这个任务开一个工作区”剩下的事情全部由工具自动分配。底层实现上Worktrunk 会在仓库的.git目录下维护一个任务注册表类似一个 JSON 文件记录每个任务的 ID、对应的 worktree 路径、分支名、基线分支、创建时间、Agent 类型等元数据。当任务结束并清理后这些记录会一并归档方便追溯。这样的设计有几个直接好处。一是命名统一worktree 路径统一放在wrk/任务ID目录下分支名统一规范为任务ID前缀不会出现“A 叫 feat-authB 叫 auth-refactor”这种混乱。二是状态可视一条wrk list就能看到所有正在进行的 Agent 任务、各自的分支和路径谁在跑、谁已经僵死一目了然。三是清理安全因为知道任务和目录的对应关系删除前可以做检查避免误删正在运行的 Agent 现场。3.2 快速上手安装、初始化、创建第一个工作区先说安装。Worktrunk 是单二进制分发不依赖运行时环境。目前提供了 brew、winget 和 go install 三种渠道任选其一# macOS / Linux brew install worktrunk # Windows winget install worktrunk # 或者使用 Go go install github.com/worktrunk-cli/worktrunklatest装完以后在项目仓库根目录执行初始化它会检测当前 Git 仓库状态并写入注册表文件cd ~/projects/order-system wrk init初始化做的事情有三件确认当前目录是一个 Git 仓库在当前 HEAD 上打一个基线标记baseline作为后续创建 worktree 的默认父分支在.git下创建注册表文件。整个过程不会改动你现有的任何代码和分支。接下来创建一个给 Agent 使用的工作区wrk new refactor-auth-jwt这条命令会自动完成在wrk/refactor-auth-jwt目录创建子目录从当前 HEAD 检出名为refactor-auth-jwt的新分支把任务信息注册进列表输出一行提示告诉你如何进入这个目录启动 Agent。命令输出大概长这样[ok] Worktree created for task refactor-auth-jwt path: wrk/refactor-auth-jwt branch: refactor-auth-jwt base: main (commit 8c3f2aa) [info] Start your agent with: cd wrk/refactor-auth-jwt到这里一个属于 Agent 的“专属工位”就准备好了。你再也不用管目录和分支的关系只需要记住任务 ID。3.3 关键命令拆解从创建到回收的完整闭环Worktrunk 的命令设计围绕着“创建 → 查看 → 提交 → 回收”这条链路展开每个阶段都有对应的子命令。我把最常用的几个拆开讲。wrk list列出所有活跃任务。输出包含任务 ID、分支、路径、基线 commit、创建时间。这个命令是我日常用得最多的每隔一段时间就要刷一眼看看哪些 Agent 还在跑哪些已经跑完没清理。wrk switch task-id切换到某个任务对应的目录。内部实现其实就是cd但它会先确认这个 worktree 没有未提交的冲突防止切过去之后发现现场一团糟。wrk finish task-id [--merge base]收尾命令。它会把当前 worktree 里的改动提交如果有未提交的变更会提示你先 commit然后切回主工作区执行一次 merge 或 rebase把该任务分支合入目标分支默认是初始化时记录的 main最后清理 worktree 目录并归档注册表记录。也就是说一个任务从新建到合并到主干的完整生命周期走到这一步就闭环了。wrk abort task-id放弃这个任务。只清除 worktree 和分支不做合并。Agent 跑崩了、产出完全不可用的时候用这条命令收拾残局。wrk cleanup扫描所有注册表里的任务检查对应的 worktree 目录是否存在、是否有未提交的修改然后给出清理建议。这个是我建议定期跑一遍的命令能有效避免“僵尸 worktree 堆积”。4. 实操双 Agent 并行开发的完整流程4.1 场景设定与任务拆分为了让你直观看到这套工作流的效果我拿一个真实跑过的项目举例。假设我在维护一个订单系统的后端仓库技术栈是 Node.js TypeScript。我同时接到两个需求一个是给订单列表增加 CSV 导出功能另一个是把老的 Session 登录改成 JWT 鉴权。这两个需求互相独立但改动范围都在核心代码上如果串行做至少花一个下午并行做两边互不干扰一小时能搞定。我的做法是拆成两个 Agent 任务。Agent 1 负责feature/export-ordersAgent 2 负责refactor/auth-jwt。用 Worktrunk 建两个独立工作区。4.2 操作步骤实录第一步初始化并创建两个工作区cd ~/projects/order-system wrk init wrk new feature/export-orders wrk new refactor/auth-jwt wrk listwrk list的输出类似ID Branch Path Base feature/export-orders feature/export-orders wrk/feature/export-orders main refactor/auth-jwt refactor/auth-jwt wrk/refactor/auth-jwt main第二步分别启动两个 Agent在各自的工作目录里开工。我用 Codex CLI 举例子但 Claude Code、Cursor Agent 也是同一套思路关键点只是“把工作目录指到 wrk 子目录下”cd wrk/feature/export-orders codex --workspace . # 提示词给 /api/orders/list 接口增加 CSV 导出功能导出文件名格式为 orders-YYYYMMDD.csv另一个终端cd wrk/refactor/auth-jwt codex --workspace . # 提示词将登录模块从 Session 改为 JWT保留现有接口参数不变更新相关测试第三步观察进度并处理跨任务依赖。两个 Agent 的工作目录、分支完全隔离它们不会看到对方产生的未提交代码。但有一点要注意如果 Agent 1 在代码里改了公共类型定义Agent 2 在它的工作区里是看不到的只有等 Agent 1 提交并合并到主干后Agent 2 手动把主干拉进自己的分支才能感知到。第四步逐个收尾并合并回主干cd ~/projects/order-system wrk finish feature/export-orders --merge main wrk finish refactor/auth-jwt --merge main如果合并过程中没有冲突这两条命令跑完两个任务的分支就已经合到 main 上了worktree 自动清除注册表归档目录也干净了。4.3 并行度选择不是开得越多越快这里我想多说一个很多人忽略的点并行 Agent 的“并行度”不是越大越好。我一开始图省事一口气开了 5 个 Agent 跑 5 个任务结果第 3 个和第 4 个任务共享同一个底层模块两个 Agent 各自按自己的理解改这个模块的接口最后合并时冲突大得我想骂人。从那以后我总结出一个任务拆分原则如果两个任务改动的文件集合重叠度超过 30%就不要并行老老实实排队串行跑。实际上 Worktrunk 也支持给任务打scope标签比如wrk new refactor/auth-jwt --scope auth。你可以用wrk list --scope auth按模块过滤任务快速检查同一模块下是不是同时开了太多 Agent。这个字段不是强制的但建议每次都填因为并行解决不了模块耦合提前识别耦合才是关键。4.4 环境变量与依赖隔离让每个 Agent 跑在独立环境里我在实操中还发现光隔离 Git 工作区还不够很多 Agent 在启动时会安装依赖、读取环境变量。如果你让 5 个 Agent 共享同一个 node_modules 目录那么 Agent 1 在装包时改动的依赖树会让 Agent 2 的程序直接崩掉。所以 worktree 目录创建好之后我建议在启动 Agent 前先跑一次独立的依赖安装cd wrk/feature/export-orders npm install --no-audit --no-fund这样做确实会多占一些磁盘空间但换来的是依赖树的完整隔离。如果项目依赖安装很耗时也可以在 Worktrunk 的配置文件里给特定任务指定--reuse-node-modules让它软链接到主机目录——这是省磁盘的折中方案但只适合依赖极其稳定、不会有 Agent 去动package.json的场景。环境变量方面我习惯在启动 Agent 时用一个wrk env task-id子命令它会读取注册表里的env配置把变量注入到当前 shell。比如某个任务需要访问测试数据库、某个任务需要走 mock 服务、某个任务需要特定的日志级别各自定义好互不干扰。这个功能实现起来不复杂但对多 Agent 并行场景帮助巨大——否则你会出现“Agent 2 读到了 Agent 1 的 API key把请求打到错误环境”这种事。5. 常见问题与排查技巧实录工具再好用用久了总会碰到各种边角问题。我把跑并行 Agent 工作流半年多来遇到的真实问题整理成一张速查表每个问题后面附上排查思路。现象直接原因解决办法worktree 目录里执行git checkout main报错branch is already checked outmain 分支已经在主工作区检出了worktree 不能同时检出同一个分支不要手动切 branch每个 worktree 固定只跑自己的任务分支要用主线代码时用git fetchgit merge origin/main拉取清理 worktree 时提示contains modified filesworktree 目录里有未提交的改动Git 为安全起见拒绝删除先git status确认改动内容要保留就git commit进任务分支再wrk finish不保留就用wrk abort强制清理Agent 跑崩了残留目录和分支堆了很多Agent 没有正常退出原生命令不会自动清理用wrk cleanup扫描僵尸任务逐个wrk abort或wrk finish收尾两个 Agent 改了同一个文件合并时冲突巨大任务拆分时没有检查文件覆盖度参考 4.3 节的 scope 规则开工前先对比两个任务的改动文件集合重叠度高的串行执行worktree 目录占磁盘空间大每个 worktree 都有一份依赖安装用wrk new --reuse-node-modules做软链接复用或定期删除已合并任务对应的目录worktree 创建成功但目录里看起来“没有代码”没理解 worktree 是“空工作区 对应分支”不是新克隆检查当前分支git log -1查看 HEADWorktrunk 默认从 main 的 HEAD 检出文件都在只是目录是新生成的fork 出来的任务分支落后于 main合并时有老冲突main 被其他 Agent 合并了新代码收尾前先git fetch origin main git merge origin/main再wrk finish让冲突在自己分支内提前解决我再补充几个排查心得。第一遇到“目录里找不到文件”的问题90% 是搞混了“克隆”和“worktree”的区别。Worktrunk 创建出来的目录不是独立副本它只是仓库的另一个检出现场。你用git log -1 --oneline看一眼 HEAD 就知道代码都在只是分支不同。第二Agent 崩溃后没有正常 exit导致 worktree 目录被进程占用Windows 上尤其常见。这时候wrk abort可能会报目录被占用只需要关掉占用目录的终端窗口再重试就行。第三如果注册表文件本身坏了比如手动编辑 JSON 出错Worktrunk 会拒绝加载所有任务。我踩过一次之后学乖了绝不手动改注册表所有操作走命令入口。6. Worktrunk 的边界与扩展思路讲完命令和排查我再聊聊这个工具目前解决不了什么以及它后续可以怎么扩展。Worktrunk 解决的是“工作区隔离”这个环节它不负责任务调度。也就是说它不会自动帮你判断哪个 Agent 该执行哪个任务也不会做资源分配和失败重试。我和朋友讨论过团队里如果用 n8n、Dify 这类流程编排工具管理 AgentWorktrunk 可以作为一个“行动节点”接入流程引擎负责任务拆分和分发Worktrunk 负责执行“创建一个隔离工作区”。两者的职责互补不冲突。另一个可以扩展的方向是让 Worktrunk 直接感知 Agent 的生命周期。目前 Agent 跑完不会自动调用wrk finish需要人工确认产物质量后再收尾。这个“人工确认”在严格的项目里反而是优点——AI 写的代码要先过 review 再合并主干。如果是完全自动化的流水线可以考虑给wrk finish加一个--force参数跳过确认直接合并。还有人把 worktree 和 CI/CD 做联动每个 Agent 任务从创建 worktree 开始就触发一次构建合并主干后再触发一次部署。这个思路可行相当于把“AI 开发 → 构建 → 部署”串成一条流水线。Worktrunk 目前已经在注册表里记录了基线 commit 和任务分支理论上可以对接任何 CI 系统。7. 关于命名规范与团队协作的一点经验最后单独写一节是因为我发现“多 Agent 并行”一旦从个人工具变成团队协作命名规范的重要性会突然放大十倍。我踩过一次很糟糕的坑团队里另一个同事用 Worktrunk 建了一个任务任务 ID 叫revert。结果他用完后没清理第二天我跑wrk cleanup时以为这是某个回滚任务差点把他正在开发的 worktree 清掉了。从那以后我们团队定了一套硬性规范任务 ID 必须遵循type/module-description格式type 只能是feature、fix、refactor、experiment四种。revert这类模糊词不允许出现在任务 ID 里。还建议在项目根目录放一个WRK.md文件里面记录两条信息当前活跃任务的清单和负责人以及每个任务的验收标准。这个文件不参与构建但作用很大——因为 Agent 本身也会读这个文件你可以在启动 Agent 时把它作为上下文的一部分让它心里有数“我在并行体系里处于什么位置我的改动要满足什么条件”。实测下来给 Agent 交代清楚“你改完代码不需要自己合并到主干只要在 WRK.md 对应的验收标准上打勾”出错率会明显下降。Worktrunk 的价值在于让“多个 AI 同时在仓库里干活”这件事从失控变成可控。我个人在实际使用中的体会是工具本身很简单真正复杂的是工作流的定义——什么时候并行、什么时候串行、冲突如何提前识别、收尾如何确认。如果你正在被多 Agent 并行开发的环境问题困扰我建议你从一个小仓库开始建两个 worktree 跑两个最简单的任务跑通一遍再逐步加码。等流程顺畅了你就会发现AI Agent 从来不是瓶颈环境才是。
Worktrunk：基于Git Worktree的并行AI Agent工作区隔离方案
1. 并行 AI Agent 工作流的致命痛点工作目录互踩最近我在帮团队搭建并行 AI Agent 流水线Node、Python、Go 各路的 Agent 都试过一轮Codex CLI、Claude Code 这类工具用起来确实爽代码唰唰地写。但我很快发现一个绕不开的坑多个 Agent 同时在一个仓库里干活时工作目录会互相踩踏。这个问题不解决后面全是乱账。先说场景。你有一个电商后台仓库想并行跑两个 Agent一个做订单导出功能一个重构登录鉴权。正常人的第一反应是开两个终端各跑一个 Agent指向同一个仓库目录。然后热闹了——Agent A 在读代码的时候Agent B 已经改了同一个文件Agent A 基于改了一半的状态分析业务逻辑得出来的结论全是错的两个 Agent 都在同一分支上提交git log 乱成一锅粥。更麻烦的是很多 Agent 会自己执行git add、git commit你根本拦不住。最后你会发现不是 Agent 不够聪明是它们生存的“环境”根本不支持并行。我试过几套所谓的“隔离方案”都不尽如人意。最土的办法是多克隆几份仓库每个 Agent 一份。但这是磁盘杀手一个带 node_modules 的仓库动辄几个 G克隆三份就没地方了而且每个副本要各自 pull、各自同步远端Agent 之间看不到对方的改动合并的时候冲突能堆成山。还有人用 Docker 容器跑 Agent隔离是彻底但也重——镜像构建、目录挂载、文件回传每一步都有摩擦Agent 写完代码你还要想尽办法把产物拷出来。所谓“轻量级”根本谈不上。这个问题的本质是“同一份代码基线”并行展开时需要多个互相隔离、又能随时合并的工作区。Git 本身其实早就提供了一个机制只是很多人没用过那就是 Git Worktree。而本文要聊的 Worktrunk就是把这个机制封装成一个面向并行 AI Agent 工作流的 CLI让“多 Agent 并行开发”变得真正可控、可复用、可清理。你不需要去记那一堆git worktree原生命令也不需要手工管理分支和目录的对应关系一条命令解决一个环节。这篇文章里我会先把“为什么 worktree 是并行开发的天然底座”讲透再把 Worktrunk 的核心设计、安装配置、实操流程完整过一遍最后附上我实际跑多个 Agent 时踩过的坑和排查技巧。不管你是刚接触 AI Agent 编程的新手还是已经在用 Codex、Claude Code 跑自动化任务的老手这套工作流都值得你搭起来试试。2. Git Worktree 为什么是并行 Agent 开发的天然底座2.1 Worktree 的核心原理共享数据库隔离工作区Git Worktree 这个概念简单说就是同一个仓库可以有多个工作目录每个目录对应一个不同的分支但它们共享同一个.git对象库。很多人第一次听到会懵这不就是把仓库复制了多份吗其实不是。复制仓库是“复制”worktree 是“分身”。它们共享的是同一套 commit 对象、同一个 remote 配置、同一个 reflog。你在 worktree A 里提交了一个 commit在 worktree B 里马上就能git log看到——因为它们本来就在同一个仓库里。而 worktree 之间隔离的是“工作目录中的文件内容”和“当前检出的分支”。用生活类比来说你的电脑是一个项目仓库普通工作方式是开一个桌面窗口所有任务都在这个桌面上铺开干一件事要先把另一件事的文件收拾干净。而 Worktree 像是给你开了多个虚拟桌面每个桌面上可以独立摆文件、独立干活但它们共用同一块硬盘对象库和同一个电源remote 配置。桌面之间互不干扰想合并成果的时候把文件整理一下推进主仓库就行。这个机制对 AI Agent 工作流来说太契合了。每个 Agent 拥有一个完全独立的工作目录里面的代码状态、未提交的修改、依赖安装结果都互不影响Agent 可以任意 checkout 分支、提交代码、跑测试不会污染其他 Agent 的现场而它们之间的代码同步只需要走一次git fetchgit merge本质还是同一个仓库内部的合并比多克隆方案轻量得多。2.2 原生命令的痛点裸用 Git Worktree 很难受既然 Git 原生就支持 worktree为什么还要再做一个 Worktrunk我实操下来原生命令在并行 Agent 场景下有四个明显的“难受点”。第一命令冗长且容易拼错。git worktree add ../feat-auth -b feat-auth main这条命令要指定路径、要指定分支、要指定基线分支。如果你有 8 个 Agent 并行跑你要人工记住每个目录对应的分支是什么、基线是什么。Agent 是并行了人先累了。第二目录命名和分支命名完全靠自觉。没有统一规范有的人用feat-auth有的人用auth-refactor还有人直接test。到了要清理的时候你根本不知道哪个目录对应哪个任务也不敢乱删怕删掉正在跑的 Agent 的工作现场。第三清理残留太麻烦。Agent 跑完或跑崩后worktree 不会自动收拾。你还要手动git worktree remove如果目录里有未提交的改动命令会直接报错你得先git stash或者强制删除。来回折腾几次你就会产生“不如老老实实多克隆几份”的念头。第四任务和 worktree 之间没有元数据关联。Agents 管理的描述、任务编号、负责人、创建时间这些信息原生命令一概不知道。你只能靠目录名硬记时间一长全部混乱。Worktrunk 要解决的就是把这四个痛点全部抹平。它把“创建一个 worktree 给某个 Agent 干活”这件事变成一条带任务语义的命令并把任务和 worktree 的对应关系持久化记录。你看到的不是一堆裸目录而是一张清晰的任务工作区清单。3. Worktrunk 核心设计面向任务而非面向目录3.1 设计思路任务 ID 驱动而非路径驱动Worktrunk 最核心的设计思路是“面向任务”而不是“面向路径”。你不需要关心 worktree 目录到底放在哪里、分支名是什么你只需要告诉它“我要为 refactor-auth-jwt 这个任务开一个工作区”剩下的事情全部由工具自动分配。底层实现上Worktrunk 会在仓库的.git目录下维护一个任务注册表类似一个 JSON 文件记录每个任务的 ID、对应的 worktree 路径、分支名、基线分支、创建时间、Agent 类型等元数据。当任务结束并清理后这些记录会一并归档方便追溯。这样的设计有几个直接好处。一是命名统一worktree 路径统一放在wrk/任务ID目录下分支名统一规范为任务ID前缀不会出现“A 叫 feat-authB 叫 auth-refactor”这种混乱。二是状态可视一条wrk list就能看到所有正在进行的 Agent 任务、各自的分支和路径谁在跑、谁已经僵死一目了然。三是清理安全因为知道任务和目录的对应关系删除前可以做检查避免误删正在运行的 Agent 现场。3.2 快速上手安装、初始化、创建第一个工作区先说安装。Worktrunk 是单二进制分发不依赖运行时环境。目前提供了 brew、winget 和 go install 三种渠道任选其一# macOS / Linux brew install worktrunk # Windows winget install worktrunk # 或者使用 Go go install github.com/worktrunk-cli/worktrunklatest装完以后在项目仓库根目录执行初始化它会检测当前 Git 仓库状态并写入注册表文件cd ~/projects/order-system wrk init初始化做的事情有三件确认当前目录是一个 Git 仓库在当前 HEAD 上打一个基线标记baseline作为后续创建 worktree 的默认父分支在.git下创建注册表文件。整个过程不会改动你现有的任何代码和分支。接下来创建一个给 Agent 使用的工作区wrk new refactor-auth-jwt这条命令会自动完成在wrk/refactor-auth-jwt目录创建子目录从当前 HEAD 检出名为refactor-auth-jwt的新分支把任务信息注册进列表输出一行提示告诉你如何进入这个目录启动 Agent。命令输出大概长这样[ok] Worktree created for task refactor-auth-jwt path: wrk/refactor-auth-jwt branch: refactor-auth-jwt base: main (commit 8c3f2aa) [info] Start your agent with: cd wrk/refactor-auth-jwt到这里一个属于 Agent 的“专属工位”就准备好了。你再也不用管目录和分支的关系只需要记住任务 ID。3.3 关键命令拆解从创建到回收的完整闭环Worktrunk 的命令设计围绕着“创建 → 查看 → 提交 → 回收”这条链路展开每个阶段都有对应的子命令。我把最常用的几个拆开讲。wrk list列出所有活跃任务。输出包含任务 ID、分支、路径、基线 commit、创建时间。这个命令是我日常用得最多的每隔一段时间就要刷一眼看看哪些 Agent 还在跑哪些已经跑完没清理。wrk switch task-id切换到某个任务对应的目录。内部实现其实就是cd但它会先确认这个 worktree 没有未提交的冲突防止切过去之后发现现场一团糟。wrk finish task-id [--merge base]收尾命令。它会把当前 worktree 里的改动提交如果有未提交的变更会提示你先 commit然后切回主工作区执行一次 merge 或 rebase把该任务分支合入目标分支默认是初始化时记录的 main最后清理 worktree 目录并归档注册表记录。也就是说一个任务从新建到合并到主干的完整生命周期走到这一步就闭环了。wrk abort task-id放弃这个任务。只清除 worktree 和分支不做合并。Agent 跑崩了、产出完全不可用的时候用这条命令收拾残局。wrk cleanup扫描所有注册表里的任务检查对应的 worktree 目录是否存在、是否有未提交的修改然后给出清理建议。这个是我建议定期跑一遍的命令能有效避免“僵尸 worktree 堆积”。4. 实操双 Agent 并行开发的完整流程4.1 场景设定与任务拆分为了让你直观看到这套工作流的效果我拿一个真实跑过的项目举例。假设我在维护一个订单系统的后端仓库技术栈是 Node.js TypeScript。我同时接到两个需求一个是给订单列表增加 CSV 导出功能另一个是把老的 Session 登录改成 JWT 鉴权。这两个需求互相独立但改动范围都在核心代码上如果串行做至少花一个下午并行做两边互不干扰一小时能搞定。我的做法是拆成两个 Agent 任务。Agent 1 负责feature/export-ordersAgent 2 负责refactor/auth-jwt。用 Worktrunk 建两个独立工作区。4.2 操作步骤实录第一步初始化并创建两个工作区cd ~/projects/order-system wrk init wrk new feature/export-orders wrk new refactor/auth-jwt wrk listwrk list的输出类似ID Branch Path Base feature/export-orders feature/export-orders wrk/feature/export-orders main refactor/auth-jwt refactor/auth-jwt wrk/refactor/auth-jwt main第二步分别启动两个 Agent在各自的工作目录里开工。我用 Codex CLI 举例子但 Claude Code、Cursor Agent 也是同一套思路关键点只是“把工作目录指到 wrk 子目录下”cd wrk/feature/export-orders codex --workspace . # 提示词给 /api/orders/list 接口增加 CSV 导出功能导出文件名格式为 orders-YYYYMMDD.csv另一个终端cd wrk/refactor/auth-jwt codex --workspace . # 提示词将登录模块从 Session 改为 JWT保留现有接口参数不变更新相关测试第三步观察进度并处理跨任务依赖。两个 Agent 的工作目录、分支完全隔离它们不会看到对方产生的未提交代码。但有一点要注意如果 Agent 1 在代码里改了公共类型定义Agent 2 在它的工作区里是看不到的只有等 Agent 1 提交并合并到主干后Agent 2 手动把主干拉进自己的分支才能感知到。第四步逐个收尾并合并回主干cd ~/projects/order-system wrk finish feature/export-orders --merge main wrk finish refactor/auth-jwt --merge main如果合并过程中没有冲突这两条命令跑完两个任务的分支就已经合到 main 上了worktree 自动清除注册表归档目录也干净了。4.3 并行度选择不是开得越多越快这里我想多说一个很多人忽略的点并行 Agent 的“并行度”不是越大越好。我一开始图省事一口气开了 5 个 Agent 跑 5 个任务结果第 3 个和第 4 个任务共享同一个底层模块两个 Agent 各自按自己的理解改这个模块的接口最后合并时冲突大得我想骂人。从那以后我总结出一个任务拆分原则如果两个任务改动的文件集合重叠度超过 30%就不要并行老老实实排队串行跑。实际上 Worktrunk 也支持给任务打scope标签比如wrk new refactor/auth-jwt --scope auth。你可以用wrk list --scope auth按模块过滤任务快速检查同一模块下是不是同时开了太多 Agent。这个字段不是强制的但建议每次都填因为并行解决不了模块耦合提前识别耦合才是关键。4.4 环境变量与依赖隔离让每个 Agent 跑在独立环境里我在实操中还发现光隔离 Git 工作区还不够很多 Agent 在启动时会安装依赖、读取环境变量。如果你让 5 个 Agent 共享同一个 node_modules 目录那么 Agent 1 在装包时改动的依赖树会让 Agent 2 的程序直接崩掉。所以 worktree 目录创建好之后我建议在启动 Agent 前先跑一次独立的依赖安装cd wrk/feature/export-orders npm install --no-audit --no-fund这样做确实会多占一些磁盘空间但换来的是依赖树的完整隔离。如果项目依赖安装很耗时也可以在 Worktrunk 的配置文件里给特定任务指定--reuse-node-modules让它软链接到主机目录——这是省磁盘的折中方案但只适合依赖极其稳定、不会有 Agent 去动package.json的场景。环境变量方面我习惯在启动 Agent 时用一个wrk env task-id子命令它会读取注册表里的env配置把变量注入到当前 shell。比如某个任务需要访问测试数据库、某个任务需要走 mock 服务、某个任务需要特定的日志级别各自定义好互不干扰。这个功能实现起来不复杂但对多 Agent 并行场景帮助巨大——否则你会出现“Agent 2 读到了 Agent 1 的 API key把请求打到错误环境”这种事。5. 常见问题与排查技巧实录工具再好用用久了总会碰到各种边角问题。我把跑并行 Agent 工作流半年多来遇到的真实问题整理成一张速查表每个问题后面附上排查思路。现象直接原因解决办法worktree 目录里执行git checkout main报错branch is already checked outmain 分支已经在主工作区检出了worktree 不能同时检出同一个分支不要手动切 branch每个 worktree 固定只跑自己的任务分支要用主线代码时用git fetchgit merge origin/main拉取清理 worktree 时提示contains modified filesworktree 目录里有未提交的改动Git 为安全起见拒绝删除先git status确认改动内容要保留就git commit进任务分支再wrk finish不保留就用wrk abort强制清理Agent 跑崩了残留目录和分支堆了很多Agent 没有正常退出原生命令不会自动清理用wrk cleanup扫描僵尸任务逐个wrk abort或wrk finish收尾两个 Agent 改了同一个文件合并时冲突巨大任务拆分时没有检查文件覆盖度参考 4.3 节的 scope 规则开工前先对比两个任务的改动文件集合重叠度高的串行执行worktree 目录占磁盘空间大每个 worktree 都有一份依赖安装用wrk new --reuse-node-modules做软链接复用或定期删除已合并任务对应的目录worktree 创建成功但目录里看起来“没有代码”没理解 worktree 是“空工作区 对应分支”不是新克隆检查当前分支git log -1查看 HEADWorktrunk 默认从 main 的 HEAD 检出文件都在只是目录是新生成的fork 出来的任务分支落后于 main合并时有老冲突main 被其他 Agent 合并了新代码收尾前先git fetch origin main git merge origin/main再wrk finish让冲突在自己分支内提前解决我再补充几个排查心得。第一遇到“目录里找不到文件”的问题90% 是搞混了“克隆”和“worktree”的区别。Worktrunk 创建出来的目录不是独立副本它只是仓库的另一个检出现场。你用git log -1 --oneline看一眼 HEAD 就知道代码都在只是分支不同。第二Agent 崩溃后没有正常 exit导致 worktree 目录被进程占用Windows 上尤其常见。这时候wrk abort可能会报目录被占用只需要关掉占用目录的终端窗口再重试就行。第三如果注册表文件本身坏了比如手动编辑 JSON 出错Worktrunk 会拒绝加载所有任务。我踩过一次之后学乖了绝不手动改注册表所有操作走命令入口。6. Worktrunk 的边界与扩展思路讲完命令和排查我再聊聊这个工具目前解决不了什么以及它后续可以怎么扩展。Worktrunk 解决的是“工作区隔离”这个环节它不负责任务调度。也就是说它不会自动帮你判断哪个 Agent 该执行哪个任务也不会做资源分配和失败重试。我和朋友讨论过团队里如果用 n8n、Dify 这类流程编排工具管理 AgentWorktrunk 可以作为一个“行动节点”接入流程引擎负责任务拆分和分发Worktrunk 负责执行“创建一个隔离工作区”。两者的职责互补不冲突。另一个可以扩展的方向是让 Worktrunk 直接感知 Agent 的生命周期。目前 Agent 跑完不会自动调用wrk finish需要人工确认产物质量后再收尾。这个“人工确认”在严格的项目里反而是优点——AI 写的代码要先过 review 再合并主干。如果是完全自动化的流水线可以考虑给wrk finish加一个--force参数跳过确认直接合并。还有人把 worktree 和 CI/CD 做联动每个 Agent 任务从创建 worktree 开始就触发一次构建合并主干后再触发一次部署。这个思路可行相当于把“AI 开发 → 构建 → 部署”串成一条流水线。Worktrunk 目前已经在注册表里记录了基线 commit 和任务分支理论上可以对接任何 CI 系统。7. 关于命名规范与团队协作的一点经验最后单独写一节是因为我发现“多 Agent 并行”一旦从个人工具变成团队协作命名规范的重要性会突然放大十倍。我踩过一次很糟糕的坑团队里另一个同事用 Worktrunk 建了一个任务任务 ID 叫revert。结果他用完后没清理第二天我跑wrk cleanup时以为这是某个回滚任务差点把他正在开发的 worktree 清掉了。从那以后我们团队定了一套硬性规范任务 ID 必须遵循type/module-description格式type 只能是feature、fix、refactor、experiment四种。revert这类模糊词不允许出现在任务 ID 里。还建议在项目根目录放一个WRK.md文件里面记录两条信息当前活跃任务的清单和负责人以及每个任务的验收标准。这个文件不参与构建但作用很大——因为 Agent 本身也会读这个文件你可以在启动 Agent 时把它作为上下文的一部分让它心里有数“我在并行体系里处于什么位置我的改动要满足什么条件”。实测下来给 Agent 交代清楚“你改完代码不需要自己合并到主干只要在 WRK.md 对应的验收标准上打勾”出错率会明显下降。Worktrunk 的价值在于让“多个 AI 同时在仓库里干活”这件事从失控变成可控。我个人在实际使用中的体会是工具本身很简单真正复杂的是工作流的定义——什么时候并行、什么时候串行、冲突如何提前识别、收尾如何确认。如果你正在被多 Agent 并行开发的环境问题困扰我建议你从一个小仓库开始建两个 worktree 跑两个最简单的任务跑通一遍再逐步加码。等流程顺畅了你就会发现AI Agent 从来不是瓶颈环境才是。
