智能邮件助手 (Mail Agent)

基于 RAG（检索增强生成）和多智能体架构的 AI 邮件管理系统，通过 Microsoft Graph API 与 Outlook 深度集成，提供智能分类、优先级排序、聊天助手等功能。

• 🤖 多智能体协同：基于 LangGraph 的工作流编排，实现邮件摄入、分类、持久化的完整流程
• 🧠 双 RAG 系统：
  • EmailRAG：存储邮件正文与元数据，支持语义检索
  • ProfileRAG：存储用户画像、偏好、研究领域，动态学习用户习惯
• 🎯 智能分类：结合用户画像与邮件内容，自动标注类别（学术/课程/行政/社团/推广等）和优先级
• 💬 对话式交互：自然语言查询邮件、检查 DDL、起草回复、更新偏好
• 📊 实时统计：按分类/优先级筛选时显示总数/未读数，无需本地数据库
• 🔄 增量同步：使用 Microsoft Graph Delta API 实现高效增量拉取
• 🚫 垃圾邮件智能处理：自动识别并移动被误判为垃圾的学校转发邮件
• 📝 反馈学习：用户纠正分类后自动更新 Outlook 与 ProfileRAG，持续优化

• Vue 3 (Composition API) + Vite - 现代化前端框架与构建工具
• Tailwind CSS v4 - 原子化 CSS 框架，支持深色模式
• Pinia - 轻量级状态管理
• Vue Router - SPA 路由
• DOMPurify - 邮件 HTML 内容安全渲染

• FastAPI - 高性能异步 Web 框架，自动生成 OpenAPI 文档
• LangGraph - 状态图工作流编排，实现智能体自主决策
• LangChain Core - LLM 应用开发工具链
• MSAL (Microsoft Authentication Library) - Azure AD 设备码登录
• Microsoft Graph API - Outlook 邮件/日历/分类管理
• LightRAG Server - 轻量级 RAG 服务（双实例部署）
• 阿里百炼平台 (Bailian/DashScope) - LLM 推理（通义千问系列）

无本地数据库，全部数据通过以下方式持久化：

1. Outlook 主类别 (Master Categories)：颜色标签，全客户端同步
2. 开放扩展 (Open Extensions)：自定义元数据（优先级、推荐动作、分类原因）直接存储在邮件对象上
3. LightRAG：邮件正文与用户画像的向量/图谱索引
4. Delta Link：本地缓存 Graph API 的增量同步游标

┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  Ingestion Node  │  →   │ Classifier Node  │  →   │  Persister Node  │
│  (摄入 + 标准化)  │      │  (RAG + LLM 分类) │      │ (写回 Outlook)    │
└──────────────────┘      └──────────────────┘      └──────────────────┘

节点功能：

1. Ingestion Agent

   • 拉取 Graph API 邮件，标准化字段
   • 异步写入 EmailRAG（跟踪 track_id）
   • 画像增强：检测到重要邮件（importance=high 或 flag.flagStatus=flagged）时，自动提取关键信息并更新 ProfileRAG

2. Classifier Agent

   • 从 ProfileRAG 检索用户偏好
   • 从 EmailRAG 检索相似邮件

• 调用 LLM 生成分类结果：categories（多选）、priority（High/Medium/Low/Uninteresting）、need_reply、recommended_actions

3. Persister Agent
   • 写入 Outlook 类别（自动创建不存在的主类别）
   • 创建/更新开放扩展 ai.mail.meta，包含优先级与推荐动作
   • 标记 rag_inserted=true 避免重复摄入

┌────────────┐      ┌──────────────────┐      ┌──────────────┐
│ Plan Node  │  →   │ Execute Tools    │  →   │ Respond Node │
│ (规划工具)  │      │ (条件执行工具)     │      │ (格式化回复) │
└────────────┘      └──────────────────┘      └──────────────┘

特性：

• 自主规划：LLM 根据用户问题自动选择调用哪些工具（最多 5 个）
• 工具目录：包含 Graph API、RAG 查询、邮件分类、日历管理等 10+ 工具
• 条件执行：仅在需要时调用工具，避免浪费 tokens

