From 6404ea8c423bda57f38694ddca91d315d62dedce Mon Sep 17 00:00:00 2001 From: root <953994191@qq.com> Date: Sun, 26 Apr 2026 12:33:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E5=AD=90=E5=9B=BE?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0?= =?UTF-8?q?=E8=AF=A6=E7=BB=86=E6=B5=81=E7=A8=8B=E5=9B=BE=E5=92=8C=E4=B8=BB?= =?UTF-8?q?=E5=9B=BE=E5=85=B3=E8=81=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 384 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 374 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 238e8a3..431f50f 100644 --- a/README.md +++ b/README.md @@ -77,10 +77,10 @@ ```mermaid graph TB User[用户浏览器] -->|HTTP/SSE| Frontend[Streamlit 前端 :8501] - Frontend -->|REST API| Backend[FastAPI 后端 :8083] + Frontend -->|REST API| Backend[FastAPI 后端 :8079] Backend --> AgentService[AIAgentService] - Backend --> SubgraphAPI[子图 API 端点] + Backend --> SubgraphAPI[子图 API 端点
/subgraph/contact
/subgraph/dictionary
/subgraph/news] AgentService -->|模型路由| ChatServices[模型服务层 chat_services] ChatServices -->|自动降级| FallbackChain[FallbackServiceChain] @@ -120,6 +120,10 @@ graph TB Common --> Formatter[格式化输出] Common --> StateBase[状态基类] + Contact -->|数据库| ContactDB[(PostgreSQL 联系人)] + Dictionary -->|数据库| DictionaryDB[(PostgreSQL 生词本)] + NewsAnalysis -->|检索| NewsQdrant[(Qdrant 向量检索)] + style User fill:#e1f5ff style Frontend fill:#fff4e1 style Backend fill:#e8f5e9 @@ -130,6 +134,124 @@ graph TB style Qdrant fill:#ffebee ``` +--- + +### 主图与子图的关联架构 + +```mermaid +graph TB + subgraph "主图 MainGraph" + StartMain[START] + IntentMain[意图分类节点
判断用户意图] + ChatNode[普通对话节点
调用主 LLM] + SubgraphCaller[子图调用器
调用对应子图] + FinalMain[最终响应] + EndMain[END] + + StartMain -->|用户输入| IntentMain + IntentMain -->|chat| ChatNode + IntentMain -->|contact| SubgraphCaller + IntentMain -->|dictionary| SubgraphCaller + IntentMain -->|research| SubgraphCaller + IntentMain -->|news| SubgraphCaller + ChatNode --> FinalMain + SubgraphCaller --> FinalMain + FinalMain --> EndMain + end + + subgraph "通讯录子图 ContactSubgraph" + StartContact[START] + IntentContact[parse_intent
解析意图] + ListContacts[list_contacts
列出联系人] + AddContact[add_contact
添加联系人] + ListEmails[list_emails
列出邮件] + GenEmail[generate_email_draft
生成邮件草稿] + HumanReview[human_review
人工审核] + SendEmail[send_email
发送邮件] + SniffContact[sniff_contacts
智能嗅探] + FormatContact[format_result
格式化输出] + EndContact[END] + + StartContact --> IntentContact + IntentContact -->|list| ListContacts + IntentContact -->|add| AddContact + IntentContact -->|list_emails| ListEmails + IntentContact -->|generate_email| GenEmail + IntentContact -->|sniff| SniffContact + ListContacts --> FormatContact + AddContact --> FormatContact + ListEmails --> FormatContact + SniffContact --> FormatContact + GenEmail --> HumanReview + HumanReview -->|approve| SendEmail + HumanReview -->|reject| FormatContact + SendEmail --> FormatContact + FormatContact --> EndContact + end + + subgraph "词典子图 DictionarySubgraph" + StartDict[START] + IntentDict[parse_intent
解析意图] + QueryWord[query_word
查询单词] + Translate[translate_text
翻译文本] + ExtractTerms[extract_terms
提取专业术语] + DailyWord[get_daily_word
每日一词] + LookupWord[lookup_word_book
查询生词本] + AddToWord[add_to_word_book
添加到生词本] + FormatDict[format_result
格式化输出] + EndDict[END] + + StartDict --> IntentDict + IntentDict -->|query| QueryWord + IntentDict -->|translate| Translate + IntentDict -->|extract| ExtractTerms + IntentDict -->|daily| DailyWord + IntentDict -->|lookup| LookupWord + IntentDict -->|add| AddToWord + QueryWord --> FormatDict + Translate --> FormatDict + ExtractTerms --> FormatDict + DailyWord --> FormatDict + LookupWord --> FormatDict + AddToWord --> FormatDict + FormatDict --> EndDict + end + + subgraph "资讯分析子图 NewsSubgraph" + StartNews[START] + IntentNews[parse_intent
解析意图] + QueryNews[query_news
查询资讯] + AnalyzeUrl[analyze_url
分析链接] + ExtractKeywords[extract_keywords
提取关键词] + GenReport[generate_report
生成报告] + FormatNews[format_result
格式化输出] + EndNews[END] + + StartNews --> IntentNews + IntentNews -->|query| QueryNews + IntentNews -->|analyze| AnalyzeUrl + IntentNews -->|keywords| ExtractKeywords + IntentNews -->|report| GenReport + QueryNews --> FormatNews + AnalyzeUrl --> FormatNews + ExtractKeywords --> FormatNews + GenReport --> FormatNews + FormatNews --> EndNews + end + + SubgraphCaller -.->|调用
状态传递| StartContact + SubgraphCaller -.->|调用
状态传递| StartDict + SubgraphCaller -.->|调用
状态传递| StartNews + + style IntentMain fill:#ffe0b2 + style ChatNode fill:#e0e0e0 + style SubgraphCaller fill:#bbdefb + style FinalMain fill:#fff59d + style IntentContact fill:#c8e6c9 + style IntentDict fill:#e1bee7 + style IntentNews fill:#ffcdd2 +``` + ### LangGraph 工作流详细流程 ```mermaid @@ -937,13 +1059,13 @@ RAG 系统分为两个独立但协同的阶段： │ 子图系统架构 │ ├───────────────────────────────────────────────────────────────────┤ │ │ -│ ┌────────────────────────────────────────────────────────────┐ │ +│ ┌───────────────────────────────────────────────────────────┐ │ │ │ 公共工具库 (common/) │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────┐ │ │ │ │ │ state_base │ │ intent │ │ formatter │ │human │ │ │ -│ │ │ (状态) │ │ (React) │ │ (格式化) │ │review│ │ │ +│ │ │ (状态基类) │ │ (React模式) │ │ (格式化) │ │review│ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └──────┘ │ │ -│ └────────────────────────────────────────────────────────────┘ │ +│ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────┼───────────────┐ │ │ ↓ ↓ ↓ │ @@ -954,15 +1076,112 @@ RAG 系统分为两个独立但协同的阶段： │ │ state.py │ │ state.py │ │ state.py │ │ │ │ nodes.py │ │ nodes.py │ │ nodes.py │ │ │ │ graph.py │ │ graph.py │ │ graph.py │ │ -│ │ api_client.py │ │ api_client.py │ │ api_client.py │ │ +│ │ api_client.py │ │ api_client.py │ │ api_client.py │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ ▼ │ -│ FastAPI 子图端点 │ -│ (backend/app/backend.py) │ +│ FastAPI 子图端点 │ +│ (backend/app/backend.py) │ └───────────────────────────────────────────────────────────────────┘ ``` +--- + +### 子图架构总览 + +```mermaid +graph TB + subgraph "主图 MainGraph" + MainState[主图 MainState
用户输入 + 上下文] + IntentRouter[意图分类器
intent.py] + MainLLM[主 LLM 节点
普通对话] + end + + subgraph "通讯录子图 ContactSubgraph" + ContactState[ContactState
联系人状态] + ContactNodes[内部节点
parse_intent
add_contact
list_contacts
generate_draft
human_review
should_continue] + ContactDB[(PostgreSQL 联系人)] + end + + subgraph "词典子图 DictionarySubgraph" + DictState[DictionaryState
词典状态] + DictNodes[内部节点
translate
lookup_word
extract_terms
daily_word
lookup_word_book
add_to_word_book] + DictDB[(PostgreSQL 生词本)] + end + + subgraph "资讯分析子图 NewsSubgraph" + NewsState[NewsAnalysisState
资讯状态] + NewsNodes[内部节点
query_news
analyze_url
extract_keywords
generate_report] + NewsQdrant[(Qdrant 向量检索)] + end + + MainState -->|用户查询| IntentRouter + IntentRouter -->|contact| ContactState + IntentRouter -->|dictionary| DictState + IntentRouter -->|news| NewsState + IntentRouter -->|chat| MainLLM + + ContactState -->|调用| ContactNodes + ContactNodes -->|读写| ContactDB + ContactNodes -->|返回结果| MainState + + DictState -->|调用| DictNodes + DictNodes -->|读写| DictDB + DictNodes -->|返回结果| MainState + + NewsState -->|调用| NewsNodes + NewsNodes -->|检索| NewsQdrant + NewsNodes -->|返回结果| MainState + + style MainState fill:#e3f2fd + style IntentRouter fill:#ffe0b2 + style ContactState fill:#c8e6c9 + style DictState fill:#e1bee7 + style NewsState fill:#ffcdd2 +``` + +--- + +### 状态传送机制 + +```mermaid +sequenceDiagram + participant User as 用户 + participant Frontend as 前端 + participant Backend as 后端 API + participant Main as 主图 + participant Intent as 意图分类器 + participant Subgraph as 子图 + participant DB as 数据库 + + User->>Frontend: 输入查询 + Frontend->>Backend: POST /subgraph/{type}/{action} + Backend->>Main: 初始化 MainState + Main->>Intent: 调用意图分类 + Intent-->>Main: 返回子图类型 (contact/dictionary/news/chat) + + alt 是子图请求 + Main->>Subgraph: 传递状态 + activate Subgraph + Subgraph->>Subgraph: 解析意图 (parse_intent) + Subgraph->>DB: 读取/写入数据 + DB-->>Subgraph: 返回数据 + Subgraph->>Subgraph: 执行业务逻辑 + Subgraph->>Subgraph: 格式化结果 (format_result) + Subgraph-->>Main: 返回结果状态 + deactivate Subgraph + else 是普通对话 + Main->>Main: 调用主 LLM + end + + Main->>Main: 合并状态 + Main-->>Backend: 返回最终结果 + Backend-->>Frontend: JSON 响应 + Frontend-->>User: 显示结果 +``` + +--- + ### 公共工具说明 #### 1. state_base.py - 状态基类 @@ -987,6 +1206,8 @@ RAG 系统分为两个独立但协同的阶段： - 状态持久化 - 异步等待 +--- + ### 子图开发指南 #### 创建新子图的步骤 @@ -1044,29 +1265,172 @@ def build_my_subgraph() -> StateGraph: 5. **添加 API 客户端 (api_client.py)**（可选） 用于与外部 API 交互。 -6. **在 backend.py 中添加 API 端点** +--- ### 已实现的子图 #### 1. 通讯录子图 (contact/) -- 联系人 CRUD + +**详细流程图：** +```mermaid +stateDiagram-v2 + [*] --> parse_intent: 开始 + + parse_intent --> list_contacts: action=list + parse_intent --> add_contact: action=add + parse_intent --> list_emails: action=list_emails + parse_intent --> generate_email_draft: action=generate_email + parse_intent --> sniff_contacts: action=sniff + + list_contacts --> format_result: 返回联系人列表 + add_contact --> format_result: 添加成功 + list_emails --> format_result: 返回邮件列表 + sniff_contacts --> format_result: 嗅探完成 + + generate_email_draft --> human_review: 生成草稿 + human_review --> send_email: action=approve + human_review --> format_result: action=reject + + send_email --> format_result: 邮件已发送 + + format_result --> [*]: 格式化输出 + + note right of parse_intent + 解析用户意图 + 支持的操作： + - list: 列出联系人 + - add: 添加联系人 + - list_emails: 列出邮件 + - generate_email: 生成邮件草稿 + - sniff: 智能嗅探 + end note + + note right of human_review + 人工审核节点 + 使用 LangGraph interrupt + 支持三种操作： + - approve: 审核通过，发送邮件 + - reject: 审核拒绝，返回结果 + - modify: 审核修改，编辑内容 + end note +``` + +**功能列表：** +- 联系人 CRUD（增删改查） - 邮件读取与审核 - 外发邮件 - 智能嗅探 - 精美格式化展示 +**API 端点：** +``` +GET /subgraph/contact/{action} +参数: +- action: list | add | list_emails | generate_email | sniff +- query: 查询内容 +- user_id: 用户 ID +``` + +--- + #### 2. 词典子图 (dictionary/) + +**详细流程图：** +```mermaid +stateDiagram-v2 + [*] --> parse_intent: 开始 + + parse_intent --> query_word: action=query + parse_intent --> translate_text: action=translate + parse_intent --> extract_terms: action=extract + parse_intent --> get_daily_word: action=daily + parse_intent --> lookup_word_book: action=lookup + parse_intent --> add_to_word_book: action=add + + query_word --> format_result: 查询单词 + translate_text --> format_result: 翻译文本 + extract_terms --> format_result: 提取专业术语 + get_daily_word --> format_result: 每日一词 + lookup_word_book --> format_result: 查询生词本 + add_to_word_book --> format_result: 添加到生词本 + + format_result --> [*]: 格式化输出 + + note right of parse_intent + 解析用户意图 + 支持的操作： + - query: 查询单词 + - translate: 翻译文本 + - extract: 提取专业术语 + - daily: 每日一词 + - lookup: 查询生词本 + - add: 添加到生词本 + end note +``` + +**功能列表：** - 翻译、查词 - 每日一词 - 专业名词提炼 - 生词本管理 - 精美格式化展示 +**API 端点：** +``` +GET /subgraph/dictionary/{action} +参数: +- action: query | translate | extract | daily | lookup | add +- query: 查询内容 +- user_id: 用户 ID +``` + +--- + #### 3. 资讯分析子图 (news_analysis/) + +**详细流程图：** +```mermaid +stateDiagram-v2 + [*] --> parse_intent: 开始 + + parse_intent --> query_news: action=query + parse_intent --> analyze_url: action=analyze + parse_intent --> extract_keywords: action=keywords + parse_intent --> generate_report: action=report + + query_news --> format_result: 查询资讯 + analyze_url --> format_result: 分析链接 + extract_keywords --> format_result: 提取关键词 + generate_report --> format_result: 生成报告 + + format_result --> [*]: 格式化输出 + + note right of parse_intent + 解析用户意图 + 支持的操作： + - query: 查询资讯 + - analyze: 分析链接 + - keywords: 提取关键词 + - report: 生成报告 + end note +``` + +**功能列表：** - 资讯获取 - 内容分析 - 精美格式化展示 +**API 端点：** +``` +GET /subgraph/news/{action} +参数: +- action: query | analyze | keywords | report +- query: 查询内容 +- user_id: 用户 ID +``` + +--- + #### 4. 研究分析子图 (research/) - 规划中 - 联网搜索 - 报告生成