Mail Skill 📧

Mail Skill 是一个专门为 AI 智能体（如 Claude Code、Trae 等）设计的强大邮件管理技能。它让 AI 能够像专业秘书一样帮你处理邮件——收发、搜索、分类、总结、回复，样样精通。

• 多账户支持：同时管理多个邮箱账户，数据隔离存储
• 异步收取：后台批量拉取邮件，支持指定文件夹、时间范围、已读状态过滤
• 专业发信：Markdown 自动转精美 HTML，支持附件、抄送、密送
• 智能回复：自动带上原始邮件历史，支持回复全部

• 全文搜索：基于 SQLite FTS5 的快速关键词搜索
• 语义搜索：基于 OpenAI Embeddings + ChromaDB 的向量相似度搜索
• 混合搜索：FTS + 向量 + Cross-Encoder 重排序，搜索更精准
• 自然语言搜索：支持中文日期表达式，如"上周老板发的关于预算的邮件"

• 邮件分类：自动识别重要程度（critical/high/normal/low）和类别（work/personal/notification/promo）
• AI 回复：基于原始邮件和上下文线程生成专业回复，支持用户意图指导
• 邮件总结：按发件人分组生成摘要报告，快速掌握邮件概况
• 附件解析：支持 PDF、Excel、PPT、图片（OCR）等内容提取

• 标签系统：添加/删除标签，支持批量操作
• 批量标记：批量设置已读/星标状态
• 邮件移动：在文件夹间移动邮件
• 邮件删除：本地和服务器同步删除

• Web 配置界面：通过浏览器轻松配置账户和设置
• 精美输出：邮件详情以 Markdown 格式呈现，阅读体验极佳
• 附件信息：显示附件文件路径和内容摘要
• 签名档：每个账户可配置独立签名

• Python 3.8 或以上
• 支持 IMAP 或 POP3 的邮箱账户
• 无需外部 LLM API Key — Agent 模式默认开启，所有 AI 功能由 Agent（Claude）原生提供
• 可选：配置外部 LLM API Key 获得更快的自动化体验（支持 DeepSeek / 硅基流动 / 通义千问等 OpenAI 兼容 API）

# 1. 克隆项目
git clone <repository-url>
cd mail-skill

# 2. 安装依赖
pip install -r requirements.txt

# 3. 自动配置邮箱（推荐）
python scripts/mail_cli.py auto-configure your@email.com "授权码"

# 4. 或手动配置
cp example.config.txt config.txt
# 编辑 config.txt，填入你的邮箱信息

新功能：auto-configure 支持 29 个常见邮箱服务商自动识别（QQ、163、Gmail、Outlook 等），用户只需提供邮箱地址和授权码即可自动生成配置。

提示：大多数邮箱（QQ、Gmail、网易等）需要使用应用专用密码而非登录密码。请在邮箱设置中开启 IMAP/SMTP 服务并生成授权码。

如果你在 Claude Code、WorkBuddy、Cursor 等 AI Agent 中使用本 Skill，无需手动编辑配置文件。Agent 具备编码和文件操作能力，只需用自然语言描述配置需求即可：

在 Agent 对话中直接说：

"帮我配置邮件功能，我的 QQ 邮箱是 123456@qq.com，授权码是 xxxx，LLM 用 DeepSeek，API Key 是 sk-xxxx"

"添加第二个邮箱账户，163 邮箱 myname@163.com"

Agent 会自动：

1. 复制 example.config.txt → config.txt
2. 填入你提供的邮箱和 API 信息
3. 自动识别常见邮箱的 IMAP/SMTP 服务器地址

无需编写任何代码或修改配置文件。

# 收取邮件（默认最近 7 天）
python scripts/mail_cli.py fetch

# 搜索邮件
python scripts/mail_cli.py search --query "项目报告"

# 语义搜索（理解含义，不只是关键词）
python scripts/mail_cli.py search --query "下周会议安排" --vector

# 自然语言搜索
python scripts/mail_cli.py smart-search "上周老板发的关于预算的邮件"

# 阅读邮件
python scripts/mail_cli.py read <message_id>

