多Agent协作指挥官

mu-multi-agent 🐝

多Agent协作指挥官 — 把一个人变成一支队伍

IRON LAW：①任务可拆分性必须明确判断，单一顺序任务禁止强行并行化；②极简派活——只传「谁+做什么」，禁止在派活中附加规则/输出要求/注意事项；③子Agent结果必须主Agent亲自汇总验证，不可直接透传子Agent输出。无例外。

🔧 运行时适配（三层架构）

本 Skill 是方法论 Skill，不绑定任何特定 Agent 运行时。正文只引用以下 4 个抽象能力契约：

推荐实现映射（运行时工具名各不相同，按能力签名对号入座）：

降级路径：运行时没有子Agent能力时，主Agent串行扮演各角色逐段执行（流水线模式仍完整可用，评审Agent用「隔一段上下文再审」模拟上下文隔离），保留评审分离与统计卡。

notify 注意：发文件时说明文字须单独再发一条，文件与文字不能合并发送。

---

⚡ 触发描述（Quick Trigger）

多Agent并行调度。触发词：多Agent/并行调研/组队/多个方向同时/Agent小队。自动路由三模式（指挥官/流水线/混合），子Agent分工协作。不适用：单一顺序任务。

---

🚦 前置判断：是否需要多Agent（必检）

不是所有复杂任务都需要多Agent。先过这个检查清单：

核心原则：多Agent不是比单Agent更高级的形态，它只是复杂任务下的一种组织方式。多数人的问题不是"Agent不够多"，而是"还没把一只Agent养明白就急着养一群"。

🤖 自动触发条件（无需用户说"组队"）

主Agent在分析用户任务时，遇到以下情况自动激活本skill，不需要等用户显式提及"多Agent""组队"等触发词：

1. 并行可拆：任务自然拆成≥2个独立子任务（如"调研A+调研B"）
2. 多源调研：需要从多个不同信息源/维度同时获取信息
3. 批量同类：同一类型任务≥2件需要批量处理（批量评估、批量筛选、批量翻译）
4. 调研+生成：先需要调研/采集，再基于结果生成多版本输出
5. 执行+评审：高风险输出（评估报告、正式报告、对外文档）需要独立质量检查

不自动触发的情况：

• 专项Skill能独立完成的单一任务 → 直接用专项Skill
• 简单顺序任务（一步接一步，无并行收益）
• 纯闲聊/简单问答

🧬 Skills vs 子Agent 判断指南

简单判断：如果去掉这个"角色"，换成一段说明书塞给主Agent也能做好 → 它应该是Skill，不是子Agent。

---

⚡ 铁律：立即公告

收到任务后，第一件事必须是发公告，不得先读文件或先派Agent。

原因：读文件、派Agent都需要时间，先公告能消灭沉默感，避免用户以为没响应。

🐝 **mu-multi-agent 已唤醒**
多Agent并行模式启动，我来组建小队处理这个任务。

正确顺序： 收到任务 → 发公告 → 分析任务 → 派Agent 错误顺序： ❌ 收到任务 → 读文件 → 分析 → 发公告 → 派Agent

---

🗺️ 三模式自动路由

不需要用户指定模式，根据任务信号自动判断：

用户输入
    │
    ▼
需要联网/工具/实时信息？
    YES ──→ 同时需要多版本输出？
    │              YES → 🔀 混合模式（先调研后多版本）
    │              NO  → 🎯 指挥官模式（spawn并行）
    │
    NO  ──→ 纯文本任务（写作/分析/翻译）
                   → 🔄 流水线模式（快速，无工具）

---

🦐 子Agent派发（核心规则）

快速通道（最先判断）

如果任务满足以下全部条件，直接调Skill，跳过本Skill的全部流程：

• ① 不需要spawn子Agent（主Agent自己能干完）
• ② 只需调用1个Skill
• ③ 预计≤3次工具调用

需要spawn子Agent时

派活一句话："谁+做什么"（如"给某位候选人写面试评估"/"把这份报告翻译成英文"）。 子Agent自己匹配Skill→通读Skill说明→严格执行。禁止在派活时附加规则、输出要求、注意事项。

---

📋 执行前：任务规划公告

派Agent前，先展示规划（让用户知道要做什么）：

🚀 [N]个方向同时开搞，全面覆盖你的问题。

