# 混合 Agent 路由架构文档

## 架构概述

```
                    +-----------------+
                    |   用户输入      |
                    +--------+--------+
                             |
                             v
                    +-----------------+
                    |  意图分类器     |
                    +--------+--------+
                             |
            +----------------+-----------------+
            |                |                 |
            v                v                 v
       +---------+     +---------+      +----------------+
       | 知识查询 |     | 工具操作 |      | 复杂任务       |
       +----+----+     +----+----+      +-------+--------+
            |                |                  |
            v                v                  v
      +-----------+   +------------+    +---------------+
      |  快速 RAG |   |  快速工具 |    |  React 循环  |
      +-----+-----+   +-----+------+    +-------+-------+
            |                |                 |
            +----------------+-----------------+
                             |
                             v
                      +-------------+
                      |  最终答案  |
                      +-------------+
```

## 意图类型

| 类型 | 说明 | 示例 | 路径 |
|------|------|------|------|
| `knowledge` | 知识查询 | "公司报销政策是什么？" | 快速 RAG |
| `realtime` | 实时数据查询 | "查一下订单 123 的状态" | 快速工具 |
| `action` | 执行操作 | "帮我申请退款" | 快速工具 |
| `chitchat` | 闲聊 | "你好" | 直接回答 |
| `clarify` | 需要澄清 | "我想查点东西..." | 澄清反问 |
| `mixed` | 复杂任务 | "查订单+退款政策+写邮件" | React 循环 |

## 路由规则

```
置信度 < 0.6 → React 循环（安全模式）

置信度 >= 0.6
    ├─ knowledge → 快速 RAG
    ├─ realtime → 快速工具
    ├─ action → 快速工具
    ├─ chitchat → 直接回答
    ├─ clarify → 澄清反问
    └─ mixed → React 循环
```

## 文件结构

```
backend/app/agent/
├── intent_classifier.py    # 意图分类器
├── hybrid_router.py        # 混合路由实现
└── service.py              # Agent 服务（已更新）
```

## SSE 事件

### 新增事件

| 事件 | 说明 | 数据结构 |
|------|------|---------|
| `intent_classified` | 意图分类完成 | `{type: "intent_classified", intent: string, confidence: float, reasoning: string}` |
| `path_decision` | 路径决策完成 | `{type: "path_decision", path: "fast|react_loop", intent: string}` |

### 完整事件流

```
用户消息
  ↓
intent_classified  (新!)
  ↓
path_decision      (新!)
  ↓
[node_start] llm_call
  ↓
[reasoning] 思考过程
  ↓
[tool_call_start] 工具调用开始
  ↓
[tool_call_end] 工具调用结束
  ↓
[llm_token] 最终回答
  ↓
[human_review_request] 人工审核（如有）
  ↓
[done]
```

## 使用示例

### 快速路径示例

```python
# 输入
用户: "你好"

# 响应
intent_classified: {
  intent: "chitchat",
  confidence: 0.95,
  reasoning: "简单寒暄"
}
path_decision: {
  path: "fast",
  intent: "chitchat"
}
llm_token: "你"...
llm_token: "好"...
```

### React 循环示例

```python
# 输入
用户: "帮我查订单，然后生成邮件"

# 响应
intent_classified: {
  intent: "mixed",
  confidence: 0.92,
  reasoning: "需要查询订单、生成邮件，多步骤任务"
}
path_decision: {
  path: "react_loop",
  intent: "mixed"
}
node_start: llm_call
reasoning: "我需要先查询订单..."
tool_call_start: get_order
tool_call_end: 结果
...
```

## 快速开始

### 1. 初始化意图分类器

```python
from app.agent.intent_classifier import get_intent_classifier

classifier = get_intent_classifier()

# 分类意图
result = await classifier.classify("公司报销政策是什么？")
print(f"意图: {result.intent_type}")
print(f"置信度: {result.confidence}")
print(f"推理: {result.reasoning}")
```

### 2. 使用混合路由

```python
from app.agent.hybrid_router import HybridRouter
from app.agent.intent_classifier import get_intent_classifier

classifier = get_intent_classifier()
router = HybridRouter(
    intent_classifier=classifier,
    rag_pipeline=None,  # 传入 RAG
    tool_registry={},   # 传入工具
    react_graph=None    # 传入 Graph
)

# 路由决策
decision = await router.route("你好")
print(f"决策: {decision.action}")

# 执行
result = await router.execute(decision, "你好", "thread_123")
```

## 配置选项

### 置信度阈值

```python
# 修改 backend/app/agent/hybrid_router.py 中的 _make_decision 方法
if confidence < 0.6:  # 修改这个值
    # 走 React 循环
```

### 添加新的意图类型

1. 在 `IntentType` 枚举中添加新类型
2. 在 `routing_map` 中添加路由规则
3. 在 `_build_examples` 中添加示例

## 核心优势

1. **性能优化** - 简单问题走快速路径
2. **用户体验** - 响应速度快
3. **灵活扩展** - 易于添加新意图
4. **安全可靠** - 低置信度走完整循环
5. **可观测性** - 前端显示路径决策

## 测试建议

### 测试用例

```python
test_cases = [
    # 知识查询
    ("公司报销政策是什么？", "knowledge"),

    # 实时查询
    ("查一下订单 123 的状态", "realtime"),

    # 执行操作
    ("帮我申请退款", "action"),

    # 闲聊
    ("你好", "chitchat"),

    # 澄清
    ("我想查点东西...", "clarify"),

    # 复杂任务
    ("查订单+退款政策+写邮件", "mixed"),
]

for query, expected_intent in test_cases:
    result = await classifier.classify(query)
    print(f"{query} → {result.intent_type}")
```

## 扩展指南

### 添加新的快速路径

```python
# 在 HybridRouter 中添加
async def _execute_custom_path(self, user_input: str) -> str:
    # 自定义路径逻辑
    pass
```

### 添加缓存层

```python
# 在 IntentClassifier 中添加缓存
from functools import lru_cache

class IntentClassifier:
    @lru_cache(maxsize=1000)
    async def classify_cached(self, user_input: str):
        # 缓存分类结果
        pass
```

## 注意事项

1. 确保降级策略合理
2. 监控意图分类准确率
3. 根据实际情况调整置信度阈值
4. 前端需要处理新的 SSE 事件
5. 保持向后兼容