97 lines
4.9 KiB
Markdown
97 lines
4.9 KiB
Markdown
---
|
||
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*
|