Agent Teams的“写作用域只是提示不是锁”，重叠只报warning、不阻止写入，并发必须靠用户按目录手动切分——当框架明知并发写会冲突、却只给一个warning时，“按目录切分”这个纪律到底该由用户来执行，还是应该有一个更强的强制机制？

从软约束到强隔离：多智能体并发写入的冲突治理路径

目录

一、导语：一个 warning 背后的责任转移

在多智能体（Multi-Agent）工程实践中，一个反复出现的现象是：框架提供了“写作用域（write scope）”的声明能力，允许每个 agent 声明自己将要修改的目录或文件集合；当两个 agent 的作用域发生重叠时，框架打印一条 warning，然后继续放行。写入照常发生，冲突是否真正造成损坏，取决于两个 agent 的实际执行时序与写入粒度。表面上看，这是一种“宽容”的设计；实质上，它把并发正确性的证明责任，从框架转移给了使用者。

这种责任转移并非孤例。在版本控制、分布式数据库、协作编辑等领域，都曾经历过“先给提示、后加强制”的演进。区别在于，那些领域最终都收敛到了明确的隔离级别（isolation level）语义，而当前多数 Agent Teams 框架仍停留在“提示级”。笔者认为，问题的关键不在于“要不要 warning”，而在于框架是否向用户明示了它所提供的隔离级别，以及在该级别下用户必须承担哪些不变量（invariant）的维护责任。缺少这层明示，warning 就会退化为一种心理安慰。

核心判断：warning-only 不是“弱一点的锁”，而是“没有锁”。它改变的是信息可见性，不改变并发语义。把“按目录切分”当作纪律交给用户，等于要求用户在没有强制校验的前提下，自行证明一个分布式系统的互斥性。

二、背景与问题定义：写作用域到底是什么

2.1 形式化定义

设一次 agent 执行会话为 s，其写作用域 W(s) 是文件系统路径集合的一个子集。若两个并发会话 s1、s2 满足 W(s1) ∩ W(s2) ≠ ∅，则称二者存在作用域重叠。框架在检测到重叠时输出 warning，但不对写入操作施加任何阻塞、排队或版本校验。用并发控制的术语说，这相当于声明了一个“无隔离（no isolation）”级别，同时附带一个“重叠检测器”。

需要区分三个容易混淆的概念：声明（declaration）是 agent 对自身意图的描述；检测（detection）是框架对声明之间关系的计算；强制（enforcement）是框架对违反声明行为的拦截。warning-only 只完成了前两步，第三步缺失。本文评述：这三步的分离是合理的工程分层，但把第三步完全省略，等于让声明失去约束力，退化为文档注释。

2.2 为什么框架倾向于 warning-only

从框架设计者的视角，warning-only 有几项现实吸引力：其一，实现成本低，不需要维护锁表、版本向量或事务日志；其二，不引入死锁风险，因为根本没有阻塞；其三，对 agent 的自主性干扰最小，符合“让模型自己决定”的设计哲学；其四，在单 agent 或低并发场景下，强制机制的收益接近于零，却会带来可观测的延迟。

但这些理由都建立在“并发度低、冲突概率小”的隐含假设上。一旦 agent 数量上升、任务粒度变细、共享目录增多，冲突概率会以组合方式增长。更麻烦的是，冲突的后果往往不是立即报错，而是静默的数据损坏——这类故障的定位成本远高于一次显式的写入拒绝。

三、原理剖析：warning-only 为何必然失效

3.1 三类典型竞态

在文件系统层面，agent 的写入通常表现为“读—改—写”序列。当两个会话对同一文件并发执行该序列时，会产生三类问题。第一类是丢失更新（lost update）：两个会话都基于旧版本计算新内容，后写者覆盖先写者，先写者的修改永久丢失。第二类是脏读（dirty read）：一个会话读取到另一个会话尚未完成、后续可能被回滚的中间状态。第三类是写偏斜（write skew）：两个会话各自读取一致快照、分别写入不同文件，但合并后的全局状态违反某个约束。

warning 对这三类问题均无抑制作用。它只在“重叠被检测到”的时刻发出提示，而重叠检测通常基于声明，不基于实际访问。若 agent 的实际写入超出其声明范围（这在 LLM 驱动的 agent 中并不罕见），warning 甚至不会触发。本文评述：基于声明的检测与基于实际访问的检测之间存在系统性偏差，前者只能覆盖“诚实的声明者”，无法覆盖“越界者”，而后者的实现需要文件系统钩子或沙箱级拦截。

3.2 时间窗口与检测盲区

即便声明准确，warning 的时序也构成盲区。假设 s1 在 t0 声明作用域，s2 在 t1 声明作用域，框架在 t1 检测到重叠并告警。但 s1 的实际写入可能发生在 t2 > t1，此时 warning 已经发出，用户未必在场，写入照常进行。换言之，warning 是一个“异步通知”，而冲突是一个“同步事件”，二者在时间轴上不对齐。

