juhecli-wx-cloud 个微云存储

使用案例

概述

个微云存储 SKILL 由 juhecli-wx-cloud 提供，支持微信 CDN 云存储的完整功能。 包括图片、视频、文件、表情、朋友圈媒体等多种类型的上传和下载操作。上传操作是发送媒体消息的前置步骤，上传返回的参数将直接用于后续发送命令。

SKILL 包

触发方式

当用户提出以下意图时，Agent 应激活此 SKILL：

• "上传图片" / "上传文件到 CDN" / "发送图片前上传"
• "下载文件" / "下载语音" / "下载图片"
• "发图片给张三"（隐含上传步骤）
• "上传朋友圈图片" / "上传朋友圈视频"
• "下载这条语音消息" / "下载消息中的文件"

详细说明 — 上传

上传到 CDN (upload)

上传文件到微信 CDN，返回值是发送媒体消息的关键参数。

wx cloud upload '{"file_type": 2, "url": "https://example.com/image.jpg"}'

参数：

• file_type (int, 必填) — 文件类型（2=图片等） [用户提供]
• url (string, 必填) — 文件 URL 地址 [用户提供]

返回值（关键 — 直接用于发送命令）：

• file_id — 文件唯一标识，用于 wx msg send_image / send_video / send_file
• aes_key — 加密密钥，用于对应发送命令
• file_size — 文件大小，用于对应发送命令
• file_md5 — 文件 MD5 校验值，用于对应发送命令

上传朋友圈图片 (upload_sns_image)

wx cloud upload_sns_image '{"url": "https://example.com/img.jpg"}'

参数：

• url (string, 必填) — 图片 URL [用户提供]

上传朋友圈视频 (upload_sns_video)

wx cloud upload_sns_video '{"url": "https://example.com/video.mp4"}'

参数：

• url (string, 必填) — 视频 URL [用户提供]

上传文件 (upload_file)

wx cloud upload_file '{"file_type": 2, "url": "https://example.com/doc.pdf"}'

参数：

• file_type (int, 必填) — 文件类型 [用户提供]
• url (string, 必填) — 文件 URL [用户提供]

上传大文件 (upload_big)

用于上传大尺寸文件，支持分片上传。

wx cloud upload_big '{}'

更新 DNS (update_dns)

wx cloud update_dns '{}'

详细说明 — 下载

通用下载 (download)

从 CDN 下载文件，需要提供消息记录中的加密参数。

wx cloud download '{"file_type": 2, "file_id": "xxx", "aes_key": "xxx", "file_size": 12345, "file_name": "image.jpg"}'

参数：

• file_type (int, 必填) — 文件类型
• file_id (string, 必填) — 文件 ID [来自消息记录]
• aes_key (string, 必填) — 加密密钥 [来自消息记录]
• file_size (int, 必填) — 文件大小 [来自消息记录]
• file_name (string, 必填) — 保存文件名 [用户提供]

下载语音 (download_voice)

wx cloud download_voice '{"msg_id": "xxx", "length": 0, "room_username": "", "file_name": "voice.amr", "to_mp3": false}'

参数：

• msg_id (string, 必填) — 语音消息 ID [来自消息记录]
• length (int, 可选) — 语音长度
• room_username (string, 可选) — 群聊中的发言者 username
• file_name (string, 必填) — 保存文件名 [用户提供]
• to_mp3 (bool, 可选) — 是否转为 MP3，默认 false

下载微信表情 (download_wxemotion)

wx cloud download_wxemotion '{"url": "", "token": "", "enc_idx": "", "key": "", "file_name": "emoji.gif"}'

参数：

• url (string, 必填) — 表情 URL [来自消息记录]
• token (string, 必填) — 认证令牌 [来自消息记录]
• enc_idx (string, 必填) — 加密索引 [来自消息记录]
• key (string, 必填) — 加密密钥 [来自消息记录]
• file_name (string, 必填) — 保存文件名 [用户提供]

其他下载命令

