1. 多 Agent 并行开发的冲突根源与 worktree 隔离思路同时跑多个 AI Agent 写代码最让人头疼的不是模型能力不够而是它们互相踩脚。我最近在做一个中型项目重构开了三个 Agent 分别处理数据层、接口层和前端组件结果两个 Agent 同时改了同一个配置文件一个把另一个的改动覆盖了排查了半天才发现是文件锁冲突。这种问题在单 Agent 场景下根本不会出现但一旦并行文件系统就成了共享资源谁先写谁后写完全不可控。1.1 为什么同一个工作目录跑多个 Agent 必然出问题核心原因在于 Git 的工作区模型。一个普通的 Git 仓库只有一个工作目录working directory和一个索引index所有分支切换、文件修改都发生在同一块磁盘区域上。当你让 Agent A 切到 feature-a 分支改代码Agent B 同时切到 feature-b 分支Git 的 HEAD 指针会被反复覆盖暂存区也会互相污染。更隐蔽的问题是Agent 通常以非交互方式运行它们不会像人一样看到“当前分支已切换”的提示而是直接按自己的上下文继续操作结果就是在错误的分支上提交了代码。我实测过一个典型场景两个 Agent 同时执行git checkout -b创建新分支第二个 Agent 的命令会因为分支已存在而失败但它不会停下来询问而是继续在当前分支上修改文件。最终两个 Agent 的改动混在同一个分支里提交历史一团糟。这不是 Agent 的 bug而是工作目录共享导致的必然结果。1.2 worktree 隔离的核心机制与优势git worktree是 Git 2.5 引入的功能它允许同一个仓库关联多个工作目录每个工作目录可以检出不同的分支且各自拥有独立的索引和 HEAD。用生活化的类比普通 Git 仓库像一间办公室所有人共用一张桌子worktree 则像给每个 Agent 分配了独立的工位桌子上的文件互不干扰但大家共享同一个档案柜即.git对象库。这种隔离方式有几个关键优势。第一磁盘开销小。worktree 不会复制整个.git目录只创建新的工作区文件对于大仓库来说比git clone快得多也省空间。第二分支管理清晰。每个 worktree 绑定一个分支Agent 在自己的目录里随便切分支、提交、回滚完全不影响其他 worktree。第三合并回流可控。所有 worktree 共享同一个对象库意味着 Agent A 提交的 commit 在 Agent B 的 worktree 里也能看到这为后续的反馈回流和代码合并提供了基础。注意worktree 不能在同一分支上创建两个实例。如果你尝试git worktree add ../dir2 main而 main 已经被主工作区占用Git 会直接报错。这个限制其实是好事它强制每个 Agent 使用独立分支避免了分支级别的冲突。1.3 方案选型的对比与决策依据在决定用 worktree 之前我对比过几种常见方案。git clone多份仓库最直接但每个克隆都有完整的.git目录对于几百 MB 的仓库来说三个 Agent 就是三倍磁盘占用而且拉取远程更新时要重复操作。Docker 容器隔离更彻底但启动开销大文件挂载配置复杂Agent 访问宿主机代码需要额外映射调试起来很麻烦。虚拟机方案太重完全不适合日常开发节奏。worktree 的定位刚好在中间隔离级别足够独立工作区、独立索引开销又足够小共享对象库而且完全在 Git 原生能力范围内不需要额外工具。对于“多个 Agent 并行改代码”这个具体场景worktree 是目前最平衡的选择。我后来把这个方案推荐给团队里其他用 Agent 的同事反馈都是“早该这么干”。2. 从零搭建 worktree 隔离环境的完整实操理论说再多不如直接上手。这一章我按实际操作的顺序从环境检查到脚本落地把每一步的命令和意图都拆开讲。你跟着做一遍基本就能在自己的项目里跑起来。2.1 环境准备与 Git 版本确认第一步永远是确认 Git 版本。git worktree需要 Git 2.5 以上但一些子命令的稳定性在 2.7 之后才完善建议至少用 2.20 以上的版本。在终端执行git --version如果版本低于 2.5需要先升级。Windows 用户去 Git 官网下载最新安装包安装时注意勾选“Git Bash”和“添加到 PATH”。macOS 用brew install git即可。Linux 根据发行版用apt或yum安装。安装完成后重新打开终端再次确认版本。提示Windows 上如果遇到npm : 无法将“npm”项识别为 cmdlet这类报错通常是环境变量没配好。Git 安装时自带的 Git Bash 可以绕过这个问题但如果你要在 PowerShell 里跑脚本需要手动把 Git 的cmd目录加到系统 PATH 里。2.2 创建 worktree 的标准流程假设你的主仓库在~/projects/myapp当前在main分支。现在要给三个 Agent 分别分配工作区操作如下cd ~/projects/myapp # 为 Agent A 创建 worktree绑定新分支 feature-agent-a git worktree add ../myapp-agent-a -b feature-agent-a # 为 Agent B 创建 worktree绑定新分支 feature-agent-b git worktree add ../myapp-agent-b -b feature-agent-b # 为 Agent C 创建 worktree绑定新分支 feature-agent-c git worktree add ../myapp-agent-c -b feature-agent-c执行完后~/projects/下会多出三个目录每个目录都是一个完整的工作区但共享同一个.git对象库。你可以用git worktree list查看当前所有 worktree 的状态git worktree list输出会显示主工作区和三个新增工作区的路径、当前 commit 和分支名。这个命令在排查“某个 Agent 到底在哪个目录干活”时特别有用。2.3 目录结构与分支命名规范目录命名我建议遵循“主仓库名-agent标识”的格式比如myapp-agent-a。这样在文件管理器里一眼就能看出对应关系不会跟其他项目混淆。分支命名则用“feature-agent-标识”或“task-功能名-agent标识”关键是让分支名自带上下文后续合并时不用去翻日志猜这个分支是干嘛的。我踩过的一个坑是早期用agent1、agent2这种无意义命名结果一周后完全想不起来 agent2 当时在改什么功能。后来改成feature-payment-agent-b这种格式分支列表一目了然。另外如果 Agent 的任务有明确的功能边界分支名里带上功能关键词合并时的 commit message 也会更清晰。2.4 批量创建脚本的编写与参数化手动敲命令创建三个 worktree 还行但如果要开五个、十个 Agent或者经常需要重建环境就得靠脚本了。下面这个 Shell 脚本是我实际在用的版本支持传入 Agent 数量和分支前缀#!/bin/bash # create-worktrees.sh # 用法: ./create-worktrees.sh agent数量 分支前缀 [基础分支] set -e AGENT_COUNT${1:-3} BRANCH_PREFIX${2:-feature-agent} BASE_BRANCH${3:-main} REPO_ROOT$(git rev-parse --show-toplevel) REPO_NAME$(basename $REPO_ROOT) PARENT_DIR$(dirname $REPO_ROOT) echo 仓库根目录: $REPO_ROOT echo 将创建 $AGENT_COUNT 个 worktree分支前缀: $BRANCH_PREFIX for i in $(seq 1 $AGENT_COUNT); do AGENT_ID$(printf %02d $i) WORKTREE_DIR${PARENT_DIR}/${REPO_NAME}-agent-${AGENT_ID} BRANCH_NAME${BRANCH_PREFIX}-${AGENT_ID} if [ -d $WORKTREE_DIR ]; then echo [跳过] $WORKTREE_DIR 已存在 continue fi git worktree add $WORKTREE_DIR -b $BRANCH_NAME $BASE_BRANCH echo [完成] $WORKTREE_DIR - $BRANCH_NAME done echo 全部完成当前 worktree 列表 git worktree list这个脚本里几个关键点值得说明。set -e让脚本在任意命令失败时立即退出避免创建到一半留下脏状态。git rev-parse --show-toplevel自动获取仓库根目录这样脚本放在任何位置都能正确执行。printf %02d把编号格式化成两位数保证目录排序时agent-01在agent-02前面不会出现agent-10排在agent-2前面的问题。-b参数指定新分支名$BASE_BRANCH作为起点确保每个 Agent 都从最新的主分支开始工作。注意脚本里的seq命令在 macOS 上默认可用但某些精简版 Linux 可能没有。如果报错可以用for ((i1; iAGENT_COUNT; i))的 Bash 算术循环替代。3. Agent 任务分配与反馈回流机制设计worktree 解决了“不打架”的问题但并行开发的最终目标是把各个 Agent 的产出合并回主线。如果只是隔离而不设计回流路径那跟各干各的没区别。这一章讲怎么给 Agent 分任务、怎么收集它们的改动、怎么安全地合并。3.1 任务拆分原则与 Agent 能力匹配不是所有任务都适合并行。我的经验是按文件边界拆分比按功能拆分更安全。比如数据层改models/目录接口层改api/目录前端改components/目录这样即使两个 Agent 的功能有交集文件层面也不会冲突。如果实在无法避免文件重叠就要在任务描述里明确告诉 Agent“只修改某个函数”或“只动某个文件的某一段”并在合并时人工审查。Agent 的能力匹配也很重要。我通常把复杂度高、需要跨文件推理的任务交给能力强的 Agent把格式化、重命名、补测试这类机械任务交给轻量 Agent。这样既能保证质量又能控制成本。任务描述里要写清楚目标文件路径、期望的改动范围、验收标准比如“所有测试通过”、以及“不要修改其他文件”的硬性约束。3.2 反馈回流的三种模式反馈回流指的是 Agent 完成工作后它的改动如何回到主仓库。我实践下来有三种模式各有适用场景。第一种是直接合并。Agent 在自己的 worktree 里提交后主工作区执行git merge feature-agent-a。这种方式最简单适合改动小、冲突概率低的场景。但缺点是如果 Agent 的提交历史很乱比如有十几个 WIP commit合并后主分支的历史会很难看。第二种是压缩合并。用git merge --squash feature-agent-a把 Agent 的所有改动压缩成一个 commit再手动提交。这样主分支历史干净每个 Agent 的产出对应一个清晰的提交。我大部分场景都用这种方式尤其是 Agent 会产生大量中间提交的时候。第三种是补丁审查。Agent 提交后用git format-patch生成补丁文件人工审查后再git am应用到主分支。这种方式最安全适合对代码质量要求极高的场景但操作步骤多适合作为最终把关手段而不是日常流程。3.3 合并冲突的预防与处理策略即使做了 worktree 隔离合并时仍然可能冲突因为不同 Agent 可能改了同一个文件的不同部分。预防冲突的关键是尽早合并。不要让 Agent 的分支存活太久最好每天合并一次减少分叉程度。另外在任务分配时就明确“这个文件归 Agent A 管”从源头上避免重叠。如果真的冲突了处理流程是先在主工作区git merge feature-agent-aGit 会标记冲突文件。打开冲突文件你会看到、、标记。这时候不要慌先理解两边的改动意图再决定保留哪边或怎么融合。我通常会用git diff对比两个分支的改动确认没有逻辑冲突后再手动编辑。处理完后git add冲突文件git commit完成合并。提示如果冲突文件很多可以用git mergetool打开可视化工具比手动编辑效率高。但工具只是辅助最终判断还是要靠你对代码的理解。3.4 自动化回流脚本的设计手动合并三个 Agent 的分支还行但如果每天都要做就得自动化。下面这个脚本遍历所有 Agent 分支依次压缩合并到当前分支并在合并前检查是否有未提交的改动#!/bin/bash # merge-agents.sh # 用法: ./merge-agents.sh 分支前缀 set -e BRANCH_PREFIX${1:-feature-agent} CURRENT_BRANCH$(git rev-parse --abbrev-ref HEAD) echo 当前分支: $CURRENT_BRANCH echo 准备合并前缀为 $BRANCH_PREFIX 的所有分支 # 检查工作区是否干净 if [ -n $(git status --porcelain) ]; then echo 错误当前工作区有未提交的改动请先处理 exit 1 fi # 获取所有匹配的分支 BRANCHES$(git branch --list ${BRANCH_PREFIX}-* | sed s/^[* ]*//) if [ -z $BRANCHES ]; then echo 没有找到匹配的分支 exit 0 fi for BRANCH in $BRANCHES; do echo ---------------------------------------- echo 正在合并: $BRANCH # 检查分支是否有新提交 COMMIT_COUNT$(git rev-list --count $CURRENT_BRANCH..$BRANCH) if [ $COMMIT_COUNT -eq 0 ]; then echo [跳过] $BRANCH 没有新提交 continue fi echo 该分支有 $COMMIT_COUNT 个新提交 # 压缩合并 if git merge --squash $BRANCH; then git commit -m merge: 合并 $BRANCH 的改动$COMMIT_COUNT 个提交 echo [完成] $BRANCH 已合并 else echo [冲突] $BRANCH 合并时产生冲突请手动处理 echo 冲突文件 git diff --name-only --diff-filterU exit 1 fi done echo ---------------------------------------- echo 全部合并完成 git log --oneline -10这个脚本的核心逻辑是先检查工作区干净再遍历分支用git rev-list --count判断分支是否有新提交避免合并空分支然后用--squash压缩合并。如果遇到冲突脚本会列出冲突文件并退出让你手动处理而不是强行继续。最后打印最近 10 条提交日志方便确认合并结果。4. 常见问题排查与实战避坑经验这一章是我在实际使用中踩过的坑和总结的排查方法。很多问题在官方文档里不会写但实际跑起来一定会遇到。4.1 worktree 创建失败的典型原因最常见的报错是fatal: xxx is already checked out at yyy。这说明你要检出的分支已经被另一个 worktree 占用了。解决办法是换一个分支名或者先删除占用该分支的 worktree。用git worktree list可以快速定位是哪个目录占用了分支。另一个常见问题是路径已存在。如果目标目录非空git worktree add会拒绝创建。这时候要么换个目录名要么先清空目标目录。我建议在脚本里加一个if [ -d $WORKTREE_DIR ]的判断存在就跳过避免误删数据。还有一种情况是.git文件损坏。worktree 目录里有一个.git文件不是目录它指向主仓库的.git/worktrees/下的元数据。如果这个文件被误删或内容被改worktree 就会失效。修复方法是删除该 worktree 目录重新用git worktree add创建。4.2 Agent 在错误目录执行命令的排查Agent 有时候会“迷路”在主工作区而不是自己的 worktree 里执行命令。这种情况通常是因为 Agent 的上下文里没有明确当前工作目录或者它自己cd到了别的地方。排查方法是在每个 Agent 的任务描述开头强制加上cd /path/to/worktree并在脚本里用pwd打印当前目录确认。我还会在 worktree 目录里放一个.agent-context文件写明“你当前在 Agent A 的工作区分支是 feature-agent-a只修改本目录下的文件”。Agent 读取这个文件后行为会稳定很多。这个技巧看起来简单但实测能减少大量“改错目录”的问题。4.3 合并时的隐性冲突与代码审查要点有些冲突 Git 检测不到但逻辑上是矛盾的。比如 Agent A 把某个函数的参数从两个改成三个Agent B 在另一个文件里调用这个函数时还是传两个参数。Git 合并时不会报冲突但代码跑起来就崩了。这类问题只能靠测试和代码审查发现。我的做法是合并后立即跑一遍完整测试套件包括单元测试和集成测试。如果测试覆盖不够就手动检查所有跨文件的接口调用。另外合并前用git diff main...feature-agent-a查看 Agent 的完整改动重点关注函数签名、配置项、数据库 schema 这类“契约”层面的变化。4.4 常见问题速查表问题现象可能原因解决方法fatal: branch is already checked out分支已被其他 worktree 占用换分支名或删除占用 worktreeworktree 目录创建失败目标路径已存在且非空换目录名或清空目标目录Agent 改错目录Agent 上下文缺少工作目录信息任务描述强制cd放置.agent-context文件合并后代码运行报错隐性接口冲突合并后跑完整测试检查函数签名和配置git worktree list显示异常.git文件损坏删除 worktree 目录重新创建合并时大量冲突分支存活太久分叉严重提高合并频率按文件边界分配任务4.5 性能与资源占用的实测数据我在一个约 200MB 的仓库上做了对比测试。用git clone创建三个副本总磁盘占用约 600MB每个副本首次拉取耗时约 15 秒。用 worktree 创建三个工作区总磁盘占用约 220MB只多了工作区文件创建耗时不到 2 秒。这个差距在仓库越大时越明显。内存方面worktree 本身不额外占用内存Agent 进程的内存消耗取决于模型和任务复杂度。CPU 方面多个 Agent 同时跑会有竞争但 worktree 的文件隔离减少了锁竞争整体吞吐比共享目录高不少。我实测三个 Agent 并行时worktree 方案的任务完成时间比共享目录方案快约 30%主要省在冲突排查和重试上。注意worktree 虽然省磁盘但每个工作区的node_modules、venv这类依赖目录是独立的。如果项目依赖很大三个 worktree 就是三份依赖。解决办法是用符号链接共享依赖目录或者用 pnpm 这类支持全局缓存的包管理器。5. 脚本化落地与持续集成衔接把前面的零散操作串成一套可重复执行的流程才算真正落地。这一章讲怎么把 worktree 管理脚本化以及怎么跟 CI 流程衔接。5.1 一键创建与清理脚本的整合我把创建和清理逻辑整合到一个脚本里用子命令区分操作#!/bin/bash # worktree-manager.sh # 用法: ./worktree-manager.sh create|clean|list [参数] set -e REPO_ROOT$(git rev-parse --show-toplevel) REPO_NAME$(basename $REPO_ROOT) PARENT_DIR$(dirname $REPO_ROOT) case $1 in create) COUNT${2:-3} PREFIX${3:-feature-agent} for i in $(seq 1 $COUNT); do ID$(printf %02d $i) DIR${PARENT_DIR}/${REPO_NAME}-agent-${ID} BRANCH${PREFIX}-${ID} if [ -d $DIR ]; then echo [跳过] $DIR 已存在 continue fi git worktree add $DIR -b $BRANCH main echo [创建] $DIR - $BRANCH done ;; clean) git worktree list --porcelain | grep ^worktree | awk {print $2} | while read -r wt; do if [ $wt ! $REPO_ROOT ]; then echo [删除] $wt git worktree remove $wt --force fi done git worktree prune echo 清理完成 ;; list) git worktree list ;; *) echo 用法: $0 create|clean|list [参数] exit 1 ;; esacclean子命令用git worktree list --porcelain获取所有 worktree 路径跳过主工作区逐个用git worktree remove --force删除最后git worktree prune清理元数据。--force是为了处理有未提交改动的 worktree但这也意味着会丢失未提交的改动所以我在实际使用时会先确认没有重要改动。5.2 与 CI 流程的衔接方式CI 环境里通常不需要 worktree因为 CI 本身就是一次性的。但如果你的 CI 要跑多个 Agent 的代码可以用 worktree 在同一个 CI job 里并行测试多个分支。具体做法是CI 拉取主仓库后用脚本创建 worktree分别 checkout 各个 Agent 分支然后并行跑测试。这样比开多个 CI job 省资源也比串行测试快。另一个衔接点是合并后的验证。Agent 分支合并到主分支后CI 自动触发完整测试。如果测试失败可以用git revert回滚合并提交或者用git reset --hard回到合并前的状态。我建议用git revert因为它保留了历史记录方便追溯是哪个 Agent 的改动导致了问题。5.3 日志记录与可追溯性设计多 Agent 并行时出问题后最难的是定位“是谁改的”。我的做法是每个 Agent 的提交都带上 Agent 标识比如[agent-a] feat: 添加用户查询接口。合并时用--squash会丢失单个提交的信息所以我在合并提交的 message 里写明来源分支和提交数量。另外脚本执行时把关键操作写入日志文件比如worktree-manager.log记录创建时间、目录、分支、操作结果。这样出问题时翻日志就能还原整个过程。5.4 扩展思路从 worktree 到多机隔离worktree 解决的是单机多 Agent 的隔离问题。如果 Agent 分布在多台机器上worktree 就不适用了需要用远程分支加 CI 的方式。每台机器 clone 仓库Agent 在各自机器上工作通过 push 远程分支来汇总。这种方式隔离更彻底但网络开销和合并复杂度更高。我的建议是单机场景优先用 worktree多机场景再考虑远程分支方案不要为了“看起来高级”而过度设计。最后分享一个我在实际使用中总结的小技巧给每个 worktree 目录放一个README-agent.md写明这个工作区的用途、当前任务、负责人哪个 Agent、以及合并状态。这个文件不提交到 Git只是本地参考。当你有五六个 worktree 时这个文件能帮你快速回忆每个目录在干嘛省去翻分支列表的时间。
1. 多 Agent 并行开发的冲突根源与 worktree 隔离思路同时跑多个 AI Agent 写代码最让人头疼的不是模型能力不够而是它们互相踩脚。我最近在做一个中型项目重构开了三个 Agent 分别处理数据层、接口层和前端组件结果两个 Agent 同时改了同一个配置文件一个把另一个的改动覆盖了排查了半天才发现是文件锁冲突。这种问题在单 Agent 场景下根本不会出现但一旦并行文件系统就成了共享资源谁先写谁后写完全不可控。1.1 为什么同一个工作目录跑多个 Agent 必然出问题核心原因在于 Git 的工作区模型。一个普通的 Git 仓库只有一个工作目录working directory和一个索引index所有分支切换、文件修改都发生在同一块磁盘区域上。当你让 Agent A 切到 feature-a 分支改代码Agent B 同时切到 feature-b 分支Git 的 HEAD 指针会被反复覆盖暂存区也会互相污染。更隐蔽的问题是Agent 通常以非交互方式运行它们不会像人一样看到“当前分支已切换”的提示而是直接按自己的上下文继续操作结果就是在错误的分支上提交了代码。我实测过一个典型场景两个 Agent 同时执行git checkout -b创建新分支第二个 Agent 的命令会因为分支已存在而失败但它不会停下来询问而是继续在当前分支上修改文件。最终两个 Agent 的改动混在同一个分支里提交历史一团糟。这不是 Agent 的 bug而是工作目录共享导致的必然结果。1.2 worktree 隔离的核心机制与优势git worktree是 Git 2.5 引入的功能它允许同一个仓库关联多个工作目录每个工作目录可以检出不同的分支且各自拥有独立的索引和 HEAD。用生活化的类比普通 Git 仓库像一间办公室所有人共用一张桌子worktree 则像给每个 Agent 分配了独立的工位桌子上的文件互不干扰但大家共享同一个档案柜即.git对象库。这种隔离方式有几个关键优势。第一磁盘开销小。worktree 不会复制整个.git目录只创建新的工作区文件对于大仓库来说比git clone快得多也省空间。第二分支管理清晰。每个 worktree 绑定一个分支Agent 在自己的目录里随便切分支、提交、回滚完全不影响其他 worktree。第三合并回流可控。所有 worktree 共享同一个对象库意味着 Agent A 提交的 commit 在 Agent B 的 worktree 里也能看到这为后续的反馈回流和代码合并提供了基础。注意worktree 不能在同一分支上创建两个实例。如果你尝试git worktree add ../dir2 main而 main 已经被主工作区占用Git 会直接报错。这个限制其实是好事它强制每个 Agent 使用独立分支避免了分支级别的冲突。1.3 方案选型的对比与决策依据在决定用 worktree 之前我对比过几种常见方案。git clone多份仓库最直接但每个克隆都有完整的.git目录对于几百 MB 的仓库来说三个 Agent 就是三倍磁盘占用而且拉取远程更新时要重复操作。Docker 容器隔离更彻底但启动开销大文件挂载配置复杂Agent 访问宿主机代码需要额外映射调试起来很麻烦。虚拟机方案太重完全不适合日常开发节奏。worktree 的定位刚好在中间隔离级别足够独立工作区、独立索引开销又足够小共享对象库而且完全在 Git 原生能力范围内不需要额外工具。对于“多个 Agent 并行改代码”这个具体场景worktree 是目前最平衡的选择。我后来把这个方案推荐给团队里其他用 Agent 的同事反馈都是“早该这么干”。2. 从零搭建 worktree 隔离环境的完整实操理论说再多不如直接上手。这一章我按实际操作的顺序从环境检查到脚本落地把每一步的命令和意图都拆开讲。你跟着做一遍基本就能在自己的项目里跑起来。2.1 环境准备与 Git 版本确认第一步永远是确认 Git 版本。git worktree需要 Git 2.5 以上但一些子命令的稳定性在 2.7 之后才完善建议至少用 2.20 以上的版本。在终端执行git --version如果版本低于 2.5需要先升级。Windows 用户去 Git 官网下载最新安装包安装时注意勾选“Git Bash”和“添加到 PATH”。macOS 用brew install git即可。Linux 根据发行版用apt或yum安装。安装完成后重新打开终端再次确认版本。提示Windows 上如果遇到npm : 无法将“npm”项识别为 cmdlet这类报错通常是环境变量没配好。Git 安装时自带的 Git Bash 可以绕过这个问题但如果你要在 PowerShell 里跑脚本需要手动把 Git 的cmd目录加到系统 PATH 里。2.2 创建 worktree 的标准流程假设你的主仓库在~/projects/myapp当前在main分支。现在要给三个 Agent 分别分配工作区操作如下cd ~/projects/myapp # 为 Agent A 创建 worktree绑定新分支 feature-agent-a git worktree add ../myapp-agent-a -b feature-agent-a # 为 Agent B 创建 worktree绑定新分支 feature-agent-b git worktree add ../myapp-agent-b -b feature-agent-b # 为 Agent C 创建 worktree绑定新分支 feature-agent-c git worktree add ../myapp-agent-c -b feature-agent-c执行完后~/projects/下会多出三个目录每个目录都是一个完整的工作区但共享同一个.git对象库。你可以用git worktree list查看当前所有 worktree 的状态git worktree list输出会显示主工作区和三个新增工作区的路径、当前 commit 和分支名。这个命令在排查“某个 Agent 到底在哪个目录干活”时特别有用。2.3 目录结构与分支命名规范目录命名我建议遵循“主仓库名-agent标识”的格式比如myapp-agent-a。这样在文件管理器里一眼就能看出对应关系不会跟其他项目混淆。分支命名则用“feature-agent-标识”或“task-功能名-agent标识”关键是让分支名自带上下文后续合并时不用去翻日志猜这个分支是干嘛的。我踩过的一个坑是早期用agent1、agent2这种无意义命名结果一周后完全想不起来 agent2 当时在改什么功能。后来改成feature-payment-agent-b这种格式分支列表一目了然。另外如果 Agent 的任务有明确的功能边界分支名里带上功能关键词合并时的 commit message 也会更清晰。2.4 批量创建脚本的编写与参数化手动敲命令创建三个 worktree 还行但如果要开五个、十个 Agent或者经常需要重建环境就得靠脚本了。下面这个 Shell 脚本是我实际在用的版本支持传入 Agent 数量和分支前缀#!/bin/bash # create-worktrees.sh # 用法: ./create-worktrees.sh agent数量 分支前缀 [基础分支] set -e AGENT_COUNT${1:-3} BRANCH_PREFIX${2:-feature-agent} BASE_BRANCH${3:-main} REPO_ROOT$(git rev-parse --show-toplevel) REPO_NAME$(basename $REPO_ROOT) PARENT_DIR$(dirname $REPO_ROOT) echo 仓库根目录: $REPO_ROOT echo 将创建 $AGENT_COUNT 个 worktree分支前缀: $BRANCH_PREFIX for i in $(seq 1 $AGENT_COUNT); do AGENT_ID$(printf %02d $i) WORKTREE_DIR${PARENT_DIR}/${REPO_NAME}-agent-${AGENT_ID} BRANCH_NAME${BRANCH_PREFIX}-${AGENT_ID} if [ -d $WORKTREE_DIR ]; then echo [跳过] $WORKTREE_DIR 已存在 continue fi git worktree add $WORKTREE_DIR -b $BRANCH_NAME $BASE_BRANCH echo [完成] $WORKTREE_DIR - $BRANCH_NAME done echo 全部完成当前 worktree 列表 git worktree list这个脚本里几个关键点值得说明。set -e让脚本在任意命令失败时立即退出避免创建到一半留下脏状态。git rev-parse --show-toplevel自动获取仓库根目录这样脚本放在任何位置都能正确执行。printf %02d把编号格式化成两位数保证目录排序时agent-01在agent-02前面不会出现agent-10排在agent-2前面的问题。-b参数指定新分支名$BASE_BRANCH作为起点确保每个 Agent 都从最新的主分支开始工作。注意脚本里的seq命令在 macOS 上默认可用但某些精简版 Linux 可能没有。如果报错可以用for ((i1; iAGENT_COUNT; i))的 Bash 算术循环替代。3. Agent 任务分配与反馈回流机制设计worktree 解决了“不打架”的问题但并行开发的最终目标是把各个 Agent 的产出合并回主线。如果只是隔离而不设计回流路径那跟各干各的没区别。这一章讲怎么给 Agent 分任务、怎么收集它们的改动、怎么安全地合并。3.1 任务拆分原则与 Agent 能力匹配不是所有任务都适合并行。我的经验是按文件边界拆分比按功能拆分更安全。比如数据层改models/目录接口层改api/目录前端改components/目录这样即使两个 Agent 的功能有交集文件层面也不会冲突。如果实在无法避免文件重叠就要在任务描述里明确告诉 Agent“只修改某个函数”或“只动某个文件的某一段”并在合并时人工审查。Agent 的能力匹配也很重要。我通常把复杂度高、需要跨文件推理的任务交给能力强的 Agent把格式化、重命名、补测试这类机械任务交给轻量 Agent。这样既能保证质量又能控制成本。任务描述里要写清楚目标文件路径、期望的改动范围、验收标准比如“所有测试通过”、以及“不要修改其他文件”的硬性约束。3.2 反馈回流的三种模式反馈回流指的是 Agent 完成工作后它的改动如何回到主仓库。我实践下来有三种模式各有适用场景。第一种是直接合并。Agent 在自己的 worktree 里提交后主工作区执行git merge feature-agent-a。这种方式最简单适合改动小、冲突概率低的场景。但缺点是如果 Agent 的提交历史很乱比如有十几个 WIP commit合并后主分支的历史会很难看。第二种是压缩合并。用git merge --squash feature-agent-a把 Agent 的所有改动压缩成一个 commit再手动提交。这样主分支历史干净每个 Agent 的产出对应一个清晰的提交。我大部分场景都用这种方式尤其是 Agent 会产生大量中间提交的时候。第三种是补丁审查。Agent 提交后用git format-patch生成补丁文件人工审查后再git am应用到主分支。这种方式最安全适合对代码质量要求极高的场景但操作步骤多适合作为最终把关手段而不是日常流程。3.3 合并冲突的预防与处理策略即使做了 worktree 隔离合并时仍然可能冲突因为不同 Agent 可能改了同一个文件的不同部分。预防冲突的关键是尽早合并。不要让 Agent 的分支存活太久最好每天合并一次减少分叉程度。另外在任务分配时就明确“这个文件归 Agent A 管”从源头上避免重叠。如果真的冲突了处理流程是先在主工作区git merge feature-agent-aGit 会标记冲突文件。打开冲突文件你会看到、、标记。这时候不要慌先理解两边的改动意图再决定保留哪边或怎么融合。我通常会用git diff对比两个分支的改动确认没有逻辑冲突后再手动编辑。处理完后git add冲突文件git commit完成合并。提示如果冲突文件很多可以用git mergetool打开可视化工具比手动编辑效率高。但工具只是辅助最终判断还是要靠你对代码的理解。3.4 自动化回流脚本的设计手动合并三个 Agent 的分支还行但如果每天都要做就得自动化。下面这个脚本遍历所有 Agent 分支依次压缩合并到当前分支并在合并前检查是否有未提交的改动#!/bin/bash # merge-agents.sh # 用法: ./merge-agents.sh 分支前缀 set -e BRANCH_PREFIX${1:-feature-agent} CURRENT_BRANCH$(git rev-parse --abbrev-ref HEAD) echo 当前分支: $CURRENT_BRANCH echo 准备合并前缀为 $BRANCH_PREFIX 的所有分支 # 检查工作区是否干净 if [ -n $(git status --porcelain) ]; then echo 错误当前工作区有未提交的改动请先处理 exit 1 fi # 获取所有匹配的分支 BRANCHES$(git branch --list ${BRANCH_PREFIX}-* | sed s/^[* ]*//) if [ -z $BRANCHES ]; then echo 没有找到匹配的分支 exit 0 fi for BRANCH in $BRANCHES; do echo ---------------------------------------- echo 正在合并: $BRANCH # 检查分支是否有新提交 COMMIT_COUNT$(git rev-list --count $CURRENT_BRANCH..$BRANCH) if [ $COMMIT_COUNT -eq 0 ]; then echo [跳过] $BRANCH 没有新提交 continue fi echo 该分支有 $COMMIT_COUNT 个新提交 # 压缩合并 if git merge --squash $BRANCH; then git commit -m merge: 合并 $BRANCH 的改动$COMMIT_COUNT 个提交 echo [完成] $BRANCH 已合并 else echo [冲突] $BRANCH 合并时产生冲突请手动处理 echo 冲突文件 git diff --name-only --diff-filterU exit 1 fi done echo ---------------------------------------- echo 全部合并完成 git log --oneline -10这个脚本的核心逻辑是先检查工作区干净再遍历分支用git rev-list --count判断分支是否有新提交避免合并空分支然后用--squash压缩合并。如果遇到冲突脚本会列出冲突文件并退出让你手动处理而不是强行继续。最后打印最近 10 条提交日志方便确认合并结果。4. 常见问题排查与实战避坑经验这一章是我在实际使用中踩过的坑和总结的排查方法。很多问题在官方文档里不会写但实际跑起来一定会遇到。4.1 worktree 创建失败的典型原因最常见的报错是fatal: xxx is already checked out at yyy。这说明你要检出的分支已经被另一个 worktree 占用了。解决办法是换一个分支名或者先删除占用该分支的 worktree。用git worktree list可以快速定位是哪个目录占用了分支。另一个常见问题是路径已存在。如果目标目录非空git worktree add会拒绝创建。这时候要么换个目录名要么先清空目标目录。我建议在脚本里加一个if [ -d $WORKTREE_DIR ]的判断存在就跳过避免误删数据。还有一种情况是.git文件损坏。worktree 目录里有一个.git文件不是目录它指向主仓库的.git/worktrees/下的元数据。如果这个文件被误删或内容被改worktree 就会失效。修复方法是删除该 worktree 目录重新用git worktree add创建。4.2 Agent 在错误目录执行命令的排查Agent 有时候会“迷路”在主工作区而不是自己的 worktree 里执行命令。这种情况通常是因为 Agent 的上下文里没有明确当前工作目录或者它自己cd到了别的地方。排查方法是在每个 Agent 的任务描述开头强制加上cd /path/to/worktree并在脚本里用pwd打印当前目录确认。我还会在 worktree 目录里放一个.agent-context文件写明“你当前在 Agent A 的工作区分支是 feature-agent-a只修改本目录下的文件”。Agent 读取这个文件后行为会稳定很多。这个技巧看起来简单但实测能减少大量“改错目录”的问题。4.3 合并时的隐性冲突与代码审查要点有些冲突 Git 检测不到但逻辑上是矛盾的。比如 Agent A 把某个函数的参数从两个改成三个Agent B 在另一个文件里调用这个函数时还是传两个参数。Git 合并时不会报冲突但代码跑起来就崩了。这类问题只能靠测试和代码审查发现。我的做法是合并后立即跑一遍完整测试套件包括单元测试和集成测试。如果测试覆盖不够就手动检查所有跨文件的接口调用。另外合并前用git diff main...feature-agent-a查看 Agent 的完整改动重点关注函数签名、配置项、数据库 schema 这类“契约”层面的变化。4.4 常见问题速查表问题现象可能原因解决方法fatal: branch is already checked out分支已被其他 worktree 占用换分支名或删除占用 worktreeworktree 目录创建失败目标路径已存在且非空换目录名或清空目标目录Agent 改错目录Agent 上下文缺少工作目录信息任务描述强制cd放置.agent-context文件合并后代码运行报错隐性接口冲突合并后跑完整测试检查函数签名和配置git worktree list显示异常.git文件损坏删除 worktree 目录重新创建合并时大量冲突分支存活太久分叉严重提高合并频率按文件边界分配任务4.5 性能与资源占用的实测数据我在一个约 200MB 的仓库上做了对比测试。用git clone创建三个副本总磁盘占用约 600MB每个副本首次拉取耗时约 15 秒。用 worktree 创建三个工作区总磁盘占用约 220MB只多了工作区文件创建耗时不到 2 秒。这个差距在仓库越大时越明显。内存方面worktree 本身不额外占用内存Agent 进程的内存消耗取决于模型和任务复杂度。CPU 方面多个 Agent 同时跑会有竞争但 worktree 的文件隔离减少了锁竞争整体吞吐比共享目录高不少。我实测三个 Agent 并行时worktree 方案的任务完成时间比共享目录方案快约 30%主要省在冲突排查和重试上。注意worktree 虽然省磁盘但每个工作区的node_modules、venv这类依赖目录是独立的。如果项目依赖很大三个 worktree 就是三份依赖。解决办法是用符号链接共享依赖目录或者用 pnpm 这类支持全局缓存的包管理器。5. 脚本化落地与持续集成衔接把前面的零散操作串成一套可重复执行的流程才算真正落地。这一章讲怎么把 worktree 管理脚本化以及怎么跟 CI 流程衔接。5.1 一键创建与清理脚本的整合我把创建和清理逻辑整合到一个脚本里用子命令区分操作#!/bin/bash # worktree-manager.sh # 用法: ./worktree-manager.sh create|clean|list [参数] set -e REPO_ROOT$(git rev-parse --show-toplevel) REPO_NAME$(basename $REPO_ROOT) PARENT_DIR$(dirname $REPO_ROOT) case $1 in create) COUNT${2:-3} PREFIX${3:-feature-agent} for i in $(seq 1 $COUNT); do ID$(printf %02d $i) DIR${PARENT_DIR}/${REPO_NAME}-agent-${ID} BRANCH${PREFIX}-${ID} if [ -d $DIR ]; then echo [跳过] $DIR 已存在 continue fi git worktree add $DIR -b $BRANCH main echo [创建] $DIR - $BRANCH done ;; clean) git worktree list --porcelain | grep ^worktree | awk {print $2} | while read -r wt; do if [ $wt ! $REPO_ROOT ]; then echo [删除] $wt git worktree remove $wt --force fi done git worktree prune echo 清理完成 ;; list) git worktree list ;; *) echo 用法: $0 create|clean|list [参数] exit 1 ;; esacclean子命令用git worktree list --porcelain获取所有 worktree 路径跳过主工作区逐个用git worktree remove --force删除最后git worktree prune清理元数据。--force是为了处理有未提交改动的 worktree但这也意味着会丢失未提交的改动所以我在实际使用时会先确认没有重要改动。5.2 与 CI 流程的衔接方式CI 环境里通常不需要 worktree因为 CI 本身就是一次性的。但如果你的 CI 要跑多个 Agent 的代码可以用 worktree 在同一个 CI job 里并行测试多个分支。具体做法是CI 拉取主仓库后用脚本创建 worktree分别 checkout 各个 Agent 分支然后并行跑测试。这样比开多个 CI job 省资源也比串行测试快。另一个衔接点是合并后的验证。Agent 分支合并到主分支后CI 自动触发完整测试。如果测试失败可以用git revert回滚合并提交或者用git reset --hard回到合并前的状态。我建议用git revert因为它保留了历史记录方便追溯是哪个 Agent 的改动导致了问题。5.3 日志记录与可追溯性设计多 Agent 并行时出问题后最难的是定位“是谁改的”。我的做法是每个 Agent 的提交都带上 Agent 标识比如[agent-a] feat: 添加用户查询接口。合并时用--squash会丢失单个提交的信息所以我在合并提交的 message 里写明来源分支和提交数量。另外脚本执行时把关键操作写入日志文件比如worktree-manager.log记录创建时间、目录、分支、操作结果。这样出问题时翻日志就能还原整个过程。5.4 扩展思路从 worktree 到多机隔离worktree 解决的是单机多 Agent 的隔离问题。如果 Agent 分布在多台机器上worktree 就不适用了需要用远程分支加 CI 的方式。每台机器 clone 仓库Agent 在各自机器上工作通过 push 远程分支来汇总。这种方式隔离更彻底但网络开销和合并复杂度更高。我的建议是单机场景优先用 worktree多机场景再考虑远程分支方案不要为了“看起来高级”而过度设计。最后分享一个我在实际使用中总结的小技巧给每个 worktree 目录放一个README-agent.md写明这个工作区的用途、当前任务、负责人哪个 Agent、以及合并状态。这个文件不提交到 Git只是本地参考。当你有五六个 worktree 时这个文件能帮你快速回忆每个目录在干嘛省去翻分支列表的时间。
