多AI Agent并行改代码，用Git Worktree隔离与Worktrunk管理实现零冲突

当多个 AI Agent 同时改代码我靠这招把仓库冲突降到了零最近半年我的开发工作流基本变成了这样左边开着一个 Claude Code 处理接口重构右边一个 Codex CLI 在写测试用例偶尔中间还插一个 Agent 在跑数据分析脚本的调研。听起来很美但实际跑起来没多久就出了问题——两个 Agent 同时改同一个仓库提交变更是小事最怕的是它们各自拉到不同的分支最后合并的时候冲突多到怀疑人生。我一开始的土办法是给每个 Agent 分配一个克隆仓库各自独立干完再手动合并。但克隆几个 G 的仓库光拉依赖和构建缓存就占掉几十 G 磁盘而且两个仓库之间的代码同步也得自己手动折腾效率很低。后来我盯上了 Git Worktree研究了一段时间后又套了一层自己的命令封装把它做成了一个专门给并行的 AI Agent 服务的 CLI 工具也就是今天要说的 Worktrunk。这篇文章就围绕 Worktrunk 这个东西完整讲讲它解决什么问题、底层原理是什么、怎么用以及在实战中哪些坑绕不过去。不管你是 AI Agent 的活跃用户还是只打算在团队里引入并行 AI 编码流程这篇都能提供一份可以直接抄作业的参考。1. Worktrunk 的设计思路为什么 AI Agent 并行开发这么难1.1 Agent 并发改代码时到底在冲突什么我们把问题拆开看。现在主流的 AI Coding Agent不管是 Claude Code、Codex CLI 还是其他工具本质都是在你给的指令范围内读取仓库里的代码生成修改方案然后把变更写进文件里。一个两个没问题但只要有两个以上的 Agent 在同一时间操作同一个工作目录麻烦就来了。最典型的情况是这样的Agent A 被叫去重构src/api/client.tsAgent B 被叫去给同一批接口补测试。两个 Agent 几乎同时开始工作读到的都是原始版本代码。A 把client.ts改了B 因为读取的是旧版本生成的测试代码可能是基于旧接口写的。更麻烦的是如果它们直接往同一个分支上提交那你根本不知道哪些文件是 A 写的、哪些是 B 写的出问题了也没法回退。用分支隔离可以缓解一部分问题。但注意分支隔离不等于目录隔离。在同一个工作目录下切换分支需要把所有未提交的变更先 stash 或者 commit否则切不过去。而 AI Agent 的工作过程里会产生大量中间过程文件你不可能让两个 Agent 在同一个目录里频繁提交、stash、切换分支那样它们会互相打断甚至导致上下文丢失。我测试过让两个 Agent 在同一目录不同分支上交替工作结果它们都在各自的思考过程里引用当前的代码状态一旦切换分支文件内容和 Agent 记忆中的内容对不上后续的修改就开始变得不靠谱。这是并行 Agent 工作流里最核心的冲突点——上下文冲突。1.2 为什么 Git Worktree 是天然解药Git Worktree 是 Git 从 2.5 开始提供的功能它的设计目标就是一个仓库多个工作目录。每个 Worktree 对应一个分支互不影响。你在/path/to/repo保持主分支的代码同时可以创建/path/to/repo-wt-agent-a作为另一个分支的工作目录。同一个仓库的不同 Worktree 之间是共享 Git 对象库的也就是说只需要维护一份.git对象数据库不需要复制整个仓库的代码。创建 Worktree 是秒级操作因为 Git 只需要 checkout 出对应分支的文件即可本质是对文件系统的一次硬链接或者软链接索引实际是 checkout 文件内容到工作区不需要把仓库历史拷一份。对 AI Agent 并行工作流来说Worktree 的价值在于每个 Agent 拥有一个完全独立的工作目录但它又和其他 Agent 共享同一个 Git 对象库与提交历史。这样每个 Agent 看到的都是完整的最新提交状态比如统一的main分支基线并且各自往自己的分支上开发。最后要做整合时只要在操作系统层面把几个 Worktree 的分支合并回主分支即可。我用了一段时间原生 Git Worktree 之后发现它其实已经能解决 90% 的隔离问题。但剩下的 10% 很恼人——原生命令太碎了每次创建一个 Agent 工作区要敲git worktree add -b feat/xxx /path/to/repo-wt main跑完一个 Agent 要git worktree remove这些命令一旦要维护四五个并行 Agent就得写一堆脚本去管理目录名、分支名很容易乱。所以我才有了做 Worktrunk 的想法。1.3 Worktrunk 的定位与整体思路Worktrunk 从定位上说是针对 AI Agent 并行开发场景的 Worktree 管理封装层。它不是一个代码编辑器也不是 Agent 本身而是架在 Git 和 Agent 中间的一层命令行工具负责回答这几个问题当前仓库有哪些 Agent 的工作区某个工作区对应哪个分支、状态如何怎么快速新建一个基线干净的工作区给一个新的 AgentAgent 完成后怎么把工作区的成果安全合并回主干不需要的工作区怎么一键清理我的核心设计原则是每个 Agent 的生命周期 一个 Worktrunk Workspace 的生命周期。一条命令初始化工作区Agent 在里面随便折腾结束后一条命令合并回主干并清理。Worktrunk 管理的就是创建 - 使用 - 合并 - 删除这四段每个阶段都提供对应的 CLI 命令。相比直接写 Shell 脚本CLI 工具的好处是它能把项目的状态记录在一个配置文件里下次启动时能知道你曾经创建过哪些 Agent 工作区、每个工作区对应哪个分支、关联哪些任务。脚本做这种事往往要解析文本输出来维持状态维护成本很高。2. Worktrunk 的核心实现一条命令解决 Agent 工作区全生命周期2.1 安装与环境依赖Worktrunk 本身是 Node.js 写的依赖 Node.js 18 及以上版本和 Git 2.30 以上版本主要用到了git worktree prune等命令的更稳定行为。安装方式直接走 npm 安装npm install -g worktrunk/cli装完之后验证一下版本worktrunk --version如果是在团队里使用我更建议用 corepack 锁定 Node 版本或者在 CI 环境中用npx worktrunk/cli直接调用避免全局安装污染环境。提示主流的 AI Coding Agent 工具Claude Code、Codex CLI、ZCode 等本质上都是 CLI 程序。Worktrunk 与它们是平级的关系它不依赖任何特定 Agent 的 API只负责 Git 工作区的编排。所以无论你最终用哪个 Agent 工具都可以套上 Worktrunk 来管理并行工作流。2.2 首次初始化worktrunk init在仓库根目录执行worktrunk init这个命令会做三件事检查当前目录是否是一个合法的 Git 仓库。创建.worktrunk/config.json配置文件里面记录默认的基准分支默认是main或master自动识别。在.gitignore中追加/.worktrunk/和仓库的.worktrunk/路径如果没被忽略的话避免本地的 Agent 状态配置被误提交。配置文件的内容类似这样{ version: 1, baseBranch: main, workspaces: {}, defaults: { deleteOnMerge: true, mergeStrategy: merge } }这个文件就是 Worktrunk 管理所有 Agent 工作区的账本。后续创建的每个 Agent 工作区都会在这里登记包含工作区名称、分支名、基准提交 hash、创建时间、agent 命令等。我在设计它与原生 Git Worktree 最核心的差别就在这个账本上。原生 Git Worktree 的信息分散在.git/worktrees/目录里但每次都要先跑git worktree list才能看到。Worktrunk 把这个工作区是谁建的、跑什么指令、什么时候要清掉这种人类可读的信息直接落盘这才是对 Agent 工作流友好的状态管理模式。2.3 创建 Agent 工作区worktrunk agent new这是整个工具中最核心的一个命令。当我要新开一个 Agent 来干一件独立任务时执行worktrunk agent new api-refactor --base main执行后Worktrunk 会在main分支最新提交处创建一个新分支分支名默认是agent/api-refactor。新建/path/to/repo-worktrees/api-refactor目录把远程或本地的最新 main 代码 checkout 出来。更新.worktrunk/config.json把这个工作区的信息登记进去。打印出下一步可以直接使用的命令提示。--base参数可以选择任意的分支或提交 hash。比如你希望 Agent 在上一次 Agent 的工作成果之上继续开发就可以用worktrunk agent new db-migration --base agent/previous-work它内部实际做的事情其实是对git worktree add的包装。所以初始化一个工作区的速度非常快几 GB 的大仓库也基本是秒级。工作区目录结构方面我比较推荐统一放到仓库根目录下不远的路径比如/workspace/my-project/ # 主工作区main /workspace/my-project-worktrees/refactor # Agent A 的工作区agent/refactor /workspace/my-project-worktrees/testcase # Agent B 的工作区agent/testcase所有 Agent 工作区集中放在一个文件夹里和主仓库目录分离。这样主目录依然保持整洁而_worktrees目录可以用一套脚本统一清理或归档。2.4 查看与管理工作区worktrunk list / worktrunk status创建了几个 Agent 工作区后用worktrunk list可以看到类似下面的输出┌──────────────┬─────────────────────┬───────────┬────────────┬───────────┐ │ Workspace │ Branch │ Base │ Status │ Age │ ├──────────────┼─────────────────────┼───────────┼────────────┼───────────┤ │ api-refactor │ agent/api-refactor │ main │ clean │ 2h ago │ │ testcase │ agent/testcase │ main │ dirty │ 15m ago │ └──────────────┴─────────────────────┴───────────┴────────────┴───────────┘这个命令的信息量很关键Status 为dirty表示工作区里有未提交或未处理的变更clean 表示干净。这对维护大量 Agent 任务非常重要你可以一目了然地看出哪些 Agent 还在活跃产出哪些已经处于停滞状态。worktrunk status workspace可以查看单个工作区的更详细信息包括最后提交时间、当前 HEAD 与 base 分支相差几个提交、是否有未跟踪文件等。这些信息在决定要不要把这个 Agent 的成果合并回来时很有用。我用过很多次这类检查最终发现一个经验真正需要合并的 Agent 工作区往往在 Status 列表里的状态是 clean也就是说 Agent 自己完成了提交把代码整理干净了。如果状态显示 dirty 且改动特别大那这个 Agent 大概率是中途写崩了合并前你需要仔细 review。2.5 Agent 的运行时窗口当 Agent 工作区创建好之后你需要告诉你的 AI Agent 工具让它在那个目录中工作。例如我用 Claude Code 时进入对应的工作区目录以后再启动cd /path/to/repo-worktrees/refactor claude或者用 Codex CLIcd /path/to/repo-worktrees/testcase codex这里有件很重要的事Agent 的工作目录必须是 Worktrunk 创建的 Worktree 目录而不是主仓库目录。必须让 Agent 在它自己的分支工作区里写代码、创建文件、跑测试。这是整个隔离思路生效的前提。每个 Agent 会在这个隔离的工作区里自由地提交。这个阶段我通常不干预除非发现 Agent 跑偏了——出现不相关文件的大量创建、或者修改了不该动的基础配置——否则不做任何手动修改。2.6 合并 Agent 成果worktrunk agent merge当 Agent A 的工作已经完成并且你在工作区里完成 code review 后执行worktrunk agent merge refactor这个命令会自动做以下步骤检查 refactor 工作区当前的分支状态。确保目标 base 分支默认 main本地是最新的。执行git merge --no-ff agent/refactor把该分支合并回 main。如果合并过程中出现冲突命令会停下来提示你手动处理而不是强制继续。合并成功后根据配置决定是否自动删除这个 Worktree。这里的--no-ff是我个人强制指定的策略。即使用merge可以直接 fast-forward因为从 main 创建 agent 分支后main 可能没有新提交我也希望保留 Agent 工作分支的存在感。这样以后看 Git 历史时一眼就能看出这段代码是由哪个 Agent 任务开发的。如果你的团队更偏好线性历史可以在配置文件里把mergeStrategy改成rebaseworktrunk config set mergeStrategy rebase此时worktrunk agent merge会先执行git rebase再执行git merge --ff-only。两种策略各有利弊这个后面在合并冲突处理章节再展开。2.7 清理工作区worktrunk agent cleanAgent 的任务合并完成后它的 Worktree 就没用了。直接跑worktrunk agent clean refactor执行过程会先把当前分支 merge 回 main如果你没先 merge然后删除对应的工作区目录、删除分支agent/refactor最后更新.worktrunk/config.json。清理是很容易被忽略的一步。如果不清理长期下来工作区目录会越来越多每一个都占用磁盘空间每个 worktree 的检出文件是有体积的但不包括对象库。更重要的是多余的工作区会让worktrunk list变得混乱影响后续的 Agent 调度决策。2.8 并行 Agent 工作流的完整实战操作上面每条命令单独看都不难但组合起来才是一个完整的并行工作流。我实际在项目中跑多 Agent 协作时大概的流程是这样的场景主仓库main分支上有一个老旧的电商系统最近要做三件事重构商品查询接口、为订单模块补单元测试、设计一个全新的促销引擎。我先后执行worktrunk agent new item-query-refactor --base main worktrunk agent new order-test-suite --base main worktrunk agent new promo-engine --base main三个 Agent 工作区瞬间创建完成。接着给每个工作区指定不同的 Agent 工具在item-query-refactor里启动 Claude Code指令是重构商品查询接口优化数据库查询逻辑保持接口兼容性。在order-test-suite里启动 Codex CLI指令是为 order 模块的 service 层和 controller 后补单元测试使用 vitest。在promo-engine里启动另一个 Claude Code 实例指令是设计并实现一个促销引擎先给出设计方案文档。三个 Agent 互不干扰地工作各改各的文件各提交各的 commit。我在主仓库目录下继续做其他工作读代码、写文档、review merge request。等第一个 Agent 完成后我进工作区 review 变更然后 merge 回 main。第二个、第三个 Agent 完成后也各自 review、merge。整个过程最爽的一点是没有任何一个 Agent 需要等待其他 Agent 的 IO 操作释放锁也没有任何一个 Agent 会因为目录里的意外变更而失去上下文。如果中途某个 Agent 跑偏了频繁出现我可以直接worktrunk agent clean把它删除再用worktrunk agent new重新建一个干净的工作区之前错误的提交不会污染主分支。3. 高级用法把 Agent 输出限定在可控范围内3.1 用 hooks 在创建和合并时自动做检查Worktrunk 支持在.worktrunk/config.json里配置hooks在关键节点自动触发外部脚本。我自己最常配的是合并前检查和创建后初始化{ hooks: { afterAgentCreate: [bash scripts/setup-agent-env.sh], beforeAgentMerge: [bash scripts/check-lint-and-tests.sh, bash scripts/validate-build.sh] } }afterAgentCreate会在worktrunk agent new之后自动执行脚本。我给每个新工作区设置了一个专用的.env.local文件这样 Agent 在链接数据库或调用外部 API 时用的配置就和其他工作区隔离不会污染主环境。beforeAgentMerge更关键。Agent 写完代码后代码是否能通过 lint、能否通过单测这是合并前的硬门槛。我写了一个脚本里面依次执行npm run lint、npm run test、npm run build。只有全部通过才允许合并。如果其中任何一步失败合并流程会在入口处直接中断并提示你回工作区修复后再试。这个设计其实借鉴了 CI/CD 的思路。传统 CI 是在 push 之后跑检查但只要 Agent 在本地合并回 main就必须在本地做一次冒烟验证——否则带病代码一多CI 红灯就成家常便饭了。3.2 与 MCP、Agent Skill 结合的工作区状态注入2025 年的 AI Agent 生态有一个很明显的趋势就是 Agent 开始有外挂记忆和外挂工具典型的就是 MCPModel Context Protocol和各种 Skill 包。Agent 不再只是简单读文件、改文件而是能通过 MCP 连接外部 API、数据库、任务管理工具。Worktrunk 在这种场景下也有用武之地。我在设计配置文件时预留了一个context字段{ workspaces: { refactor: { branch: agent/refactor, path: /workspace/my-project-worktrees/refactor, taskDescription: 重构商品查询接口优化查询性能, relatedSkill: typescript-refactor-skill } } }这样的信息对 Agent 工作区的可追溯性很重要。当并行跑 5 个 Agent 时如果你不记录这个工作区到底在干什么过两天再看worktrunk list你很难凭一个分支名想起当时的上下文。加上taskDescription和relatedSkill之后状态管理的成本显著下降。我见过有人把这段 JSON 作为 prompt 上下文注入给新的 Agent。在 Agent 启动时先读 Worktrunk 的配置了解当前已有哪些 Agent 在工作、各自任务是什么然后在此基础上规划自己的改动范围。这相当于让 Agent 具备了一点项目级态势感知而不是孤立地闷头改文件。这种组合虽然不是 Worktrunk 默认提供的功能但基于配置文件的开放性实现起来非常轻松。3.3 多仓库场景worktrunk repo 嵌套管理一个项目经常有多个代码仓库尤其微服务架构下一个仓库就是一个服务。如果每个仓库都装一套 Worktrunk操作起来会分散。我从 v0.3 开始支持一种轻量叠加的模式。可以在项目根目录下建立多个子仓库每个子仓库有自己的.worktrunk/config.json也可以用一个总入口脚本对多个仓库批量执行 Worktrunk 命令worktrunk repo sync --all这个实际是对每个子仓库执行git fetch、git status等命令然后汇总输出。它本身不接管仓库内的 Agent 工作区创建但是配合worktrunk list可以让全仓库的Agent状态一目了然。我一般只在很小的团队里用这个功能因为跨多个服务协同并行 Agent 的开发模式目前还处于偏个人工作流的阶段团队协作的成熟度还需要时间验证。4. 避坑指南Worktrunk 实战中不可不知的细节4.1 哪些人适合 / 不适合 Worktrunk先说结论Worktrunk 最适合只用单个 AI Agent 工具做独立任务、但希望同时跑多个任务的人。如果你所在团队已经有成熟的 Git Flow 和代码评审流程那也可以把 Worktrunk 作为本地开发环境的前置工具它不替代 CI也不替代 PR/MR 流程。不适合的情况也很明确如果你的 Agent 只在主分支上做增量小改动且任务之间没有隔离需要那 Worktrunk 反而增加了一层要管理的状态。如果你的项目经常需要跨分支共享未提交的改动Worktree 这种隔离模型反而会碍事。如果你用的 Agent 工具没法设置工作目录比如某些 IDE 插件固定打开主仓库路径Worktrunk 就派不上用场。我这段时间的经验是AI Agent 并行开发真正适合的是任务边界清晰、代码关联度低、需要独立产出的工作。像给 A 模块写测试和重构 B 模块的接口这种任务边界非常清楚并行起来收益极大。但如果两个 Agent 的任务都集中在同一个核心文件上那即使有 Worktrunk 的隔离合并阶段仍然会冲突这种任务建议还是老老实实排队做。4.2 合并冲突是躲不开的关键是把它控制在小范围虽然 Worktrunk 做了目录隔离但分支最终要合并回 main冲突依然可能发生。两个 Agent 同时改了同一个配置文件比如package.json、tsconfig.json或者一个改了某个模块的公共类型定义另一个实现了相关功能——这些都是冲突高发区。我的经验是处理冲突要趁早不趁晚。一旦worktrunk agent merge提示冲突我不会立刻手动改冲突标记而是先看冲突的文件属于哪个领域然后决定是直接手动解决还是把冲突描述喂给对应的 Agent 让它自己修复。后者听起来很酷但实际效果取决于 Agent 对冲突上下文的理解程度。大部分情况下让 Agent 去解决另一个 Agent 生成的冲突代码效果不太理想因为它的上下文里没有对方的设计意图。所以冲突代码我基本都是自己手动改或者重新打开那个工作区让后续任务基于新的 main 分支再去改一遍。另一个减少冲突的手段是让所有 Agent 都以统一的 base 分支起步。即使创建时间不同也不要让中间某个 Agent 的合并结果立即成为另一个 Agent 的 base除非明确需要依赖它。保持 base 分支只有 main会让每个 Agent 的合并路径更短冲突概率更低。4.3 磁盘占用与性能影响原生 Git Worktree 共享对象库这一点很多人以为不会额外占太多磁盘但实际上每个 Worktree 的工作区文件checkout 出来的源码、依赖目录、build 产物都是完整的。一个仓库源码 200MB装好依赖后 1GB10 个 Worktree 就是 10GB。所以 Worktrunk 创建的工作区默认会加入一层依赖目录映射的优化思路对 Node.js 项目我建议给每个 Worktree 设置NODE_MODULES_SYMLINK指向主仓库的 node_modules这样依赖不重复下载。但要注意这会让不同分支共享 node_modules如果你在 A 分支装了新的依赖包B 分支的 Agent 立刻也能用可能导致 B 分支的锁文件没有同步更新。所以生产环境不建议用 symlink 共享依赖开发环境可以用。对 Rust 项目cargo 的 target 目录很大但通常可以设置一个共享的 sccache或者在 Worktree 里只保留增量编译缓存。实测下来每次 Agent 的改动范围通常很小target 目录的重复编译浪费其实没那么严重。性能方面影响最大的是 Worktree 数量很多时的git status和git log操作。如果你开了十几个工作区每个工作区都要跑一次git fetch网络 IO 确实会带来压力。但单纯本地看文件、改代码Worktree 的性能和普通工作目录没有任何区别。我这边的惯例是同时活跃的 Agent 工作区尽量控制在 5 个以内超过 5 个的任务队列会明显变慢倒不是工具的问题而是作为人类的我根本 review 不过来。4.4 Worktrunk 与 IDE 的集成问题不少写在前面的坑都是来自 IDE 和 Worktree 的兼容性。比如 VS Code 打开一个普通目录没问题但打开一个 Worktree 目录时有些插件会试图从 git 配置里找主仓库结果路径解析失败。我实际测试过的情况VS Code 直接code /path/to/repo-worktrees/refactor打开 Worktree 目录正常工作Git 插件也能识别所在分支。WebStorm 对嵌套 Git 仓库的识别略复杂但 Worktree 作为一个独立的项目目录打开时基本没问题。如果 IDE 一直把这个 Worktree 目录识别为零散的未纳入版本控制的文件多半是.git文件不是目录没有被 IDE 正确读取。由于 Worktree 的 git 元数据是一个.git文本文件指向主仓库的worktrees/xxx目录部分 IDE 插件对这种外部 worktree的兼容性不够好。解决办法是给 IDE 设置里指明打开独立目录作为项目根目录。另外有一个我不太推荐的做法把主仓库目录和 Worktree 目录放在同一个 window 下的 multi-root workspace 里。因为两个目录本身的 git 状态不同IDE 的全局搜索和重构功能会把它们混着处理导致文件路径混乱Agent 也会因为 IDE 的额外文件索引而产生上下文污染。4.5 跨平台使用时的路径大小写和换行符如果团队里有 macOS、Windows、Linux 三种环境并行Worktree 的路径管理就有讲究了。Git 本身支持 Windows 的大小写不敏感文件系统但 Worktree 创建时的目录名如果和已有目录名只有大小写差异在 Windows 上会变得不可预测。我在 Worktrunk 里做了一层校验创建 Worktree 时会判断目录名是否与已存在目录冲突并在 Windows 上自动转为小写。换行符是另一个坑。不同 Agent 生成代码时可能在 Windows 上产生 CRLF在 macOS/Linux 上产生 LF。如果多个 Agent 的工作区换行符不一致合并时 Git 有时会产生大量整文件冲突。我强烈建议在仓库根目录提交一个统一的.gitattributes文件明确文本文件的换行符规范通常是text eollf。这样不管是哪个平台的 Agent 生成的文件提交进 Git 时都会被统一成 LF冲突会显著减少。4.6 一个容易忽视的问题Agent 生成的大量临时文件AI Agent 在实际执行任务时会产生相当多中间产物。比如 Claude Code 在分析项目时生成的.claude/目录Codex CLI 在调试时生成的临时脚本和日志。这些文件如果在 Worktree 里被大量生成会因为未提交或未跟踪文件而让worktrunk status显示为 dirty。处理方式有两个在仓库根目录的.gitignore里统一忽略 Agent 工具的目录.claude/、.codex/等。这是最干净的方案。如果某个工作区不想改全局 gitignore可以单独在这个 Worktree 里配置.git/info/exclude。不要忽视这些临时文件因为它们会直接影响 Agent 下次启动时的上下文。如果 Agent 重新扫描目录时发现上万个自己不认识的临时文件它的思考过程会被污染出现莫名其妙的这个项目太乱的判断。4.7 Worktrunk 在 CI 环境中使用时的注意事项Worktrunk 不只适用于本地开发。我在 CI 里也跑过主要用于生成多个并行验证任务的工作区。典型场景是两个 Agent 基于同一提交分别做前端代码检查和后端单元测试CI 里并行跑两个 job每个 job 构建各自的工作区。CI 里用 Worktrunk 要注意的是不要用 root 用户运行 Git 相关命令在部分容器镜像里会有问题以及保证环境变量里没有残留的 GIT_DIR 或 GIT_WORK_TREE。这两个环境变量如果被设置了会让 Worktree 的解析直接错乱。还有一个点CI 里一般建议用worktrunk agent new创建的空工作区直接执行命令而不是跑完整的 merge 流程。因为 merge 的 review 环节在 CI 里不好做合并操作保留在本地开发环节更合理。5. 常见问题排查与实用速查表5.1 命令执行后工作区没有出现如果你执行完worktrunk agent new xxx后发现工作区目录不存在首先检查.worktrunk/config.json里的workspaces字段有没有记录。如果有记录但目录不存在多半是创建时被防病毒软件或文件系统权限拦了。遇到这种情况手动创建下目录再执行worktrunk agent repair xxxrepair命令会根据配置里登记的信息重新 checkout 工作区。我大概遇到过一次原因是在某个云同步盘里创建 Worktree同步进程锁了目录导致后续 checkout 失败。最终我把 Worktree 路径从云同步盘移到了本地磁盘问题再没出现过。5.2 合并时提示工作区有未提交的更改Agent 还在工作或中途异常退出时工作区会残留未提交的文件。执行 merge 前先查看状态worktrunk status refactor确认是哪些文件未提交进入对应工作区查看这些文件是否必要必要的话就先提交再回到主仓库执行 merge。不必要的话直接丢弃再 merge。犹豫不决的话可以先在refactor分支上建一个 WIP 分支保存现场再回到 main 执行合并这样不至于把未提交的代码带入合并结果。5.3 多个 Agent 用了同一个分支名我自己踩过的比较尴尬的一个坑两个不同的任务同时被分配到了同一个分支名agent/refactor原因是工作区命名规则里按任务类型自动生成了分支名而两个任务类型撞了。Worktrunk 默认在创建时会检查分支名冲突。如果分支名已存在它会自动追加时间戳或随机后缀。我建议所有 Agent 工作区分支名的第一个前缀是 Agent 工作区名而不是任务类型。也就是说agent/refactor这种通用命名最好改成agent/refactor-20250618或者干脆用内部代号。分支名一旦在创建后就不要改改分支名意味着工作区也要跟着挪麻烦又易错。5.4 切换 Agent 工具时 Worktree 不生效有时候你先把某个目录当作普通 Git 克隆来用后来想把它并入 Worktrunk 管理。这种情况下直接用worktrunk init可以把它变成 Worktrunk 仓库但如果这个目录本身是一个非 Worktree的普通仓库Worktrunk 会建议你把它重新 clone 一遍而不是在同一目录里既保留普通仓库结构又叠加 Worktree。原因很简单一个目录要么是一个 Git 工作树要么不是一个 Git 工作树两者不会共存。我的建议是最开始就做好规划主仓库目录用git clone创建其余任务分支都用worktrunk agent new创建。不要在中间把一个普通 Working Directory 硬塞进 Worktrunk 的管理里。5.5 常见命令速查表场景命令初始化 Worktrunk 管理worktrunk init查看所有 Agent 工作区worktrunk list查看单个工作区详情worktrunk status workspace新建 Agent 工作区基于 mainworktrunk agent new workspace --base main新建 Agent 工作区基于指定分支worktrunk agent new workspace --base branch进入 Agent 工作区cd /path/to/repo-worktrees/workspace合并并删除工作区worktrunk agent merge workspace仅合并不删除工作区worktrunk agent merge workspace --keep删除工作区不合并worktrunk agent clean workspace修复工作区worktrunk agent repair workspace设置合并策略worktrunk config set mergeStrategy merge / rebase6. 下一步扩展从个人效率工具到团队协作平台Worktrunk 目前对我来说最实用的还是个人工作流。一个人开多个 Agent 干活每个 Agent 一个工作区互不干扰。我也见过有人把 Worktrunk 扩展到团队里使用做法是让每个开发者在本地维护自己的 Worktrunk然后用worktrunk export导出一个 json 文件方便 code review 时把一个 Agent 工作区的所有上下文分支、任务说明、变更文件列表一起贴到 PR 描述里。这个思路其实可以被进一步拉深。如果把 Worktrunk 的配置和 CI 的 pipeline 做联动每次worktrunk agent merge时自动触发对应 Agent 工作区的回归测试然后基于测试结果决定是否允许合并那这条链路就完整了。还有一个小众但很有意思的方向把 Worktrunk 与知识库工具结合。每个 Agent 工作区的taskDescription和最终合并的 commit message其实就是一个AI 做过什么的项目日志。长期积累下来你可以用它来回答上个月让 AI 做过哪些任务各个 Agent 的产出质量如何哪些任务类型适合让 Agent 去做 这算是 AI 工程化里很少被人提到的AI 工作流可观测性问题。Worktrunk 现在做的事只是把原始数据记录下来后续怎么挖掘价值我还在摸索中。对我个人来说这套 CLI 工具的价值不在于某一条命令有多花哨而在于它让并行 AI Agent这件事从一个听起来很酷的概念变成了一个我每天都能稳定复现、稳定交付的开发流程。如果你也在被几个 Agent 抢同一个仓库这件事折磨着我建议你先手动试一下原生git worktree add感受一下隔离带来的清爽感然后就可以上手 Worktrunk 把管理成本进一步降下来。最后再分享一个小技巧当你要开多个 Agent 并行任务时别一次性把它们全部启动而是留一个 Agent 专门负责清理与合并辅助——它不需要写代码只负责跑worktrunk list、检查冲突、执行 merge。这样你的主脑也就是你自己只需要做最终代码审核其他的调度脏活让 Agent 去干它不香吗。