2026/9/19 7:08:03
FEATURED · 精选文章 
1. 项目概述与核心思路先说结论Worktrunk 是一个把 Git Worktree 操作封装成项目级命令的 CLI 工具核心场景是让多个 AI Agent 在同一仓库内互不干扰地并行干活。这半年做 AI 编程相关的工作应该都体会过一个痛点Codex CLI、ZCode CLI、Claude Code 这类工具同时往一个仓库里读写不出一小时就会互相踩踏。A agent 改完了src/api/client.tsB agent 不知道继续在旧内容上做修改最后 git 冲突多到不想看。更麻烦的是有些 agent 还会自作主张地git stash、git reset把你的本地改动全部冲掉。传统解法有三种给每个 agent 克隆一份仓库、用 docker 隔离、或者让 agent 排队串行。但三种都有明显缺陷。克隆仓库要重复拉依赖磁盘开销大合并回来还得手动处理 remote 关系docker 隔离虽然彻底但配置成本和工作流切割成本都不低串行最稳也最浪费四个 agent 干活变成四倍时间。Git Worktree 一直是解决这类问题的原生方案。它允许你在同一个仓库下开出多个工作目录每个目录绑定独立分支共享同一个.git对象库。不是复制仓库只是复制工作区 分支指针磁盘占用极小。可惜原生命令用起来有点繁琐尤其是多 agent 并行时会话一多git worktree list一长串信息根本分不清哪个目录对应哪个任务哪个分支要被合并回主干。Worktrunk 做的事情其实很简单把 开工作区、绑定分支、记录任务上下文、合并回主干、清理工作区 这一整套流程收敛成一个命令行工具里的几个短命令。它让你面对的不是裸的 git worktree 语法而是任务和工作区的对应关系。每个 agent 分配一个工作区干完活合并最后统一回收。这篇内容适合正在用或准备用 AI Agent 做编码、想搭建多 Agent 并行工作流的开发者。无论你是自己写 agent 工作流还是团队里多人配合多个 AI 编程工具Worktrunk 这种管理思路都值得参考。我会把命令设计、原理解析、完整实操和踩坑记录全部展开照着走一遍就能用起来。1.1 核心需求解析先说需求侧。实际工作中用 AI agent 编程最典型的场景是这样的你有四个模块需要 AI 协助比如写一个新的 API 路由、修一个已知 bug、补单元测试、重构某个 utility 函数。如果你把这些任务一股脑发给同一个 agent 会话会有两个问题。第一个问题是 agent 的上下文长度有限任务一多前面任务的细节就记不清了。第二个问题是 agent 的执行环境总是同一个目录它改到一半你能看到文件变化但它改完这个任务再去碰另一个任务文件系统就成了一个巨大的共享状态容易串味。所以更合理的组织方式是一个任务对应一个 agent 实例一个 agent 实例对应一个独立工作区。这样隔离是完整的文件系统隔离、分支隔离、上下文隔离。Git Worktree 恰好同时满足这三项Worktrunk 则解决了这层隔离的易用性问题。1.2 与通用 Git Worktree 命令的差异原生git worktree add指令本身不复杂git worktree add ../project-feature-a -b feature/a问题出在管理侧。开十个 worktree 容易但你需要记住../project-feature-a对应哪个 feature 分支哪个 worktree 已经合并完了可以删除合并回主干的时候目标分支是main还是develop连续开了多个 worktree 后哪些还处于工作状态这些元信息命令本身不会帮你记录。Worktrunk 把这些状态变成了一个清单文件每次开工作区、切换任务、合并、清理都会同步更新这个清单。你随时可以查看当前所有并行工作区的状态类似一个轻量级的任务看板。2. 核心细节解析与实操要点2.1 Git Worktree 基础原理解读想用好 Worktrunk至少得理解 Worktree 的几个底层机制。它不是魔法就是一个被不少开发者忽略的原生能力。一个正常 clone 下来的 Git 仓库包含三部分.git目录对象库、引用、配置、工作区你实际编辑的文件、索引暂存区。git worktree add做的事是在.git/worktrees/下新建一个管理目录里面保存这个新工作区对应的 HEAD、索引、以及指向主仓库.git的链接。本质上它不是复制仓库而是给同一个对象库新增了一条工作区到引用的映射。这意味着几件事共享对象存储几乎零额外磁盘占用。开十个 worktree 不会像 clone 十份那样吃几个 GB 的空间。分支是独立的但对象是共享的。每个 worktree 检出独立分支但提交的对象都写进同一个对象库里。所以合并、diff、cherry-pick 都非常快因为两份代码共享绝大多数对象。不能在同一分支上开两个 worktree。默认规则下一个分支只能被一个工作区检出。所以每个 agent 必须有独立分支这也是 by design 的。主工作区不能删除。只要仓库的主工作区还在任何对 worktree 的操作都不会影响对象库里的内容。理解这几点后你就明白 Worktrunk 的分支管理策略为什么是强制的每个新任务默认开启一个新分支任务结束后由人工确认合并然后清理。2.2 配置格式与任务清单设计Worktrunk 的状态存储我做成了仓库内的一个隐藏目录.worktrunk/里面放一个state.json。每次操作都会读取并更新这个文件。为什么不用数据库或全局配置因为项目的状态应该跟项目走而不是跟着某台机器的用户目录走。一个典型的 state.json 结构{ version: 1, mainBranch: main, worktrees: [ { id: task-42, branch: feature/task-42-login-page, path: ../worktrees/task-42, agent: codex, status: in-progress, createdAt: 2025-06-01T10:00:00Z, mergedAt: null }, { id: task-43, branch: feature/task-43-refactor-utils, path: ../worktrees/task-43, agent: zcode, status: ready-to-merge, createdAt: 2025-06-01T10:05:00Z, mergedAt: null } ] }字段设置是有讲究的。id是你给任务取的短名字后续所有命令都会用到比如worktrunk switch task-42。branch是实际创建的 git 分支名为了减少 agent 操作时的路径歧义默认跟 id 强绑定。path是这个 worktree 的工作目录我会把统一的工作区都放到主仓库同级的worktrees/目录下这样所有并行工作区都在同一层管理和清理都方便。agent是可选字段标记这个工作区是给哪个 agent 用的。如果 worktrunk 能自动识别当前终端环境变量里的 agent 类型就会自动填充。status则用来标记当前生命周期阶段包括in-progress、ready-to-merge、merged、stale几个枚举值。2.3 命令设计思路Worktrunk 的命令设计围绕一条核心链路create → switch → sync → merge → cleanup。worktrunk create task-42 --base main --agent codex创建一个新的工作区确认分支不存在后自动创建分支并检出。worktrunk list列出所有工作区标注状态、分支名、最近提交时间方便快速排查。worktrunk switch task-42在当前 shell 中切换某个工作区实际上就是输出一条cd指令。由于 CLI 进程无法改变父 shell 的工作目录我在这里做了一个小的 shell 函数封装让worktrunk switch能直接作用于当前终端。这个细节对 agent 工作流特别重要因为 agent 通常通过 shell 命令执行操作它并不关心 cd 背后的机制但需要路径有效。worktrunk sync依次在每个 worktree 里执行git fetch和git status汇总展示有哪些工作区落后于主干、哪些有未提交改动。worktrunk merge task-42 --to main把指定工作区的分支合并进主干分支。执行前会检查工作区是否有未提交改动、目标分支是否干净检查通过后切换到目标分支执行 merge。worktrunk cleanup清理所有已合并且无未提交改动的 worktree同时删除对应的分支。这套命令并不复杂但每一步都卡在关键动作上并且把多个原生 git 命令组合成了高内聚的原子操作。举个例子原生git worktree add需要指定路径和分支名然后还要git checkout还要确认这是否是你想要的工作区路径策略三个动作在 Worktrunk 里被合并成一个 create 命令并且自动记录到状态清单里。3. 实操过程与核心环节实现3.1 环境准备与安装方式Worktrunk 依赖 Git 2.30 以上版本主要是git worktree list --porcelain这类命令在更早版本中输出不稳定。Python 版本要求 3.10 以上用argparse写命令行入口没有太多花哨依赖。安装命令很简单pip install worktrunk # 或者用 pipx 安装避免污染全局 Python 环境 pipx install worktrunk安装后建议做一次性初始化worktrunk init --main main这个命令会在当前仓库创建.worktrunk/目录并且把state.json的mainBranch设置为你的主干分支名。如果你用的是develop或者trunk就传对应的分支名。我把作者的安装录入了配置强烈建议组织内的开发者统一配置避免每个人用不同的主干分支名导致状态文件互相覆盖。3.2 创建并行工作区的完整流程假设现在仓库在/projects/myapp主干分支是main我要让两个 AI agent 同时干两件事任务 A 写一个用户登录表单页面任务 B 重构工具函数模块。第一步在仓库根目录执行worktrunk create task-42-login --base main --agent codex输出大概是这样的[worktrunk] Creating worktree for task-42-login... [worktrunk] Branch feature/task-42-login [worktrunk] Path ../worktrees/task-42-login [worktrunk] Done. 切换到此工作区: worktrunk switch task-42-login此时观察一下仓库结构。主仓库仍然是你的默认工作区指针还停在main分支上。新的工作区在/projects/worktrees/task-42-login分支已经创建并检出且没有影响主工作区的一丁点内容。接着创建第二个worktrunk create task-43-refactor --agent zcode注意这里我刻意少传了--base main因为 Worktrunk 默认会读取 state.json 里的mainBranch字段绝大多数情况不需要重复指定。这时候你会看到worktrunk list输出ID BRANCH PATH STATUS AGENT task-42-login feature/task-42-login ../worktrees/task-42-login in-progress codex task-43-refactor feature/task-43-refactor ../worktrees/task-43-refactor in-progress zcode这个表格一眼就能看清两个 agent 各自在哪个目录、用了哪个分支、干到哪一步。3.3 与 AI Agent 的组合使用现在到了最有意思的部分如何把这两个工作区交给两个 agent。我实测下来最顺的组合是配 Codex CLI 或 ZCode CLI。每个 agent 有自己的终端或者用同一个终端轮流切换工作区。假设我用 Codex 处理登录表单页面。先切换工作区worktrunk switch task-42-login我的 zsh 配置里加了这样一个函数worktrunk() { if [[ $1 switch -n $2 ]]; then local target_dir target_dir$(command worktrunk switch $2) if [[ -d $target_dir ]]; then cd $target_dir else echo $target_dir fi else command worktrunk $ fi }它检测到worktrunk switch时会调用底层命令获取目标路径然后直接在当前 shell 执行cd。这样 agent 执行worktrunk switch task-42-login之后后续所有文件操作就都发生在正确的工作区里。切换到工作区后直接启动 CodexcodexCodex 会读取当前目录下的上下文比如.codex配置在这里我们手动或通过命令配置好项目级指令说明它的任务是完成登录表单页面。由于工作区是独立分支Codex 的每次提交只影响feature/task-42-login不会碰其他工作区。第二个 agent 同样操作只是切换到task-43-refactor的目录然后启动 ZCode。两个 agent 同时跑互相看不见对方的文件改动git 提交也是各自独立的完美符合预期。3.4 代码同步、提交与合并回主干当 agent 完成了一部分工作我们可以定期做一次状态总览worktrunk sync这个命令会遍历所有 worktree 执行git fetch origin和git status --short。如果有工作区落后于main它会在输出里提醒你。如果你的 agent 工具支持自动拉取最新main分支变更这一步特别重要因为并行分支之间的合并冲突本质上是信息不同步导致的。Worktrunk 在这里的作用是把落后提醒变成显式的。功能开发完成准备把 A 分支合并回主干。执行worktrunk merge task-42-login --to main --no-ffWorktrunk 内部会做这几件事检查task-42-login工作区没有未提交改动。切换到主工作区确保在main分支。执行git pull origin main如果要同步远端。执行git merge --no-ff feature/task-42-login -m Merge task-42-login: ...。更新 state.json把status改为merged记录mergedAt。合并完成后清理这个工作区worktrunk cleanup task-42-login此时它会把对应 worktree 删除同时删除feature/task-42-login分支因为已经合并进主干不会丢失。如果你忘了合并就想清理它会有一次交互式确认避免误删未合并内容。3.5 冲突预防策略大量实操后我发现worktree 隔离解决的是并行开发时文件乱动的问题但解决不了两个 agent 同时修改同一文件的冲突只是把冲突延迟到了合并阶段。为了尽可能减少合并冲突有几条策略值得刻意执行。第一个是明确划分模块边界。给 agent 布置任务时尽量让任务之间的改动文件不相交。比如一个负责src/pages/login另一个负责src/utils而不是两个 agent 都去改src/api/index.ts。第二个是养成频繁同步的习惯。每次worktrunk sync发现某个分支落后于main可以手动执行git merge main更新到该 worktree 分支而不是等到最后全部合并时一次性处理。因为越晚合并上下文差异越大冲突解决成本越高。我一般建议每天至少同步一次。第三个是创建分支时带上相关的上下文。如果你在create命令里加了--agent codexWorktrunk 会在分支说明里记下这个工作区是给哪个 agent 用的甚至可以在switch时自动向 agent 传递一个任务说明文件。这个文件放到工作区根目录的.worktrunk/TASK.mdagent 工具能自动读取它作为初始指令。实测下来这比在对话里反复说明要稳定得多。4. 常见问题与排查技巧实录4.1 高频问题速查表问题现象可能原因解决办法worktrunk create报分支已存在上一次执行后没有清理分支worktrunk cleanup id或手动git branch -D后重试worktrunk switch输出的路径无效worktree 目录被误删了用git worktree list核实路径必要时重新 createAgent 在工作区里看不到预期文件Agent 的启动目录不在工作区确认在启动 agent 前已经执行了cd可以用pwd检查worktrunk merge提示有未提交改动Agent 在工作区里留下了未提交文件手动进入工作区处理或让 agent 先 commit合并冲突一大片两个分支改动重叠较多用git log --graph --oneline --all查看分支分叉点逐个文件解决worktrunk cleanup想删但删不掉worktree 目录有锁定文件或文件被占用先清理工作区中的后台进程再执行git worktree prune后重试4.2 Worktree 被意外移动导致的冗余状态有一次我手动把某个 worktree 目录移动到了别处然后直接用git worktree remove去清理结果 Git 提示目录不存在。Worktrunk 的 state.json 里还标记着这个工作区为 in-progress产生了幽灵状态。排查方式是用git worktree list --porcelain看 Git 自己记录的路径然后手动更新或重新注册。后来我在 Worktrunk 里加了一条worktrunk refresh命令它会重新扫描 Git worktree 的官方列表和 state.json 做比对修复不一致的记录。这个命令在处理陈旧状态时非常管用。4.3 Agent 修改了错误分支的坑并行 AI agent 工作流最危险的情况是 agent 本身执行了分支切换操作。Codex CLI 或 ZCode CLI 在执行任务时通常会查看当前 git 分支但如果它发现当前分支不对可能会尝试git checkout main或git switch -c xxx。这在独立 worktree 里会带来灾难因为它在当前 worktree 里切换分支会直接导致工作区内容变化而 worktree 的约束只限制同一分支不能被两个 worktree 检出但 agent 可以在它的 worktree 里自由切换其他分支。解决办法是两层防护。第一Worktrunk 在创建 worktree 后会在工作区里放一个.git/info/exclude文件把.worktrunk/忽略掉减少 agent 意外修改状态文件的概率。第二建议在项目的 agent 配置里明确声明当前工作区的分支不得随意切换只允许在当前分支上提交和拉取。如果你的 agent 工具支持自定义指令一定要加这一条。4.4 Windows 环境下的路径分隔符问题如果团队里有 Windows 开发者会踩到路径分隔符的坑。Worktrunk 默认把 worktree 目录设置为主仓库同级的worktrees/目录当主仓库路径包含中文或空格时不同系统的路径拼接会有差异。我在代码里统一用pathlib处理不用字符串拼路径基本解决。但如果你用的是老版本遇到路径相关的报错先手动检查state.json里的 path 字段是否多了一个\或/。5. 进阶工作流与团队落地经验5.1 怎么规划 Agent 的工作区数量我见过很多团队一上来就开十几个 worktree结果 git 对象库虽然不大但状态管理混乱到崩溃。建议遵循一个经验法则同时进行中的 agent 任务数请控制在 3 到 5 个以内。原因不是技术限制而是人类的跟踪能力有限。超过这个数字人工审核合并时很难快速判断每个分支的代码质量反而降低整体效率。如果真的需要更多并行任务应当分阶段例如一个阶段同时推进 3 个合并完再开下一批。Worktrunk 的list输出设计成表格也是为了让状态一眼可读而不是开满一屏。5.2 通过 CI 钩子自动校验 Worktrunk 状态团队层面我给 Worktrunk 加了一个可选能力在 CI 的pre-merge阶段自动读取.worktrunk/state.json检查是否有标记为merged但 branch 仍存在的工作区。如果有CI 会打一个 warning提醒开发者执行 cleanup。这个钩子类似一个房间巡检防止状态文件与真实 git 状态长期脱节。实现也不复杂就是一个轻量的 CI 脚本在 merge 请求创建或更新时触发。这样即使开发者忘了 cleanup系统也会自动提醒。实测上线后团队里因为状态文件过期产生的排查时间大幅减少。5.3 从个人工具到团队工具的扩展如果只是个人用Worktrunk 的价值已经够明显。但当它变成一个团队的共同工具时需要约定几条规则否则状态文件会被不同人的操作搞花。推荐的做法是Worktrunk 的状态文件入库.gitignore 不忽略它这样所有团队成员共享同一个状态视图。每个人创建任务时其他人能立即在worktrunk list看到。但要注意不同人同时执行create可能会产生竞态。我在内部加了一个简单的文件锁在写 state.json 前创建一个.lock文件操作完成后释放避免两个并发命令互相覆盖。另一个建议是约定谁创建谁清理。每个工作区的清理操作尽量由创建者执行避免别人误删自己在做的内容。如果创建者休假了那就由 team lead 用worktrunk refresh核对状态后接管。5.4 后续可能的扩展方向基于现在的基础我已经在设计下一个插件接口把 agent 的类型识别解耦出去。目前内置了 codex 和 zcode 的检测逻辑但未来可能会有更多 agent CLI 工具出现比如把任务描述自动传给 deepseek CLI或者通过 MCP 把 worktree 信息暴露给 n8n 这类工作流平台。如果你也在搭类似的并行 agent 系统不妨抽时间看看项目里的agent_detector.py那部分是最好懂的扩展入口。我自己在持续试验的一个方向是把 worktree 列表同步给一个可视化面板通过 localhost 页面展示每个 agent 的实时状态。虽然 CLI 已经能满足基本需求但视觉化之后团队 review 的状态会轻松很多。6. 真实操作心得与避坑建议前面讲了不少结构和命令最后分享点实操中沉淀下来的心得。第一个心得是用 Worktrunk 之前先想清楚你的 agent 工具是否支持工作目录隔离。不同 AI agent 的上下文机制不一样有的 agent 会在启动时记录当前目录的所有文件内容如果你切换 worktree 后不重启 agent它仍然持有上一份工作区的文件索引。这会让你以为它改的是正确分支实际上它只是在旧上下文上生成代码然后写入命令指定的新目录。最稳妥的做法是每个任务一个独立 agent 进程不要跨工作区复用同一个 agent 会话。第二个心得是Worktrunk 的状态文件虽然有锁机制但并发写操作依然需要克制。早期我在一个任务里同时跑了四个 agent然后每十分钟执行一次 sync偶尔会遇上状态文件被覆盖。后来我改成每十五分钟 sync并手动确认没有另一个 worktrunk 命令在运行。普通团队的使用强度下锁机制是够用的但要避免写脚本无脑循环执行 create 和 merge。第三个心得是关于 agent 自动执行 git 操作的危险性。目前大部分 agent 工具并不会智能区分当前是在主工作区还是子工作区它们只会盲目地对我说话的那个目录操作。一旦 agent 在子工作区里执行了git merge main然后又 commit这通常没问题。但有些 agent 会顺手git push --force这就有风险了。强烈建议在 agent 的全局配置里禁用强制推送同时把 worktree 的 remote 设置为只读或者干脆不配置 remote只在合并回主干后才统一推送到远端。最后说一点点心法并行 AI agent 工作流的管理本质上是任务边界的管理。Worktrunk 解决的是渠道问题但真正决定效率高低的是你给每个 agent 划分任务时切得是否干净。如果一个任务需要 agent 同时改后端接口、前端页面、数据库脚本那无论用多少 worktree合并阶段都会异常痛苦。反过来按文件模块、按服务边界、按改动涉及面去切分任务配合 Worktrunk 的独立分支和状态跟踪你会发现多个 agent 并行不但不是灾难反而是效率提升最明显的手段。
Worktrunk：基于Git Worktree的多AI Agent并行开发管理方案
1. 项目概述与核心思路先说结论Worktrunk 是一个把 Git Worktree 操作封装成项目级命令的 CLI 工具核心场景是让多个 AI Agent 在同一仓库内互不干扰地并行干活。这半年做 AI 编程相关的工作应该都体会过一个痛点Codex CLI、ZCode CLI、Claude Code 这类工具同时往一个仓库里读写不出一小时就会互相踩踏。A agent 改完了src/api/client.tsB agent 不知道继续在旧内容上做修改最后 git 冲突多到不想看。更麻烦的是有些 agent 还会自作主张地git stash、git reset把你的本地改动全部冲掉。传统解法有三种给每个 agent 克隆一份仓库、用 docker 隔离、或者让 agent 排队串行。但三种都有明显缺陷。克隆仓库要重复拉依赖磁盘开销大合并回来还得手动处理 remote 关系docker 隔离虽然彻底但配置成本和工作流切割成本都不低串行最稳也最浪费四个 agent 干活变成四倍时间。Git Worktree 一直是解决这类问题的原生方案。它允许你在同一个仓库下开出多个工作目录每个目录绑定独立分支共享同一个.git对象库。不是复制仓库只是复制工作区 分支指针磁盘占用极小。可惜原生命令用起来有点繁琐尤其是多 agent 并行时会话一多git worktree list一长串信息根本分不清哪个目录对应哪个任务哪个分支要被合并回主干。Worktrunk 做的事情其实很简单把 开工作区、绑定分支、记录任务上下文、合并回主干、清理工作区 这一整套流程收敛成一个命令行工具里的几个短命令。它让你面对的不是裸的 git worktree 语法而是任务和工作区的对应关系。每个 agent 分配一个工作区干完活合并最后统一回收。这篇内容适合正在用或准备用 AI Agent 做编码、想搭建多 Agent 并行工作流的开发者。无论你是自己写 agent 工作流还是团队里多人配合多个 AI 编程工具Worktrunk 这种管理思路都值得参考。我会把命令设计、原理解析、完整实操和踩坑记录全部展开照着走一遍就能用起来。1.1 核心需求解析先说需求侧。实际工作中用 AI agent 编程最典型的场景是这样的你有四个模块需要 AI 协助比如写一个新的 API 路由、修一个已知 bug、补单元测试、重构某个 utility 函数。如果你把这些任务一股脑发给同一个 agent 会话会有两个问题。第一个问题是 agent 的上下文长度有限任务一多前面任务的细节就记不清了。第二个问题是 agent 的执行环境总是同一个目录它改到一半你能看到文件变化但它改完这个任务再去碰另一个任务文件系统就成了一个巨大的共享状态容易串味。所以更合理的组织方式是一个任务对应一个 agent 实例一个 agent 实例对应一个独立工作区。这样隔离是完整的文件系统隔离、分支隔离、上下文隔离。Git Worktree 恰好同时满足这三项Worktrunk 则解决了这层隔离的易用性问题。1.2 与通用 Git Worktree 命令的差异原生git worktree add指令本身不复杂git worktree add ../project-feature-a -b feature/a问题出在管理侧。开十个 worktree 容易但你需要记住../project-feature-a对应哪个 feature 分支哪个 worktree 已经合并完了可以删除合并回主干的时候目标分支是main还是develop连续开了多个 worktree 后哪些还处于工作状态这些元信息命令本身不会帮你记录。Worktrunk 把这些状态变成了一个清单文件每次开工作区、切换任务、合并、清理都会同步更新这个清单。你随时可以查看当前所有并行工作区的状态类似一个轻量级的任务看板。2. 核心细节解析与实操要点2.1 Git Worktree 基础原理解读想用好 Worktrunk至少得理解 Worktree 的几个底层机制。它不是魔法就是一个被不少开发者忽略的原生能力。一个正常 clone 下来的 Git 仓库包含三部分.git目录对象库、引用、配置、工作区你实际编辑的文件、索引暂存区。git worktree add做的事是在.git/worktrees/下新建一个管理目录里面保存这个新工作区对应的 HEAD、索引、以及指向主仓库.git的链接。本质上它不是复制仓库而是给同一个对象库新增了一条工作区到引用的映射。这意味着几件事共享对象存储几乎零额外磁盘占用。开十个 worktree 不会像 clone 十份那样吃几个 GB 的空间。分支是独立的但对象是共享的。每个 worktree 检出独立分支但提交的对象都写进同一个对象库里。所以合并、diff、cherry-pick 都非常快因为两份代码共享绝大多数对象。不能在同一分支上开两个 worktree。默认规则下一个分支只能被一个工作区检出。所以每个 agent 必须有独立分支这也是 by design 的。主工作区不能删除。只要仓库的主工作区还在任何对 worktree 的操作都不会影响对象库里的内容。理解这几点后你就明白 Worktrunk 的分支管理策略为什么是强制的每个新任务默认开启一个新分支任务结束后由人工确认合并然后清理。2.2 配置格式与任务清单设计Worktrunk 的状态存储我做成了仓库内的一个隐藏目录.worktrunk/里面放一个state.json。每次操作都会读取并更新这个文件。为什么不用数据库或全局配置因为项目的状态应该跟项目走而不是跟着某台机器的用户目录走。一个典型的 state.json 结构{ version: 1, mainBranch: main, worktrees: [ { id: task-42, branch: feature/task-42-login-page, path: ../worktrees/task-42, agent: codex, status: in-progress, createdAt: 2025-06-01T10:00:00Z, mergedAt: null }, { id: task-43, branch: feature/task-43-refactor-utils, path: ../worktrees/task-43, agent: zcode, status: ready-to-merge, createdAt: 2025-06-01T10:05:00Z, mergedAt: null } ] }字段设置是有讲究的。id是你给任务取的短名字后续所有命令都会用到比如worktrunk switch task-42。branch是实际创建的 git 分支名为了减少 agent 操作时的路径歧义默认跟 id 强绑定。path是这个 worktree 的工作目录我会把统一的工作区都放到主仓库同级的worktrees/目录下这样所有并行工作区都在同一层管理和清理都方便。agent是可选字段标记这个工作区是给哪个 agent 用的。如果 worktrunk 能自动识别当前终端环境变量里的 agent 类型就会自动填充。status则用来标记当前生命周期阶段包括in-progress、ready-to-merge、merged、stale几个枚举值。2.3 命令设计思路Worktrunk 的命令设计围绕一条核心链路create → switch → sync → merge → cleanup。worktrunk create task-42 --base main --agent codex创建一个新的工作区确认分支不存在后自动创建分支并检出。worktrunk list列出所有工作区标注状态、分支名、最近提交时间方便快速排查。worktrunk switch task-42在当前 shell 中切换某个工作区实际上就是输出一条cd指令。由于 CLI 进程无法改变父 shell 的工作目录我在这里做了一个小的 shell 函数封装让worktrunk switch能直接作用于当前终端。这个细节对 agent 工作流特别重要因为 agent 通常通过 shell 命令执行操作它并不关心 cd 背后的机制但需要路径有效。worktrunk sync依次在每个 worktree 里执行git fetch和git status汇总展示有哪些工作区落后于主干、哪些有未提交改动。worktrunk merge task-42 --to main把指定工作区的分支合并进主干分支。执行前会检查工作区是否有未提交改动、目标分支是否干净检查通过后切换到目标分支执行 merge。worktrunk cleanup清理所有已合并且无未提交改动的 worktree同时删除对应的分支。这套命令并不复杂但每一步都卡在关键动作上并且把多个原生 git 命令组合成了高内聚的原子操作。举个例子原生git worktree add需要指定路径和分支名然后还要git checkout还要确认这是否是你想要的工作区路径策略三个动作在 Worktrunk 里被合并成一个 create 命令并且自动记录到状态清单里。3. 实操过程与核心环节实现3.1 环境准备与安装方式Worktrunk 依赖 Git 2.30 以上版本主要是git worktree list --porcelain这类命令在更早版本中输出不稳定。Python 版本要求 3.10 以上用argparse写命令行入口没有太多花哨依赖。安装命令很简单pip install worktrunk # 或者用 pipx 安装避免污染全局 Python 环境 pipx install worktrunk安装后建议做一次性初始化worktrunk init --main main这个命令会在当前仓库创建.worktrunk/目录并且把state.json的mainBranch设置为你的主干分支名。如果你用的是develop或者trunk就传对应的分支名。我把作者的安装录入了配置强烈建议组织内的开发者统一配置避免每个人用不同的主干分支名导致状态文件互相覆盖。3.2 创建并行工作区的完整流程假设现在仓库在/projects/myapp主干分支是main我要让两个 AI agent 同时干两件事任务 A 写一个用户登录表单页面任务 B 重构工具函数模块。第一步在仓库根目录执行worktrunk create task-42-login --base main --agent codex输出大概是这样的[worktrunk] Creating worktree for task-42-login... [worktrunk] Branch feature/task-42-login [worktrunk] Path ../worktrees/task-42-login [worktrunk] Done. 切换到此工作区: worktrunk switch task-42-login此时观察一下仓库结构。主仓库仍然是你的默认工作区指针还停在main分支上。新的工作区在/projects/worktrees/task-42-login分支已经创建并检出且没有影响主工作区的一丁点内容。接着创建第二个worktrunk create task-43-refactor --agent zcode注意这里我刻意少传了--base main因为 Worktrunk 默认会读取 state.json 里的mainBranch字段绝大多数情况不需要重复指定。这时候你会看到worktrunk list输出ID BRANCH PATH STATUS AGENT task-42-login feature/task-42-login ../worktrees/task-42-login in-progress codex task-43-refactor feature/task-43-refactor ../worktrees/task-43-refactor in-progress zcode这个表格一眼就能看清两个 agent 各自在哪个目录、用了哪个分支、干到哪一步。3.3 与 AI Agent 的组合使用现在到了最有意思的部分如何把这两个工作区交给两个 agent。我实测下来最顺的组合是配 Codex CLI 或 ZCode CLI。每个 agent 有自己的终端或者用同一个终端轮流切换工作区。假设我用 Codex 处理登录表单页面。先切换工作区worktrunk switch task-42-login我的 zsh 配置里加了这样一个函数worktrunk() { if [[ $1 switch -n $2 ]]; then local target_dir target_dir$(command worktrunk switch $2) if [[ -d $target_dir ]]; then cd $target_dir else echo $target_dir fi else command worktrunk $ fi }它检测到worktrunk switch时会调用底层命令获取目标路径然后直接在当前 shell 执行cd。这样 agent 执行worktrunk switch task-42-login之后后续所有文件操作就都发生在正确的工作区里。切换到工作区后直接启动 CodexcodexCodex 会读取当前目录下的上下文比如.codex配置在这里我们手动或通过命令配置好项目级指令说明它的任务是完成登录表单页面。由于工作区是独立分支Codex 的每次提交只影响feature/task-42-login不会碰其他工作区。第二个 agent 同样操作只是切换到task-43-refactor的目录然后启动 ZCode。两个 agent 同时跑互相看不见对方的文件改动git 提交也是各自独立的完美符合预期。3.4 代码同步、提交与合并回主干当 agent 完成了一部分工作我们可以定期做一次状态总览worktrunk sync这个命令会遍历所有 worktree 执行git fetch origin和git status --short。如果有工作区落后于main它会在输出里提醒你。如果你的 agent 工具支持自动拉取最新main分支变更这一步特别重要因为并行分支之间的合并冲突本质上是信息不同步导致的。Worktrunk 在这里的作用是把落后提醒变成显式的。功能开发完成准备把 A 分支合并回主干。执行worktrunk merge task-42-login --to main --no-ffWorktrunk 内部会做这几件事检查task-42-login工作区没有未提交改动。切换到主工作区确保在main分支。执行git pull origin main如果要同步远端。执行git merge --no-ff feature/task-42-login -m Merge task-42-login: ...。更新 state.json把status改为merged记录mergedAt。合并完成后清理这个工作区worktrunk cleanup task-42-login此时它会把对应 worktree 删除同时删除feature/task-42-login分支因为已经合并进主干不会丢失。如果你忘了合并就想清理它会有一次交互式确认避免误删未合并内容。3.5 冲突预防策略大量实操后我发现worktree 隔离解决的是并行开发时文件乱动的问题但解决不了两个 agent 同时修改同一文件的冲突只是把冲突延迟到了合并阶段。为了尽可能减少合并冲突有几条策略值得刻意执行。第一个是明确划分模块边界。给 agent 布置任务时尽量让任务之间的改动文件不相交。比如一个负责src/pages/login另一个负责src/utils而不是两个 agent 都去改src/api/index.ts。第二个是养成频繁同步的习惯。每次worktrunk sync发现某个分支落后于main可以手动执行git merge main更新到该 worktree 分支而不是等到最后全部合并时一次性处理。因为越晚合并上下文差异越大冲突解决成本越高。我一般建议每天至少同步一次。第三个是创建分支时带上相关的上下文。如果你在create命令里加了--agent codexWorktrunk 会在分支说明里记下这个工作区是给哪个 agent 用的甚至可以在switch时自动向 agent 传递一个任务说明文件。这个文件放到工作区根目录的.worktrunk/TASK.mdagent 工具能自动读取它作为初始指令。实测下来这比在对话里反复说明要稳定得多。4. 常见问题与排查技巧实录4.1 高频问题速查表问题现象可能原因解决办法worktrunk create报分支已存在上一次执行后没有清理分支worktrunk cleanup id或手动git branch -D后重试worktrunk switch输出的路径无效worktree 目录被误删了用git worktree list核实路径必要时重新 createAgent 在工作区里看不到预期文件Agent 的启动目录不在工作区确认在启动 agent 前已经执行了cd可以用pwd检查worktrunk merge提示有未提交改动Agent 在工作区里留下了未提交文件手动进入工作区处理或让 agent 先 commit合并冲突一大片两个分支改动重叠较多用git log --graph --oneline --all查看分支分叉点逐个文件解决worktrunk cleanup想删但删不掉worktree 目录有锁定文件或文件被占用先清理工作区中的后台进程再执行git worktree prune后重试4.2 Worktree 被意外移动导致的冗余状态有一次我手动把某个 worktree 目录移动到了别处然后直接用git worktree remove去清理结果 Git 提示目录不存在。Worktrunk 的 state.json 里还标记着这个工作区为 in-progress产生了幽灵状态。排查方式是用git worktree list --porcelain看 Git 自己记录的路径然后手动更新或重新注册。后来我在 Worktrunk 里加了一条worktrunk refresh命令它会重新扫描 Git worktree 的官方列表和 state.json 做比对修复不一致的记录。这个命令在处理陈旧状态时非常管用。4.3 Agent 修改了错误分支的坑并行 AI agent 工作流最危险的情况是 agent 本身执行了分支切换操作。Codex CLI 或 ZCode CLI 在执行任务时通常会查看当前 git 分支但如果它发现当前分支不对可能会尝试git checkout main或git switch -c xxx。这在独立 worktree 里会带来灾难因为它在当前 worktree 里切换分支会直接导致工作区内容变化而 worktree 的约束只限制同一分支不能被两个 worktree 检出但 agent 可以在它的 worktree 里自由切换其他分支。解决办法是两层防护。第一Worktrunk 在创建 worktree 后会在工作区里放一个.git/info/exclude文件把.worktrunk/忽略掉减少 agent 意外修改状态文件的概率。第二建议在项目的 agent 配置里明确声明当前工作区的分支不得随意切换只允许在当前分支上提交和拉取。如果你的 agent 工具支持自定义指令一定要加这一条。4.4 Windows 环境下的路径分隔符问题如果团队里有 Windows 开发者会踩到路径分隔符的坑。Worktrunk 默认把 worktree 目录设置为主仓库同级的worktrees/目录当主仓库路径包含中文或空格时不同系统的路径拼接会有差异。我在代码里统一用pathlib处理不用字符串拼路径基本解决。但如果你用的是老版本遇到路径相关的报错先手动检查state.json里的 path 字段是否多了一个\或/。5. 进阶工作流与团队落地经验5.1 怎么规划 Agent 的工作区数量我见过很多团队一上来就开十几个 worktree结果 git 对象库虽然不大但状态管理混乱到崩溃。建议遵循一个经验法则同时进行中的 agent 任务数请控制在 3 到 5 个以内。原因不是技术限制而是人类的跟踪能力有限。超过这个数字人工审核合并时很难快速判断每个分支的代码质量反而降低整体效率。如果真的需要更多并行任务应当分阶段例如一个阶段同时推进 3 个合并完再开下一批。Worktrunk 的list输出设计成表格也是为了让状态一眼可读而不是开满一屏。5.2 通过 CI 钩子自动校验 Worktrunk 状态团队层面我给 Worktrunk 加了一个可选能力在 CI 的pre-merge阶段自动读取.worktrunk/state.json检查是否有标记为merged但 branch 仍存在的工作区。如果有CI 会打一个 warning提醒开发者执行 cleanup。这个钩子类似一个房间巡检防止状态文件与真实 git 状态长期脱节。实现也不复杂就是一个轻量的 CI 脚本在 merge 请求创建或更新时触发。这样即使开发者忘了 cleanup系统也会自动提醒。实测上线后团队里因为状态文件过期产生的排查时间大幅减少。5.3 从个人工具到团队工具的扩展如果只是个人用Worktrunk 的价值已经够明显。但当它变成一个团队的共同工具时需要约定几条规则否则状态文件会被不同人的操作搞花。推荐的做法是Worktrunk 的状态文件入库.gitignore 不忽略它这样所有团队成员共享同一个状态视图。每个人创建任务时其他人能立即在worktrunk list看到。但要注意不同人同时执行create可能会产生竞态。我在内部加了一个简单的文件锁在写 state.json 前创建一个.lock文件操作完成后释放避免两个并发命令互相覆盖。另一个建议是约定谁创建谁清理。每个工作区的清理操作尽量由创建者执行避免别人误删自己在做的内容。如果创建者休假了那就由 team lead 用worktrunk refresh核对状态后接管。5.4 后续可能的扩展方向基于现在的基础我已经在设计下一个插件接口把 agent 的类型识别解耦出去。目前内置了 codex 和 zcode 的检测逻辑但未来可能会有更多 agent CLI 工具出现比如把任务描述自动传给 deepseek CLI或者通过 MCP 把 worktree 信息暴露给 n8n 这类工作流平台。如果你也在搭类似的并行 agent 系统不妨抽时间看看项目里的agent_detector.py那部分是最好懂的扩展入口。我自己在持续试验的一个方向是把 worktree 列表同步给一个可视化面板通过 localhost 页面展示每个 agent 的实时状态。虽然 CLI 已经能满足基本需求但视觉化之后团队 review 的状态会轻松很多。6. 真实操作心得与避坑建议前面讲了不少结构和命令最后分享点实操中沉淀下来的心得。第一个心得是用 Worktrunk 之前先想清楚你的 agent 工具是否支持工作目录隔离。不同 AI agent 的上下文机制不一样有的 agent 会在启动时记录当前目录的所有文件内容如果你切换 worktree 后不重启 agent它仍然持有上一份工作区的文件索引。这会让你以为它改的是正确分支实际上它只是在旧上下文上生成代码然后写入命令指定的新目录。最稳妥的做法是每个任务一个独立 agent 进程不要跨工作区复用同一个 agent 会话。第二个心得是Worktrunk 的状态文件虽然有锁机制但并发写操作依然需要克制。早期我在一个任务里同时跑了四个 agent然后每十分钟执行一次 sync偶尔会遇上状态文件被覆盖。后来我改成每十五分钟 sync并手动确认没有另一个 worktrunk 命令在运行。普通团队的使用强度下锁机制是够用的但要避免写脚本无脑循环执行 create 和 merge。第三个心得是关于 agent 自动执行 git 操作的危险性。目前大部分 agent 工具并不会智能区分当前是在主工作区还是子工作区它们只会盲目地对我说话的那个目录操作。一旦 agent 在子工作区里执行了git merge main然后又 commit这通常没问题。但有些 agent 会顺手git push --force这就有风险了。强烈建议在 agent 的全局配置里禁用强制推送同时把 worktree 的 remote 设置为只读或者干脆不配置 remote只在合并回主干后才统一推送到远端。最后说一点点心法并行 AI agent 工作流的管理本质上是任务边界的管理。Worktrunk 解决的是渠道问题但真正决定效率高低的是你给每个 agent 划分任务时切得是否干净。如果一个任务需要 agent 同时改后端接口、前端页面、数据库脚本那无论用多少 worktree合并阶段都会异常痛苦。反过来按文件模块、按服务边界、按改动涉及面去切分任务配合 Worktrunk 的独立分支和状态跟踪你会发现多个 agent 并行不但不是灾难反而是效率提升最明显的手段。 