mail-agent/
├── backend/                    # FastAPI 后端
│   ├── agents/                 # 智能体实现
│   │   ├── ingestion_agent.py      # 邮件摄入与标准化
│   │   ├── classifier_agent.py     # 邮件分类（RAG+LLM）
│   │   ├── persister_agent.py      # 写回 Outlook
│   │   └── feedback_agent.py       # 用户反馈学习
│   ├── clients/                # API 客户端
│   │   ├── graph_client.py         # Microsoft Graph API
│   │   ├── lightrag_client.py      # LightRAG Server
│   │   └── bailian_client.py       # 阿里百炼 LLM
│   ├── workflows/              # LangGraph 工作流
│   │   ├── agent_workflow.py       # 邮件处理流程
│   │   └── chat_workflow.py        # 聊天助手流程
│   ├── utils/
│   │   └── tool_catalog.py         # 聊天工具目录
│   ├── main.py                 # FastAPI 应用入口
│   ├── config.py               # 配置文件
│   └── requirements.txt        # Python 依赖
├── frontend/                   # Vue 3 前端
│   ├── src/
│   │   ├── api/                    # API 客户端
│   │   ├── components/             # Vue 组件
│   │   │   ├── ChatBubble.vue          # 聊天气泡
│   │   │   ├── EmailCard.vue           # 邮件卡片
│   │   │   └── FiltersPanel.vue        # 筛选面板
│   │   ├── stores/                 # Pinia 状态管理
│   │   │   ├── auth.js                 # 认证状态
│   │   │   ├── email.js                # 邮件列表与筛选
│   │   │   ├── chat.js                 # 聊天状态
│   │   │   └── profile.js              # 画像状态
│   │   ├── views/                  # 页面视图
│   │   │   ├── LoginView.vue           # 登录页
│   │   │   └── InboxView.vue           # 收件箱（三栏布局）
│   │   ├── router/                 # Vue Router
│   │   └── styles/                 # 全局样式
│   └── package.json            # NPM 依赖
├── frontend/
│   ├── docker-compose.db.yml           # Lightrag 数据库配置
│   ├── docker-compose.lightrags.yml    # Lightrag server 启动配置
│   └── lightrag.env                    # Lightrag server 环境配置
├── .gitignore
└── README.md                   # 本文件

• Python 3.8+（推荐 3.11）
• Node.js 20+ 或 22+
• Azure AD 应用注册（获取 Client ID）
• LightRAG Server（两个实例：EmailRAG 与 ProfileRAG）
• 阿里百炼 API Key（通义千问）

git clone https://github.com/your-org/mail-agent.git
cd mail-agent

cd backend
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt

创建 backend/.env 文件：

# Azure AD 配置
AZURE_CLIENT_ID=your_client_id_here
AZURE_TENANT_ID=common

# LightRAG Server 地址
EMAIL_RAG_URL=http://localhost:9622
PROFILE_RAG_URL=http://localhost:9623
EMAIL_RAG_API_KEY=your_email_rag_key
PROFILE_RAG_API_KEY=your_profile_rag_key

# 阿里百炼配置
BAILIAN_API_KEY=sk-your_bailian_key_here
BAILIAN_API_ENDPOINT=https://dashscope.aliyuncs.com/compatible-mode/v1
BAILIAN_MODEL=qwen-plus

# 方式 1：使用 uvicorn（推荐，支持热重载）
uvicorn main:app --host 0.0.0.0 --port 5000 --reload

# 方式 2：使用启动脚本
./start.sh

# 方式 3：直接运行 Python
python main.py

后端将启动在 http://localhost:5000

自动生成的 API 文档：

• Swagger UI: http://localhost:5000/docs
• ReDoc: http://localhost:5000/redoc

cd frontend
npm install

创建 frontend/.env 文件：

VITE_API_URL=http://localhost:5000

如不创建，默认使用 http://localhost:5000。

npm run dev

前端将启动在 http://localhost:5173

npm run build
npm run preview

需要部署两个独立的 LightRAG Server 实例，参考 databases 文件夹中的容器启动：

