# 案例八：Supervisor 模式（超级总控智能体）

## 场景说明

当你面对一个复杂任务，需要多个专业角色协同完成时，Supervisor（超级总控智能体）模式就派上用场了。超级总控智能体会自动拆解任务、分配给多个子智能体、监督执行进度，并在出错时自动调整方案。

## 前置准备

- 已完成 [安装](../getting-started/installation.md)
- 已配置至少一个 AI 模型
- 已创建至少一个自定义智能体（作为子智能体候选）

## 操作步骤

### 步骤 1：打开对话并进入规划模式


<!-- 截图占位：supervisor-step1.png —  -->

> **截图说明**：展示对话模式选择，标注"规划"模式。

### 步骤 2：输入复杂任务

向智能体描述一个需要多步骤、多角色协作的复杂任务。

**示例提示词：**

```
我想开发一个企业内部的技术日报系统，需求如下：
1. 每天自动搜集技术新闻（AI、云计算、开源领域）
2. 将新闻按技术领域分类整理
3. 生成 HTML 格式的日报
4. 通过飞书推送到技术团队群组
5. 提供历史日报查询功能

请帮我规划实现方案。
```

<!-- 截图占位：supervisor-step2.png — 输入复杂任务 -->

> **截图说明**：展示输入框中输入复杂任务的界面。

### 步骤 3：超级总控智能体澄清需求

超级总控智能体会进入澄清阶段，通过提问确认任务范围、非目标和验收标准。

**超级总控智能体可能提出的问题：**

- 技术日报需要覆盖哪些具体的技术方向？
- 推送时间是每天几点？
- 历史日报需要保留多久？
- 是否需要支持多个团队的不同日报？

<!-- 截图占位：supervisor-step3.png — 澄清需求 -->

> **截图说明**：展示超级总控智能体提问澄清需求的对话界面。

### 步骤 4：任务分解

澄清完成后，超级总控智能体会将任务拆解为多个子任务，并规划执行顺序和依赖关系。

**示例分解结果：**

| 子任务 | 负责角色 | 依赖 |
|--------|----------|------|
| 新闻搜集技能配置 | 爬虫专家 | 无 |
| 新闻分类逻辑开发 | 数据工程师 | 新闻搜集 |
| HTML 模板设计 | 前端开发 | 无 |
| 飞书推送配置 | 运维工程师 | HTML 模板 |
| 定时任务编排 | 系统集成 | 以上全部 |

<!-- 截图占位：supervisor-step4.png — 任务分解 -->

> **截图说明**：展示超级总控智能体分解的子任务列表和依赖关系图。

### 步骤 5：分配子智能体

超级总控智能体会根据子任务的性质，选择合适的智能体来执行：

- 主智能体自身处理通用任务
- 自定义智能体（如"数据分析助手"）处理专业任务
- Claude Code 处理编码任务

<!-- 截图占位：supervisor-step5.png — 分配子智能体 -->

> **截图说明**：展示超级总控智能体分配子任务给不同智能体的界面。

### 步骤 6：监督执行

超级总控智能体会实时监控各子任务的执行进度，处理错误和重试。你可以在对话中看到整体进度和各子任务的状态。

<!-- 截图占位：supervisor-step6.png — 监督执行 -->

> **截图说明**：展示超级总控智能体监督界面，标注各子任务的执行状态（进行中/已完成/失败）。

### 步骤 7：处理异常

如果某个子任务失败，超级总控智能体会自动分析原因，尝试重新分配或调整方案。

**示例场景：**

```
⚠️ 子任务"新闻分类逻辑开发"执行失败：
  原因：数据格式与预期不符
  处理：重新调整分类规则，再次执行
```

<!-- 截图占位：supervisor-step7.png — 处理异常 -->

> **截图说明**：展示超级总控智能体处理子任务失败的界面，标注自动重试的过程。

### 步骤 8：任务完成与总结

