多 Agent 协作：并行改不同文件与冲突处理
多智能体（Multi-Agent）并行能把「四个模块同时开工」压到一轮对话的时间里，但它只在一种前提下成立：每个智能体（Agent）的改动集合互不相交。这条边界一旦破了，省下的时间会在合并与调试阶段成倍还回去。
可行边界：文件级隔离
| 并行方式 | 是否可行 | 原因 |
|---|---|---|
| 每个 Agent 独占若干完整文件 | 可行 | 最稳，文本冲突概率接近零 |
| 每个 Agent 独占一个包或目录 | 可行 | 只要不跨包修改接口 |
| 每个 Agent 独占一层（实现/测试/文档） | 有条件可行 | 依赖接口已冻结 |
| 两个 Agent 改同一文件的不同函数 | 不可行 | 后写覆盖先写，版本控制救不了 |
| 两个 Agent 同时改接口与实现 | 不可行 | 语义耦合，自动合并会「合上但不对」 |
结论：并行单位是文件，不是函数、不是行、更不是「谁先想好谁先改」。
共享文件为什么必然冲突
- 接口与类型定义：所有实现都要引用，一处签名变更牵动全部并行方。
- 路由表、注册表、依赖注入容器：集中式清单，双方各加一行，位置还相邻。
- 配置与常量：枚举值、错误码、超时阈值，容易各自新增出冲突编号。
- 依赖清单与锁文件（lockfile）：几乎必然文本冲突，且合并后必须重新安装校验。
- 数据库迁移文件序号：两个 Agent 都写
0007_，文件本身不冲突，执行顺序却错了。 - 文档与变更日志（CHANGELOG）：都在同一位置追加。
比文本冲突更麻烦的是「合并成功但语义错误」：两个 Agent 都基于旧基线插入路由，顺序错了，编译期毫无提示，上线才暴露。
隔离手段
| 手段 | 怎么做 | 代价 |
|---|---|---|
| 文件集合预分配 | 开工前列出每个 Agent 的独占文件清单 | 需要一次人工盘点 |
| 分支（branch） | 每个 Agent 一条特性分支 | 仍需处理共享文件 |
| 工作树（git worktree） | 每个 Agent 一棵独立工作树，互不干扰 | 占磁盘，收工要清理 |
| 目录边界 | 按模块目录划分归属 | 跨模块需求不好切 |
| 任务队列 | 共享文件相关的改动排队串行执行 | 牺牲部分并行度 |
| 只读角色 | 调研型 Agent 不写文件 | 产出需人工转写 |
# 三个 Agent 各占一棵工作树
git worktree add ../wt-api -b feat/api-agent
git worktree add ../wt-worker -b feat/worker-agent
git worktree add ../wt-docs -b docs/readme-agent
git worktree list # 收工时确认没有遗漏
git worktree remove ../wt-docs
共享文件串行化：接口先行
- 由单人（或一个「地基」Agent）先改完共享文件：接口签名、类型、常量、路由占位、迁移序号。
- 冻结基线并打临时标签，把该提交作为所有并行 Agent 的共同起点。
- 并行 Agent 只改自己独占的文件；确需改共享文件时停下，提交变更请求而不是直接动手。
- 编排者按预定顺序合入，每合一个就跑一次编译与测试，绝不批量合。
冲突后的合并与验证流程
1. 立即冻结：双方停止继续写冲突文件，避免边合边改
2. 逐个合入：一次只合一个 Agent 的分支，不一次性 merge 两个
3. 手工判语义：接口签名、错误码、枚举值、默认值逐条对齐，不信自动合并
4. 重新生成：锁文件、代码生成产物、迁移汇总文件重跑生成命令
5. 验证：编译 + 全量测试 + 契约测试 + 真实启动一次进程
6. 回写：把冲突根因写进规则文件（AGENTS.md）的禁止项，避免重复踩
冲突高发点与预防
| 位置 | 预防做法 |
|---|---|
| 接口与类型定义 | 先冻结，变更走变更请求 |
| 路由与注册表 | 由地基步骤一次性加好占位 |
| 配置与常量 | 预分配编号区间，禁止各自递增 |
| 依赖清单与锁文件 | 只允许一个 Agent 改，合并后统一重装 |
| 数据库迁移序号 | 开工前分配好序号段 |
| 文档与变更日志 | 收尾阶段由单人统一撰写 |
分工切法
| 切法 | 适合场景 | 风险 |
|---|---|---|
| 按目录/模块 | 模块间依赖很弱 | 公共代码仍会撞车 |
| 按层（实现/测试/文档） | 接口已冻结 | 测试与实现口径不一致 |
| 按关注点（功能/性能/安全） | 审查类任务 | 同一文件被多方修改 |
| 实现 + 验证 | 高风险改动 | 需要额外的验证时间 |
独立验证者
验证型 Agent 只读、不改代码，职责是从零复现构建与测试、核对 diff 与说明是否一致、主动找未覆盖的边界与异常分支。写代码的 Agent 不能兼任验证者：同一份上下文会沿用自己的假设，看不出自己的错。
度量与复盘
- 关注四个数：冲突文件数、每个 Agent 的返工次数、合并窗口时长、集成后首次测试通过率。
- 冲突率上升说明共享文件划分不合理，而不是 Agent 不够聪明——先改划分方式，再谈模型。
- 每次冲突都在规则文件里留一条禁止项，两三轮之后并行冲突会显著减少。
小结：多 Agent 协作的收益来自文件级互斥，而不是并发数量。开工前冻结接口等共享文件、给每个 Agent 划定独占文件集合、用工作树与分支隔离现场，冲突后再按「冻结、逐个合入、手工判语义、重新生成、全量验证」的固定流程收尾，并行才真正省时间。