QQ邮箱管理器 关键约束（必须遵守）

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

唯一定位：所有操作必须使用 folder + mAIl_id 定位邮件。mAIl_id 仅在单个文件夹内唯一，禁止仅按 mAIl_id 定位、去重或操作 操作确认：删除/移动邮件必须先预览（不加 --confirm）并展示给用户，用户明确确认后才执行；发送邮件必须先展示收件人、主题、正文摘要，确认后才发送 分页展示：每次只调用一次 搜索_emAIls.py，将返回结果展示给用户。当 has_more=true 时，在末尾提示"还有更多邮件，需要查看下一页吗？"后停止——无论用户要求多少封、还差几封凑齐，都不得自行发起第二次调用，必须等用户明确要求翻页后才可使用 --off设置 表格模板：向用户展示邮件信息时一律使用以下表格，即使只有一封邮件也必须使用，禁止自由叙述： folder mAIl_id 主题 发件人 日期 错误阻断：脚本返回 error 或 partial 状态时，必须告知用户，不得继续执行删除/移动/发送等破坏性操作 任务目标 本 技能 用于：管理QQ邮箱，实现邮件的收取、搜索、删除和发送 能力包含：列出文件夹、浏览/搜索邮件、查看邮件详情、下载附件、标记已读/未读、移动/删除邮件、发送邮件 触发条件：用户表达"查看邮件"、"搜索邮件"、"删除邮件"、"移动邮件"、"发送邮件"、"有哪些文件夹"等意图 前置准备 用户需在QQ邮箱中开启IMAP/SMTP服务并获取授权码（非QQ登录密码） OpenClaw 环境变量：QQ_EMAIL（邮箱地址）和 QQ_EMAIL_AUTH_CODE（QQ邮箱授权码） 脚本仍兼容旧 Coze 环境变量，但 OpenClaw 中优先使用上述通用变量 详细配置步骤见 references/qq-emAIl-config.md 操作步骤

• 列出文件夹

python "{baseDir}/scripts/列出_folders.py"

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

• 浏览/搜索邮件

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

与 获取_emAIl 的边界：

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

搜索模式选择规则：

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

搜索词扩展规则：

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

分页规则：

--limit：期望返回的总结果数，不指定则返回全部 limit <= 15：不分页，一次返回 limit > 15 且 total_matched > 15：按15分页，用 --off设置 翻页 total_matched <= 15：无论 limit 多少，均一次返回 重要：--limit 是搜索范围，不是"必须凑齐的数量"。每次只调一次脚本，展示当页结果，has_more=true 时等用户确认再翻页 # 浏览收件箱（不指定limit则返回全部，超过15封自动分页） python "{baseDir}/scripts/搜索_emAIls.py" --folder INBOX

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

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

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

# 日期范围筛选 python "{baseDir}/scripts/搜索_emAIls.py" --查询 "" --since 2025-01-01 --before 2025-03-01

# 最近2小时的未读邮件 python "{baseDir}/scripts/搜索_emAIls.py" --查询 "" --recent 2h --unseen

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

# 翻页 python "{baseDir}/scripts/搜索_emAIls.py" --查询 "会议" --off设置 15

• 语义搜索

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

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

验证码邮件（3封）：

• #12 您的验证码是123456 — noreply@example.com
• #37 验证码通知 — security@bank.com

订阅邮件（2封）：

• #8 本周技术周刊 — newsletter@tech.com

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

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

• 查看邮件详情

python "{baseDir}/scripts/获取_emAIl.py" --mAIl_ids <邮件编号> --folder INBOX python "{baseDir}/scripts/获取_emAIl.py" --mAIl_ids 1,2,3 --folder INBOX

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

• 下载附件

python "{baseDir}/scripts/下载_attachment.py" --mAIl_ids <编号> --folder INBOX --dir ./下载s python "{baseDir}/scripts/下载_attachment.py" --mAIl_ids <编号> --folder INBOX --file "报告.pdf"

• 标记已读/未读

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=未读。

• 移动/删除邮件

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

# 预览删除 python "{baseDir}/scripts/move_emAIl.py" --mAIl_ids 1,2,3 --src_folder INBOX --删除 # 确认删除 python "{baseDir}/scripts/move_emAIl.py" --mAIl_ids 1,2,3 --src_folder INBOX --删除 --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

• 发送/回复邮件

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

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

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

Hello

" --html

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

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

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

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

资源索引 脚本: scripts/列出_folders.py — 列出所有邮箱文件夹，参数:无 脚本: scripts/搜索_emAIls.py — 浏览/搜索邮件，支持跨文件夹。参数: --查询 模糊搜索（匹配发件人、主题、收件人），* 表示不限关键词 --from 精确按发件人搜索（优先于 --查询） --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分页 --off设置 分页偏移量，默认0 脚本: scr