• download_image — 下载图片，参数同 download
• download_video — 下载视频，参数同 download
• download_file — 下载文件，参数同 download
• download_fav — 下载收藏内容
• download_fav_file — 下载收藏文件
• download_wwfile — 下载企业文件
• download_wx_emotion — 下载微信表情（别名）

上传返回 → 发送命令映射

upload → send_image / send_video / send_file

upload_sns_image → sns post

参数来源说明

典型工作流

发送图片消息

1. wx cloud upload — 上传图片，获取 file_id / aes_key / file_size / file_md5
2. wx msg send_image — 使用上传返回的参数发送图片

发送文件消息

1. wx cloud upload_file — 上传文件，获取参数
2. wx msg send_file — 使用上传返回的参数发送文件

发布带图朋友圈

1. wx cloud upload_sns_image — 上传朋友圈图片，获取 content_url
2. wx sns post — 传入 title 和 content_url 发布朋友圈

下载消息中的媒体

1. 从消息记录获取 file_id / aes_key / file_size 等参数
2. wx cloud download — 传入参数下载媒体文件

下载语音消息

1. 从消息记录获取 msg_id
2. wx cloud download_voice — 下载语音，可转 MP3

AI Agent 调用示例

wx cloud upload

// 用户：把这张图片发给张三 https://example.com/photo.jpg
AI: 好的，我先上传图片到 CDN。

[步骤 1: 上传图片]
[调用 wx cloud upload {"file_type":2,"url":"https://example.com/photo.jpg"}]
→ file_id: "cdn_abc123", aes_key: "key_xyz", file_size: 102400, file_md5: "md5_hash"

[步骤 2: 查询张三并发送]
[调用 db contact search {"keyword":"张三"}] → username="wxid_zhangsan"
[调用 wx msg send_image {"username":"wxid_zhangsan","file_id":"cdn_abc123","aes_key":"key_xyz","file_size":102400,"file_md5":"md5_hash"}]

AI: 图片已成功发送给张三！

wx cloud upload_sns_image

// 用户：发一条带图片的朋友圈，内容"今天天气真好"
AI: 好的，我先上传朋友圈图片。

[步骤 1: 上传朋友圈图片]
[调用 wx cloud upload_sns_image {"url":"https://example.com/sunset.jpg"}]
→ content_url: "sns_url_xxx"

[步骤 2: 发布朋友圈]
[调用 wx sns post {"title":"今天天气真好","content_url":"sns_url_xxx"}]

AI: 朋友圈发布成功！

wx cloud download_voice

// 用户：帮我下载这条语音消息
AI: 好的，我从消息记录获取参数并下载。

[从消息记录获取 msg_id]
[调用 wx cloud download_voice {"msg_id":"msg_12345","length":0,"room_username":"","file_name":"voice.mp3","to_mp3":true}]

AI: 语音下载成功！已保存为 voice.mp3。

完整工作流：发送文件到群

// 用户：把这个 PDF 文件发给技术部群
AI: 好的，我来处理。

[步骤 1: 上传文件]
[调用 wx cloud upload_file {"file_type":2,"url":"https://example.com/report.pdf"}]
→ file_id: "f_001", aes_key: "ak_001", file_size: 2048000, file_md5: "md5_001"

[步骤 2: 查询群信息]
[调用 db contact search {"keyword":"技术部"}] → room_username="12345@chatroom"

[步骤 3: 发送文件]
[调用 wx msg send_file {"username":"12345@chatroom","file_id":"f_001","aes_key":"ak_001","file_size":2048000,"file_md5":"md5_001","file_name":"report.pdf"}]

AI: 文件已成功发送到技术部群！

错误处理

• URL 无效或无法访问：返回下载失败，请检查 URL 是否可公开访问
• 文件过大：使用 upload_big 命令替代 upload
• file_id / aes_key 不匹配：返回解密失败，检查参数是否来自同一次上传
• 上传超时：文件较大时可能需要更长时间，请耐心等待
• 下载失败：确认消息记录中的加密参数完整且正确