QQ邮箱管理器#

关键约束（必须遵守）#

以下规则在每次操作中均不可违反，优先级高于所有其他指导：

1. 唯一定位：所有操作必须使用 folder + mail_id 定位邮件。mail_id 仅在单个文件夹内唯一，禁止仅按 mail_id 定位、去重或操作
2. 操作确认：删除/移动邮件必须先预览（不加 --confirm）并展示给用户，用户明确确认后才执行；发送邮件必须先展示收件人、主题、正文摘要，确认后才发送
3. 分页展示：每次只调用一次 search_emails.py，将返回结果展示给用户。当 has_more=true 时，在末尾提示"还有更多邮件，需要查看下一页吗？"后停止——无论用户要求多少封、还差几封凑齐，都不得自行发起第二次调用，必须等用户明确要求翻页后才可使用 --offset
4. 表格模板：向用户展示邮件信息时一律使用以下表格，即使只有一封邮件也必须使用，禁止自由叙述：

foldermail_id主题发件人日期

1. 错误阻断：脚本返回 error 或 partial 状态时，必须告知用户，不得继续执行删除/移动/发送等破坏性操作

任务目标#

• 本 Skill 用于：管理QQ邮箱，实现邮件的收取、搜索、删除和发送
• 能力包含：列出文件夹、浏览/搜索邮件、查看邮件详情、下载附件、标记已读/未读、移动/删除邮件、发送邮件
• 触发条件：用户表达"查看邮件"、"搜索邮件"、"删除邮件"、"移动邮件"、"发送邮件"、"有哪些文件夹"等意图

前置准备#

• 用户需在QQ邮箱中开启IMAP/SMTP服务并获取授权码（非QQ登录密码）
• OpenClaw 环境变量： QQ_EMAIL（邮箱地址）和 QQ_EMAIL_AUTH_CODE（QQ邮箱授权码）
• 脚本仍兼容旧 Coze 环境变量，但 OpenClaw 中优先使用上述通用变量
• 详细配置步骤见 references/qq-email-config.md

操作步骤#

1. 列出文件夹#

bash

python "{baseDir}/scripts/list_folders.py"

返回的 name 字段即为其他脚本 --folder 参数的可选值。

2. 浏览/搜索邮件#

统一入口，无搜索条件时浏览邮件列表，有条件时搜索邮件。

与 get_email 的边界：

• search_emails.py：浏览/搜索邮件，返回摘要（编号、主题、发件人、日期）
• get_email.py：获取邮件完整内容（正文、附件列表），需先通过 search 找到 mail_id 后再调用
• 用户说"读取/查看某封邮件"时，应使用 get_email

搜索模式选择规则：

• 只有用户明确表达"语义搜索"意图时（如"帮我语义搜索"、"语义分析邮件"），才调用 semantic_search.py
• 其余所有情况一律使用 search_emails.py，包括浏览、关键词搜索、按字段搜索、按日期筛选
• 不要自行判断用户需求是否"需要语义理解"而擅自调用 semantic_search

搜索词扩展规则：

• 用户输入中文关键词时，自动补充对应英文/常用同义词，分别调用 search_emails.py 后按 folder + mail_id 合并去重
• 常见扩展："验证码"→ "验证码"+"verification code"；"账单"→ "账单"+"bill"+"order"；"会议"→ "会议"+"meeting"；"通知"→ "通知"+"notification"+"notice"

分页规则：

• --limit：期望返回的总结果数，不指定则返回全部
• limit <= 15：不分页，一次返回
• limit > 15 且 total_matched > 15：按15分页，用 --offset 翻页
• total_matched <= 15：无论 limit 多少，均一次返回
• 重要： --limit 是搜索范围，不是"必须凑齐的数量"。每次只调一次脚本，展示当页结果，has_more=true 时等用户确认再翻页

bash

# 浏览收件箱（不指定limit则返回全部，超过15封自动分页）
python "{baseDir}/scripts/search_emails.py" --folder INBOX

