AI 实战文档

Appearance

多 Agent 协作与冲突治理 ​

当你让多个 AI Agent 同时开发时，冲突不是偶发事件，而是默认风险。 要稳定协作，核心不是“让 Agent 更聪明”，而是把协作流程工程化。

一句话原则 ​

  1. 一 Agent 一分支 一 worktree。
  2. 先锁文件，再改代码。
  3. 先定契约，再并行实现。
  4. 小步提交，高频同步，队列合并。

为什么会冲突 ​

  1. 文本冲突：多个 Agent 同时改同一文件或同一区块。
  2. 语义冲突：接口签名没冲突，但行为不兼容。
  3. 节奏冲突：分支长期不同步，最后一次性合并爆炸。

推荐协作模型 ​

1. 隔离执行面 ​

  • 每个 Agent 使用独立 git worktree，避免同目录互踩。
  • 每个 Agent 使用独立分支，禁止共享开发分支。
bash
git worktree add ../repo-wt-agent-a -b agent/agent-a/feature-x
git worktree add ../repo-wt-agent-b -b agent/agent-b/feature-y

2. 显式所有权 ​

  • 在任务开始前登记“改哪些路径”。
  • 路径锁存在冲突时，后来的任务必须等待或改方案。
  • 文件 owner 负责第一优先级冲突处理。

3. 契约先行 ​

  • 共享 API、类型、事件、数据结构先单独提交。
  • 其它 Agent 只基于已合并契约开发。
  • 契约升级采用向后兼容或显式版本化。

4. 严格门禁 ​

  • 合并前必须通过 build/lint/typecheck/tests。
  • 建议开启 merge queue，串行入主干。
  • 每个 PR 都基于最新主干重放 CI。

最小可落地流程 ​

  1. 拆任务：按模块边界拆，不按“页面/需求描述”粗拆。
  2. 分配 owner：任务、分支、worktree 一一对应。
  3. 登记文件锁：更新锁表，防止抢改。
  4. 开发同步：每天至少一次 fetch + rebase。
  5. 交接复核：提交交接单 + PR 检查清单。
  6. 队列合并：合并后释放锁并更新任务状态。

实操模板（本仓库） ​

这个仓库已经提供可直接复用的模板：

  • multi-agent/agent-board.md
  • multi-agent/file-locks.yaml
  • multi-agent/handoff-template.md
  • multi-agent/pr-checklist.md
  • scripts/worktree-agent.sh

使用示例：

bash
./scripts/worktree-agent.sh add agent-a agent/agent-a/docs-update
./scripts/worktree-agent.sh list
./scripts/worktree-agent.sh remove agent-a

常见误区 ​

  1. 让多个 Agent 共享一个分支。
  2. 没有文件锁，靠“口头约定”避免冲突。
  3. 大 PR 一次性合并，缺少中间验证。
  4. 只关注代码冲突，不关注契约和行为冲突。

结论 ​

多 Agent 协作的关键是“流程约束 + 自动化门禁 + 小步快跑”。 Agent 的能力决定上限，协作机制决定稳定性下限。