MailMind — AI Email Agent

开源、自部署、多协议（IMAP + POP + SMTP）统一的 AI 邮件代理

MailMind 是一个智能邮箱管家：接入你的邮箱后自动分类邮件、识别意图、提取联系人关系、生成回复草稿，并提供 Web Dashboard 审核后发送。

---

特性

• 多协议接入 — 支持 IMAP/POP/SMTP，兼容 QQ邮箱、163、Gmail、Outlook 等主流邮箱
• AI 驱动分类 — LLM 自动分类邮件（咨询/投诉/会议/通知/垃圾），识别紧急程度
• 关系网记忆 — 自动追踪联系人交互历史，时间线记录每次来往事件
• 智能起草 — 根据邮件上下文 + 联系人画像自动生成回复草稿，人工审核后通过 SMTP 发送
• Web 仪表盘 — 统一收件箱视图、规则配置、草稿审核队列

---

快速开始

环境要求

• Docker & Docker Compose
• LLM API Key（兼容 OpenAI 接口，支持 DeepSeek / OpenAI 等）

启动

# 1. 复制环境变量模板
cp .env.example .env

# 2. 编辑 .env，填入你的 LLM_API_KEY 和其他配置
# 3. 启动服务
docker compose up -d --build

访问 http://localhost:8000/health 验证服务运行状态。

Dashboard: http://localhost:8000/dashboard

直接运行（开发模式）

pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

---

架构概览

┌───────────────────────────────────────────────────────┐
│                     Web Dashboard                      │
│        收件箱 / 草稿审核 / 规则配置 / 联系人            │
└───────────────────────┬───────────────────────────────┘
                        │
┌───────────────────────▼───────────────────────────────┐
│                  FastAPI 路由层                         │
│  /api/emails  /api/contacts  /api/follow-ups  /api/digest│
└───────────────────────┬───────────────────────────────┘
                        │
┌───────────────────────▼───────────────────────────────┐
│                   核心服务层                             │
│                                                        │
│  ┌──────────┐ ┌────────────┐ ┌──────────────────────┐ │
│  │ 规则引擎  │ │  LLM 服务   │ │  关系网记忆 (M5)      │ │
│  │ rules    │ │ classify + │ │ ContactMemory        │ │
│  │ engine   │ │ draft +    │ │ add_contact /        │ │
│  │          │ │ embedding  │ │ timeline / search    │ │
│  └──────────┘ └────────────┘ └──────────────────────┘ │
│                                                        │
│  ┌──────────┐ ┌────────────┐ ┌──────────────────────┐ │
│  │  收件     │ │ 去重分组    │ │ 草稿审核通知 (QQ)     │ │
│  │ IMAP     │ │ dedup      │ │ draft_review         │ │
│  └──────────┘ └────────────┘ └──────────────────────┘ │
└───────────────────────┬───────────────────────────────┘
                        │
┌───────────────────────▼───────────────────────────────┐
│                 SQLAlchemy 2.0 + PostgreSQL             │
│  users  email_connections  emails  contacts            │
│  contact_events  follow_ups  user_configs              │
└───────────────────────────────────────────────────────┘

数据模型

表	说明
users	用户（邮箱登录）
email_connections	邮箱连接配置（IMAP/OAuth）
emails	邮件（正文、分类、优先级、意图）
contacts	联系人（email、公司、角色、嵌入向量）
contact_events	联系人事件时间线
follow_ups	待跟进事项 / 草稿
user_configs	用户偏好设置

目录结构

app/
├── main.py              # FastAPI 入口 + 生命周期
├── config.py            # 配置管理（环境变量）
├── database.py          # SQLAlchemy async engine + session
├── models/              # SQLAlchemy 模型
│   ├── user.py          # User
│   ├── email.py         # EmailConnection, Email
│   ├── followup.py      # FollowUp, UserConfig
│   └── contact.py       # Contact, ContactEvent
├── api/                 # API 路由
│   ├── auth.py          # OAuth + IMAP 健康检查
│   ├── emails.py        # 收件箱列表/详情
│   ├── contacts.py      # 联系人搜索 + 时间线
│   ├── followups.py     # 草稿审核队列
│   └── digest.py        # 每日摘要（占位）
├── routes/
│   └── dashboard.py     # Web Dashboard 页面 + 自动起草 API
├── services/
│   ├── imap_client.py   # IMAP 收件客户端
│   ├── rules_engine.py  # YAML 规则引擎
│   ├── llm.py           # LLM 分类/摘要
│   ├── draft.py         # LLM 回复生成
│   ├── dedup.py         # 邮件去重/线程合并
│   ├── draft_review.py  # 自动起草管道 + QQ 通知
│   ├── memory.py        # 联系人记忆系统
│   └── embedding.py     # 文本向量 + 语义检索
├── templates/           # Jinja2 Dashboard 模板
└── static/              # 静态资源

---

API 端点

方法	路径	说明
GET	/health	健康检查
GET	/api/emails	收件箱列表（支持 threaded 模式）
GET	/api/emails/{id}	邮件详情
GET	/api/contacts?q=	联系人搜索（关键字）
GET	/api/contacts/search?q=&semantic=true	语义搜索联系人
GET	/api/contacts/{email}/timeline	联系人交互时间线
GET	/api/follow-ups	草稿审核队列
POST	/api/follow-ups/{id}/approve	批准草稿
POST	/api/follow-ups/{id}/reject	拒绝草稿
GET	/api/auth/google	Google OAuth 授权 URL
GET	/api/auth/health/imap	IMAP 连接健康检查
POST	/dashboard/api/auto-draft	批量自动起草
POST	/dashboard/api/generate-draft	单封邮件生成草稿
POST	/dashboard/api/drafts/notify-qq	QQ 审核通知消息

---

环境变量

# 数据库
DATABASE_URL=postgresql+asyncpg://emailagent:emailagent@localhost:5432/emailagent

# LLM（兼容 OpenAI 接口）
LLM_API_KEY=sk-your-api-key
LLM_BASE_URL=https://api.deepseek.com
LLM_CLASSIFY_MODEL=deepseek-chat
LLM_DRAFT_MODEL=deepseek-chat
LLM_EMBEDDING_MODEL=text-embedding-3-small

# Google OAuth（Gmail API，可选）
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=http://localhost:8000/api/auth/google/callback

# 安全
SECRET_KEY=change-me-in-production

# 调试
DEBUG=true

---

规则引擎

通过 app/rules.yaml 配置邮件处理规则：

rules:
  - name: "Newsletter auto-archive"
    condition: { keywords: ["unsubscribe", "newsletter"] }
    action: { set_group: "newsletter", set_priority: 1, auto_draft: false }

  - name: "Urgent inquiry"
    condition: { keywords: ["urgent", "asap", "deadline"] }
    action: { set_group: "urgent", set_priority: 5, auto_draft: true }

  - name: "Team mail"
    condition: { from_domain: "maxeagle.site" }
    action: { set_group: "team", set_priority: 4, auto_draft: true }

支持 from_domain、keywords、and/or 组合条件；auto_draft: true 时自动触发 LLM 起草。

---

技术栈

• Python 3.12 + FastAPI
• SQLAlchemy 2.0 (async) + PostgreSQL 16
• Jinja2 模板渲染（Dashboard）
• OpenAI-compatible LLM API（分类/摘要/起草/向量）
• Docker Compose 一键部署

---

许可证

GNU Affero General Public License v3.0 (AGPL-3.0)

详见 LICENSE