# 限定返回3封
python "{baseDir}/scripts/search_emails.py" --folder INBOX --limit 3

# 模糊搜索（匹配发件人、主题、收件人）
python "{baseDir}/scripts/search_emails.py" --query "会议" --folder INBOX

# 精确按字段搜索
python "{baseDir}/scripts/search_emails.py" --from "zhangsan@qq.com" --subject "通知"

# 日期范围筛选
python "{baseDir}/scripts/search_emails.py" --query "*" --since 2025-01-01 --before 2025-03-01

# 最近2小时的未读邮件
python "{baseDir}/scripts/search_emails.py" --query "*" --recent 2h --unseen

# 跨文件夹搜索
python "{baseDir}/scripts/search_emails.py" --query "验证码" --all-folders

# 翻页
python "{baseDir}/scripts/search_emails.py" --query "会议" --offset 15

3. 语义搜索#

仅在用户明确触发时使用。拉取指定文件夹的邮件元数据+正文摘要，供智能体做语义判断。

分类展示格式：每组标题标注分类名+数量，禁止编号范围缩写（如"#12-51"），必须逐封列出：

text

验证码邮件（3封）：
- #12 您的验证码是123456 — noreply@example.com
- #37 验证码通知 — security@bank.com

订阅邮件（2封）：
- #8 本周技术周刊 — newsletter@tech.com

bash

# 拉取收件箱最新100封邮件（默认）
python "{baseDir}/scripts/semantic_search.py" --folder INBOX

# 自定义拉取数量
python "{baseDir}/scripts/semantic_search.py" --folder INBOX --limit 50

4. 查看邮件详情#

bash

python "{baseDir}/scripts/get_email.py" --mail_ids <邮件编号> --folder INBOX
python "{baseDir}/scripts/get_email.py" --mail_ids 1,2,3 --folder INBOX

--mail_ids 和 --folder 均为必填，来自搜索结果中的字段。

5. 下载附件#

bash

python "{baseDir}/scripts/download_attachment.py" --mail_ids <编号> --folder INBOX --dir ./downloads
python "{baseDir}/scripts/download_attachment.py" --mail_ids <编号> --folder INBOX --file "报告.pdf"

6. 标记已读/未读#

bash

python "{baseDir}/scripts/mark_email.py" --mail_ids 123 --action read --folder INBOX
python "{baseDir}/scripts/mark_email.py" --mail_ids 1,2,3 --action unread --folder INBOX

--action： read =已读， unread =未读。

7. 移动/删除邮件#

删除=移至垃圾箱，不支持永久删除。 必须先预览再确认（见关键约束第2条）。

bash

# 预览删除
python "{baseDir}/scripts/move_email.py" --mail_ids 1,2,3 --src_folder INBOX --delete
# 确认删除
python "{baseDir}/scripts/move_email.py" --mail_ids 1,2,3 --src_folder INBOX --delete --confirm

# 预览移动
python "{baseDir}/scripts/move_email.py" --mail_ids 5 --src_folder INBOX --dst_folder "Sent Messages"
# 确认移动
python "{baseDir}/scripts/move_email.py" --mail_ids 5 --src_folder INBOX --dst_folder "Sent Messages" --confirm

8. 发送/回复邮件#

发送前必须展示收件人、主题、正文摘要并确认（见关键约束第2条）。

bash

# 发送纯文本邮件
python "{baseDir}/scripts/send_email.py" --to <收件人> --subject "<主题>" --body "<正文>"

# 发送HTML邮件
python "{baseDir}/scripts/send_email.py" --to <收件人> --subject "<主题>" --body "<h1>Hello</h1>" --html

# 从文件读取正文（正文含换行/引号/HTML或超过200字符时优先使用）
python "{baseDir}/scripts/send_email.py" --to <收件人> --subject "<主题>" --body-file ./content.html --html

