| name | z-mail-reader |
| description | Use when user wants to read emails, check inbox, fetch emails via IMAP, download email attachments, extract inline images, or summarize email content. Also supports real-time polling for new emails with system notifications. Triggers: read emails, check inbox, fetch emails, email summary, email attachments, mail listener, IMAP, QQ邮箱, Foxmail, 读邮件, 查看邮件, 收件箱, 邮件摘要, 邮件总结, 查收邮件, 监听邮件. |
z-mail-reader — IMAP 邮件读取与实时监听
Overview
通过 IMAP 协议连接任意邮箱（默认 QQ 邮箱），读取指定时间范围内的邮件，自动下载附件和内嵌图片到本地，并生成邮件内容摘要。支持 实时轮询监听，新邮件到达时自动处理并发送系统通知。
核心原理： Python imaplib → IMAP 服务器 → 解析邮件 → 保存附件/图片 → Agent 生成摘要
前置配置
使用前需设置环境变量（或在调用时通过参数传入）：
export MAIL_IMAP_SERVER="imap.qq.com"
export MAIL_ADDR="your_email@qq.com"
export MAIL_AUTH_CODE="your_auth_code"
QQ 邮箱获取授权码方法： QQ邮箱 → 设置 → 账户 → POP3/IMAP/SMTP服务 → 开启 IMAP → 生成授权码
存储目录
邮件附件、图片和摘要保存到：
{output_dir}/
└── YYYYMMDD_HHMM_邮件主题/
├── 附件文件...
├── images/ # 正文中的图片
│ ├── img_001.png
│ └── ...
└── sum.md # 邮件摘要（Agent 生成）
核心流程
1. 确定时间范围（本周/最近N天/自定义）
↓
2. 运行 Python 脚本连接 IMAP 获取邮件
↓
3. 脚本自动：解析邮件头、提取正文、下载附件、保存正文图片
↓
4. 为每封邮件创建独立目录（按时间+主题命名）
↓
5. Agent 阅读邮件内容，生成 sum.md 摘要
↓
6. 汇总输出邮件列表给用户
脚本位置
scripts/
├── read_emails.py # IMAP 邮件读取
└── listen_emails.py # 实时轮询监听
使用方法
读取邮件
python3 scripts/read_emails.py --email "you@qq.com" --auth-code "YOUR_CODE" --days 7
参数说明
| 参数 | 默认值 | 说明 |
|---|
--email | 环境变量 MAIL_ADDR | 邮箱地址 |
--auth-code | 环境变量 MAIL_AUTH_CODE | IMAP 授权码 |
--days | 7 | 读取最近 N 天 |
--since | - | 起始日期 YYYY-MM-DD |
--until | - | 截止日期 YYYY-MM-DD |
--folder | INBOX | 邮件文件夹 |
--output-dir | ./mails | 输出目录 |
--limit | 100 | 最大邮件数量 |
--body-length | 3000 | 正文截取长度 |
实时监听
python3 scripts/listen_emails.py --start
python3 scripts/listen_emails.py --start > /dev/null 2>&1 &
python3 scripts/listen_emails.py --status
python3 scripts/listen_emails.py --stop
python3 scripts/listen_emails.py --once
输出格式
脚本输出 JSON 到 stdout（进度信息输出到 stderr）：
{
"total": 5,
"emails": [
{
"subject": "邮件主题",
"from": "发件人",
"date": "2026-06-05 14:30:00",
"body_preview": "正文前3000字...",
"attachments": [{"filename": "附件.pdf", "path": "...", "size": 12345}],
"inline_images": [{"filename": "img_001.png", "path": "...", "size": 67890, "source": "cid"}],
"output_dir": "/path/to/mails/20260605_1430_邮件主题",
"has_attachments": true,
"has_images": true
}
]
}
图片保存说明
脚本自动保存三类正文图片：
| 类型 | source | 说明 |
|---|
| CID 内联图片 | cid | 邮件 MIME 中 Content-ID 引用的图片 |
| HTML 外链图片 | url | <img src="https://..."> 自动下载 |
| Base64 嵌入图 | base64 | data:image/... 编码的图片 |
Agent 工作步骤
1. 运行脚本获取邮件
python3 scripts/read_emails.py --days 7
2. 为每封邮件生成 sum.md
在每封邮件的 output_dir 下创建 sum.md，包含：邮件元信息、摘要、附件列表、正文图片引用。
3. 汇总报告
向用户输出简洁的邮件列表。
依赖
- Python 3.8+
imapclient（监听模式需要）：pip3 install imapclient
注意事项
- 授权码安全：推荐用环境变量，不要在输出中显示完整授权码
- 附件大小：超大附件（>50MB）可能被 IMAP 服务器跳过
- 编码兼容：脚本自动处理 UTF-8/GBK/GB2312 编码
- IMAP 限制：部分邮箱有频率限制，监听轮询间隔默认30秒
- QQ邮箱特殊性：QQ邮箱的 IMAP IDLE 不推送事件，脚本已内置轮询兜底
常见问题
| 问题 | 解决方案 |
|---|
| 登录失败 | 检查授权码是否正确，邮箱是否开启了 IMAP |
| 找不到邮件 | 尝试扩大时间范围或检查文件夹名称 |
| 附件下载失败 | 可能是超大附件，检查网络连接 |
| 正文乱码 | 脚本已自动处理常见编码 |
| 监听无反应 | QQ邮箱不支持 IDLE 推送，已用30秒轮询兜底 |