# 实例 1: EmailRAG (端口 9622)
# 按照 HKUDS/LightRAG 仓库说明启动服务

# 实例 2: ProfileRAG (端口 9623)
# 使用不同端口与工作目录再次启动

推荐使用 Docker 或 systemd 管理服务进程。

1. 访问 Azure Portal → Azure Active Directory → 应用注册
2. 点击新注册，填写应用名称（如 Mail Agent）
3. 支持的账户类型：选择"任何组织目录（多租户）和个人 Microsoft 账户"
4. 身份验证 → 允许公共客户端流：启用
5. API 权限 → 添加委托权限（Delegated）：
   • Mail.Read
   • Mail.ReadWrite
   • Mail.Send
   • MailboxSettings.ReadWrite（管理类别与规则）
   • Calendars.ReadWrite（日历集成，可选）
   • offline_access（长效令牌）
6. 点击授予管理员同意（或用户首次登录时授权）

1. 访问 http://localhost:5173
2. 点击使用 Microsoft 账号登录
3. 页面显示设备码（如 ABC-DEF-GHI）并自动打开 Microsoft 验证页面
4. 在验证页面输入设备码并完成登录
5. 前端自动检测登录成功并跳转到收件箱

增量同步：

• 点击工具栏同步按钮，仅拉取新邮件与更改
• 系统会缓存 Delta Link，下次同步从上次中断处继续

强制同步：

• 点击强制按钮，清空缓存并重新全量同步

分类标签：

• 全部、学术、课程、行政、社团、推广、任务、通知、讲座、活动
• 点击标签筛选对应类别的邮件
• 标题栏显示"总数/未读数"，随筛选动态更新

优先级筛选：

• High / Medium / Low / Uninteresting
• 可与分类标签组合使用

邮件卡片信息：

• 发件人、主题、摘要、时间
• AI 优先级徽章
• 已读/未读状态

点击邮件卡片进入详情面板（桌面端右侧，移动端跳转新页面）：

邮件正文：

• HTML 自动消毒（DOMPurify）
• 自适应宽度，支持长链接断行
• 图片与媒体自动缩放

AI 智能标注：

• 优先级、分类、是否需回复
• 推荐动作（如"回复导师"、"添加日历"）
• 分类原因

手动反馈：

• 修改分类标签（多选）
• 调整优先级
• 标记是否需回复
• 添加喜欢/不喜欢的主题（如"奖学金"、"促销"）
• 填写备注
• 提交后自动更新 Outlook 与 ProfileRAG

操作菜单：

• 重新分类：仅重新运行分类 Agent
• 强制重新摄入 + 分类：重新写入 EmailRAG 并分类

点击右下角聊天气泡打开对话框：

支持的查询类型：

• 检查 DDL："这周有课程作业 DDL 吗？"
• 搜索邮件："找一下导师上周发的关于项目的邮件"
• 起草回复："帮我回复这封邮件，语气要正式"
• 更新偏好："我对奖学金类邮件很感兴趣，请设为高优先"
• 分类邮件："把这封信标为学术+任务"

工具自动选择：

• 聊天 Agent 会根据问题自动调用合适的工具（Graph API、RAG、LLM）
• 无需手动指定命令

自动学习：

• 重要邮件（高优先级或已标记）自动提取关键信息并更新画像
• 用户反馈（分类纠正、主题标注）实时同步到 ProfileRAG

手动更新：

• 通过聊天助手输入："我是计算机科学专业研究生，研究方向是机器学习"
• 系统自动提取实体与关系并存储

画像内容：

• 个人信息（专业、年级、研究方向）
• 兴趣偏好（喜欢/不喜欢的主题）
• 联系人关系（导师、同学、社团）
• 行为模式（回复习惯、常用分类）

• FastAPI - 现代 Python Web 框架
• LangGraph - 智能体工作流编排
• Vue.js - 渐进式前端框架
• Tailwind CSS - CSS 样式
• Microsoft Graph API - Office 365 集成
• LightRAG - 轻量级 RAG 框架
• 阿里云百炼平台 - 通义千问 LLM