# 发送邮件
python scripts/mail_cli.py send --to recipient@example.com --subject "主题" --body "正文"

# 回复邮件
python scripts/mail_cli.py reply <message_id> --body "回复内容"

# Agent 辅助回复 — 输出结构化邮件数据，Agent 自行撰写回复
python scripts/mail_cli.py ai-reply <message_id>

# 邮件摘要报告 — 按发件人分组，Agent 自行总结
python scripts/mail_cli.py summary-report --days 7

# 邮件分类（规则引擎）
python scripts/mail_cli.py classify <message_id>

# 解析附件内容（图片使用 vision-skill 识别）
python scripts/mail_cli.py parse-attachments --message-id <message_id>

# 列出所有支持的服务商
python scripts/mail_cli.py list-providers

# 标签管理
python scripts/mail_cli.py tag add <message_id> "重要"
python scripts/mail_cli.py tag batch-add "待处理" --from-search "from:boss"

# 批量标记
python scripts/mail_cli.py batch-mark --from-search "newsletter" --read 1

# 查看邮件线程
python scripts/mail_cli.py thread <message_id>

# 重建搜索索引
python scripts/mail_cli.py rebuild-index

mail-skill/
├── scripts/
│   ├── mail_cli.py              # 主 CLI 入口
│   └── mail_manager/
│       ├── client.py            # IMAP/SMTP 客户端
│       ├── db.py                # 数据库操作（SQLite + ChromaDB）
│       ├── config_manager.py    # 配置管理（读取 config.txt）
│       ├── classifier.py        # 邮件分类器
│       ├── query_parser.py      # 自然语言查询解析
│       ├── date_parser.py       # 中文日期解析
│       ├── detail.py            # 邮件详情格式化
│       ├── templates.py         # 邮件模板
│       ├── thread_manager.py    # 邮件线程管理
│       ├── summary_report.py    # 邮件摘要报告
│       ├── reply_assistant.py   # AI 回复助手
│       ├── email_providers.py  # 29 个邮箱服务商自动配置
│       ├── errors.py            # 错误码定义
│       ├── llm/                 # LLM 客户端（Agent+外部双模式）
│       │   ├── client.py
│       │   └── prompts.py
│       └── attachment_parser/   # 附件解析器（图片用vision-skill）
│           ├── pdf_parser.py
│           ├── excel_parser.py
│           ├── pptx_parser.py
│           ├── image_parser.py
│           └── text_parser.py
├── tests/                       # 测试文件
├── mail_data/                   # 数据目录（运行时生成）
│   └── <account>/               # 按账户隔离存储
│       ├── mail_index.db        # 邮件索引
│       ├── eml/                 # 原始邮件
│       ├── attachments/         # 附件
│       └── signature.md         # 签名档
├── config.txt                   # 配置文件（从 example.config.txt 复制）
├── SKILL.md                     # Agent 技能说明
├── README.md                    # 本文件
└── requirements.txt             # 依赖列表

• Agent 模式（默认）：无需配置任何外部 LLM API Key，所有 AI 功能由 Agent（Claude）原生提供
  • ai-reply：输出结构化邮件数据，Agent 自行撰写回复
  • summary-report：按发件人分组输出，Agent 自行总结
  • thread --summary：输出线程时间线，Agent 自行摘要
• 邮箱服务商自动配置：auto-configure 命令支持 29 个常见邮箱服务商（QQ、163、Gmail、Outlook 等），只需邮箱地址和授权码即可自动生成配置
• vision-skill 集成：图片附件自动使用 vision-skill 识别内容，无需配置视觉模型
• 外部 LLM 可选化：配置 LLM_API_KEY 后走外部 API 直接调用（更快自动化），不配置则使用 Agent 模式

• is_ai_enabled() 不再阻断 AI 功能 — Agent 模式下所有命令正常可用
• config.txt 中已清除泄露的真实 API Key

