更新 README：添加完整的 React 模式架构说明和流程图

2026-05-01 23:45:08 +08:00
parent 5d0a6e4aba
commit 01762970af
1 changed files with 158 additions and 28 deletions
--- a/backend/app/README.md
+++ b/backend/app/README.md
@@ -23,26 +23,27 @@ app/
 │
 ├── agent/                   # ⭐ Agent 服务层
 │   ├── __init__.py
-│   ├── service.py           # AIAgentService - 核心服务类
+│   ├── agent_service.py     # AIAgentService - 核心服务类
 │   ├── history.py           # 历史查询服务
 │   └── prompts.py           # 提示词模板
 │
 ├── main_graph/              # ⭐ 主图 - LangGraph 主流程
 │   ├── __init__.py
-│   ├── state.py             # 主图状态定义
-│   ├── graph_builder.py     # 主图构建器
+│   ├── state.py             # 主图状态定义（MainGraphState）
+│   ├── graph.py             # 图组件重导出
+│   ├── config.py            # 流配置
 │   │
 │   ├── nodes/               # 主图节点
 │   │   ├── __init__.py
-│   │   ├── router.py        # 路由决策节点
-│   │   ├── llm_call.py      # LLM 调用节点（React 模式）
-│   │   ├── tool_call.py     # 工具执行节点
+│   │   ├── react_nodes.py   # React 模式节点（推理、路由）
+│   │   ├── llm_call.py      # LLM 调用节点
 │   │   ├── retrieve_memory.py # 记忆检索节点
+│   │   ├── memory_trigger.py # 记忆触发节点
 │   │   ├── summarize.py     # 记忆摘要节点
 │   │   ├── finalize.py      # 最终处理节点
-│   │   ├── memory_trigger.py # 记忆触发节点
 │   │   ├── rag_nodes.py     # RAG 相关节点
-│   │   └── react_nodes.py   # React 模式节点
+│   │   ├── web_search_node.py # 联网搜索节点
+│   │   └── error_handling_node.py # 错误处理节点
 │   │
 │   ├── tools/               # 主图工具
 │   │   ├── __init__.py
@@ -51,8 +52,8 @@ app/
 │   │
 │   └── utils/               # 主图工具函数
 │       ├── __init__.py
+│       ├── main_graph_builder.py # 主图构建器
 │       ├── retry_utils.py   # 重试工具
-│       ├── subgraph_builder.py # 子图构建器
 │       ├── rag_initializer.py # RAG 初始化工具
 │       └── visualize_graph.py # 图可视化工具
 │
@@ -82,7 +83,8 @@ app/
 │
 ├── model_services/          # 模型服务层
 │   ├── __init__.py
-│   ├── base.py              # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager
+│   ├── README.md            # 模型服务文档
+│   ├── base.py              # 基类：BaseServiceProvider, FallbackServiceChain
 │   ├── chat_services.py     # 生成式大模型服务
 │   ├── embedding_services.py # 嵌入模型服务
 │   └── rerank_services.py   # 重排序服务
@@ -136,23 +138,42 @@ app/

 | 文件 | 说明 |
 |------|------|
-| `service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 |
+| `agent_service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 |
 | `history.py` | 历史对话查询服务 |
 | `prompts.py` | 系统提示词模板 |

 ---

-### 3. `main_graph/` - 主图
+### 3. `main_graph/` - 主图（React 模式）

-LangGraph 的主流程，处理普通对话和工具调用：
+LangGraph 的主流程，采用 React 模式（Reasoning + Acting）：

 | 目录/文件 | 说明 |
 |----------|------|
-| `state.py` | 主图状态定义，包含消息、RAG 上下文、错误记录等 |
-| `graph_builder.py` | 构建主图的类，定义节点和边 |
-| `nodes/` | 所有节点实现（router, llm_call, tool_call 等） |
-| `tools/` | 图的工具定义（天气、文件、网页、RAG 等） |
-| `utils/` | 辅助函数（重试、子图构建、初始化等） |
+| `state.py` | 主图状态定义（MainGraphState），整合所有旧状态字段 |
+| `graph.py` | StateGraph, START, END 等组件重导出 |
+| `config.py` | 流写入器配置 |
+| `nodes/` | 所有节点实现 |
+| `tools/` | 图的工具定义 |
+| `utils/main_graph_builder.py` | 主图构建器 - 构建完整的 React 模式图 |
+
+#### 🔄 主图节点说明
+
+| 节点 | 类型 | 说明 |
+|------|------|------|
+| `retrieve_memory` | 记忆 | 从 Mem0 检索相关长期记忆 |
+| `memory_trigger` | 记忆 | 检测记忆指令，主动触发存储 |
+| `init_state` | React | 初始化状态 |
+| `react_reason` | React | 推理节点，理解意图并决策下一步 |
+| `rag_retrieve` | 工具 | RAG 检索 |
+| `web_search` | 工具 | 联网搜索 |
+| `contact_subgraph` | 子图 | 调用通讯录子图 |
+| `dictionary_subgraph` | 子图 | 调用词典子图 |
+| `news_analysis_subgraph` | 子图 | 调用资讯分析子图 |
+| `handle_error` | 错误 | 错误处理和重试 |
+| `llm_call` | 模型 | 调用大模型生成回复 |
+| `summarize` | 记忆 | 对话总结，提交 Mem0 存储 |
+| `finalize` | 完成 | 发送完成事件 |

 ---

