---
name: Agent Team 协同经验教训
description: 基于 2026-04-13 文档团队实战总结的 Agent Team 协同问题、解决方案和关键经验
type: feedback
originSessionId: 4fd99c0b-ce4a-4ce4-8356-91880b65a867
---
# Agent Team 协同经验教训

> 来源: 2026-04-13 文档团队实战（4 Agent 并行：req-writer, ui-designer, ux-writer, claude-md-updater）

---

## ⚠️ 关键经验（必须遵循）

### 1. Agent 完成工作后必须立即关闭

**规则**: Agent 完成任务并发送 idle 通知后，主 Agent 必须立即发送 shutdown_request。不要等待用户提醒。

**Why**: 空闲 Agent 持续占用 API 配额和系统资源（每个 Agent 约 1-2GB 内存）。本次任务中，3 个 Agent 完成后空闲了约 15 分钟，直到用户提醒才关闭。

**How to apply**: 收到 idle_notification 且任务已标记 completed 时，立即发送 shutdown_request。不要等「更好的时机」。

### 2. Agent 可能静默完成但不标记任务

**规则**: 不能仅依赖 TaskUpdate 状态判断 Agent 工作完成。必须同时验证产出物是否存在。

**Why**: ui-designer 创建了 2084 行的 docs/05-设计-UI.md 文件，但没有通过 TaskUpdate 将 Task#3 标记为 completed。进度追踪显示 "pending" 但实际已完成。发送进度查询消息后 ui-designer 也未回复。

**How to apply**: 当 Agent 进入 idle 且长时间未更新任务状态时，主动检查文件系统（`ls -la` / `wc -l`）确认产出物。不要仅依赖 TaskList。

### 3. SendMessage 参数格式必须包含 summary

**规则**: SendMessage 的 message 参数为字符串时，必须同时提供 summary 参数。

**Why**: 第一次尝试向 3 个 Agent 发送 shutdown_request 时全部失败，错误信息为 "summary is required when message is a string"。

**How to apply**: 所有 SendMessage 调用都必须包含 summary 字段，无论 message 是字符串还是 JSON 对象。

---

## 一般经验

### Agent 间通信

4. **消息不保证回复**: 向 Agent 发送消息后，Agent 可能进入 idle 而不回复。这不是错误，是 Agent 生命周期行为。需要通过其他手段（文件检查、任务状态）判断进展。

5. **shutdown 协议**: 发送 `{"type": "shutdown_request"}` 后，Agent 会回复 `{"type": "shutdown_response", "approve": true}` 并进入 idle。这是正常的确认流程。

### 文件编辑

6. **Edit 工具对空白敏感**: old_string 必须与文件内容完全匹配，包括制表符和空格。本次任务中 Mermaid 图表编辑失败，原因是 old_string 中的缩进（tab vs spaces）与文件实际内容不匹配。遇到编辑失败时，重新 Read 文件获取精确内容。

7. **大文件分段编辑**: 850 行的 req-review-report.md 不适合一次性替换。策略是按节分段编辑（§1.3 → §4.1 → §4.2 → §5.1 → ...），每次编辑一个小节。这样做的好处是：失败影响范围小、可以逐步验证。

### 团队管理

8. **TaskUpdate 由 Agent 自行完成**: 创建任务时在 prompt 中明确要求「完成后使用 TaskUpdate 标记为 completed」。但不要依赖 Agent 一定会执行。主 Agent 应该在 Agent 报告完成后再次确认。

9. **团队清理顺序**: TeamDelete 之前，确保所有 Agent 已 shutdown。本次任务中先发送 shutdown → 收到确认 → 再执行 TeamDelete，流程正确。

### 任务规划

10. **依赖任务串行执行**: Task#5（更新 req-review-report.md）依赖 Task#1-#4 的结果。通过 TaskUpdate 的 addBlockedBy 设置依赖关系是正确的做法。但阻塞解除后需要主 Agent 手动开始执行，不会自动触发。

11. **并行任务数量控制**: 本次 4 个 Agent 并行工作在 10GB 内存环境下是可行的，但接近上限。建议同时并行不超过 3 个 Agent 执行重 IO/长上下文任务。

---

## 问题清单

| # | 问题 | 影响 | 解决方案 | 严重度 |
|---|------|------|---------|--------|
| 1 | Agent 空闲未主动关闭 | 资源浪费 15min | 收到 idle+completed 立即 shutdown | 高 |
| 2 | ui-designer 未标记任务完成 | 进度追踪不准 | 主 Agent 主动检查文件系统 | 高 |
| 3 | SendMessage 缺 summary 参数 | 关闭请求失败 | 所有 SendMessage 必须带 summary | 中 |
| 4 | Edit 空白不匹配 | 编辑失败需重试 | 失败后重新 Read 获取精确内容 | 低 |
| 5 | Agent 不回复进度查询 | 无法了解进展 | 改用文件系统检查替代 | 中 |

---

## 推荐的 Agent Team 工作流程

```
1. 创建团队 (TeamCreate)
2. 创建任务 (TaskCreate) + 设置依赖 (TaskUpdate addBlockedBy)
3. 启动并行 Agent (Agent tool with team_name)
4. 监控进展:
   - 收到 teammate message → 确认产出物
   - 收到 idle notification → 检查任务状态 → 完成则立即 shutdown
5. 所有并行任务完成 → 启动依赖任务
6. 所有任务完成 → 发送 shutdown_request → TeamDelete
```

---

*最后更新: 2026-04-13*