过去三周我把自己项目的开发方式彻底改成多 AI Agent 并行工作流之后，几乎每天都在和 Git Worktree 打交道。单个代理时代这个问题根本不存在——一台机器一个工作目录，一个 CLI 工具只要管好眼前的分支就够了；可一旦同时跑三个、五个代理会话，普通的git switch就会变成灾难源头：代理 A 刚把src/auth.ts改到一半，代理 B 切个分支过来直接提示Your local changes would be overwritten，整个会话被迫中断。这篇文章要聊的 Worktrunk，就是我把 Git Worktree 的管理经验固化出来的一个小型 CLI，专门面向这种"多个 AI Agent 在同一仓库里各干各的活"的场景。我会从痛点拆解、工具设计、实际操作到踩坑记录，完整讲一遍这套方案的来龙去脉。
1. 并行 AI Agent 工作流的真实痛点：为什么开关分支行不通
1.1 多代理并发的典型崩溃现场
先还原一个我在项目里真实遇到的场景。当时我开了一个主分支main，然后让 Codex CLI 去实现用户登录模块，让 Claude Code 去重构导出功能，我自己同时在同一份代码里调样式。听起来分工明确对吧？实际操作五分钟之后就开始出问题。
第一个问题出现在"切换分支"这个动作上。代理在一个分支工作到一半，我需要切回主分支查看某个历史逻辑，于是执行了git checkout main。结果工作区的未提交修改被 Git 死死拦住，我得先想办法处理这些改动。对单个人类开发者来说，这也许就是 commit 或 stash 一下的事，但对 AI Agent 来说完全不一样——代理的运行上下文、它记住的"当前状态"、它正在跑的 watch 脚本，全都被打断了。等你切回代理分支重新启动会话，它已经忘了刚才改到哪，甚至可能重新生成一份和现有修改冲突的代码。
第二个问题更隐蔽：共享工作目录导致的状态污染。三个代理都在同一个目录里读写dist/、node_modules/、测试报告、日志文件。代理 A 跑完测试生成了覆盖率报告，代理 B 下一轮构建直接把这个报告当输入吃进去；代理 C 在配置里改了端口号，代理 A 的接口测试立刻报连接失败。这些不是 git 层面的冲突，而是物理目录层面的强耦合，是分支切换解决不了的问题。
第三个问题出现在"验证代码"的环节。代理写完一段逻辑，常规操作是跑测试、起服务、看运行结果。如果所有代理共用一个工作区，跑服务就意味着抢占端口；跑测试就意味着大家共用同一份编译产物。到最后，我根本无法判断当前目录里那一堆报错到底是谁的代码引入的。
1.2 git worktree 能解什么，不能解什么
这也是我转向 Git Worktree 的直接原因。git worktree允许你在同一个仓库下创建多个工作目录，每个工作目录都可以签出不同的分支，而它们共享同一个.git对象库。你可以在.agents/login目录里检出一个agent/login分支，同时在.agents/export目录里检出另一个agent/export分支，两边互不干扰。每个工作树都有自己独立的 HEAD、索引和工作区文件，git add、git commit、git diff在自己的目录里随便跑，不影响其他工作树。
这个机制天然适合 AI Agent 并行工作：代理 A 在agents/auth里改认证逻辑，代理 B 在agents/report里改导出模块，两者都可以拥有各自的node_modules、.env.local、dist/输出目录，甚至可以各自启动独立的开发服务器——端口冲突通过配置文件错开就行。更重要的是，它们永远不会因为另一个代理"切走了分支"而中断上下文。
但裸用git worktree也有明显短板。官方命令只管"创建树""删除树"这种最底层的操作，不管业务层面的问题：这个工作树是给哪个任务开的？对应的分支应该叫什么名字？代理干完活之后代码该合给谁？多个工作树的磁盘占用怎么控制？工作树长时间不用，怎么判断该不该清理？我自己用 shell 脚本封了一层，后来又发现脚本越写越复杂，跨任务、跨会话的状态没法统一管理，最后干脆做成了 Worktrunk 这个 CLI，把所有决策固化到配置文件里。
2. Worktrunk 的模型：把每个工作树当成一个代理会话容器
2.1 为什么不用现成的 git worktree 裸命令
在我最早期的方案里，每次开新任务都手动执行一段固定流程：git branch创建分支、git worktree add添加目录、然后写一个 txt 文件记录任务描述。这套流程在开两三个任务时还能撑住，一旦任务并发超过五个，就彻底失控了。其中最烦的还不是命令多，而是"状态靠脑子记"这件事。
比如我在.agents/login里开了一个任务，工作好几天之后，光看目录名根本想不起来这个任务的基分支是main还是release/v2，代码改到一半有没有提交过，代理是否已经跑完最后一轮测试。用git worktree list能看到每个目录对应哪个分支，但"这个分支对应什么任务"、"任务处于什么阶段"这类业务信息完全没有。
Worktrunk 的核心思路，是把每个工作树抽象成"一个代理会话容器"，并给这个容器补齐两类信息：
- 基础设施信息：路径、分支名、基分支、创建时间；
- 业务状态信息：任务描述、目标、当前阶段（spawned / in_progress / review / merged / closed）、关联的代理日志。
这些信息统一存放在仓库根目录下的一个状态文件里，Worktrunk 的所有命令都围绕这份状态文件运转。这样无论过了多久，只要执行一条wt list，所有会话的状态就一目了然。
2.2 状态文件、分支命名与目录约定
Worktrunk 在仓库根目录建一个.worktrunk/config.yml作为全局配置，同时在一个隐藏目录里维护任务状态。下面是一个真实的配置示例：
project: myapp worktree_root: .agents branch_prefix: agent base_branch: main agent_context_file: AGENTS.md这意味着默认情况下：
- 所有工作树都会创建在
.agents/目录下； - 分支统一使用
agent/<task-slug>前缀； - 新任务默认基于
main分支创建； - 每个工作树里会自动生成一份
AGENTS.md，用于引导进入该目录的 AI Agent。
wt spawn命令在创建任务时，会执行一套确定的命名逻辑。假设我输入的任务名是登录页前端重构，它会自动转成login-page-refactor这样的 slug，然后生成目录.agents/login-page-refactor、分支agent/login-page-refactor。这种命名的价值在于：目录名、分支名、任务标识三者完全对齐，无论通过文件系统、git 命令还是状态文件定位某个会话，都能对得上号。
状态文件长这样：
tasks: - id: login-page-refactor name: 登录页前端重构 base_branch: main branch: agent/login-page-refactor path: .agents/login-page-refactor status: in_progress created_at: "2025-06-10T09:30:00+08:00" agent: codex2.3 工作树之间的依赖隔离与共享缓存
多个工作树并行运行的另一个实际问题是磁盘占用和依赖重复安装。一个 Node.js 项目的node_modules动辄几百 MB 到几个 GB，如果每个工作树都完整安装一遍，开五个代理会话就是五倍空间，本来没什么大不了，但在 SSD 快满的笔记本上，这绝对是一个真实的烦恼。
Worktrunk 的做法是对依赖目录做分级处理。对于可以安全共享的依赖缓存（比如 pnpm 的全局 store、npm 的 cache），让多个工作树通过环境变量指向同一个缓存目录，不重复下载。对于必须隔离的目录（node_modules本身、.venv），保留在工作树内。遇到.env这种环境配置文件，Worktrunk 不会自动复制到新工作树，而是生成一份.env.example和一段提示信息，让开发者或代理按需手动补齐——避免登录密钥、API Token 之类的内容被代理无意识地带到分支提交里去。
另外，Worktrunk 会对输出目录做约定管理。凡是代理生成的产物，比如dist/、coverage/、*.log，默认统一添加到该工作树的.git/info/exclude里，确保这些文件不会因为代理的误操作混进提交。这个细节在实际使用中极其重要，AI Agent 在跑测试时经常顺手生成一堆临时文件，如果不提前排除，最后 review 代码时会看到数量惊人的无用改动。
3. 实战操作：用 Worktrunk 把三个代理同时拉起来
3.1 安装与前置依赖
Worktrunk 是一个单文件 CLI，安装方式很简单，二进制放到 PATH 里就行。前置依赖主要有三个：Git 版本不低于 2.30（因为早期版本的 worktree 功能在文件锁和引用操作上有些小毛病）、一个能跑 bash/zsh 的终端环境、以及对应的 AI Agent 工具本身（Codex CLI、Claude Code 等）。
项目初始化只需要一条命令：
cd /path/to/myapp wt init --name myapp --base main初始化做的事情很简单：检查当前目录是否是合法的 git 仓库，确认main分支存在，然后生成.worktrunk/config.yml。同时把.worktrunk/目录加入.gitignore——状态文件是本地开发状态，不需要也不应该提交到远程仓库。
3.2 创建三个代理任务工作树
初始化完成之后，我用三条命令创建三个并行任务：
wt spawn login-page --base main --agent codex --desc "重构登录页 UI 并接入新 API" wt spawn export-report --base main --agent claude --desc "实现数据导出为 Excel 的功能" wt spawn fix-race-condition --base main --agent codex --desc "修复并发请求下用户状态竞态问题"执行wt spawn后，Worktrunk 会在后台执行一串标准操作：
- 基于
main创建新分支agent/login-page； - 在
.agents/login-page添加对应的工作树； - 在工作树内生成
AGENTS.md，把任务描述、基线分支、验证命令写进去； - 更新状态文件，把这个任务标记为
in_progress。
这个过程大概几秒钟完成。如果创建失败（比如分支已存在、路径被占用），Worktrunk 会直接回滚所有操作，不会留下半截工作树。
3.3 启动 AI Agent 并验证隔离性
现在我可以分别在三个目录里拉三个代理。每个代理的当前工作目录都各不相同，它的改动只落在这个目录对应的工作树里，天然隔离。
cd .agents/login-page codex exec --full-auto --sandbox workspace=/path/to/myapp/.agents/login-page cd ../export-report claude -p "实现数据导出功能，先读 AGENTS.md" cd ../fix-race-condition codex exec --full-auto --sandbox workspace=/path/to/myapp/.agents/fix-race-condition关键细节在于每个代理的启动参数。Codex CLI 和 Claude Code 这类工具基本都支持设置工作根目录，我把工作根目录指向对应的工作树路径，同时明确告诉代理先读取AGENTS.md。这样代理的认知边界和 git 边界就完全重合了，它看到的就是它需要改的那部分代码。
验证隔离性有一个很简单的办法：分别在三个目录里执行git status、git log --oneline -3和git branch --show-current，可以确认三个目录指向不同的分支、有各自独立的 HEAD。再让两个代理同时跑npm run dev，在各自的工作树里配置不同的端口号，比如 3001 和 3002，两个服务就可以并行启动，互不干扰。
4. 会话生命周期：从代理交活到清理资源
4.1 代理完成后如何安全合并
当某个代理完成自己的任务后，我不会立刻把它的分支合进主分支，而是先执行 Worktrunk 的审阅逻辑：
wt review login-page这条命令会输出该工作树对应的分支相对基分支main的所有变更摘要，包括修改文件列表、新增文件、删除文件、粗略的 diff 统计。它也会提醒我检查AGENTS.md中记录的验证命令是否已全部跑过。这里的原则是：AI Agent 产出的代码必须经过人工或自动化测试的确认，Worktrunk 不鼓励无脑合并。
确认没有问题后，执行：
wt merge login-pagewt merge内部会进入.agents/login-page目录，切换到main分支，拉取最新代码，把agent/login-page分支合并进来。默认使用--no-ff合并，保留一个明确的合并提交，方便以后追溯某个任务是什么时候合入的。合并成功后，工作树和分支是否保留，由参数决定：我通常用--cleanup让它在合并完成后自动移除工作树并删除本地分支。
4.2 冲突规避和自动化处理
只要两个代理改动的文件区域不重叠，合并时一般不会出现冲突。但并行开发中冲突仍然难以完全避免，尤其是都改了公共类型定义或路由配置的时候。基于这段时间的实测，我认为比较好的策略是：防 > 解。
从防的角度，我会在spawn阶段就把任务边界切细。比如"重构登录页 UI"和"实现数据导出"这两个任务，涉及的模块几乎没有交集；而"重构登录页 UI"和"修改登录接口类型定义"就很容易撞车，应该串行安排或明确划分模块。Worktrunk 本身不能替我做任务拆分，但它能在wt spawn时主动检查当前有哪些进行中的任务，如果任务描述里出现相同的关键路径，会给出警告。
从解的角度，如果合并冲突确实出现，wt merge会中止并给出明确报错。这时我进入.agents/login-page目录手动解决冲突，然后执行git merge --continue，最后再用wt review重新检查一遍。要注意，代理生成的代码里，冲突标记<<<<<<<偶尔会被它当作普通文本保留下来，解决完冲突后要全仓库搜索一遍确认没有遗漏标记。
4.3 清理和磁盘回收
并行工作流的会话数量会快速膨胀。前两天我开了七个任务，每个工作树都是完整的项目副本，磁盘占用瞬间多了近 8GB，其中绝大部分是各自独立的node_modules。Worktrunk 提供了两条清理路径。
对已经合并完的任务，wt clean --merged会找出所有状态为merged的工作树，逐个执行git worktree remove并删除对应分支，同时清理状态文件中的记录。对长期没有进展的僵尸任务，wt list --stale能看到最近一次活动时间超过一定天数的会话，由我确认后统一删除。
还有一个很少人留意的细节是共享仓库的 gc。每个工作树共享同一个.git对象库，当某个工作树里执行了git gc或者大量变基操作，对象库会进入压缩状态，同一时间其他工作树的 git 操作可能短暂变慢甚至遇到index.lock报错。我的建议是：不要让多个代理在同一时刻并发执行大型 git 操作，至少不要在同一台机器上针对同一个仓库同时跑git gc。如果确实需要执行，可以在状态文件里临时标记一个maintenance锁，Worktrunk 的钩子会阻止其他会话在锁期间发起写操作。
下面是几个关键命令的速查表：
| 命令 | 作用 | 常用参数 |
|---|---|---|
wt init | 初始化项目配置 | --name、--base |
wt spawn | 创建任务工作树 | --base、--agent、--desc |
wt list | 查看所有任务状态 | --stale、--status |
wt review | 输出变更摘要和检查清单 | 无 |
wt merge | 合并任务分支到基分支 | --cleanup |
wt clean | 清理已合并或废弃工作树 | --merged、--force |
5. 与 Codex CLI / Claude Code / IDE 的集成实测
5.1 命令行 AI Agent 的接入模式
Codex CLI 和 Claude Code 是目前我主力使用的两个命令行 AI 代理工具。它们的接入逻辑其实大同小异：在工作树目录里启动，告诉它工作根目录，让它在受限的沙箱或工作区内运行。Worktrunk 在spawn阶段生成的AGENTS.md，是实现这一步无缝衔接的关键。
实际生成的AGENTS.md内容大致如下：
# 任务：登录页前端重构 ## 目标 重构登录页 UI，接入新认证 API。 ## 基线分支 main ## 验证命令 - npm run lint - npm run test:unit ## 约束 - 只修改本项目内代码 - 不要提交 .env 文件 - 完成后运行全部验证命令并在 CLAUDE.md 中记录结果代理进入工作树后，第一眼读到的就是这份文件。它的行为边界、任务目标、验收方式，全都是显式的。Codex CLI 的--sandbox参数会把文件系统读写限制在指定目录，Claude Code 的权限模式也可以设置只允许修改当前目录。这相当于给代理上了一道物理锁，比单纯在提示词里说"别乱改"可靠得多。
实际运行中我会额外做一个小动作：在spawn之后先在每个工作树里执行一条git fetch origin && git reset --hard origin/main，确保工作树的基线版本一致。否则后续合并回main时，基线不一致会导致非预期的差异。
5.2 IDE 多窗口场景
如果代理开发过程中需要我人工介入调试（比如看 UI 渲染效果），我会直接用编辑器打开对应的工作树目录。IDE 把.agents/login-page当成一个独立项目文件夹打开，Git 面板会正确识别这是一个 git worktree，能正常显示当前分支和改动文件。多个工作树分别放在多个窗口里，互不打架。
这里有个容易踩的坑：不要在 IDE 里同时打开仓库根目录和某个工作树目录，然后把二者当作一个项目里的多根目录来用。因为它们的 Git 状态来自同一个仓库但指向不同的 HEAD，有些编辑器的源码管理面板会把二者叠加显示，提交时会混入另一个工作树的分支信息。我平时都是严格"一个工作树 = 一个窗口"，物理上避免这种混乱。
5.3 钩子脚本与轻度自动化
Worktrunk 预留了简单的 Hook 机制，支持post-spawn、post-merge等事件。我实际用得最多的是post-spawn：它在工作树创建完成并生成AGENTS.md之后触发，让外部脚本自动写入代理会话号、初始化本地环境变量文件，甚至可以直接拉起一个后台的npm install。
每个工作树里还有一个session.json，记录这个任务与哪个代理实例对应、会话 ID 是什么、最后一次修改时间。代理跑完后，我可以通过一条简单命令把日志归档到.worktrunk/logs/<task>/下，方便日后复盘某个任务到底是怎么完成的。对于写了大量失败尝试、最后活下来的代理会话，这个日志能帮你理解它为什么那样改，比直接看代码 diff 有效得多。
6. 踩坑记录：关于并发代理工作流的几点反思
6.1 高频报错与解决路径
并行使用多个 Git Worktree 时，有几个报错是我在短时间内反复踩过的，这里做一个清单：
| 报错内容 | 原因 | 解决方案 |
|---|---|---|
fatal: '<path>' already exists | 目标目录非空 | 用空目录或使用--force，或先清理既有文件 |
fatal: A branch named 'agent/xxx' already exists | 分支已经存在 | 检查分支归属，不要重复-b，改用wt open打开已有工作树 |
error: unable to unlink old 'dist/main.js' | 输出目录正被其他进程占用 | 关闭该目录下的打包/监控进程，或让各工作树输出到不同目录 |
fatal: this operation must be run in a work tree | 进入了.git目录或未正确识别工作树 | 检查当前目录是否是 worktree 目录，执行git worktree list确认 |
Another git process seems to be running | 多个 git 操作并发产生锁 | 等锁释放，或删除.git/index.lock（确认没有 git 进程时） |
最需要注意的还是最后一个锁问题。我曾试过在三个工作树里同时让代理各自提交代码，结果其中一个会话报出index.lock冲突。原因在于所有工作树共享同一个.git目录，索引锁虽然通常按工作树隔离，但引用更新、对象压缩等操作会在仓库级做全局锁。后来的对策是给每个工作树的代理提示词里加上一条约束：提交前先确认没有其他会话正在执行大型 git 写操作。这个约束不是 100% 防住，但能显著降低报错频率。
6.2 设计上的取舍：为什么我不做全自动合并
在规划 Worktrunk 的时候，有人建议我做"代理任务完成后自动合入主分支"的完全自动化流程。我考虑后否决了。原因在于 AI Agent 生成的代码在多数场景下仍然需要人工审阅，尤其是跨模块改动涉及隐式依赖的时候。全自动合并带来的效率提升，不足以抵消"合入一个 bug 到主分支然后全链路排查"的代价。
所以 Worktrunk 默认的路径是：代理产出 →wt review输出变更摘要 → 人工或 CI 检查 →wt merge合并。这条路径在牺牲少量自动化的同时，保证每个代理会话的产物都经过一道明确的关卡。
另一个取舍是不自动清理工作树。我见过有些工具会在分支合并成功后立刻删掉工作树，这看起来干净，但 AI Agent 的会话经常出现"合并完又发现要补改一个问题"的情况。如果工作树已被删除，代理上下文就断了，重新创建会话成本很高。因此 Worktrunk 默认只把任务标记为merged，真正删除由wt clean操作决定。
6.3 这个方案的适用边界
最后说说什么场景适合 Worktrunk 这套做法。如果你每天要同时维护多个 AI Agent 任务，且这些任务都作用于同一个代码仓库，那么基于 Git Worktree 的会话隔离几乎是最好的方案。它让每个代理有自己的完整世界视图，不互相踩脚，又共享同一个对象库带来的轻量优势。
反之，如果你的代理任务大多只涉及单文件的小改动，或者你同时只有一两个会话，那么直接开条分支就够了，不需要额外引入工作树管理工具。此外，如果代理需要跨多个仓库协同改动（比如前端的组件库和后端服务同时改），工作树管理解决不了仓库之间的一致性问题，你需要的是更大的 monorepo 改造或跨仓库编排方案，那是另一套复杂度的东西。
对我个人而言，这套工具带来最明显的变化是：并行代理从"听起来很美好但一跑就乱"变成了一个真正可稳定的日常节奏。每个代理都有明确的沙盒、明确的任务书、明确的验收路径，我只需要在关键节点把一次关。如果你也正被多代理并行搞得焦头烂额，我建议先别急着上复杂的任务编排框架——把 Git Worktree 用好，再在外面套一层会话状态管理，也许就能解决你 80% 的混乱。
