Skill: sccc726/qq-mail-manager (version 1.0.0)

--- 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邮箱地址，例如 [REDACTED_SECRET]"},{"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 "[REDACTED_SECRET]" --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 — [REDACTED_SECRET] - #37 验证码通知 — [REDACTED_SECRET] 订阅邮件（2封）： - #8 本周技术周刊 — [REDACTED_SECRET] ``` ```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 获取可用值 - 删除邮件实际是移至垃圾箱，不支持永久删除


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)