文章目录第一章 飞领地到底在指什么并行 Agent 的“修改范围”为什么守不住1.1 一个 Agent 的“领地”由什么构成不只是它正在编辑的那几个文件1.2 三种典型的飞领地现场每一类都不会在运行时主动报错1.3 并行 Agent 的收益和飞领地风险共享同一套成本结构第二章 为什么“各跑各的”在代码任务上失效2.1 代码库不是独立文件的集合是一个带隐式状态图的共享对象2.2 隔离解决了编辑时的打架但把冲突推到了合并时——而合并时的信息已经丢失了2.3 语义级冲突比文本级冲突更值得防但 Git 只看得懂行第三章 把飞领地关进笼子四层防御的落地方式3.1 第一层工作区隔离做对关键不是“有 worktree”而是 worktree 和任务的绑定方式3.2 第二层文件锁和语义锁解决不同粒度的问题不能互相替代3.3 第三层把“写时检测”提前到 merge 之前而不是相信 Agent 会在提交时自觉3.4 第四层合并策略要从“谁先完成谁先合”改成“谁的影响面小谁先合”第四章 一套可以直接落地的配置清单和排错顺序4.1 启动并行 Agent 之前先做的三件事4.2 已经发生飞领地时的排查顺序先查提交边界再查语义假设4.3 哪些场景不值得上重型协调哪些场景必须上你正在同时跑三个 AI Coding Agent一个改后端接口一个补单元测试一个重构前端组件。十分钟后你回来一看——测试 Agent 顺手“优化”了接口文件里的一个 import后端 Agent 的未提交改动被git commit --amend卷进了前端的提交里审计日志对不上但没有任何一行代码报错。这不是某个框架的 bug。这是一个结构性问题并行 Agent 在共享工作区里天然缺乏对彼此“修改范围”的全局感知。我用一个词来指代这种越界行为——飞领地。一个 Agent 飞进了另一个 Agent 正在修改的范围覆盖、污染或吞并了对方的工作而整个过程可以是静默的。第一章 飞领地到底在指什么并行 Agent 的“修改范围”为什么守不住1.1 一个 Agent 的“领地”由什么构成不只是它正在编辑的那几个文件如果把“领地”窄化成“当前打开的文件”飞领地问题会被严重低估。一个 Agent 在修改代码时它的实际影响范围至少包含三层直接修改层它显式写入的文件和代码块。这是最容易看见的一层也是大多数人以为“只要不碰同一个文件就安全”的那一层。爆炸半径层它修改的函数或模块所影响到的传递调用链。Agent A 改了parseRequest()的输入格式Agent B 正在基于旧的输入格式修改validateSchema()——两者没有碰同一个文件但 A 的改动让 B 的全部假设失效了。共享不变量层两个 Agent 在看似无关的模块里各自维护着同一条隐式约定。比如一个 Agent 在enqueue里加了延迟逻辑另一个 Agent 在dequeue里依赖原来的 FIFO 时序——单看每一处改动都“局部正确”合在一起却破坏了系统级保证。飞领地之所以隐蔽正是因为大多数人只防住了第一层。文件不重叠不等于修改范围不重叠。AI21 的工程团队在把并行 Agent 从只读任务推进到写代码时得到的结论更直白Agents that only read can share an environment. Agents that write need isolation。读任务可以共享沙箱写任务不能。1.2 三种典型的飞领地现场每一类都不会在运行时主动报错第一种直接覆盖。两个 Agent 在同一个工作区里各自读取文件、修改、写回后写入的版本把先写入的覆盖掉。Agent-Nexus 的文档把这个场景描述得很精确多个并发 Agent 会话“缺乏全局感知”同时修改同一文件导致代码覆盖而没有任何一方收到“你覆盖了别人的工作”的信号。Git 合并冲突至少会在合并时炸出来共享工作区里的覆盖是静默的。第二种WIP 卷带。这是一个比直接覆盖更隐蔽的变体。Agent A 正在某个文件里做未提交的修改Agent B 执行了git add或git commit --amend把 A 的未提交工作一起卷进了自己的提交里。在一个真实的并行 review-resolver 案例中Agent C 运行git commit --amend后把 Agent B 的未提交改动AGENTS.md和 runbook收进了自己的提交消息之下Agent B 随后报告了一个“幽灵 commit SHA”因为它的改动已经被别人的 amend 吸收了那个 SHA 从未存在过。代码没有丢失但归属关系和审计链路已经失真了。第三种语义冲突延后爆炸。两个 Agent 在各自的隔离环境里独立决策直到合并时才第一次“见面”。Git 在文本层面能捕获行级冲突但如果 A 修改了parseRequest的行为、B 修改了调用它的validateSchema的假设两边的 diff 可能完全“干净”合并自动通过而系统在运行时崩溃。OpenHands 的工程讨论把这类冲突拆成三种直接重叠、爆炸半径重叠、共享不变量重叠并指出 Git 的文本级检测对后两者基本无能为力。1.3 并行 Agent 的收益和飞领地风险共享同一套成本结构并行 Agent 的吸引力在于时间折叠N 个独立子任务理论上可以在最慢那个任务的时间内完成而不是各自耗时之和。但这个收益有一个隐含前提子任务之间的修改范围真正不相交。一旦发生飞领地收益会被反向吃掉。恢复成本包括定位哪次提交属于谁、从错误的提交里剥离别人的改动、重新跑已经被污染状态下的测试、以及最昂贵的——当 Agent 已经基于一个被侵入的代码状态继续推理了几十步之后你不知道它后续的哪些决策建立在错误的前提上。STORM 论文的作者把这个问题总结为工作区隔离把冲突解决推迟到了合并阶段而到了那时“恢复是昂贵的”。所以飞领地不是一个“偶发的协作小摩擦”。它是并行写任务在缺少修改范围治理时的一种默认结局。第二章 为什么“各跑各的”在代码任务上失效2.1 代码库不是独立文件的集合是一个带隐式状态图的共享对象多 Agent 在只读或广度探索任务上表现出色查资料、搜多个来源、独立分析不同竞品这些子任务天然可切片彼此不依赖中间状态。但代码编辑是完全不同的物种。代码编辑高度共享状态改了 A 文件会影响 import B 文件的一致性改了接口签名会让一处测试全部失效一个 Agent 引入的类型变化会沿着调用图传播到它从未打开过的模块。把代码库切成“你的文件”和“我的文件”是一种幻觉。文件系统层面的分区无法切断语义层面的依赖。这也是为什么“给每个 Agent 分配不同目录”这种朴素做法在很多真实项目里不够用微服务仓库里共享的go.mod、monorepo 里根级的 tsconfig、跨模块的类型定义都不属于任何一个“功能分区”但每一个 Agent 的改动都可能触碰它们。2.2 隔离解决了编辑时的打架但把冲突推到了合并时——而合并时的信息已经丢失了git worktree是目前最主流的隔离手段。每个 Agent 获得独立的工作目录和独立分支文件层面完全隔离一个 Agent 的未提交编辑对另一个 Agent 不可见index 锁也不再争用。SwarmGit 等项目把这件事做到了极致一条命令自动拆分任务、为每个 Agent 创建 worktree、并行启动、完成后合并回主干。但隔离有一个结构性代价它只阻止了“编辑时的物理碰撞”没有阻止“设计层面的分歧”。两个 Agent 在各自的 worktree 里基于同一份代码快照做出了互不兼容的设计选择——A 把鉴权逻辑抽成中间件B 在 handler 里直接写鉴权——两边的 diff 都是合法的worktree 隔离让它们在开发阶段完全看不见对方。合并时才会发现这两个设计不能共存。STORM 的论文把这个局限讲得很清楚工作区隔离将冲突解决“推迟到事后的合并步骤”而到了那时Agent 已经在各自的方向上“commit 了可能不兼容的设计”。换句话说git worktree让飞领地变得“不会在编辑时发生”但它并没有让飞领地“不会发生”。冲突只是换了一个更晚、更贵的时机浮出水面。2.3 语义级冲突比文本级冲突更值得防但 Git 只看得懂行Git 的冲突检测发生在文本层面两个分支是否修改了同一文件的相邻或相同行。这个机制对人工协作已经足够因为人类在提交之前通常知道自己动过什么。但并行 Agent 的工作方式是“读到什么就基于什么改”它没有一个稳定的、跨会话的“我动过哪些语义实体”的记忆。这就是claim_work_scope这类工具试图填补的缝隙。它不等待 Git 在合并时报文本冲突而是让 Agent 在动手写代码之前先声明“我打算修改哪些函数/模块”在一个共享的协调层里做集合运算直接重叠是简单的 set intersection爆炸半径重叠通过调用图做 2 层遍历来检测共享不变量重叠则查询一个“不变量索引”看两个 Agent 各自声明的范围是否共同覆盖了同一条隐式保证。检测发生在写第一行代码之前而不是合并时。当然语义级协调的代价是 Agent 必须被改造成“先声明再行动”的模式而且调用图和不变量索引本身需要基础设施。但在代码任务上在写入前多花一次声明成本通常远低于在合并后发现两个 Agent 已经沿着不兼容的方向走了很远。第三章 把飞领地关进笼子四层防御的落地方式3.1 第一层工作区隔离做对关键不是“有 worktree”而是 worktree 和任务的绑定方式git worktree本身只是命令真正的工程问题在于每个 worktree 是否与一个明确的、不可复用的任务标识绑定。一个常见的半成品做法是“手动给每个 Agent 开一个 worktree跑完再合并”。这种做法在 Agent 数量少、任务边界清晰时能用但一旦 Agent 数量上来worktree 目录会变成一堆没有归属的临时文件夹你无法从目录名判断哪个分支对应哪个任务也无法在 Agent 崩溃后知道哪个 worktree 可以安全清理。更可运维的模式是把 worktree 的生命周期挂在任务 ID 上。learn-claude-code 的实践方案是控制平面用.tasks/管理任务状态执行平面用.worktrees/存放每个任务的独立工作目录两边通过任务 ID 双向关联配合事件总线记录全生命周期。helloagents-x 的 worktree 隔离也采取类似逻辑只有在子 Agent 存在重叠文件写入时才自动创建 worktree只读任务不触发隔离避免为不需要隔离的工作付出不必要的合并成本。一个可以直接拿走的判断规则是如果两个子任务的产物需要在同一次 commit 或同一个 PR 里交付它们就不应该跑在同一个共享工作区里。反过来如果两个子任务只是各自产出 patch 提案、由中央整合者统一套用共享工作区或轻量协调层可能比完整 worktree 更合适。3.2 第二层文件锁和语义锁解决不同粒度的问题不能互相替代文件锁解决的是“两个 Agent 同时写同一个文件”的物理碰撞。它的实现可以很简单写之前获取 per-file 锁写完在finally里释放TTL 兜底孤儿锁。gitagent 的 per-file 锁默认 TTL 是 15 秒过期自动回收避免 Agent 崩溃后锁永久残留。Agent-Nexus 把锁的粒度做到了 File / Module / Symbol 三级并在PreToolUse阶段做毫秒级裁决无冲突放行并锁定有冲突则把后排 Agent 放入等待队列前排进程退出时立即唤醒。但文件锁管不住飞领地的后两层。两个 Agent 锁住了不同文件完全合法地并行写入但一个改了parseRequest的返回值、另一个在调用侧基于旧返回值写了新逻辑——文件锁对此一无所知。语义锁补的就是这个缺口。claim_work_scope的工作方式不是锁文件而是锁“意图作用域”Agent 在写入前声明它要碰的函数/模块 ID协调层返回safeScope没有冲突的子集和warnings非阻塞的爆炸半径提示冲突类型被明确分类为direct、blast_radius、shared_invariant。它的成本比文件锁高但在调用关系密集的代码库里省下的是合并时才发现设计撞车的返工时间。工程上的务实组合通常是物理层用 per-file 锁或 worktree 兜底语义层在关键模块鉴权、订单、支付、状态机上做写入前声明。不必对每一行代码都上语义锁但要对“改错了会连锁失效”的实体上锁。3.3 第三层把“写时检测”提前到 merge 之前而不是相信 Agent 会在提交时自觉并行 review-resolver 的那个案例提供了一个可以直接照搬的避坑点防止git commit --amend扫进其他 Agent 的未提交 WIP。该案例的恢复方案写得很具体resolver 的 prompt 应显式要求先执行git stash -u把不属于本次任务范围的未提交改动隔离出去再 staging 自己的文件。这个细节背后是一条更一般的规则Agent 的提交操作和 Agent 的修改范围必须是两个可以分开审计的对象。如果 Agent 可以自由地git add .或amend它就拥有了把自己领地之外的改动“合法化”进自己提交的权限而飞领地恰恰可以通过这种合法操作完成。对应的工程约束可以很轻量每个 Agent 的提交只允许包含它声明过的文件列表git add不接受通配符或目录级参数禁止--amend在并行会话中作为默认操作或者至少要求 amend 前先执行带-u的 stash提交完成后输出一份“本次提交涉及的文件清单”与任务声明的范围做比对不一致就标记为需要人工复核。这些约束不优雅也不“智能”但它们把飞领地从一个静默的、事后才发现的问题变成了一个在提交入口就能被拦截的可见异常。3.4 第四层合并策略要从“谁先完成谁先合”改成“谁的影响面小谁先合”并行 Agent 完成后合并顺序会显著影响冲突成本和最终结果。如果按完成时间合并一个影响面很大的 Agent 可能先落地后续所有小范围 Agent 的 diff 都要在它的新基线上重放。更稳的顺序是影响面小、与主线偏离少的改动先合影响面大、改变了共享假设的改动后合并在合并前强制重新跑全量验证。STORM 的思路在这里有参考价值它在写入时就维护每个 Agent 对共享工作区的“一致视图”冲突在写时被检测和解决而不是全部推到 merge 队列。如果你的系统做不到写时解决退一步的做法至少是合并队列里对每个分支计算“它修改的语义实体集合”与已合入但尚未稳定下来的改动做交集检查有交集就触发重跑而不是直接合并。另一个容易忽略的点是测试状态的归属。在共享工作区里Agent A 跑测试时读到的可能是 Agent B 正在中间修改的代码在 worktree 隔离下每个 Agent 的测试跑在自己的快照上结果可信得多但合并后仍然需要一次在合并后代码上执行的验证。并行案例中“测试是否被动过”和“是否刷绿”被列为一类独立的坑原因就在这里。每个 Agent 自己报告“测试通过”是不够的需要区分“在我的隔离环境里通过”和“在合并后的集成状态里通过”。第四章 一套可以直接落地的配置清单和排错顺序4.1 启动并行 Agent 之前先做的三件事第一给每个 Agent 写一个显式的“可写范围”声明而不是让它自己从任务描述里猜。范围声明的粒度按项目风险决定低风险脚本任务可以用目录级声明核心业务模块至少声明到文件级鉴权、支付、状态机这类共享不变量密集的区域声明到函数/符号级。OpenHands 的claim_work_scope把这件事工具化了但即使不用这个工具在 prompt 里要求 Agent 先输出“我计划修改的文件和函数列表”再动手就已经把飞领地概率压低了一截。第二确认 worktree 或隔离环境与任务是一一绑定的目录名或分支名中包含任务 ID崩溃后可以按 ID 定位和清理。只读子任务不强制 worktree写任务必须隔离。第三检查提交入口的约束是否有任何 Agent 可以执行git add .、git commit -a或git commit --amend而没有额外的范围校验。如果有先堵住。这是成本最低、收益最直接的一步。4.2 已经发生飞领地时的排查顺序先查提交边界再查语义假设当发现“某些改动归属不对”或“合并后行为异常”时不要一上来就 diff 整个代码库。按这个顺序缩小范围先查提交边界。运行git log --stat看每个提交是否包含了超出该 Agent 任务声明的文件。飞领地的典型痕迹是某个提交里出现了与 commit message 主题无关的文件或者某个 Agent 报告的 commit SHA 在 reflog 中对应不上。再查未提交 WIP 是否被扫走。如果使用了amend或add .检查git stash list和当时的会话日志确认是否有一个 Agent 的未提交工作被另一个 Agent 的提交吸收。最后查语义层。如果提交归属都正常但运行时行为不对用“两个 Agent 各自修改的实体集合”做交集它们有没有共同触及同一个调用链的上下游或者各自维护了同一条隐式约定的一半。这一步比读 diff 慢但它是唯一能抓到“文本干净、语义冲突”的方式。4.3 哪些场景不值得上重型协调哪些场景必须上不值得上语义锁和完整 worktree 编排的场景一次性脚本生成、独立的文档翻译、彼此没有 import 关系的模块草稿、只读代码审查。这些任务的修改范围天然不相交上重型协调的收益覆盖不了工具链和等待成本。Anthropic 自己的工程结论也指向同一个方向多 Agent 适合可并行、广度搜索、且价值足以覆盖数倍成本的场景不适合紧密共享 context 的任务。必须上隔离和写入前协调的场景多个 Agent 同时写同一个 monorepo任务涉及共享配置文件、依赖清单、数据库迁移子任务之间存在调用链或类型依赖任何“改错了会在运行时静默失败”而不是编译报错的模块。判断标准不是 Agent 的数量而是修改范围的语义重叠概率。两个 Agent 也可能需要完整 worktree 加语义声明五个 Agent 各自改五个互不 import 的独立脚本可能裸跑反而更快。飞领地不是某个框架的待修 bug而是并行写任务在缺少“修改范围治理”时的默认行为。隔离把碰撞从编辑时推到了合并时锁把碰撞从静默覆盖变成了显式等待语义声明把冲突从“代码写完之后”提前到了“动手之前”——每一层都不能消灭飞领地但每一层都在把它变得更早、更可见、更便宜。你在同时跑多个 Coding Agent 时遇到过最隐蔽的一次“领地侵入”是什么形态——文件被覆盖、WIP 被卷进别人的提交还是合并干净但运行时才炸欢迎留言交流。