zrong 邮件处理 Skill
基于 IMAP 协议的邮件 CLI 工具。Python 3.13+ 必需。
首次使用
运行 init 命令交互式创建配置：
python3 scripts/email_tool.py init
会依次询问：
- 配置文件保存路径（默认
agent_config.toml，保存在当前项目目录） - 账户名（默认
qqmail） - 邮箱地址、IMAP/SMTP 服务器信息
- 密码/授权码
结果：
- 配置（含密码）写入
agent_config.toml（与其他 skill 共用同一配置文件） - 密码同时写入
.env（优先级更高） - 自动将
.env加入.gitignore - 自动测试 IMAP 连接
配置说明
配置文件为 agent_config.toml（多 skill 共用，按 [skill名] 分区）。
查找策略：当前目录 → skill 目录 → git 根目录。
模板位于 skill 目录的 agent_config.example.toml。
agent_config.toml（[email] 区块）：
[email.accounts.qqmail]
email = "user@example.com"
imap_host = "imap.qq.com"
imap_port = 993
smtp_host = "smtp.qq.com"
smtp_port = 465
password = "your_app_password"
密码优先级（从高到低）：
.env文件中的EMAIL_{ACCOUNT}_PASSWORD环境变量agent_config.toml中账户的password字段
环境变量命名规则：EMAIL_{ACCOUNT}_PASSWORD，ACCOUNT 为账户名大写。
脚本路径
相对于 skill 安装目录：scripts/email_tool.py
所有命令在项目目录下执行（配置文件通过三位置发现策略自动查找）。
命令速查
| 命令 | 用途 | 示例 |
|---|---|---|
init |
交互式初始化配置 | email_tool.py init |
folders |
列出所有文件夹 | email_tool.py folders |
list |
搜索列出邮件 | email_tool.py list --subject "发票" --last 5 |
read |
读取邮件内容 | email_tool.py read --uid 12345 |
download |
下载附件 | email_tool.py download --subject "发票" --ext pdf --output-dir /tmp |
move |
移动邮件 | email_tool.py move --subject "账单" --target-folder "账单" --yes |
search-links |
从 HTML 提取链接 | email_tool.py search-links --subject "京东" |
通用参数
--config PATH：配置文件路径（默认使用 agent_config.toml 三位置发现策略）--account NAME：账户名（默认 qqmail）--subject TEXT：主题关键词搜索--sender TEXT：发件人搜索--since DD-Mon-YYYY：起始日期（如01-Jan-2026）--before DD-Mon-YYYY：截止日期--last N：只处理最新 N 封
命令详情
init - 初始化配置
email_tool.py init
# 或指定配置路径
email_tool.py --config /path/to/agent_config.toml init
交互式询问账户信息，自动：
- 创建或追加到
agent_config.toml（[email.accounts.{name}]区块） - 将密码同时写入
.env（不覆盖已有内容） - 将
.env加入.gitignore - 测试 IMAP 连接
list - 列出邮件
email_tool.py list --subject "发票"
email_tool.py list --sender "jd.com" --last 3
email_tool.py list --subject "报告" --folder "工作"
输出 JSON 包含 uid、subject、from、date。
read - 读取邮件内容
email_tool.py read --uid 12345 12346
email_tool.py read --subject "发票" --last 1
email_tool.py read --uid 12345 --html
输出 JSON 包含 body、content_type、attachments（附件列表）。
download - 下载附件
email_tool.py download --uid 12345 --output-dir /tmp/attachments
email_tool.py download --subject "发票" --ext pdf --output-dir /tmp/invoices
email_tool.py download --subject "报销" --last 1 --output-dir .
move - 移动邮件
# dry run（默认，只列出不移动）
email_tool.py move --subject "账单" --target-folder "账单"
# 执行移动
email_tool.py move --subject "账单" --target-folder "账单" --yes
# 只移动最新一封
email_tool.py move --subject "通知" --target-folder "归档" --last 1 --yes
文件夹名支持中文，自动处理 IMAP modified UTF-7 编码。优先使用 MOVE 命令，不支持时降级 COPY+DELETE。
search-links - 提取链接
email_tool.py search-links --subject "京东"
email_tool.py search-links --sender "didifapiao"
输出 JSON 包含 pdf_links、xml_links、invoice_numbers。
注意事项
- Python 版本：必须 3.13+，无第三方依赖
- QQ 邮箱需要使用授权码（非登录密码），在 QQ 邮箱设置 → 账户 → IMAP 服务中生成
- 密码安全：密码可存放在
agent_config.toml的password字段中，或通过环境变量EMAIL_{ACCOUNT}_PASSWORD读取（环境变量优先） - IMAP 搜索支持中文（自动使用 UTF-8 charset）
- QQ Mail BEFORE bug：QQ 邮箱 IMAP 在 CHARSET UTF-8 模式下
BEFORE关键词返回空结果。工具已自动处理：服务端只发SINCE，BEFORE在本地按 Date 头过滤 move命令默认 dry run，必须加--yes才执行download的--ext参数支持逗号分隔多个扩展名（如pdf,xml）- 日期格式为 IMAP 标准格式：
DD-Mon-YYYY（如15-Mar-2026）