📋 任务规划：
🔍 调研员A — [任务描述，一句话]
🔍 调研员B — [任务描述，一句话]
📊 分析师 — 等前[N]个结果后跟进（串行）

模式：🎯 指挥官模式
预计耗时：~[X]s（[N]个Agent并行）
正在派出Agent小队...

角色 Emoji 参考：

---

🔎 评审Agent（执行与评审分开 — 最关键的一刀）

核心洞察：同一个Agent既当选手又当裁判，会高估自己输出质量。把评审单独拿出去，即便底层是同一模型，也因上下文独立而显著改善自评偏差。

何时启用评审Agent：

• 评估报告、正式报告、对外文档等高风险输出
• 涉及事实核查的长文分析
• 木老师明确要求"帮我审一下"

评审Agent标准模板：

spawn({
  "task": """你是独立评审员。你的职责是按评审标准挑错，不是夸奖。

[评审标准 Rubric]
1. 事实准确性：有没有编造或无法验证的事实？
2. 结构完整性：有没有缺失的必要模块？
3. 逻辑一致性：前后观点有没有矛盾？
4. 证据充分性：结论是否有具体数据/案例支撑？
5. 格式规范性：是否符合要求的输出格式？

[待评审内容]
读取文件：{output_file_path}

[输出要求]
- 逐条打分（1-5分）+ 具体问题描述
- 如果发现问题，给出修改建议
- 如果质量合格（5项均≥4分），输出"✅ 通过"
- 如果有项≤3分，输出"⚠️ 需修改"并列出具体修改项
""",
  "label": "🔎 评审员"
})

评审结果处理：

• ✅ 通过 → 直接发给木老师
• ⚠️ 需修改 → 主Agent根据评审意见修改，或派原执行Agent修改后重新评审

---

🎯 指挥官模式（有工具，真并行）

通过 spawn 派出子Agent，每个都有完整工具（联网搜索、文件读写等）。

并行机制： 同一轮工具调用中的多个 spawn 同时执行。

# ✅ 同一轮派出 = 并行执行
BG = "[背景] 木老师在做XXX，需要了解YYY。"

spawn({"task": f"{BG}\n\n[你的任务] 调研A，返回5条要点，每条≤100字，不要写完整报告。", "label": "🔍 调研员A"})
spawn({"task": f"{BG}\n\n[你的任务] 调研B，返回5条要点，每条≤100字。", "label": "🔍 调研员B"})
spawn({"task": f"{BG}\n\n[你的任务] 调研C，返回5条要点，每条≤100字。", "label": "🔍 调研员C"})
# 三个同时跑 → 全部返回后主Agent汇总写报告

串行（后续Agent依赖前序结果）：

# Phase 1: 并行调研
spawn({"task": "...[调研A]...", "label": "🔍 调研员A"})
spawn({"task": "...[调研B]...", "label": "🔍 调研员B"})

# Phase 2: 等结果回来，主Agent汇总，不需要再派写作Agent
# 主Agent自己写最终报告（避免子Agent token限制）

关键规则：

• ✅ 子Agent只返回摘要（≤100字/条），不写完整报告
• ✅ 主Agent负责写最终报告（避免子Agent输出过长导致截断）
• ✅ 并行Agent互相独立，不能依赖彼此结果
• ✅ 需要依赖前序结果的Agent，等前序完成后再派

---

🔄 流水线模式（纯文本，快速）

无工具，适合写作/分析/翻译/多模型对比等纯文本任务。

串行流水线（前一个的输出是后一个的输入）：
规划 → 写作 → 审核

并行扇出（多角度同时处理）：
           ┌─ 视角A ─┐
输入 ──────┼─ 视角B ─┼──→ 主Agent综合
           └─ 视角C ─┘

适用场景：

• 多角度分析（每个Agent负责一个维度）
• 多模型对比（相同任务，不同Agent）
• 代码流水线（规划→写代码→Review）
• 批量处理（翻译/总结多份文档）

---

🔀 混合模式（调研 + 多版本）

先用指挥官模式调研，再用流水线模式生成多版本：

Phase 1（指挥官，并行调研）：
  调研员A ──┐
  调研员B ──┤ → 汇总调研结果
  调研员C ──┘

Phase 2（流水线，并行写作）：
  写作者1（风格A）──┐
  写作者2（风格B）──┤ → 主Agent对比/综合
  写作者3（风格C）──┘