• POP3 协议支持：同时支持 IMAP 和 POP3 协议，可通过 MAIL_ACCOUNT_N_PROTOCOL=pop3 切换
• 独立 AI 供应商配置：LLM 和 Embedding 可使用不同供应商（如 LLM 用 DeepSeek，Embedding 用阿里云）
• AI 功能可选化：不配置 LLM_API_KEY 时，邮件收发、搜索等基础功能正常工作，AI 功能优雅降级
• 环境变量命名重构：OPENAI_API_KEY → LLM_API_KEY，EMBEDDING_API_KEY 独立配置

• 导入修复：移除脆弱的 from scripts.xxx 导入，改为 from mail_manager.xxx
• 可选依赖懒加载：chromadb、markdown、jinja2、openpyxl、fitz、pptx 等模块缺失时不再阻止 CLI 启动
• 协议一致性：IMAP/POP3 的 Message-ID 归一化、日期时区处理、端口解析统一
• 配置安全：端口值类型转换保护、USE_SSL 布尔化、空账户前置检查
• SQLite WAL 模式：启用 WAL 日志 + busy_timeout，提升并发安全性
• ChromaDB 防重试风暴：初始化失败后禁用重试，避免无限错误循环
• 线程时间线修复：in_reply_to 括号匹配，SQLITE_MAX_VARIABLE 分块查询
• LLM prompt 安全：{ } 转义防止 str.format() crash
• 全局错误处理：main() 未配置账户时输出友好 JSON 错误
• 资源泄漏修复：tempfile.mkdtemp 注册 atexit 清理、MailBox socket 异常释放、数据库连接管理

• Web 配置界面：回归 config.txt 文件配置方式
• SQLite 配置数据库：简化配置流程

自然语言搜索

• 支持"上周"、"本月"、"昨天"等中文日期表达式
• 自动提取搜索意图中的发件人、时间范围、关键词
• 与发件人列表进行模糊匹配，提高搜索准确度

邮件分类系统

• 自动识别邮件重要程度：critical / high / normal / low
• 自动识别邮件类别：work / personal / notification / promo
• 支持基于规则引擎的分类（可配置 YAML 规则）
• 支持手动重新分类

AI 回复助手

• 基于原始邮件内容生成专业回复
• 支持包含邮件线程上下文
• 支持"用户意图"指导（如"礼貌拒绝"、"确认参加"）
• 回复反馈学习机制，越用越准

邮件摘要报告

• 按发件人分组生成 Markdown 格式摘要报告
• 支持自定义日期范围
• LLM 生成每组的简要总结
• 支持输出到文件

附件内容解析

• 支持 PDF 文档文本提取
• 支持 Excel 表格内容读取
• 支持 PPT 演示文稿内容提取
• 支持图片 OCR（通过视觉模型）
• 解析内容存入数据库，支持搜索

邮件线程管理

• 增强的线程时间线显示
• 基于发件人/收件人匹配的线程关联
• 支持生成线程摘要

批量操作

• 批量标记已读/星标
• 批量添加标签
• 支持从搜索结果批量操作

其他改进

• 邮件详情 Markdown 格式化，阅读体验更好
• 邮件模板系统，支持自定义模板
• 统一的错误码和响应格式
• 完整的类型注解

• 测试覆盖率达到 75%
• 模块化架构，易于扩展
• 完善的错误处理机制

Q: 连接邮箱失败怎么办？

检查以下几点：

1. 确认 IMAP/SMTP 服务已开启
2. 使用应用专用密码而非登录密码
3. 检查服务器地址和端口是否正确
4. 检查网络是否需要代理

Q: 搜索结果为空？

运行 python scripts/mail_cli.py rebuild-index 重建搜索索引。

Q: AI 功能报错？

Agent 模式下无需配置任何 API Key。如已配置外部 Key 但报错，请检查 Key 有效性和 API 地址。

Q: 如何查看附件内容？

使用 python scripts/mail_cli.py read <message_id> -a 可显示附件文件路径和内容摘要。需要先运行 parse-attachments 解析附件内容。

Q: 数据存储在哪里？

所有数据存储在 ./mail_data/ 目录下，按账户隔离。删除此目录不影响邮箱服务器上的原始数据。

MIT License

欢迎提交 Issue 和 Pull Request！