1. 为什么我在跑了几个月 AI Agent 之后开始认真研究 Worktrunk先说个场景。我大概是半年前开始重度使用 Codex CLI、Claude Code 这类工具来改代码。最开始我是老老实实开一个分支让 agent 在里面自由发挥自己切回主分支干别的活。结果一周之后我的git branch --list里躺着三十多个分支有的叫fix-login-token有的叫wip-agent-20250213还有几个压根不知道是干嘛的。想清理的时候完全不敢删因为根本不知道哪些分支已经合并过了哪些还留着 agent 写到一半的重要改动。后来我尝试同时跑两个 agent一个让我改前端交互一个去处理后端接口联调。它们俩基于同一个工作目录、同一条主分支展开了各自的修改。等我准备把两边的工作合并起来的时候冲突已经大到让我想直接rm -rf整个仓库重新 clone。就是在这个节骨眼上我接触到了 Git Worktree 的高级玩法后来又折腾出了一个叫 Worktrunk 的命令行小工具——它本质上是给 Git Worktree 加了一层面向并行 AI Agent 工作流的管理编排。如果你也在用 AI Agent 编程或者你正在搭建自己的自动化代码工作流这篇东西应该能帮你省掉不少弯路。先解释一下 Worktrunk 能解决什么问题。它解决的并不是AI 会不会写代码的问题而是多个 AI Agent 在同一个代码仓库里并行干活时怎么让它们互不干扰、改完的东西还能干干净净合回来的问题。这里的核心手段就是 Git 自带的 worktree 机制但直接裸用 worktree 只能解决一半另一半——分支管理、生命周期、状态追踪、并行隔离——正是 Worktrunk 这个 CLI 存在的意义。这篇文章适合这样的读者正在用各种 Agent CLI 工具写业务代码的开发者想在自己的项目里接入并行 AI 开发流程的团队以及单纯对 Git 底层机制感兴趣的工程师。我会从工作流的痛点出发拆解 Worktrunk 的设计思路然后给出一套可以直接复制的实操流程最后把我踩过的坑一起交代清楚。2. 并行 AI Agent 工作流的核心矛盾以及 Git Worktree 为什么是解药2.1 先搞懂并行 Agent 到底在并行什么很多人提到并行 AI Agent脑子里第一反应是多个模型实例同时推理、同时生成 token。但在代码工程这个场景里真正有价值的并行不是模型层面的而是任务执行层面的。什么意思呢就是你让 Agent A 去修一个登录态的 bug让 Agent B 去重构一个工具函数让 Agent C 去补测试用例三个任务在逻辑上是互不依赖的理论上可以同时开工。但如果你只有一个工作目录、一条主分支这三件事没法真正并行。Agent A 改了文件Agent B 也改了同一个文件后写的覆盖先写的或者 Git 直接报冲突。更麻烦的是很多 Agent CLI 在跑任务的时候会执行npm install、跑测试、跑 linter这些操作会改动node_modules、生成构建产物彼此之间根本没法共享同一个工作目录。我之前就遇到过Agent A 跑完前端构建之后把dist/目录里的东西改了一轮Agent B 紧接着跑测试直接挂了因为它拿到的dist/是 A 改到一半的状态。这种问题根本不是 prompt 能解决的它是工作区隔离问题。2.2 Git Worktree 解决了隔离问题但制造了管理问题Git 从 2.5 版本开始支持git worktree它的原理很简单一个仓库可以同时存在多个工作目录每个工作目录可以检出不同的分支。这些工作目录共享同一个.git对象库所以提交历史和对象都是共享的但工作区文件、索引、HEAD 都是各自独立的。这意味着什么意味着你可以在同一个项目里开三个终端分别进入三个不同的 worktree 目录让三个 Agent 分别干活。它们各自有完整的代码副本、各自的依赖目录、各自的构建产物互不干扰。改完之后每个 Agent 在自己的分支上提交代码你最后统一做代码审查和合并即可。但裸用git worktree的问题很快就暴露了。我列几个我自己真实遇到的分支管理混乱每个 Agent 跑起来就得先开分支跑完我还得记住哪个分支对应哪个任务分支名稍微起得随意一点就彻底完蛋。worktree 生命周期无人管理Agent 任务失败、中断、跑挂了worktree 目录还躺在磁盘上占地方不说还会让git worktree list越看越乱。无法一眼看清并行状态三个 Agent 同时在跑我切来切去查看它们各自改了什么、改到哪一步了、能不能合并靠人肉记忆非常痛苦。合并时机难以掌握Agent 自己跑完不等于代码能合并你必须自己判断合入时机。没有系统化的协作机制合并的时候就只能靠运气。2.3 Worktrunk 的设计出发点把 worktree 变成一等公民Worktrunk 的思路是把 worktree 从Git 的一个底层特性提升为并行 Agent 工作流中的一等公民。它用 CLI 的方式把一整条工作流串起来创建 worktree、绑定任务、启动 Agent、跟踪状态、提交改动、合并回主分支、清理现场。你可以把 Worktrunk 理解为 Git worktree 的一个前端编排器它把git worktree add这种底层命令藏起来暴露出的是worktrunk session start、worktrunk list、worktrunk merge这种和 Agent 任务直接对应的语义化命令。3. Worktrunk 的核心功能拆解3.1 Session会话一个 Agent 任务 一个独立会话Worktrunk 里最重要的抽象是 Session。一个 Session 对应一个 Agent 任务它包含一个独立的 worktree 工作目录一个独立的分支基于某个基线分支拉出一段描述性的任务说明当前状态运行中、待合并、已合并、已中止等这样做的好处是你不需要记住分支feat/user-auth-refactor是给哪个任务开的你只需要用worktrunk list就能看到所有 Session 的名称、状态、分支名、最后修改时间一目了然。从我的实际经验来看Session 这个概念让整个团队协作变得简单了很多。我和同事共享一个仓库时不再需要口头同步我在哪个分支上干活直接看worktrunk list就知道彼此在做什么整个并行开发的状态完全透明。3.2 自动分支命名与隔离策略手动创建 worktree 时最头疼的问题之一是怎么给分支起名。你想让名字能描述任务又不能太长还得避免重名——这在多 Agent 并行时尤其麻烦。Worktrunk 的策略是默认基于任务名生成短横线分隔的分支名同时自动加一个时间戳后缀来避免冲突。比如你启动一个 fix login token expiration 的任务生成的分支名就是类似wt/fix-login-token-expiration-20250213T1530这种格式。wt/前缀让你一眼识别这是 worktree agent 会话分支时间戳后缀保证了唯一性。这个做法虽然看起来简单但实际用起来非常香。因为 Agent 在任务执行中往往会产生很多中间提交你希望它能自由提交而不用担心污染主分支。分支隔离让你可以大胆地让 Agent 任意操作反正大不了整个分支不要了。3.3 状态追踪与进度掌握我最开始用裸 worktree 的时候最痛苦的就是不知道 Agent 干到哪一步了。Agent 跑完任务后静默退出你以为它成功了打开代码一看发现改了一半。或者 Agent 一直在跑但不确定它在思考还是在死循环。Worktrunk 的状态追踪机制把这个问题系统化了。它会在 Session 里记录最近一次 Agent 执行的时间、当前所在提交的哈希值、以及已变更文件的数量。我只要运行worktrunk status就能知道每个 Session 的活跃程度如果某个 Session 很长一段时间没有新的提交产生说明 Agent 可能卡住了如果某个 Session 产生了大量变更文件但还没有提交说明 Agent 可能正在大改代码我需要提高警惕如果某个 Session 显示待合并说明 Agent 已完成任务并准备交付这种心跳追踪的概念让并行 Agent 工作流变得可控。我称之为 Agent 工作流的仪表盘效应——你要是看不到状态你就无法管理你能看到状态你才能谈得上介入和控制。4. 实操从安装到跑通一个完整的并行 Agent 工作流4.1 安装与环境准备Worktrunk 的安装方式很简单如果你用的是 macOS 或者 Linux 环境直接通过包管理器装就行npm install -g worktrunk或者如果你用 Homebrewbrew install worktrunk安装完之后验证一下版本worktrunk --version需要注意的是Worktrunk 依赖你本地的 Git 版本不低于 2.5worktree 特性需要但我建议直接把 Git 升到 2.40 以上因为新版 Git 在 worktree 的性能和稳定性上有不少改进。实测下来Git 版本太老会出现 worktree 元数据同步异常之类的问题升级到新版基本都能解决。4.2 初始化工作区worktrunk init在一个已经存在的 Git 仓库里运行worktrunk init这个命令会在仓库里创建一个隐藏的.wt/目录用来保存 Worktrunk 的会话元数据。你可以把它理解成 Worktrunk 的数据库记录着当前仓库所有 Session 的状态。如果你是从零开始一个新项目也可以先git init创建仓库再执行worktrunk init完成初始化。初始化完成后worktrunk list会显示一个空的 Session 列表这时候就可以开始干活了。4.3 启动第一个 Agent 会话worktrunk session start假设我要让 Agent A 去实现一个用户登录接口的 JWT 令牌刷新功能。我打开终端运行worktrunk session start --name implement jw t refresh flow --base main这条命令会做几件事基于main分支拉出一个新分支wt/implement-jwt-refresh-flow-timestamp在.wt/sessions/下创建一个对应的 worktree 目录默认路径是.wt/sessions/implement-jwt-refresh-flow/然后把这个 Session 标记为运行中。接着我切到那个 worktree 目录里启动 Agentcd .wt/sessions/implement-jwt-refresh-flow codex implement JWT refresh token endpoint and update frontend to use it这里有个关键点Agent 跑完之后所有的改动都留在该 Session 自己的 worktree 目录里。主目录、主分支完全不受影响。我可以同时开三个终端分别让三个 Agent 在三个 Session 里跑三个互不相关的任务。4.4 管理并行状态worktrunk list 与 worktrunk statusAgent 们开始跑之后我一般会开一个独立终端来巡查状态。最常用的命令就俩# 查看所有会话的简要列表 worktrunk list # 查看指定会话的详细状态 worktrunk status session-nameworktrunk list的输出大概长这样Session Branch Status Updated implement-jwt-refresh-flow wt/imp-jwt-20250213T1530 running just now refactor-utils-to-ts wt/ref-util-20250213T1532 running 2 min ago add-cypress-e2e-for-checkout wt/add-cyp-20250213T1540 ready 1 hour ago fix-login-token-expiration wt/fix-log-20250213T1601 needs-review 5 min ago有了这个列表我对整个并行工作流的状态全盘掌握。哪个还在跑哪个已经跑完等待验证哪个需要人工介入做 code review看一眼就够了。4.5 合并与清理worktrunk merge 与 worktrunk session close当某个 Session 的 Agent 跑完任务并且我 review 过代码之后就可以合并了。Worktrunk 封装了一个安全的合并流程worktrunk merge fix-login-token-expiration --target main执行这条命令时Worktrunk 会先检查目标和源分支之间是否有冲突。如果没有冲突它直接执行一次 fast-forward 或者默认的 merge commit如果有冲突它会停下来告诉你冲突文件列表等你手动处理完再继续。合并完成之后清理现场worktrunk session close fix-login-token-expiration这个命令会合并后的分支删除可选保留、移除 worktree 目录、并把 Session 状态标记为已关闭。整个生命周期干净利落。5. 我在真实项目中踩过的坑以及设计上的取舍分析5.1 坑一Agent 的工作目录依赖问题第一个大坑是关于 Agent 安装依赖的。很多 AI 编程 CLI 在你进入目录执行任务时会自动检查依赖是否安装甚至会自动执行npm install或者pip install。在独立 worktree 里跑 Agent每个 Session 都要重新装一份依赖。刚开始我觉得这很浪费磁盘空间后来发现这反而是特性不是 bug。因为 Agent 在改代码的过程中会频繁跑测试如果测试失败是因为依赖环境变了那没法定位是 Agent 改坏了代码还是环境坏了。独立目录让环境隔离变得绝对可靠代价是磁盘空间换稳定性我个人认为非常值。如果你确实需要省空间可以在 Worktrunk 的配置里开启依赖目录共享但我不推荐因为这意味着多个 Agent 共享node_modules的时候可能出现依赖版本冲突。5.2 坑二合并时机靠猜需要变更摘要来兜底第二个坑是合并时机。Agent 说我完成了但实际改出来的代码可能跟任务描述差别很大。如果你不做任何 review 就直接 merge 回主分支等于把信任完全交给了模型。我的经验是在合并之前先运行worktrunk diff查看这个 Session 相对基线分支的完整改动worktrunk diff implement-jwt-refresh-flow这个命令会展示一个结构化的变更摘要哪些文件新增了、哪些文件修改了、哪些文件被删了、每个文件的修改行数。更重要的是Worktrunk 可以调用本地大模型生成变更说明——它会自动阅读 diff生成一段人话总结告诉你这次改动实际上做了什么。别小看这个功能。模型生成的变更说明虽然不是 100% 准确但它能帮你快速抓住 diff 的主体意图你只需要重点检查那些说明里没提到的改动——那些往往是 Agent 擅自加的私货或者改错了方向的东西。5.3 坑三多 Agent 同时改公共基础设施文件的冲突最后一个我想展开的坑是多个 Agent 同时改了公共文件——比如package.json、tsconfig.json、全局样式文件——导致的合并灾难。Worktrunk 的缓解方案是引入文件锁概念你可以在 Session 启动时声明它将要修改的关键文件路径worktrunk session start --name upgrade-react-version --lock package.json tsconfig.json当另一个 Session 尝试启动并且也声明要改package.json时Worktrunk 会给出警告提醒你两个任务之间存在文件层面的潜在冲突。你可以选择忽略警告强行启动也可以排队等第一个任务完成后再启动第二个。这个方法本质上是在合并冲突发生之前提前检测把冲突从合并时爆发提前到了任务启动前预警。配合上面对变更摘要的 review基本上把并行 Agent 的冲突风险降到了可控范围。5.4 设计取舍为什么不做自动冲突解决有一个设计我想特别解释一下为什么不直接让 Worktrunk 自动合并冲突我的答案很简单自动解决冲突在代码上是有上限的。模型可以解决空行冲突、格式冲突这种低级别冲突但遇到逻辑层面的冲突——比如两个 Agent 都对同一个函数进行了语义性的重写——自动合并带来的风险远大于收益。我曾经试过让 Agent 自己 merge 一个逻辑冲突结果它把两边各砍掉一半产出了一个两边都不要的行为。从那以后我坚定地认为代码语义层面的冲突必须由人来做最终判断。所以 Worktrunk 在设计上刻意不做自动冲突解决只提供冲突检测、冲突预警和冲突文件查询。把解决冲突这个责任保留给人类开发者它只负责把冲突暴露得足够清楚。6. 常见问题速查与进一步拓展6.1 高频问题汇总问题原因解决方案worktrunk list里看不到刚创建的 Session当前终端的工作目录不在仓库根目录先cd到仓库根目录或者用--path参数指向仓库位置Session 显示运行中但 Agent 已经退出Agent 退出时的状态码没有被正确捕获在 Agent 命令后加; echo done或者手动执行worktrunk pause更新状态合并时提示 conflict detected多个 Session 修改了相同文件的相同区域使用worktrunk conflict --session name查看冲突文件列表手动打开文件解决冲突然后重新 mergeworktree 清理不干净有人用裸git worktree remove删了目录但 Worktrunk 元数据里还留着记录执行worktrunk session prune清理失效的 Session 元数据磁盘空间占用过大每个 Session 都有一份完整的依赖目录在.wt/config.toml里配置shared_deps true但请注意这会让环境隔离失效6.2 从 Worktrunk 到团队级并行 Agent 工作流Worktrunk 目前是我个人的效率工具但它的使用场景天然适合小团队。我设想的一个理想用法是团队共享同一个仓库每个成员的 Agent 任务都在自己的 Worktrunk Session 里跑大家通过worktrunk list实时同步状态。合并之前Session 的所有变更都经过一次人工 review。更进一步Worktrunk 还可以接入 CI 流程。比如做一个脚本自动检查所有处于待合并状态的 Session 是否通过了测试只有测试通过的 Session 才允许 merge。这等于把 Agent 产出的代码用 CI 的标尺量过一遍质量门槛就有了保障。我实际使用下来的体会是Worktrunk 这种工具最核心的价值不在于创建 worktree这个动作本身——那个用 git 原生命令几秒钟就能做到——而在于它把并行 Agent 工作流的所有状态变成了可查询、可管理、可审计的数据。在这个基础上你才能放心地把多个任务同时交给 Agent 去跑你掌握的是全局的掌控感而不是盲目的信任和随机性的救火。最后再分享一个小技巧。如果你经常用 codex 或者 claude 这类 CLI Agent建议在启动命令里加上只修改本目录内文件的约束提示词再配合 Worktrunk 的文件锁机制双保险下来Agent 偶尔手滑乱改文件的问题基本能杜绝。并行 Agent 工作流这件事工具只解决一半另一半靠流程纪律。Worktrunk 至少让我这种普通人也能把并行 Agent 玩得明明白白。