docs: 更新 backend/app/README.md，按模块整理已实现功能

backend/app/README.md

@@ -1,7 +1,6 @@
 # 后端模块 (backend/app/)
 
-## 项目概览
-这是一个基于 LangGraph 的个人助手系统，提供对话、工具调用、记忆管理和 RAG 检索功能。
+这是一个基于 LangGraph 的个人助手系统，提供对话、工具调用、记忆管理、RAG 检索和子图功能。
 
 ---
 
@@ -11,23 +10,33 @@
 backend/app/
 ├── agent/                    # Agent 服务层
 │   ├── service.py           # AIAgentService - 主服务类
-│   ├── llm_factory.py       # LLM 工厂 - 多模型创建
 │   ├── rag_initializer.py   # RAG 工具初始化
 │   ├── history.py           # 对话历史管理
 │   └── prompts.py           # 提示词模板
-├── agent_subgraphs/           # 子图模块（规划中，仅 README）
-├── graph/                    # LangGraph 图构建
+├── agent_subgraphs/           # 子图模块 ✅ 已实现
+│   ├── common/              # 公共工具
+│   │   ├── state_base.py   # 状态基类
+│   │   ├── intent.py       # 意图理解（React 模式）
+│   │   ├── formatter.py    # 格式化输出工具
+│   │   └── human_review.py # 人工审核节点
+│   ├── contact/             # 通讯录子图
+│   ├── dictionary/          # 词典子图
+│   ├── news_analysis/       # 资讯分析子图
+│   ├── research/            # 研究分析子图（规划中）
+│   └── README.md
+├── graph/                    # LangGraph 主图构建
 │   ├── graph_builder.py     # 图构建器
 │   ├── graph_tools.py       # 工具定义
 │   ├── state.py            # 状态定义
 │   ├── retrieve_memory.py   # 记忆检索节点
+│   ├── rag_nodes.py        # RAG 集成节点
 │   └── visualize_graph.py   # 图可视化
 ├── memory/                   # 记忆模块
 │   └── mem0_client.py       # Mem0 客户端
-├── model_services/            # 模型服务（嵌入、重排等）⭐ 新增
+├── model_services/            # 模型服务层 ✅ 已重构
 │   ├── __init__.py
-│   ├── README.md
 │   ├── base.py              # 基类和降级机制
+│   ├── chat_services.py     # 生成式大模型服务
 │   ├── embedding_services.py # 嵌入服务
 │   └── rerank_services.py   # 重排服务
 ├── nodes/                    # LangGraph 节点实现
@@ -37,10 +46,11 @@ backend/app/
 │   ├── summarize.py         # 摘要节点
 │   ├── finalize.py          # 最终节点
 │   └── memory_trigger.py     # 记忆触发节点
-├── rag/                      # RAG 检索模块
+├── rag/                      # RAG 检索模块 ✅ 已重构
 │   ├── pipeline.py          # RAG 流水线
 │   ├── tools.py            # RAG 工具
-│   ├── reranker.py         # 重排器（将弃用，用 model_services）
+│   ├── rerank.py           # 重排业务逻辑
+│   ├── retriever.py        # 检索器
 │   ├── query_transform.py   # 查询转换
 │   └── fusion.py           # 结果融合
 ├── utils/                    # 工具函数
@@ -59,13 +69,13 @@ backend/app/
   - 接收外部 checkpointer，管理图生命周期
   - 支持多模型动态切换
   - 提供流式和非流式接口
-- **LLMFactory** - LLM 工厂
-  - 支持智谱 AI (glm-4.7-flash)
-  - 支持 DeepSeek (deepseek-reasoner)
-  - 支持本地模型 (vLLM/llama.cpp)
+- **多模型支持** - 通过 chat_services
+  - 智谱 AI (glm-4.7-flash)
+  - DeepSeek (deepseek-reasoner)
+  - 本地模型 (vLLM/llama.cpp)
 - **对话历史** - 基于 LangGraph 状态持久化
 
-### 2. LangGraph 图 (graph/)
+### 2. LangGraph 主图 (graph/)
 - **GraphBuilder** - 图构建器
   - 模块化节点创建，依赖注入
   - 支持 Mem0 客户端集成
@@ -78,6 +88,7 @@ backend/app/
   - read_pdf_summary - 读取 PDF
   - read_excel_as_markdown - 读取 Excel
   - fetch_webpage_content - 抓取网页
+- **React 模式** - 循环推理 + 超时重试 + 结构化错误处理
 
 ### 3. 节点实现 (nodes/)
 - **llm_call** - LLM 调用节点
@@ -93,78 +104,110 @@ backend/app/
   - 支持记忆检索和添加
   - 可集成到 LangGraph 中
 
-### 5. 模型服务 (model_services/) - ⭐ 新增
+### 5. 模型服务层 (model_services/)
+架构：纯服务层 + 业务逻辑分离
+
+#### 5.1 基类与公共机制 (base.py)
 - **BaseServiceProvider** - 服务提供者基类
   - 统一接口：is_available() 和 get_service()
 - **FallbackServiceChain** - 链式降级机制
   - 优先尝试主服务，失败自动尝试备用服务
 - **SingletonServiceManager** - 单例管理器
   - 全局单例，避免重复创建