t0  s1 声明 W(s1) = {src/a}
t1  s2 声明 W(s2) = {src/a}   --> 框架输出 warning
t2  s1 读取 src/a 版本 v1
t3  s2 读取 src/a 版本 v1
t4  s1 写入 src/a 版本 v2
t5  s2 写入 src/a 版本 v3   --> v2 被覆盖，丢失更新

上例中，warning 在 t1 发出，但真正的损坏发生在 t5。若用户在 t1 与 t5 之间没有介入，warning 就没有起到任何保护作用。笔者认为，这正是“提示不是锁”的精确含义：提示作用于人的注意力，锁作用于操作的可执行性，二者不可互相替代。

3.3 目录切分纪律的脆弱性

“按目录切分”要求用户为每个 agent 分配互不相交的目录。该纪律在理想条件下有效，但存在三个脆弱点。其一，共享文件不可避免：配置文件、依赖清单、锁文件、路由注册表、类型定义聚合文件等，天然是多方写入点。其二，目录边界与逻辑边界不一致：一个功能改动可能横跨多个目录，强行切分会破坏内聚性。其三，纪律依赖人的记忆与一致性，无法被机器校验，随着团队规模扩大必然衰减。

本文评述：把纪律交给用户并非不可，但前提是框架提供了“可校验的纪律”。例如，框架可以在写入时校验路径是否落在声明范围内，越界即拒绝。这种“声明即约束”的设计，成本远低于完整的事务机制，却能消除大部分越界写入。当前多数框架连这一层都未实现，才是问题的症结。

四、强制机制的技术路线与代价对比

4.1 四类可选机制

从弱到强，可选的强制机制大致有四类。第一类是声明校验（scope enforcement）：写入前校验路径是否在声明集合内，越界拒绝。第二类是文件锁（file locking）：对写入路径加排他锁，冲突时阻塞或快速失败。第三类是乐观并发控制（optimistic concurrency control）：写入时携带版本号，版本不匹配则拒绝并重试。第四类是事务性工作区与合并（transactional workspace / merge）：每个 agent 在独立工作区写入，最后做三方合并或 CRDT 合并。

4.2 机制选择的判据

选择机制不应追求“最强”，而应匹配冲突的代价分布。若冲突后果是“重新跑一遍”，乐观并发即可；若后果是“静默损坏且难以发现”，则需要更强的隔离。一个实用的判据是：当检测到冲突的成本高于阻止冲突的成本时，应选择阻止。在 agent 场景中，一次静默损坏的定位往往需要人工比对大量 diff，成本极高，因此倾向于更强的机制。

本文评述：声明校验是性价比最高的一层，因为它不需要维护全局锁状态，只需在写入路径上做一次集合成员判断。它无法解决“两个合法声明者写同一文件”的问题，但能消除“越界写入”这一大类故障。建议将其作为任何 Agent Teams 框架的最低配置。

五、关键数据与工程案例

5.1 冲突概率的量化直觉

冲突概率与 agent 数量、共享文件占比、任务时长正相关。设共享文件占比为 p，并发 agent 数为 n，在随机访问模型下，至少一对 agent 访问同一共享文件的概率近似为 1 − (1 − p)^{n(n−1)/2}。当 p = 0.05、n = 5 时，该概率约为 1 − 0.95^{10} ≈ 40%。这是一个模拟估算，用于说明量级，不代表任何具体框架的实测值。它表明：即便共享文件只占 5%，5 个 agent 并发时冲突也并非小概率事件。

需要强调，上述模型假设随机访问，实际访问具有局部性，冲突概率会偏离该估算。但其结论方向是稳健的：冲突概率随并发度呈组合增长，而非线性增长。这解释了为何“低并发时 warning 够用”的经验，在规模扩大后会突然失效。

5.2 一个可复现的故障模式

考虑两个 agent 分别负责“新增接口”和“重构接口”。二者都声明作用域包含 src/api/。框架输出 warning，但两者继续执行。agent A 在 src/api/routes.ts 追加路由，agent B 重写同一文件以调整导出结构。由于 B 基于旧版本重写，A 追加的路由被覆盖。构建仍然通过，测试可能通过（若未覆盖新路由），故障在运行时才暴露。

# 伪代码：声明校验的最小实现
def write(path, content, declared_scopes):
    if not any(is_within(path, s) for s in declared_scopes):
        raise ScopeViolation(path)
    # 可选：版本校验
    current = read_version(path)
    if expected_version is not None and current != expected_version:
        raise VersionConflict(path, current, expected_version)
    atomic_write(path, content)

