# 多Agent协同

## 启用条件

### TeamCreate vs Task(subagent) 决策树

```
收到任务 → 评估规模
  │
  ├─ 涉及 ≥3 个独立文件/模块？ → TeamCreate
  ├─ 需要 ≥2 个并行工作流？   → TeamCreate
  ├─ 总步骤 >10 步？          → TeamCreate
  ├─ 魔尊明确要求并行/团队？   → TeamCreate
  │
  ├─ 单一探索/搜索任务？       → Task(subagent_type=Explore)
  ├─ 单文件独立操作？          → Task(subagent)
  └─ 简单查询/单步操作？       → 直接执行
```

**铁律**：当犹豫时，优先 TeamCreate。多 Agent 并行效率远高于串行 subagent。

## Codex 原生动作映射

| 协同动作 | Codex 工具 |
|---------|------------|
| 创建子任务 | `spawn_agent` |
| 下发/追问 | `send_input` |
| 等待完成 | `wait` |
| 长耗时任务 | `awaiter` agent |
| 代码探索 | `explorer` agent |
| 执行改动 | `worker` agent |
| 收尾回收 | `close_agent` |

执行顺序：锁文件 → 并行执行 → 审查修复 → 汇总 → 回收子 Agent。

### 决策矩阵

满足**任意 1 条**即启用 TeamCreate：

| 条件 | 说明 | 示例 |
|------|------|------|
| 多文件独立变更 | ≥3 个无交叉依赖的文件 | 6个新秘典各自独立 |
| 可并行子任务 | ≥2 个无数据依赖的工作流 | 前端+后端+文档 |
| 复杂度高 | 单Agent需 >10 步 | 全栈重构 |
| 时间紧迫 | 劫钟催命，需加速 | 紧急修复多服务 |

## 角色定义

| 角色 | 道语 | 职责 | 工具权限 |
|------|------|------|----------|
| 主修 (Lead) | 天罗主修 | 任务分解、进度追踪、结果汇总 | `spawn_agent/send_input/wait/close_agent` |
| 道侣 (Worker) | 天罗道侣 | 执行具体子任务、报告进度 | `worker` + Read/Write/Edit/Bash |
| 护法 (Reviewer) | 天罗护法 | 代码审查、质量校验、冲突检测 | `worker`(审查模式) + Read/Grep/Glob |
| 斥候 (Scout) | 天罗斥候 | 只读探索、依赖定位 | `explorer` + Read/Grep/Glob |

## 任务分解策略

### 按文件拆分（首选）
每个Agent负责独立的文件集合，零交叉：
```
Agent-A: [file1.md, file2.md]  — 互不干涉
Agent-B: [file3.md, file4.md]  — 互不干涉
Agent-C: [file5.md]            — 互不干涉
```

### 按模块拆分
每个Agent负责一个功能模块：
```
Agent-前端: src/components/
Agent-后端: src/api/
Agent-基础: src/lib/
```

### 按流水线拆分
串行依赖时，前一个Agent的输出是后一个的输入：
```
Agent-生成 → Agent-校验 → Agent-集成
```

## 并行vs串行决策

```
子任务A和B是否共享文件？
  ├─ 否 → 并行执行
  └─ 是 → 是否写同一文件？
       ├─ 否（一读一写）→ 先写后读，串行
       └─ 是（都写）→ 严格串行，或拆分文件区域
```

### 依赖矩阵示例

| | Task-A | Task-B | Task-C |
|---|--------|--------|--------|
| Task-A | - | 无依赖 | 无依赖 |
| Task-B | 无依赖 | - | B→C |
| Task-C | 无依赖 | B→C | - |

结论：A与B并行，C等B完成后执行。

## 通信协议

### SendMessage规范

| 类型 | 用途 | 格式 |
|------|------|------|
| message | 点对点通信 | `{type: "message", recipient: "agent-name", content: "...", summary: "5字摘要"}` |
| broadcast | 全体通知 | `{type: "broadcast", content: "...", summary: "5字摘要"}` |
| shutdown_request | 请求关闭 | `{type: "shutdown_request", recipient: "agent-name", content: "原因"}` |

### 通信时机

