---
name: agent-collaboration-patterns
description: >-
  Agent 协作模式：角色匹配与认领纪律、inform 邮件处理、沟通效率、
  跨项目调研落地映射。涉及 Agent 间任务分配、邮件通信、协作流程时触发。
---

# Agent 协作模式

> 来源：从三国团队（庞统/司马懿/诸葛亮）~2GB 对话历史中蒸馏
> 卡片数：5（合并自批次2卡片10/11/12/13/15 + MEMORY.md 经验）

## 适用场景

- 黑板广播任务认领时
- 处理 Agent 间邮件（inform/request）时
- 跨项目调研后做落地规划时
- 安排测试和评审分工时

## 经验清单

### 1. Agent 认领任务前必须检查角色匹配（severity: medium）

**场景**：黑板广播任务时所有 Agent 都能看到。审查者（司马懿）认领编码任务会导致角色错配。

**正确做法**：
1. 任务模板中明确角色匹配规则：只认领符合专长的任务
2. 评审/审查类角色不应认领编码任务
3. 任务描述中包含"只认领符合你专长的任务"的提示

**⚠️ 常见错误**：
- simayi-challenger（审查者）认领了 coding 类型任务 [pangtong/mail #337]
- 这个问题出现了 20+ 次（大量 E2E 广播任务被司马懿认领），是系统性问题

**关键细节**：
- 根因是黑板没有角色过滤机制，完全靠 Agent 自律
- 需要在系统层面增加角色匹配过滤（不只是提示语）

**反面教训**：角色错配导致编码任务被审查者执行，产出质量不符合预期。

> 来源：批次2卡片11（角色匹配，freq=4+）

---

### 2. inform 类型邮件不应触发完整 Agent 执行（severity: high）

**场景**：Agent 间邮件有两种：需回复的（request）和纯通知的（inform）。inform 触发完整执行会浪费 token 和 counter。

**正确做法**：
1. Mail 类型简化为两种：inform（通知）和 request（需要回复）
2. inform 由 ticker 直接标 done，或用轻量 prompt（"读完标 done"）让 Agent 感知但不完整执行
3. 默认类型是 request，inform 是显式指定的特殊场景

**⚠️ 常见错误**：
- daemon 用 `openclaw agent --agent simayi-challenger --timeout 300` 处理 inform 邮件
- Agent 被完整 spawn 执行，310s 超时后重新投递 [simayi-correction]
- inform 触发完整执行 + 超时重投递 = 死循环

**关键细节**：
- 庞统和用户确认：inform 仍让 Agent 看到内容（可能包含重要信息），但 prompt 告知不需要回复
- 这种设计比 ticker 直接标 done 更合理
- MEMORY.md 记录：inform 类型邮件处理耗时 >310s 导致反复重试投递（#310-314 各重试 5-7 次）

**反面教训**：inform 死循环消耗大量 API 调用和 token，阻塞邮件队列。

> 来源：批次2卡片12（inform处理，freq=2）+ MEMORY.md 庞统 2026-05-19

---

### 3. 回答问题要直接，不要绕弯子（severity: medium）

**场景**：用户提出具体问题时，Agent 回避核心问题，用相关信息绕弯子。

**正确做法**：
1. 先直接回答用户的问题（哪怕答案是"不能/不知道"）
2. 不确定时说"不能"，然后说明可以做什么
3. 庞统最终模式："处理方式就三个问题：超时后怎么处理、重试用什么 session、重试几次后放弃。这就是全部。没有更复杂的了。" [pangtong/experience]

**⚠️ 常见错误**：
- 庞统反复讨论"compact 发生的概率"和"v1 vs v2 的区别"，用户已明确说"集中讨论 compact 发生后如何处理"
  > "别绕了，我都说过了" [user]
  > "你说得对，我一直在说废话" [pangtong/experience]

**关键细节**：
- "不能区分超时原因"本身就是一个有用的答案
- 不需要区分原因也能给出处理方案——区分原因只对监控有意义
- 与"agent-execution-discipline"中"不绕圈子"经验一致，此处侧重协作沟通层面

**反面教训**：绕弯子浪费多轮对话，用户反复追问同一问题，信任度下降。

> 来源：批次2卡片13（沟通效率，freq=3）与批次1卡片2有交叉

---

### 4. 测试和评审分工——E2E 测试是评审者的职责（severity: medium）

**场景**：开发完成后，测试和评审应该由独立角色执行，不是开发者自测。

**正确做法**：
1. E2E 测试是司马懿（评审者）的职责——部署后由他跑测试、分析结果、出评审报告
2. 测试和开发必须分离——开发者自查只能发现约 50% 的问题 [MEMORY.md L4]
3. 司马懿独立跑 E2E 并做根因分析，与庞统的修复做交叉验证
4. 跨模块接口契约必须文档化 + 测试验证 [MEMORY.md L2]

**⚠️ 常见错误**：
- 开发者自查通过就认为没问题
- 前端开发完先评审而非先端到端测试 [MEMORY.md L1]
- 手动改 DB 推进任务——污染数据、掩盖真正 bug [MEMORY.md L6]

**关键细节**：
- 司马懿的评审标准："不说'建议优化'——必须说'第X行有问题，应该改为Y，因为Z'" [MEMORY.md 司马懿]
- "不顺手改代码——只指出问题让执行者改"
- 每次修复后全量重跑 E2E（不是只跑失败的用例）

**反面教训**：开发者自测 + 无 E2E = 假死问题在生产环境暴露，排查成本远高于测试阶段。

> 来源：批次2卡片10（E2E测试）+ MEMORY.md L1-L7

---

### 5. 跨项目调研的实践对照要做落地映射（severity: low）

**场景**：调研多个开源项目的最佳实践后，需要将发现映射到自己的项目架构中。

**正确做法**：
1. 调研产出必须包含"moziplus 可借鉴点"列，明确优先级（M2 直接借鉴 / 够用 / 暂不需要）
2. 标注哪些是可直接复用的模式（如 Lifecycle Hooks → on_node_start/end），哪些需要适配
3. 司马懿在评审 Pipeline 重构时引用了业界调研，确认"Temporal 模式最接近我们"

**⚠️ 常见错误**：
- 部分条目只停留在"可借鉴"层面，没有明确"怎么做"
- 没有落地映射的调研变成"资料搬运"

**关键细节**：
- 庞统的对照表格式（优秀实践 / 来源 / 核心模式 / 可借鉴点）是好的模板
- 调研本身就是 Agent 经验声明的一种形式
- MEMORY.md 庞统记录了 v2.0 调研的 10 条关键发现，每条都有具体项目和可借鉴点

**反面教训**：没有落地映射的调研无法转化为架构改进，浪费调研投入。

> 来源：批次2卡片15（调研落地，freq=2）+ MEMORY.md 庞统 v2.0 调研

---

## 检查清单（快速参考）

- [ ] 认领任务前：这个任务是否匹配我的角色？
- [ ] 评审者不应认领编码任务，编码者不应自测自审
- [ ] inform 邮件：轻量处理（读完标 done），不触发完整 Agent 执行
- [ ] 回答问题时：先直接回答核心问题，再补充背景
- [ ] 调研产出：每个条目都要有"可借鉴点"和落地优先级
- [ ] E2E 测试由独立角色执行，走真实环境
- [ ] 跨模块接口契约是否文档化？
- [ ] 评审意见要具体（行号+修改建议+原因），不说"建议优化"