1. 从“一个人写代码”到“一支AI军队”Worktrunk 到底在解决什么问题最近这半年我明显感觉到身边的开发者分成了两拨一拨还在用编辑器自带终端老老实实开分支、切分支、合并另一拨已经让三四个 AI Agent 同时在自己的仓库里干活了速度快到 GitHub 的 contribution 图都快变成实心方块。但你真让三四个 Agent 在同一个 Git 仓库里并行跑任务第一个炸掉的一定不是代码而是分支管理。我自己就栽过大跟头。用 Codex CLI 跑一个重构任务同时在另一个终端里用 Claude Code 做测试用例补全。本来两个任务互不相关结果因为共用了同一个工作目录一个 Agent 把另一个 Agent 生成的文件给 git clean 掉了。更离谱的是有个 Agent 改到一半另一个 Agent 的自动提交直接把半成品推到了远端CI 直接红了一片。后来我开始用 Git Worktree 把这个痛点一个个拆掉但拆完发现又掉进了新的坑——Worktree 本身命令不难难的是在并行 AI Agent 场景下如何把“每个 Agent 一块独立工作区 独立分支 独立环境变量 独立上下文”这套流程管起来。手动敲 git worktree add 敲到第十次的时候我就知道必须找个工具来干这事。这就是Worktrunk出现的理由一个面向并行 AI Agent 工作流的 Git Worktree 管理 CLI。它的核心定位不是替代 Git而是把你脑子里那些“该给哪个 Agent 分哪块地、这块地叫什么名字、用完怎么回收”的管理逻辑固化下来。说白了一句话Worktrunk 就是给 AI Agent 打工的分地管家。这篇文章我主要聊三件事为什么并行 AI Agent 工作流里 Worktree 是刚需Worktrunk 是怎么把它变成一套顺手流程的以及我在真实项目中踩过的坑和总结出来的避坑清单。如果你正在用 Codex CLI、Claude Code 或者任何支持命令行调用的 AI Agent 工具这篇文章值得看完。2. 为什么要用 Worktree并行任务与原生命令的真实摩擦点2.1 一个场景三块碎片假设你现在手头有一个订单服务仓库同时来了三件事订单超时自动关闭逻辑要重构支付回调的日志要补全加上关键链路的 trace_id 追踪给 README 补充 API 文档示例在传统开发模式下你大概率这么干git checkout -b feature/order-timeout写代码写完切回 main再开新分支改日志再切回 main改文档。一切看起来挺顺无非是多切几次分支。但如果你把这三个任务分别交给三个 AI Agent 呢每个 Agent 都需要一份完整代码库都需要一个干净的分支都需要能独立跑测试都需要不想被别人干扰。三个 Agent 在同一个目录里“共处”的唯一结果就是资源竞争和状态污染。Git Worktree 的价值就在这里它允许你在同一个仓库下创建多个工作目录每个目录对应一个独立分支且互不干扰。简单说就是同一个 .git 仓库长出多个独立的工作区树这就是 “worktree”工作树名称的由来。2.2 原生命令的三宗罪那直接用原生的 git worktree 不就行了理论上是但实操起来有三宗罪第一宗罪命令繁琐心智负担重。每次创建都要写全git worktree add -b feature/order-timeout ../orders-timeout main。如果再加上设置环境变量、配置 AI CLI 的上下文目录、启动 Agent 会话一个任务至少五六个步骤。手动操作第三四个任务时心态已经开始崩了。第二宗罪命名全靠自律。不同 Agent 跑任务工作区目录叫什么、分支叫什么、跟哪个基分支分离如果全靠临时拍脑袋隔几天回来看根本不知道哪个目录对应哪个任务。../wip1、../abc、../final_v2这种目录名我在同事电脑上见过不止一次。第三宗罪清理靠胆量。git worktree remove 有个安全机制——如果工作区里有未提交或未跟踪的文件会拒绝删除。这个保护是好意但在 AI Agent 场景下变成了灾难你不确定这个 Agent 有没有留下需要保留的东西又不敢粗暴删最后一堆残留 worktree 堆在那里git worktree list 一拉下来满屏都是记录。2.3 Worktrunk 的解题方向Worktrunk 的思路很简单把这些散落的操作收拢到一个 CLI 工具里用一套“项目级配置 约定优于配置”的方式把创建、分配、清理工作区的流程固化下来。它解决的洞察是当你在并行跑 AI Agent 时你真正需要管理的不是 Git 分支而是每一个 Agent 的运行环境快照。分支只是这个快照的载体之一其他的还包括环境变量比如给 Agent 预设的 API key、会话初始提示词、绑定的远端目标以及任务完成后这个环境是清掉还是保留。为了让后面所有命令演示有明确路径我先声明一下我的实测环境和版本信息操作系统macOS 14.5Apple Silicon相同的流程在 Ubuntu 22.04 上我也验证过Git 版本2.45.1要求不低于 2.30worktree 基础功能和 2.31--track 增强Node.js 版本v20.14.0Worktrunk 本身基于 Node 生态分发安装方式npm 全局安装这也是目前最省事的方式3. 核心功能拆解Worktrunk 真正值钱的四个能力Worktrunk 的功能如果只是封装“创建 worktree”那不稀奇用 shell 脚本也能做到。它真正值钱的是把并行 AI Agent 工作流里的几个关键环节都串起来了。3.1 一图看懂配置驱动的 Worktree 预定义先看最核心的能力通过配置文件预定义任务类型。安装后我习惯在项目根目录下放一份 .worktrunk.json或者叫 wt.config.jsonWorktrunk 都认举个例子{ baseBranch: main, project: order-service, worktreesDir: ../order-service-agent-workspaces, defaultEnv: { CODE_SEVERITY: high, TEMPERATURE_OVERRIDE: 0.2 }, taskTemplates: { refactor: { idPrefix: ref, base: main, env: { TASK_TYPE: refactor } }, test: { idPrefix: tst, base: main, env: { TASK_TYPE: testing, RUN_ALL_TESTS: true } }, docs: { idPrefix: doc, base: main, env: { TASK_TYPE: documentation } } } }这个文件干了一件很重要的事它把一个“任务的分配规则”和“环境预置参数”绑定在一起。每类任务有独立的目录前缀、基分支、环境变量。Agent 跑起来之前环境就已经就位了。3.2 创建、列出与销毁一套顺手的管理命令配置好之后日常操作基本就四类命令# 1. 创建一个 refactor 类型的任务工作区 worktrunk create refactor 重构订单超时逻辑 # 2. 查看所有 worktree 及其关联状态 worktrunk list # 3. 用完销毁顺便清理空分支 worktrunk destroy ref-20240612-订单超时重构 # 4. 同步远端最新代码到所有 worktree worktrunk sync --fetchcreate 命令跑完之后它会自动完成几个动作计算出任务目录名比如 ref-20240612-order-timeout-refactor按配置中的 baseBranch 分离新分支创建独立工作区目录写入环境变量文件.env.local供后续启动 Agent 使用打印一段提示信息里面包括如何启动对应 Agent 命令的建议整个流程非常像“分配代码空间”而不是“手搓文件夹”。3.3 快照与恢复Agent 回滚的最小成本方案还有一个我最常用的功能snapshot快照。AI Agent 有时候会写出惊为天人的一段代码但这个“惊为天人”是在一顿猛改之后才出现的。问题在于 Agent 的中间过程你回不去。Worktrunk 的 snapshot 机制解决的是这个问题# 在某个 worktree 中标记当前状态为“可回滚点” worktrunk snapshot save 重构后逻辑跑通准备加日志 # 查看历史快照 worktrunk snapshot list # 恢复某个快照 worktrunk snapshot restore --snapshot-ref20240612-183245它本质上是通过在对应 worktree 中创建 git tag 来实现的。但比手动打 tag 多了两个价值第一快照有统一前缀便于搜索第二快照命令会连带记录一条备注信息你想知道“这个 tag 当时是干嘛的”一条命令就能拉出来。这一点在 Agent 高频产出代码的场景下非常有必要。3.4 Codex CLI 等 AI 编程工具的无缝集成这可能是很多用户最感兴趣的一块Worktrunk 怎么跟 Codex CLI 这类 AI 编程工具配合。Codex CLIOpenAI 出的命令行编程 Agent启动时需要指定代码目录和工作上下文。Worktrunk 创建完 worktree 后会自动打印一行类似这样的命令cd ../order-service-agent-workspaces/test-20240612-api-trace-test codex exec 补全支付回调关键链路 trace_id 日志也就是说你不用记住每个 Agent 工作在哪个目录Worktrunk 把目录和任务模板绑定好了它直接按模板内容生成对应的 Codex CLI 调用命令。我实测下来在同一个时间点并行启动三个 Codex 会话分别在三个 worktree 里每个会话访问的是完全独立的工作区git status 互不干扰跑测试也互不影响。这对并行度要求高的场景是非常实用的提升。实际上这种“CLI 工具编排 AI 编程工具”的模式并不复杂但做好的人不多。大多数项目还停在“手动 cd 目录再敲 codex 命令”的阶段Worktrunk 做的是把这两步合成一步还顺手注入了环境变量。4. 实操演示从零开始把 Worktrunk 跑起来4.1 安装与初始化Worktrunk 是 npm 包全局安装即可npm install -g worktrunk worktrunk --version然后在你现有的项目根目录下worktrunk init这个 init 命令会做两件事一是检查当前目录是不是 Git 仓库二是生成一份默认的 .worktrunk.json 配置模板给你改。如果 init 检测到你的 Git 版本低于 2.30它会直接警告你因为低版本 Git 对 worktree 的支持不完整并行场景下容易出现子分支关联错乱的问题。4.2 一次完整的“三个 Agent 并行跑”流程演练我拿一个负责订单服务的模拟项目来演示一遍完整流程。假设项目路径是 ~/projects/order-service远程分支有 main 和 dev 两条主干。第一步初始化配置在项目根目录下写好配置重点是这三个字段baseBranch 指定了默认基于哪个分支分离worktreesDir 配置了 worktree 统一放在上级目录的子文件夹里不推荐放仓库内部否则会出现“仓库套仓库”的问题taskTemplates 定义了三种任务类型{ baseBranch: main, project: order-service, worktreesDir: ../order-service-workspaces, taskTemplates: { agent1-refactor: { idPrefix: ref, base: main, env: { AGENT_ID: refactor-agent } }, agent2-test: { idPrefix: tst, base: main, env: { AGENT_ID: test-agent } }, agent3-doc: { idPrefix: doc, base: main, env: { AGENT_ID: doc-agent } } } }第二步创建三个并行任务工作区cd ~/projects/order-service worktrunk create agent1-refactor 重构订单超时自动关闭逻辑 worktrunk create agent2-test 补充支付回调链路 trace_id 日志与单元测试 worktrunk create agent3-doc 完善 README 中订单状态机 API 说明执行时 Worktrunk 会给每个任务自动生成唯一 ID格式类似 ref-20240612-153001-a3f2。第三步分别在三个终端进入对应目录启动 Agent这边有个经验不要在一个终端里用后台进程方式并行跑多个 Agent生产实践中我见过很多因为输出串流或快捷键冲突搞乱环境的问题。建议开三个独立终端窗口每个窗口只跑一个 Agent这样 Agent 的流式输出不会互相污染。# 终端 A cd ~/projects/order-service-workspaces/ref-20240612-153001-a3f2 codex exec 展开 refactor 计划先输出并确认重构步骤再动手 # 终端 B cd ~/projects/order-service-workspaces/tst-20240612-153200-b9x1 codex exec 为支付回调链路补充 trace_id 日志并运行相关测试 # 终端 C cd ~/projects/order-service-workspaces/doc-20240612-153310-c7k9 codex exec 按 README 模板更新订单状态机说明保留示例代码三个 Agent 并行跑的过程中互相不会看到对方的改动。这在原生 git checkout 切换分支的方案里是做不到的因为你只有一个工作目录、一个 index、一份未提交改动。第四步任务完成后的合并与回收这个阶段也是并行管理最容易出乱子的地方。我的建议是每个 Agent 完成后在其对应 worktree 内把改动提交并推送到远端分支别直接在 main 上合并。# 在对应的 worktree 目录中 git add -A git commit -m refactor: 重构订单超时自动关闭逻辑 git push origin HEAD:refs/for/ref-20240612-153001-a3f2三个分支推上远端后再用 Worktrunk 统一清理本地工作区worktrunk destroy ref-20240612-153001-a3f2 worktrunk destroy tst-20240612-153200-b9x1 worktrunk destroy doc-20240612-153310-c7k9这样本地就不会堆积一堆没用又不舍得删的目录。4.3 参数计算与选择逻辑有些读者可能会问这些目录名、前缀、配额这些东西有什么讲究吗idPrefix 选择短、易辨识、降冲突概率。ref、tst、doc 这种三位前缀就够用没必要用长英文单词。日期时间戳格式统一用 YYYYMMDD-HHMMSS这保证了哪怕同一天反复创建同类任务目录名也不会重复。worktreesDir 放在仓库外这是强制建议别把 worktree 目录放在仓库目录内部否则 Git 会把它当作一个尚未跟踪的文件夹要么让你加 .gitignore要么导致 watch 类工具循环扫描磁盘和 CPU 都遭殃。环境变量隔离不同 Agent 对模型温度、推理强度可能有不同要求通过 taskTemplates 里的 env 字段提前预设好避免每次启动时还要单独写。4.4 非标准场景同一任务类型多个 Agent 并行现实中有个更刁钻的场景三四个 Agent 同时做 refactor 类型任务但改的是不同模块。如果用我上面的配置它们会都从 main 分离然后各自改各自的。这里有一个大坑如果两个 refactor Agent 改了同一个文件谁后提交谁就和别人冲突。Worktrunk 在这个场景下的解决思路是支持在 create 时指定 target 分支比如worktrunk create agent1-refactor 重构用户模块 --target user-service worktrunk create agent1-refactor 重构支付模块 --target payment-service它会默认把 worktree 的基分支指向你指定的 target 分支而不是模板里的 base。实际跑下来这类“同型多 Agent、分模块并行”的冲突概率会明显下降至少不会在同一个文件上彼此覆盖。5. 真实使用中的经验与坑下面这部分是我在这段时间高强度使用 Worktrunk 后总结的几条经验和踩坑实录很多都是文档里找不到的。5.1 坑远端分支混乱第一次用 Worktrunk 并行跑四个 Agent 时我要求每个 Agent 完成后把分支推到远端。结果第四天回来看远端分支列表多了十几个 ref-、tst-、doc-* 分支淹没了正式分支。后来我改用前面演示的做法每个 Agent 只在 worktree 里提交推送时推到 refs/for/ 这种 review 命名空间或者干脆先不推远端等工作区清理前统一确认哪些分支值得留存。Worktrunk 的 destroy 命令也支持 --force真出现“本地分支忘记合并且 worktree 已被删除”的情况时可以去 .git/worktrees 里手动清理残留引用。5.2 坑多个 Agent 写同一份环境变量文件一开始我把环境变量写在项目根目录的 .env 里结果两个 Agent 同时读写把一个 key 覆盖了。排查了半天才发现是这个原因。解决方案就是 Worktrunk 的 env 隔离机制每个 worktree 独立生成一份 .env.local里面只包含该 Agent 任务相关的环境变量。Codex CLI 启动时会优先读取当前目录的 .env.local 而不是全局 .env。这样兼顾了公钥配置放在全局 .env和任务特定配置放在 .env.local的需求。5.3 坑Fast Refresh / 热更新的端口冲突前端项目并行跑 Agent 时经常遇到两个 dev server 端口冲突。Next.js 默认跑 3000两个 worktree 同时启动就会有一个直接报端口占用。经验做法Worktrunk 创建 worktree 时支持通过 taskTemplates 注入 PORT3100 这种变量或者你在启动 Agent 前手动改 package.json 脚本。我在实际中比较喜欢用环境变量方式因为不改代码。{ taskTemplates: { agent1-refactor: { idPrefix: ref, base: main, env: { AGENT_ID: refactor-agent, PORT: 3100 } } } }这样每个 worktree 都有独特的端口互不打架。5.4 经验什么时候不该用 WorktreeWorktrunk 也不是万能药。如果你的项目是单体仓库但各个模块之间严重耦合、一次改动动辄跨三十个文件那么强行把多个 Agent 切成多块并行最后的合并成本可能会高于串行开发。并行化不是免费的。Worktrunk 能确保“物理隔离”但不能替你解决“逻辑耦合”。我的经验是适合用 Worktrunk 并行跑的任务至少有这个特征——任务之间没有共享文件层面的交叠。用人话说就是改订单模块和改支付模块的两个 Agent 不会碰同一个文件。如果两个任务都扎在同一个核心业务文件里那还是排队一个跑完再跑另一个吧。5.5 经验给每个 Agent 建立“任务说明 验收标准”最后一个纯经验向的建议不管用不用 Worktrunk给 AI Agent 输入任务时一定要带上验收标准。我发现很多并行 Agent 最后生成的代码质量差异很大主要原因不是工具不行而是任务描述太含糊。我一般会在 codex exec 的命令里附上这样一段codex exec 重构订单超时自动关闭逻辑。验收标准1) 原有测试全部通过2) 新增两个边界测试用例超时时间无配置、超时时间动态调整3) 不要改动支付模块代码4) 提交信息符合 conventional commits 规范。这样 Agent 就有了一组在操作中可以对照的完成度定义。如果再配合 Worktrunk 的 mock 或 snapshot 功能可以做到“改完、验收、快照、再继续”。这是我觉得并行 AI Agent 工作流里最值得复制的实践。6. 常见问题速查与排查思路在实际使用 Worktrunk 的过程中我还碰到了一些报错和异常情况这里整理成一张速查表方便你快速对照排查。症状可能原因处理方式create 命令报 “invalid worktree path”worktreesDir 指向的目录不存在或没权限手动创建目录后重试或调整配置路径worktrunk list 看到的记录和实际目录对不上有人手动删除了 worktree 目录但没有执行 git worktree prune运行git worktree pruneWorktrunk 会基于新的实际情况重新扫描destroy 命令提示 “worktree has uncommitted changes”worktree 里有未提交改动默认保护机制触发先确认是否有保留价值再使用worktrunk destroy --force强制清理agent 启动后读不到预期的环境变量检查 .env.local 是否生成、是否有拼写错误重新 create 或手动在当前目录 source .env.local热更新/测试端口冲突多个 worktree 使用了相同端口在 taskTemplates 中给每个任务类型派发独立端口合并时出现大量冲突多个 Agent 改动了重叠文件确认任务边界设计必要时调整并行策略串行执行冲突区域任务排查这个表里的问题我先看错误信息再看对应 worktree 目录状态最后才看 Worktrunk 配置。多数问题不是工具本身的 bug而是使用习惯和预期不一致导致的。7. 我个人的一点体会在真正用 Worktrunk 之前我其实花了不少时间在“自己写脚本管理 worktree”上。写过 create.sh、clean.sh、sync.sh也能跑但始终有个问题脚本只能解决我的习惯和我的项目结构换一个仓库、换一个队友脚本就要重新改。Worktrunk 比较聪明的一点是它把“这个仓库有多套 worktree”这件事变成了一个有模板、有约定、可复用的流程。团队新人来了看一遍 .worktrunk.json 就知道这个项目里哪些 Agent 任务在跑、工作区在哪、怎么建新的不用去翻一堆内部文档。最后再分享一个使用技巧我在跑长时间 Agent 任务时会每隔一段时间执行一下worktrunk snapshot save这比依赖 Agent 自己记住状态要可靠得多。之前有次 Agent 跑了一个小时把代码改坏了我靠着快照直接恢复了改坏之前的状态省下了重新梳理上下文的时间。这个习惯某种程度上比工具本身更值钱也推荐你试试。 
长河君 · 2026/9/18 17:09:12 · 阅读 1.2k Worktrunk：并行AI Agent的Git Worktree管理利器
1. 从“一个人写代码”到“一支AI军队”Worktrunk 到底在解决什么问题最近这半年我明显感觉到身边的开发者分成了两拨一拨还在用编辑器自带终端老老实实开分支、切分支、合并另一拨已经让三四个 AI Agent 同时在自己的仓库里干活了速度快到 GitHub 的 contribution 图都快变成实心方块。但你真让三四个 Agent 在同一个 Git 仓库里并行跑任务第一个炸掉的一定不是代码而是分支管理。我自己就栽过大跟头。用 Codex CLI 跑一个重构任务同时在另一个终端里用 Claude Code 做测试用例补全。本来两个任务互不相关结果因为共用了同一个工作目录一个 Agent 把另一个 Agent 生成的文件给 git clean 掉了。更离谱的是有个 Agent 改到一半另一个 Agent 的自动提交直接把半成品推到了远端CI 直接红了一片。后来我开始用 Git Worktree 把这个痛点一个个拆掉但拆完发现又掉进了新的坑——Worktree 本身命令不难难的是在并行 AI Agent 场景下如何把“每个 Agent 一块独立工作区 独立分支 独立环境变量 独立上下文”这套流程管起来。手动敲 git worktree add 敲到第十次的时候我就知道必须找个工具来干这事。这就是Worktrunk出现的理由一个面向并行 AI Agent 工作流的 Git Worktree 管理 CLI。它的核心定位不是替代 Git而是把你脑子里那些“该给哪个 Agent 分哪块地、这块地叫什么名字、用完怎么回收”的管理逻辑固化下来。说白了一句话Worktrunk 就是给 AI Agent 打工的分地管家。这篇文章我主要聊三件事为什么并行 AI Agent 工作流里 Worktree 是刚需Worktrunk 是怎么把它变成一套顺手流程的以及我在真实项目中踩过的坑和总结出来的避坑清单。如果你正在用 Codex CLI、Claude Code 或者任何支持命令行调用的 AI Agent 工具这篇文章值得看完。2. 为什么要用 Worktree并行任务与原生命令的真实摩擦点2.1 一个场景三块碎片假设你现在手头有一个订单服务仓库同时来了三件事订单超时自动关闭逻辑要重构支付回调的日志要补全加上关键链路的 trace_id 追踪给 README 补充 API 文档示例在传统开发模式下你大概率这么干git checkout -b feature/order-timeout写代码写完切回 main再开新分支改日志再切回 main改文档。一切看起来挺顺无非是多切几次分支。但如果你把这三个任务分别交给三个 AI Agent 呢每个 Agent 都需要一份完整代码库都需要一个干净的分支都需要能独立跑测试都需要不想被别人干扰。三个 Agent 在同一个目录里“共处”的唯一结果就是资源竞争和状态污染。Git Worktree 的价值就在这里它允许你在同一个仓库下创建多个工作目录每个目录对应一个独立分支且互不干扰。简单说就是同一个 .git 仓库长出多个独立的工作区树这就是 “worktree”工作树名称的由来。2.2 原生命令的三宗罪那直接用原生的 git worktree 不就行了理论上是但实操起来有三宗罪第一宗罪命令繁琐心智负担重。每次创建都要写全git worktree add -b feature/order-timeout ../orders-timeout main。如果再加上设置环境变量、配置 AI CLI 的上下文目录、启动 Agent 会话一个任务至少五六个步骤。手动操作第三四个任务时心态已经开始崩了。第二宗罪命名全靠自律。不同 Agent 跑任务工作区目录叫什么、分支叫什么、跟哪个基分支分离如果全靠临时拍脑袋隔几天回来看根本不知道哪个目录对应哪个任务。../wip1、../abc、../final_v2这种目录名我在同事电脑上见过不止一次。第三宗罪清理靠胆量。git worktree remove 有个安全机制——如果工作区里有未提交或未跟踪的文件会拒绝删除。这个保护是好意但在 AI Agent 场景下变成了灾难你不确定这个 Agent 有没有留下需要保留的东西又不敢粗暴删最后一堆残留 worktree 堆在那里git worktree list 一拉下来满屏都是记录。2.3 Worktrunk 的解题方向Worktrunk 的思路很简单把这些散落的操作收拢到一个 CLI 工具里用一套“项目级配置 约定优于配置”的方式把创建、分配、清理工作区的流程固化下来。它解决的洞察是当你在并行跑 AI Agent 时你真正需要管理的不是 Git 分支而是每一个 Agent 的运行环境快照。分支只是这个快照的载体之一其他的还包括环境变量比如给 Agent 预设的 API key、会话初始提示词、绑定的远端目标以及任务完成后这个环境是清掉还是保留。为了让后面所有命令演示有明确路径我先声明一下我的实测环境和版本信息操作系统macOS 14.5Apple Silicon相同的流程在 Ubuntu 22.04 上我也验证过Git 版本2.45.1要求不低于 2.30worktree 基础功能和 2.31--track 增强Node.js 版本v20.14.0Worktrunk 本身基于 Node 生态分发安装方式npm 全局安装这也是目前最省事的方式3. 核心功能拆解Worktrunk 真正值钱的四个能力Worktrunk 的功能如果只是封装“创建 worktree”那不稀奇用 shell 脚本也能做到。它真正值钱的是把并行 AI Agent 工作流里的几个关键环节都串起来了。3.1 一图看懂配置驱动的 Worktree 预定义先看最核心的能力通过配置文件预定义任务类型。安装后我习惯在项目根目录下放一份 .worktrunk.json或者叫 wt.config.jsonWorktrunk 都认举个例子{ baseBranch: main, project: order-service, worktreesDir: ../order-service-agent-workspaces, defaultEnv: { CODE_SEVERITY: high, TEMPERATURE_OVERRIDE: 0.2 }, taskTemplates: { refactor: { idPrefix: ref, base: main, env: { TASK_TYPE: refactor } }, test: { idPrefix: tst, base: main, env: { TASK_TYPE: testing, RUN_ALL_TESTS: true } }, docs: { idPrefix: doc, base: main, env: { TASK_TYPE: documentation } } } }这个文件干了一件很重要的事它把一个“任务的分配规则”和“环境预置参数”绑定在一起。每类任务有独立的目录前缀、基分支、环境变量。Agent 跑起来之前环境就已经就位了。3.2 创建、列出与销毁一套顺手的管理命令配置好之后日常操作基本就四类命令# 1. 创建一个 refactor 类型的任务工作区 worktrunk create refactor 重构订单超时逻辑 # 2. 查看所有 worktree 及其关联状态 worktrunk list # 3. 用完销毁顺便清理空分支 worktrunk destroy ref-20240612-订单超时重构 # 4. 同步远端最新代码到所有 worktree worktrunk sync --fetchcreate 命令跑完之后它会自动完成几个动作计算出任务目录名比如 ref-20240612-order-timeout-refactor按配置中的 baseBranch 分离新分支创建独立工作区目录写入环境变量文件.env.local供后续启动 Agent 使用打印一段提示信息里面包括如何启动对应 Agent 命令的建议整个流程非常像“分配代码空间”而不是“手搓文件夹”。3.3 快照与恢复Agent 回滚的最小成本方案还有一个我最常用的功能snapshot快照。AI Agent 有时候会写出惊为天人的一段代码但这个“惊为天人”是在一顿猛改之后才出现的。问题在于 Agent 的中间过程你回不去。Worktrunk 的 snapshot 机制解决的是这个问题# 在某个 worktree 中标记当前状态为“可回滚点” worktrunk snapshot save 重构后逻辑跑通准备加日志 # 查看历史快照 worktrunk snapshot list # 恢复某个快照 worktrunk snapshot restore --snapshot-ref20240612-183245它本质上是通过在对应 worktree 中创建 git tag 来实现的。但比手动打 tag 多了两个价值第一快照有统一前缀便于搜索第二快照命令会连带记录一条备注信息你想知道“这个 tag 当时是干嘛的”一条命令就能拉出来。这一点在 Agent 高频产出代码的场景下非常有必要。3.4 Codex CLI 等 AI 编程工具的无缝集成这可能是很多用户最感兴趣的一块Worktrunk 怎么跟 Codex CLI 这类 AI 编程工具配合。Codex CLIOpenAI 出的命令行编程 Agent启动时需要指定代码目录和工作上下文。Worktrunk 创建完 worktree 后会自动打印一行类似这样的命令cd ../order-service-agent-workspaces/test-20240612-api-trace-test codex exec 补全支付回调关键链路 trace_id 日志也就是说你不用记住每个 Agent 工作在哪个目录Worktrunk 把目录和任务模板绑定好了它直接按模板内容生成对应的 Codex CLI 调用命令。我实测下来在同一个时间点并行启动三个 Codex 会话分别在三个 worktree 里每个会话访问的是完全独立的工作区git status 互不干扰跑测试也互不影响。这对并行度要求高的场景是非常实用的提升。实际上这种“CLI 工具编排 AI 编程工具”的模式并不复杂但做好的人不多。大多数项目还停在“手动 cd 目录再敲 codex 命令”的阶段Worktrunk 做的是把这两步合成一步还顺手注入了环境变量。4. 实操演示从零开始把 Worktrunk 跑起来4.1 安装与初始化Worktrunk 是 npm 包全局安装即可npm install -g worktrunk worktrunk --version然后在你现有的项目根目录下worktrunk init这个 init 命令会做两件事一是检查当前目录是不是 Git 仓库二是生成一份默认的 .worktrunk.json 配置模板给你改。如果 init 检测到你的 Git 版本低于 2.30它会直接警告你因为低版本 Git 对 worktree 的支持不完整并行场景下容易出现子分支关联错乱的问题。4.2 一次完整的“三个 Agent 并行跑”流程演练我拿一个负责订单服务的模拟项目来演示一遍完整流程。假设项目路径是 ~/projects/order-service远程分支有 main 和 dev 两条主干。第一步初始化配置在项目根目录下写好配置重点是这三个字段baseBranch 指定了默认基于哪个分支分离worktreesDir 配置了 worktree 统一放在上级目录的子文件夹里不推荐放仓库内部否则会出现“仓库套仓库”的问题taskTemplates 定义了三种任务类型{ baseBranch: main, project: order-service, worktreesDir: ../order-service-workspaces, taskTemplates: { agent1-refactor: { idPrefix: ref, base: main, env: { AGENT_ID: refactor-agent } }, agent2-test: { idPrefix: tst, base: main, env: { AGENT_ID: test-agent } }, agent3-doc: { idPrefix: doc, base: main, env: { AGENT_ID: doc-agent } } } }第二步创建三个并行任务工作区cd ~/projects/order-service worktrunk create agent1-refactor 重构订单超时自动关闭逻辑 worktrunk create agent2-test 补充支付回调链路 trace_id 日志与单元测试 worktrunk create agent3-doc 完善 README 中订单状态机 API 说明执行时 Worktrunk 会给每个任务自动生成唯一 ID格式类似 ref-20240612-153001-a3f2。第三步分别在三个终端进入对应目录启动 Agent这边有个经验不要在一个终端里用后台进程方式并行跑多个 Agent生产实践中我见过很多因为输出串流或快捷键冲突搞乱环境的问题。建议开三个独立终端窗口每个窗口只跑一个 Agent这样 Agent 的流式输出不会互相污染。# 终端 A cd ~/projects/order-service-workspaces/ref-20240612-153001-a3f2 codex exec 展开 refactor 计划先输出并确认重构步骤再动手 # 终端 B cd ~/projects/order-service-workspaces/tst-20240612-153200-b9x1 codex exec 为支付回调链路补充 trace_id 日志并运行相关测试 # 终端 C cd ~/projects/order-service-workspaces/doc-20240612-153310-c7k9 codex exec 按 README 模板更新订单状态机说明保留示例代码三个 Agent 并行跑的过程中互相不会看到对方的改动。这在原生 git checkout 切换分支的方案里是做不到的因为你只有一个工作目录、一个 index、一份未提交改动。第四步任务完成后的合并与回收这个阶段也是并行管理最容易出乱子的地方。我的建议是每个 Agent 完成后在其对应 worktree 内把改动提交并推送到远端分支别直接在 main 上合并。# 在对应的 worktree 目录中 git add -A git commit -m refactor: 重构订单超时自动关闭逻辑 git push origin HEAD:refs/for/ref-20240612-153001-a3f2三个分支推上远端后再用 Worktrunk 统一清理本地工作区worktrunk destroy ref-20240612-153001-a3f2 worktrunk destroy tst-20240612-153200-b9x1 worktrunk destroy doc-20240612-153310-c7k9这样本地就不会堆积一堆没用又不舍得删的目录。4.3 参数计算与选择逻辑有些读者可能会问这些目录名、前缀、配额这些东西有什么讲究吗idPrefix 选择短、易辨识、降冲突概率。ref、tst、doc 这种三位前缀就够用没必要用长英文单词。日期时间戳格式统一用 YYYYMMDD-HHMMSS这保证了哪怕同一天反复创建同类任务目录名也不会重复。worktreesDir 放在仓库外这是强制建议别把 worktree 目录放在仓库目录内部否则 Git 会把它当作一个尚未跟踪的文件夹要么让你加 .gitignore要么导致 watch 类工具循环扫描磁盘和 CPU 都遭殃。环境变量隔离不同 Agent 对模型温度、推理强度可能有不同要求通过 taskTemplates 里的 env 字段提前预设好避免每次启动时还要单独写。4.4 非标准场景同一任务类型多个 Agent 并行现实中有个更刁钻的场景三四个 Agent 同时做 refactor 类型任务但改的是不同模块。如果用我上面的配置它们会都从 main 分离然后各自改各自的。这里有一个大坑如果两个 refactor Agent 改了同一个文件谁后提交谁就和别人冲突。Worktrunk 在这个场景下的解决思路是支持在 create 时指定 target 分支比如worktrunk create agent1-refactor 重构用户模块 --target user-service worktrunk create agent1-refactor 重构支付模块 --target payment-service它会默认把 worktree 的基分支指向你指定的 target 分支而不是模板里的 base。实际跑下来这类“同型多 Agent、分模块并行”的冲突概率会明显下降至少不会在同一个文件上彼此覆盖。5. 真实使用中的经验与坑下面这部分是我在这段时间高强度使用 Worktrunk 后总结的几条经验和踩坑实录很多都是文档里找不到的。5.1 坑远端分支混乱第一次用 Worktrunk 并行跑四个 Agent 时我要求每个 Agent 完成后把分支推到远端。结果第四天回来看远端分支列表多了十几个 ref-、tst-、doc-* 分支淹没了正式分支。后来我改用前面演示的做法每个 Agent 只在 worktree 里提交推送时推到 refs/for/ 这种 review 命名空间或者干脆先不推远端等工作区清理前统一确认哪些分支值得留存。Worktrunk 的 destroy 命令也支持 --force真出现“本地分支忘记合并且 worktree 已被删除”的情况时可以去 .git/worktrees 里手动清理残留引用。5.2 坑多个 Agent 写同一份环境变量文件一开始我把环境变量写在项目根目录的 .env 里结果两个 Agent 同时读写把一个 key 覆盖了。排查了半天才发现是这个原因。解决方案就是 Worktrunk 的 env 隔离机制每个 worktree 独立生成一份 .env.local里面只包含该 Agent 任务相关的环境变量。Codex CLI 启动时会优先读取当前目录的 .env.local 而不是全局 .env。这样兼顾了公钥配置放在全局 .env和任务特定配置放在 .env.local的需求。5.3 坑Fast Refresh / 热更新的端口冲突前端项目并行跑 Agent 时经常遇到两个 dev server 端口冲突。Next.js 默认跑 3000两个 worktree 同时启动就会有一个直接报端口占用。经验做法Worktrunk 创建 worktree 时支持通过 taskTemplates 注入 PORT3100 这种变量或者你在启动 Agent 前手动改 package.json 脚本。我在实际中比较喜欢用环境变量方式因为不改代码。{ taskTemplates: { agent1-refactor: { idPrefix: ref, base: main, env: { AGENT_ID: refactor-agent, PORT: 3100 } } } }这样每个 worktree 都有独特的端口互不打架。5.4 经验什么时候不该用 WorktreeWorktrunk 也不是万能药。如果你的项目是单体仓库但各个模块之间严重耦合、一次改动动辄跨三十个文件那么强行把多个 Agent 切成多块并行最后的合并成本可能会高于串行开发。并行化不是免费的。Worktrunk 能确保“物理隔离”但不能替你解决“逻辑耦合”。我的经验是适合用 Worktrunk 并行跑的任务至少有这个特征——任务之间没有共享文件层面的交叠。用人话说就是改订单模块和改支付模块的两个 Agent 不会碰同一个文件。如果两个任务都扎在同一个核心业务文件里那还是排队一个跑完再跑另一个吧。5.5 经验给每个 Agent 建立“任务说明 验收标准”最后一个纯经验向的建议不管用不用 Worktrunk给 AI Agent 输入任务时一定要带上验收标准。我发现很多并行 Agent 最后生成的代码质量差异很大主要原因不是工具不行而是任务描述太含糊。我一般会在 codex exec 的命令里附上这样一段codex exec 重构订单超时自动关闭逻辑。验收标准1) 原有测试全部通过2) 新增两个边界测试用例超时时间无配置、超时时间动态调整3) 不要改动支付模块代码4) 提交信息符合 conventional commits 规范。这样 Agent 就有了一组在操作中可以对照的完成度定义。如果再配合 Worktrunk 的 mock 或 snapshot 功能可以做到“改完、验收、快照、再继续”。这是我觉得并行 AI Agent 工作流里最值得复制的实践。6. 常见问题速查与排查思路在实际使用 Worktrunk 的过程中我还碰到了一些报错和异常情况这里整理成一张速查表方便你快速对照排查。症状可能原因处理方式create 命令报 “invalid worktree path”worktreesDir 指向的目录不存在或没权限手动创建目录后重试或调整配置路径worktrunk list 看到的记录和实际目录对不上有人手动删除了 worktree 目录但没有执行 git worktree prune运行git worktree pruneWorktrunk 会基于新的实际情况重新扫描destroy 命令提示 “worktree has uncommitted changes”worktree 里有未提交改动默认保护机制触发先确认是否有保留价值再使用worktrunk destroy --force强制清理agent 启动后读不到预期的环境变量检查 .env.local 是否生成、是否有拼写错误重新 create 或手动在当前目录 source .env.local热更新/测试端口冲突多个 worktree 使用了相同端口在 taskTemplates 中给每个任务类型派发独立端口合并时出现大量冲突多个 Agent 改动了重叠文件确认任务边界设计必要时调整并行策略串行执行冲突区域任务排查这个表里的问题我先看错误信息再看对应 worktree 目录状态最后才看 Worktrunk 配置。多数问题不是工具本身的 bug而是使用习惯和预期不一致导致的。7. 我个人的一点体会在真正用 Worktrunk 之前我其实花了不少时间在“自己写脚本管理 worktree”上。写过 create.sh、clean.sh、sync.sh也能跑但始终有个问题脚本只能解决我的习惯和我的项目结构换一个仓库、换一个队友脚本就要重新改。Worktrunk 比较聪明的一点是它把“这个仓库有多套 worktree”这件事变成了一个有模板、有约定、可复用的流程。团队新人来了看一遍 .worktrunk.json 就知道这个项目里哪些 Agent 任务在跑、工作区在哪、怎么建新的不用去翻一堆内部文档。最后再分享一个使用技巧我在跑长时间 Agent 任务时会每隔一段时间执行一下worktrunk snapshot save这比依赖 Agent 自己记住状态要可靠得多。之前有次 Agent 跑了一个小时把代码改坏了我靠着快照直接恢复了改坏之前的状态省下了重新梳理上下文的时间。这个习惯某种程度上比工具本身更值钱也推荐你试试。