层级	组件	说明
编排框架	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	否

中断恢复机制

子图支持在人工审核节点中断，恢复时从审核点继续执行。

README.md Unescape Escape

通讯录子图 (Contact Subgraph)

🎯 核心架构

技术栈

子图分层架构

数据流总览

📂 模块与文件结构

🎯 演进路线与核心机制

Level 1：基础联系人管理

Level 2：邮件读取与基础发送

Level 3：智能嗅探与上下文感知

Level 4：邮件智能处理

Level 5：通讯录智能助理

🔧 核心组件详解

1. 意图理解节点

2. 联系人 CRUD 节点

3. 邮件读取节点

4. 邮件草稿生成节点

5. 人工审核节点

6. 邮件发送节点

7. 智能嗅探节点

🔀 条件路由详解

入口路由：意图分支

审核路由

嗅探路由

📊 状态设计

状态结构概览

🔄 工作流程与中断恢复

邮件发送流程

联系人保存流程

智能嗅探流程

中断恢复机制

README.md