docs: 完善子图架构文档，添加详细流程图和主图关联

2026-04-26 12:33:25 +08:00
parent b78aa63739
commit 6404ea8c42
1 changed files with 374 additions and 10 deletions
--- 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 端点<br>/subgraph/contact<br>/subgraph/dictionary<br>/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[意图分类节点<br>判断用户意图]
+        ChatNode[普通对话节点<br>调用主 LLM]
+        SubgraphCaller[子图调用器<br>调用对应子图]
+        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<br>解析意图]
+        ListContacts[list_contacts<br>列出联系人]
+        AddContact[add_contact<br>添加联系人]
+        ListEmails[list_emails<br>列出邮件]
+        GenEmail[generate_email_draft<br>生成邮件草稿]
+        HumanReview[human_review<br>人工审核]
+        SendEmail[send_email<br>发送邮件]
+        SniffContact[sniff_contacts<br>智能嗅探]
+        FormatContact[format_result<br>格式化输出]
+        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<br>解析意图]
+        QueryWord[query_word<br>查询单词]
+        Translate[translate_text<br>翻译文本]
+        ExtractTerms[extract_terms<br>提取专业术语]
+        DailyWord[get_daily_word<br>每日一词]
+        LookupWord[lookup_word_book<br>查询生词本]
+        AddToWord[add_to_word_book<br>添加到生词本]
+        FormatDict[format_result<br>格式化输出]
+        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<br>解析意图]
+        QueryNews[query_news<br>查询资讯]
+        AnalyzeUrl[analyze_url<br>分析链接]
+        ExtractKeywords[extract_keywords<br>提取关键词]
+        GenReport[generate_report<br>生成报告]
+        FormatNews[format_result<br>格式化输出]
+        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 -.->|调用<br>状态传递| StartContact
+    SubgraphCaller -.->|调用<br>状态传递| StartDict
+    SubgraphCaller -.->|调用<br>状态传递| 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<br>用户输入 + 上下文]
+        IntentRouter[意图分类器<br>intent.py]
+        MainLLM[主 LLM 节点<br>普通对话]
+    end
+
+    subgraph "通讯录子图 ContactSubgraph"
+        ContactState[ContactState<br>联系人状态]
+        ContactNodes[内部节点<br>parse_intent<br>add_contact<br>list_contacts<br>generate_draft<br>human_review<br>should_continue]
+        ContactDB[(PostgreSQL 联系人)]
+    end
+
+    subgraph "词典子图 DictionarySubgraph"
+        DictState[DictionaryState<br>词典状态]
+        DictNodes[内部节点<br>translate<br>lookup_word<br>extract_terms<br>daily_word<br>lookup_word_book<br>add_to_word_book]
+        DictDB[(PostgreSQL 生词本)]
+    end
+
+    subgraph "资讯分析子图 NewsSubgraph"
+        NewsState[NewsAnalysisState<br>资讯状态]
+        NewsNodes[内部节点<br>query_news<br>analyze_url<br>extract_keywords<br>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/) - 规划中
 - 联网搜索
 - 报告生成