root
7945f53086
Some checks failed
构建并部署 AI Agent 服务 / deploy (push) Failing after 5m36s
- 添加 agent_subgraphs 目录，包含主图 README.md 和三个子图文档 - 通讯录子图：联系人 CRUD、邮件读取/发送、智能嗅探 - 智能词典子图：翻译、查词、每日一词、专业名词提炼 - 研究分析子图：联网搜索、报告生成、引用溯源 - 公共工具：意图理解、人工审核、格式化输出、检查点持久化、条件路由、LLM 调用、数据库工具、状态基类 - 配置调整：启用 DEBUG 日志级别 - 启动脚本：使用 python3 替代 python
392 lines
16 KiB
Markdown
392 lines
16 KiB
Markdown
# 通讯录子图 (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 | 否 |
|
||
|
||
### 中断恢复机制
|
||
|
||
子图支持在人工审核节点中断，恢复时从审核点继续执行。
|