多Agent并行协作：用git worktree隔离工作区与反馈回流实战

1. 多 Agent 并行协作的冲突根源与隔离思路1.1 为什么多个 Agent 同时改代码会“打架”先说结论多 Agent 并行开发时最典型的翻车场景不是模型能力不够而是它们共享同一个工作目录。我最早做 Agent 编排的时候图省事让三个 Agent 同时跑在同一个仓库里结果一个在改utils.py另一个在重构utils.py的调用方第三个还在跑测试。十分钟后git status一片红谁改了哪一行根本分不清git diff里混着三份互不相关的改动回滚都不知道从哪下手。这个问题的本质是文件系统层面的写冲突。Git 本身是为“单人串行提交”设计的工作区working tree只有一份暂存区index也只有一份。多个进程同时写同一份工作区会出现几类典型故障覆盖写Agent A 刚写完文件Agent B 基于旧内容又写了一遍A 的改动直接消失。半成品污染Agent A 改到一半Agent B 跑测试时读到的是残缺代码测试结果全是假阳性。索引竞争两个进程同时git addindex.lock 冲突报Unable to create index.lock。分支切换踩踏一个 Agent 执行git checkout切分支另一个 Agent 的工作区瞬间被换掉。很多人第一反应是“那就加锁串行跑”。串行确实能解决冲突但代价是吞吐量归零——本来三个 Agent 并行能压缩到三分之一的时间串行后一点没省。而且 Agent 任务往往有长尾一个卡住全队列都堵着。1.2 worktree 隔离给每个 Agent 发一套独立工作区git worktree是 Git 2.5 之后内置的能力它允许同一个仓库同时检出多个工作区每个工作区绑定不同的分支但共享同一个.git对象库。这句话拆开看有两个关键点第一每个 worktree 有自己独立的文件目录、独立的 index、独立的 HEAD。Agent A 在/work/a里改文件Agent B 在/work/b里改文件物理上就是两个目录谁也碰不到谁。这就从根上消灭了写冲突。第二它们共享对象库。也就是说 commit、blob、tree 这些底层对象只存一份不会因为开了十个 worktree 就把仓库体积翻十倍。分支之间还能互相cherry-pick、merge回流改动非常方便。打个比方主仓库像一栋楼的图纸档案室worktree 就像按同一份图纸盖出来的多间独立办公室。每间办公室里的家具怎么摆互不影响但档案室里的资料是共享的。Agent 各自在自己的办公室里干活干完了把成果登记回档案室就行。相比“复制整个仓库目录”这种土办法worktree 的优势很明显方案磁盘占用分支管理回流难度对象库一致性复制目录每份全量拷贝各自独立易分叉需手动 diff/patch容易不一致多 worktree仅增量文件统一由主仓库管理直接 merge/cherry-pick天然一致同目录并行无额外占用冲突频发几乎无法回流混乱我实测过一个中等规模项目约 8 万行代码开 6 个 worktree 额外占用的磁盘不到 200MB而复制 6 份目录要吃掉将近 3GB。差距非常直观。1.3 反馈回流隔离之后怎么把成果收回来隔离只是第一步真正难的是回流。Agent 在各自 worktree 里干完活产物怎么合并回主线这里有几个层次的设计代码回流Agent 在自己的分支上 commit主控进程按顺序merge或cherry-pick到集成分支。状态回流Agent 的执行结果成功/失败/日志/产物路径要写回一个共享的反馈通道供调度器决策。冲突回流如果两个 Agent 改了同一块逻辑merge 时必然冲突这时候需要有人或规则来裁决。我踩过最大的坑就是只做了代码隔离没做反馈回流。Agent 各自跑完日志散落在六个目录里我得手动一个个翻效率反而比串行还低。后来我加了一层“反馈文件”机制每个 Agent 把结构化结果写到一个约定路径主控进程轮询收集。这一下子就把整个流程盘活了。2. worktree 隔离的落地细节与脚本实现2.1 环境准备与 worktree 基础命令先把基础打牢。git worktree的核心命令就四条记住它们基本够用# 新增一个 worktree绑定新分支 agent/task-1 git worktree add ../work-agent-1 -b agent/task-1 # 基于已有分支新增 worktree git worktree add ../work-agent-2 agent/task-2 # 列出所有 worktree 及其状态 git worktree list # 删除 worktree先删目录再 prune或直接 remove git worktree remove ../work-agent-1 git worktree prune几个容易忽略的细节路径不要放在主仓库内部。如果你把 worktree 建在.git同级或子目录里Git 会警告甚至拒绝。我一般统一放在仓库同级的../worktrees/目录下结构清晰。分支不能重复检出。同一个分支不能同时被两个 worktree 占用这是 Git 的硬约束。所以每个 Agent 必须有自己的分支命名建议带任务 ID比如agent/task-uuid。git worktree list是你的仪表盘。养成习惯每次调度前先看一眼避免残留的僵尸 worktree 占着分支。注意如果你的 Git 版本低于 2.5worktree命令不存在。用git --version确认一下低于 2.5 的建议升级现在主流发行版自带的都远高于这个版本。2.2 目录规划与分支命名规范多人多 Agent 场景下命名规范比技术本身更重要。我见过太多团队因为分支名乱起最后git branch列表几百条根本认不出哪个是哪个。我目前用的规范是这样的仓库根目录/ ├── project/ # 主仓库集成分支 main └── worktrees/ # 所有 Agent 工作区 ├── agent-taskId/ # 每个任务一个目录 └── ...分支命名agent/taskId/short-desc例如agent/t1/refactor-utils。taskId 用短 UUID 或递增编号short-desc 用两三个词概括任务。这样git branch --list agent/*一眼就能扫出所有在跑的任务。目录和分支的对应关系建议写进一个manifest.json主控进程维护它{ t1: { worktree: ../worktrees/agent-t1, branch: agent/t1/refactor-utils, status: running, startedAt: 2025-01-01T10:00:00Z } }这个 manifest 是反馈回流的基础设施。没有它你根本不知道哪个目录对应哪个任务回收的时候全靠猜。2.3 创建与回收 worktree 的 Shell 脚本下面是我实际在用的脚本分创建和回收两部分。先看创建#!/usr/bin/env bash set -euo pipefail REPO_ROOT${1:?usage: create-worktree.sh repo-root task-id desc} TASK_ID${2:?missing task-id} DESC${3:?missing desc} WORKTREE_BASE$(dirname $REPO_ROOT)/worktrees BRANCHagent/${TASK_ID}/${DESC} WORKTREE_PATH${WORKTREE_BASE}/agent-${TASK_ID} mkdir -p $WORKTREE_BASE # 从当前集成分支切出新分支 cd $REPO_ROOT BASE_BRANCH$(git rev-parse --abbrev-ref HEAD) if git show-ref --verify --quiet refs/heads/${BRANCH}; then echo branch ${BRANCH} already exists, reusing git worktree add $WORKTREE_PATH $BRANCH else git worktree add $WORKTREE_PATH -b $BRANCH $BASE_BRANCH fi echo worktree ready: $WORKTREE_PATH (branch: $BRANCH)这个脚本有几个设计考量。set -euo pipefail是必须的任何一步失败都要立刻停否则会留下半成品 worktree。BASE_BRANCH取当前分支而不是硬编码main是为了支持“从任意集成分支拉活”的灵活场景。分支已存在时走复用逻辑避免重复创建报错。回收脚本更关键因为回收不干净会留下僵尸 worktree 和孤儿分支#!/usr/bin/env bash set -euo pipefail REPO_ROOT${1:?usage: cleanup-worktree.sh repo-root task-id} TASK_ID${2:?missing task-id} WORKTREE_PATH$(dirname $REPO_ROOT)/worktrees/agent-${TASK_ID} cd $REPO_ROOT if [ -d $WORKTREE_PATH ]; then # 先检查是否有未提交改动 if [ -n $(git -C $WORKTREE_PATH status --porcelain) ]; then echo WARN: uncommitted changes in $WORKTREE_PATH, skipping removal exit 1 fi git worktree remove $WORKTREE_PATH fi git worktree prune echo cleaned up worktree for task $TASK_ID这里我特意加了一道未提交改动检查。早期版本直接remove --force结果有一次 Agent 崩溃前没 commit改动全丢了白跑半小时。现在只要检测到脏工作区就拒绝删除让人工介入判断宁可留着也不误删。实操心得git worktree remove默认拒绝删除有未提交改动的 worktree这是保护机制别用--force图省事。真需要强删时先把改动git stash或 commit 到临时分支。2.4 并行调度的并发控制worktree 解决了隔离但并发数不能无限开。我一开始贪心同时开 12 个 Agent结果机器 CPU 打满、内存爆掉Agent 之间抢资源反而更慢。后来做了压测找到几个经验阈值CPU 密集型任务编译、跑测试并发数 ≈ CPU 核心数。IO 密集型任务大量文件读写、网络请求并发数可以到核心数的 2 到 3 倍。混合型从核心数起步观察负载再调。调度器里我用一个简单的信号量控制并发MAX_PARALLEL4 running0 for task in ${TASKS[]}; do while [ $running -ge $MAX_PARALLEL ]; do wait -n # 等任意一个子进程结束 running$((running - 1)) done run_agent $task running$((running 1)) done waitwait -n是 bash 4.3 的特性能等“任意一个”子进程结束比轮询优雅得多。如果你的环境 bash 版本低可以用jobs -p配合轮询但体验差不少。3. 反馈回流机制的设计与实现3.1 反馈通道的三种形态隔离做完Agent 各自跑各自的但主控进程怎么知道它们干得怎么样这就是反馈回流要解决的问题。我实践下来有三种通道形态各有适用场景第一种是文件通道。每个 Agent 把结果写到一个约定路径比如../worktrees/agent-taskId/.agent-result.json。主控进程轮询这些文件。优点是简单、无依赖、跨语言缺点是实时性差轮询有延迟。第二种是标准输出通道。Agent 进程把结构化日志打到 stdout主控进程捕获并解析。优点是实时、天然流式缺点是日志和业务输出容易混在一起解析要小心。第三种是消息队列通道。Agent 把结果发到 Redis、RabbitMQ 之类的队列主控订阅。优点是解耦彻底、支持分布式缺点是引入了外部依赖小项目没必要。我现在的默认选择是文件通道 stdout 混合关键结果成功/失败/产物路径写文件过程日志走 stdout。这样既有可靠的最终状态又有实时的过程可见性。3.2 结构化反馈文件的字段设计反馈文件的内容设计直接决定了回流逻辑好不好写。我踩过的坑是字段太少后来不得不加字段导致新旧格式不兼容。现在我的 schema 固定成这样{ taskId: t1, status: success, branch: agent/t1/refactor-utils, commit: a1b2c3d, changedFiles: [src/utils.py, tests/test_utils.py], artifacts: [dist/report.html], error: null, startedAt: 2025-01-01T10:00:00Z, finishedAt: 2025-01-01T10:05:30Z, metrics: { tokensUsed: 12345, durationMs: 330000 } }几个字段值得展开说。status用枚举值success/failed/partial不要用布尔值因为“部分成功”是真实存在的状态。commit记录 Agent 最终提交的 SHA回流时直接cherry-pick这个 commit不用去猜分支头。changedFiles用于冲突预判——如果两个任务的改动文件有交集merge 前就要预警。metrics是给调度器做决策用的比如 token 消耗超预算的任务要降优先级。注意反馈文件一定要原子写入。Agent 写文件时如果被主控进程读到半截JSON 解析会失败。做法是先写临时文件再mvmv在同一文件系统内是原子的。3.3 回流脚本从收集到合并收集和合并是两个阶段。收集阶段扫描所有反馈文件合并阶段按策略把改动合回集成分支。先看收集#!/usr/bin/env bash set -euo pipefail WORKTREE_BASE${1:?usage: collect-results.sh worktree-base} RESULT_DIR${WORKTREE_BASE}/../results mkdir -p $RESULT_DIR for wt in $WORKTREE_BASE/agent-*; do [ -d $wt ] || continue result_file${wt}/.agent-result.json if [ -f $result_file ]; then task_id$(basename $wt | sed s/^agent-//) cp $result_file ${RESULT_DIR}/${task_id}.json echo collected: $task_id else echo missing result: $wt fi done合并阶段我做了冲突预判这是整个回流里最有价值的一环#!/usr/bin/env bash set -euo pipefail REPO_ROOT${1:?usage: merge-results.sh repo-root results-dir} RESULTS_DIR${2:?missing results-dir} cd $REPO_ROOT INTEGRATION_BRANCH$(git rev-parse --abbrev-ref HEAD) # 收集所有任务的改动文件检测交集 declare -A file_owners conflicts() for result in $RESULTS_DIR/*.json; do [ -f $result ] || continue task_id$(basename $result .json) while IFS read -r f; do if [ -n ${file_owners[$f]:-} ]; then conflicts($f: ${file_owners[$f]} vs $task_id) else file_owners[$f]$task_id fi done (jq -r .changedFiles[] $result) done if [ ${#conflicts[]} -gt 0 ]; then echo POTENTIAL CONFLICTS DETECTED: printf %s\n ${conflicts[]} echo aborting merge, resolve manually exit 2 fi # 无冲突按顺序 cherry-pick for result in $RESULTS_DIR/*.json; do [ -f $result ] || continue commit$(jq -r .commit $result) status$(jq -r .status $result) [ $status success ] || continue git cherry-pick $commit done echo merge complete on $INTEGRATION_BRANCH这段脚本的核心是先检测再合并。file_owners这个关联数组记录每个文件被哪个任务改过一旦发现同一文件被两个任务碰过立刻中止并打印冲突清单。这比直接 merge 然后处理冲突要高效得多——冲突在 merge 阶段暴露时上下文已经乱了而在预判阶段暴露你还能清楚地知道是哪两个任务在抢同一块代码。3.4 冲突裁决的三种策略预判出冲突后怎么办我总结了三种策略按场景选策略一串行化。把冲突的任务排成队列一个跑完再跑下一个。适合冲突文件少、任务本身不长的场景。缺点是牺牲并行度。策略二人工介入。把冲突清单推给人由人决定保留哪个。适合关键路径代码比如核心业务逻辑。我一般对src/core/下的文件强制走人工。策略三自动重跑。让后一个 Agent 基于前一个的结果重新执行。适合任务本身幂等、重跑成本低的场景。实现上就是等前一个 merge 完再给后一个 Agent 发新任务让它基于最新代码重做。实际项目里我通常是混合使用非核心文件走策略一核心文件走策略二测试类任务走策略三。这个决策逻辑可以写进调度器的配置里按文件路径模式匹配。4. 常见问题与排查技巧实录4.1 worktree 相关的高频故障这一节全是血泪。我把实际遇到过的 worktree 故障整理成速查表现象根因解决fatal: branch is already checked out分支被另一个 worktree 占用换分支名或先 remove 占用的 worktreeUnable to create index.lock同目录多进程并发操作确认每个 Agent 独立 worktree检查是否有残留进程worktree 目录删了但git worktree list还在目录被手动删除元数据残留git worktree prunegit worktree add报路径已存在上次回收不干净检查目录内容确认无改动后手动删再 addAgent 提交后主仓库看不到分支提交在 worktree 的独立 HEAD 上git branch确认分支存在用git log branch查看其中分支重复检出是最常见的。我一开始给所有 Agent 都用agent/task这个分支名第二个 Agent 一启动就报错。后来改成带 taskId 的命名问题消失。这个坑很典型worktree 的分支必须全局唯一因为一个分支在任意时刻只能被一个工作区检出。还有一个隐蔽的坑worktree 里的.git是个文件不是目录。它内容是一行gitdir: /path/to/main/.git/worktrees/name。有些工具尤其是老版本的 IDE 和构建脚本会假设.git是目录遇到文件就报错。我遇到过某个打包脚本在 worktree 里跑失败排查半天才发现是它硬编码检查.git目录。解决办法是在脚本里用git rev-parse --git-dir动态获取别硬编码路径。4.2 反馈丢失与状态不一致的排查反馈回流最烦人的问题是状态不一致主控以为任务在跑其实 Agent 早就崩了或者 Agent 写完了结果主控没收到。排查这类问题我有一套固定流程第一步看进程。ps aux | grep agent确认 Agent 进程是否还活着。如果进程没了但状态还是 running说明是崩溃没上报。第二步看反馈文件。检查.agent-result.json是否存在、是否完整。文件不存在说明 Agent 没走到写结果那步文件存在但 JSON 解析失败说明写入不是原子的。第三步看 worktree 状态。git -C worktree status看有没有未提交改动。有改动但没 commit说明 Agent 在提交前挂了。第四步看日志。stdout 日志里通常有崩溃前的最后输出能定位到具体哪一步。我后来加了个心跳机制来预防这类问题Agent 每隔 30 秒更新一次反馈文件里的heartbeatAt字段主控进程发现某个任务超过 90 秒没心跳就判定为失联标记为stale并触发清理。这个机制把“任务卡死无人知”的概率降到了几乎为零。实操心得心跳超时阈值不要设太短。我一开始设 30 秒结果 Agent 跑长任务比如编译大项目时正常阻塞也被误判。后来改成 90 秒配合 Agent 在长操作前主动发一次心跳误判就没了。4.3 并发数调优与资源争抢并发数不是越大越好这个我在 2.4 提过但值得再展开。资源争抢的表现很隐蔽Agent 不报错但每个都变慢整体吞吐反而下降。我做过一组对照实验同一个任务集20 个中等规模重构任务不同并发数下的总耗时并发数总耗时CPU 峰值内存峰值备注142 min25%1.2 GB串行基线224 min50%2.1 GB接近线性加速415 min88%3.8 GB最佳点616 min100%5.4 GB开始争抢821 min100%7.1 GB明显劣化可以看到 4 并发是拐点再往上加收益递减甚至为负。原因是 CPU 打满后Agent 之间的上下文切换和内存压力开始主导。所以并发数要压测确定别拍脑袋。另外如果 Agent 会调用外部 API比如模型推理并发数还要受速率限制约束。我遇到过并发 4 个 Agent 同时打 API触发限流全部重试反而更慢。这种情况要在调度器里加令牌桶限速把 API 调用速率控制在配额内。4.4 脚本健壮性的几个关键点最后说说脚本本身。我早期的脚本很脆跑几次就出问题后来总结了几个必须做的加固第一所有路径用绝对路径或基于脚本位置解析。用$(cd $(dirname $0) pwd)拿到脚本目录再拼相对路径。别依赖调用者的当前目录否则换个地方跑就崩。第二所有外部命令检查退出码。set -e是基础但有些命令在管道里失败不会触发需要set -o pipefail。我吃过git worktree add | tee log的亏add 失败了但 tee 成功脚本继续往下跑留下一堆烂摊子。第三临时文件和锁要清理。用trap注册清理函数脚本退出正常或异常时都执行cleanup() { rm -f $LOCK_FILE $TMP_FILE } trap cleanup EXIT INT TERM第四幂等性。脚本要能重复执行不出错。比如创建 worktree 前先检查是否已存在存在就复用而不是报错。这在 Agent 重试场景下特别重要。第五日志要带时间戳和任务 ID。多 Agent 并行时日志混在一起没有标识根本没法排查。我统一用[$(date -Iseconds)] [task-$TASK_ID] message的格式事后 grep 某个任务一目了然。这套东西搭起来之后我现在跑多 Agent 并行基本是“设好任务、启动、收结果”三步中间不用盯着。偶尔出问题靠反馈文件和日志也能快速定位。真正花时间的反而是任务拆分本身——怎么把一个需求切成互不冲突的子任务这个比技术实现更考验人。我的经验是拆分时尽量按文件边界切让每个 Agent 负责一组独立的文件冲突预判阶段就能直接放行回流几乎零成本。