wecomcli-media

name	wecomcli-media
version	1.0.0
description	企业微信媒体文件上传/下载技能。承接基于 media_id 下载媒体文件到本地，以及上传本地文件获取 media_id 两类操作。当其他技能（微盘、邮件等）返回了 media_id 需要落地为本地文件，或已有本地文件需要转换为 media_id 供其他技能使用时，必须先读取本技能获取完整指引，不得凭记忆处理。本技能不解析/识别文件内容，仅负责文件本身的搬运。

wecom-cli 是插件提供的 tool，不是终端命令：所有操作都通过调用该 tool 完成，参数应使用 args 传入，禁止通过 exec / shell / 终端等命令行方式使用。

⚠️ 前置条件：首次调用 wecom-cli 前，必须按 wecomcli-preflight 技能执行前置条件检查，确保工具已加入白名单。

企业微信媒体文件

资源型 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 下载媒体文件到本地，返回本地文件路径。

调用方式

使用 wecom-cli 工具按照下面格式调用

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。

调用方式

使用 wecom-cli 工具按照下面格式调用

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

参数缺失 / 意图不明确时，用自然语言追问让用户明确，不要瞎猜。