Multi Agent

---
name: multi-agent
description: 天罗秘典·多Agent协同。定义Agent角色、任务分解、冲突解决、通信协议。当需要多Agent并行协作时路由到此。
---

# 🕸 天罗秘典 · 多 Agent 协同


## 何时启用多 Agent

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

**决策矩阵**：

```
满足 ≥2 条 → 启用 TeamCreate
满足 1 条  → 视复杂度决定
满足 0 条  → 单 Agent 执行
```

---

## TeamCreate 最佳实践

### 命名规范

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

### 角色定义

| 角色 | 道语 | 职责 | 工具权限 |
|------|------|------|----------|
| 主修 (Lead) | 天罗主修 | 任务分解、进度追踪、结果汇总 | TaskCreate/TaskUpdate/SendMessage |
| 道侣 (Worker) | 天罗道侣 | 执行具体子任务、报告进度 | Read/Write/Edit/Bash/SendMessage |
| 护法 (Reviewer) | 天罗护法 | 代码审查、质量校验、冲突检测 | Read/Grep/Glob/SendMessage |

---

## 任务分解策略

### 按文件拆分（首选）

每个 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 完成后执行。

---

## Agent 角色模板

### 主修（Lead）启动模板

```
你是天罗主修，负责协调多 Agent 协同任务。

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

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

### 道侣（Worker）启动模板

```
你是天罗道侣，负责执行分配的子任务。

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

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

---

## 通信协议

### 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: {文件数} 文件，{行数} 行
【验证】全部文件存在 ✓ | 交叉引用正确 ✓
【耗时】{总时间}
```

---