# 回复邮件
python "{baseDir}/scripts/send_email.py" --reply-to-id <邮件编号> --reply-folder INBOX --body "<回复内容>"

# 回复并引用原文
python "{baseDir}/scripts/send_email.py" --reply-to-id <邮件编号> --reply-folder INBOX --reply-quote --body "<回复内容>"

# 测试SMTP连接
python "{baseDir}/scripts/send_email.py" --test

资源索引#

• 脚本: scripts/list_folders.py — 列出所有邮箱文件夹，参数:无

• 脚本: scripts/search_emails.py — 浏览/搜索邮件，支持跨文件夹。参数:

  • --query 模糊搜索（匹配发件人、主题、收件人）， * 表示不限关键词
  • --from 精确按发件人搜索（优先于 --query）
  • --subject 精确按主题搜索（可与 --from 组合）
  • --folder 邮箱文件夹，默认 INBOX
  • --all-folders 搜索所有文件夹
  • --since 起始日期，含当天（YYYY-MM-DD）
  • --before 截止日期，不含当天（YYYY-MM-DD）
  • --recent 最近时间段（30m/2h/7d/1w），分钟/小时级别做二次精确过滤
  • --seen/ --unseen 仅已读/未读（互斥）
  • --limit 期望总结果数，不指定返回全部，≤15不分页，>15按15分页
  • --offset 分页偏移量，默认0

• 脚本: scripts/semantic_search.py — 语义搜索，拉取邮件供智能体分析。参数: --folder(必填), --limit(默认100, 最大100)

• 脚本: scripts/get_email.py — 获取邮件详情。参数: --mail_ids(必填, 逗号分隔), --folder(必填)

• 脚本: scripts/download_attachment.py — 下载附件。参数: --mail_ids(必填, 逗号分隔), --folder(必填), --dir(输出目录, 默认当前目录), --file(仅下载指定附件名)

• 脚本: scripts/mark_email.py — 标记已读/未读。参数: --mail_ids(必填), --action(read/unread), --folder(必填)

• 脚本: scripts/move_email.py — 移动或删除邮件。参数: --mail_ids(必填), --src_folder(必填), --dst_folder(与--delete二选一), --delete(移至垃圾箱, 与--dst_folder二选一), --confirm(确认执行, 不加则仅预览)

• 脚本: scripts/send_email.py — 发送/回复邮件。参数: --to(收件人, 回复模式可省略), --subject(主题, 与--subject-file二选一, 回复模式可省略), --subject-file(从文件读主题), --body(正文, 与--body-file二选一), --body-file(从文件读正文, 优先于--body), --html(HTML格式), --cc(抄送), --bcc(密送), --attachments(附件路径), --reply-to-id(回复邮件编号), --reply-folder(回复时必填), --reply-quote(引用原文), --test(测试SMTP)

• 参考: references/qq-email-config.md — 凭证配置引导、授权码获取、服务器信息、常见问题

注意事项#

展示细节#

• 禁止编号范围缩写：展示邮件列表时禁止使用"1-5"等范围缩写，必须逐封列出
• 删除预览：除表格外还需显示收件时间
• 确认操作：确认删除/移动/回复时也必须用表格展示 folder + mail_id
• 分组明确：语义分类结果按类别分组，每组标题标注分类名+数量，编号不得跨组产生歧义

跨文件夹操作#

• 跨文件夹搜索合并结果时，按 folder + mail_id 组合去重，不同文件夹中相同 mail_id 视为不同邮件
• 跨文件夹搜索（ --all-folders）会遍历所有文件夹，文件夹较多时耗时较长

发送规范#

• 正文含换行、引号、HTML 或超过200字符时，优先使用 --body-file 从文件读取，避免命令行转义问题
• 复杂主题使用 --subject-file

其他#

• 不确定文件夹名称时，先调用 list_folders 获取可用值
• 删除邮件实际是移至垃圾箱，不支持永久删除