diff --git a/backend/app/README.md b/backend/app/README.md new file mode 100644 index 0000000..32475a7 --- /dev/null +++ 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) +``` diff --git a/backend/app/agent_subgraphs/README.md b/backend/app/agent_subgraphs/README.md deleted file mode 100644 index cb6d6e0..0000000 --- a/backend/app/agent_subgraphs/README.md +++ /dev/null @@ -1,744 +0,0 @@ -# LangGraph Agent - 全能个人助手系统 - -该模块负责将个人助手从"查询型"升级为"全能执行型"，通过 LangGraph 子图架构实现通讯录管理、智能词典、增强研究分析等核心功能。 - ---- - -## 🔧 公共工具与共享组件 - -三个子图共享一套统一的基础设施和通用工具，避免重复实现，确保架构一致。 - -### 公共工具架构 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ 公共工具层 (Shared Tools) │ -├─────────────────────────────────────────────────────────────────┤ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │ -│ │意图理解工具 │ │人工审核工具 │ │格式化输出 │ │状态管理│ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │ -│ │检查点持久化 │ │条件路由 │ │LLM 调用 │ │数据库 │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │ -└─────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 子图层 (Subgraphs) │ -├─────────────────────────────────────────────────────────────────┤ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ 通讯录子图 │ │ 智能词典子图│ │ 研究分析子图│ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### 公共工具详解 - -#### 1. 意图理解工具 (Intent Understanding Tool) - -**技术栈**：LangChain LLM + 少样本提示词 + 结构化输出 - -**使用方法**： -```python -from agent_subgraphs.common.intent import parse_intent - -result = parse_intent( - user_input="添加张三电话13800138000", - intent_categories=["contact", "dictionary", "research", "chat"] -) -# 返回: { -# "intent_type": "contact", -# "sub_intent": "add", -# "extracted_info": {"name": "张三", "phone": "13800138000"} -# } -``` - -**实现逻辑**： -- 使用 LLM 进行意图分类，输出结构化 JSON -- 关键词匹配兜底（如"保存"、"添加" → contact） -- 自动提取关键信息（实体、参数） -- 支持自定义意图分类器 - -**所有子图共用**：在 `agent_subgraphs/common/intent.py` - ---- - -#### 2. 人工审核工具 (Human-in-the-loop Tool) - -**技术栈**：LangGraph `interrupt()` + 状态持久化 - -**使用方法**： -```python -from agent_subgraphs.common.human_loop import human_approval_node - -def email_send_workflow(state: dict) -> dict: - # 生成邮件草稿... - state["pending_action"] = {"type": "email_send", "draft": draft} - return human_approval_node(state) # 挂起等待用户确认 -``` - -**实现逻辑**： -- 使用 `interrupt()` 触发挂起 -- 支持三种操作：确认、修改、取消 -- 超时自动取消（可配置超时时间） -- 用户反馈结构化存储 -- 支持断点续作 - -**共享位置**：`agent_subgraphs/common/human_loop.py` - -**应用场景**： -- 通讯录：邮件发送、联系人删除 -- 研究分析：信息源确认、报告结构调整 -- 智能词典：批量删除确认 - ---- - -#### 3. 格式化输出工具 (Formatting Tool) - -**技术栈**：Jinja2 模板 + Markdown 生成 - -**使用方法**： -```python -from agent_subgraphs.common.format import format_output - -result = format_output( - template="contact_result", - data={"contact": contact_data, "action": "added"} -) -``` - -**实现逻辑**： -- 预定义输出模板库 -- 支持 Markdown、HTML、纯文本三种格式 -- 自动处理列表、表格等复杂结构 -- 支持用户自定义模板 - -**共享位置**：`agent_subgraphs/common/format.py` - ---- - -#### 4. 检查点持久化工具 (Checkpoint Tool) - -**技术栈**：LangGraph CheckpointSaver + SQLite / PostgreSQL - -**使用方法**： -```python -from agent_subgraphs.common.checkpoint import get_checkpointer - -checkpointer = get_checkpointer(db_url="sqlite:///checkpoints.db") - -# 在图编译时传入 -graph = workflow.compile(checkpointer=checkpointer) -``` - -**实现逻辑**： -- 自动在每个节点执行后保存检查点 -- 支持断点续作 -- 状态版本管理 -- 支持查询历史状态 - -**共享位置**：`agent_subgraphs/common/checkpoint.py` - ---- - -#### 5. 条件路由工具 (Conditional Routing Tool) - -**技术栈**：LangGraph 条件边 + 路由函数 - -**使用方法**： -```python -from agent_subgraphs.common.routing import route_by_intent - -def my_router(state: dict) -> str: - return route_by_intent( - state, - { - "translate": "translate_node", - "lookup": "lookup_node", - } - ) -``` - -**实现逻辑**： -- 标准化的意图路由 -- 支持复杂条件判断 -- 路由函数可组合 -- 自动处理默认分支 - -**共享位置**：`agent_subgraphs/common/routing.py` - ---- - -#### 6. LLM 调用工具 (LLM Invocation Tool) - -**技术栈**：LangChain ChatOpenAI + 重试 + 流式输出 - -**使用方法**： -```python -from agent_subgraphs.common.llm import call_llm, call_llm_stream - -# 同步调用 -result = call_llm(prompt="翻译这句话", system_prompt="你是翻译官") - -# 流式调用 -async for chunk in call_llm_stream(prompt="写一篇文章"): - print(chunk.content, end="") -``` - -**实现逻辑**： -- 统一的 LLM 调用接口 -- 自动重试（指数退避） -- 支持流式和非流式 -- Token 计数和监控 -- 模型 fallback 机制 - -**共享位置**：`agent_subgraphs/common/llm.py` - ---- - -#### 7. 数据库工具 (Database Tool) - -**技术栈**：SQLAlchemy + PostgreSQL / SQLite - -**使用方法**： -```python -from agent_subgraphs.common.db import get_db, add_record, query_records - -# 获取 session -with get_db() as db: - # 添加记录 - add_record(db, Contact, {"name": "张三", "phone": "13800138000"}) - # 查询记录 - contacts = query_records(db, Contact, filters={"name": "张三"}) -``` - -**实现逻辑**： -- 统一的 ORM 会话管理 -- 标准 CRUD 操作封装 -- 支持事务 -- 自动错误处理 - -**共享位置**：`agent_subgraphs/common/db.py` - ---- - -#### 8. 状态基类工具 (State Base Classes) - -**技术栈**：TypedDict + 类型注解 - -**使用方法**： -```python -from agent_subgraphs.common.state import BaseSubgraphState - -class ContactState(BaseSubgraphState): - # 继承基础字段 - contact_data: Optional[dict] - # 自定义字段... -``` - -**实现逻辑**： -- 预定义基础状态字段 -- 类型安全 -- 状态验证 -- 状态合并辅助函数 - -**共享位置**：`agent_subgraphs/common/state.py` - ---- - -### 公共工具目录结构 - -``` -agent_subgraphs/ -├── common/ # 公共工具层 -│ ├── __init__.py -│ ├── intent.py # 意图理解工具 -│ ├── human_loop.py # 人工审核工具 -│ ├── format.py # 格式化输出工具 -│ ├── checkpoint.py # 检查点持久化工具 -│ ├── routing.py # 条件路由工具 -│ ├── llm.py # LLM 调用工具 -│ ├── db.py # 数据库工具 -│ ├── state.py # 状态基类 -│ └── prompts/ # 公共提示词模板 -│ ├── intent.j2 -│ └── format.j2 -├── contact/ # 通讯录子图（简化版，使用公共工具） -├── dictionary/ # 智能词典子图（简化版，使用公共工具） -└── research/ # 研究分析子图（简化版，使用公共工具） -``` - ---- - -### 公共配置项 - -所有子图共享的配置项（在 `.env` 中配置）： - -```env -# LLM 配置 -LLM_PROVIDER=deepseek -LLM_MODEL=deepseek-chat -LLM_API_KEY=*** -LLM_TEMPERATURE=0.7 -LLM_MAX_TOKENS=2000 - -# 数据库配置 -DB_URL=postgresql://user:pass@localhost/agent_db - -# 检查点配置 -CHECKPOINT_DB_URL=sqlite:///checkpoints.db - -# 人工审核配置 -HUMAN_LOOP_TIMEOUT=3600 - -# 格式化配置 -DEFAULT_OUTPUT_FORMAT=markdown -``` - ---- - -### 使用公共工具开发新子图 - -创建新子图的步骤： - -1. **继承状态基类** -```python -from agent_subgraphs.common.state import BaseSubgraphState - -class MySubgraphState(BaseSubgraphState): - my_field: str -``` - -2. **使用公共意图理解** -```python -from agent_subgraphs.common.intent import parse_intent - -def intent_node(state: MySubgraphState) -> MySubgraphState: - result = parse_intent(state["user_input"], ["my_intents]) - state.update(result) - return state -``` - -3. **使用公共人工审核** -```python -from agent_subgraphs.common.human_loop import human_approval_node - -def my_workflow(state: MySubgraphState) -> MySubgraphState: - return human_approval_node(state) -``` - -4. **使用公共格式化输出** -```python -from agent_subgraphs.common.format import format_output - -def format_node(state: MySubgraphState) -> MySubgraphState: - state["final_result"] = format_output("my_template", state) - return state -``` - ---- - -## 📑 目录导航 - -- [核心功能](#-核心功能) - 三大子图功能和技术特性 -- [技术架构](#️-技术架构) - 技术栈、子图架构图、数据流 -- [子图设计](#-子图设计) - 三个核心子图的详细说明 -- [状态管理](#-状态管理) - 主状态和子状态定义 -- [安全与边界](#️-安全与边界) - 安全机制和边界控制 -- [快速开始](#-快速开始) - 开发环境搭建 -- [实现指南](#-实现指南) - 子图开发、工具集成 -- [未来规划](#-未来规划) - 多模态、流式输出等 - ---- - -## 🎯 核心功能 - -### 三大核心子图 - -| 子图模块 | 功能概述 | 关键特性 | -|---------|---------|---------| -| **通讯录子图** | 联系人 CRUD、邮件读取与审核、外发邮件、智能嗅探 | 人工审核强制、敏感信息加密、IMAP 邮箱绑定 | -| **智能词典子图** | 翻译、查词、每日一词、专业名词提炼、生词本管理 | 联想记忆法、艾宾浩斯遗忘曲线、Anki 导出 | -| **研究分析子图** | 联网搜索、报告生成、引用溯源、可视化图表 | 人工干预点、可定制报告结构、引用验证 | - -### 通用机制 - -- ✅ **人工审核（Human-in-the-loop）**：通用节点，用于邮件发送、重要操作前的确认 -- ✅ **自动联系人嗅探**：对话中出现"人名+联系方式"时，主动询问是否保存 -- ✅ **流式输出**：所有 LLM 生成内容均采用流式传输，提升交互体验 -- ✅ **长期记忆**：PostgreSQL + pgvector 实现持久化记忆和语义检索 - ---- - -## 🏗️ 技术架构 - -### 技术栈总览 - -| 层级 | 组件 | 技术选型 | 版本 | 说明 | -|------|------|---------|------|------| -| **Agent 框架** | 工作流编排 | LangGraph + LangChain | latest | 子图架构，状态机驱动 | -| **LLM 服务** | 模型调用 | 智谱 AI / DeepSeek / 本地模型 | latest | 多模型路由 | -| **向量数据库** | 语义检索 | Qdrant / pgvector | v1.12+ | 对话记忆、联系人语义索引 | -| **关系数据库** | 结构化存储 | PostgreSQL | v16 | 联系人、生词本、邮件配置 | -| **邮件协议** | IMAP/SMTP | `imaplib` / `smtplib` | 内置 | 邮件读取和发送 | -| **后端框架** | API 服务 | FastAPI + Uvicorn | v0.115+ | 子图执行、状态管理 | - -### 主图架构流程图 - -```mermaid -graph TB - Start[START] --> Intent[意图分类节点] - - Intent -->|contact| ContactSubgraph[通讯录子图] - Intent -->|dictionary| DictSubgraph[智能词典子图] - Intent -->|research| ResearchSubgraph[研究分析子图] - Intent -->|chat| ChatNode[普通对话节点] - - ContactSubgraph --> Final[最终响应] - DictSubgraph --> Final - ResearchSubgraph --> Final - ChatNode --> Final - - Final --> End[END] - - style Start fill:#e1f5ff - style Intent fill:#fff4e1 - style ContactSubgraph fill:#e8f5e9 - style DictSubgraph fill:#f3e5f5 - style ResearchSubgraph fill:#ffebee - style Final fill:#fff9c4 -``` - -### 子图架构总览 - -```mermaid -graph TB - MainGraph[主图
MainState] - - MainGraph --> ContactSub[通讯录子图
ContactSubState] - MainGraph --> DictSub[词典子图
DictSubState] - MainGraph --> ResearchSub[研究子图
ResearchSubState] - - ContactSub --> ContactNodes[内部节点
parse_intent
add_contact
list_contacts
generate_draft
human_approval
send_email] - DictSub --> DictNodes[内部节点
translate
lookup
extract_terms
daily_word] - ResearchSub --> ResearchNodes[内部节点
decompose
web_search
extract_info
generate_report] - - ContactNodes --> PG[(PostgreSQL
联系人)] - DictNodes --> PG2[(PostgreSQL
生词本)] - ResearchNodes --> Qdrant[(Qdrant
向量检索)] - - style MainGraph fill:#e1f5ff - style ContactSub fill:#e8f5e9 - style DictSub fill:#f3e5f5 - style ResearchSub fill:#ffebee -``` - -### 状态传递机制 - -``` -主状态 (MainState) - │ - ├─→ input: {user_input: messages[-1].content} - │ - ▼ -子图状态 (SubState) - │ - ├─→ 内部处理... - │ - ▼ -output: {messages: [AIMessage(final_result)], last_action: sub_state} - │ - ▼ -主状态更新 -``` - ---- - -## 📂 项目结构 - -``` -Agent1/ -├── agent_subgraphs/ # LangGraph 子图模块 -│ ├── __init__.py -│ ├── contact/ # 通讯录子图 -│ │ ├── README.md -│ │ ├── __init__.py -│ │ ├── state.py # 子图状态定义 -│ │ ├── graph.py # 子图构建器 -│ │ ├── nodes.py # 子图节点实现 -│ │ ├── tools.py # 子图工具集 -│ │ └── prompts.py # 提示词模板 -│ ├── dictionary/ # 智能词典子图 -│ │ ├── README.md -│ │ ├── __init__.py -│ │ ├── state.py -│ │ ├── graph.py -│ │ ├── nodes.py -│ │ ├── tools.py -│ │ └── prompts.py -│ └── research/ # 研究分析子图 -│ ├── README.md -│ ├── __init__.py -│ ├── state.py -│ ├── graph.py -│ ├── nodes.py -│ ├── tools.py -│ └── prompts.py -├── backend/ # 现有后端模块 -│ └── app/ -│ ├── graph/ # 主图构建 -│ │ ├── graph_builder.py # 主图 + 子图集成 -│ │ └── state.py # 主状态定义 -│ └── ... -└── ... -``` - ---- - -## 🎯 状态管理 - -### 主状态定义 (MainState) - -```python -from typing import TypedDict, List, Optional, Annotated -from langchain_core.messages import BaseMessage -from langgraph.graph import add_messages - -class MainState(TypedDict): - messages: Annotated[List[BaseMessage], add_messages] - intent: str # 顶层意图：contact / dictionary / research / chat - sub_intent: str # 细分意图 - - # 工具通用 - tool_call: Optional[dict] # 当前要执行的工具调用 - tool_result: str - - # 控制流 - next_node: str - human_feedback: Optional[str] # 用于挂起重启 - - # 子图结果 - last_contact_action: Optional[dict] - last_dict_action: Optional[dict] - last_research_action: Optional[dict] -``` - -### 状态映射函数 - -```python -# 通讯录子图输入映射 -def contact_input_mapper(state: MainState) -> dict: - return { - "user_input": state["messages"][-1].content, - } - -# 通讯录子图输出映射 -def contact_output_mapper(sub_state: dict, original: MainState) -> dict: - return { - "messages": [AIMessage(content=sub_state["final_result"])], - "last_contact_action": sub_state, - } -``` - ---- - -## 🎯 主图实现 - -### 主图构建器 - -```python -from langgraph.graph import StateGraph, START, END -from agent_subgraphs.contact import build_contact_subgraph -from agent_subgraphs.dictionary import build_dict_subgraph -from agent_subgraphs.research import build_research_subgraph - -def build_main_graph() -> StateGraph: - main_graph = StateGraph(MainState) - - # 添加子图节点 - main_graph.add_node( - "contact_module", - build_contact_subgraph(), - input=contact_input_mapper, - output=contact_output_mapper, - ) - main_graph.add_node( - "dict_module", - build_dict_subgraph(), - input=dict_input_mapper, - output=dict_output_mapper, - ) - main_graph.add_node( - "research_module", - build_research_subgraph(), - input=research_input_mapper, - output=research_output_mapper, - ) - main_graph.add_node("chat_node", chat_node) - main_graph.add_node("final_response", final_response_node) - - # 主图路由 - main_graph.add_conditional_edges( - START, - route_main_intent, - { - "contact": "contact_module", - "dictionary": "dict_module", - "research": "research_module", - "chat": "chat_node", - } - ) - - # 所有路径汇聚到最终响应 - main_graph.add_edge("contact_module", "final_response") - main_graph.add_edge("dict_module", "final_response") - main_graph.add_edge("research_module", "final_response") - main_graph.add_edge("chat_node", "final_response") - main_graph.add_edge("final_response", END) - - return main_graph.compile() - -def route_main_intent(state: MainState) -> str: - """顶层意图分类""" - user_input = state["messages"][-1].content - # 使用 LLM 分类 - # 返回 contact / dictionary / research / chat -``` - ---- - -## 🔒 安全与边界 - -### 安全机制 - -| 风险点 | 对策 | 实现位置 | -|--------|------|---------| -| 邮箱密码泄露 | 使用环境变量存储，永不写入日志 | `agent_subgraphs/contact/tools.py` | -| 恶意邮件发送 | 强制人工审核，单日发送数量限制 | 人工审核节点 | -| 联系人隐私 | 向量检索结果脱敏展示，仅交互时完整显示 | 通讯录子图节点 | -| 搜索内容安全 | 过滤成人内容，屏蔽高风险域名 | 研究子图搜索工具 | -| 敏感词输出 | 流式输出后处理过滤 | 最终响应节点 | - -### 人工审核节点 - -```python -from langgraph.graph import interrupt - -def human_approval_node(state: dict) -> dict: - """人工审核节点：挂起图，等待外部输入""" - pending_action = state["pending_action"] - - # 触发中断，等待外部通过 update_state 传入 human_feedback - return interrupt( - { - "type": "human_approval", - "message": f"请确认操作：{pending_action}", - "options": ["确认", "修改", "取消"], - } - ) -``` - ---- - -## 🚀 快速开始 - -### 环境配置 - -```bash -# 激活虚拟环境 -source venv/bin/activate - -# 安装依赖（新增） -pip install langgraph langchain-experimental -``` - -### 配置文件 - -在 `.env` 中新增： - -```env -# 通讯录模块 -IMAP_SERVER=imap.qq.com -IMAP_PORT=993 -SMTP_SERVER=smtp.qq.com -SMTP_PORT=587 -EMAIL_USER=your_email@qq.com -EMAIL_PASSWORD=your_auth_code - -# 词典模块 -DEEPL_API_KEY=your_deepl_key -YOUDAO_API_KEY=your_youdao_key - -# 研究模块 -SEARCH_API_KEY=your_search_key -``` - -### 运行测试 - -```python -from backend.app.graph.graph_builder import build_main_graph - -# 编译主图 -graph = build_main_graph() - -# 调用子图 -result = graph.invoke({ - "messages": [HumanMessage(content="添加张三电话 13800138000")] -}) - -print(result["messages"][-1].content) -``` - ---- - -## 📖 实现指南 - -### 添加新子图 - -1. 在 `agent_subgraphs/` 下创建新文件夹 -2. 创建 `state.py` 定义子图状态 -3. 创建 `nodes.py` 实现子图节点 -4. 创建 `graph.py` 构建子图 -5. 在主图 `graph_builder.py` 中注册新子图 - -### 子图开发最佳实践 - -- ✅ 子图拥有独立的状态，避免与主状态命名冲突 -- ✅ 使用 `input`/`output` 映射函数进行状态转换 -- ✅ 子图内部节点之间直接连接，主图只负责路由到子图入口 -- ✅ 将工具封装在子图内部，通过节点调用 -- ✅ 提供子图级别的单元测试 - ---- - -## 🎯 未来规划 - -### Phase 1: 基础功能（当前） - -- [ ] 通讯录子图完整实现 -- [ ] 智能词典子图完整实现 -- [ ] 研究分析子图完整实现 -- [ ] 主图集成和状态管理 - -### Phase 2: 增强功能 - -- [ ] 流式输出改造（所有 LLM 调用） -- [ ] 多模态语音输入（STT） -- [ ] 可视化图表生成 -- [ ] Anki 生词本导出 - -### Phase 3: 高级特性 - -- [ ] 智能家居控制子图 -- [ ] 日程管理子图 -- [ ] 更多工具集成 - ---- - -## 📚 相关文档 - -- [通讯录子图 README](./contact/README.md) - 详细了解通讯录模块 -- [智能词典子图 README](./dictionary/README.md) - 详细了解词典模块 -- [研究分析子图 README](./research/README.md) - 详细了解研究模块 -- [主项目 README](../README.md) - 了解整体架构 - diff --git a/backend/app/agent_subgraphs/contact/README.md b/backend/app/agent_subgraphs/contact/README.md deleted file mode 100644 index cc0c222..0000000 --- a/backend/app/agent_subgraphs/contact/README.md +++ /dev/null @@ -1,391 +0,0 @@ -# 通讯录子图 (Contact Subgraph) - -该子图负责处理通讯录管理、邮件读取与发送等功能，基于 LangGraph 状态机编排多阶段工作流，支持联系人 CRUD、IMAP 邮箱绑定、邮件审核发送等核心能力。子图设计遵循"安全优先、审核强制、隐私保护"原则，通过敏感信息加密和人工审核保障数据安全。 - -> **使用公共工具**：意图理解、人工审核、格式化输出、检查点持久化、条件路由、LLM 调用、数据库工具、状态基类 - ---- - -## 🎯 核心架构 - -### 技术栈 - -| 层级 | 组件 | 说明 | -|:-----|:-----|:-----| -| **编排框架** | LangGraph StateGraph | 状态机驱动的子图工作流编排，支持中断恢复 | -| **LLM 服务** | 智谱 AI / DeepSeek API | 意图理解、邮件草稿生成、联系人信息提取（使用公共 LLM 工具） | -| **关系存储** | PostgreSQL | 联系人、邮箱配置持久化（使用公共数据库工具） | -| **邮件协议** | imaplib / smtplib | 邮件读取与发送 | -| **加密存储** | cryptography | 邮箱密码等敏感信息加密 | - -### 子图分层架构 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ 主图 (Main Graph) │ -└──────────────────────────────┬──────────────────────────────────┘ - │ 状态映射 / 结果聚合 - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 通讯录子图接口层 │ -│ - 状态转换：主状态 ↔ 子图状态（使用公共状态基类） │ -│ - 错误传播与优雅降级 │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 工作流编排层 │ -│ - 节点调度与条件路由（使用公共路由工具） │ -│ - 人工审核节点暂停/恢复管理（使用公共审核工具） │ -│ - 状态持久化与检查点（使用公共检查点工具） │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 节点层 │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ -│ │意图理解 │ │联系人CRUD│ │邮件读取 │ │草稿生成 │ │人工审核│ │ -│ │(公共工具)│ │ │ │ │ │ │ │(公共) │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │邮件发送 │ │智能嗅探 │ │格式输出 │ │ -│ │ │ │ │ │(公共) │ │ -│ └──────────┘ └──────────┘ └──────────┘ │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 工具层 │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │数据库工具│ │IMAP工具 │ │SMTP工具 │ │加密工具 │ │ -│ │(公共) │ │ │ │ │ │ │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### 数据流总览 - -通讯录子图根据意图类型分支执行，关键操作前强制人工审核。 - -``` -用户请求 - │ - ▼ -┌─────────────┐ -│ 意图理解 │ ← 使用公共意图理解工具 -└──────┬──────┘ - │ - ├──────────┬──────────┬──────────┬──────────┐ - ▼ ▼ ▼ ▼ ▼ - 联系人CRUD 邮件读取 邮件发送 智能嗅探 列表查询 - │ │ │ │ │ - ▼ ▼ ▼ ▼ ▼ - 数据库操作 IMAP读取 草稿生成 信息提取 结果展示 - │ │ │ │ │ - │ │ ▼ │ │ - │ │ 人工审核 │ │ - │ │ (公共) │ │ - │ │ │ │ │ - │ │ ▼ │ │ - │ │ SMTP发送 │ │ - │ │ │ │ │ - └──────────┴──────────┴──────────┴──────────┘ - │ - ▼ - 格式输出 ← 使用公共格式化工具 - │ - ▼ - 返回主图 -``` - ---- - -## 📂 模块与文件结构 - -``` -app/contact/ -├── __init__.py -├── graph.py # 子图构建入口，定义状态图与路由 -├── state.py # 子图状态定义（继承公共状态基类） -├── nodes/ # 节点实现 -│ ├── __init__.py -│ ├── crud.py # 联系人CRUD节点 -│ ├── email_read.py # 邮件读取节点 -│ ├── draft.py # 邮件草稿生成节点 -│ ├── email_send.py # 邮件发送节点 -│ └── sniff.py # 智能嗅探节点 -├── tools/ # 子图特有工具集 -│ ├── imap.py # IMAP邮件读取工具 -│ ├── smtp.py # SMTP邮件发送工具 -│ └── crypto.py # 敏感信息加密工具 -└── persistence/ # （使用公共检查点工具，无需单独实现） -``` - -> **注意**：以下模块使用公共工具，无需单独实现： -> - 意图理解节点 → 使用 `agent_subgraphs.common.intent` -> - 人工审核节点 → 使用 `agent_subgraphs.common.human_loop` -> - 格式输出节点 → 使用 `agent_subgraphs.common.format` -> - 检查点持久化 → 使用 `agent_subgraphs.common.checkpoint` -> - 条件路由 → 使用 `agent_subgraphs.common.routing` -> - LLM 调用 → 使用 `agent_subgraphs.common.llm` -> - 数据库操作 → 使用 `agent_subgraphs.common.db` - ---- - -## 🎯 演进路线与核心机制 - -### Level 1：基础联系人管理 - -**核心机制**：联系人 CRUD 操作 + 基础列表查询。 - -- 使用 LLM 解析用户请求，提取联系人信息（姓名、电话、邮箱等）。 -- 数据库存储联系人信息，支持增删改查。 -- 支持按姓名模糊查询和列表展示。 - -**适用场景**：保存联系人、查询电话、修改信息等基础操作。 - -**实现指引**：意图理解节点识别 CRUD 类型，路由到对应节点。 - -### Level 2：邮件读取与基础发送 - -**核心机制**：IMAP 邮箱绑定 + 邮件列表读取 + 简单发送。 - -- 支持配置多个 IMAP/SMTP 邮箱账户。 -- 读取收件箱邮件列表，展示主题、发件人、时间。 -- 生成邮件草稿，人工审核后发送。 - -**适用场景**：查收邮件、发送简单邮件。 - -**实现指引**：邮箱密码加密存储，发送前强制人工审核。 - -### Level 3：智能嗅探与上下文感知 - -**核心机制**：对话中自动识别联系人信息，主动询问是否保存。 - -- 在任意对话中监听"人名+联系方式"模式。 -- 识别到潜在联系人信息时，主动询问用户是否保存。 -- 支持确认后自动创建联系人记录。 - -**适用场景**：日常对话中自然保存联系人。 - -**实现指引**：与主图协作，在对话节点后插入嗅探检查点。 - -### Level 4：邮件智能处理 - -**核心机制**：邮件内容理解 + 智能回复建议 + 批量处理。 - -- 读取邮件全文，理解内容意图。 -- 基于邮件内容生成智能回复草稿。 -- 支持邮件分类、标记、归档操作。 - -**适用场景**：邮件管理、智能回复。 - -**实现指引**：利用 LLM 进行邮件内容理解和回复生成。 - -### Level 5：通讯录智能助理 - -**核心机制**：联系人关系图谱 + 智能推荐 + 多模态交互。 - -- 构建联系人关系网络，识别社交圈子。 -- 基于历史交互推荐联系人。 -- 支持名片扫描、语音输入等多模态交互。 - -**适用场景**：深度联系人管理、智能社交助理。 - ---- - -## 🔧 核心组件详解 - -### 1. 意图理解节点 - -**职责**：接收用户原始请求，区分联系人 CRUD、邮件读取、邮件发送、智能嗅探等意图类型。 - -**输入**：用户自然语言请求。 - -**输出**： -- `intent_type`：意图类别枚举（contact_crud / email_read / email_send / sniff / list）。 -- `extracted_info`：提取的关键信息（联系人姓名、邮件主题等）。 - -**实现要点**： -- 使用 LLM 进行少样本分类，输出结构化 JSON。 -- 关键词匹配兜底（如"保存"、"添加" → contact_crud）。 - -### 2. 联系人 CRUD 节点 - -**职责**：执行联系人的增删改查操作，与数据库交互。 - -**输入**：意图类型、提取的联系人信息。 - -**输出**： -- `operation_result`：操作结果（成功/失败）。 -- `contact_data`：操作后的联系人数据。 - -**实现要点**： -- 使用 SQLAlchemy 与 PostgreSQL 交互。 -- 支持部分字段更新（如只修改电话）。 -- 删除操作前二次确认。 - -### 3. 邮件读取节点 - -**职责**：通过 IMAP 协议连接邮箱，读取邮件列表或单封邮件详情。 - -**输入**：邮箱配置、读取指令（列表/详情）。 - -**输出**： -- `email_list`：邮件列表（主题、发件人、时间）。 -- `email_content`：单封邮件详情（如需要）。 - -**实现要点**： -- 支持配置多个邮箱账户。 -- 密码使用 cryptography 加密存储。 -- 分页读取邮件列表，避免一次性加载过多。 - -### 4. 邮件草稿生成节点 - -**职责**：根据用户指令生成邮件草稿，包含收件人、主题、正文。 - -**输入**：用户发送邮件的指令、上下文。 - -**输出**： -- `draft_recipient`：收件人邮箱。 -- `draft_subject`：邮件主题。 -- `draft_body`：邮件正文。 - -**实现要点**： -- 使用 LLM 生成自然流畅的邮件内容。 -- 从通讯录智能匹配收件人邮箱。 -- 支持多语言邮件生成。 - -### 5. 人工审核节点 - -**职责**：在邮件发送、联系人删除等关键操作前挂起，等待用户确认。 - -**输入**：待审核内容（邮件草稿、删除确认等）。 - -**输出**： -- `user_approved`：是否通过审核。 -- `user_modification`：用户修改内容（如有）。 - -**实现要点**： -- 使用 LangGraph `interrupt` 机制实现挂起。 -- 支持用户修改草稿后再次审核。 -- 超时自动取消操作。 - -### 6. 邮件发送节点 - -**职责**：审核通过后，通过 SMTP 协议发送邮件。 - -**输入**：审核通过的邮件草稿。 - -**输出**： -- `send_result`：发送结果。 -- `sent_time`：发送时间。 - -**实现要点**： -- 使用 smtplib 发送邮件。 -- 支持抄送、密送。 -- 发送失败重试机制。 - -### 7. 智能嗅探节点 - -**职责**：在对话中检测联系人信息，主动询问是否保存。 - -**输入**：用户对话历史。 - -**输出**： -- `detected_contact`：检测到的潜在联系人信息。 -- `should_ask`：是否应该询问用户。 - -**实现要点**： -- 使用 NER 识别实体（人名、电话、邮箱）。 -- 与已有联系人去重。 -- 询问用户确认后自动保存。 - ---- - -## 🔀 条件路由详解 - -### 入口路由：意图分支 - -- **位置**：意图理解节点之后。 -- **条件**： - - `intent_type == "contact_crud"` → 联系人 CRUD 节点。 - - `intent_type == "email_read"` → 邮件读取节点。 - - `intent_type == "email_send"` → 草稿生成节点。 - - `intent_type == "sniff"` → 智能嗅探节点。 - - `intent_type == "list"` → 列表查询节点。 - -### 审核路由 - -- **位置**：人工审核节点之后。 -- **条件**： - - `user_approved == True` → 执行操作（发送/删除等）。 - - `user_approved == False` 且 `user_modification` 存在 → 返回草稿生成节点。 - - `user_approved == False` 且无修改 → 取消操作。 - -### 嗅探路由 - -- **位置**：智能嗅探节点之后。 -- **条件**： - - `should_ask == True` → 询问用户确认。 - - `should_ask == False` → 直接结束，不打扰用户。 - ---- - -## 📊 状态设计 - -### 状态结构概览 - -| 分组 | 字段 | 类型 | 说明 | -|:-----|:-----|:-----|:-----| -| **输入** | `user_input` | `str` | 用户原始请求 | -| **意图** | `intent_type` | `str` | 意图类别 | -| | `extracted_info` | `dict` | 提取的关键信息 | -| **联系人** | `contact_data` | `dict` | 联系人数据 | -| | `contact_list` | `list[dict]` | 联系人列表 | -| **邮件** | `email_config` | `dict` | 邮箱配置 | -| | `email_list` | `list[dict]` | 邮件列表 | -| | `draft_recipient` | `str` | 草稿收件人 | -| | `draft_subject` | `str` | 草稿主题 | -| | `draft_body` | `str` | 草稿正文 | -| **审核** | `pending_action` | `dict` | 待审核操作 | -| | `user_approved` | `bool` | 是否通过审核 | -| | `user_modification` | `dict` | 用户修改 | -| **控制流** | `current_phase` | `str` | 当前执行阶段 | -| | `next_node` | `str` | 下一节点名称 | -| | `interrupt_point` | `str` | 中断点标识 | -| **输出** | `final_result` | `str` | 最终结果 | - ---- - -## 🔄 工作流程与中断恢复 - -### 邮件发送流程 - -| 步骤 | 节点 | 人工干预 | -|:-----|:-----|:---------| -| 1 | 意图理解 | 否 | -| 2 | 草稿生成 | 否 | -| 3 | 人工审核 | **是** | -| 4 | 邮件发送 | 否 | -| 5 | 格式输出 | 否 | - -### 联系人保存流程 - -| 步骤 | 节点 | 人工干预 | -|:-----|:-----|:---------| -| 1 | 意图理解 | 否 | -| 2 | 联系人 CRUD | 否 | -| 3 | 格式输出 | 否 | - -### 智能嗅探流程 - -| 步骤 | 节点 | 人工干预 | -|:-----|:-----|:---------| -| 1 | 智能嗅探 | 否 | -| 2 | 询问确认 | **是** | -| 3 | 联系人 CRUD | 否 | - -### 中断恢复机制 - -子图支持在人工审核节点中断，恢复时从审核点继续执行。 diff --git a/backend/app/agent_subgraphs/dictionary/README.md b/backend/app/agent_subgraphs/dictionary/README.md deleted file mode 100644 index 5fbd3df..0000000 --- a/backend/app/agent_subgraphs/dictionary/README.md +++ /dev/null @@ -1,428 +0,0 @@ -# 智能词典子图 (Dictionary Subgraph) - -该子图负责处理翻译、查词、生词本管理等功能，基于 LangGraph 状态机编排多阶段学习流程，支持联想记忆法、艾宾浩斯遗忘曲线复习、Anki 导出等核心能力。子图设计遵循"高效学习、科学复习、持久记忆"原则。 - -> **使用公共工具**：意图理解、格式化输出、检查点持久化、条件路由、LLM 调用、数据库工具、状态基类 - ---- - -## 🎯 核心架构 - -### 技术栈 - -| 层级 | 组件 | 说明 | -|:-----|:-----|:-----| -| **编排框架** | LangGraph StateGraph | 状态机驱动的子图工作流编排 | -| **LLM 服务** | 智谱 AI / DeepSeek API | 翻译、释义生成、联想记忆、专业名词提炼（使用公共 LLM 工具） | -| **翻译服务** | DeepL / 有道 API | 高质量机器翻译 | -| **关系存储** | PostgreSQL | 生词本、复习记录持久化（使用公共数据库工具） | -| **导出工具** | csv / Anki APKG | 生词本导出格式 | - -### 子图分层架构 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ 主图 (Main Graph) │ -└──────────────────────────────┬──────────────────────────────────┘ - │ 状态映射 / 结果聚合 - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 智能词典子图接口层 │ -│ - 状态转换：主状态 ↔ 子图状态（使用公共状态基类） │ -│ - 错误传播与优雅降级 │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 工作流编排层 │ -│ - 节点调度与条件路由（使用公共路由工具） │ -│ - 复习计划计算 │ -│ - 状态持久化与检查点（使用公共检查点工具） │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 节点层 │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ -│ │意图理解 │ │翻译节点 │ │查词节点 │ │每日一词 │ │专业提炼│ │ -│ │(公共工具)│ │ │ │ │ │ │ │ │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │生词管理 │ │复习计划 │ │联想记忆 │ │格式输出 │ │ -│ │ │ │ │ │ │ │(公共) │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 工具层 │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │翻译API │ │词典API │ │数据库工具│ │艾宾浩斯 │ │ -│ │ │ │ │ │(公共) │ │ │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### 数据流总览 - -智能词典子图根据学习意图分支执行，支持查词、翻译、复习等多种学习模式。 - -``` -用户请求 - │ - ▼ -┌─────────────┐ -│ 意图理解 │ ← 使用公共意图理解工具 -└──────┬──────┘ - │ - ├──────────┬──────────┬──────────┬──────────┬──────────┐ - ▼ ▼ ▼ ▼ ▼ ▼ - 翻译 查词 每日一词 专业提炼 生词管理 复习计划 - │ │ │ │ │ │ - ▼ ▼ ▼ ▼ ▼ ▼ - 翻译API 词典API 每日推荐 术语提取 增删改查 复习计算 - │ │ │ │ │ │ - │ ▼ │ │ │ │ - │ 联想记忆 │ │ │ │ - │ │ │ │ │ │ - └──────────┴──────────┴──────────┴──────────┴──────────┘ - │ - ▼ - 格式输出 ← 使用公共格式化工具 - │ - ├──────────┐ - │ │ - ▼ ▼ - 保存生词 Anki导出 - │ │ - └──────────┘ - │ - ▼ - 返回主图 -``` - ---- - -## 📂 模块与文件结构 - -``` -app/dictionary/ -├── __init__.py -├── graph.py # 子图构建入口，定义状态图与路由 -├── state.py # 子图状态定义（继承公共状态基类） -├── nodes/ # 节点实现 -│ ├── __init__.py -│ ├── translate.py # 翻译节点 -│ ├── lookup.py # 查词节点 -│ ├── daily_word.py # 每日一词节点 -│ ├── extract_terms.py # 专业名词提炼节点 -│ ├── vocab.py # 生词本管理节点 -│ ├── review.py # 复习计划节点 -│ ├── association.py # 联想记忆节点 -│ └── export.py # Anki导出节点 -├── tools/ # 子图特有工具集 -│ ├── translate_api.py # 翻译API工具 -│ ├── dictionary_api.py # 词典API工具 -│ ├── ebinghaus.py # 艾宾浩斯遗忘曲线工具 -│ └── anki.py # Anki导出工具 -└── persistence/ # （使用公共检查点工具，无需单独实现） -``` - -> **注意**：以下模块使用公共工具，无需单独实现： -> - 意图理解节点 → 使用 `agent_subgraphs.common.intent` -> - 格式输出节点 → 使用 `agent_subgraphs.common.format` -> - 检查点持久化 → 使用 `agent_subgraphs.common.checkpoint` -> - 条件路由 → 使用 `agent_subgraphs.common.routing` -> - LLM 调用 → 使用 `agent_subgraphs.common.llm` -> - 数据库操作 → 使用 `agent_subgraphs.common.db` - ---- - -## 🎯 演进路线与核心机制 - -### Level 1：基础翻译与查词 - -**核心机制**：调用翻译/词典 API，展示基础释义。 - -- 支持中↔英、中↔日等多语言互译。 -- 提供单词词性、释义、例句。 -- 基础生词本功能（添加、查询）。 - -**适用场景**：快速翻译、单词查询。 - -**实现指引**：意图理解节点识别翻译/查词意图，路由到对应节点。 - -### Level 2：联想记忆法 - -**核心机制**：利用 LLM 生成联想记忆法，帮助记忆单词。 - -- 词根词缀分析。 -- 词源故事/文化背景。 -- 趣味联想（谐音、画面感）。 -- 同根词/近义词/反义词扩展。 - -**适用场景**：深度单词学习、高效记忆。 - -**实现指引**：查词后自动生成联想记忆内容，可选是否保存到生词本。 - -### Level 3：艾宾浩斯遗忘曲线复习 - -**核心机制**：基于遗忘曲线科学安排复习时间。 - -- 首次学习后按 1天、2天、4天、7天、15天、30天 间隔复习。 -- 根据用户记忆反馈动态调整复习间隔。 -- 每日复习提醒。 - -**适用场景**：长期词汇积累、抗遗忘学习。 - -**实现指引**：复习计划节点计算下次复习时间，存入数据库。 - -### Level 4：专业名词提炼与管理 - -**核心机制**：从文本中自动提取专业名词，建立术语库。 - -- 支持从任意文本中提取专业术语。 -- 自动生成术语释义。 -- 按领域分类管理术语库。 - -**适用场景**：专业文档阅读、学术学习。 - -**实现指引**：使用 LLM 进行 NER 和术语识别。 - -### Level 5：智能词汇教练 - -**核心机制**：个性化学习路径、多模态记忆、学习进度追踪。 - -- 根据用户水平推荐学习内容。 -- 图片、音频等多模态记忆辅助。 -- 学习统计与进度可视化。 -- 自适应难度调整。 - -**适用场景**：系统化语言学习、个性化辅导。 - ---- - -## 🔧 核心组件详解 - -### 1. 意图理解节点 - -**职责**：接收用户请求，区分翻译、查词、每日一词、专业提炼、生词管理、复习等意图。 - -**输入**：用户自然语言请求。 - -**输出**： -- `intent_type`：意图类别（translate / lookup / daily / extract / vocab / review / export）。 -- `target_word`：目标单词/文本。 -- `source_lang`：源语言。 -- `target_lang`：目标语言。 - -**实现要点**： -- 使用 LLM 分类意图，输出结构化 JSON。 -- 关键词匹配兜底（如"翻译"、"查一下"）。 - -### 2. 翻译节点 - -**职责**：调用翻译 API，返回高质量翻译结果。 - -**输入**：待翻译文本、源语言、目标语言。 - -**输出**： -- `translation`：翻译结果。 -- `alternative_translations`：备选翻译（如有）。 - -**实现要点**： -- 优先使用 DeepL，降级到有道或 LLM 翻译。 -- 支持长文本分段翻译。 - -### 3. 查词节点 - -**职责**：查询单词详细释义、词性、例句等信息。 - -**输入**：目标单词。 - -**输出**： -- `word_info`：单词信息（词性、释义、音标）。 -- `examples`：例句列表。 - -**实现要点**： -- 调用词典 API，缺失时使用 LLM 生成。 -- 支持英英、英汉双解。 - -### 4. 每日一词节点 - -**职责**：根据用户水平和历史，推荐今日学习单词。 - -**输入**：用户学习偏好。 - -**输出**： -- `daily_word`：今日推荐单词。 -- `word_detail`：单词详情。 -- `learning_tip`：学习建议。 - -**实现要点**： -- 结合用户历史生词和复习进度推荐。 -- 难度适中递进。 - -### 5. 专业名词提炼节点 - -**职责**：从文本中提取专业名词，生成释义。 - -**输入**：待分析文本、领域（可选）。 - -**输出**： -- `extracted_terms`：提取的专业名词列表。 -- `term_definitions`：名词释义。 - -**实现要点**： -- 使用 LLM 进行术语识别和定义生成。 -- 支持按领域过滤。 - -### 6. 生词本管理节点 - -**职责**：生词本的增删改查操作。 - -**输入**：操作类型、生词数据。 - -**输出**： -- `operation_result`：操作结果。 -- `vocab_list`：更新后的生词列表。 - -**实现要点**： -- 支持批量添加。 -- 按标签/难度/复习时间筛选。 - -### 7. 复习计划节点 - -**职责**：基于艾宾浩斯遗忘曲线计算复习计划。 - -**输入**：生词 ID、上次复习时间、记忆强度。 - -**输出**： -- `next_review`：下次复习时间。 -- `review_schedule`：完整复习计划。 - -**实现要点**： -- 使用标准艾宾浩斯间隔（1天、2天、4天、7天、15天、30天）。 -- 根据用户反馈动态调整。 - -### 8. 联想记忆节点 - -**职责**：为单词生成联想记忆法，帮助记忆。 - -**输入**：目标单词。 - -**输出**： -- `root_analysis`：词根词缀分析。 -- `etymology`：词源故事。 -- `association`：趣味联想。 -- `word_family`：同根词/近义词/反义词。 - -**实现要点**： -- 使用 LLM 生成富有创意的记忆法。 -- 支持用户自定义联想。 - -### 9. Anki 导出节点 - -**职责**：导出生词本为 Anki 可导入格式。 - -**输入**：导出范围（全部/按标签/按时间）。 - -**输出**： -- `export_file`：导出文件路径。 -- `export_count`：导出单词数量。 - -**实现要点**： -- 支持 CSV 和 APKG 两种格式。 -- 包含联想记忆内容。 - ---- - -## 🔀 条件路由详解 - -### 入口路由：意图分支 - -- **位置**：意图理解节点之后。 -- **条件**： - - `intent_type == "translate"` → 翻译节点。 - - `intent_type == "lookup"` → 查词节点。 - - `intent_type == "daily"` → 每日一词节点。 - - `intent_type == "extract"` → 专业提炼节点。 - - `intent_type == "vocab"` → 生词管理节点。 - - `intent_type == "review"` → 复习计划节点。 - - `intent_type == "export"` → Anki导出节点。 - -### 查词后续路由 - -- **位置**：查词节点之后。 -- **条件**： - - 用户询问"怎么记" → 联想记忆节点。 - - 用户说"保存" → 生词管理节点（添加）。 - - 无后续 → 格式输出。 - ---- - -## 📊 状态设计 - -### 状态结构概览 - -| 分组 | 字段 | 类型 | 说明 | -|:-----|:-----|:-----|:-----| -| **输入** | `user_input` | `str` | 用户原始请求 | -| **意图** | `intent_type` | `str` | 意图类别 | -| | `target_word` | `str` | 目标单词/文本 | -| | `source_lang` | `str` | 源语言 | -| | `target_lang` | `str` | 目标语言 | -| **翻译** | `translation` | `str` | 翻译结果 | -| | `alternative_translations` | `list[str]` | 备选翻译 | -| **查词** | `word_info` | `dict` | 单词信息 | -| | `examples` | `list[str]` | 例句 | -| **联想** | `root_analysis` | `str` | 词根分析 | -| | `etymology` | `str` | 词源 | -| | `association` | `str` | 联想记忆 | -| | `word_family` | `list[str]` | 词族 | -| **每日一词** | `daily_word` | `str` | 今日单词 | -| | `word_detail` | `dict` | 单词详情 | -| | `learning_tip` | `str` | 学习建议 | -| **专业提炼** | `extracted_terms` | `list[dict]` | 提取的术语 | -| | `term_definitions` | `dict` | 术语释义 | -| **生词本** | `vocab_list` | `list[dict]` | 生词列表 | -| | `operation_result` | `str` | 操作结果 | -| **复习** | `next_review` | `datetime` | 下次复习时间 | -| | `review_schedule` | `list[dict]` | 复习计划 | -| **导出** | `export_file` | `str` | 导出文件路径 | -| | `export_count` | `int` | 导出数量 | -| **控制流** | `current_phase` | `str` | 当前阶段 | -| | `next_node` | `str` | 下一节点 | -| **输出** | `final_result` | `str` | 最终结果 | - ---- - -## 🔄 工作流程 - -### 查词+联想记忆流程 - -| 步骤 | 节点 | 说明 | -|:-----|:-----|:-----| -| 1 | 意图理解 | 识别查词意图 | -| 2 | 查词 | 查询单词释义 | -| 3 | 联想记忆 | 生成记忆法 | -| 4 | 询问保存 | 可选保存到生词本 | -| 5 | 格式输出 | 展示结果 | - -### 复习流程 - -| 步骤 | 节点 | 说明 | -|:-----|:-----|:-----| -| 1 | 意图理解 | 识别复习意图 | -| 2 | 复习计划 | 获取今日需复习单词 | -| 3 | 复习交互 | 逐个复习，记录记忆强度 | -| 4 | 更新计划 | 计算下次复习时间 | -| 5 | 格式输出 | 展示复习结果 | - -### Anki导出流程 - -| 步骤 | 节点 | 说明 | -|:-----|:-----|:-----| -| 1 | 意图理解 | 识别导出意图 | -| 2 | Anki导出 | 生成导出文件 | -| 3 | 格式输出 | 提供下载链接 | diff --git a/backend/app/agent_subgraphs/research/README.md b/backend/app/agent_subgraphs/research/README.md deleted file mode 100644 index 1a93ee5..0000000 --- a/backend/app/agent_subgraphs/research/README.md +++ /dev/null @@ -1,633 +0,0 @@ -# 研究分析子图 (Research Analysis Subgraph) - -该子图负责处理研究分析相关的请求，基于 LangGraph 状态机编排多阶段研究流水线，支持联网搜索、信息提取与验证、结构化报告生成等功能。子图设计遵循"可中断、可恢复、质量优先、透明可追溯"原则，通过内置人工干预点和多源交叉验证保障输出质量。 - -> **使用公共工具**：意图理解、人工审核、格式化输出、检查点持久化、条件路由、LLM 调用、数据库工具、状态基类 - ---- - -## 🎯 核心架构 - -### 技术栈 - -| 层级 | 组件 | 说明 | -|:-----|:-----|:-----| -| **编排框架** | LangGraph StateGraph | 状态机驱动的子图工作流编排，支持条件路由与中断恢复 | -| **LLM 服务** | 智谱 AI / DeepSeek API | 意图理解、任务分解、信息提取、报告生成等认知任务（使用公共 LLM 工具） | -| **向量检索** | Qdrant / pgvector | 历史研究结果语义检索，实现记忆增强研究 | -| **关系存储** | PostgreSQL | 研究项目、报告版本、引用记录持久化（使用公共数据库工具） | -| **搜索服务** | 多源搜索 API 网关 | 统一接入通用搜索、学术数据库、专业知识库等外部信息源 | -| **图表生成** | 图表服务 | 趋势图、对比图、分布图等可视化图表自动生成 | - -### 子图分层架构 - -子图采用分层设计，各层职责清晰、边界明确，便于独立测试与演化。 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ 主图 (Main Graph) │ -└──────────────────────────────┬──────────────────────────────────┘ - │ 状态映射 / 结果聚合 - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 研究分析子图接口层 │ -│ - 状态转换：主状态 ↔ 子图状态（使用公共状态基类） │ -│ - 错误传播与优雅降级 │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 工作流编排层 │ -│ - 节点调度与条件路由（使用公共路由工具） │ -│ - 人工干预点暂停/恢复管理（使用公共审核工具） │ -│ - 状态持久化与检查点（使用公共检查点工具） │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 节点层 │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ -│ │意图理解 │ │任务分解 │ │搜索执行 │ │信息提取 │ │报告生成│ │ -│ │(公共工具)│ │ │ │ │ │ │ │ │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │信息源筛选│ │信息整合 │ │结构生成 │ │人工审核 │ │ -│ │ │ │ │ │ │ │(公共) │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 工具层 │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │搜索工具集│ │提取工具集│ │验证工具集│ │图表工具集│ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### 数据流总览 - -研究分析子图的数据流向遵循"输入 → 理解 → 检索 → 处理 → 整合 → 生成 → 审核 → 输出"的线性推进路径，每个阶段的状态变更均被完整记录，支持断点续作。 - -``` -用户研究请求 - │ - ▼ -┌─────────────┐ -│ 意图理解 │ ← 使用公共意图理解工具 -└──────┬──────┘ - │ - └─────┐ - ▼ -┌─────────────┐ -│ 任务分解 │ -└──────┬──────┘ - │ - ▼ -┌─────────────┐ ┌─────────────┐ -│ 多源搜索 │────▶│ 信息源筛选 │ -└─────────────┘ └──────┬──────┘ - │ - ▼ -┌─────────────┐ ┌─────────────┐ -│ 报告生成 │◀────│ 报告结构确认│ -└──────┬──────┘ └─────────────┘ - │ - ▼ -┌─────────────┐ -│ 格式输出 │ ← 使用公共格式化工具 -└──────┬──────┘ - │ - ▼ - 返回主图 -``` - ---- - -## 📂 模块与文件结构 - -子图代码组织遵循 LangGraph 最佳实践，核心模块职责分明。 - -``` -app/research/ -├── __init__.py -├── graph.py # 子图构建入口，定义状态图与路由 -├── state.py # 子图状态定义（继承公共状态基类） -├── nodes/ # 节点实现 -│ ├── __init__.py -│ ├── decomposition.py # 任务分解节点 -│ ├── search.py # 搜索执行节点 -│ ├── extraction.py # 信息提取节点 -│ ├── integration.py # 信息整合与冲突检测节点 -│ ├── structure.py # 报告结构生成节点 -│ └── generation.py # 报告生成节点 -├── tools/ # 子图特有工具集 -│ ├── search/ # 搜索工具集 -│ ├── extract/ # 信息提取工具集 -│ ├── verify/ # 信息验证工具集 -│ └── chart/ # 图表生成工具集 -└── persistence/ # （使用公共检查点工具，无需单独实现） -``` - -> **注意**：以下模块使用公共工具，无需单独实现： -> - 意图理解节点 → 使用 `agent_subgraphs.common.intent` -> - 人工审核节点 → 使用 `agent_subgraphs.common.human_loop` -> - 格式输出节点 → 使用 `agent_subgraphs.common.format` -> - 检查点持久化 → 使用 `agent_subgraphs.common.checkpoint` -> - 条件路由 → 使用 `agent_subgraphs.common.routing` -> - LLM 调用 → 使用 `agent_subgraphs.common.llm` -> - 数据库操作 → 使用 `agent_subgraphs.common.db` - ---- - -## 🎯 演进路线与核心机制 - -研究分析子图的能力演进分为五个层级，每一层在上一层的基座上叠加更复杂的认知与决策能力。 - -### Level 1：基础单轮研究流水线 - -**核心机制**：单一意图理解 → 单次搜索 → 简单提取 → 直接报告生成。 - -- 使用 LLM 解析用户请求，生成搜索关键词。 -- 调用通用搜索引擎获取原始结果。 -- 基于规则或轻量模型提取关键信息片段。 -- 按照预设模板生成 Markdown 格式报告。 - -**适用场景**：快速知识查询、简单概念解释。 - -**实现指引**：子图默认配置为完整流水线的最小化变体，通过路由条件识别“简单查询”后走该分支。 - -### Level 2：多阶段搜索与信息验证 - -**核心机制**：引入“广度→深度→验证”三轮搜索策略，叠加信息冲突检测与多源交叉验证。 - -- **第一轮广度搜索**：使用主要关键词并行查询多个信息源，获取广泛上下文。 -- **第二轮深度搜索**：基于首轮结果识别出的关键话题，生成细化关键词进行深入检索。 -- **第三轮验证搜索**：针对关键事实（如时间、数据、人名）执行验证性搜索，对比多个独立来源。 -- **冲突检测**：自动识别不同来源对同一事实的冲突描述，按严重程度分级标记。 -- **交叉验证评分**：对每条关键信息计算多源一致性得分，低分项触发人工审核或补充搜索。 - -**适用场景**：市场调研、事件分析、学术资料整理等对信息准确性要求较高的任务。 - -**实现指引**：搜索执行节点内部维护搜索轮次状态，每一轮均可动态调整关键词；信息整合节点输出冲突报告。 - -### Level 3：人工干预点与动态路由 - -**核心机制**：在关键决策点（信息源确认、报告结构调整）插入人工审核节点，子图挂起等待用户反馈，并根据反馈动态调整后续路由。 - -- **信息源筛选审核**：自动筛选后的信息源列表（含可信度、时效性评分）展示给用户，用户可增删或调整优先级。 -- **报告结构审核**：生成的报告大纲与可视化建议展示给用户，用户可调整章节顺序、增删模块。 -- **路由反馈闭环**： - - 用户要求添加信息源 → 返回搜索执行节点补充检索。 - - 用户调整报告结构 → 重新进入结构生成节点。 - - 关键信息冲突且用户无法裁决 → 返回搜索执行节点补充验证来源。 - -**适用场景**：专业研究报告、决策支持分析等需要人类专家介入的场景。 - -**实现指引**：人工审核节点使用 LangGraph 的 `interrupt` 机制实现状态挂起；路由函数读取用户反馈字段决定下一节点。 - -### Level 4：记忆增强研究 - -**核心机制**：利用历史研究结果作为上下文，避免重复搜索，提升研究深度与连贯性。 - -- **语义检索历史**：将当前研究主题与意图向量化，从向量库检索相关历史研究项目。 -- **上下文注入**：将匹配到的历史报告摘要、关键结论、已确认信息源作为先验知识注入意图理解与任务分解阶段。 -- **增量更新**：对于相似主题的后续研究，仅搜索新增或变化的信息，与历史结果融合生成更新报告。 - -**适用场景**：周期性行业分析、追踪式课题研究、企业内部知识累积复用。 - -**实现指引**：在意图理解节点前增加记忆检索步骤，检索结果存入子图状态的 `historical_context` 字段供下游节点消费。 - -### Level 5：自主研究规划与多模态分析 - -**核心机制**：子图具备初步的自主规划能力，能够分解开放式研究问题，并协调多模态搜索与分析工具。 - -- **复杂任务自主分解**：LLM 根据高层研究目标生成多步骤研究计划，包括子任务依赖关系、预期信息源类型。 -- **多模态搜索与分析**：除文本外，支持图像、视频、表格数据的搜索与信息提取。 -- **质量自评估与迭代**：生成报告后，由 LLM 对报告完整性、一致性进行自评，识别信息缺口并自动触发补充搜索。 -- **插件化工具扩展**：第三方可通过标准接口注册自定义搜索源或分析工具。 - -**适用场景**：综合性行业白皮书撰写、跨领域技术调研、深度竞品分析。 - -**实现指引**：任务分解节点升级为规划节点，输出结构化的研究计划图；工具调用采用 OpenAI Function Calling 风格统一接口。 - ---- - -## 🔧 核心组件详解 - -### 1. 意图理解节点 - -**职责**：接收用户原始请求，区分简单查询、深度研究、对比分析等意图类型，评估研究复杂度。 - -**输入**：用户自然语言请求、历史记忆上下文（可选）。 - -**输出**： -- `intent_type`：意图类别枚举。 -- `complexity_level`：复杂度评分（影响流程分支选择）。 -- `clarified_query`：消歧后的核心研究问题。 - -**实现要点**： -- 使用 LLM 进行少样本分类，输出结构化 JSON。 -- 结合关键词匹配与规则兜底（如“对比”、“区别” → 对比分析）。 -- 复杂度评分综合考虑用户指定信息源数量、时间范围跨度、是否需要可视化等因素。 - -### 2. 任务分解节点 - -**职责**：将复杂研究任务拆解为原子子任务，生成搜索关键词列表，并设计初步报告结构。 - -**输入**：澄清后的研究问题、意图类型、复杂度评分。 - -**输出**： -- `sub_tasks`：子任务列表，每个子任务包含描述与预期信息类型。 -- `search_keywords`：多组搜索关键词（支持广度/深度/验证轮次）。 -- `draft_outline`：初步报告章节大纲。 - -**实现要点**： -- 针对对比分析类意图，自动生成对比维度矩阵。 -- 关键词生成利用 LLM 同义词扩展与上下位词推理能力。 -- 初步大纲作为后续报告结构生成的基础框架。 - -### 3. 搜索执行节点 - -**职责**：根据搜索策略执行多轮搜索，收集原始信息并记录元数据。 - -**输入**：搜索关键词组、搜索策略（广度/深度/验证）、信息源偏好。 - -**输出**： -- `raw_search_results`：原始搜索结果列表，每条包含标题、摘要、URL、来源域名、发布时间。 -- `search_metadata`：搜索执行记录（搜索词、时间戳、来源类型）。 - -**实现要点**： -- 内部调用统一搜索网关，屏蔽不同搜索源的 API 差异。 -- 支持并行请求多个搜索源，通过 `asyncio.gather` 提升效率。 -- 每条结果附带初始可信度评分（基于域名信誉库与来源类型）。 - -### 4. 信息源筛选节点（人工干预点） - -**职责**：自动筛选低质量信息源，将候选列表提交用户确认，根据反馈决定后续流向。 - -**输入**：原始搜索结果列表。 - -**输出**： -- `confirmed_sources`：用户确认使用的信息源列表。 -- `user_feedback`：用户添加/删除/优先级调整记录。 - -**实现要点**： -- 自动筛选规则：排除可信度评分低于阈值的来源、发布时间过旧的内容、已被屏蔽的域名。 -- 人工审核界面以简洁列表形式展示信息源，支持多选、拖拽排序。 -- 若用户选择“跳过审核”，则直接使用自动筛选后的结果进入下一阶段。 - -### 5. 信息提取节点 - -**职责**：从确认后的信息源中提取结构化关键信息，标注实体与术语。 - -**输入**：确认后的信息源内容（网页全文或摘要）。 - -**输出**： -- `extracted_fragments`：信息片段列表，每条包含内容文本、提取类型（事实/观点/数据）、来源指针。 -- `entity_annotations`：实体识别结果（时间、地点、人物、组织、专业术语）。 - -**实现要点**： -- 使用 LLM 进行开放式信息抽取，遵循预定义的抽取模式（如“主体-关系-客体”）。 -- 对数值类信息（百分比、金额、增长率）进行归一化处理，便于后续对比。 -- 每条信息片段保留完整来源元数据，支持最终报告的引用溯源。 - -### 6. 信息整合与冲突检测节点 - -**职责**：融合多源信息片段，检测冲突并进行交叉验证，生成结构化信息视图。 - -**输入**：提取的信息片段列表。 - -**输出**： -- `integrated_info`：按主题/时间线/对比维度组织的结构化信息。 -- `conflict_report`：冲突项列表，含冲突等级与各方陈述。 -- `verification_summary`：关键事实的多源验证结果。 - -**实现要点**： -- 采用聚类算法或 LLM 语义匹配将描述同一事实的片段聚合。 -- 冲突检测基于事实三元组比对（如“X 公司市场份额 20%” vs “X 公司市场份额 25%”）。 -- 高优先级冲突（如核心数据差异超过阈值）触发路由至人工审核或补充搜索。 - -### 7. 报告结构生成节点（人工干预点） - -**职责**：基于整合后的信息生成详细报告结构，提交用户确认或调整。 - -**输入**：结构化信息、初步大纲、用户偏好。 - -**输出**： -- `confirmed_outline`：确认后的报告结构（多级标题）。 -- `visualization_suggestions`：建议的图表类型与数据映射。 - -**实现要点**： -- 报告结构生成考虑信息量分布与逻辑叙事顺序。 -- 可视化建议基于数据特征（如时间序列 → 折线图，类别对比 → 柱状图）。 -- 用户反馈可触发结构调整或返回信息整合节点重新组织内容。 - -### 8. 报告生成节点 - -**职责**：按照确认的结构生成完整报告草稿，自动插入引用标记。 - -**输入**：确认的报告结构、结构化信息、引用元数据。 - -**输出**： -- `draft_report`：包含章节内容与引用标记的完整报告文本。 -- `citation_map`：引用标记到来源 URL 的映射表。 - -**实现要点**： -- 使用 LLM 逐章节生成内容，确保风格统一与逻辑连贯。 -- 引用标记采用 `[^1]` 脚注风格，在报告末尾聚合展示来源链接。 -- 对于数据可视化部分，调用图表服务生成图片并嵌入 Markdown 引用。 - -### 9. 人工审核节点 - -**职责**：在特定检查点挂起子图执行，等待用户输入，将反馈存入状态供后续路由消费。 - -**输入**：待审核内容（信息源列表、报告结构等）。 - -**输出**：用户反馈（确认、修改指令、取消等）。 - -**实现要点**： -- 基于 LangGraph `interrupt` 函数实现状态持久化挂起。 -- 反馈数据结构化存储，包含操作类型（confirm/modify/cancel）与具体参数。 -- 支持超时自动确认（可配置）以保证流程不无限阻塞。 - -### 10. 最终格式化节点 - -**职责**：将报告草稿转换为用户指定输出格式，生成执行摘要，准备返回主图。 - -**输入**：确认后的报告草稿、输出格式偏好。 - -**输出**： -- `final_report`：格式化后的报告内容。 -- `executive_summary`：执行摘要（可选）。 -- `suggestions`：后续研究建议（可选）。 - -**实现要点**： -- 支持 Markdown、HTML、纯文本三种输出格式。 -- 执行摘要通过 LLM 从完整报告中提炼核心观点与结论。 -- 最终输出聚合到子图状态 `output` 字段，由接口层转换回主状态。 - ---- - -## 🔀 条件路由详解 - -子图内部通过条件路由函数实现动态流程控制，主要路由点如下： - -### 入口路由：选择流程模式 - -- **位置**：意图理解节点之后。 -- **条件**： - - `complexity_level == "simple"` → 简化流程（跳过任务分解与多轮搜索）。 - - `complexity_level in ["moderate", "complex"]` → 完整流程。 -- **实现**：路由函数读取状态中的 `complexity_level` 字段返回下一节点名称。 - -### 搜索策略路由 - -- **位置**：任务分解节点之后。 -- **条件**： - - 用户要求“快速概览” → 单轮搜索。 - - 用户要求“深度分析” → 多轮搜索（广度→深度→验证）。 - - 意图为“对比分析” → 按对比维度分别搜索后融合。 -- **实现**：根据 `intent_type` 与用户偏好字段决定搜索执行节点的内部模式。 - -### 信息源确认路由 - -- **位置**：信息源筛选节点（人工干预点）之后。 -- **条件**： - - 用户点击“确认” → 进入信息提取节点。 - - 用户点击“添加信息源” → 返回搜索执行节点，携带补充关键词。 - - 用户点击“调整优先级” → 重新排序后再次进入审核（循环）。 -- **实现**：读取 `user_feedback.action` 字段进行路由。 - -### 冲突处理路由 - -- **位置**：信息整合节点之后。 -- **条件**： - - 无冲突或仅有低优先级冲突 → 进入报告结构生成。 - - 存在高优先级冲突且用户未选择“忽略” → 进入人工审核节点。 - - 用户要求“补充验证” → 返回搜索执行节点进行第三轮验证搜索。 -- **实现**：评估 `conflict_report` 中的最高冲突等级与用户历史选择。 - -### 报告结构确认路由 - -- **位置**：报告结构生成节点（人工干预点）之后。 -- **条件**： - - 用户确认 → 进入报告生成节点。 - - 用户要求修改结构 → 重新调用结构生成节点（带修改指令）。 - - 用户要求调整内容 → 返回信息整合节点调整结构化信息。 -- **实现**：读取 `user_feedback` 中的结构修改指令进行路由。 - -### 输出格式路由 - -- **位置**：最终格式化节点之前。 -- **条件**： - - `output_format == "markdown"` → Markdown 格式化。 - - `output_format == "html"` → HTML 格式化。 - - `output_format == "text"` → 纯文本格式化。 -- **实现**：读取用户偏好或默认配置选择格式化器。 - ---- - -## 📊 状态设计 - -子图状态采用 TypedDict 定义，按研究阶段分层组织，完整记录中间产物以支持中断恢复与调试。 - -### 状态结构概览 - -| 分组 | 字段 | 类型 | 说明 | -|:-----|:-----|:-----|:-----| -| **输入** | `user_request` | `str` | 用户原始研究请求 | -| | `preferences` | `dict` | 用户指定的信息源、输出格式等偏好 | -| | `historical_context` | `list[dict]` | 记忆检索注入的历史研究摘要 | -| **意图与任务** | `intent_type` | `str` | 意图类别 | -| | `complexity_level` | `str` | 复杂度评级 | -| | `clarified_query` | `str` | 澄清后的核心问题 | -| | `sub_tasks` | `list[dict]` | 子任务列表 | -| | `search_keywords` | `list[list[str]]` | 多轮搜索关键词组 | -| | `draft_outline` | `list[str]` | 初步报告大纲 | -| **搜索与收集** | `raw_search_results` | `list[dict]` | 原始搜索结果（含元数据） | -| | `confirmed_sources` | `list[dict]` | 用户确认使用的信息源 | -| | `user_source_feedback` | `dict` | 用户对信息源的调整记录 | -| **提取与整合** | `extracted_fragments` | `list[dict]` | 结构化信息片段 | -| | `integrated_info` | `dict` | 按主题/时间线组织的整合信息 | -| | `conflict_report` | `list[dict]` | 冲突项列表 | -| | `verification_summary` | `dict` | 关键事实验证结果 | -| **报告生成** | `confirmed_outline` | `list[dict]` | 确认后的报告结构 | -| | `visualization_suggestions` | `list[dict]` | 图表建议 | -| | `draft_report` | `str` | 报告草稿（含引用标记） | -| | `citation_map` | `dict` | 引用标记到来源映射 | -| | `user_structure_feedback` | `dict` | 用户对报告结构的调整 | -| **控制流** | `current_phase` | `str` | 当前执行阶段 | -| | `next_node` | `str` | 下一节点名称 | -| | `interrupt_point` | `str` | 中断点标识 | -| | `error_info` | `dict` | 错误信息（如有） | -| **输出** | `final_report` | `str` | 最终报告内容 | -| | `output_format` | `str` | 输出格式 | -| | `executive_summary` | `str` | 执行摘要 | - -### 状态更新原则 - -- **增量写入**：每个节点只修改其职责范围内的字段，其他字段只读。 -- **原子提交**：节点执行成功后才将变更合并到全局状态。 -- **版本记录**：每次状态变更均记录前序版本，支持回滚（用于人工审核场景）。 -- **持久化友好**：所有字段均可 JSON 序列化，便于通过检查点器持久化。 - ---- - -## 🔄 工作流程与中断恢复 - -### 完整研究流程（四个阶段） - -| 阶段 | 步骤 | 节点 | 人工干预 | -|:-----|:-----|:-----|:---------| -| **理解与分解** | 1. 意图理解 | `intent_understanding` | 否 | -| | 2. 任务分解 | `task_decomposition` | 否 | -| **检索与收集** | 3. 多源搜索执行 | `search_execution` | 否 | -| | 4. 信息源筛选与确认 | `source_filtering` | **是** | -| **提取与整合** | 5. 关键信息提取 | `information_extraction` | 否 | -| | 6. 信息整合与冲突检测 | `information_integration` | 否（可能触发审核） | -| **生成与输出** | 7. 报告结构确认 | `structure_generation` | **是** | -| | 8. 报告生成与格式化 | `report_generation` + `final_formatting` | 否 | - -### 简化流程（快速查询模式） - -当 `complexity_level == "simple"` 时，子图走精简路径： - -1. 意图理解（简化版，不拆解任务）。 -2. 单次搜索执行（仅广度搜索）。 -3. 快速信息提取（不进行深度整合）。 -4. 直接生成简短回答（跳过结构确认）。 - -### 中断与恢复机制 - -子图支持在以下位置中断并持久化状态： - -- 信息源筛选节点（人工干预点 1） -- 报告结构生成节点（人工干预点 2） -- 任意节点执行完成后的检查点（由检查点器自动保存） - -**恢复流程**： -1. 主图传入相同的 `thread_id` 与中断前状态。 -2. 子图从检查点加载状态，定位 `interrupt_point`。 -3. 若中断点为人工审核节点，等待用户反馈后继续执行。 -4. 若为其他检查点，直接从下一节点开始执行。 - ---- - -## 🔒 安全与边界控制 - -### 安全机制 - -| 类别 | 机制 | 实现位置 | -|:-----|:-----|:---------| -| **内容安全** | 搜索关键词过滤、结果内容审查、成人内容屏蔽 | 搜索工具网关 | -| **数据安全** | 用户数据加密存储、传输层 TLS、敏感信息脱敏 | 持久化层与接口层 | -| **访问控制** | 基于角色的功能权限（普通/高级/管理员） | 接口层中间件 | -| **资源限制** | 单用户 QPS 限制、单次研究最大 Token 消耗、最大信息源数量 | 工作流编排层 | -| **审计日志** | 记录所有搜索、提取、生成操作，包含操作者、时间戳、资源消耗 | 各节点内置日志 | - -### 人工审核触发边界 - -以下情况强制进入人工审核节点： - -- 信息源可信度平均评分低于阈值。 -- 高优先级信息冲突且无法自动裁决。 -- 用户请求超出常规研究边界（如要求访问受限领域）。 -- 首次使用特定高风险搜索源。 - -### 错误处理边界 - -- **可恢复错误**（如单次搜索超时）：自动重试或切换备选搜索源。 -- **不可恢复错误**（如 LLM 服务不可用）：终止执行，向主图返回错误状态与友好提示。 -- **部分成功**：即使部分子任务失败，仍返回已完成的部分结果（如已提取的信息片段）。 - ---- - -## 🛠️ 工具集成 - -### 工具集概览 - -| 工具集 | 功能 | 外部依赖 | -|:-------|:-----|:---------| -| **搜索工具集** | 通用网页搜索、学术论文检索、专业知识库查询、新闻资讯获取 | 搜索 API 网关 | -| **信息提取工具集** | 实体识别、数据提取、术语标注、关系抽取、摘要生成 | LLM 服务 | -| **信息验证工具集** | 多源交叉验证、可信度评分、时效性检查、一致性检查 | 域名信誉库、LLM | -| **报告生成工具集** | 内容生成、引用插入、图表生成、格式转换 | LLM、图表服务 | -| **记忆检索工具集** | 历史研究语义检索、项目检索、时间范围检索 | Qdrant / pgvector | - -### 工具调用规范 - -所有工具遵循统一接口规范： - -- **输入**：标准字典参数。 -- **输出**：标准字典结果，包含 `status`、`data`、`error` 字段。 -- **元数据**：每次调用记录调用时间、耗时、资源标识。 - -### 工具扩展方式 - -新增工具仅需三步： - -1. 在对应工具集中实现标准接口的适配器。 -2. 在工具注册表中声明工具元数据（名称、描述、参数模式）。 -3. 在相关节点中通过工具名称调用，无需修改节点核心逻辑。 - ---- - -## 📑 快速开始（概念级） - -研究分析子图作为主图的一个子图节点被调用，典型集成方式如下： - -1. **主图路由**：当主图识别到用户意图为“研究分析”时，路由至 `research_subgraph` 节点。 -2. **状态映射**：主状态中的 `user_input`、`user_id` 等字段映射到子图状态输入部分。 -3. **子图执行**：子图按照上述工作流自主执行，可能在人工干预点挂起。 -4. **结果回传**：子图执行完毕后，将 `final_report`、`executive_summary` 等字段回写到主状态。 - -子图内部配置项（如默认搜索源、重试次数、审核超时）通过环境变量或配置文件管理。 - ---- - -## ⚙️ 配置项参考 - -| 配置项 | 说明 | 默认值 | -|:-------|:-----|:-------| -| `RESEARCH_LLM_MODEL` | 意图理解与生成使用的 LLM 模型 | `deepseek-chat` | -| `SEARCH_API_GATEWAY_URL` | 统一搜索网关地址 | `http://localhost:8080` | -| `SEARCH_DEFAULT_SOURCES` | 默认启用的搜索源列表 | `["web", "news"]` | -| `MAX_SEARCH_ROUNDS` | 最大搜索轮次 | `3` | -| `RERANK_TOP_N` | 信息源筛选保留数量 | `20` | -| `CONFLICT_SEVERITY_THRESHOLD` | 触发人工审核的冲突等级 | `high` | -| `HUMAN_LOOP_TIMEOUT_SEC` | 人工审核超时自动确认时间 | `3600` | -| `VECTOR_DB_URL` | 记忆检索向量库地址 | `http://localhost:6333` | -| `CHART_SERVICE_URL` | 图表生成服务地址 | `http://localhost:3000` | - ---- - -## 🤝 与主系统集成 - -研究分析子图通过 LangGraph 子图机制与主系统解耦集成： - -- **状态隔离**：子图状态字段使用前缀 `research_` 避免与主状态冲突。 -- **错误传播**：子图内部异常捕获后转换为标准错误结构向上传递，主图可选择重试或降级。 -- **检查点共享**：子图与主图共用同一检查点器后端，确保整体流程的断点续作能力。 - -子图对外暴露的唯一接口是编译后的 `StateGraph` 实例，主图通过 `builder.add_node("research", research_subgraph)` 将其作为一个节点加入。 - ---- - -## 📈 性能考量 - -- **并行搜索**：多源搜索与多关键词检索采用异步并行，典型场景下搜索阶段耗时控制在 3 秒内。 -- **流式报告生成**：报告生成节点支持流式输出，用户在报告结构确认后可实时看到内容逐段生成。 -- **结果缓存**：对于相同搜索词在短时间内的重复请求，搜索网关层提供 TTL 缓存。 -- **状态压缩**：持久化前对大型字段（如原始搜索结果全文）进行摘要化处理，减少存储开销。 - ---- - -## 🔮 未来演进方向 - -参见需求文档中的详细规划，技术实现层面重点关注： - -- **LLM 工具调用标准化**：向 OpenAI Function Calling 风格对齐。 -- **多模态管道**：集成图像描述生成与视觉问答模型。 -- **插件市场**：提供标准工具接口 SDK，支持第三方搜索源接入。 -- **协同研究**：支持多用户对同一研究项目的评论与版本分支管理。 \ No newline at end of file