@@ -174,7 +195,7 @@ LangGraph 的主流程，处理普通对话和工具调用：

 | 文件 | 说明 |
 |------|------|
-| `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链）、`SingletonServiceManager`（单例管理） |
+| `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链） |
 | `chat_services.py` | 生成式大模型服务（智谱、DeepSeek、本地） |
 | `embedding_services.py` | 嵌入模型服务 |
 | `rerank_services.py` | 重排序服务 |
@@ -196,19 +217,65 @@ LangGraph 的主流程，处理普通对话和工具调用：

 ---

-## 🔄 数据流
+## 🔄 完整流程图
+
+```
+START
+  ↓
+retrieve_memory (从Mem0检索长期记忆)
+  ↓
+memory_trigger (记忆触发器 - 检测记忆指令)
+  ↓
+init_state (初始化状态)
+  ↓
+react_reason (推理节点 - 理解意图并决策) ←───────────┐
+  ↓                                                       │
+route_by_reasoning (条件路由)                             │
+  ↓                                                       │
+┌─────────────────────────────────────────────────┐       │
+│ 分支选择：                                      │       │
+│  ├─ rag_retrieve →───────────────────────────┐ │       │
+│  ├─ web_search →─────────────────────────────┤ │       │
+│  ├─ contact_subgraph →───────────────────────┤ │       │
+│  ├─ dictionary_subgraph →────────────────────┤ │       │
+│  ├─ news_analysis_subgraph →─────────────────┤ │       │
+│  ├─ handle_error →───────────────────────────┤ │       │
+│  └─ llm_call →────────────────────────────────┘ │       │
+└─────────────────────────────────────────────────┘       │
+                          ↓                               │
+                    (回到 react_reason) ──────────────────┘
+                          ↓
+                    (无工具调用)
+                          ↓
+                    llm_call (直接生成回复)
+                          ↓
+┌─────────────────────────────────────────────────┐
+│ 检查：需要总结吗？(turns_since_last_summary >=5?) │
+│  ├─ 是 → summarize (提交Mem0存储)               │
+│  └─ 否 → (跳过)                                 │
+└─────────────────────────────────────────────────┘
+                          ↓
+                    finalize (发送完成事件)
+                          ↓
+                    END
+```
+
+---
+
+## 📊 数据流

 ```
 用户请求 
  └─> backend.py (FastAPI)
-       └─> agent/service.py (AIAgentService)
-            ├─> model_services/ (获取模型)
-            ├─> main_graph/ (执行主图)
-            │    ├─> nodes/ (执行节点)
-            │    ├─> tools/ (调用工具)
-            │    └─> rag/ (RAG 检索)
-            └─> subgraphs/ (可选：调用子图)
-                 └─> core/ (共享工具)
+       └─> agent/agent_service.py (AIAgentService)
+            ├─> model_services/ (获取模型 - 支持降级链)
+            ├─> main_graph/utils/main_graph_builder.py (构建主图)
+            └─> graph.astream() (执行图流)
+                 ├─> nodes/ (执行节点)
+                 ├─> tools/ (调用工具)
+                 ├─> rag/ (RAG 检索)
+                 ├─> subgraphs/ (可选：调用子图)
+                 └─> memory/ (记忆检索和存储)
 ```

 ---
@@ -227,3 +294,66 @@ uvicorn app.backend:app --reload --host 0.0.0.0 --port 8079
 # 方式 3：Docker
 docker compose up
 ```
+
+---
+
+## 📝 状态系统
+
+### MainGraphState
+
+所有节点统一使用 `MainGraphState`（dataclass），包含以下字段：
+
+```python
+@dataclass
+class MainGraphState:
+    # 消息和记忆
+    messages: Annotated[Sequence[BaseMessage], add_messages]
+    llm_calls: int
+    memory_context: str
+    system_prompt: str
+    turns_since_last_summary: int
+    
+    # LLM 输出
+    last_token_usage: Dict[str, Any]
+    last_elapsed_time: float
+    
+    # 用户信息
+    user_query: str
+    user_id: str
+    
+    # React 推理
+    reasoning_step: int
+    max_steps: int
+    last_action: str
+    reasoning_history: List[Dict[str, Any]]
+    
+    # RAG 相关
+    rag_context: str
+    rag_retrieved: bool
+    rag_docs: List[Dict[str, Any]]
+    
+    # 搜索相关
+    web_search_results: List[str]
+    
+    # 错误处理
+    errors: List[ErrorRecord]
+    current_error: Optional[ErrorRecord]
+    retry_action: Optional[str]
+    
+    # 子图结果
+    news_result: Optional[Dict[str, Any]]
+    dictionary_result: Optional[Dict[str, Any]]
+    contact_result: Optional[Dict[str, Any]]
+    
+    # 执行状态
+    current_action: CurrentAction
+    current_phase: str
+    error_message: str
+    final_result: str
+    success: bool
+    
+    # 元数据
+    start_time: Optional[str]
+    end_time: Optional[str]
+    debug_info: Dict[str, Any]
+```