QQ邮箱管理技能,支持收取、搜索、删除和发送邮件;当用户需要查看邮箱、查找邮件、管理邮件或发送邮件时使用
---
name: qq-mail-manager
description: QQ邮箱管理技能,支持收取、搜索、删除和发送邮件;当用户需要查看邮箱、查找邮件、管理邮件或发送邮件时使用
metadata: {"openclaw":{"requires":{"env":["QQ_EMAIL","QQ_EMAIL_AUTH_CODE"]},"primaryEnv":"QQ_EMAIL","envVars":[{"name":"QQ_EMAIL","required":true,"description":"QQ邮箱地址,例如 123456@qq.com"},{"name":"QQ_EMAIL_AUTH_CODE","required":true,"description":"QQ邮箱 IMAP/SMTP 授权码,不是 QQ 登录密码"}]}}
---
# QQ邮箱管理器
## 关键约束(必须遵守)
以下规则在每次操作中均不可违反,优先级高于所有其他指导:
1. **唯一定位**:所有操作必须使用 `folder + mail_id` 定位邮件。mail_id 仅在单个文件夹内唯一,禁止仅按 mail_id 定位、去重或操作
2. **操作确认**:删除/移动邮件必须先预览(不加 `--confirm`)并展示给用户,用户明确确认后才执行;发送邮件必须先展示收件人、主题、正文摘要,确认后才发送
3. **分页展示**:每次只调用一次 search_emails.py,将返回结果展示给用户。当 `has_more=true` 时,在末尾提示"还有更多邮件,需要查看下一页吗?"后停止——无论用户要求多少封、还差几封凑齐,都不得自行发起第二次调用,必须等用户明确要求翻页后才可使用 `--offset`
4. **表格模板**:向用户展示邮件信息时一律使用以下表格,即使只有一封邮件也必须使用,禁止自由叙述:
| folder | mail_id | 主题 | 发件人 | 日期 |
|--------|---------|------|--------|------|
5. **错误阻断**:脚本返回 `error` 或 `partial` 状态时,必须告知用户,不得继续执行删除/移动/发送等破坏性操作
## 任务目标
- 本 Skill 用于:管理QQ邮箱,实现邮件的收取、搜索、删除和发送
- 能力包含:列出文件夹、浏览/搜索邮件、查看邮件详情、下载附件、标记已读/未读、移动/删除邮件、发送邮件
- 触发条件:用户表达"查看邮件"、"搜索邮件"、"删除邮件"、"移动邮件"、"发送邮件"、"有哪些文件夹"等意图
## 前置准备
- 用户需在QQ邮箱中开启IMAP/SMTP服务并获取授权码(非QQ登录密码)
- OpenClaw 环境变量:`QQ_EMAIL`(邮箱地址)和 `QQ_EMAIL_AUTH_CODE`(QQ邮箱授权码)
- 脚本仍兼容旧 Coze 环境变量,但 OpenClaw 中优先使用上述通用变量
- 详细配置步骤见 [references/qq-email-config.md](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"),必须逐封列出:
```
验证码邮件(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/list_folders.py) — 列出所有邮箱文件夹,参数:无
- 脚本: [scripts/search_emails.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](scripts/semantic_search.py) — 语义搜索,拉取邮件供智能体分析。参数: `--folder`(必填), `--limit`(默认100, 最大100)
- 脚本: [scripts/get_email.py](scripts/get_email.py) — 获取邮件详情。参数: `--mail_ids`(必填, 逗号分隔), `--folder`(必填)
- 脚本: [scripts/download_attachment.py](scripts/download_attachment.py) — 下载附件。参数: `--mail_ids`(必填, 逗号分隔), `--folder`(必填), `--dir`(输出目录, 默认当前目录), `--file`(仅下载指定附件名)
- 脚本: [scripts/mark_email.py](scripts/mark_email.py) — 标记已读/未读。参数: `--mail_ids`(必填), `--action`(read/unread), `--folder`(必填)
- 脚本: [scripts/move_email.py](scripts/move_email.py) — 移动或删除邮件。参数: `--mail_ids`(必填), `--src_folder`(必填), `--dst_folder`(与--delete二选一), `--delete`(移至垃圾箱, 与--dst_folder二选一), `--confirm`(确认执行, 不加则仅预览)
- 脚本: [scripts/send_email.py](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](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 获取可用值
- 删除邮件实际是移至垃圾箱,不支持永久删除
don't have the plugin yet? install it then click "run inline in claude" again.