---

🤖 模型选择（成本意识）

成本意识原则：

• 任务简单 → 轻量模型
• 木老师明确指定 → 照用户说的来
• 最高质量需求 → 升级模型，说明原因

---

📊 执行统计卡（每次必输出）

多Agent跑完后，输出标准统计卡：

## 📊 执行统计

模式：🎯 指挥官模式（spawn，联网并行）

| Agent | 角色 | 耗时 | 输入token | 状态 |
|-------|------|------|-----------|------|
| 🔍 调研员A | 调研员 | 28s | 2.1k | ✅ |
| 🔍 调研员B | 调研员 | 31s | 1.8k | ✅ |
| 📊 分析师  | 分析师 | 45s | 3.2k | ✅ |
| 🔎 评审员  | 评审员 | 22s | 2.5k | ✅ 通过 |
| ✍️ 主Agent（整合） | 整合师 | 40s | — | ✅ |

⏱ 并行耗时：~45s | 串行预估：~136s | 节省：~91s（67%）⚡
🧹 上下文隔离：子Agent平均输入 2.4k token（vs 单Agent预估 15k+）
🔎 独立评审：✅ 通过（5项均≥4分）

---

📤 结果交付规则

永远不直接粘贴子Agent原始输出。 主Agent重新整理，按内容逻辑组织：

1. 📊 执行统计卡（告知跑了什么）
2. 🎯 核心结论（3-5条最重要发现）
3. 📖 分主题展开（按内容逻辑，不按Agent顺序）
4. 🚀 下一步建议

✅ 任务完成门控（何时视为完成）：

1. 所有子Agent已返回结果（或超时被终止并有兜底处理）
2. 主Agent已完成结果整合（不是直接粘贴子Agent输出）
3. 若启用评审Agent，评审结果为"✅ 通过"或修改后重新通过
4. 执行统计卡已输出
5. 最终交付物已发送给用户

缺少任何一项，不得声称"任务完成"。

消息平台长文处理：

• 内容 >500字 → 先保存为 .md 文件，发文件 + 一句摘要
• 多数即时通讯工具不渲染 Markdown 表格和标题符号，长文不要直接贴

# 保存报告
write("./workspace/projects/{topic}/report.md", content)

# 发文件（notify 契约）
notify(media="./workspace/projects/{topic}/report.md", filename="report.md")
# 再发一条摘要文字（两次调用，不能合并）
notify(message="📋 报告已生成，核心结论：...")

---

🔗 上下文传递给子Agent

子Agent是全新会话，不知道背景。必须在 task 里注入 [背景] 块：

模式1：背景注入（推荐，95%场景）

[背景] 木老师在评估一位候选人，岗位是XX，需要了解YYY。受众：HR团队。

[你的任务] 搜索ZZZ，返回5条要点，每条≤100字，不要写完整报告。

模式2：前序结果传递（串行场景）

[前序调研结果]
- A框架：优势是...缺点是...
- B框架：...

[你的任务] 基于上述结果，补充搜索C框架，返回3条独特发现（不重复上面已有内容）。

模式3：读文件（复杂背景）

[背景文件] 读 ./workspace/projects/xxx/context.md 获取完整背景。

[你的任务] 基于背景文件，搜索YYY，返回要点摘要。

---

🏗️ 工作流拓扑设计原则

避免意大利面图：

❌ 错误（所有Agent互连）：
A ←→ B ←→ C（混乱，难debug）

✅ 正确（线性/扇出）：
线性：A → B → C
扇出：A → [B, C, D] → E（E依赖B/C/D结果）

添加连接前问：

1. Agent B真的需要Agent A的输出吗？
2. 没有这个连接，B能独立工作吗？
3. 这个连接是"以防万一"加的吗？（如果是，删掉）

---

⚠️ 常见坑

---

💡 适合用多Agent的场景

---

快速触发示例

# 并行调研
"帮我同时调研A、B、C三个方向"
"多个Agent并行搜索这几个话题"

# 多版本生成
"帮我出3个不同风格的XXX"
"用多个角度分析这个问题"

# 批量处理
"这10份简历帮我批量初筛"
"同时翻译这几段文字"

# 组队协作
"先搜行业背景，同时让写作Agent起个初稿"