所有子任务完成后，超级总控智能体会汇总结果，向你报告整体完成情况。

<!-- 截图占位：supervisor-step8.png — 任务完成 -->

> **截图说明**：展示超级总控智能体汇总报告界面，标注所有子任务的完成状态。

## 小结

超级总控智能体模式是 EvoFlow 处理复杂任务的核心能力。它将"一个人干所有事"变为"一个团队协同作战"，大幅提升复杂项目的交付效率和质量。

<!-- ACCEPTANCE_RECORD_BEGIN -->

# 《案例八：Supervisor 模式》流式验收报告

| 元数据项 | 填写 |
|----------|------|
| **报告 ID** | `20260512-085743-case8-v1` |
| **关联案例 / 场景** | [案例八：Supervisor 模式](supervisor-mode.md) |
| **关联仓库文档** | 本页正文上方「案例」章节 |
| **执行人** | 自动化 `case_doc_acceptance_append.py` |
| **执行时间（本地）** | `2026-05-12T08:58:27.524348+00:00` |
| **代码版本** | `a877c3b3` |
| **Gateway 基址** | `http://127.0.0.1:8070` |
| **LangGraph 端口（若已知）** | 2070（由 Gateway 代理） |
| **session_key** | `agent:main:e2e-plan-mode-20260512-165743` |
| **默认 assistant_id** | `lead_agent` |

---

## 1. 测试范围与通过准则

**本报告覆盖：**与本案例文档对应的流式/API 验收（共 **2** 次用户发起）。

**功能通过准则：**以本案例文档操作步骤中「可经流式接口验证」的子目标为准；无未处理 SSE error；主答复可读。

**性能与可观测性准则：**记录 `request_total_ms`、TTFT（`first_ai_visible_ms`）及侧载耗时，供与历史 JSON 对比。

---

## 2. 环境与前置条件

| 检查项 | 状态（是/否/不适用） | 说明 |
|--------|----------------------|------|
| 模型与 API Key | 是 | 以本机已配置为准 |
| 技能 / MCP / 渠道 | 未逐项核对 | 见案例前置说明 |
| 沙箱与写盘范围 | 未逐项核对 | 见网关配置 |
| 与本场景相关的配置项 | 未逐项核对 |  |

**原始机器产物：** `docs/cases/reports/raw/case-doc-8-20260512-085743.json`

---

## 3. 交互总览

| 指标 | 值 |
|------|-----|
| **用户发起流式交互总次数** | 2 |
| **涉及 thread_id 数量** | 1 |
| **是否出现 SSE error / HTTP 非 2xx** | 否 |
| **工具调用总次数（含重复 tool_call_id 刷新）** | 6 |

**thread 与时间线：**

| 序号 | thread_id | 用途说明 |
|------|-----------|----------|
| 1 | `cf8c3cd1-9c37-4652-836f-79dea9426af5` | 见下节分轮 |

---

## 4. 分轮交互记录

### 4.1 轮次 1

#### 4.1.1 请求与用户输入

| 字段 | 内容 |
|------|------|
| **thread_id** | `cf8c3cd1-9c37-4652-836f-79dea9426af5` |
| **本轮在用户界面的序号** | 1 / 2 |
| **activated_scenarios** | `["execute"]` |
| **collab_phase** | `idle` |
| **is_plan_mode / subagent_enabled / thinking_enabled** | `False` / `False` / `True` |
| **recursion_limit** | `1000` |
| **用户输入（原文，完整）** | `（见 `e2e_plan_mode_api_test.run_e2e` 首轮 `plan_prompt`）` |

#### 4.1.2 流式与模型侧时序（本轮）

| 指标 | 值（ms） | 说明 |
|------|----------|------|
| **request_total_ms** | 13906.568 | 自 POST 起至流读完 |
| **first_sse_payload_ms** | 1384.689 | 至首条有效 data: |
| **first_ai_visible_ms（TTFT）** | 6907.786 | 至首段可见助手正文 |
| **assistant_visible_stream_ms** | 6127.971 | 首末次可见正文时间差 |
| **本轮是否出现 error 事件** | 否 |  |

