前阵子我同时开了三个 AI 编程任务让 Agent 在同一个仓库里改代码一个重构工具函数一个加登录功能一个修崩溃 bug。结果不到半小时仓库就被折腾得一塌糊涂——三个任务各自切分支、互相覆盖工作区合并的时候冲突多到让人想摔键盘。后来我彻底换了思路与其教多个 Agent 在同一个工作区里保持“默契”不如直接给它们一人一个独立工作区这就是 Git Worktree 的用法。Git Worktree 本身不是新东西但真正让它发挥价值的是配合 AI Agent 并行开发的场景。于是我把这套流程封装成了一个命令行工具 Worktrunk一条命令创建任务工作区一条命令查看所有 Agent 的工作状态一条命令把结果合回主线。这篇内容适合正在用 Codex CLI、Claude Code CLI 这类 AI 编程助手做实际项目又被多任务并行折腾得头疼的开发者。我会把原理、设计思路和完整实操流程都拆开讲清楚包括那些文档里不会写的坑。1. 并行 Agent 开发的核心难题为什么仓库总在打架1.1 AI Agent 的工作方式和人类协作的区别先想清楚一个问题Agent 和普通 CI 脚本不一样它不是一个“改完就跑”的任务。Agent 会不断读取文件、生成新文件、执行测试、根据报错再次修改文件它是一个有状态的循环过程。这意味着它干活的时候文件系统随时都在变化而且这个变化是多次迭代的结果不是一次 git commit 能概括的。更麻烦的是现在的 AI 编程工具普遍支持“并行任务”你可以同时让一个 Agent 重构模块、另一个 Agent 加新功能。这种并行方式在聊天界面里看起来是分开的但它们落到底层还是同一个仓库、同一个工作目录。于是就会发生Agent A 刚把auth.py整体重写Agent B 的需求是基于旧的auth.py继续开发两边互相不知道最终产物就是一团乱麻。这里要区分一个概念Agent 是由 LLM 驱动、通过工具调用和文件系统交互的完整循环模型本身只是它的“大脑”。之所以并行开发会出问题不是因为模型能力不够而是因为多个大脑共用了一套四肢同一个工作目录协作基本靠运气。1.2 分支切换式协作的三大死法没有用 worktree 之前最常见的方案是每个 Agent 一个分支要干活就git checkout branchA。听上去合理实际操作中问题很多。第一是工作区残留。Agent 干活时会生成各种临时文件、缓存文件、未跟踪的神秘文件。你切换分支的时候这些文件可能留着也可能因为冲突直接报错。Agent 下一次启动时看到一堆不属于当前分支的文件会产生幻觉以为这些是项目的一部分然后基于错误的上下文开始改代码。第二是构建缓存冲突。前后端项目基本都有node_modules、dist、__pycache__这类目录。切换分支的时候这些缓存目录里的内容不会自动刷新。你切到新分支继续开发发现跑起来还是旧代码排查半天才明白是缓存作祟。Agent 不会帮你排这个雷它只会一脸无辜地说“看起来应该没问题”。第三是合并灾难。多个 Agent 从同一个基线出发各自改了不同的文件最后 merge 回主干时只要有一个文件被两个 Agent 同时改过就得人工解决冲突。AI Agent 生成的代码风格还不一样有的喜欢把所有工具函数塞在一个文件里有的喜欢拆开合并起来的酸爽你试过就知道。1.3 为什么 worktree 是正解Git Worktree 的核心思想很简单同一个仓库可以同时检出多个分支每个分支对应一个独立的物理目录。它们共享同一个.git对象库但各自拥有独立的HEAD、index和暂存区。最关键的是目录隔离。Agent A 在/repo/worktrees/task-refactor里干活Agent B 在/repo/worktrees/task-login里干活两者物理上就是不同的文件夹。Agent 互相之间看不到对方的改动也不会踩对方的缓存。这比“切换分支”彻底得多——切换分支是同一块地面翻来覆去worktree 是直接划分地盘。同时它又比“复制整个仓库”好得多。多个 worktree 共享同一个.git不复制版本历史不重复拉取远端磁盘占用和网络开销都小。而且它的切任务成本几乎为零你要切到另一个任务不需要git checkout直接cd到另一个目录就行。Git 官方从 2.5 开始提供 worktree 功能2.15 之后相对稳定。如果你用了这么多年 git 还没碰过 worktree并行 Agent 工作流就是最好的上手场景。2. Worktrunk 的设计思路让“任务工作区”成为一等对象2.1 为什么需要再套一层 CLI直接用 git worktree 命令也能干活但有几个体验问题。第一个问题是心智负担重。每次创建一个 Agent 任务你要想清楚用什么分支名、放哪个目录、基于哪个基线、之后怎么清理。任务一多这些信息散落在各个终端历史里根本记不住。第二个问题是缺少任务视角的管理视图。git worktree list 能列出所有工作区但它不知道哪个工作区对应哪个 Agent 任务、哪个已经合并完可以清理、哪个还处于活跃状态。这些上下文完全靠人脑维护。第三个问题是 Agent 兼容性。AI 编程 CLI 工具一般只认当前目录和当前环境它不会主动去理解你的分支策略。你需要一个统一的接口让 Agent 能感知到“我现在在哪个任务里、这个任务叫什么、目标分支是什么”。把这些信息串联起来正是 Worktrunk 这类工具存在的意义。Worktrunk 的设计目标很明确用一套简单命令把“创建任务工作区、进入任务状态、同步基线、合并回主线、清理过期工作区”这个完整生命周期管起来并且所有输出都可以被脚本和 Agent 解析。2.2 核心命令设计一条命令对应一个状态流转我设计 Worktrunk 的时候命令集刻意做得很小因为工具是给人以及 Agent用的命令越少学习成本越低自动化的稳定性也越高。核心命令如下命令作用底层操作worktrunk init初始化任务状态目录在仓库根目录创建.worktrunk/记录当前主线分支worktrunk create task-name创建新任务工作区git worktree add -b task-name path base并写入状态文件worktrunk list列出所有任务工作区读取状态文件展示状态、分支、路径worktrunk switch task-name切换到指定任务目录本质上就是输出目录路径方便配合 shell aliasworktrunk sync task-name把主线最新改动同步进来在任务工作区里执行git merge baseworktrunk merge task-name把任务合并回主线切换回主线目录git merge --no-ff task-nameworktrunk discard task-name丢弃整个任务git worktree remove --force并清理状态其中create是最核心的一条。它会自动做四件事给任务分配一个独立目录、创建对应的分支、把当前主线作为基线、记录这条路的所有元数据。你不需要自己想目录放哪、分支叫什么一切按约定自动完成。我特意为所有命令都加了--json参数。因为 Agent 相关的脚本经常需要解析命令输出。人看表格Agent 看 JSON两边各取所需。2.3 任务上下文绑定Agent 不再“失忆”AI 编程工具有一个通病你给它一个任务它干到一半如果会话中断、或者你想让它换个方向它有相当概率“失忆”。失忆的本质是上下文丢失而上下文不仅包括对话历史还包括它正在操作的文件路径、当前分支、未提交的改动。Worktrunk 解决的是其中一部分把文件路径和分支信息固定下来。每个任务工作区都和 task-name 严格绑定无论谁在什么时候进入这个目录都知道“这里是哪个任务的地盘”。你还可以在 task 创建时写入描述比如worktrunk create task-login --desc 实现邮箱登录需要处理验证码这个描述会存到状态文件里后续无论是人还是脚本都能随时取出来注入给 Agent。实测下来的体会是有这套绑定之后Agent 出错的概率明显下降。因为不管它自己怎么折腾至少不会搞错工作目录不会把任务 A 的改动提交到任务 B 的分支上。目录本身成了比会话更可靠的状态锚点。3. 实操演练用 Worktrunk 同时跑三个 Agent 任务3.1 安装和初始化假设你已经有一个 Git 仓库主线分支是main。安装 Worktrunk 后目前支持 Homebrew 和直接下载二进制两种方式第一次使用需要先在仓库根目录执行初始化cd /path/to/your/repo worktrunk init --base main命令执行后Worktrunk 会在仓库根目录下创建.worktrunk/目录里面保存仓库的基础信息。同时它会检查当前 git 版本是否支持 worktree 特性不支持会直接报错。初始化只需要做一次。之后所有 worktree 都放在仓库根目录下的worktrees/文件夹里命名规则是worktrees/task-name。把这个目录加进.gitignore因为它的内容不需要提交。3.2 场景拆解重构、新功能、修 bug 三线并行我们模拟一个实际项目。假设这个项目是 Python 写的 Web 服务有三个任务task-refactor把散落的工具函数统一到utils/包下。task-login新增邮箱验证码登录接口。task-fix-crash修复用户上传文件时的空指针崩溃。第一步给三个任务各开一个工作区互不干扰worktrunk create task-refactor worktrunk create task-login worktrunk create task-fix-crash每执行一条命令Worktrunk 都会创建一个独立目录和对应分支。执行完worktrunk list你看到的输出是类似这样的TASK STATUS BRANCH PATH task-refactor active task-refactor worktrees/task-refactor task-login active task-login worktrees/task-login task-fix-crash active task-fix-crash worktrees/task-fix-crash三个 Agent 可以分别在三个终端里进入各自目录开工。在第二个终端里启动一个专门做登录功能的会话cd /path/to/your/repo/worktrees/task-login codex 在现有项目中实现邮箱验证码登录接口先看一下项目结构再动手另一个终端里处理崩溃问题cd /path/to/your/repo/worktrees/task-fix-crash codex 空指针崩溃发生在文件上传模块先定位问题再修复因为三个目录物理隔离Agent 之间不会抢文件也不会互相污染环境。每个 terminal 里跑各自的 agent改动都落在各自的分支上。这是整个方案最爽的地方。3.3 合并流程谁先完成谁先合还是全部完成后统一合任务完成后合并回主线有两种策略。快速策略是完成一个合并一个worktrunk merge task-fix-crash --into main这条命令会自动切换到主线目录、执行 merge、然后把该任务的 worktree 标记为已合并。如果合并时没有冲突整个操作几秒钟就完成了。合并完成后worktrunk list这条任务的状态会变成merged你随时可以用worktrunk cleanup把所有已合并任务的目录清理掉。稳妥策略是先同步再合并。当任务 A 和任务 B 都改了同一个文件时早合并的那个没事晚合并的那个大概率冲突。要减少冲突养成一个习惯任务开始一段时间后主动把主线的最新改动同步到自己的任务工作区里。命令是worktrunk sync task-login --from main这会在task-login目录里执行一次 merge把 main 分支的改动拉进来。你可能觉得这样把本该后面发生的冲突提前了但提前解决冲突比最后堆一堆冲突要轻松得多。主动同步的频率越高最后合并的阻力越小。我实际用下来的建议是bug 修复类任务单独快速合回主干因为它改动面小大型重构类和功能类任务全部在各自工作区里完成并通过测试后再统一 merge合并前各自先 sync 一次 latest main。这样总体冲突率最低。4. 常见报错与排查技巧实录4.1 高频问题速查表报错/现象原因处理方式fatal: branch is already used by worktree at ...分支已被另一个 worktree 占用用git worktree list查占用情况确认是否是过期任务HEAD detached at commitAgent 可能在 worktree 里执行了 checkout 导致游离头在任务目录执行git switch task-name找回分支fatal: worktrees/task-x already exists目录残留但状态文件丢失手动检查.worktrunk/state.json确认后清理目录合并时报大量冲突多任务改了同一批文件优先用worktrunk sync提前合并解决一个任务后重新跑测试Agent 在任务目录里看不到远端分支worktree 共享 refs 但远端跟踪需要手动 fetch执行git fetch --all再git branch -r检查Windows 上报路径过长目录层级太深设置core.longpaths true或把仓库放到浅目录4.2 我踩过的三个坑第一个坑是任务工作区的编译缓存。我在一个 Node 项目里跑了三个并行 Agent任务逻辑上隔离了但node_modules是共享的。Agent 在任务 A 里装了一个新依赖任务 B 的代码马上就能看见听起来是好事其实不然。Agent 不会知道共享依赖的变化它可能基于旧依赖写完代码最后跑起来失败。处理办法是每个任务工作区里显式声明依赖版本或者把 Agent 的“检查 package.json / requirements.txt”写进任务提示让它干活前先确认。第二个坑是 Agent 在 worktree 里擅自执行了一些全局操作。曾经有一个 Agent 在当前任务目录里执行了git reset --hard把我同仓库其他 worktree 的引用也影响了。这种问题不好完全靠工具防住只能在 Agent 的工具说明里明确规则只允许操作当前目录内的文件禁止对仓库执行全局性的 reset 或 rebase。第三个坑是状态文件和实际 git 状态不一致。比如手动删除了一个 worktree 目录但没跑worktrunk discard导致 Worktrunk 还认为这个任务是活跃的。后来我养成了习惯所有 worktree 的生命周期操作都必须通过 Worktrunk 命令完成不要手动git worktree remove。这就像自己定的规矩越简单越不会出错。4.3 排查技巧从三处入手最快定位遇到问题先不要慌按下面顺序排查基本能快速定位大多数异常。先看 Worktrunk 的状态文件。打开.worktrunk/state.json里面记录了每个任务与目录、分支、状态的映射关系。确认状态文件里的路径是否真实存在。再看 git 本身怎么想。执行git worktree list --porcelain输出每个 worktree 的路径、HEAD 和分支信息。和状态文件对比差异在哪里问题基本就浮出水面了。最后看 Agent 的实际操作对象。如果 Agent 报错说找不到文件直接看它的终端路径是不是正确的任务工作区。很多时候 Agent 错误地把命令跑在了仓库根目录而不是 worktree 目录里导致找不到文件或者改错文件。这种问题不看 Agent 日志根本发现不了。5. 进阶玩法和其他 AI 编程工具联用的实战姿势5.1 每个 Agent 一个独立 Shell 会话最简单的集成方式是把 Worktrunk 和任意 AI 编程 CLI 组合起来。现在比较主流的 Codex CLI、Claude Code CLI 本质上都是“在当前目录下干活”的工具你只需要保证每个 Agent 启动时的当前目录是它自己的 worktree 目录。我的习惯是每个任务开一个独立的终端标签页或 tmux 窗口标题就写任务名进入目录后启动 Agent。这样做的好处是会话日志天然隔离任务结束之后翻历史记录也不会串台。5.2 用环境变量给 Agent 注入任务上下文你可以在启动 Agent 前设置一些环境变量让 Agent 通过工具调用感知到任务信息。比如cd /path/to/your/repo/worktrees/task-login export WORKTRUNK_TASK_NAMEtask-login export WORKTRUNK_BRANCHtask-login codexAgent 读取这些环境变量后可以在每次操作前做一个“快速自检”我当前在哪个任务里、应该在哪个目录操作。这个自检步骤虽然简单但能省掉大量“改错分支、改错文件”的返工。5.3 用 worktrunk 的 JSON 输出自动化编排如果你在跑一个多 Agent 的批处理流程比如自动生成多个模块代码可以把 Worktrunk 的--json输出和 Shell 脚本对接worktrunk list --json | jq -r .[] | select(.status active) | .path这一步可以迅速拿到全部活跃任务的目录然后挨个启动 Agent。更复杂的编排是把任务状态作为条件判断的依据如果某个任务工作区在 30 分钟内没有任何文件变动就自动销毁重新生成。这种逻辑不管在本地还是 CI 流水线里都很实用。5.4 自动化回收与通知并行 Agent 跑多了之后工作区和分支会越来越多所以一定要有一个明确的回收机制。我现在跑的流程是Agent 完成任务后自动执行worktrunk merge --auto尝试合并如果合并失败就标记为“需要人工介入”同时发一条通知。每次任务结束用worktrunk cleanup把所有 merged 或 discarded 状态的任务目录清理掉。长期挂着不清理的 worktree 是隐患。轻则占磁盘空间重则会和新的任务分支撞名导致莫名报错。我是每周五下班前固定执行一次大扫除把所有不是本周创建而且状态不是 active 的 worktree 一次清干净。6. Worktrunk 内部实现要点如果自己写一个类似的 CLI6.1 底层到底该怎么调 GitWorktrunk 内部并不是直接解析.git目录的二进制内容而是通过 subprocess 调用 git CLI。原因很简单git 命令接口是长期稳定的而内部文件格式没有承诺稳定。跨大版本升级直接读文件很可能踩雷。创建 worktree 的核心命令是git worktree add -b branch path base-b表示自动创建并检出新分支path是新工作区的路径base是基线分支名。删除 worktree 用下面这条git worktree remove --force path注意设计 CLI 时调用的命令输出一定要同时捕获 stdout 和 stderr。git 的报错信息很多走 stderr如果只捞 stdout排查问题的时候你会一头雾水。6.2 状态文件是怎么设计的我们把每个 task 的映射信息存到一个 JSON 文件里基本结构是 task-name 到 worktree 信息的一对一映射。关键字段包括分支名、目录路径、基线、创建时间、状态、关联的 Agent 类型和任务描述。为什么不用解析git worktree list的输出来反推任务信息因为 git 不知道我们的 task 概念它只知道有一个 worktree。真正可靠的方案是自己维护状态文件git 的信息只做交叉验证。这样即使 git 输出格式变化你的核心逻辑也不受影响。状态变更一定要走“先画靶再射箭”的流程先写状态文件再去执行实际的 git 操作操作失败则回滚状态。这样可以避免“git 操作成功了但状态文件没更新”的尴尬境地保证你看到的状态是可信的。提示如果你打算自己实现类似的工具建议一开始就支持--json输出。别问为什么等你第二次写脚本解析你的 CLI 输出的时候你会感谢这个决定。7. 设计取舍与适用边界7.1 为什么不做成 GUI有人会问现在都有 VS Code 插件、JetBrains 插件了为什么 Worktrunk 还要做成纯 CLI因为它的主要用户不是人是 Agent。AI Agent 目前最成熟的交互方式就是命令行它能执行命令、解析输出、根据结果决定下一步动作。CLI 天然是给 Agent 用的 API。GUI 反而会引入额外的自动化成本——你要么为它写专门的插件接口要么截图让 Agent 识别这都是低效路径。而 CLI 的输出是结构化的可以被任意脚本调用和组合这才是 Agent 友好的接口形态。7.2 哪些场景适合/不适合 WorktrunkWorktrunk 最适合的场景是仓库设计合理、增量相对清晰、有多任务并行需求并且 Agent 主要在仓库内部代码上做修改。特别是 AI Agent 编程刚开始流行的这个阶段多 Agent 在同一仓库里并发干活的诉求会越来越多。但如果你的项目一次任务会跨十几个仓库改动或者经常有大规模重构和重写worktree 的意义就不大。这时候你应该考虑的是把大任务拆成多个小任务让每个小任务在各自的 worktree 里完成最后再逐层合并。要是任务本身大到无法拆分那不管用什么工具靠并行 Agent 也救不了老老实实一个任务一个 Agent 串行才是正解。7.3 与传统分支模型的关系你可能关心 Worktrunk 和 Git Flow、GitHub Flow 这些分支模型是否冲突。实际使用中完全不冲突。Worktrunk 只是帮你管理“本地同时存在多个工作区”这件事至于分支怎么命名、何时合并到哪个主干还是由你的团队规范决定。我自己倾向于把它当成本地开发阶段的“任务管理面板”主线依然保持干净功能分支的创建、开发、合并都通过 Worktrunk 编排。它不会改变你和团队协作的方式只会把你和每个 agent 之间那份混乱的目录管理任务接走。用 Worktrunk 之后我个人的铁律是一个任务一个 worktree任务结束必须合回或丢弃绝不长期挂着。这套流程用下来多 Agent 并行的项目交叉污染的返工率肉眼可见地下降给我省了很多把 Agent 生成的代码“无中生有”修回去的时间。如果你正在被“同时开几个 AI 编程助手但仓库一片狼藉”这个问题困扰建议花一个下午把 worktree 和这类 CLI 工具跑熟。它不会让你的 Agent 变得更聪明但会让每个 Agent 都有一个干净、独立、可复盘的“工位”。这就够了。