z-mail-reader

---

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"    # IMAP 服务器地址
export MAIL_ADDR="[e-mail]"     # 邮箱地址
export MAIL_AUTH_CODE="your_auth_code"   # IMAP 授权码（非登录密码）

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 "[e-mail]" --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	正文截取长度

实时监听

# 前台监听（Ctrl+C 停止）
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

注意事项

1. 授权码安全：推荐用环境变量，不要在输出中显示完整授权码
2. 附件大小：超大附件（>50MB）可能被 IMAP 服务器跳过
3. 编码兼容：脚本自动处理 UTF-8/GBK/GB2312 编码
4. IMAP 限制：部分邮箱有频率限制，监听轮询间隔默认30秒
5. QQ邮箱特殊性：QQ邮箱的 IMAP IDLE 不推送事件，脚本已内置轮询兜底

常见问题

问题	解决方案
登录失败	检查授权码是否正确，邮箱是否开启了 IMAP
找不到邮件	尝试扩大时间范围或检查文件夹名称
附件下载失败	可能是超大附件，检查网络连接
正文乱码	脚本已自动处理常见编码
监听无反应	QQ邮箱不支持 IDLE 推送，已用30秒轮询兜底