From 93b1f1b8ed304351b5f61d439ea8cc84bd79b56e Mon Sep 17 00:00:00 2001 From: root <953994191@qq.com> Date: Sat, 25 Apr 2026 13:47:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=81=A2=E5=A4=8D=E4=B8=89=E5=A4=A7?= =?UTF-8?q?=E5=AD=90=E5=9B=BE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 恢复 contact/README.md - 恢复 dictionary/README.md - 恢复 research/README.md - 恢复 agent_subgraphs/README.md --- backend/app/agent_subgraphs/README.md | 744 ++++++++++++++++++ backend/app/agent_subgraphs/contact/README.md | 391 +++++++++ .../app/agent_subgraphs/dictionary/README.md | 428 ++++++++++ .../app/agent_subgraphs/research/README.md | 633 +++++++++++++++ 4 files changed, 2196 insertions(+) create mode 100644 backend/app/agent_subgraphs/README.md create mode 100644 backend/app/agent_subgraphs/contact/README.md create mode 100644 backend/app/agent_subgraphs/dictionary/README.md create mode 100644 backend/app/agent_subgraphs/research/README.md diff --git a/backend/app/agent_subgraphs/README.md b/backend/app/agent_subgraphs/README.md new file mode 100644 index 0000000..cb6d6e0 --- /dev/null +++ b/backend/app/agent_subgraphs/README.md @@ -0,0 +1,744 @@ +# 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 new file mode 100644 index 0000000..cc0c222 --- /dev/null +++ b/backend/app/agent_subgraphs/contact/README.md @@ -0,0 +1,391 @@ +# 通讯录子图 (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 new file mode 100644 index 0000000..5fbd3df --- /dev/null +++ b/backend/app/agent_subgraphs/dictionary/README.md @@ -0,0 +1,428 @@ +# 智能词典子图 (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 new file mode 100644 index 0000000..1a93ee5 --- /dev/null +++ b/backend/app/agent_subgraphs/research/README.md @@ -0,0 +1,633 @@ +# 研究分析子图 (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