Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/wecom-skills/wecomcli-email
wecomcli-email
Verified何时用:仅当用户明确提到企业微信「邮箱/邮件」时使用;泛指发消息默认走本地或消息技能,纯日程/会议走 calendar/meeting 技能。企微邮件:发送/回复/转发、搜索列表、获取详情(正文/附件/内嵌图片),支持经邮件发送日程邀约和会议预定。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.8 KB |
| references/forward-mail.md | markdown | 6.9 KB |
| references/get-mail.md | markdown | 11.7 KB |
| references/reply-mail.md | markdown | 10.4 KB |
| references/search-mail.md | markdown | 14.1 KB |
| references/security.md | markdown | 2.6 KB |
| references/send-mail.md | markdown | 12.9 KB |
| references/send-schedule.md | markdown | 5.7 KB |
references/reply-mail.md
View on GitHub# 工作流示例:邮件回复
**适用场景**:用户需要回复某封邮件,可能带附件或正文内嵌图片。
## 执行前必读
当本文档流程中需要调用其他技能、或本技能内其他子命令(如 `wecom-cli mail search` / `wecom-cli mail get` / `wecom-cli mail send` 等)时,必须先阅读对应的 SKILL 或 reference 文档,获取完整的接口参数和调用规范后再执行。**禁止仅凭 `mail_id` 等字段直接拼装命令调用。**
## 步骤一:定位被回复邮件
若用户未直接提供邮件,参考 [search-mail](./search-mail.md) 搜索定位目标邮件(用主题关键词或发件人作为搜索条件),内部记录:
- `mail_id`(用于 `reply.last_mail_id`)
- **原邮件主题 `subject`**(用于步骤六构造新主题)
- **原邮件发件人邮箱 `sender.email`**(用于步骤三作为回复收件人,不要另外查通讯录)
三项都可以从搜索邮件接口返回的 `mails[]` 取得;若只有 `mail_id` 没有主题或发件人邮箱,参考 [get-mail](./get-mail.md) 获取邮件详情补齐。
> `mail_id` 字段对用户不可见,但 `subject` 需要用于构造新主题,务必拿到。
**搜索结果为多封邮件时的处理**:若搜索返回多封邮件且无法明确判断用户要回复哪一封,必须将搜索结果以摘要列表形式展示给用户(包含主题、发件人、发送时间等关键信息),让用户选择目标邮件后再继续后续步骤。禁止在有多封候选邮件时自行假定用户意图而直接选取某一封进行回复。
## 步骤二:获取回复正文
若用户未提供正文,用自然语言追问回复内容(可举例"收到,谢谢"、"好的,已知悉"等常见回复供用户参考)。
- **正文统一使用 Markdown**:回复正文写成 Markdown 片段(标题、列表、表格、加粗、链接等都可用 Markdown 表达),调用时设 `content_type: "markdown"`
- **需要内嵌图(截图/示意图)**:支持,走步骤五的内嵌图占位符流程(写法见 [send-mail](send-mail.md) 步骤五)
- 回复邮件**必须**填写正文,不能省略(唯一的"省略正文"场景是转发,不是回复)
- 内嵌图必须严格写成 ``(方括号留空,不带 alt 和 title),不要直接 base64 内联
## 步骤三:解析收件人
- **默认收件人为原邮件发件人**:若步骤一中返回的 `sender.email` 不为空,直接使用该邮箱填入 `to.emails`,不要查通讯录。**若 `sender.email` 为空,则通过 `wecomcli-contact` 查询发件人姓名,优先取其 `email` 填入 `to.emails`,若该用户也没有邮箱则使用其 `userid` 填入 `to.userids` 尝试投递,不要因为没有邮箱就直接拒绝回复;**
- **回复范围二选一,互斥**:`reply.reply_all` 只有两种正确用法,不能混用:
- **A. 全部回复(默认)**:用户说"回复这封邮件"、"帮我回一下"等未明确指定回复谁时,设 `reply.reply_all = true`。此时接口会**自动**把原邮件的收件人和抄送人作为本次回复的收件人/抄送人,**禁止**自己再把原邮件的收件人列表手动塞进 JSON 参数的 `to`/`cc`(重复且可能与接口行为冲突)。工作邮件通常涉及多个参与者,默认全部回复能确保所有人同步信息,避免遗漏关键干系人。
- **预览补全**:虽然接口参数 `to`/`cc` 不需要技能构造,但步骤七的预览**必须**完整列出最终会发到的所有人——使用步骤一记录的原邮件 `to[]` / `cc[]`:当原邮件发件人是自己时**不排除自己**,否则**排除自己**。具体规则见步骤七 7.1 及 [SKILL.md](../SKILL.md)「邮件发送预览」章节。
- **B. 自定义收件人/抄送人**:当用户明确说"只回复发件人"、"单独回复他"、"不要回复所有人",或要求指定具体的收件人/抄送人列表时,**必须**设 `reply.reply_all = false`,并由本技能手动构造 `to` / `cc` 字段(原发件人邮箱 + 用户额外指定的人)。
- **额外收件人解析**:如果用户指定了额外收件人/抄送人(不是原发件人,而是新增的人),按邮件发送工作流步骤二处理:仅当提供人名时走 `wecomcli-contact` 查询——优先取其 `email` 填入 `to.emails`/`cc.emails`,若该用户没有邮箱则使用其 `userid` 填入 `to.userids`/`cc.userids`;已提供完整邮箱则直接使用。注意:一旦出现额外指定,就属于上面 B 场景,必须配套设 `reply.reply_all = false`。
- **发件人**:由接口自动填充,无需查询通讯录获取发件人信息
## 步骤四:写正文到本地文件(必做,无例外)
用 `write` 把回复正文写入本地 Markdown 文件:
- `tmp/mail/mail_reply_<唯一后缀>.md`,文件内容为 Markdown 片段(与 send-mail 统一:正文是中间文件,一律写 `tmp/mail/`,不放产出物面板根目录,也不用自创的 `temp/output/` 路径)
调用 `mail send` 时,`content_type` 固定填 `"markdown"`,`file_path` 指向这个 `.md` 文件。
## 步骤五:处理附件和内嵌图片(如有)
如果回复中需要带附件或内嵌图片,参考 [send-mail](send-mail.md):`media_id` 与 `file_path` 二选一、禁止同时填,`media_id` 禁止自行构造,详见 send-mail.md 步骤四(附件)与步骤五(内嵌图片)。
内嵌图片的占位符引用同样要出现在步骤四写入的 Markdown 正文文件里——严格写成 ``(方括号留空,不带 alt 和 title,首尾 `$` 是协议的一部分,不能省),并在 `inline_images[]` 里用完全相同的含 `$` 字符串填 `content_id`,再用 `media_id` 或 `file_path` 关联图片内容(二选一,优先 `media_id`)。
## 步骤六:构造回复主题
回复主题必须由本技能自己构造并填入 `subject` 字段,接口不会自动拼前缀,也不能留空。
默认规则:
```
subject = "回复:" + 原邮件主题
```
例如原邮件主题为 `"Q2 项目进展汇报"`,构造后的回复主题为 `"回复:Q2 项目进展汇报"`。
**智能去重**:如果原邮件主题已经是某封邮件的回复,此时**直接沿用原主题**,不再叠加 `"回复:"` 前缀,避免出现 `"回复:回复:回复:xxx"` 这种链式叠加。
**匹配算法**:
1. 先 trim 掉原主题前导的空白字符
2. 大小写不敏感地判断开头是否是 `回复` 或 `re`(英文),后面跟中文冒号 `:` 或英文冒号 `:`
3. 冒号前后的空格数量**不影响匹配**:`Re: x`、`re:x`、`RE : x`、`回复: x`、`回复 :x` 都算命中
4. **命中时**:直接沿用原主题,必须**一字不差**保留原始的大小写、空格、标点,不要"顺手规范化"
5. **未命中时**:在原主题前面加 `"回复:"`(中文全角冒号)
| 原主题 | 判断 | 构造后的回复主题 |
|---|---|---|
| `Q2 项目进展汇报` | 未命中 | `回复:Q2 项目进展汇报` |
| `回复:Q2 项目进展汇报` | 命中 `回复:` | `回复:Q2 项目进展汇报`(沿用) |
| `Re: Weekly Sync` | 命中 `Re:` | `Re: Weekly Sync`(沿用) |
| `Re: Weekly Sync`(双空格) | 命中 `Re:` | `Re: Weekly Sync`(沿用,双空格原样保留) |
| `re: weekly sync`(全小写) | 命中 `re:`(大小写不敏感) | `re: weekly sync`(沿用,小写原样保留) |
| `RE : Weekly Sync`(冒号前有空格) | 命中 `RE :`(容忍空格) | `RE : Weekly Sync`(沿用) |
若用户明确指定了另一个主题,使用用户指定的值,不做上述构造。
## 步骤七:预览并回复邮件
### 7.1 预览回复邮件
调用 `wecom-cli mail send` 之前,必须先在对话中向用户展示一份回复邮件预览,让用户感知邮件内容。**预览只作为内容呈现,展示完成后无需主动追问"是否发送/确认",直接进入 7.2 调用接口**。
预览输出格式、字段说明见 [SKILL.md](../SKILL.md) 「邮件发送预览」章节。
### 7.2 调用接口
**前置检查**:调用接口前,确认刚刚已执行过 7.1 预览;若尚未预览,必须先回到 7.1。
把各步骤得到的参数组装成最终 JSON,调用 `wecom-cli mail send` 回复。
```bash
wecom-cli mail send --json '{
"to": {
"emails": ["<收件人邮箱>"],
"userids": ["<收件人 userid>"]
},
"subject": "回复:<原邮件主题>",
"file_path": "<步骤四写入的本地 .md 正文文件路径>",
"content_type": "markdown",
"reply": {
"last_mail_id": "<被回复邮件 mail_id>",
"reply_all": true
},
"attachments": [
{"media_id": "<媒体 ID,优先>"}
],
"inline_images": [
{"content_id": "$reply_img_1$", "media_id": "<媒体 ID,优先>"}
]
}'
```
- `subject` 必须按步骤六构造好的结果填入,不能留空也不能照抄原主题
- `file_path` 必须指向回复正文的本地 `.md` 文件,`content_type` 固定填 `"markdown"`
- 没有附件/内嵌图片时,可完全省略 `attachments` 和 `inline_images` 字段
- 接口返回 `mail_id` → 告知用户邮件已成功回复,展示收件人和主题即可。**`mail_id` 是一串不可读的内部编码,禁止出现在面向用户的任何输出中**
- 接口失败时 → **必须**按 SKILL.md「接口失败处理」展示 `error.message`(失败原因)和 `error.instruction`(解决建议);禁止只回复"失败"而不附带原因,禁止透出 `code`/`callid`,禁止盲目重试
## 关键注意点
- **收件人直接复用邮件接口返回的发件人邮箱**:定位邮件时参考 [search-mail](./search-mail.md) 搜索邮件或参考 [get-mail](./get-mail.md) 获取邮件详情,已返回 `sender.email`,直接填入 `to.emails`,禁止为了"解析收件人"去查通讯录(通讯录模糊搜索可能匹配同音不同人,导致邮件发给错误的人)
- **回复正文必填**:回复邮件不能留空
- **主题必填且必须构造**:接口不会自动拼 `Re: ` 前缀,技能自己负责把 `subject` 构造为 `"回复:" + 原邮件主题`;原主题已有 `回复:`/`Re:` 前缀时直接沿用。因此在步骤一定位邮件时就要把 `subject` 一起记下来
- 附件/内嵌图片:`media_id` 与 `file_path` 二选一、禁止同时填,`media_id` 禁止自行构造;详见 [send-mail](send-mail.md) 步骤四(附件)与步骤五(内嵌图片)
- **邮件总大小不超过 50MB**:正文文件 + 所有附件合计不能超过 50MB,上传失败时提醒用户检查是否超限
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |