docs: 重构 README 文档，整理已实现和待实现功能

- 创建 backend/app/README.md 主文档 - 整理已实现功能（带 ✅ 标记） - 列出待实现功能（带 🚧 标记） - 删除 agent_subgraphs/ 下的旧 README 文件
2026-04-24 23:05:03 +08:00
parent 8db63e7a8d
commit 851d52ed8d
5 changed files with 265 additions and 2196 deletions
--- a/backend/app/README.md
+++ b/backend/app/README.md
@@ -0,0 +1,265 @@
+# 后端模块 (backend/app/)
+
+## 项目概览
+这是一个基于 LangGraph 的个人助手系统，提供对话、工具调用、记忆管理和 RAG 检索功能。
+
+---
+
+## 📂 目录结构
+
+```
+backend/app/
+├── agent/                    # Agent 服务层
+│   ├── service.py           # AIAgentService - 主服务类
+│   ├── llm_factory.py       # LLM 工厂 - 多模型创建
+│   ├── rag_initializer.py   # RAG 工具初始化
+│   ├── history.py           # 对话历史管理
+│   └── prompts.py           # 提示词模板
+├── agent_subgraphs/           # 子图模块（规划中，仅 README）
+├── graph/                    # LangGraph 图构建
+│   ├── graph_builder.py     # 图构建器
+│   ├── graph_tools.py       # 工具定义
+│   ├── state.py            # 状态定义
+│   ├── retrieve_memory.py   # 记忆检索节点
+│   └── visualize_graph.py   # 图可视化
+├── memory/                   # 记忆模块
+│   └── mem0_client.py       # Mem0 客户端
+├── model_services/            # 模型服务（嵌入、重排等）⭐ 新增
+│   ├── __init__.py
+│   ├── README.md
+│   ├── base.py              # 基类和降级机制
+│   ├── embedding_services.py # 嵌入服务
+│   └── rerank_services.py   # 重排服务
+├── nodes/                    # LangGraph 节点实现
+│   ├── llm_call.py          # LLM 调用节点
+│   ├── tool_call.py         # 工具调用节点
+│   ├── router.py            # 路由节点
+│   ├── summarize.py         # 摘要节点
+│   ├── finalize.py          # 最终节点
+│   └── memory_trigger.py     # 记忆触发节点
+├── rag/                      # RAG 检索模块
+│   ├── pipeline.py          # RAG 流水线
+│   ├── tools.py            # RAG 工具
+│   ├── reranker.py         # 重排器（将弃用，用 model_services）
+│   ├── query_transform.py   # 查询转换
+│   └── fusion.py           # 结果融合
+├── utils/                    # 工具函数
+├── __init__.py
+├── backend.py                # FastAPI 后端入口
+├── config.py                # 配置管理
+└── logger.py                # 日志模块
+```
+
+---
+
+## ✅ 已实现功能
+
+### 1. Agent 服务 (agent/)
+- **AIAgentService** - 主服务类
+  - 接收外部 checkpointer，管理图生命周期
+  - 支持多模型动态切换
+  - 提供流式和非流式接口
+- **LLMFactory** - LLM 工厂
+  - 支持智谱 AI (glm-4.7-flash)
+  - 支持 DeepSeek (deepseek-reasoner)
+  - 支持本地模型 (vLLM/llama.cpp)
+- **对话历史** - 基于 LangGraph 状态持久化
+
+### 2. LangGraph 图 (graph/)
+- **GraphBuilder** - 图构建器
+  - 模块化节点创建，依赖注入
+  - 支持 Mem0 客户端集成
+- **状态管理**
+  - MessagesState - 对话状态（消息、token、时间、摘要轮数）
+  - GraphContext - 执行上下文（用户 ID）
+- **工具定义**
+  - get_current_temperature - 示例温度工具
+  - read_local_file - 读取本地文件
+  - read_pdf_summary - 读取 PDF
+  - read_excel_as_markdown - 读取 Excel
+  - fetch_webpage_content - 抓取网页
+
+### 3. 节点实现 (nodes/)
+- **llm_call** - LLM 调用节点
+- **tool_call** - 工具调用节点
+- **router** - 路由节点（should_continue）
+- **summarize** - 记忆摘要节点
+- **finalize** - 最终响应节点
+- **memory_trigger** - 记忆触发节点
+
+### 4. 记忆管理 (memory/)
+- **Mem0Client** - Mem0 记忆客户端
+  - 异步初始化和连接测试
+  - 支持记忆检索和添加
+  - 可集成到 LangGraph 中
+
+### 5. 模型服务 (model_services/) - ⭐ 新增
+- **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/)
+- **RAGPipeline** - RAG 流水线
+  - 查询改写 → 并行检索 → RRF 融合 → 重排 → 返回结果
+- **ParentDocumentRetriever** - 父文档检索器（基于 rag_core）
+- **查询转换** - MultiQueryGenerator
+- **结果融合** - Reciprocal Rank Fusion
+
+### 7. 配置管理 (config.py)
+- 集中管理环境变量
+- 支持智谱 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
+- 数据库和 Qdrant 配置
+
+---
+
+## 🚧 待实现功能
+
+### 1. agent_subgraphs/ - 子图模块
+- **通讯录子图**
+  - 联系人 CRUD
+  - 邮件读取与审核
+  - 外发邮件
+  - 智能嗅探
+- **智能词典子图**
+  - 翻译、查词
+  - 每日一词
+  - 专业名词提炼
+  - 生词本管理
+- **研究分析子图**
+  - 联网搜索
+  - 报告生成
+  - 引用溯源
+  - 可视化图表
+
+### 2. 公共工具层 (agent_subgraphs/common/)
+- **意图理解工具** - 标准化意图分类和信息提取
+- **人工审核工具** - LangGraph interrupt + 状态持久化
+- **格式化输出工具** - Jinja2 模板 + Markdown
+- **检查点持久化工具** - LangGraph CheckpointSaver
+- **条件路由工具** - 标准化路由机制
+- **LLM 调用工具** - 统一接口 + 重试 + Token 计数 + 降级
+- **数据库工具** - SQLAlchemy 会话管理 + 标准 CRUD
+- **状态基类工具** - TypedDict 类型安全的状态基类
+
+### 3. 其他待完善
+- 更完善的错误处理和日志
+- 监控和指标收集
+- API 文档完善
+- 单元测试和集成测试
+
+---
+
+## 🛠️ 技术栈
+
+| 层级 | 组件 | 技术选型 |
+|------|------|---------|
+| Agent 框架 | 工作流编排 | LangGraph + LangChain |
+| LLM 服务 | 模型调用 | 智谱 AI / DeepSeek / 本地模型 (llama.cpp/vLLM) |
+| Embedding | 向量嵌入 | 本地 llama.cpp / 智谱 AI |
+| Rerank | 重排序 | 本地 llama.cpp / 智谱 AI |
+| 向量数据库 | 语义检索 | Qdrant |
+| 关系数据库 | 结构化存储 | PostgreSQL |
+| 后端框架 | API 服务 | FastAPI + Uvicorn |
+| 记忆服务 | 长期记忆 | Mem0 |
+
+---
+
+## 📝 使用指南
+
+### 快速开始
+
+1. **配置环境变量**
+   复制 `.env` 文件并配置：
+   - 数据库配置（PostgreSQL）
+   - Qdrant 配置
+   - LLM 配置（智谱/DeepSeek/本地）
+   - 嵌入和重排服务配置
+
+2. **启动后端**
+   ```bash
+   cd backend
+   python -m app.backend
+   ```
+
+3. **API 接口**
+   - POST /chat - 非流式对话
+   - POST /chat/stream - 流式对话
+
+### 配置说明
+
+#### 必需配置
+```env
+# 数据库
+DB_HOST=your_db_host
+DB_PORT=5432
+DB_USER=your_db_user
+DB_PASSWORD=your_db_password
+DB_NAME=langgraph_db
+
+# Qdrant
+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
+```
+
+#### 可选配置
+```env
+# 本地模型服务
+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
+
+# 智谱其他配置
+ZHIPU_EMBEDDING_MODEL=embedding-3
+ZHIPU_RERANK_MODEL=rerank-2
+```
+
+### 使用模型服务
+
+#### 嵌入服务
+```python
+from app.model_services import get_embedding_service
+
+# 自动选择可用服务（优先本地，降级智谱）
+embeddings = get_embedding_service()
+
+# 使用
+vector = embeddings.embed_query("hello")
+```
+
+#### 重排服务
+```python
+from app.model_services import get_rerank_service
+
+# 自动选择可用服务
+reranker = get_rerank_service()
+
+# 使用
+from langchain_core.documents import Document
+docs = [Document(page_content="...")]
+sorted_docs = reranker.compress_documents(docs, "query", top_n=5)
+```