1. 为什么并行 AI Agent 工作流需要 Worktree先说个真实场景。上周我在本机同时起了四个 Codex CLI 实例打算让它们分头改一个中型 TypeScript 仓库的不同模块——一个做 API 路由重构一个改数据库模型一个补前端组件测试一个优化构建脚本。理论上大家各干各的互不干扰对吧结果半小时后我就后悔了Agent A 跑测试时发现依赖被 Agent B 改了Agent C 提交的代码把 Agent D 正在读的接口文件覆盖了更离谱的是一个 Agent 执行git checkout切分支直接把另一个 Agent 的工作目录搅成一锅粥。那天下午我花了将近三个小时处理合并冲突和恢复丢失的未提交改动。这个场景在今天一点都不稀奇。AI 编程工具已经从帮你补全几行代码进化到给你一个终端你自己去把任务搞定的形态Codex CLI、Claude CLI 这类工具能够自主读文件、改代码、跑测试、多次提交一个 Agent 本质上就是一个很勤奋但眼神不太好、还不太会看路的实习生。当你有多个这样的实习生同时在同一个仓库里干活Git 本身的工作流就成了最大的瓶颈。如果你在单个工作目录里并行跑多个 Agent会遇到两个逃不掉的问题一是分支切换会打断未提交的工作——Agent 写到一半的文件可能被 stash 或者直接冲突二是可见性不可控——每个 Agent 都能看到其他 Agent 产生的中间状态互相踩脚是必然的。传统做法是给每个 Agent 开一台虚拟机或者 Docker 容器各自git clone一份仓库但这会带来磁盘空间膨胀、依赖安装重复、最终合并困难等一堆新问题。Git Worktree 恰好就是冲着这个问题来的。它是 Git 从 2.5 版本开始提供的官方特性允许你在同一个仓库下创建多个工作目录不同目录可以检出不同的分支共享同一个.git对象数据库。与完全 clone 一份仓库相比Worktree 几乎不占额外空间只需要一份对象库分支的创建和合并都在同一个仓库内完成切换成本极低。但 Git Worktree 的手动使用有一个很尴尬的断层你需要自己维护一套哪个目录对应哪个分支、这个目录是给哪个 Agent 用的、用完要不要清理的映射关系。命令本身不复杂复杂的是状态管理。Worktrunk 这个 CLI 工具本质上就是把这个状态管理自动化了把所有 Worktree 的操作封装成专门面向并行 AI Agent 场景的几条命令。2. Worktrunk 的核心设计思路从给人用到给 Agent 用2.1 手动管理 Worktree 的痛点先用一段命令还原手动使用 Worktree 的典型流程。假设你有一个仓库myapp想让 Agent A 在feature/auth分支上开发Agent B 在feature/api分支上开发你需要这么操作cd ~/work/myapp git worktree add ../myapp-agent-a -b feature/auth git worktree add ../myapp-agent-b -b feature/api然后你得时刻记着../myapp-agent-a是 Agent A 的工作目录../myapp-agent-b是 Agent B 的。等 Agent 跑完了你要回到主工作目录去 mergecd ~/work/myapp git merge feature/auth git worktree remove ../myapp-agent-a --force看起来也还好问题出在规模化的时候。当你同时管理三四个、甚至七八个 Agent 实例时每个 Agent 的工作目录、分支名、当前进度、是否已完成、哪些分支要保留、哪些目录要清理这些信息会迅速超出人脑能可靠记忆的范畴。更重要的是Agent 本身是程序它不关心路径美不美它需要的是确定性的、可预期的环境。如果你每次都要手输一串不同的路径和分支名Agent 的启动命令就会变得很长很脆弱而且容易写错。2.2 Worktrunk 的命令设计哲学Worktrunk 的定位很清楚它不是一个通用的 Git 增强工具而是面向并行 Agent 场景的 Worktree 生命周期管理器。它的命令设计围绕三个核心需求展开快速创建隔离工作区、随时查看全局状态、安全地合并与清理。围绕这几个需求我把核心命令设计成下面这套你在实际使用中也可以按这个思路去组织自己的脚本命令作用对应手动操作worktrunk init初始化当前仓库的管理配置无worktrunk agent new name为指定 Agent 创建独立工作树和分支git worktree addgit checkout -bworktrunk list展示所有 Agent 工作区及其状态git worktree list 人工记忆worktrunk switch name切换当前终端到某 Agent 工作区cdgit checkoutworktrunk merge name将某 Agent 的分支合并回主分支git merge 人工确认worktrunk cleanup清理已合并的 Agent 工作区git worktree remove 手工检查这里的关键差异在于传统命令的输入是路径和分支名Worktrunk 的输入是Agent 的名字。名字是人类和 Agent 都能理解的最小单位。你只需要告诉 Worktrunk 给 agent-auth 开个工作区它会自动生成规范化的目录名、创建独立分支、记录 Agent 的工作目录并在后续所有操作中通过名字引用。2.3 元数据存储与状态同步机制Worktrunk 要正常工作必须把Agent 名 → 工作目录 → 分支名 → 状态这套映射关系持久化。在设计上我把它存在仓库根目录下的.worktrunk/目录里并在.gitignore中忽略它避免配置文件污染提交历史。目录结构大致长这样.worktrunk/ config.json # 全局配置主分支名、目录命名规则等 agents/ auth.json # 每个 Agent 一份状态文件 api.json每份 Agent 状态文件记录的内容包括{ name: auth, branch: feature/agent-auth, path: ../myapp-agent-auth, createdAt: 2025-01-12T10:30:00Z, status: active, lastCommit: 3f2a1c9e... }设计这个机制时有一个很朴素的考虑Agent 在跑批任务时不可预测可能突然中断、可能提交多次、可能留下未合并的分支。有了状态文件无论 Worktrunk 的进程本身是否存活只要仓库还在就能通过worktrunk list把当前全局状态完整还原出来。这一点彻底解决了我之前每次开新终端都要回忆一遍现在有哪些 Worktree 在跑的问题。还有一个容易被忽略的细节分支命名规则。Worktrunk 默认用feature/agent-name作为分支名同时把 Agent 工作目录约定为主仓库目录的兄弟目录命名格式为仓库名-agent-name。这样即使不打开状态文件光看目录列表和分支列表也能一眼知道哪些工作区是 Agent 的哪些是你自己手动开的。3. 实际使用场景与工作流实操3.1 初始化与创建 Agent 工作区下面完整演示一遍 Worktrunk 的使用流程。这是我实测下来最顺的一条链路你可以直接照抄。首先进入你的主仓库执行初始化cd ~/work/myapp worktrunk init --main-branch main初始化做了什么它读取了当前仓库的基本信息仓库名、当前分支生成了.worktrunk/config.json然后在.gitignore里追加上.worktrunk/并校验当前 Git 版本是否支持 Worktree需要 Git 2.5 以上。如果你用的是老版本 Git它会直接报错提示你升级避免后续踩坑。接着为两个 Agent 创建隔离工作区worktrunk agent new auth worktrunk agent new api执行第一条命令时Worktrunk 会在后台依次执行git branch feature/agent-auth # 基于当前 HEAD 创建新分支 git worktree add ../myapp-agent-auth -b feature/agent-auth echo {name:auth,branch:feature/agent-auth,...} .worktrunk/agents/auth.json到此为止~/work/myapp-agent-auth这个目录就是一个完整的、独立的工作副本Agent A 可以在里面随意修改、提交完全不影响主仓库和其他工作区。Agent A 的启动命令可以简化为codexcli --cd ~/work/myapp-agent-auth 实现用户认证模块的登录接口我强烈建议你不要让 Agent 在 Worktree 里创建虚拟环境或安装全局依赖而是把依赖目录也放进工作区内、通过.gitignore排除。这样做的好处是每个 Agent 隔离一套自己的依赖状态避免 Agent A 升级依赖导致 Agent B 的测试环境被破坏。3.2 多 Agent 并行开发中的状态查看当两个 Agent 同时跑到一半时你最需要的是一个全局视图。直接执行worktrunk list输出类似这样Agent Branch Path Status Last Commit auth feature/agent-auth ../myapp-agent-auth active 3f2a1c9e api feature/agent-api ../myapp-agent-api active 8d3b6f21这个视图看起来简单但它在实际工作中帮我省掉了大量cdgit loggit status的轮询操作。更关键的是worktrunk list会主动去检查工作区目录是否存在、分支是否领先或落后于主分支如果 Agent A 已经提交了 5 个 commit而主分支已经前进了一大截它会给出提示方便你提前评估冲突风险。如果需要快速进入某个 Agent 的工作目录做检查不需要自己去拼路径worktrunk switch auth # 输出: Switched to agent workspace: ~/work/myapp-agent-auth这个命令本质上是告诉你工作目录的路径如果当前 shell 支持 source 一个脚本输出它也可以直接帮你cd过去。在实操中我通常是手动 cd 过去因为 IDE 和终端的工作目录不一致时容易出问题但如果你是在脚本里调用可以约定用worktrunk path auth来获取路径做变量拼接。3.3 合并与清理安全完成 Agent 的生命周期Agent 完成任务后你的核心诉求是把它的改动安全合并回主分支然后果断清理工作区。合并的操作我建议走两步worktrunk merge auth --strategymergeWorktrunk 会先帮你执行git merge feature/agent-auth如果冲突存在它会停在那里列出冲突文件不会强制继续。这时候你需要人工介入处理冲突处理完再执行一次worktrunk merge auth --continue。这里有一个我在实际使用中总结出来的教训不要用--strategyrebase去处理 Agent 的提交。Agent 在跑任务过程中可能产生大量小步提交比如每改一个文件就 commit 一次rebase 会把主分支的提交历史线性化但一旦 Agent 在执行中途做了多次与主分支无关的调整rebase 产生的冲突会比 merge 多得多。用 merge 加上--no-ff保留一个合并节点虽然历史里会有一个 merge commit但可追溯性和可回滚性是最好的。确认合并无误后清理工作区worktrunk cleanup auth这条命令会做三次确认分支是否已合并工作目录是否有未提交的改动是否有未推送的 commit全部通过后才会真正执行git worktree remove和git branch -d。如果有未合并的分支它默认拒绝删除你可以用--force强制清理——但我建议不到万不得已别用因为一旦删了分支Agent 的成果就真的回不来了。4. 常见问题与排查技巧4.1 无法在同一个分支上打开多个 Worktree这是 Git Worktree 的硬性限制一个分支只能在一个 Worktree 中检出。如果你在主分支上创建了一个 Agent 工作区然后又在另一个目录试图 checkout 主分支Git 会直接报错。这种情况在 Worktrunk 中的体现是如果你在运行worktrunk agent new时当前主仓库正处于某个非主分支上Worktrunk 生成的 Agent 分支会基于这个非主分支而不是基于主分支。这是我早期踩过的一个坑有一次主仓库停在feature/x分支上我给 Agent A 和 Agent B 各建了一个工作区结果两个 Agent 的分支都基于feature/x等 Agent 跑完 merge 回主分支时把feature/x上的半成品代码全都带进来了。排查方法执行worktrunk list时留意每个 Agent 分支的Last Commit是否和主分支同源。如果发现分支起点不对用git log --oneline --graph agent-branch --not main查看 Agent 分支是否包含了不应包含的提交。预防的办法是在worktrunk init之后、创建任何 Agent 之前确保主仓库处于干净的、基于主分支的 HEAD 位置。4.2 Worktree 目录删不掉git worktree remove失败的常见原因只有两个工作目录里有未跟踪或未提交的改动以及该目录是当前 shell 的$PWD。后者尤其在 Windows 环境下频发——你人还站在那个目录里Git 怎么敢删。Worktrunk 的cleanup有防御性检查会在删除前打印有问题的文件列表。但如果出现这种情况fatal: working trees containing modified or untracked files cannot be removed你有两条路走真正确认改动都不需要了用git worktree remove --force如果目录已经被搞得很乱但分支的提交历史还在可以接受目录残缺先把分支合并好然后用git worktree prune清理 Git 内部的 Worktree 记录。实操心得每次让 Agent 跑完任务后我第一步不是看代码而是先看有没有未提交的改动。AI Agent 经常会在完成任务后留下一些调试用的临时文件、测试日志或者未纳入 git 的配置文件你如果不检查直接 cleanup这些痕迹和潜在有价值的中间产物会全部丢失。我的习惯是让 Agent 跑完任务后立刻执行git status --porcelain把输出存档再决定清理策略。4.3 和 IDE 及开发工具的冲突用 Worktree 跑 Agent 时还有一个容易被忽视的问题你的 IDE 可能会把多个工作目录识别成同一个项目。如果你用 VS Code 打开myapp-agent-auth和myapp-agent-api两个目录代码补全和跨文件跳转有时候会串场因为两个目录里都有相同的node_modules和类型定义文件。我的应对方案是在.code-workspace文件里给每个工作区配置独立的path并且把 JavaScript/TypeScript 项目的tsconfig.json里的rootDir指清楚。如果你用的是 JetBrains 系列的 IDE同理在项目结构里手动把 Agent 工作目录识别为独立的模块不要混在一起。另一个常见的坑是lint 和格式化工具的配置漂移。假如主仓库用的是 Prettier而某个 Agent 在运行过程中自动修改了.prettierrc之后再合并回来就会有一堆格式化的噪音 diff。为了防止这种情况我在 Worktrunk 的状态文件里额外加了一个protectedFiles字段列出那些 Agent 不应该修改的文件路径。在实际使用中你是没法指望 LLM 主动克制不去动配置文件的最好的办法是在 Agent 的提示词里明确写不要修改 .prettierrc、eslint.config.js 等配置文件同时在 merge 时留意这些文件的 diff。4.4 磁盘空间占用异常Worktree 共享一个对象库通常不会占太多额外空间但在真实使用中它会膨胀。原因是每个工作区都有自己完整的node_modules或 Python 虚拟环境目录而这些目录通常被.gitignore忽略不会进入 Git 对象库但它们会真实占用磁盘空间。你开 5 个 Agent就等于把依赖装了 5 遍。如果你机器磁盘吃紧有几个变通思路第一把.gitignore里的依赖目录做成符号链接symlink指向一个公共的依赖缓存目录比如node_modules - ~/.cache/myapp-node_modules但要注意这可能会引入多个 Agent 同时修改同一个依赖文件的隐患实测下来 Node 生态相对安全Python 的__pycache__偶尔会互相干扰第二限制同时并行的 Agent 数量用 Worktrunk 的list和cleanup及时回收已完成的工作区第三用du -sh .worktrunk/*写一个定期检查的脚本在磁盘占用超过阈值时报警。4.5 与 CI/CD 的衔接问题Agent 的工作区本质上是本地分支如果你们团队用 GitHub Actions 之类的 CI 系统本地合并后推送就能触发 CI。但有一个细节要处理Worktree 的 remote 配置引用。Worktrunk 创建的工作区是从本地分支切出来的默认情况下没有配置 upstream你需要执行一次git push -u origin feature/agent-auth为了让这条链路顺畅我在 Worktrunk 的merge命令里加了一个--push参数合并完成后自动执行 push。如果 CI 要求 PRPull Request流程那就不能走直接 push 分支合并的路线你需要在 Worktrunk 之外额外调 GitHub CLI 创建 PR这也好办——gh pr create --head feature/agent-auth一条命令就能搞定。5. 从 Worktrunk 到更大的 Agent 编排视角聊完具体命令和排查我想跳出工具本身说说这套思路带给我的启发。过去我们编排多个 Agent重点往往放在怎么让 Agent 之间通信、怎么共享上下文这些偏模型层面的设计上。但真实跑起来你会发现Agent 之间最严重的冲突源不是语义层面的理解不一致而是文件系统和 Git 状态层面的读写冲突。两个 Agent 哪怕用同一个 prompt 模板只要它们在同一时刻写同一个文件结果一定是灾难。Git Worktree 加 Worktrunk 提供的这一层隔离相当于在物理层面把Agent 的可见世界切分开了——每个 Agent 只能看到自己工作目录下的文件它对全局的认知只通过 Git 分支的合并来同步。这个思路和微服务架构的演进有点异曲同工。一开始你把所有代码放在一个单体仓库里靠规范和纪律约束不同开发者的修改边界后来发现做不到就拆成独立服务、独立部署、独立数据存储。多 Agent 并行开发也是同一个道理与其指望 Agent 不越界不如从一开始就给它一个越不了界的环境。Worktrunk 本身只解决 Git 工作区隔离这一层但它和现在的 AI Agent 开发生态能拼成一套更完整的工作流。比如你可以把 Worktrunk 和目录级权限控制搭配使用——在容器里跑 Agent 时把 Agent 的工作目录挂载为只读或限定写权限进一步兜底也可以把worktrunk agent new集成到你的 Agent 编排脚本里每次要下发任务时自动创建一个新的隔离工作区任务结束自动清理。我在自己的一个内部小项目中就是这么做的用一个 Python 脚本调度 Codex CLI 实例每个实例通过 Worktrunk 拿到独立目录跑完所有任务后统一合并、统一汇总。最后分享一个我现在固定的工作习惯不管什么任务只要涉及多个 Agent 并行我一定会先用worktrunk agent new给每个 Agent 开独立工作区然后无论如何都不让它们在主目录里直接动手。这个习惯坚持了快两个月并行开发的返工率明显下降。工具本身不复杂一两句话就能说清用法但它背后先隔离、再并行、最后合并的思路才是真正值得借鉴的东西。 
长河君 · 2026/9/17 6:31:42 · 阅读 1.2k Worktrunk：为并行AI Agent隔离Git工作区的利器
1. 为什么并行 AI Agent 工作流需要 Worktree先说个真实场景。上周我在本机同时起了四个 Codex CLI 实例打算让它们分头改一个中型 TypeScript 仓库的不同模块——一个做 API 路由重构一个改数据库模型一个补前端组件测试一个优化构建脚本。理论上大家各干各的互不干扰对吧结果半小时后我就后悔了Agent A 跑测试时发现依赖被 Agent B 改了Agent C 提交的代码把 Agent D 正在读的接口文件覆盖了更离谱的是一个 Agent 执行git checkout切分支直接把另一个 Agent 的工作目录搅成一锅粥。那天下午我花了将近三个小时处理合并冲突和恢复丢失的未提交改动。这个场景在今天一点都不稀奇。AI 编程工具已经从帮你补全几行代码进化到给你一个终端你自己去把任务搞定的形态Codex CLI、Claude CLI 这类工具能够自主读文件、改代码、跑测试、多次提交一个 Agent 本质上就是一个很勤奋但眼神不太好、还不太会看路的实习生。当你有多个这样的实习生同时在同一个仓库里干活Git 本身的工作流就成了最大的瓶颈。如果你在单个工作目录里并行跑多个 Agent会遇到两个逃不掉的问题一是分支切换会打断未提交的工作——Agent 写到一半的文件可能被 stash 或者直接冲突二是可见性不可控——每个 Agent 都能看到其他 Agent 产生的中间状态互相踩脚是必然的。传统做法是给每个 Agent 开一台虚拟机或者 Docker 容器各自git clone一份仓库但这会带来磁盘空间膨胀、依赖安装重复、最终合并困难等一堆新问题。Git Worktree 恰好就是冲着这个问题来的。它是 Git 从 2.5 版本开始提供的官方特性允许你在同一个仓库下创建多个工作目录不同目录可以检出不同的分支共享同一个.git对象数据库。与完全 clone 一份仓库相比Worktree 几乎不占额外空间只需要一份对象库分支的创建和合并都在同一个仓库内完成切换成本极低。但 Git Worktree 的手动使用有一个很尴尬的断层你需要自己维护一套哪个目录对应哪个分支、这个目录是给哪个 Agent 用的、用完要不要清理的映射关系。命令本身不复杂复杂的是状态管理。Worktrunk 这个 CLI 工具本质上就是把这个状态管理自动化了把所有 Worktree 的操作封装成专门面向并行 AI Agent 场景的几条命令。2. Worktrunk 的核心设计思路从给人用到给 Agent 用2.1 手动管理 Worktree 的痛点先用一段命令还原手动使用 Worktree 的典型流程。假设你有一个仓库myapp想让 Agent A 在feature/auth分支上开发Agent B 在feature/api分支上开发你需要这么操作cd ~/work/myapp git worktree add ../myapp-agent-a -b feature/auth git worktree add ../myapp-agent-b -b feature/api然后你得时刻记着../myapp-agent-a是 Agent A 的工作目录../myapp-agent-b是 Agent B 的。等 Agent 跑完了你要回到主工作目录去 mergecd ~/work/myapp git merge feature/auth git worktree remove ../myapp-agent-a --force看起来也还好问题出在规模化的时候。当你同时管理三四个、甚至七八个 Agent 实例时每个 Agent 的工作目录、分支名、当前进度、是否已完成、哪些分支要保留、哪些目录要清理这些信息会迅速超出人脑能可靠记忆的范畴。更重要的是Agent 本身是程序它不关心路径美不美它需要的是确定性的、可预期的环境。如果你每次都要手输一串不同的路径和分支名Agent 的启动命令就会变得很长很脆弱而且容易写错。2.2 Worktrunk 的命令设计哲学Worktrunk 的定位很清楚它不是一个通用的 Git 增强工具而是面向并行 Agent 场景的 Worktree 生命周期管理器。它的命令设计围绕三个核心需求展开快速创建隔离工作区、随时查看全局状态、安全地合并与清理。围绕这几个需求我把核心命令设计成下面这套你在实际使用中也可以按这个思路去组织自己的脚本命令作用对应手动操作worktrunk init初始化当前仓库的管理配置无worktrunk agent new name为指定 Agent 创建独立工作树和分支git worktree addgit checkout -bworktrunk list展示所有 Agent 工作区及其状态git worktree list 人工记忆worktrunk switch name切换当前终端到某 Agent 工作区cdgit checkoutworktrunk merge name将某 Agent 的分支合并回主分支git merge 人工确认worktrunk cleanup清理已合并的 Agent 工作区git worktree remove 手工检查这里的关键差异在于传统命令的输入是路径和分支名Worktrunk 的输入是Agent 的名字。名字是人类和 Agent 都能理解的最小单位。你只需要告诉 Worktrunk 给 agent-auth 开个工作区它会自动生成规范化的目录名、创建独立分支、记录 Agent 的工作目录并在后续所有操作中通过名字引用。2.3 元数据存储与状态同步机制Worktrunk 要正常工作必须把Agent 名 → 工作目录 → 分支名 → 状态这套映射关系持久化。在设计上我把它存在仓库根目录下的.worktrunk/目录里并在.gitignore中忽略它避免配置文件污染提交历史。目录结构大致长这样.worktrunk/ config.json # 全局配置主分支名、目录命名规则等 agents/ auth.json # 每个 Agent 一份状态文件 api.json每份 Agent 状态文件记录的内容包括{ name: auth, branch: feature/agent-auth, path: ../myapp-agent-auth, createdAt: 2025-01-12T10:30:00Z, status: active, lastCommit: 3f2a1c9e... }设计这个机制时有一个很朴素的考虑Agent 在跑批任务时不可预测可能突然中断、可能提交多次、可能留下未合并的分支。有了状态文件无论 Worktrunk 的进程本身是否存活只要仓库还在就能通过worktrunk list把当前全局状态完整还原出来。这一点彻底解决了我之前每次开新终端都要回忆一遍现在有哪些 Worktree 在跑的问题。还有一个容易被忽略的细节分支命名规则。Worktrunk 默认用feature/agent-name作为分支名同时把 Agent 工作目录约定为主仓库目录的兄弟目录命名格式为仓库名-agent-name。这样即使不打开状态文件光看目录列表和分支列表也能一眼知道哪些工作区是 Agent 的哪些是你自己手动开的。3. 实际使用场景与工作流实操3.1 初始化与创建 Agent 工作区下面完整演示一遍 Worktrunk 的使用流程。这是我实测下来最顺的一条链路你可以直接照抄。首先进入你的主仓库执行初始化cd ~/work/myapp worktrunk init --main-branch main初始化做了什么它读取了当前仓库的基本信息仓库名、当前分支生成了.worktrunk/config.json然后在.gitignore里追加上.worktrunk/并校验当前 Git 版本是否支持 Worktree需要 Git 2.5 以上。如果你用的是老版本 Git它会直接报错提示你升级避免后续踩坑。接着为两个 Agent 创建隔离工作区worktrunk agent new auth worktrunk agent new api执行第一条命令时Worktrunk 会在后台依次执行git branch feature/agent-auth # 基于当前 HEAD 创建新分支 git worktree add ../myapp-agent-auth -b feature/agent-auth echo {name:auth,branch:feature/agent-auth,...} .worktrunk/agents/auth.json到此为止~/work/myapp-agent-auth这个目录就是一个完整的、独立的工作副本Agent A 可以在里面随意修改、提交完全不影响主仓库和其他工作区。Agent A 的启动命令可以简化为codexcli --cd ~/work/myapp-agent-auth 实现用户认证模块的登录接口我强烈建议你不要让 Agent 在 Worktree 里创建虚拟环境或安装全局依赖而是把依赖目录也放进工作区内、通过.gitignore排除。这样做的好处是每个 Agent 隔离一套自己的依赖状态避免 Agent A 升级依赖导致 Agent B 的测试环境被破坏。3.2 多 Agent 并行开发中的状态查看当两个 Agent 同时跑到一半时你最需要的是一个全局视图。直接执行worktrunk list输出类似这样Agent Branch Path Status Last Commit auth feature/agent-auth ../myapp-agent-auth active 3f2a1c9e api feature/agent-api ../myapp-agent-api active 8d3b6f21这个视图看起来简单但它在实际工作中帮我省掉了大量cdgit loggit status的轮询操作。更关键的是worktrunk list会主动去检查工作区目录是否存在、分支是否领先或落后于主分支如果 Agent A 已经提交了 5 个 commit而主分支已经前进了一大截它会给出提示方便你提前评估冲突风险。如果需要快速进入某个 Agent 的工作目录做检查不需要自己去拼路径worktrunk switch auth # 输出: Switched to agent workspace: ~/work/myapp-agent-auth这个命令本质上是告诉你工作目录的路径如果当前 shell 支持 source 一个脚本输出它也可以直接帮你cd过去。在实操中我通常是手动 cd 过去因为 IDE 和终端的工作目录不一致时容易出问题但如果你是在脚本里调用可以约定用worktrunk path auth来获取路径做变量拼接。3.3 合并与清理安全完成 Agent 的生命周期Agent 完成任务后你的核心诉求是把它的改动安全合并回主分支然后果断清理工作区。合并的操作我建议走两步worktrunk merge auth --strategymergeWorktrunk 会先帮你执行git merge feature/agent-auth如果冲突存在它会停在那里列出冲突文件不会强制继续。这时候你需要人工介入处理冲突处理完再执行一次worktrunk merge auth --continue。这里有一个我在实际使用中总结出来的教训不要用--strategyrebase去处理 Agent 的提交。Agent 在跑任务过程中可能产生大量小步提交比如每改一个文件就 commit 一次rebase 会把主分支的提交历史线性化但一旦 Agent 在执行中途做了多次与主分支无关的调整rebase 产生的冲突会比 merge 多得多。用 merge 加上--no-ff保留一个合并节点虽然历史里会有一个 merge commit但可追溯性和可回滚性是最好的。确认合并无误后清理工作区worktrunk cleanup auth这条命令会做三次确认分支是否已合并工作目录是否有未提交的改动是否有未推送的 commit全部通过后才会真正执行git worktree remove和git branch -d。如果有未合并的分支它默认拒绝删除你可以用--force强制清理——但我建议不到万不得已别用因为一旦删了分支Agent 的成果就真的回不来了。4. 常见问题与排查技巧4.1 无法在同一个分支上打开多个 Worktree这是 Git Worktree 的硬性限制一个分支只能在一个 Worktree 中检出。如果你在主分支上创建了一个 Agent 工作区然后又在另一个目录试图 checkout 主分支Git 会直接报错。这种情况在 Worktrunk 中的体现是如果你在运行worktrunk agent new时当前主仓库正处于某个非主分支上Worktrunk 生成的 Agent 分支会基于这个非主分支而不是基于主分支。这是我早期踩过的一个坑有一次主仓库停在feature/x分支上我给 Agent A 和 Agent B 各建了一个工作区结果两个 Agent 的分支都基于feature/x等 Agent 跑完 merge 回主分支时把feature/x上的半成品代码全都带进来了。排查方法执行worktrunk list时留意每个 Agent 分支的Last Commit是否和主分支同源。如果发现分支起点不对用git log --oneline --graph agent-branch --not main查看 Agent 分支是否包含了不应包含的提交。预防的办法是在worktrunk init之后、创建任何 Agent 之前确保主仓库处于干净的、基于主分支的 HEAD 位置。4.2 Worktree 目录删不掉git worktree remove失败的常见原因只有两个工作目录里有未跟踪或未提交的改动以及该目录是当前 shell 的$PWD。后者尤其在 Windows 环境下频发——你人还站在那个目录里Git 怎么敢删。Worktrunk 的cleanup有防御性检查会在删除前打印有问题的文件列表。但如果出现这种情况fatal: working trees containing modified or untracked files cannot be removed你有两条路走真正确认改动都不需要了用git worktree remove --force如果目录已经被搞得很乱但分支的提交历史还在可以接受目录残缺先把分支合并好然后用git worktree prune清理 Git 内部的 Worktree 记录。实操心得每次让 Agent 跑完任务后我第一步不是看代码而是先看有没有未提交的改动。AI Agent 经常会在完成任务后留下一些调试用的临时文件、测试日志或者未纳入 git 的配置文件你如果不检查直接 cleanup这些痕迹和潜在有价值的中间产物会全部丢失。我的习惯是让 Agent 跑完任务后立刻执行git status --porcelain把输出存档再决定清理策略。4.3 和 IDE 及开发工具的冲突用 Worktree 跑 Agent 时还有一个容易被忽视的问题你的 IDE 可能会把多个工作目录识别成同一个项目。如果你用 VS Code 打开myapp-agent-auth和myapp-agent-api两个目录代码补全和跨文件跳转有时候会串场因为两个目录里都有相同的node_modules和类型定义文件。我的应对方案是在.code-workspace文件里给每个工作区配置独立的path并且把 JavaScript/TypeScript 项目的tsconfig.json里的rootDir指清楚。如果你用的是 JetBrains 系列的 IDE同理在项目结构里手动把 Agent 工作目录识别为独立的模块不要混在一起。另一个常见的坑是lint 和格式化工具的配置漂移。假如主仓库用的是 Prettier而某个 Agent 在运行过程中自动修改了.prettierrc之后再合并回来就会有一堆格式化的噪音 diff。为了防止这种情况我在 Worktrunk 的状态文件里额外加了一个protectedFiles字段列出那些 Agent 不应该修改的文件路径。在实际使用中你是没法指望 LLM 主动克制不去动配置文件的最好的办法是在 Agent 的提示词里明确写不要修改 .prettierrc、eslint.config.js 等配置文件同时在 merge 时留意这些文件的 diff。4.4 磁盘空间占用异常Worktree 共享一个对象库通常不会占太多额外空间但在真实使用中它会膨胀。原因是每个工作区都有自己完整的node_modules或 Python 虚拟环境目录而这些目录通常被.gitignore忽略不会进入 Git 对象库但它们会真实占用磁盘空间。你开 5 个 Agent就等于把依赖装了 5 遍。如果你机器磁盘吃紧有几个变通思路第一把.gitignore里的依赖目录做成符号链接symlink指向一个公共的依赖缓存目录比如node_modules - ~/.cache/myapp-node_modules但要注意这可能会引入多个 Agent 同时修改同一个依赖文件的隐患实测下来 Node 生态相对安全Python 的__pycache__偶尔会互相干扰第二限制同时并行的 Agent 数量用 Worktrunk 的list和cleanup及时回收已完成的工作区第三用du -sh .worktrunk/*写一个定期检查的脚本在磁盘占用超过阈值时报警。4.5 与 CI/CD 的衔接问题Agent 的工作区本质上是本地分支如果你们团队用 GitHub Actions 之类的 CI 系统本地合并后推送就能触发 CI。但有一个细节要处理Worktree 的 remote 配置引用。Worktrunk 创建的工作区是从本地分支切出来的默认情况下没有配置 upstream你需要执行一次git push -u origin feature/agent-auth为了让这条链路顺畅我在 Worktrunk 的merge命令里加了一个--push参数合并完成后自动执行 push。如果 CI 要求 PRPull Request流程那就不能走直接 push 分支合并的路线你需要在 Worktrunk 之外额外调 GitHub CLI 创建 PR这也好办——gh pr create --head feature/agent-auth一条命令就能搞定。5. 从 Worktrunk 到更大的 Agent 编排视角聊完具体命令和排查我想跳出工具本身说说这套思路带给我的启发。过去我们编排多个 Agent重点往往放在怎么让 Agent 之间通信、怎么共享上下文这些偏模型层面的设计上。但真实跑起来你会发现Agent 之间最严重的冲突源不是语义层面的理解不一致而是文件系统和 Git 状态层面的读写冲突。两个 Agent 哪怕用同一个 prompt 模板只要它们在同一时刻写同一个文件结果一定是灾难。Git Worktree 加 Worktrunk 提供的这一层隔离相当于在物理层面把Agent 的可见世界切分开了——每个 Agent 只能看到自己工作目录下的文件它对全局的认知只通过 Git 分支的合并来同步。这个思路和微服务架构的演进有点异曲同工。一开始你把所有代码放在一个单体仓库里靠规范和纪律约束不同开发者的修改边界后来发现做不到就拆成独立服务、独立部署、独立数据存储。多 Agent 并行开发也是同一个道理与其指望 Agent 不越界不如从一开始就给它一个越不了界的环境。Worktrunk 本身只解决 Git 工作区隔离这一层但它和现在的 AI Agent 开发生态能拼成一套更完整的工作流。比如你可以把 Worktrunk 和目录级权限控制搭配使用——在容器里跑 Agent 时把 Agent 的工作目录挂载为只读或限定写权限进一步兜底也可以把worktrunk agent new集成到你的 Agent 编排脚本里每次要下发任务时自动创建一个新的隔离工作区任务结束自动清理。我在自己的一个内部小项目中就是这么做的用一个 Python 脚本调度 Codex CLI 实例每个实例通过 Worktrunk 拿到独立目录跑完所有任务后统一合并、统一汇总。最后分享一个我现在固定的工作习惯不管什么任务只要涉及多个 Agent 并行我一定会先用worktrunk agent new给每个 Agent 开独立工作区然后无论如何都不让它们在主目录里直接动手。这个习惯坚持了快两个月并行开发的返工率明显下降。工具本身不复杂一两句话就能说清用法但它背后先隔离、再并行、最后合并的思路才是真正值得借鉴的东西。