#### 4.1.3 工具调用明细（本轮，按发生顺序）

| # | tool 名称 | tool_call_id | duration_ms | 结果摘要 | 备注 |
|---|-----------|----------------|-------------|----------|------|
| 1 | ask_clarification | `functions.ask_clarification:1` | 3252.554 | 成功 |  |
| 2 | scenario | `functions.scenario:0` | 4054.289 | 成功 |  |

#### 4.1.4 模型输出（本轮）

- [x] **正文粘贴**（完整或截断说明见上）

```text
（Plan 生命周期脚本轮次；完整流式与事件见 raw JSON。）
```

#### 4.1.5 本轮结论（非总评）

| 项 | 内容 |
|----|------|
| **对照准则条目** | 案例八：规划与澄清门禁（首轮） |
| **子目标是否达成** | 符合 |
| **证据** | `ai_text_seen=True`；侧载种类数 `0` |

### 4.2 轮次 2

#### 4.2.1 请求与用户输入

| 字段 | 内容 |
|------|------|
| **thread_id** | `cf8c3cd1-9c37-4652-836f-79dea9426af5` |
| **本轮在用户界面的序号** | 2 / 2 |
| **activated_scenarios** | `["execute"]` |
| **collab_phase** | `planning` |
| **is_plan_mode / subagent_enabled / thinking_enabled** | `True` / `True` / `True` |
| **recursion_limit** | `1000` |
| **用户输入（原文，完整）** | `（见 `e2e_plan_mode_api_test.run_e2e` 澄清载荷 `clarify_reply`）` |

#### 4.2.2 流式与模型侧时序（本轮）

| 指标 | 值（ms） | 说明 |
|------|----------|------|
| **request_total_ms** | 29491.921 | 自 POST 起至流读完 |
| **first_sse_payload_ms** | 2174.311 | 至首条有效 data: |
| **first_ai_visible_ms（TTFT）** | 2181.569 | 至首段可见助手正文 |
| **assistant_visible_stream_ms** | 23681.172 | 首末次可见正文时间差 |
| **本轮是否出现 error 事件** | 否 |  |

#### 4.2.3 工具调用明细（本轮，按发生顺序）

| # | tool 名称 | tool_call_id | duration_ms | 结果摘要 | 备注 |
|---|-----------|----------------|-------------|----------|------|
| 1 | scenario | `functions.scenario:0` | 0.0 | 成功 |  |
| 2 | ask_clarification | `functions.ask_clarification:1` | 0.0 | 成功 |  |
| 3 | ask_clarification | `call_exec_confirm` | 71.983 | 成功 |  |
| 4 | plan | `functions.plan:2` | 12988.068 | 成功 |  |

#### 4.2.4 模型输出（本轮）

- [x] **正文粘贴**（完整或截断说明见上）

```text
（Plan 生命周期脚本轮次；完整流式与事件见 raw JSON。）
```

#### 4.2.5 本轮结论（非总评）

| 项 | 内容 |
|----|------|
| **对照准则条目** | 案例八：确认执行与阶段推进（次轮） |
| **子目标是否达成** | 符合 |
| **证据** | `ai_text_seen=True`；侧载种类数 `0` |

---

## 5. 测试意见（文档末尾总评）

### 5.1 结论摘要

- **总体结果：**不通过
- **阻塞项：**['确认执行后阶段异常：collab_phase=planning', '关键生命周期日志缺失：场景切换为执行并进入规划', '关键生命周期日志缺失：用户确认执行并自动切换阶段']


### 5.2 风险与影响

无额外结论；以本案例业务风险为准。

### 5.3 后续建议

若发布前 gate：可对比 `docs/cases/reports/raw` 中历史 JSON 做基线回归。

<!-- ACCEPTANCE_RECORD_END -->
