1. 多 Agent 并行为什么会互相踩脚1.1 从一次真实的翻车现场说起前阵子我在做一个代码仓库的自动化改造思路很直接让几个 Agent 同时干活一个负责重构工具函数一个负责补单元测试一个负责更新文档。听起来很美好实际跑起来十分钟不到仓库就乱成了一锅粥。具体表现是这样的Agent A 正在改utils/parser.pyAgent B 因为要补测试顺手也动了同一个文件里的导入部分Agent C 更新文档时执行了一次git add .把 A 和 B 还没写完的半成品一起提交了。等我回头看git log提交历史像被搅拌机打过一样根本分不清哪次改动是谁做的想回滚都不知道从哪下手。这个问题的本质不是 Agent 不够聪明而是它们共享了同一个工作目录。在同一个目录里文件系统是全局状态git的暂存区、工作区、HEAD 指针也都是全局状态。多个进程同时读写这些全局状态冲突是必然的只是早晚的问题。1.2 共享工作区的三类典型冲突我把踩过的坑归了归类大概有这么三种第一类是文件级冲突。两个 Agent 同时写同一个文件后写的覆盖先写的。这种最直观也最容易发现。麻烦的是那种看起来没冲突的情况——A 改了第 10 行B 改了第 50 行如果它们各自基于旧版本写入最后只有一个改动能留下。第二类是 Git 索引冲突。这个比文件冲突更隐蔽。git add操作的是暂存区暂存区是仓库级别的共享资源。Agent A 执行git add src/a.pyAgent B 同时执行git commitB 很可能把 A 暂存的内容一起提交了。你以为是两个独立的提交实际上纠缠在一起。第三类是分支指针冲突。如果多个 Agent 都在同一个分支上提交HEAD 会不断前移。Agent A 基于 commit X 做修改等它要提交时HEAD 已经跑到 commit Y 了。这时候要么产生意料之外的合并要么直接报错中断。提示很多人第一反应是那我给每个 Agent 加个锁不就行了。加锁确实能避免同时写但代价是并行变成了串行多 Agent 的意义就没了。我们要的是隔离不是排队。1.3 隔离思路的选型为什么是 worktree解决并行冲突常见的思路有几种克隆多个仓库副本、用容器隔离、用git worktree。我逐个试过最后选了 worktree理由如下。克隆多个副本最直接git clone几次就有几个独立目录。但问题是磁盘占用大而且各个副本之间的分支、提交是割裂的想把某个 Agent 的成果合并回来得走一遍远程仓库或者手动加 remote很别扭。仓库稍微大一点克隆一次就是几百 MB 甚至几个 GB开五个 Agent 就是五份。容器隔离更彻底每个 Agent 一个容器文件系统、网络、进程全隔离。但这对本地开发来说太重了启动慢、配置复杂而且容器里的 Git 操作还是要面对怎么把改动弄回宿主机的问题。适合 CI 环境不适合日常开发。git worktree是 Git 原生提供的能力它允许一个仓库同时检出多个工作树。关键在于这些工作树共享同一个.git对象库但各自有独立的工作目录、独立的索引、独立的 HEAD。也就是说Agent A 在worktree-a里提交Agent B 在worktree-b里提交它们的提交对象都进同一个对象库但互不干扰。合并的时候直接git merge或者git cherry-pick就行因为它们本来就是同一个仓库。打个比方克隆副本像是把一本书复印了好几份各改各的最后要拼起来很麻烦worktree 像是同一本书的不同书签位置内容共享但每个人翻到自己的那一页互不影响。方案磁盘占用隔离程度合并成本适用场景多副本克隆高N 倍完全高跨机器协作容器隔离中完全中CI/CD 流水线git worktree低共享对象库工作区/索引/HEAD 独立低本地多 Agent 并行选型结论很清晰本地多 Agent 并行worktree 是性价比最高的方案。2. worktree 隔离的落地细节2.1 worktree 到底隔离了什么没隔离什么要用好 worktree得先搞清楚它的边界。我一开始以为 worktree 是完全隔离结果踩了坑才发现不是。隔离的部分工作目录每个 worktree 有自己独立的文件树A 改的文件 B 看不到。索引暂存区每个 worktree 有自己的.git/worktrees/name/indexgit add互不影响。HEAD每个 worktree 可以检出不同的分支或提交互不干扰。共享的部分对象库所有 commit、tree、blob 都存在主仓库的.git/objects里。这意味着一个 worktree 里创建的提交在另一个 worktree 里可以通过分支名或 commit hash 访问到。引用refs分支、标签是共享的。这里有个关键限制——同一个分支不能同时被两个 worktree 检出。Git 会直接拒绝报错fatal: xxx is already checked out at ...。这个限制非常重要它直接决定了我们的分支策略。你不能让两个 Agent 都检出main分支必须给每个 Agent 分配独立的分支。注意共享对象库是 worktree 的优势也是陷阱。优势是省空间、合并方便陷阱是如果你在某个 worktree 里执行了git gc或者git prune可能会影响其他 worktree 正在使用的对象。日常开发基本遇不到但心里要有数。2.2 分支命名与目录规划基于上面的限制我给每个 Agent 分配一个独立分支命名规则是agent/任务名worktree 目录放在仓库同级的../worktrees/任务名。为什么目录放在仓库外面因为如果放在仓库内部主仓库的git status会把这些 worktree 目录当成未跟踪文件很烦。放在同级目录干净利落。分支命名用agent/前缀好处是git branch一看就知道哪些是 Agent 的工作分支清理的时候git branch | grep agent/一把梭。目录结构大概长这样project/ # 主仓库 ├── .git/ ├── src/ └── ... worktrees/ # worktree 根目录 ├── refactor-utils/ # Agent A 的工作树 │ └── (project 的文件树) ├── add-tests/ # Agent B 的工作树 └── update-docs/ # Agent C 的工作树这里有个实操细节worktree 的路径最好用绝对路径或者相对于主仓库的稳定相对路径。我一开始用了相对路径结果在 worktree 内部执行脚本时相对路径的基准变了导致找不到目录。后来统一改成绝对路径问题消失。2.3 创建与清理的完整命令创建 worktree 的核心命令是git worktree add。给 Agent A 创建# 在主仓库根目录执行 git worktree add -b agent/refactor-utils ../worktrees/refactor-utils main这条命令做了三件事基于main创建新分支agent/refactor-utils在../worktrees/refactor-utils创建 worktree并检出这个新分支。如果分支已经存在去掉-b参数git worktree add ../worktrees/refactor-utils agent/refactor-utils查看当前所有 worktreegit worktree list输出类似/path/to/project abc1234 [main] /path/to/worktrees/refactor-utils def5678 [agent/refactor-utils] /path/to/worktrees/add-tests ghi9012 [agent/add-tests]清理的时候先删 worktree 再删分支git worktree remove ../worktrees/refactor-utils git branch -d agent/refactor-utils如果 worktree 里有未提交的改动git worktree remove会拒绝。这时候要么先提交要么加--force强制删除慎用会丢改动。提示git worktree prune可以清理那些目录已经被手动删除、但 Git 还记录着的僵尸 worktree。我遇到过几次手动rm -rf目录后 Git 还报 worktree 存在的情况prune一下就干净了。3. 反馈回流让 Agent 的成果回到主干3.1 回流不是简单的 merge隔离做好了下一个问题是Agent 干完活成果怎么回到主分支很多人第一反应是git merge。但直接 merge 有个问题多个 Agent 的分支都是从main分出去的如果 Agent A 先合并了Agent B 的分支就落后了再合并 B 的时候可能产生冲突而且冲突解决起来很麻烦因为 B 是基于旧的main开发的。我的做法是先 rebase 再合并或者更稳妥的cherry-pick。具体选哪个取决于 Agent 的提交粒度。如果 Agent 的提交是干净的、逻辑完整的用 rebase# 在 Agent B 的 worktree 里 git fetch origin git rebase main # 解决可能的冲突 git checkout main git merge agent/add-tests如果 Agent 的提交比较碎或者你只想挑其中几个提交用 cherry-pickgit checkout main git cherry-pick commit-hash-1 commit-hash-23.2 回流前的自动检查Agent 的产出不能无脑合并得先过一遍检查。我在回流脚本里加了几个关卡第一关工作区是否干净。git status --porcelain如果有输出说明有未提交的改动要么让 Agent 提交要么标记为待处理。第二关是否有冲突标记。搜索文件里有没有、、这些冲突残留。Agent 有时候会自作聪明地留下这些东西。第三关测试是否通过。如果仓库有测试跑一遍。这一步最耗时但最能拦住问题。第四关diff 规模是否合理。如果 Agent 声称只改了一个函数结果 diff 有几千行那肯定有问题得人工看一眼。这几关用 shell 脚本串起来回流前自动跑通过了才允许合并。下面是一个简化版的检查脚本#!/bin/bash # check_worktree.sh - 回流前的健康检查 set -e WORKTREE_PATH$1 cd $WORKTREE_PATH echo 检查工作区状态 if [ -n $(git status --porcelain) ]; then echo 警告存在未提交的改动 git status --short exit 1 fi echo 检查冲突标记 if git diff --cached --name-only | xargs grep -l 2/dev/null; then echo 错误发现冲突标记 exit 1 fi echo 检查 diff 规模 CHANGED_LINES$(git diff main...HEAD --stat | tail -1 | grep -oE [0-9] | head -1) echo 改动行数$CHANGED_LINES if [ $CHANGED_LINES -gt 2000 ]; then echo 警告改动规模过大建议人工审查 fi echo 检查通过 这个脚本我用了很久虽然简单但拦住了不少低级错误。特别是冲突标记那一关Agent 留下的冲突残留肉眼很难发现脚本一扫就出来了。3.3 回流顺序与依赖处理多个 Agent 的成果回流顺序很重要。如果 Agent B 的改动依赖 Agent A 的改动那必须先合 A 再合 B。我的处理方式是给每个 Agent 的任务打上依赖标签。比如 A 是重构工具函数B 是基于新工具函数补测试那 B 依赖 A。回流时按依赖拓扑排序先合无依赖的再合有依赖的。如果两个 Agent 改了同一个文件的不同部分回流时可能产生冲突。这时候不要慌冲突是正常的关键是冲突解决要有依据。我的经验是谁的任务更底层就以谁为准。比如 A 改的是接口定义B 改的是接口实现那以 A 的接口为准B 的实现要适配 A 的接口。4. 一套可复用的并行编排脚本4.1 脚本的整体设计前面讲了原理和细节这一节把东西串起来给一套可以直接用的脚本。设计目标是一条命令启动多个 Agent 的隔离环境一条命令收集所有成果并回流。脚本分三个部分setup.sh负责创建 worktreerun_agents.sh负责并行执行collect.sh负责回流。我把它放在仓库的scripts/目录下。先看目录约定scripts/ ├── setup.sh # 创建 worktree ├── run_agents.sh # 并行执行 Agent ├── collect.sh # 收集并回流 └── agents.conf # Agent 任务配置agents.conf是任务清单每行一个任务格式是任务名:分支名:命令refactor-utils:agent/refactor-utils:python run_agent.py --task refactor add-tests:agent/add-tests:python run_agent.py --task test update-docs:agent/update-docs:python run_agent.py --task docs4.2 setup.sh批量创建隔离环境#!/bin/bash # setup.sh - 为每个 Agent 创建独立的 worktree set -e REPO_ROOT$(git rev-parse --show-toplevel) WORKTREE_BASE$(dirname $REPO_ROOT)/worktrees CONF_FILE$REPO_ROOT/scripts/agents.conf mkdir -p $WORKTREE_BASE while IFS: read -r task_name branch_name cmd; do [ -z $task_name ] continue worktree_path$WORKTREE_BASE/$task_name if [ -d $worktree_path ]; then echo 跳过 $task_nameworktree 已存在 continue fi echo 创建 worktree$task_name - $branch_name git worktree add -b $branch_name $worktree_path main done $CONF_FILE echo 当前 worktree 列表 git worktree list这个脚本的关键点是REPO_ROOT用git rev-parse --show-toplevel获取保证不管从哪个子目录执行都能找到仓库根。WORKTREE_BASE放在仓库同级避免污染主仓库。4.3 run_agents.sh并行执行与日志隔离#!/bin/bash # run_agents.sh - 并行执行所有 Agent set -e REPO_ROOT$(git rev-parse --show-toplevel) WORKTREE_BASE$(dirname $REPO_ROOT)/worktrees LOG_DIR$REPO_ROOT/logs CONF_FILE$REPO_ROOT/scripts/agents.conf mkdir -p $LOG_DIR pids() while IFS: read -r task_name branch_name cmd; do [ -z $task_name ] continue worktree_path$WORKTREE_BASE/$task_name log_file$LOG_DIR/$task_name.log echo 启动 Agent$task_name ( cd $worktree_path eval $cmd $log_file 21 ) pids($!) done $CONF_FILE echo 等待所有 Agent 完成 for pid in ${pids[]}; do wait $pid || echo PID $pid 执行失败 done echo 执行完毕日志在 $LOG_DIR 这里有几个细节值得说。第一每个 Agent 在子 shell 里执行cd到自己的 worktree互不影响。第二日志按任务名分开写出问题好排查。第三用pids数组收集所有后台进程的 PID最后wait等待全部完成。wait的返回值要处理某个 Agent 失败不能影响其他 Agent 的等待。注意eval $cmd有安全风险如果agents.conf被恶意篡改可能执行任意命令。生产环境建议改成白名单校验或者用数组形式传参。本地开发图方便可以先用eval。4.4 collect.sh回流与冲突处理#!/bin/bash # collect.sh - 收集所有 Agent 成果并回流到 main set -e REPO_ROOT$(git rev-parse --show-toplevel) WORKTREE_BASE$(dirname $REPO_ROOT)/worktrees CONF_FILE$REPO_ROOT/scripts/agents.conf cd $REPO_ROOT git checkout main while IFS: read -r task_name branch_name cmd; do [ -z $task_name ] continue worktree_path$WORKTREE_BASE/$task_name echo 处理 $task_name # 健康检查 if ! bash $REPO_ROOT/scripts/check_worktree.sh $worktree_path; then echo 跳过 $task_name健康检查未通过 continue fi # rebase 到最新 main ( cd $worktree_path git rebase main || { echo 冲突$task_name rebase 失败需人工处理 git rebase --abort exit 1 } ) # 合并 git merge --no-ff $branch_name -m merge: $task_name echo $task_name 合并完成 done $CONF_FILE echo 回流完成 git log --oneline -10这个脚本的核心逻辑是逐个处理每个先检查再 rebase 再合并。--no-ff参数保证每次合并都产生一个合并提交方便回溯。如果 rebase 冲突直接 abort 并跳过留给人工处理不硬来。4.5 脚本使用中的几个坑这套脚本我迭代了好几版踩过的坑分享几个。坑一set -e和wait的冲突。set -e会在任何命令返回非零时退出脚本。但wait等待的进程如果失败返回非零脚本会直接退出后面的 Agent 就不等了。解决办法是wait $pid || true或者像上面那样用|| echo处理。坑二worktree 路径含空格。如果仓库路径里有空格cd $worktree_path不加引号会出错。所有变量引用都加双引号这是 shell 脚本的铁律。坑三并发写日志。如果多个 Agent 写同一个日志文件内容会交错。所以每个 Agent 一个日志文件用任务名区分。坑四rebase 后的分支状态。rebase 会改写提交历史如果 Agent 的分支已经被推送到远程rebase 后推送需要--force。本地开发无所谓但如果涉及远程协作要谨慎。5. 并行编排的边界与经验总结5.1 什么任务适合并行什么不适合worktree 隔离解决了打架问题但不是所有任务都适合并行。我的经验是适合并行的任务之间文件重叠少、逻辑独立。比如一个改前端组件一个改后端接口一个写文档。这种并行收益最大。不适合并行的任务之间有强依赖或者都要改同一个核心文件。比如两个 Agent 都要重构同一个模块那并行只会制造冲突不如串行。判断标准很简单如果两个任务改的文件集合交集为空就可以并行如果有交集就要评估冲突成本。交集越大越不适合并行。5.2 反馈回流的质量把控回流不是终点质量把控才是。我在实践中总结了几条提交信息要规范。Agent 的提交信息经常是update、fix这种无意义的词。我在 Agent 的 prompt 里强制要求提交信息格式type(scope): description比如refactor(parser): extract token validation。这样回流后git log才可读。小步提交优于大步提交。一个 Agent 如果只产生一个巨大的提交回流时冲突很难解决。鼓励 Agent 每完成一个逻辑单元就提交一次回流时 cherry-pick 更灵活。回流后跑一次全量测试。单个 Agent 的测试通过不代表合并后通过。合并可能引入集成问题全量测试是最后一道防线。5.3 从能跑到好用的几点体会最后分享几个让这套方案从能跑到好用的细节。第一给 Agent 加超时。有的 Agent 会卡死无限等待。在run_agents.sh里用timeout命令包一层比如timeout 600 python run_agent.py十分钟没结果就杀掉避免整个流程卡住。第二日志要能实时看。后台执行时日志写文件但调试阶段我想实时看。可以用tail -f logs/*.log同时盯多个日志或者用multitail这类工具。第三worktree 要定期清理。跑多了会积累一堆 worktree 和分支占空间也乱。我写了个cleanup.sh把所有agent/开头的分支和对应 worktree 一键清掉每周跑一次。第四配置文件要版本化。agents.conf跟着仓库走任务定义、分支命名都记录在案换台机器或者换个人setup.sh一跑就能复现环境。这套方案我用在几个中型项目上多 Agent 并行的效率提升很明显最关键的是不再有打架的焦虑。隔离做干净了回流有章法了剩下的就是让 Agent 安心干活。worktree 这个 Git 原生能力被低估太久了值得每个做 Agent 编排的人认真用起来。
