# 媒体文件

在**你的本地文件**和**企业微信里的文件形态**之间搬运：把本地文件传上去，或者把企业微信里的文件落到本地。
它只搬运，不看内容——不做 OCR、不读 PDF 正文、不做看图问答。

**这一域你基本不会直接点名。** 它是别的能力在流程中间自动调用的一步：
发图片消息、读邮件附件、把已有素材放进微盘，都要先经过它换一次形态。
写这一篇是为了让你知道「为什么发图片比发文字多花一步」。

## 你可以怎么说

大多数时候你不会这么说，而是说下面这些话——由助手自己决定要不要调它：

> 「把这张图发到群里」（发消息前会自动上传一次）
> 「下载邮件里的附件看看」（读附件内容前会自动下载一次）
> 「这个 PDF 传到微盘」（**这个反而不需要**，见下）

## 📋 验证状态

| 项 | 状态 |
|---|---|
| 上传本地文件 | ⚠️ **未实测** |
| 下载文件到本地 | ⚠️ **未实测** |
| 完整链路 | ⚠️ 未实测 |

**本域没有做过独立实测。** 它总是被别的能力顺带调用，验收过程中没有单独跑过这两个方法，
也没有跑过任何需要它参与的完整链路（发图片消息、读邮件附件都没测）。

所以本页**不写「实际效果」，不附任何命令返回值**。
下面「能力清单」与「注意事项」来自接口定义与技能文档，是**设计意图，不是实测结论**。

## 能力清单

> 均**未实测**。

| 能做什么 | 命令 | 风险 |
|---|---|---|
| 本地文件 → 企业微信媒体形态 | `wecom-cli media upload` | 低风险写入 |
| 企业微信媒体形态 → 本地文件 | `wecom-cli media download` | 读取 |

**两个动作都不会被别人看见。** 上传只是把文件放进企业微信的媒体暂存换一个内部标识，
**在被别的能力引用之前谁也看不到**；下载只往你自己的本地磁盘写文件。
真正让文件被别人看见的是「引用它」的那一步——发消息、发邮件、传微盘——
**确认闸门加在那里，不在这里**。

## 注意事项

**不是所有「带文件」的操作都需要经过这一步。** 这是最容易误解的地方：

| 你要做的事 | 需不需要先经过这一步 |
|---|---|
| 发图片 / 文件 / 语音 / 视频**消息** | **需要**。消息接口只认企业微信内部的媒体形态，不吃本地路径 |
| 传文件到**微盘** | **不需要**。可以直接给本地路径，上传是内部完成的 |
| 发带附件 / 内嵌图的**邮件** | **不需要**。附件可以直接给本地路径 |
| 把本地文件**导入成在线文档 / 表格** | **不需要**。同上 |
| 往智能表格 / 智能文档里传图片、附件 | **不需要**。同上 |
| **读**邮件附件、内嵌图的**内容** | **需要**。得先落到本地才能读 |
| **下载**微盘文件 | **不需要**。微盘自己就能给你本地文件 |

一句话记法：**要看内容（下行）几乎总要经过这一步；要发出去（上行）只有发消息一定要经过，
邮件和微盘都能直接吃本地路径。**

**它下载不了链接，只认内部标识。**
把邮件里的附件链接、正文里的图片链接、微盘的分享链接丢给它，一定失败——它只吃企业微信的媒体标识。

**防泄漏（DLP）加密链接下不来。** 企业微信有一类与你的身份绑定的加密资源链接，
这个能力**下载不了也解不开**。正确做法是把链接原样给你，你在企业微信客户端里点开看。
**助手不会尝试用别的手段绕过去。**

**类型要和下游对齐。** 上传时要声明这是图片、语音、视频还是普通文件；
发消息时消息类型必须跟它一致——**不能拿图片当文件发**。这一步由助手对齐，你不用管。

**它不解析内容。** OCR、看图问答、PDF/Word/Excel 正文提取、音视频转写都不在这一域范围内。
它的职责到「文件已经在本地了」为止，之后的读取由别的能力接手。

**它不负责「找」文件。** 邮件附件的标识由邮件能力产出，微盘文件的由微盘能力产出。
这一域只接收别人给的标识，**不搜索也不猜**。

**内部标识和本地路径都不会给你看。** 你问「文件在哪」时，助手会用自然语言指代
（「你刚发的那个附件」「已取到文件《周报.pdf》」），需要给你可点的东西时用可读链接。

### 三条通用边界在本域怎么体现

1. **只能改它自己建的东西**——这一域**不修改任何已有内容**，只做搬运，所以这条不直接生效。
   但它的下游会受限：上传上来的文件要发出去、要放进别人的文档里时，边界就开始生效了。
2. **能力按品类逐项开通**——它跟着调用它的那个能力所属的品类走。
   比如发图片消息需要消息品类、读邮件附件需要邮件品类。相关品类未开通时，
   助手会把官方开通指引原样转给你，然后停下，不重试。
3. **危险动作先问你**——**这一域本身不问你**，因为上传下载都不产生对外可见的后果。
   问你的是下一步：发消息、发邮件、传到共享空间。
   见 [99 风险与确认](99-风险与确认.md)。

## 相关

- [03 消息与会话](03-消息与会话.md)——**唯一一定要经过本域的上行场景**
- [08 邮件](08-邮件.md)——读附件内容时会经过本域；**发附件不需要**
- [14 微盘](14-微盘.md)——上传下载都**不需要**经过本域
- [04 群聊历史](04-群聊历史.md)——把群里的图片、文件落到本地
- [99 风险与确认](99-风险与确认.md)——确认闸门为什么加在下游而不是这里