4.9 KiB
name, description, type, originSessionId
| name | description | type | originSessionId |
|---|---|---|---|
| Agent Team 协同经验教训 | 基于 2026-04-13 文档团队实战总结的 Agent Team 协同问题、解决方案和关键经验 | feedback | 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 间通信
-
消息不保证回复: 向 Agent 发送消息后，Agent 可能进入 idle 而不回复。这不是错误，是 Agent 生命周期行为。需要通过其他手段（文件检查、任务状态）判断进展。
-
shutdown 协议: 发送
{"type": "shutdown_request"}后，Agent 会回复{"type": "shutdown_response", "approve": true}并进入 idle。这是正常的确认流程。
文件编辑
-
Edit 工具对空白敏感: old_string 必须与文件内容完全匹配，包括制表符和空格。本次任务中 Mermaid 图表编辑失败，原因是 old_string 中的缩进（tab vs spaces）与文件实际内容不匹配。遇到编辑失败时，重新 Read 文件获取精确内容。
-
大文件分段编辑: 850 行的 req-review-report.md 不适合一次性替换。策略是按节分段编辑（§1.3 → §4.1 → §4.2 → §5.1 → ...），每次编辑一个小节。这样做的好处是：失败影响范围小、可以逐步验证。
团队管理
-
TaskUpdate 由 Agent 自行完成: 创建任务时在 prompt 中明确要求「完成后使用 TaskUpdate 标记为 completed」。但不要依赖 Agent 一定会执行。主 Agent 应该在 Agent 报告完成后再次确认。
-
团队清理顺序: TeamDelete 之前，确保所有 Agent 已 shutdown。本次任务中先发送 shutdown → 收到确认 → 再执行 TeamDelete，流程正确。
任务规划
-
依赖任务串行执行: Task#5（更新 req-review-report.md）依赖 Task#1-#4 的结果。通过 TaskUpdate 的 addBlockedBy 设置依赖关系是正确的做法。但阻塞解除后需要主 Agent 手动开始执行，不会自动触发。
-
并行任务数量控制: 本次 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