-- **Embedding 服务**
-  - LocalLlamaCppEmbeddingProvider - 本地 llama.cpp 嵌入
-  - ZhipuEmbeddingProvider - 智谱 AI 嵌入
-  - get_embedding_service() - 统一接口，自动降级
-- **Rerank 服务**
-  - LocalLlamaCppRerankProvider - 本地 llama.cpp 重排
-  - ZhipuRerankProvider - 智谱 AI 重排
-  - get_rerank_service() - 统一接口，自动降级
 
-### 6. RAG 检索 (rag/)
+#### 5.2 生成式大模型 (chat_services.py)
+- **LocalVLLMChatProvider** - 本地 VLLM 服务（gemma-4-E4B-it）
+- **ZhipuChatProvider** - 智谱 AI 服务（glm-4.7-flash）
+- **DeepSeekChatProvider** - DeepSeek 服务（deepseek-reasoner）
+- **get_chat_service()** - 默认服务（自动降级）
+- **get_all_chat_services()** - 获取所有可用模型
+
+#### 5.3 嵌入服务 (embedding_services.py)
+- **LocalLlamaCppEmbeddingProvider** - 本地 llama.cpp 嵌入
+- **ZhipuEmbeddingProvider** - 智谱 AI 嵌入
+- **get_embedding_service()** - 统一接口，自动降级
+
+#### 5.4 重排服务 (rerank_services.py)
+- **LocalLlamaCppRerankProvider** - 本地 llama.cpp 重排
+- **ZhipuRerankProvider** - 智谱 AI 重排
+- **get_rerank_service()** - 统一接口，自动降级
+
+### 6. RAG 检索模块 (rag/)
+架构：业务逻辑层 + 服务层分离
+
 - **RAGPipeline** - RAG 流水线
   - 查询改写 → 并行检索 → RRF 融合 → 重排 → 返回结果
-- **ParentDocumentRetriever** - 父文档检索器（基于 rag_core）
+- **DocumentReranker** - 重排业务逻辑（rag/rerank.py）
+- **ParentDocumentRetriever** - 父文档检索器
 - **查询转换** - MultiQueryGenerator
 - **结果融合** - Reciprocal Rank Fusion
 
-### 7. 配置管理 (config.py)
+### 7. 子图模块 (agent_subgraphs/) ✅ 已实现
+
+#### 7.1 公共工具 (common/)
+- **state_base.py** - TypedDict 类型安全的状态基类
+- **intent.py** - 意图理解（React 模式）- 是否调用 RAG、是否重新检索
+- **formatter.py** - 格式化输出工具（Jinja2 + Markdown）
+- **human_review.py** - 人工审核节点（LangGraph interrupt）
+
+#### 7.2 通讯录子图 (contact/)
+- 联系人管理（CRUD）
+- 邮件读取与审核
+- 外发邮件
+- 智能嗅探
+- API 客户端
+- 精美格式化展示
+
+#### 7.3 词典子图 (dictionary/)
+- 翻译、查词
+- 每日一词
+- 专业名词提炼
+- 生词本管理
+- API 客户端
+- 精美格式化展示
+
+#### 7.4 资讯分析子图 (news_analysis/)
+- 资讯获取
+- 内容分析
+- API 客户端
+- 精美格式化展示
+
+#### 7.5 研究分析子图 (research/)
+- 规划中
+
+### 8. FastAPI 后端 (backend.py)
+- POST /chat - 非流式对话
+- POST /chat/stream - 流式对话
+- 子图 API 端点
+- 人工审核交互端点（确定/取消/继续）
+
+### 9. 配置管理 (config.py)
 - 集中管理环境变量
-- 支持智谱 AI 配置
+- 智谱 AI 配置
   - ZHIPUAI_API_KEY
   - ZHIPU_EMBEDDING_MODEL（默认 embedding-3）
   - ZHIPU_RERANK_MODEL（默认 rerank-2）
   - ZHIPU_API_BASE
-- 支持本地 llama.cpp 配置
-  - VLLM_BASE_URL
-  - LLAMACPP_EMBEDDING_URL
-  - LLAMACPP_RERANKER_URL
-  - LLAMACPP_API_KEY
+- DeepSeek 配置
+  - DEEPSEEK_API_KEY
+- 本地模型配置
+  - VLLM_BASE_URL（主 LLM）
+  - LLAMACPP_EMBEDDING_URL（嵌入）
+  - LLAMACPP_RERANKER_URL（重排）
+  - LLM_API_KEY / LLAMACPP_API_KEY
 - 数据库和 Qdrant 配置
 
 ---
 
-## 🚧 待实现功能
+## 🚧 待完善功能
 
