先说说我为什么折腾 Worktrunk 这个东西。最近我的工作节奏基本都是人带多个 AI Agent并行干活一边让 Codex CLI 改后端搜索接口一边让 Claude Code 写前端筛选组件自己还得给下一轮任务写 prompt。最开始我图省事所有 Agent 共用一条分支来回 git checkout结果被现实狠狠教育了几次Agent A 的测试还没跑完Agent B 一切换分支A 的运行环境就全乱了Agent A 改了一半的文件又被 Agent B 的提交动作顺手带走两个 Agent 同时写同一个 lock 文件的时候现场更是直接失控。后来我才想明白问题的根源不在 Agent而在于一个仓库默认只能有一个工作目录这个约束。Git Worktree 能一次挂出多个独立工作区而且互不干扰但它原生命令的信息密度太低同时管理多个 Agent 会话时很麻烦。于是我自己封装了 Worktrunk 这个 CLI围绕 Git Worktree 提供一套面向并行 AI Agent 工作流的命令层。这篇文章会从设计思路、核心命令、多 Agent 实操到常见问题排查完整讲一遍。1. 为什么并行 AI Agent 工作流离不开 Git Worktree1.1 单分支串行模式的三宗罪大部分人的 Git 使用习惯是一条分支打天下新任务来了拉一下最新代码改完提交再切换。这个习惯在单人单线程开发里没毛病但一旦你让多个 AI Agent 并行介入问题就全冒出来了。第一宗罪是进程环境互相污染。Agent 在终端里持续运行它会读取当前目录的文件、执行测试、启动开发服务器。你这边 Agent B 一旦 git checkout 切分支工作目录里的文件被整体替换Agent A 正在读取的源码可能瞬间变了进程甚至会直接崩掉。第二宗罪是未提交改动混流。AI Agent 经常会边思考边写文件改动散落在工作目录各处。Agent B 一条 git pull --rebase 或者 git stash就可能把 Agent A 还没写完的代码一起卷走。第三宗罪是提交边界模糊。多个 Agent 的改动挤在同一个 Index 里合的时候根本分不清哪一段是谁干的代码 review 变成猜谜。这三宗罪本质上都指向同一个约束一个仓库同一时间只能有一个工作目录。想要并行就必须把工作区这个维度拆开。1.2 Git Worktree 到底做了什么Git Worktree 不是什么新功能它从 Git 2.5 开始就是官方能力。一句话解释同一个仓库的 .git 元数据可以对应多个独立的工作目录每个工作目录叫一个 worktree拥有自己的 HEAD 和 Index可以各自检出一条不同的分支。用生活化的例子说就好比你只有一个文件柜仓库的 .git 对象库但办公桌上可以摆好几个摊子工作目录每个摊子摊开不同的任务材料分支改完自己那份再统一归档。摊子和摊子之间只要没刻意去动别人那堆材料基本不会打架。原生命令也很简单git worktree add ../feat-search -b feat-search git worktree list git worktree remove ../feat-search但原生命令有两个问题。第一它不带太多上下文信息你要自己记住某个 worktree 对应哪个分支、哪个 Agent 任务、上次提交是什么。第二它对创建后的环境配置没有帮助比如 .env 复制、node_modules 共享、Agent 会话目录绑定这些都得你手动做。Worktrunk 就是把这些手工活收编成一条命令。1.3 对 AI Agent 工作流的三个关键价值我用了段时间之后发现 Worktrunk 对 AI Agent 工作流有三层价值缺一不可。第一层是进程级隔离。每个 Agent 的工作目录完全独立cwd 不一样运行中的测试服务器互不影响A 改代码不会惊动 B。第二层是变更边界清晰。一个 worktree 对应一个分支Agent 的所有改动天然归属那条分支合并的时候按 worktree 粒度和分支粒度 review谁干了什么一目了然。第三层是快速回收。任务验收完直接合并分支、销毁 worktree主目录保持干净不用等某个 Agent 慢悠悠地把环境恢复原样。顺便回答一个经常被问的问题Agent、LLM、AI 模型到底是什么关系。DeepSeek 这类产品里包含的是大语言模型属于大脑Codex CLI、Claude Code 这类是手脚负责调模型、读写文件、执行命令而 Worktrunk 管的是这些手脚各自工作的那张桌子。三者的层级完全不同可以组合使用。2. Worktrunk 的设计思路命令层应该怎么长2.1 原则约定优于配置给 AI Agent 用的小工具最大的敌人是配置文件地狱。如果每建一个工作区都要先写一段 YAML、定义一堆字段Agent 理解不了你自己也烦。所以 Worktrunk 的核心原则是约定优于配置工作区目录名等于分支名等于 Agent 会话名三者严格一一对应不引入额外的映射层。比如你创建一个名为 backend-search 的工作区它默认会在仓库下创建 .work/agents/backend-search 目录并自动创建同名分支 backend-search。你不需要记住目录叫什么、分支叫什么这种对应关系因为答案永远一样。状态数据全部存在仓库根目录的 .worktrunk/state.json 里纯文本、可 diff、可放进 .gitignore甚至可以直接扔给 Agent 让它自己读。2.2 命令设计总览Worktrunk 的命令刻意做得很少每个命令只做一件事而且动词全是开发者的直觉命令作用底层行为wr create name创建 Agent 工作区执行 git worktree add 并配置环境文件wr list列出所有工作区读取 worktree 和 last commit 信息wr use name切换到某个工作区输出并记录当前 Agent 工作目录wr exec name -- cmd在指定工作区执行命令设置 AGENT_WORKTREE_DIR 后运行wr sync同步工作区改动自动加暂存、提交到对应分支wr commit提交当前工作区生成规范信息并保留 Agent 上下文wr destroy name销毁工作区git worktree remove 并清理状态命令行的哲学是一次只解决一个问题。wr create 只负责把工作区建好wr sync 只负责把 Agent 的结果落到分支上wr destroy 只负责清理。这样无论你是在终端手动操作还是让 Agent 通过脚本调用行为都可预期。2.3 与主流 Agent 工具的接入方式日常工作中我用得比较多的是 Codex CLI、Claude Code以及基于 DeepSeek 模型自建的一些 harness 流程Worktrunk 对它们都保持不侵入原则。侵入是什么意思就是承诺自动帮你改 Agent 配置文件、自动注入 MCP server这些我一律不做。接入只有两个方式足够用了。一是环境变量每个 Agent 会话都会拿到 WORKTREE_NAME 和 AGENT_WORKTREE_DIR脚本和 prompt 里可以直接引用。二是命令包装想在一个指定工作区里启动 Agent直接执行 wr exec backend-search -- codex 或者 wr exec filter-component -- claudeWorktrunk 自动切好目录、配好环境变量再把命令跑起来。对 skill、memory、MCP 这类 Agent 扩展组件我的建议是把 Worktrunk 相关的操作封装成一个 skill让 Agent 在开工前先调用 wr list 看现场、开工后用 wr sync 交作业。这样 Agent 的动作记忆就有了固定的走廊而不是每次胡写一通 Git 命令。3. 核心功能与实操要点3.1 创建 Agent 工作区wr create创建是整个流程的第一步也是最值得抠细节的一步。假设我要让一个 Agent 去重构搜索接口命令长这样wr create backend-search --base main --copy .env --link node_modules这条命令做了四件事基于 main 分支创建新分支 backend-search用 git worktree add 挂出独立工作区把根目录的 .env 复制进新工作区把 node_modules 以符号链接方式共享给新工作区。--copy .env 很关键。很多 Agent 跑起来第一件事就是读环境变量你不给它 .env它容易自己脑补一个或者直接报错。--link node_modules 是用来防止磁盘爆炸的后文排查部分我会重点说。这个参数我实际用下来是真的能省掉好几个 G 的重复安装。3.2 查看与切换wr list / wr use工作区一多人脑就记不住状态了。wr list 的输出会把每个工作区的分支、最近提交、负责人、状态一眼列出来NAME STATUS BRANCH LAST COMMIT backend-search active backend-search 12s ago filter-component idle filter-component 3m ago test-coverage idle test-coverage 1h ago这里的 active 表示有 Agent 正在里面跑idle 表示建好了但还没动静。wr use backend-search 则是把当前终端的上下文切到对应目录同时更新 state.json 里的 current 字段。很多 Agent 启动时会自动记录 cwd配合 wr use 之后目录天然正确再也不会出现在仓库根目录空跑半天的情况。3.3 收尾与清理wr sync / wr commit / wr destroyAgent 干完活之后常见的尴尬是它改了一堆文件但不知道该怎么提交或者提交信息写成一坨。Worktrunk 的 wr sync 会自动识别工作区里的变更执行 git add -A然后以 [worktree-name] 为前缀生成提交信息把描述放在第二行。如果你自己写了一段 review 总结还想手工提交就单独跑 wr commit它只会帮你把状态记录好不会动你的提交信息。工作区没有利用价值之后wr destroy backend-search 会删除目录和分支同时清理 state.json 里的记录。这个命令我特意做了保护默认只允许删除已经合并进主分支的工作区避免误删 Agent 还没交账的成果。想强删必须加 --force。提示wr destroy 的 --force 请慎用。Git worktree remove 会拒绝删除存在未提交改动的工作区--force 等于跳过校验。建议执行前先 wr list 确认状态再决定要不要删。4. 三 Agent 并行的完整实操案例4.1 场景设定与本仓库准备为了把整个流程讲明白我拿一个具体的例子走一遍。假设我手上有这么一个仓库后端是 FastAPI前端是 Vue测试用 pytest代码都躺在 main 分支上。我现在有三个任务要并行推进Agent 1 给搜索接口加分页Agent 2 做前端筛选组件Agent 3 补测试用例。首先把仓库克隆下来然后依次创建三个工作区git clone gitgithub.com:example/myapp.git cd myapp wr create agent/search-pagination --base main --copy .env --link node_modules wr create agent/filter-component --base main --link node_modules wr create agent/test-coverage --base main wr list创建 test-coverage 时我故意没有 --copy .env因为补测试用例的 Agent 往往只需要读代码不需要完整的运行环境。少复制一个文件就少一份环境维护成本。4.2 分别启动 Agent绑定环境变量创建完工作区之后我会开三个终端窗口或者用 tmux 起三个 pane分别在对应目录下启动 Agentcd .work/agents/agent/search-pagination codex另一种更推荐的方式是让 Worktrunk 直接包装wr exec agent/search-pagination -- codex wr exec agent/filter-component -- claude这样所有 Agent 进程自然继承 AGENT_WORKTREE_DIR 环境变量它们的所有文件操作都会落在自己的工作目录下面。实测下来三个 Agent 同时跑互不干扰。最直观的感觉是再也不会出现 A Agent 跑着跑着工作目录里的文件被 B Agent 的操作替换掉以前那种改完代码后测试结果完全对不上的情况直接消失了。4.3 验收、合并与清理三个 Agent 完成各自任务后我按下面顺序收尾wr sync git checkout main git merge agent/search-pagination --no-ff -m feat: search pagination git merge agent/filter-component --no-ff -m feat: filter component git merge agent/test-coverage --no-ff -m test: coverage cases wr destroy agent/search-pagination wr destroy agent/filter-component wr destroy agent/test-coverage这里有两个细节。第一每次合并前我会先看 wr list确认对应工作区没有未提交的文件防止 Agent 的进度还停留在工作区里就急着合分支。第二merge 用的是 --no-ff保留合并提交。这样每个 Agent 的改动在历史里都有一条独立的提交链回滚的时候可以按 Agent 粒度操作非常干净。5. 常见问题与排查技巧实录5.1 创建时报错A branch named ... already exists这个报错很常见原因是 Git 要求一个分支只能在一个工作区里被检出你在另一个工作区已经检出了同名分支再创建自然失败。Worktrunk 内部做了一次预检发现同名分支会直接提示你该分支属于哪个工作区但如果你是直接在命令行操作还是需要自己长个心眼。解决办法也很简单要么删除旧工作区再用 wr create 重建要么换一个工作区名字。我建议永远不要复用已经存在过的 Agent 工作区名因为 state.json 里还留着历史记录复用名字容易让日志和提交对不上。5.2 磁盘占用过大node_modules 重复安装这是并行 Agent 工作流里最容易被忽视的问题。每个 worktree 都是独立的目录如果不做处理每个工作区都会装一份完整的 node_modules三个 Agent 就是三份依赖轻松吃掉几个 G。我在 wr create 里提供的 --link node_modules 选项本质是把主工作区的 node_modules 符号链接到新工作区里安装一次全员共享。但要注意一个坑如果不同 Agent 需要安装不同的依赖版本共享的 node_modules 会被互相覆盖装完 A 的包再去装 B 的包可能把 A 的环境搞坏。所以这个选项只适合依赖相对稳定、增量修改少的任务。遇到高频变动依赖的场景宁可多花点磁盘也别压榨这一步。5.3 Agent 进程跑错目录找不到文件有时候 Agent 明明在跑但它写的文件却不在对应工作区里。排查方法是一看环境变量、二看 cwdwr exec backend-search -- pwd wr exec backend-search -- echo $AGENT_WORKTREE_DIR worktrunk where如果 Agent 拿到的 cwd 和 AGENT_WORKTREE_DIR 不一致多半是启动 Agent 的方式没有经过 Worktrunk 包装而是直接从某个固定路径启动。解决办法是把 Agent 的启动快捷方式统一改成 wr exec 包装。这是我从多次产物失踪里总结出的经验很值得记下来。5.4 未提交改动卡住销毁wr destroy 默认会拒绝删除有未提交改动的工作区但如果你确定这些改动已经不需要了得先清理再删除wr exec backend-search -- git status --short wr exec backend-search -- git checkout -- . wr destroy backend-search或者是想留下记录就先 wr sync 提交再销毁。这里我也吃过一次亏某个 Agent 生成的临时文件没进 .gitignorewr sync 每次都把它们提交进去污染了分支历史。后来我养成了两个习惯给每个工作区单独维护一份 .gitignore以及定期检查 wr status 的输出确保交作业的清单完全可控。5.5 问题速查表现象可能原因处理方式创建时报已有同名分支另一个工作区占用同名分支wr list 确认后删除旧工作区磁盘占用暴涨各工作区独立安装依赖创建时启用 --link node_modulesAgent 文件跑错目录启动命令未经过 wr exec改用 wr exec 包装启动销毁失败工作区存在未提交改动先git status 清理后再销毁提交信息混乱多个 Agent 共用同一状态记录依靠 worktree 名称前缀区分提交最后一些实际操作中的体会Worktrunk 不是灵丹妙药它只是把 Git Worktree 这个本来就好用的特质整理成了 AI Agent 工作流里顺手的样子。我个人现在还有个习惯给每个 Agent 工作区名加上日期标志比如 task/search-0421方便一周后回查。另外每次开始一个大的并行任务前我都会固定跑一遍 wr list 和 git status确认主分支干净。这套小工具加小习惯让我在同时带三四条 Agent 工作流的时候基本没再为目录冲突和环境污染操过心。如果你想试直接从 wr create 建一个工作区开始跑完一次完整的创建—干活—合并—销毁你就能感受到并行工作流和传统切分支到底差了多远。