@rezti/dsh-rez-suite 0.1.49 → 0.1.51

package/templates/shared/wecomcli-email/references/send-mail.md

@@ -0,0 +1,186 @@
+# 工作流示例：邮件发送
+
+**适用场景**：用户需要发送新邮件给一个或多个收件人，可能带附件或正文内嵌图片。
+
+## 执行前必读
+
+当本文档流程中需要调用其他技能时，必须先阅读对应技能的 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 语法直接表达
+- **需要内嵌图（截图/示意图）**：按"步骤五：处理内嵌图片"走 `$占位符$` 流程（固定写法 `![]($xxx$)`，方括号留空、不带 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 人）→ 用自然语言请用户提供更多信息（如部门/职位）缩小范围后重新搜索
+
+**发件人**：由接口自动填充，无需查询通讯录获取发件人信息。
+
+## 步骤三：写正文到本地文件
+
+用 Write 工具把正文写入本地 Markdown 文件：
+
+```
+{产出目录}/mail_body_<唯一后缀>.md
+```
+
+- `<唯一后缀>` 可用时间戳或简短主题拼成，避免多次发送相互覆盖
+- 文件内容是 Markdown 片段，直接写自然的 Markdown 语法（标题、段落、列表、表格、引用、加粗、链接、代码块、分隔线等）
+- 调用 `mail send` 时设 `content_type: "markdown"`，`file_path` 指向这个 `.md` 文件
+- 如果有内嵌图片占位符（见步骤五），此时应该已经写在 Markdown 文件里，形式必须是 `![]($xxx$)`（方括号留空，不带 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 图片语法 `![]($xxx$)`（方括号留空，不带 alt 和 title），发送时接口会把整个标签替换为真正的内嵌图片 MIME 引用。只要方括号里填了文字，或者在 `$xxx$` 后面加了 title 引号（无论内容是否为空），模板就不再匹配，占位符不会被替换，收件人看到的是原样的 `$xxx$` 字符串或坏图。
+
+### 操作步骤
+
+1. **为每张图片想一个占位符字符串**：建议使用短小的英文数字下划线组合，例如 `chart01`、`progress_chart`、`screenshot_1`，避免空格、中文和特殊字符。同一封邮件里不同图片必须使用不同的占位符。
+2. **在 Markdown 正文里用 `![]($<占位符>$)` 引用**（方括号留空，不带 alt 和 title）：
+   ```markdown
+   下图是本周进度曲线：
+
+   ![]($progress_chart$)
+   ```
+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$)`**：方括号必须留空，**禁止**在 `$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`**：`attachments` / `inline_images` 的每一项**二选一**填 `media_id` 或 `file_path`，**优先用 `media_id`**——已有 `media_id` 直接复用，不要多此一举先下载成本地文件再走 `file_path`；仅无现成 `media_id` 时才填 `file_path`，CLI 内部基于 `file_path` 自动完成上传。`media_id` 必须来自接口真实返回值，禁止自行构造。
+- **`content_id` 必须含首尾 `$` 且与正文一字不差**：正文里 `![]($xxx$)` 中的 `$xxx$` 部分要和 `inline_images[].content_id` 完全一致（包括两端的 `$`，大小写敏感）；少一个 `$`、多一个空格都会让接口无法完成替换
+- **内嵌图必须严格写成 `![]($xxx$)`**：方括号必须留空，**禁止**在 `$xxx$` 后面加 title 引号（无论内容是否为空）。接口按整段标签做模板匹配，方括号里有文字、或者后面多了 title 引号都会让匹配失败，占位符不会被替换
+- **收件人解析**：用户提供完整邮箱地址（含 `@`）时直接使用，无需查询通讯录；仅当用户提供人名/昵称时才走通讯录查询流程，且**必须对每个人名分别独立执行**，不能批量传入多个人名
+- **发件人无需查询**：发件人由接口自动填充，不要调用通讯录查询当前用户信息
+- **邮件总大小不超过 50MB**：正文文件 + 所有附件合计不能超过 50MB。如果上传正文文件或附件时失败，提醒用户检查邮件总大小是否超限，建议精简正文内容、减少附件数量或压缩附件后重试

package/templates/shared/wecomcli-email/references/send-schedule.md

@@ -0,0 +1,83 @@
+# 邮件日程与会议参数说明
+
+**适用场景**：用户需要发送日程邀约或会议邮件时，需要额外组装 `schedule`（以及可选的 `meeting`）对象。普通邮件无需关注本文档。
+
+---
+
+## 日程与会议的关系
+
+- **日程邀约**：只需填 `schedule`，不需要 `meeting`。适用于用户没有明确说要"开会/会议"的场景，如日程提醒、活动通知、约碰头等
+- **会议邮件**：必须**同时**填 `schedule` 和 `meeting`。只要用户明确说要"发会议邮件"、"约个会议"等，即视为会议邮件，**不区分线下还是线上**（线下会议也会创建，用户可自行选择是否使用线上会议室，线下地点通过 `location` 字段承载）。单独填 `meeting` 而不填 `schedule` 会导致接口报错
+- 判断依据：用户说"开会"、"开个线上会议"、"拉个视频会"、"约腾讯会议"→ 会议邮件（schedule + meeting）；用户说"发个日程"、"约个碰头"、"提醒大家周五有活动"→ 日程邀约（仅 schedule）。不确定时直接问用户"需要创建线上会议室吗？"
+
+## schedule 参数补全
+
+以下参数用户未提供时**必须用自然语言追问用户补全，禁止猜测或使用默认值**：
+
+| 参数 | 格式 | 追问示例 |
+|---|---|---|
+| 开始时间 (`begin_time`) | `YYYY-MM-DD HH:mm:ss` | "请问日程/会议的开始时间是？" |
+| 结束时间 (`end_time`) | `YYYY-MM-DD HH:mm:ss` | "结束时间是几点？"（如果用户只说了"开一小时的会"，可自行推算） |
+
+以下参数有合理默认值，用户未提供时**可使用默认值**，无需追问：
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `method` | `"request"` | 固定值，不需要向用户询问 |
+| `location` | 不填 | 可选，用户提到地点时才填 |
+| `reminders.is_remind` | `true` | 默认开启提醒 |
+| `reminders.remind_before_event_mins` | `15` | 默认提前 15 分钟提醒 |
+| `reminders.timezone` | `{"timezone_id": "Asia/Shanghai", "timezone_offset": 28800}` | 默认北京时间；`timezone_id` 为 IANA 时区标识，`timezone_offset` 为相对 UTC 的秒数偏移 |
+| `reminders.is_repeat` | `false` | 默认不重复 |
+
+---
+
+## 重复规则（用户明确要求时才填）
+
+当用户要求日程重复（如"每周三都开"、"每天提醒我"），需要组装 `reminders` 中的重复相关字段：
+
+- `is_repeat`: `true`
+- `is_custom_repeat`: 当用户要求特定日期重复时设为 `true`（如"每周三和周五"）
+- `repeat_type`: `daily` / `weekly` / `monthly` / `yearly`
+- `repeat_interval`: 重复间隔（如"每两周"则为 2），仅自定义重复时有效
+- `repeat_day_of_week`：每周周几重复，取值为英文缩写字符串（`MO`=周一，`TU`=周二，`WE`=周三，`TH`=周四，`FR`=周五，`SA`=周六，`SU`=周日），仅 `repeat_type=weekly` 且自定义重复时有效
+- `repeat_day_of_month`: 每月哪几天重复，取值 1~31，仅 `repeat_type=monthly` 或 `yearly` 时有效
+- `repeat_month_of_year`: 每年哪几个月重复，取值 1~12，仅 `repeat_type=yearly` 时有效
+- `repeat_until`: 重复结束时刻（格式 `YYYY-MM-DD HH:mm:ss`），不填表示一直重复
+
+> **注意**：音视频会议（即同时填了 `meeting` 的场景）对重复规则有限制，某些重复组合不被支持。如果接口拒绝重复规则，按 SKILL.md「接口失败处理规范」展示 `error.message` 和 `error.instruction`，告知用户调整重复规则。
+
+---
+
+## 日程管理员（可选）
+
+`schedule_admins` 最多指定 3 人，且必须是同企业用户且在邮件参与人（收件人/抄送人）中。不填时所有参与人权限相同。当用户说"让张三来管理这个日程"时才填。
+
+---
+
+## meeting 参数补全（仅会议邮件场景）
+
+当判定为会议邮件时，组装 `meeting` 对象。以下参数均有合理默认值，用户未提到时**使用默认值**：
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `meeting_admins` | 不填（默认为发件人） | 仅可指定 1 人，用户说"让 xx 管理会议"时才填 |
+| `hosts` | 不填 | 会议主持人，最多 10 人，用户说"xx 来主持"时才填 |
+| `option.password` | 不填（无密码） | 4~6 位纯数字，用户说"加个会议密码"时才填 |
+| `option.auto_record` | `"off"` | 用户说"自动录制"时改为 `"cloud"` 或 `"local"` |
+| `option.enable_waiting_room` | `false` | 用户说"开等候室"时设 `true` |
+| `option.allow_enter_before_host` | `false` | 用户说"允许提前入会"时设 `true` |
+| `option.enable_screen_watermark` | `false` | 用户说"开屏幕水印"时设 `true` |
+| `option.enable_enter_mute` | `"auto_over_6"` | 默认超过 6 人自动静音 |
+| `option.enter_restraint` | `"all"` | 用户说"只允许企业内部人员"时改为 `"internal_only"` |
+| `option.remind_scope` | `"host_only"` | 用户说"提醒所有人入会"时改为 `"all"` |
+| `option.water_mark_type` | `"single"` | 默认单排水印 |
+
+---
+
+## 关键注意点
+
+- **会议邮件必须同时带 `schedule`**：`meeting` 对象不能单独使用，必须同时填写 `schedule`。漏掉 `schedule` 会导致接口报错。日程邀约则可以不填 `meeting`
+- **`begin_time` 不能小于当前时间**：接口会校验 `begin_time`，过去的时间会被接口拒绝。若用户提供的开始时间早于当前系统时间，必须用自然语言询问用户重新选择时间，禁止自行调整或猜测
+- **会议持续时间不超过 24 小时**：`end_time` 减 `begin_time` 超过 24 小时会被接口拒绝
+- **会议对重复规则有限制**：音视频会议不是所有重复规则都支持，接口拒绝时按 SKILL.md「接口失败处理规范」展示 `error.message` 和 `error.instruction` 告知用户调整

package/templates/shared/wecomcli-media/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: wecomcli-media
+version: 1.0.0
+description: 企业微信媒体文件上传/下载技能。承接基于 media_id 下载媒体文件到本地，以及上传本地文件获取 media_id 两类操作。当其他技能（微盘、邮件等）返回了 media_id 需要落地为本地文件，或已有本地文件需要转换为 media_id 供其他技能使用时，必须先读取本技能获取完整指引，不得凭记忆处理。本技能不解析/识别文件内容，仅负责文件本身的搬运。
+metadata:
+  requires:
+    bins: ["wecom-cli"]
+  cliHelp: "wecom-cli media --help"
+---
+
+# 企业微信媒体文件
+
+> 执行任何 `wecom-cli` 命令前，必须先读取并完成 `wecomcli-shared` 技能的公共前置检查。
+
+资源型 skill，负责基于 `media_id` 下载媒体文件到本地，以及把本地文件上传为 `media_id`。是其他技能（微盘、邮件等）处理 `media_id` 相关操作的基础依赖：`upload` 会产出新的 `media_id`，但本 skill 不负责搜索/发现其他业务场景中已存在的 `media_id`（如邮件附件、微盘文件的 `media_id` 由对应业务技能产出），也不解析文件内容。
+
+## 适用范围
+
+### 适用
+
+- 根据其他技能或用户提供的 `media_id` 下载媒体文件到本地
+- 上传本地文件（本地路径已知）获取 `media_id`，供其他技能后续使用（如微盘上传素材）
+
+### 不适用
+
+- 解析/识别文件内容（正文提取、OCR、看图问答、PDF/Word/Excel 解析等） → 本 skill 只负责把文件下载到本地拿 `file_path`，如需查看内容请直接通过 `file_path` 读取该本地文件
+- 搜索/发现其他业务场景中已存在的 `media_id`（如邮件附件、微盘文件列表/搜索等） → 由对应业务技能负责产出并返回 `media_id`，本 skill 只接收已有的 `media_id` 做下载；本地文件转`media_id` 的场景仍走本 skill 的 `upload`
+- 编造或猜测 `media_id` / 本地文件路径 → 两者必须来自其他技能返回或用户明确提供，禁止自行构造
+
+## 接口详述
+
+### 下载媒体文件
+
+根据 `media_id` 下载媒体文件到本地，返回本地文件路径。
+
+**命令**
+
+```bash
+wecom-cli media download --json '{"media_id": "MEDIA_ID"}'
+```
+
+**入参**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|:----:|---|
+| `media_id` | string | 是 | 文件的 `media_id`，由上传文件后获得，或由其他技能（邮件附件/内嵌图片等）返回 |
+
+**返回**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `file_path` | string | 下载成功后的本地文件路径 |
+
+**使用规则**
+
+- 下载完成后如需查看文件内容，直接通过 `file_path` 读取该本地文件。
+- 下载失败时返回错误码和错误信息。
+- **`media_id` 必须是真正的 media_id，不接受任何形式的 URL**：若拿到的是一个链接（如 `attach_url`、正文里的图片/附件链接），**不要**把这个 URL 当作 `media_id` 传入本接口，会直接报错。尤其是命中 `work.weixin.qq.com/filepreview/security/` 特征的防泄漏加密链接，属于加密的、与用户身份绑定的资源，本接口**无法下载或解密**，应直接告知用户该文件受防泄漏策略保护，引导其点击链接、在企业微信客户端内打开查看/保存，不要尝试用本接口或其他手段绕过。
+
+### 上传媒体文件
+
+将本地文件上传，获取 `media_id`。
+
+**命令**
+
+```bash
+wecom-cli media upload --json '{"file_path": "/tmp/example.pdf"}'
+```
+
+**入参**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|:----:|---|
+| `file_path` | string | 是 | 需要上传的文件的本地路径 |
+
+**返回**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `type` | string | 媒体类型：`image`(图片)/`voice`(语音)/`video`(视频)/`file`(文件) |
+| `media_id` | string | 上传后的 `media_id`，供其他技能后续使用（如微盘`upload` 的 `file_content_media`） |
+| `created_at` | string | 创建时间，格式：`YYYY-MM-DD HH:mm:ss`|
+
+## 关键约束
+
+- **`media_id` / `file_path` 不得编造**：`media_id` 必须来自上传结果、其他技能返回或用户明确提供；`file_path` 必须是真实存在的本地路径。两者都没有时用自然语言追问，禁止靠猜测凑一个。
+- **不做内容解析**：本 skill 只负责文件的下载落地与上传，`download` 拿到 `file_path` 后如需查看内容，直接通过 `file_path` 读取，不在本 skill 职责范围内。
+- **内部 ID 不外露**：`media_id` 仅用于后续接口调用，禁止直接展示给用户；下载后的本地 `file_path` 同样不展示给用户。
+- **CLI 报错原样转达**：命令返回明确错误码时如实告知用户并给替代建议，禁止用 curl / python 等通用手段绕过 CLI 强行完成。
+
+## 跨技能依赖
+
+| 依赖场景 | 说明 |
+|---|---|
+| `wecomcli-email` | 邮件附件/内嵌图片的 `media_id`，使用本 skill 的 `download` 下载到本地后通过 `file_path` 读取 |
+| `wecomcli-disk` | 上传文件到微盘时若已有 `media_id`，直接作为 `disk files upload` 的 `file_content_media` 使用，无需再走本 skill；若只有本地路径且需要先转成 `media_id`，可用本 skill 的 `upload` |
+
+> 参数缺失 / 意图不明确时，用自然语言追问让用户明确，不要瞎猜。