-### 1. agent_subgraphs/ - 子图模块
-- **通讯录子图**
-  - 联系人 CRUD
-  - 邮件读取与审核
-  - 外发邮件
-  - 智能嗅探
-- **智能词典子图**
-  - 翻译、查词
-  - 每日一词
-  - 专业名词提炼
-  - 生词本管理
-- **研究分析子图**
-  - 联网搜索
-  - 报告生成
-  - 引用溯源
-  - 可视化图表
+### 1. 子图模块
+- **research/** - 研究分析子图（联网搜索、报告生成、引用溯源、可视化）
 
-### 2. 公共工具层 (agent_subgraphs/common/)
-- **意图理解工具** - 标准化意图分类和信息提取
-- **人工审核工具** - LangGraph interrupt + 状态持久化
-- **格式化输出工具** - Jinja2 模板 + Markdown
-- **检查点持久化工具** - LangGraph CheckpointSaver
-- **条件路由工具** - 标准化路由机制
-- **LLM 调用工具** - 统一接口 + 重试 + Token 计数 + 降级
-- **数据库工具** - SQLAlchemy 会话管理 + 标准 CRUD
-- **状态基类工具** - TypedDict 类型安全的状态基类
-
-### 3. 其他待完善
+### 2. 其他
 - 更完善的错误处理和日志
 - 监控和指标收集
-- API 文档完善
+- API 文档完善（OpenAPI/Swagger）
 - 单元测试和集成测试
 
 ---
@@ -213,7 +256,7 @@ backend/app/
 DB_HOST=your_db_host
 DB_PORT=5432
 DB_USER=your_db_user
-DB_PASSWORD=your_db_password
+DB_PASSWORD=***
 DB_NAME=langgraph_db
 
 # Qdrant
@@ -221,8 +264,8 @@ QDRANT_URL=http://your_qdrant_host:6333
 QDRANT_API_KEY=your_qdrant_api_key
 
 # 至少配置一个 LLM
-ZHIPUAI_API_KEY=your_zhipu_key
-DEEPSEEK_API_KEY=your_deepseek_key
+ZHIPUAI_API_KEY=***
+DEEPSEEK_API_KEY=***
 ```
 
 #### 可选配置
@@ -231,7 +274,8 @@ DEEPSEEK_API_KEY=your_deepseek_key
 VLLM_BASE_URL=http://localhost:8000/v1
 LLAMACPP_EMBEDDING_URL=http://localhost:8001/v1
 LLAMACPP_RERANKER_URL=http://localhost:8002/v1
-LLAMACPP_API_KEY=your_key
+LLM_API_KEY=***
+LLAMACPP_API_KEY=***
 
 # 智谱其他配置
 ZHIPU_EMBEDDING_MODEL=embedding-3
@@ -240,6 +284,17 @@ ZHIPU_RERANK_MODEL=rerank-2
 
 ### 使用模型服务
 
+#### 生成式大模型
+```python
+from app.model_services import get_chat_service, get_all_chat_services
+
+# 自动选择可用服务（优先本地，降级智谱，再降级 DeepSeek）
+llm = get_chat_service()
+
+# 获取所有可用模型（用于多模型切换）
+all_llms = get_all_chat_services()  # Dict[str, BaseChatModel]
+```
+
 #### 嵌入服务
 ```python
 from app.model_services import get_embedding_service
@@ -254,12 +309,48 @@ vector = embeddings.embed_query("hello")
 #### 重排服务
 ```python
 from app.model_services import get_rerank_service
+from app.rag.rerank import create_document_reranker
 
-# 自动选择可用服务
-reranker = get_rerank_service()
+# 获取原始重排服务（仅计算分数）
+rerank_service = get_rerank_service()
+scores = rerank_service.compute_scores("query", ["doc1", "doc2"])
 
-# 使用
-from langchain_core.documents import Document
-docs = [Document(page_content="...")]
+# 使用业务逻辑层（完整的文档重排）
+reranker = create_document_reranker()
 sorted_docs = reranker.compress_documents(docs, "query", top_n=5)
 ```
+
+---
+
+## 📁 架构说明
+
+### 模型服务层架构
+```
+model_services/
+├── base.py              # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager
+├── chat_services.py     # 生成式大模型（纯服务层）
+├── embedding_services.py # 嵌入服务（纯服务层）
+└── rerank_services.py   # 重排服务（纯服务层）
+
+业务逻辑层
+├── rag/rerank.py        # 重排业务逻辑（使用 model_services）
+└── agent/service.py     # Agent 服务（使用 model_services）
+```
+
+### 子图架构
+```
+agent_subgraphs/
+├── common/              # 公共工具（所有子图共享）
+│   ├── state_base.py   # 状态基类
+│   ├── intent.py       # 意图理解
+│   ├── formatter.py    # 格式化输出
+│   └── human_review.py # 人工审核
+├── contact/             # 每个子图独立目录
+│   ├── state.py        # 状态定义
+│   ├── nodes.py        # 节点实现
+│   ├── graph.py        # 图构建
+│   ├── api_client.py   # API 客户端
+│   └── __init__.py
+└── dictionary/
+    └── (同 contact)
+```