feat: 添加混合 Agent 路由架构

backend/docs/HYBRID_ROUTER.md

@@ -0,0 +1,269 @@
+# 混合 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. 保持向后兼容