最近这半年我是彻底被 AI Agent 编程助手给惯坏了。Codex 帮我写接口Claude Code 帮我修 bugTrae CLI 帮我跑重构有时候同一时间能开两三个会话。代码产出确实上来了但问题也跟着来了多个 Agent 同时在一个仓库里干活工作目录是同一个分支是同一根改着改着就互相踩脚。你改了 A 文件它以为 A 文件还是旧的你跑测试跑挂了发现是另一个 Agent 的中间状态导致的。这个思路说穿了就一句话每个 Agent 任务一个独立工作树、独立分支互不干扰最后合并回主干。Git Worktree 本身具备这个能力但直接用 git worktree 命令管理一堆任务状态维护、目录命名、清理、上下文注入都很痛苦。Worktrunk 把这些细节封装起来让“为任务开工作区、跑到一半看状态、跑完合并清理”变成几条简单命令。这篇文章会聊清楚它解决什么问题、底层原理怎么配合、我实际是怎么用的以及踩过的坑。1. 项目概述与核心需求解析1.1 并行 AI Agent 工作流到底卡在哪我现在的工作方式基本是给 Codex 或 Claude Code 派一个任务让它自己读代码、改文件、跑测试。单 Agent 的模式很流畅一旦并行起来就全变味了。问题通常出在几个地方。第一多个 Agent 共用一个工作目录时文件状态是错乱的。Agent A 正在改src/api/user.tsAgent B 同时也在看这个文件它读到的是 A 改到一半的中间状态。轻则理解错误重则直接把 A 的修改覆盖掉。AI 模型没有能力区分“这个改动是我做的”和“这个改动是别人刚留下的”因为它本身就活在当前文件系统里。第二分支是同一根语义全乱。如果两个 Agent 都从 main 拉出去改最后都往同一个分支上提交你根本不知道这个分支代表哪个任务。更常见的情况是Agent A 在分支 feature/login 上干活Agent B 因为git checkout操作把整个仓库切到了另一个分支A 的文件瞬间“消失”随后 A 再创建新文件时实际落在了 B 的分支上。这种问题排查起来极其痛苦。第三构建产物和缓存互相污染。Node 项目的node_modules、Python 的__pycache__、编译生成的target/、以及各类日志文件多个 Agent 频繁读写同一套内容经常出现“我这边明明跑过了怎么换个人就挂了”的假性失败。实际上不是代码逻辑问题而是缓存目录被另一个任务改坏了。这三个痛点本质上是同一个根源工作目录没有隔离。人工开发的时候开发者之间有 commit 节奏、有 code review、有权限边界能靠约定和流程避让。AI Agent 的协作能力还没到这个水平它不会主动说“你先改完我再动”所以只能从工程层面强制隔离。1.2 Worktrunk 是什么解决什么问题Worktrunk 就是一个面向并行 AI Agent 工作流的 Git Worktree 管理 CLI。核心思路是给每个 Agent 任务创建一个独立的 worktree 目录和独立分支让所有 Agent 在物理隔离的工作区里干活。它对外暴露的命令围绕“任务”展开而不是围绕 Git 内部概念展开。你在 Worktrunk 里看到的不是“工作树”“引用”“HEAD”而是“创建任务”“查看任务”“进入任务目录”“完成任务”。它把 Git Worktree 的底层操作全部转化成了任务生命周期管理。举一个典型使用过程。你想修一个登录 bug同时加一个导出功能还希望 Agent 并行去做不需要互相等待。传统做法是手动开两个目录、切两个分支、记住每个目录对应哪个任务然后分别把 Codex 或 Claude Code 扔进去。任务一多就乱尤其是过了两天再回头看完全分不清某个 worktree 是为了哪个需求创建的改动是否已经合并。Worktrunk 的做法是worktrunk init worktrunk task create fix-login-bug worktrunk task create add-export worktrunk task list这样就有了两个隔离的工作区。接下来你可以让 Agent A 在 fix-login-bug 目录里修登录让 Agent B 在 add-export 目录里做导出。它们看到的代码基线一模一样但改动互不影响测试互不干扰。跑完之后各自合回主干。所以这个工具解决的核心问题是多 Agent 并行工作时的工作区和分支分配问题。它不改变 Agent 本身的业务能力也不改变 Git 的底层逻辑只是把 Git 已有的能力编排成适合 AI 工作流的样子。1.3 适用场景与目标用户这个工具最适用的场景是那些“任务之间基本不重叠”的并行开发。比如同时修多个独立 bug、同时给几个模块加独立功能、同时跑几个实验性方案对比效果。任务之间的代码交集越小worktree 隔离策略的效果就越明显。不适合的场景也要说清楚如果你的任务本身高度耦合改登录 bug 的时候必须同步改导出模块的依赖那强行拆到两个 worktree 只会增加最后合并的冲突量。这种场景还是让一个 Agent 串行做完更合适。目标用户有两类。第一类是重度 AI 编程用户日常靠 Codex、Claude Code、Trae CLI 这类终端工具写代码并且经常同时开多个会话。第二类是开始搭建“Agent 多机编排”的团队希望把多个 Agent 接入同一个代码仓库做自动化改动但需要一个清晰的隔离和合并机制。2. Git Worktree 原理与选型考量2.1 Git Worktree 是什么和普通分支有什么区别很多人对 Git Worktree 的理解停留在“一个仓库可以开多个分支”这个层面这其实是不准确的。分支只是引用默认情况下一个仓库只有一个工作目录同一时间只能检出一个分支的内容。Git Worktree 是 Git 2.5 引入的功能。它的做法是在一个主仓库的基础上额外创建多个“工作树”。每个工作树有自己独立的目录、独立的索引文件、独立的 HEAD 引用但对象数据库和 refs 引用空间是共享的。用大白话解释主仓库是一棵树的主干每一个 worktree 是独立生长出来的枝条。枝条里的树叶文件可以随便改不影响主干也不影响其他枝条。但所有枝条共享同一个根系对象数据库所以分支、提交记录这些内容是互通的。关键命令就三个git worktree add -b feat-export ../repo-export git worktree list git worktree remove ../repo-exportgit worktree add -b feat-export ../repo-export做的事情是基于当前 HEAD 创建一个新分支 feat-export同时在新路径../repo-export下初始化一份完整的工作目录然后切换到新分支。这个目录里的.git是一个文件内容指向主仓库的.git/worktrees/repo-export目录。所以它不是一个独立仓库而是一个“主仓库的另一个视图”。2.2 为什么用 Git Worktree 而不是 clone 多份仓库最直观的替代方案是git clone多份仓库。但实际对比下来worktree 优势非常明显。对比项Git Worktree多次 Clone磁盘占用只复制工作文件共享 .git 对象库每个仓库都含完整 .git体积成倍上涨拉取新提交主仓库 fetch 一次所有 worktree 同步可见每个 clone 都要分别 fetch分支切换每个 worktree 独立固定在一个分支需要手动维护多个 remote 和分支同步最终合并直接在同一个仓库内 merge简单直接需要加 remote、fetch、再 merge流程冗长资源开销极低几十个 worktree 也没压力每多一个 clone 都是完整仓库复制很早以前我用 clone 方案管理路径和 remote 的心智负担特别重。每个 clone 都要添加 remote、设置 upstream、定期同步 main操作错了还会出现“为什么我改了 A但 B 的代码还是旧的”这种困惑。换成 worktree 以后所有任务共享同一个 fetch 状态新版代码一拉所有 worktree 都能基于最新主分支创建任务。对 AI Agent 工作流来说还有一点很关键worktree 是“一个仓库内的隔离”最终合并时改动粒度很小不需要跨仓库搬运提交。Agent 在各自目录里完成修改后所有提交都在同一个 repo 的引用空间里合并只是普通的git merge。2.3 为什么做成 CLI 而不是编辑器插件有人在设计时问过我为什么不直接做成 VS Code 插件或者 IDE 面板我的判断是AI Agent 工作流的入口在终端不在 IDE。现在的 AI 编程工具比如 Codex CLI、Claude Code、Trae CLI本质都是终端进程。它们天然适合在终端环境里被调度、被脚本化、被环境变量配置。Worktrunk 做成 CLI可以直接作为 Agent 启动命令的前置封装也能被 CI 脚本调用还能被用户手动在任意 shell 里执行。如果做成 IDE 插件功能边界会受限——插件必须依附于 IDE 进程无法单独在终端里驱动 Agent而且用户如果同时用 VS Code 和终端插件就覆盖不全。CLI 是各种工具的公共交集思路最通用维护成本也最低。3. 核心功能设计与实操过程3.1 安装与初始化这个项目我用 Go 写发布方式很简单提供一个静态编译的二进制文件。如果你本地有 Go 环境也可以直接安装go install github.com/yourname/worktrunklatest或者下载对应平台的 release 包解压后把可执行文件放到 PATH 里。Windows 用户注意一下Git for Windows 自带一个git.exeWorktrunk 会通过 PATH 查找它所以 Git 的安装目录必须已经在 PATH 里。之前有用户反馈Codex CLI 安装完之后在 CMD 里codex --version正常但换到 Windows Terminal 就提示找不到原因就是两个终端的 PATH 环境变量不一致同步解决就好。初始化非常简单在已有的 Git 仓库根目录执行worktrunk init运行后会有以下效果检查当前目录是否是一个 Git 仓库创建.worktrunk/目录用于存放状态配置和任务索引默认把 worktree 统一放在.worktrunk/worktrees/下保证所有工作区集中管理不乱撒生成config.yaml里面记录主仓库路径、worktree 根目录、默认主分支名等信息。config.yaml内容类似这样repo: /home/user/projects/myapp worktree_dir: .worktrunk/worktrees main_branch: main完成 init 后这个仓库就具备并行任务管理能力了。3.2 创建和管理并行任务工作区创建任务的命令是worktrunk task create fix-login-bug这个命令背后做的事情比看起来复杂。Worktrunk 会先检查任务名是否冲突然后在.worktrunk/worktrees/fix-login-bug路径下执行git worktree add -b fix-login-bug最后把任务信息写入状态文件记录“任务名、分支名、worktree 路径、创建时间、当前状态”。如果你想指定其他目录也可以加参数。但我平时建议直接用默认结构因为 Worktrunk 的所有命令都是按默认结构设计的强行自定义路径会增加认知负担。创建完两个任务后目录结构大概长这样myapp/ ├── .worktrunk/ │ ├── config.yaml │ ├── state.yaml │ └── worktrees/ │ ├── fix-login-bug/ │ └── add-export/ ├── src/ ├── tests/ └── README.md主仓库根目录仍然保持干净两个任务工作区都在.worktrunk/worktrees/下面。git status不会显示这些 worktree 的改动因为它们是独立工作目录对主仓库来说只是普通的未跟踪目录。任务列表一眼就能看全worktrunk task list输出类似NAME BRANCH PATH STATUS fix-login-bug fix-login-bug .worktrunk/worktrees/fix-login-bug active add-export add-export .worktrunk/worktrees/add-export active切到某个任务的工作目录worktrunk task go fix-login-bug这个命令本质上是在子 shell 里切目录但它同时做了另一件事写入环境变量标识当前处于哪个任务。这样后续在目录里执行任何命令都可以感知到任务上下文。3.3 与 AI Agent 的上下文联动Worktrunk 和一个普通的工作目录管理工具最大的区别就在这里它能和 Agent 启动流程打通。我通常这样启动 Agentworktrunk task run fix-login-bug -- codex这条命令会完成三件事把当前工作目录切换到 fix-login-bug 的 worktree设置环境变量WORKTRUNK_TASK_IDfix-login-bug、WORKTRUNK_BRANCHfix-login-bug在设置好的环境里执行codex命令。为什么多这一步很重要因为 AI Agent 是无状态的程序它只能感知到当前进程的工作目录和环境变量。如果你直接手动cd到某个目录再启动 CodexAgent 并不知道自己属于哪个任务、要往哪个分支提交。Worktrunk 把任务标识和分支信息注入环境Agent 就能在初始化时读取这些信息更精准地理解自己的“工作边界”。我在配置 Agent 时会把提示词模板写成这样你现在正在执行任务 $WORKTRUNK_TASK_ID。 工作分支是 $WORKTRUNK_BRANCH。 请只修改当前工作目录下的文件不要尝试切换分支。 完成修改后优先提交到当前分支。这种做法有几个直接好处。第一Agent 知道自己的目标分支不会乱 checkout第二如果工作区里同时有多个目录Agent 也能定位到自己负责的位置第三提交信息可以自动带上任务名方便后续合并和回溯。如果你用的是 Claude Code 或 Trae CLI也是一样的套路。因为终端 AI 工具都遵循“当前目录即上下文”的原则只要目录隔离得干净Agent 的行为就会收敛到自己的任务范围内。3.4 任务收尾与清理Agent 完成任务后收尾流程是worktrunk task finish fix-login-bug这条命令内部会依次做几件事进入任务 worktree检查是否有未提交的改动如果有会提示你是否先提交或者用--force跳过把任务分支切回主分支比如 main在保证没有未提交内容的情况下删除 worktree 目录清理任务状态记录。如果你希望把改动合并进主分支可以加参数worktrunk task finish fix-login-bug --merge它会额外执行一次git merge fix-login-bug把任务分支合并到主分支然后再清理。这个方式比较适合“任务完成且验证通过”的场景。还有一条命令值得说worktrunk task status它会遍历所有活跃任务列出每个任务里是否存在未提交改动、落后主分支多少提交、领先主分支多少提交。这个视图在并行多 Agent 的时候特别重要——你能快速看出哪些任务还在跑哪些已经安静下来可以收尾了。4. 常见问题与排查技巧实录4.1 我踩过的几个坑Worktrunk 本身是薄封装踩的坑大多来自 Git Worktree 的特性。第一个坑是删除 worktree 时如果目录里有未提交改动或未跟踪文件git worktree remove会直接拒绝。这个保护机制很合理但对 Agent 工作流来说很烦因为 Agent 经常会在工作目录里生成日志、临时文件、未跟踪的产物。解决办法是使用--force参数或者先手动清理生成物目录。第二个坑是主仓库目录绝对不能误删。Worktrunk 的所有 worktree 都依赖主仓库的.git/worktrees目录。如果主仓库被删了所有 worktree 全部失效里面的改动虽然文件还在但所有 Git 历史都会脱离仓库上下文。这个风险在多人协作时尤其要注意。我目前的做法是把主仓库目录放到一个不太容易被误操作的位置并且用 Worktrunk 的配置明确标注主仓库路径。第三个坑和构建缓存有关。Worktrunk 隔离了代码目录但依赖目录如果被每个 worktree 单独安装一遍磁盘开销会很大如果共享同一个依赖目录又会有两个 Agent 同时写node_modules的风险。我目前的方案是独立的高频构建目录放 worktree 内比如node_modules、target、build这些各自维护低频的大件产物放外部共享目录只读挂载。具体取舍看项目规模但一定要让每个 worktree 的构建环境保持自洽。第四个坑是 Agent 的配置文件分散在各处。Codex 的配置可能在~/.codex/或项目根目录Claude Code 的权限配置也可能放在项目级。如果 Agent 在 worktree 里读不到项目根目录的.claude/配置行为会跟预期不符。Worktrunk 目前会把主仓库根目录下的 Agent 配置文件做个软链接到 worktree 里确保 Agent 启动时能拿到一致的配置又不会互相污染。4.2 常见问题速查表现象原因解决办法git worktree add报“already exists”分支名或路径已被占用git worktree list查看现有 worktree删除旧记录删除 worktree 时提示有未提交更改Agent 留下的临时文件/改动先人工确认内容再用worktrunk task finish --force主仓库git status看不到 worktree 改动这是正常现象worktree 是独立工作树用worktrunk task status查看每个任务状态执行codex时报 “unable to locate the codex cli binary”Codex CLI 未加入 PATH 或缺少 runtime 组件检查二进制路径、环境变量确保 shell 和终端使用同一套 PATH两个任务都改了同一个文件合并时冲突任务分工没有划清边界用冲突标记手工解决后续分配任务时按模块拆分git worktree prune误删了目录worktree 元数据与目录失联尽量使用 Worktrunk 的task destroy不要手动 prune4.3 排查思路与建议如果任务状态乱了第一件事永远是查状态文件而不是乱猜。Worktrunk 的所有状态都记录在.worktrunk/state.yaml里打开它就能看到每个 worktree 对应的任务名、分支名、路径和状态。即使某个命令出错、目录失联状态文件也能把线索摆出来。如果是分支合并冲突建议先看冲突文件涉及哪些模块。如果冲突集中在一两个文件直接手工解决如果十几个文件全是冲突说明任务边界划分有问题不要硬 merge应该找业务负责人重新拆分。另外给并行 Agent 工作流一句忠告worktree 隔离解决的是“工作目录互相踩踏”的问题解决不了“业务逻辑互相依赖”的问题。任务拆分越独立worktree 方案的效果越好。我见过不少人把 Worktrunk 当成万能隔离工具用之后冲突比之前还多——核心原因就是任务本身就是高度耦合的拆到多个目录只是把即时冲突延后到了 merge 阶段。5. 内部实现与设计取舍5.1 状态存储与命令流程Worktrunk 的内部设计比较朴素核心是状态文件和 Git 命令的调度。状态文件用 YAML 记录每次创建任务都会更新tasks: - name: fix-login-bug branch: fix-login-bug path: .worktrunk/worktrees/fix-login-bug status: active created_at: 2025-01-10T10:00:00Z所有命令的执行流程都是读状态 - 解析参数 - 调用 Git 命令 - 更新状态。用 Go 实现的好处是编译成单个二进制不依赖 Python 或 Node 运行时交给 Agent 或 CI 使用都干净。对于并发场景我还给状态文件加了一个文件锁。因为有可能两个 Agent 同时发起任务创建或状态更新如果没有锁机制状态文件可能会被写坏。锁实现用的是操作系统的文件锁机制简单的 flock 就能搞定没必要引入外部服务。5.2 为什么不用纯 Shell 脚本有人提过这套功能用 Shell 脚本也能实现为什么要专门写一个 Go 项目原因有三层。第一层是跨平台。Shell 脚本在 macOS 和 Linux 上表现良好但在 Windows 上会很痛苦路径分隔符、命令行为差异、Git bash 和 CMD 的问题都不好处理。Go 可以交叉编译出三个平台的二进制维护成本更低。第二层是状态管理。Shell 脚本处理 YAML 读写和并发加锁要依赖外部工具做得再深也没有原生语言方便。而且 Shell 脚本报错信息很简陋Agent 在终端里看到错误往往不知道怎么处理。Go 的错误处理更清晰能给出带上下文提示的报错信息。第三层是可测试性和扩展性。Worktrunk 后续要接入任务调度、配额管理、Agent 日志收集这些能力Shell 脚本会变得越来越难维护。用 Go 写能针对命令流程做单元测试和集成测试也更容易扩展。5.3 后续值得扩展的方向目前 Worktrunk 已经能支撑我日常的并行 Agent 工作流但我认为还有几个方向值得继续做。第一个是任务配额管理。现在所有任务都允许任意创建但 Agent 并行太多会导致机器资源被吃满。可以给每个项目设置最大并行数任务创建时检查当前活跃任务数量超过上限就排队或拒绝。第二个是 Agent 日志收集。每个 worktree 里的 Agent 命令输出可以自动归档到.worktrunk/logs/task.log这样即使任务结束后也能回溯这个任务到底发生了什么。第三个是自动合并策略。对“改动小、测试通过、冲突概率低”的任务可以自动执行 merge 并删除 worktree。当然这个功能要先做严格的安全检查不能把没有验证过的改动直接合进主干。回到开头那个问题并行 AI Agent 工作流最大的敌人不是 Agent 能力不够而是多个进程在同一个物理环境里互相干扰。Git Worktree 提供了隔离的物理环境Worktrunk 则在上面加了一层任务语义让“开工作区、跑任务、收尾合并”变得可以管理。最后分享一个我自己的切身体会。这套工具用了两个多月最大的收获不是命令多好用而是它倒逼我把任务拆得更细了。以前我给 Agent 派活经常是一大坨需求丢过去现在因为要创建独立 worktree必须先想清楚这个任务的边界在哪里、改哪些模块、和谁可能有交集。想不清楚就拆不开拆不开就并行不起来。这个思路本身可能比任何工具都更值钱。
Worktrunk：用Git Worktree隔离并行AI Agent工作流
最近这半年我是彻底被 AI Agent 编程助手给惯坏了。Codex 帮我写接口Claude Code 帮我修 bugTrae CLI 帮我跑重构有时候同一时间能开两三个会话。代码产出确实上来了但问题也跟着来了多个 Agent 同时在一个仓库里干活工作目录是同一个分支是同一根改着改着就互相踩脚。你改了 A 文件它以为 A 文件还是旧的你跑测试跑挂了发现是另一个 Agent 的中间状态导致的。这个思路说穿了就一句话每个 Agent 任务一个独立工作树、独立分支互不干扰最后合并回主干。Git Worktree 本身具备这个能力但直接用 git worktree 命令管理一堆任务状态维护、目录命名、清理、上下文注入都很痛苦。Worktrunk 把这些细节封装起来让“为任务开工作区、跑到一半看状态、跑完合并清理”变成几条简单命令。这篇文章会聊清楚它解决什么问题、底层原理怎么配合、我实际是怎么用的以及踩过的坑。1. 项目概述与核心需求解析1.1 并行 AI Agent 工作流到底卡在哪我现在的工作方式基本是给 Codex 或 Claude Code 派一个任务让它自己读代码、改文件、跑测试。单 Agent 的模式很流畅一旦并行起来就全变味了。问题通常出在几个地方。第一多个 Agent 共用一个工作目录时文件状态是错乱的。Agent A 正在改src/api/user.tsAgent B 同时也在看这个文件它读到的是 A 改到一半的中间状态。轻则理解错误重则直接把 A 的修改覆盖掉。AI 模型没有能力区分“这个改动是我做的”和“这个改动是别人刚留下的”因为它本身就活在当前文件系统里。第二分支是同一根语义全乱。如果两个 Agent 都从 main 拉出去改最后都往同一个分支上提交你根本不知道这个分支代表哪个任务。更常见的情况是Agent A 在分支 feature/login 上干活Agent B 因为git checkout操作把整个仓库切到了另一个分支A 的文件瞬间“消失”随后 A 再创建新文件时实际落在了 B 的分支上。这种问题排查起来极其痛苦。第三构建产物和缓存互相污染。Node 项目的node_modules、Python 的__pycache__、编译生成的target/、以及各类日志文件多个 Agent 频繁读写同一套内容经常出现“我这边明明跑过了怎么换个人就挂了”的假性失败。实际上不是代码逻辑问题而是缓存目录被另一个任务改坏了。这三个痛点本质上是同一个根源工作目录没有隔离。人工开发的时候开发者之间有 commit 节奏、有 code review、有权限边界能靠约定和流程避让。AI Agent 的协作能力还没到这个水平它不会主动说“你先改完我再动”所以只能从工程层面强制隔离。1.2 Worktrunk 是什么解决什么问题Worktrunk 就是一个面向并行 AI Agent 工作流的 Git Worktree 管理 CLI。核心思路是给每个 Agent 任务创建一个独立的 worktree 目录和独立分支让所有 Agent 在物理隔离的工作区里干活。它对外暴露的命令围绕“任务”展开而不是围绕 Git 内部概念展开。你在 Worktrunk 里看到的不是“工作树”“引用”“HEAD”而是“创建任务”“查看任务”“进入任务目录”“完成任务”。它把 Git Worktree 的底层操作全部转化成了任务生命周期管理。举一个典型使用过程。你想修一个登录 bug同时加一个导出功能还希望 Agent 并行去做不需要互相等待。传统做法是手动开两个目录、切两个分支、记住每个目录对应哪个任务然后分别把 Codex 或 Claude Code 扔进去。任务一多就乱尤其是过了两天再回头看完全分不清某个 worktree 是为了哪个需求创建的改动是否已经合并。Worktrunk 的做法是worktrunk init worktrunk task create fix-login-bug worktrunk task create add-export worktrunk task list这样就有了两个隔离的工作区。接下来你可以让 Agent A 在 fix-login-bug 目录里修登录让 Agent B 在 add-export 目录里做导出。它们看到的代码基线一模一样但改动互不影响测试互不干扰。跑完之后各自合回主干。所以这个工具解决的核心问题是多 Agent 并行工作时的工作区和分支分配问题。它不改变 Agent 本身的业务能力也不改变 Git 的底层逻辑只是把 Git 已有的能力编排成适合 AI 工作流的样子。1.3 适用场景与目标用户这个工具最适用的场景是那些“任务之间基本不重叠”的并行开发。比如同时修多个独立 bug、同时给几个模块加独立功能、同时跑几个实验性方案对比效果。任务之间的代码交集越小worktree 隔离策略的效果就越明显。不适合的场景也要说清楚如果你的任务本身高度耦合改登录 bug 的时候必须同步改导出模块的依赖那强行拆到两个 worktree 只会增加最后合并的冲突量。这种场景还是让一个 Agent 串行做完更合适。目标用户有两类。第一类是重度 AI 编程用户日常靠 Codex、Claude Code、Trae CLI 这类终端工具写代码并且经常同时开多个会话。第二类是开始搭建“Agent 多机编排”的团队希望把多个 Agent 接入同一个代码仓库做自动化改动但需要一个清晰的隔离和合并机制。2. Git Worktree 原理与选型考量2.1 Git Worktree 是什么和普通分支有什么区别很多人对 Git Worktree 的理解停留在“一个仓库可以开多个分支”这个层面这其实是不准确的。分支只是引用默认情况下一个仓库只有一个工作目录同一时间只能检出一个分支的内容。Git Worktree 是 Git 2.5 引入的功能。它的做法是在一个主仓库的基础上额外创建多个“工作树”。每个工作树有自己独立的目录、独立的索引文件、独立的 HEAD 引用但对象数据库和 refs 引用空间是共享的。用大白话解释主仓库是一棵树的主干每一个 worktree 是独立生长出来的枝条。枝条里的树叶文件可以随便改不影响主干也不影响其他枝条。但所有枝条共享同一个根系对象数据库所以分支、提交记录这些内容是互通的。关键命令就三个git worktree add -b feat-export ../repo-export git worktree list git worktree remove ../repo-exportgit worktree add -b feat-export ../repo-export做的事情是基于当前 HEAD 创建一个新分支 feat-export同时在新路径../repo-export下初始化一份完整的工作目录然后切换到新分支。这个目录里的.git是一个文件内容指向主仓库的.git/worktrees/repo-export目录。所以它不是一个独立仓库而是一个“主仓库的另一个视图”。2.2 为什么用 Git Worktree 而不是 clone 多份仓库最直观的替代方案是git clone多份仓库。但实际对比下来worktree 优势非常明显。对比项Git Worktree多次 Clone磁盘占用只复制工作文件共享 .git 对象库每个仓库都含完整 .git体积成倍上涨拉取新提交主仓库 fetch 一次所有 worktree 同步可见每个 clone 都要分别 fetch分支切换每个 worktree 独立固定在一个分支需要手动维护多个 remote 和分支同步最终合并直接在同一个仓库内 merge简单直接需要加 remote、fetch、再 merge流程冗长资源开销极低几十个 worktree 也没压力每多一个 clone 都是完整仓库复制很早以前我用 clone 方案管理路径和 remote 的心智负担特别重。每个 clone 都要添加 remote、设置 upstream、定期同步 main操作错了还会出现“为什么我改了 A但 B 的代码还是旧的”这种困惑。换成 worktree 以后所有任务共享同一个 fetch 状态新版代码一拉所有 worktree 都能基于最新主分支创建任务。对 AI Agent 工作流来说还有一点很关键worktree 是“一个仓库内的隔离”最终合并时改动粒度很小不需要跨仓库搬运提交。Agent 在各自目录里完成修改后所有提交都在同一个 repo 的引用空间里合并只是普通的git merge。2.3 为什么做成 CLI 而不是编辑器插件有人在设计时问过我为什么不直接做成 VS Code 插件或者 IDE 面板我的判断是AI Agent 工作流的入口在终端不在 IDE。现在的 AI 编程工具比如 Codex CLI、Claude Code、Trae CLI本质都是终端进程。它们天然适合在终端环境里被调度、被脚本化、被环境变量配置。Worktrunk 做成 CLI可以直接作为 Agent 启动命令的前置封装也能被 CI 脚本调用还能被用户手动在任意 shell 里执行。如果做成 IDE 插件功能边界会受限——插件必须依附于 IDE 进程无法单独在终端里驱动 Agent而且用户如果同时用 VS Code 和终端插件就覆盖不全。CLI 是各种工具的公共交集思路最通用维护成本也最低。3. 核心功能设计与实操过程3.1 安装与初始化这个项目我用 Go 写发布方式很简单提供一个静态编译的二进制文件。如果你本地有 Go 环境也可以直接安装go install github.com/yourname/worktrunklatest或者下载对应平台的 release 包解压后把可执行文件放到 PATH 里。Windows 用户注意一下Git for Windows 自带一个git.exeWorktrunk 会通过 PATH 查找它所以 Git 的安装目录必须已经在 PATH 里。之前有用户反馈Codex CLI 安装完之后在 CMD 里codex --version正常但换到 Windows Terminal 就提示找不到原因就是两个终端的 PATH 环境变量不一致同步解决就好。初始化非常简单在已有的 Git 仓库根目录执行worktrunk init运行后会有以下效果检查当前目录是否是一个 Git 仓库创建.worktrunk/目录用于存放状态配置和任务索引默认把 worktree 统一放在.worktrunk/worktrees/下保证所有工作区集中管理不乱撒生成config.yaml里面记录主仓库路径、worktree 根目录、默认主分支名等信息。config.yaml内容类似这样repo: /home/user/projects/myapp worktree_dir: .worktrunk/worktrees main_branch: main完成 init 后这个仓库就具备并行任务管理能力了。3.2 创建和管理并行任务工作区创建任务的命令是worktrunk task create fix-login-bug这个命令背后做的事情比看起来复杂。Worktrunk 会先检查任务名是否冲突然后在.worktrunk/worktrees/fix-login-bug路径下执行git worktree add -b fix-login-bug最后把任务信息写入状态文件记录“任务名、分支名、worktree 路径、创建时间、当前状态”。如果你想指定其他目录也可以加参数。但我平时建议直接用默认结构因为 Worktrunk 的所有命令都是按默认结构设计的强行自定义路径会增加认知负担。创建完两个任务后目录结构大概长这样myapp/ ├── .worktrunk/ │ ├── config.yaml │ ├── state.yaml │ └── worktrees/ │ ├── fix-login-bug/ │ └── add-export/ ├── src/ ├── tests/ └── README.md主仓库根目录仍然保持干净两个任务工作区都在.worktrunk/worktrees/下面。git status不会显示这些 worktree 的改动因为它们是独立工作目录对主仓库来说只是普通的未跟踪目录。任务列表一眼就能看全worktrunk task list输出类似NAME BRANCH PATH STATUS fix-login-bug fix-login-bug .worktrunk/worktrees/fix-login-bug active add-export add-export .worktrunk/worktrees/add-export active切到某个任务的工作目录worktrunk task go fix-login-bug这个命令本质上是在子 shell 里切目录但它同时做了另一件事写入环境变量标识当前处于哪个任务。这样后续在目录里执行任何命令都可以感知到任务上下文。3.3 与 AI Agent 的上下文联动Worktrunk 和一个普通的工作目录管理工具最大的区别就在这里它能和 Agent 启动流程打通。我通常这样启动 Agentworktrunk task run fix-login-bug -- codex这条命令会完成三件事把当前工作目录切换到 fix-login-bug 的 worktree设置环境变量WORKTRUNK_TASK_IDfix-login-bug、WORKTRUNK_BRANCHfix-login-bug在设置好的环境里执行codex命令。为什么多这一步很重要因为 AI Agent 是无状态的程序它只能感知到当前进程的工作目录和环境变量。如果你直接手动cd到某个目录再启动 CodexAgent 并不知道自己属于哪个任务、要往哪个分支提交。Worktrunk 把任务标识和分支信息注入环境Agent 就能在初始化时读取这些信息更精准地理解自己的“工作边界”。我在配置 Agent 时会把提示词模板写成这样你现在正在执行任务 $WORKTRUNK_TASK_ID。 工作分支是 $WORKTRUNK_BRANCH。 请只修改当前工作目录下的文件不要尝试切换分支。 完成修改后优先提交到当前分支。这种做法有几个直接好处。第一Agent 知道自己的目标分支不会乱 checkout第二如果工作区里同时有多个目录Agent 也能定位到自己负责的位置第三提交信息可以自动带上任务名方便后续合并和回溯。如果你用的是 Claude Code 或 Trae CLI也是一样的套路。因为终端 AI 工具都遵循“当前目录即上下文”的原则只要目录隔离得干净Agent 的行为就会收敛到自己的任务范围内。3.4 任务收尾与清理Agent 完成任务后收尾流程是worktrunk task finish fix-login-bug这条命令内部会依次做几件事进入任务 worktree检查是否有未提交的改动如果有会提示你是否先提交或者用--force跳过把任务分支切回主分支比如 main在保证没有未提交内容的情况下删除 worktree 目录清理任务状态记录。如果你希望把改动合并进主分支可以加参数worktrunk task finish fix-login-bug --merge它会额外执行一次git merge fix-login-bug把任务分支合并到主分支然后再清理。这个方式比较适合“任务完成且验证通过”的场景。还有一条命令值得说worktrunk task status它会遍历所有活跃任务列出每个任务里是否存在未提交改动、落后主分支多少提交、领先主分支多少提交。这个视图在并行多 Agent 的时候特别重要——你能快速看出哪些任务还在跑哪些已经安静下来可以收尾了。4. 常见问题与排查技巧实录4.1 我踩过的几个坑Worktrunk 本身是薄封装踩的坑大多来自 Git Worktree 的特性。第一个坑是删除 worktree 时如果目录里有未提交改动或未跟踪文件git worktree remove会直接拒绝。这个保护机制很合理但对 Agent 工作流来说很烦因为 Agent 经常会在工作目录里生成日志、临时文件、未跟踪的产物。解决办法是使用--force参数或者先手动清理生成物目录。第二个坑是主仓库目录绝对不能误删。Worktrunk 的所有 worktree 都依赖主仓库的.git/worktrees目录。如果主仓库被删了所有 worktree 全部失效里面的改动虽然文件还在但所有 Git 历史都会脱离仓库上下文。这个风险在多人协作时尤其要注意。我目前的做法是把主仓库目录放到一个不太容易被误操作的位置并且用 Worktrunk 的配置明确标注主仓库路径。第三个坑和构建缓存有关。Worktrunk 隔离了代码目录但依赖目录如果被每个 worktree 单独安装一遍磁盘开销会很大如果共享同一个依赖目录又会有两个 Agent 同时写node_modules的风险。我目前的方案是独立的高频构建目录放 worktree 内比如node_modules、target、build这些各自维护低频的大件产物放外部共享目录只读挂载。具体取舍看项目规模但一定要让每个 worktree 的构建环境保持自洽。第四个坑是 Agent 的配置文件分散在各处。Codex 的配置可能在~/.codex/或项目根目录Claude Code 的权限配置也可能放在项目级。如果 Agent 在 worktree 里读不到项目根目录的.claude/配置行为会跟预期不符。Worktrunk 目前会把主仓库根目录下的 Agent 配置文件做个软链接到 worktree 里确保 Agent 启动时能拿到一致的配置又不会互相污染。4.2 常见问题速查表现象原因解决办法git worktree add报“already exists”分支名或路径已被占用git worktree list查看现有 worktree删除旧记录删除 worktree 时提示有未提交更改Agent 留下的临时文件/改动先人工确认内容再用worktrunk task finish --force主仓库git status看不到 worktree 改动这是正常现象worktree 是独立工作树用worktrunk task status查看每个任务状态执行codex时报 “unable to locate the codex cli binary”Codex CLI 未加入 PATH 或缺少 runtime 组件检查二进制路径、环境变量确保 shell 和终端使用同一套 PATH两个任务都改了同一个文件合并时冲突任务分工没有划清边界用冲突标记手工解决后续分配任务时按模块拆分git worktree prune误删了目录worktree 元数据与目录失联尽量使用 Worktrunk 的task destroy不要手动 prune4.3 排查思路与建议如果任务状态乱了第一件事永远是查状态文件而不是乱猜。Worktrunk 的所有状态都记录在.worktrunk/state.yaml里打开它就能看到每个 worktree 对应的任务名、分支名、路径和状态。即使某个命令出错、目录失联状态文件也能把线索摆出来。如果是分支合并冲突建议先看冲突文件涉及哪些模块。如果冲突集中在一两个文件直接手工解决如果十几个文件全是冲突说明任务边界划分有问题不要硬 merge应该找业务负责人重新拆分。另外给并行 Agent 工作流一句忠告worktree 隔离解决的是“工作目录互相踩踏”的问题解决不了“业务逻辑互相依赖”的问题。任务拆分越独立worktree 方案的效果越好。我见过不少人把 Worktrunk 当成万能隔离工具用之后冲突比之前还多——核心原因就是任务本身就是高度耦合的拆到多个目录只是把即时冲突延后到了 merge 阶段。5. 内部实现与设计取舍5.1 状态存储与命令流程Worktrunk 的内部设计比较朴素核心是状态文件和 Git 命令的调度。状态文件用 YAML 记录每次创建任务都会更新tasks: - name: fix-login-bug branch: fix-login-bug path: .worktrunk/worktrees/fix-login-bug status: active created_at: 2025-01-10T10:00:00Z所有命令的执行流程都是读状态 - 解析参数 - 调用 Git 命令 - 更新状态。用 Go 实现的好处是编译成单个二进制不依赖 Python 或 Node 运行时交给 Agent 或 CI 使用都干净。对于并发场景我还给状态文件加了一个文件锁。因为有可能两个 Agent 同时发起任务创建或状态更新如果没有锁机制状态文件可能会被写坏。锁实现用的是操作系统的文件锁机制简单的 flock 就能搞定没必要引入外部服务。5.2 为什么不用纯 Shell 脚本有人提过这套功能用 Shell 脚本也能实现为什么要专门写一个 Go 项目原因有三层。第一层是跨平台。Shell 脚本在 macOS 和 Linux 上表现良好但在 Windows 上会很痛苦路径分隔符、命令行为差异、Git bash 和 CMD 的问题都不好处理。Go 可以交叉编译出三个平台的二进制维护成本更低。第二层是状态管理。Shell 脚本处理 YAML 读写和并发加锁要依赖外部工具做得再深也没有原生语言方便。而且 Shell 脚本报错信息很简陋Agent 在终端里看到错误往往不知道怎么处理。Go 的错误处理更清晰能给出带上下文提示的报错信息。第三层是可测试性和扩展性。Worktrunk 后续要接入任务调度、配额管理、Agent 日志收集这些能力Shell 脚本会变得越来越难维护。用 Go 写能针对命令流程做单元测试和集成测试也更容易扩展。5.3 后续值得扩展的方向目前 Worktrunk 已经能支撑我日常的并行 Agent 工作流但我认为还有几个方向值得继续做。第一个是任务配额管理。现在所有任务都允许任意创建但 Agent 并行太多会导致机器资源被吃满。可以给每个项目设置最大并行数任务创建时检查当前活跃任务数量超过上限就排队或拒绝。第二个是 Agent 日志收集。每个 worktree 里的 Agent 命令输出可以自动归档到.worktrunk/logs/task.log这样即使任务结束后也能回溯这个任务到底发生了什么。第三个是自动合并策略。对“改动小、测试通过、冲突概率低”的任务可以自动执行 merge 并删除 worktree。当然这个功能要先做严格的安全检查不能把没有验证过的改动直接合进主干。回到开头那个问题并行 AI Agent 工作流最大的敌人不是 Agent 能力不够而是多个进程在同一个物理环境里互相干扰。Git Worktree 提供了隔离的物理环境Worktrunk 则在上面加了一层任务语义让“开工作区、跑任务、收尾合并”变得可以管理。最后分享一个我自己的切身体会。这套工具用了两个多月最大的收获不是命令多好用而是它倒逼我把任务拆得更细了。以前我给 Agent 派活经常是一大坨需求丢过去现在因为要创建独立 worktree必须先想清楚这个任务的边界在哪里、改哪些模块、和谁可能有交集。想不清楚就拆不开拆不开就并行不起来。这个思路本身可能比任何工具都更值钱。