Agents · Conflict Resolution · 5 条冲突解决铁律
第一定律：当冲突出现时，停止 commit，先报 AIOS。继续 commit 只会让冲突指数级扩大。
1. 五条铁律（必须背下来）
铁律 1 · 仓库分区 = 第一道防线
任何冲突的根因要先问：有没有越权写入？ 看 Repository-Partition.md。
若有越权：revert 越权 commit，冲突 80% 自动消失。
铁律 2 · 协议契约 = 第二道防线
跨智能体接口分歧 → 查 ../contracts/protocol-v1.md。
若契约里写明：按契约执行，无需仲裁。
若契约里没写：升级到 ClaudeB 补契约 + 写 ADR。
铁律 3 · commit 串行 = 第三道防线
同一文件同一时刻只允许一个 commit。 冲突时：先 commit 者赢，后 commit 者 stash + 等待 + rebase。
铁律 4 · 决策升级链 = 仲裁顺序
每一级有最长等待时间（见 §3）。
铁律 5 · 资源隔离 = 端口/进程不打架
dev server 不抢端口 · 测试不抢数据库 · 备份不抢分支。
见 Repository-Partition.md §6 · 物理隔离（资源层）。
2. 冲突类型与对应铁律
| 冲突类型 | 适用铁律 | 处理时间 |
|---|---|---|
| 两 agent 改同一文件 | 1 + 3 | ≤ 30 分钟 |
| API 接口理解不一致 | 2 | ≤ 2 小时（含补契约） |
| 端口被占用 | 5 | ≤ 5 分钟 |
| 协议字段命名分歧 | 2 + 4 | ≤ 4 小时 |
| 业务方向分歧 | 4（直接到人类） | ≤ 1 个工作日 |
| 实现方案 A vs B 分歧 | 4 | ≤ 4 小时 |
3. 决策升级链（详解）
Level 1 · 智能体内部尝试和解（最长 30 分钟）
- 双方在 commit message 互相 ref：
[ack: ClaudeB's contract §3.2] - 若一方让步 → 直接收敛 · 不需要 ADR
Level 2 · AIOS 仲裁（最长 2 小时）
升级触发：
- 30 分钟未和解
- 任一方在 KANBAN 标 ESCALATE: <file/topic>
AIOS 仲裁产出： - 一句话决议（"按 ClaudeB 方案 A"） - 落地动作（"ClaudeA revert 并按 §3.2 重写"） - 是否需要 ADR（见 §4）
Level 3 · 人类拍板（最长 1 工作日）
升级触发： - AIOS 仲裁不下（双方理由都成立） - 涉及业务方向 / 钱 / 客户
人类回复格式（standup 时一句话）：
AIOS 收到后：写 ADR + 更新 KANBAN + 派落地任务。
Level 4 · ADR 永久写入（异步）
任何 Level ⅔ 的决议在 24 小时内必须写成 ADR-AIOS-NN.md，存入 ../ADR/。
4. ADR 触发条件
满足任一即必须写 ADR：
- ✅ 决议影响 ≥ 2 个智能体的工作流
- ✅ 决议改变了协议契约
- ✅ 决议放弃了原计划方案 ≥ 1 步
- ✅ 决议需要回滚已 commit 的代码 ≥ 100 行
- ✅ 人类直接拍板（任何级别）
不需要 ADR 的情况： - ❌ 单个智能体内部的实现细节选择 - ❌ 临时性的 hotfix（24h 内会被覆盖） - ❌ 重复出现的、模板化的小冲突
5. 仲裁模板（AIOS 用）
## ⚖️ AIOS 仲裁 · <冲突 topic> · YYYY-MM-DD HH:MM
### 当事方
- **A 方**：<agent> · 主张 <一句话>
- **B 方**：<agent> · 主张 <一句话>
### 事实
- 文件：<path>:<line>
- 已发生 commit：<hash list>
- 协议依据：<contract §X 或 "无契约支持">
### 分析
- A 方优势：<3 点>
- B 方优势：<3 点>
- 折中可能：<是/否>
### 决议
**按 <A/B/折中> 方案** · 理由：<2 句话>
### 落地动作
1. <agent> 在 <时间> 前完成 <动作>
2. <agent> revert <hash>
3. AIOS 写 ADR-AIOS-NN
### ADR 标志
- [ ] 需要 ADR（理由：<...>）
- [ ] 不需要 ADR（理由：单方实现细节）
6. 高频冲突案例库
案例 6.1 · store 命名分歧（ClaudeA vs ClaudeB contract）
症状：ClaudeA 写 useSlotStore，ClaudeB contract 写 useShellSlotStore。
铁律：2（契约优先） + 4
决议：按 contract 执行 · ClaudeA 改名 · 不写 ADR（属契约执行）
案例 6.2 · 端口冲突（5173 被占）
症状：ClaudeA vite dev 启动失败 "EADDRINUSE :5173" 铁律：5 决议：检查是不是 demo 还在跑（layout-demo），杀进程或换端口
案例 6.3 · contract 字段缺失
症状：ClaudeA 实施 phase 5，contract §5 没写 mode-switcher 信号
铁律：2（契约不全）
决议：升级 ClaudeB 补契约 §5 + 写 ADR-AIOS-NN
案例 6.4 · 业务方向分歧
症状：ClaudeB 想做"unsigned 模式"，ClaudeA 担心 phase 工期延长 铁律：4（升级人类） 决议：人类拍板 · 写 ADR
7. 反复出现的冲突 = 设计问题
如果同一类冲突在 1 周内出现 ≥ 3 次：问题不在冲突本身，在于规则缺失。
处理： 1. AIOS 把案例汇总到本文件 §6 2. 起草新的 contract 条款 / partition 规则 3. freeze 后通告所有智能体
8. 一句话总结
冲突不可怕，怕的是没有升级链。AIOS 提供 4 级升级 + ADR 永久存档，让每个分歧都有归宿。
| 版本 | 日期 | 变化 |
|---|---|---|
| v1.0 | 2026-05-19 | 5 条铁律 + 4 级升级链 |