Files
deerflow-code/docs/superpowers/specs/2026-05-20-router-subagent-design.md

230 lines
7.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 问答模式路由智能体设计方案
> **状态**:部分实现 ✓
> - ✅ `subagent_mode` 注入机制已实现(`build_run_config`、`_CONTEXT_CONFIGURABLE_KEYS`)
> - ✅ DeerFlow 运行时 `subagent_mode` 加载已实现(`make_lead_agent`)
> - ✅ `router_quality_tool.py` 已创建
> - ✅ 子 Agent 目录结构已创建(7个子 Agent 的 SOUL.md 和 config.yaml)
> - ✅ 路由器 SOUL.md 已更新
> - ⏳ 集成测试和质检提示词测试待完成
## 1. 背景与目标
路由器智能体(`f0e75f44f7594053ba1567ed89258f35`)根据用户问题判断最合适的问答模式(fast/rag/bigMode/moreModes/taskChat/hxchat/deerFlow),选择后需要调用相应子 Agent 执行,路由器对执行结果进行**完整性质检**,通过则流式输出到前端,不通过则重新匹配模式并再次执行。
## 2. 整体流程
```
用户问题
│
▼
┌──────────────────────────────┐
│ 路由器智能体 │
│ (已有 SOUL.md) │
│ ① 判断最佳模式 │
└─────────────┬────────────────┘
│ 选择模式
▼
┌──────────────────────────────┐
│ 子 Agent 执行 │
│ (完整执行完毕,结果缓存) │
└─────────────┬────────────────┘
│ 执行完毕
▼
┌──────────────────────────────┐
│ 路由器质检 │
│ LLM 判断结果是否完整覆盖用户问题 │
└─────────────┬────────────────┘
│
③ 质检结果
┌────┴────┐
│通过 │不通过
▼ ▼
流式输出 重新匹配模式
到前端 (最多重试2次)
```
- **最大重试次数**:每个问题最多 2 次重试(总共最多 3 次执行),超过后强制输出当前结果并标注"结果可能不完整"
## 3. 目录结构
```
.deer-flow/agents/f0e75f44f7594053ba1567ed89258f35/
├── SOUL.md ← 路由器智能体(已有)
├── config.yaml ← 路由器配置
└── subagents/
├── fast/
│ ├── SOUL.md ← 快速问答子 Agent
│ └── config.yaml ← tool_groups 声明
├── rag/
│ ├── SOUL.md
│ └── config.yaml
├── bigMode/
│ ├── SOUL.md
│ └── config.yaml
├── moreModes/
│ ├── SOUL.md
│ └── config.yaml
├── taskChat/
│ ├── SOUL.md
│ └── config.yaml
├── hxchat/
│ ├── SOUL.md
│ └── config.yaml
└── deerFlow/
├── SOUL.md
└── config.yaml
```
**父子关系**:子 Agent 目录放在路由器下二级 `subagents/`,通过目录层级体现父子结构。
## 4. 子 Agent 配置
### 4.1 config.yaml 格式
```yaml
id: rag
name: 知识库问答子Agent
description: 从知识库检索并返回引用
tool_groups:
- knowledge # 知识库检索工具组
- file:read # 只读文件工具
skills: []
model: deepseek-chat
```
### 4.2 tool_groups 说明
- tool_groups 在系统级 `config.yaml` 中统一定义(`tool_groups` 列表)
- 子 Agent 的 config.yaml 通过 `tool_groups` 字段声明自己可以使用哪些工具组
- 工具组示例:web(网页搜索)、knowledge(知识库检索)、file:read、file:write、bash 等
## 5. 调用方式
### 5.1 复用 Gateway API(方案 A — 推荐)
路由器通过 DeerFlow 现有 `/api/threads/{thread_id}/runs/stream` 接口调用子 Agent:
```
POST /api/threads/{thread_id}/runs/stream
{
"assistant_id": "f0e75f44f7594053ba1567ed89258f35",
"context": {
"subagent_mode": "rag" ← 路由器注入子模式
},
"input": {
"messages": [...]
},
"stream_mode": ["values"]
}
```
**执行步骤**:
1. 路由器启动一个 run,assistant_id 指向路由器本身
2. 路由器通过 `context.subagent_mode` 告知 DeerFlow 运行时本次应加载哪个子 Agent
3. DeerFlow 运行时加载 `subagents/{subagent_mode}/SOUL.md` 和对应的 tool_groups
4. 子 Agent 完整执行,结果缓存在 StreamBridge 中
5. 执行完毕后,路由器读取完整结果
**context.subagent_mode 注入机制**:
- `build_run_config` 中新增 `subagent_mode` 到 `_CONTEXT_CONFIGURABLE_KEYS`
- `make_lead_agent` 读取 `configurable.subagent_mode`,如果存在则加载对应子 Agent 的 SOUL.md 和工具配置
- 如果 `subagent_mode` 不存在,则正常运行路由器自己的 SOUL.md
### 5.2 质检提示词
路由器在子 Agent 执行完毕后,用 LLM 进行完整性质检:
```
你是一个质检员。上游子 Agent 已根据问题执行完毕。
请判断以下结果是否完整覆盖了用户问题的所有子问题。
用户原始问题:{original_question}
子 Agent 执行结果:
{agent_output}
请只返回 JSON 格式:
{
"passed": true/false,
"reason": "判断理由(10字内)",
"missing_parts": ["缺失的子问题1", "缺失的子问题2"] // 如果 passed=false
}
```
**质检维度**:完整性(结果是否覆盖了用户问题的所有子问题)
## 6. 关键代码改动
### 6.1 DeerFlow 运行时改动 ✓
**文件**:`packages/harness/deerflow/agents/lead_agent/agent.py`
已实现:
- `make_lead_agent` 读取 `configurable.subagent_mode`(第362-394行)
- 如果存在,加载 `.deer-flow/agents/{agent_id}/subagents/{subagent_mode}/SOUL.md` 和对应 `config.yaml`
- 工具绑定使用子 Agent 的 tool_groups,而非父 Agent 的
### 6.2 build_run_config 改动 ✓
**文件**:`app/gateway/services.py`
已实现:
- `_CONTEXT_CONFIGURABLE_KEYS` 已包含 `subagent_mode`(第149-171行)
- `merge_run_context_overrides` 将 `subagent_mode` 透传到 configurable
### 6.3 路由器 SOUL.md 改动 ✓
**文件**:`.deer-flow/agents/f0e75f44f7594053ba1567ed89258f35/SOUL.md`
已更新:
- 角色扩展:增加"在确定模式后,调用相应子 Agent 执行并对结果进行质检"的职责
- 工具描述:已声明 router_quality_check 工具
### 6.4 新增路由器质检工具 ✓
**文件**:`packages/harness/deerflow/tools/builtins/router_quality_tool.py`
已实现:
```python
@tool("router_quality_check", parse_docstring=True, return_direct=True)
def router_quality_check(original_question: str, agent_output: str) -> str:
"""质检工具 — 判断子 Agent 输出是否完整覆盖用户问题"""
```
## 7. 数据流
```
用户问题
│
▼
路由器 SOUL.md 判断模式
│
▼
启动子 Agent Run(context.subagent_mode = rag)
│
▼
子 Agent SOUL.md + tool_groups 执行
│
▼
StreamBridge 缓存完整结果
│
▼
路由器调用 router_quality_check 质检
│
├── passed=true → 流式输出到前端
└── passed=false → 重新匹配模式(最多2次重试)
```
## 8. 测试计划
- **单元测试**:`tests/test_router_subagent.py` — 测试模式判断、质检逻辑、重试机制
- **集成测试**:手动调用 `/api/threads/{thread_id}/runs/stream`,验证完整流程
- **质检提示词测试**:针对不同问题类型测试质检结果的准确性
## 9. 依赖项
- 路由器复用现有 Gateway API,无需新建接口
- 质检使用 LLM(deepseek-chat 或配置中指定的模型)
- tool_groups 机制依赖系统级 config.yaml 中的工具组定义