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 include read emails, check inbox, fetch emails, email summary, email attachments, mail listener, IMAP, QQ邮箱, Foxmail, 读邮件, 查看邮件, 收件箱, 邮件摘要, 邮件总结, 查收邮件, and 监听邮件.

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 内联图片	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秒轮询兜底