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/send-mail.md
View on GitHub# 工作流示例:邮件发送
**适用场景**:用户需要发送新邮件给一个或多个收件人,可能带附件或正文内嵌图片。
## 执行前必读
当本文档流程中需要调用其他技能时,必须先阅读对应技能的 SKILL 文档,获取完整的接口参数和调用规范后再执行。
## 请求参数表
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|------|------|
| `to` | object | 是* | — | 收件人对象,`emails` 和 `userids` 二选一或都填。*回复全部场景可省略 |
| `to.emails` | array<string> | 否 | [] | 收件人邮箱地址列表 |
| `to.userids` | array<string> | 否 | [] | 收件人 userid 列表(`wo` 前缀) |
| `cc` | object | 否 | — | 抄送人对象,结构同 `to` |
| `bcc` | object | 否 | — | 密送人对象,结构同 `to` |
| `subject` | string | 是 | — | 邮件主题,不可留空。回复构造为 `"回复:" + 原主题`,转发构造为 `"转发:" + 原主题` |
| `file_path` | string | 否* | — | 邮件正文文件的本地路径,必须是 `.md` 文件(Markdown 片段) |
| `content_type` | string | 否 | `markdown` | 固定填 `markdown`。邮件正文统一使用 Markdown,由接口完成渲染 |
| `attachments` | array<object> | 否 | [] | 附件列表,每项含 `media_id`(企业微信媒体 ID,`mc` 前缀)或 `file_path`(本地文件路径,CLI 自动上传),**二选一,优先 `media_id`** |
| `inline_images` | array<object> | 否 | [] | 内嵌图片列表,每项含 `content_id`(含首尾 `$`)和 `media_id` 或 `file_path`(本地路径,CLI 自动上传),**二选一,优先 `media_id`** |
| `reply.last_mail_id` | string | 否 | — | 回复时填写被回复邮件的 `mail_id` |
| `reply.reply_all` | bool | 是 | `true` | 回复时是否回复全部 |
| `forward.last_mail_id` | string | 否 | — | 转发时填写被转发邮件的 `mail_id` |
| `schedule` | object | 否 | — | 日程会议邮件通用信息,参数细节见 [send-schedule](send-schedule.md) |
| `meeting` | object | 否 | — | 会议邮件特殊参数设置,必须配合 `schedule` 使用,参数细节见 [send-schedule](send-schedule.md) |
## 步骤一:获取邮件内容
获取邮件要素:主题、正文、收件人/抄送人(抄送人可不填)、附件列表(可不填)、内嵌图片列表(可不填)。必填参数缺失时,用自然语言追问用户补全。
- 如果用户未提供正文,用自然语言追问正文内容
- **正文统一使用 Markdown**:所有邮件正文都写 Markdown 片段,由接口完成渲染。标题、段落、列表、表格、引用、加粗、链接、代码块等常见排版都可用 Markdown 语法直接表达
- **需要内嵌图(截图/示意图)**:按"步骤五:处理内嵌图片"走 `$占位符$` 流程(固定写法 ``,方括号留空、不带 alt 和 title);不要把图片直接 base64 内联,那样会让正文急剧膨胀
- **内容忠实性**:正文只写用户明确提供的信息;用户要求包含某类内容但未给出具体内容时(如"写下经验和反思"但没说反思了什么),用自然语言追问,不要自行编造
- **落款**:正文末尾的署名必须是发件人(当前用户),不能用收件人或抄送人的名字
- **日期推断**:用户提到的日期若缺少年份,结合当前日期推断——未过去用今年,已过去用明年;涉及未来事项时确认日期在当前之后
## 步骤二:解析收件人/抄送人
对每个收件人/抄送人**分别独立执行**以下流程:
**判断是否需要查询通讯录**:
- 若用户已直接提供完整邮箱地址(含 `@`),**跳过通讯录查询**,直接使用该邮箱填入 `to.emails`/`cc.emails`
- 若用户提供的是人名或昵称(不含 `@`),则执行以下通讯录查询流程
**通讯录查询流程(仅当用户提供人名时执行)**:
1. **先阅读 `wecomcli-contact` 技能的 SKILL.md**,获取完整的接口参数和调用规范,然后使用该技能的"模糊搜索用户"能力搜索目标人员
2. 返回唯一匹配 → 优先取其 `email` 填入 `to.emails`;若该用户没有邮箱,则使用其 `userid` 填入 `to.userids` 尝试投递。**不要因为对方没有邮箱就直接拒绝发送**
3. 返回少量候选人(2-5 人)→ 用 Markdown 表格列出候选人(姓名/职位),用自然语言请用户回复序号选择目标
4. 返回结果过多(超过 5 人)→ 超过 5 位时先展示前 5 位候选供用户选择(遵循 wecomcli-contact 的展示规则),用户仍无法确认时再请其补充部门/职位缩小范围
**发件人**:由接口自动填充,无需查询通讯录获取发件人信息。
## 步骤三:写正文到本地文件
用 `write` 把正文写入本地 Markdown 文件:
```
tmp/mail/mail_body_<唯一后缀>.md
```
- 正文是**中间文件**(发送后即无用),按工作环境规则必须写进 `tmp/` 子目录,不要放到产出物面板的根目录;本技能统一用 `tmp/mail/`,reply-mail 同
- `<唯一后缀>` 可用时间戳或简短主题拼成,避免多次发送相互覆盖
- 文件内容是 Markdown 片段,直接写自然的 Markdown 语法(标题、段落、列表、表格、引用、加粗、链接、代码块、分隔线等)
- 调用 `mail send` 时设 `content_type: "markdown"`,`file_path` 指向这个 `.md` 文件
- 如果有内嵌图片占位符(见步骤五),此时应该已经写在 Markdown 文件里,形式必须是 ``(方括号留空,不带 alt 和 title)
> 唯一允许省略 `file_path` 的场景是"转发且不加附加说明"(见 [forward-mail](forward-mail.md)),此时接口会自动带上原邮件正文。
## 可选步骤四:处理附件(有附件时执行)
附件支持 `media_id` 和 `file_path` 两种填法,**二选一,优先 `media_id`**:
- **优先 `media_id`**:如果用户已直接提供 `media_id`(例如来自其他邮件/消息的引用),或本地文件已通过 `wecomcli-media` 的 `media upload` 上传得到 `media_id`,直接复用
- **退而求其次 `file_path`**:手头只有本地文件且无现成 `media_id` 时,直接传 `file_path`,CLI 会自动完成上传,无需手动调用 `wecomcli-media`
把所有附件组装成 `attachments` 数组,每项**只填其中一个**字段:
```json
"attachments": [
{"media_id": "mcabc123..."},
{"file_path": "/path/to/attachment2.xlsx"}
]
```
注意事项:
- 同一项里 `media_id` 和 `file_path` **不能同时填**,二选一
- `media_id` 必须以 `mc` 开头,且来自 `wecomcli-media` 接口的真实返回值,**禁止自行构造或猜测**
- `file_path` 必须是有效的本地文件路径
- 已经有 `media_id` 时**不要**再多此一举先下载成本地文件再走 `file_path`
## 可选步骤五:处理内嵌图片(有内嵌图时执行)
内嵌图片是指需要出现在正文 **中间位置** 的图片(如截图、示意图),与附件不同,它们要在正文渲染里显示。
> **关键契约**:企业微信邮件的发送接口用 **整段标签模板匹配** 实现内嵌图,**不是** 标准 MIME `cid:`,也**不是** 单纯的 `$xxx$` 子串替换。正文里的图片必须严格写成 Markdown 图片语法 ``(方括号留空,不带 alt 和 title),发送时接口会把整个标签替换为真正的内嵌图片 MIME 引用。只要方括号里填了文字,或者在 `$xxx$` 后面加了 title 引号(无论内容是否为空),模板就不再匹配,占位符不会被替换,收件人看到的是原样的 `$xxx$` 字符串或坏图。
### 操作步骤
1. **为每张图片想一个占位符字符串**:建议使用短小的英文数字下划线组合,例如 `chart01`、`progress_chart`、`screenshot_1`,避免空格、中文和特殊字符。同一封邮件里不同图片必须使用不同的占位符。
2. **在 Markdown 正文里用 `` 引用**(方括号留空,不带 alt 和 title):
```markdown
下图是本周进度曲线:

```
3. **组装 `inline_images` 数组**:每项用 `content_id` 填正文里出现的 `$<占位符>$` **完整字符串(含首尾 `$`)**,再用 `media_id` 或 `file_path` 指向图片内容(**二选一,优先 `media_id`**):
```json
"inline_images": [
{"content_id": "$progress_chart$", "media_id": "mcabc123..."},
{"content_id": "$screenshot_1$", "file_path": "/path/to/screenshot.png"}
]
```
**核心约束**:
1. **正文里 `$xxx$` 的完整值必须和 `inline_images[].content_id` 字段一字不差**——包括首尾的 `$` 和中间字符的大小写
2. **图片语法必须严格是 ``**:方括号必须留空,**禁止**在 `$xxx$` 后面加 title 引号(无论内容是否为空),任何偏差都会让模板匹配失败
## 可选步骤六:组装日程参数(当用户需要发送日程邀约或会议邮件时)
如果用户需要发送**日程邀约**或**预约会议**(例如"帮我约个会"、"发一个日程邀请"、"约大家下周三开会"),需要额外组装 `schedule`(以及可选的 `meeting`)对象。普通邮件跳过本步骤。
**详细参数说明、默认值、重复规则、会议参数及组装示例请参阅 [send-schedule](send-schedule.md)**。
## 步骤七:预览并发送邮件
### 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>"]
},
"cc": {
"emails": ["<抄送人邮箱>"],
"userids": ["<抄送人 userid>"]
},
"subject": "<邮件主题>",
"file_path": "<步骤三写入的本地 .md 正文文件路径>",
"content_type": "markdown",
"attachments": [
{"media_id": "<媒体 ID,优先>"}
],
"inline_images": [
{"content_id": "$progress_chart$", "media_id": "<媒体 ID,优先>"}
]
}'
```
### 业务约束
- **主题前缀去重**:回复/转发时,若原主题已有同类前缀(`回复`/`re`/`转发`/`fwd`/`fw` + 冒号,大小写不敏感)则直接沿用,不重复叠加;跨类型不抵消
- **发送成功后**:向用户确认"邮件已成功发送",展示收件人和主题即可。`mail_id` 禁止出现在面向用户的输出中
- 接口返回 `mail_id` → 告知用户邮件已成功发送,展示收件人和主题即可。`mail_id` 是一串不可读的内部编码(如 `CiA8tfm...`),对用户完全没有意义,禁止出现在面向用户的任何输出中——不要说"邮件 ID:xxx",不要放在反馈消息的任何位置
- 接口失败时 → **必须**按 SKILL.md「接口失败处理」展示 `error.message`(失败原因)和 `error.instruction`(解决建议);禁止只回复"失败"而不附原因,禁止透出 `code`/`callid`,禁止盲目重试
## 关键注意点
- **正文一律用 `file_path`**:任何长度的正文都要先写文件再传路径。
- **正文统一是 Markdown**:写入 `.md` 文件,`content_type` 固定填 `"markdown"`。
- **附件和内嵌图片**:`media_id` 与 `file_path` 二选一、禁止同时填,`media_id` 禁止自行构造;详见「可选步骤四:处理附件」与「可选步骤五:处理内嵌图片」。
- **`content_id` 必须含首尾 `$` 且与正文一字不差**:正文里 `` 中的 `$xxx$` 部分要和 `inline_images[].content_id` 完全一致(包括两端的 `$`,大小写敏感);少一个 `$`、多一个空格都会让接口无法完成替换
- **内嵌图必须严格写成 ``**:方括号必须留空,**禁止**在 `$xxx$` 后面加 title 引号(无论内容是否为空)。接口按整段标签做模板匹配,方括号里有文字、或者后面多了 title 引号都会让匹配失败,占位符不会被替换
- **收件人解析**:用户提供完整邮箱地址(含 `@`)时直接使用,无需查询通讯录;仅当用户提供人名/昵称时才走通讯录查询流程,且**必须对每个人名分别独立执行**,不能批量传入多个人名
- **发件人无需查询**:发件人由接口自动填充,不要调用通讯录查询当前用户信息
- **邮件总大小不超过 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 |