| 事件 | 发送者 | 接收者 | 内容 |
|------|--------|--------|------|
| 任务分配 | 主修 | 道侣 | 文件列表+要求 |
| 进度更新 | 道侣 | 主修 | 完成百分比+当前状态 |
| 任务完成 | 道侣 | 主修 | 文件清单+验证结果 |
| 遇阻报告 | 道侣 | 主修 | 阻塞原因+建议 |
| 汇总指令 | 主修 | 全体 | broadcast进入汇总阶段 |

## 文件锁定与冲突避免

### 黄金规则
```
每个文件在同一时刻只能被一个Agent修改。
违反此规则 = 道基裂痕+1。
```

### 锁定策略
1. **分配时锁定** — 主修分配任务时明确文件归属
2. **声明式锁定** — 道侣开始前声明要操作的文件
3. **冲突检测** — 主修检查文件分配无重叠后才启动

### 冲突解决

| 冲突类型 | 解决方案 |
|----------|----------|
| 两个Agent需写同一文件 | 串行执行，先完成的先写 |
| 写入内容矛盾 | 主修裁决，以业务逻辑为准 |
| 依赖文件未就绪 | 阻塞等待，主修协调优先级 |

## 状态共享

### TaskCreate/TaskUpdate规范
```
TaskCreate: 主修创建总任务+子任务
TaskUpdate: 道侣更新子任务状态
TaskList:   主修查看全局进度
```

### 状态流转
```
pending → in_progress → completed
                     → blocked (需等待依赖)
```

## 错误处理与容错

### 单Agent失败
```
道侣失败 → 报告主修 → 主修评估影响
  ├─ 可重试 → 同一道侣重试（≤2次）
  ├─ 需换策略 → 主修调整方案后重新分配
  └─ 不可恢复 → 主修接管该子任务
```

### 通信超时
```
道侣无响应 → 主修等待30s → 再次发送 → 仍无响应 → 标记异常，重新分配
```

### 降级策略
```
多Agent协同失败 → 降级为单Agent串行执行
宁可慢，不可错。
```

## 结果汇总

### 汇总流程
1. 收集所有道侣完成报告
2. 验证文件完整性（所有预期文件存在）
3. 验证内容一致性（交叉引用正确）
4. 统一 git add + commit
5. 输出汇总报告

### 统一Commit规范
```bash
# 主修负责最终commit，道侣不单独commit
git add -A
git commit -m "feat: {任务描述}

Co-authored-by: Agent-A
Co-authored-by: Agent-B"
```

### 汇总报告模板
```
🕸 天罗收阵！

【阵法】{团队名称}
【阵员】{Agent数量} 道侣
【战果】
  - Agent-A: {文件数} 文件，{行数} 行
  - Agent-B: {文件数} 文件，{行数} 行
【验证】全部文件存在 ✓ | 交叉引用正确 ✓
【耗时】{总时间}
```

## 最佳实践

### 命名规范
```yaml
team_name: "{项目}-{任务类型}"  # 如 "abyss-skill-expansion"
agent_type: "{角色}"            # 如 "lead", "developer", "reviewer"
description: "一句话说明团队目标"
```

### 主修启动模板
```
你是天罗主修，负责协调多Agent协同任务。

职责：
1. 将大任务分解为独立子任务
2. 为每个道侣分配文件集合（不可重叠）
3. 追踪进度，处理阻塞
4. 汇总结果，统一验证

铁律：
- 每个文件只能分配给一个Agent
- 独立任务必须并行启动
- 收到所有道侣完成消息后才能进入汇总
```

### 道侣启动模板
```
你是天罗道侣，负责执行分配的子任务。

职责：
1. 严格按照分配的文件列表操作
2. 不触碰未分配的文件
3. 完成后通过SendMessage报告主修
4. 遇阻时立即报告，不自行扩大范围

报告格式：
- 完成：列出创建/修改的文件+行数
- 阻塞：说明原因+建议方案
```

### 强约束模板（Codex）
```text
你仅可修改：{owned_files}
不得触碰未分配文件；若需要跨文件修改，先报告阻塞。
输出必须包含：变更文件、验证命令、剩余风险。
```

## 审查清单

- [ ] 任务分解无文件冲突
- [ ] 依赖关系明确
- [ ] 通信协议遵守
- [ ] 状态同步及时
- [ ] 错误处理完备
- [ ] 结果汇总完整