# 通讯录子图 (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 | 否 | ### 中断恢复机制 子图支持在人工审核节点中断，恢复时从审核点继续执行。