这段伪代码展示了声明校验与版本校验的组合。前者拦截越界，后者拦截丢失更新。二者叠加，即可覆盖大部分高频故障，而无需引入完整的锁管理器。笔者认为，这种“轻量强制”是当前框架最应优先补齐的能力。

5.3 拓展阅读

关于并发控制的理论基础，可参考 乐观并发控制 与 事务隔离级别 的综述；关于协作编辑中的合并算法，可参考 CRDT 词条；关于文件锁的工程实践，可参考 File locking。这些资料提供了本文所用概念的原始定义，本文的评述部分为独立思辨，不代表上述来源观点。

六、落地路径：从纪律到机制的分阶段方案

6.1 阶段一：让声明可校验

第一步不是上锁，而是让“声明”变成“约束”。具体做法：在 agent 的写入工具层（tool layer）注入路径校验，任何写入路径必须落在其声明集合内，否则拒绝并返回明确错误。这一步的实现成本低，且能立即消除越界写入。操作要点包括：声明集合应支持前缀匹配与通配符；校验应发生在实际落盘之前；错误信息应包含越界路径与声明集合，便于 agent 自我纠正。

6.2 阶段二：引入版本校验

第二步是在写入时携带读取时的版本标识（如文件内容哈希或 mtime+size），版本不匹配则拒绝。这解决了丢失更新问题，且不需要全局锁。操作要点：版本标识应在读取时捕获并随写入请求传递；冲突时应返回当前版本，供 agent 重新读取后重试；重试应有次数上限，避免活锁。

6.3 阶段三：按需引入工作区隔离

对于长任务或高并发场景，可为每个 agent 分配独立工作区（如 git worktree 或临时目录），任务结束后做合并。合并策略可选三方合并或按文件归属规则自动合并。操作要点：工作区创建与回收需自动化；合并冲突应显式暴露给用户，而非静默选择一方；合并前应运行测试，确保语义正确。

操作清单：① 声明集合规范化；② 写入前路径校验；③ 读取时捕获版本；④ 写入时版本比对；⑤ 冲突返回可重试错误；⑥ 重试上限与退避；⑦ 长任务工作区隔离；⑧ 合并冲突显式暴露；⑨ 冲突率与重试率埋点；⑩ 定期审计越界写入日志。

6.4 度量与验证

机制是否有效，需要可观测指标。建议埋点三类数据：越界写入拒绝次数、版本冲突次数、合并冲突次数。三者的比例可反映机制是否过强或过弱。若越界拒绝频繁，说明声明划分不合理；若版本冲突频繁，说明共享写入点过多，应考虑工作区隔离；若合并冲突频繁，说明任务切分粒度过粗。本文评述：没有度量的强制机制容易走向两个极端——要么形同虚设，要么过度阻塞。埋点是避免这两端的必要手段。

七、局限、反例与边界条件

强制机制并非没有代价。文件锁在长任务中会显著降低并发度，且存在死锁风险；乐观并发在高冲突场景下会导致大量重试，浪费模型调用；工作区隔离会引入合并成本，且合并本身可能出错。因此，“越强越好”是错误直觉。正确的做法是按冲突后果分级：后果可逆、可重跑的，用弱机制；后果不可逆、难发现的，用强机制。

另一个反例是“单 agent 场景”。当只有一个 agent 时，任何强制机制都是纯开销。因此机制应可配置、可降级，而非硬编码。本文评述：框架的责任不是替用户做选择，而是把选择显式化——提供隔离级别选项，并明确每个级别下用户需承担的不变量。warning-only 的问题不在于它弱，而在于它没有声明自己弱。

边界条件还包括：跨仓库写入、符号链接、大小写不敏感文件系统、网络文件系统的一致性延迟。这些场景下，路径校验与版本校验都可能失效，需要额外的规范化与一致性处理。工程上应在文档中明确这些边界，避免用户误以为机制覆盖了所有情况。

八、结论与展望

回到最初的问题：“按目录切分”的纪律该由用户执行，还是应有更强的强制机制？本文的结论是：二者不是二选一，而是分层。用户负责任务切分与声明划分，这是语义层面的决策，机器难以替代；框架负责声明的可校验性与冲突的显式化，这是机制层面的保障，不应转嫁给用户。warning-only 把两层混为一谈，用提示替代了保障，这才是问题所在。

展望未来，Agent Teams 的并发治理大概率会沿两条线演进：一是隔离级别的显式化，框架提供从“无隔离”到“事务工作区”的档位，并文档化每档的不变量；二是冲突的语义化，框架不仅检测路径重叠，还能理解“这两个写入是否语义冲突”，从而减少误报。后者依赖对代码结构的理解，是更具挑战性的方向。笔者认为，在语义化冲突检测成熟之前，声明校验加版本校验的组合，是性价比最高的现实选择。

九、主要参考文献