juhecli-wx-msg 个微消息
SKILL: juhecli-wx-msg — 微信个微消息收发和操作管理,支持 21+ 个命令,覆盖文本、图片、视频、文件、表情、名片、位置、链接、小程序、视频号等多种消息类型
使用案例
给微信好友张三发你好发送朋友圈截图给李四撤回刚才发的消息
发送文本消息
>给张三发消息hello
// Agent 先通过 db contact search 查找张三
$juhe-cli db contact search --keyword 张三
{
"username": "wxid_zhangsan",
"nickname": "张三"
}
// Agent 调用 wx msg send_text 发送消息
$juhe-cli wx msg send_text --to_username wxid_zhangsan --content hello
{
"msg_id": "1234567890",
"create_time": 1710000000,
"to_username": "wxid_zhangsan"
}
发送图片消息
>发送图片给李四
// Agent 先查找李四并上传图片
$juhe-cli db contact search --keyword 李四
{
"username": "wxid_lisi",
"nickname": "李四"
}
$juhe-cli wx cloud upload --file_path /tmp/photo.jpg
{
"file_id": "cdn_file_abc123",
"aes_key": "a1b2c3d4e5",
"file_size": 25600,
"file_md5": "d41d8cd98f00b204e9800998ecf8427e"
}
// Agent 调用 wx msg send_image 发送图片
$juhe-cli wx msg send_image --to_username wxid_lisi --file_id cdn_file_abc123 --aes_key a1b2c3d4e5 --file_size 25600
{
"msg_id": "9876543210",
"create_time": 1710000001
}
概述
个微消息 SKILL 由 juhecli-wx-msg 提供,是最核心的消息 SKILL 之一,包含 21+ 个命令。 支持发送文本、图片、视频、文件、表情、名片、位置、链接卡片、小程序、视频号等消息类型, 以及消息撤回、引用回复、标记已读、拍一拍、语音转文字等操作。
发送图片、视频、文件等媒体消息前,必须先调用
wx cloud upload 上传文件, 获取 file_id、aes_key、file_md5 等参数后再发送。触发方式
当用户说出以下内容时,Agent 应触发此 SKILL:
- "给张三发消息 hello"
- "发送图片给李四"
- "撤回消息"
- "在群里@张三"
- "拍一拍张三"
- "给王五发文件"
- "发送位置给赵六"
- "回复张三的消息"
- "标记已读"
SKILL 包
| SKILL 名称 | 说明 |
|---|---|
juhecli-wx-msg | 个微消息管理 - 发送文本/图片/视频/文件/表情/名片/位置/链接/小程序/视频号,撤回/引用/标记已读/语音转文字 |
命令详细说明与 Agent 交互示例
wx msg send_text — 发送文本消息
发送纯文本消息给指定联系人或群组。Agent 需先通过 db contact search 查询接收人 username。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 username | [需查询] |
content | string | 消息内容 | [用户提供] |
text
用户:给张三发消息"你好"
Agent:好的,我先查找张三。
→ 调用 db contact search {"keyword":"张三"}
→ 获取 username="wxid_zhangsan"
→ 调用 wx msg send_text {"to_username":"wxid_zhangsan","content":"你好"}
Agent:消息已发送给张三。wx msg send_room_at — 发送群@消息
在群聊中发送@某人的消息。Agent 需同时查询群 ID 和被@人的 username。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 群 ID | [需查询] |
content | string | 消息内容(含 @文本) | [用户提供] |
at_list | array | 被@人的 username 列表 | [需查询] |
text
用户:在项目群里@李四说"开会了"
Agent:好的,我来查群和李四的信息。
→ 调用 db contact search {"keyword":"项目群"} → 获取群 ID
→ 调用 db contact search {"keyword":"李四"} → 获取 wxid_lisi
→ 调用 wx msg send_room_at {"to_username":"xxx@chatroom","content":"@李四 开会了","at_list":["wxid_lisi"]}
Agent:已在项目群@李四发送"开会了"。wx msg send_image — 发送图片
发送图片给指定联系人。必须先通过 wx cloud upload 上传图片获取 CDN 参数。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
file_id | string | CDN 文件 ID | [需上传获取] |
aes_key | string | 加密密钥 | [需上传获取] |
file_size | int | 文件大小 | [需上传获取] |
前置步骤:需先调用
wx cloud upload 上传图片,获取 file_id/aes_key/file_md5 等参数后才能发送。text
用户:发送图片 /tmp/photo.jpg 给李四
Agent:好的,我先查找李四并上传图片。
→ 调用 db contact search {"keyword":"李四"} → 获取 wxid_lisi
→ 调用 wx cloud upload 上传图片 → 获取 file_id, aes_key, file_size
→ 调用 wx msg send_image {"to_username":"wxid_lisi","file_id":"xxx","aes_key":"xxx","file_size":12345}
Agent:图片已发送给李四。wx msg send_video — 发送视频
发送视频文件给指定联系人。同样需要先上传获取 CDN 参数。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
file_id / aes_key / file_size | string/int | CDN 上传参数 | [需上传获取] |
video_duration | int | 视频时长(秒) | [用户提供] |
text
用户:把视频 /tmp/demo.mp4 发给张三
Agent:好的,我先查找张三并上传视频。
→ 调用 db contact search {"keyword":"张三"} → 获取 wxid_zhangsan
→ 调用 wx cloud upload 上传视频 → 获取 CDN 参数
→ 调用 wx msg send_video {"to_username":"wxid_zhangsan","file_id":"xxx","aes_key":"xxx","file_size":99999,"video_duration":30}
Agent:视频已发送给张三。wx msg send_file — 发送文件
发送任意文件给指定联系人。需先上传并指定文件名。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
file_id / aes_key / file_size | string/int | CDN 上传参数 | [需上传获取] |
file_name | string | 文件名 | [用户提供] |
text
用户:把 doc.pdf 发给李四
Agent:好的,我先查找李四并上传文件。
→ 调用 db contact search {"keyword":"李四"} → 获取 wxid_lisi
→ 调用 wx cloud upload_file 上传文件 → 获取 CDN 参数
→ 调用 wx msg send_file {"to_username":"wxid_lisi","file_id":"xxx","aes_key":"xxx","file_size":5000,"file_name":"doc.pdf"}
Agent:文件 doc.pdf 已发送给李四。wx msg send_emoji_url — 发送表情
通过 URL 发送表情图片。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
url | string | 表情图片 URL | [用户提供] |
text
用户:给张三发表情 https://example.com/emoji.gif
Agent:好的,我来发送。
→ 调用 db contact search {"keyword":"张三"} → 获取 wxid_zhangsan
→ 调用 wx msg send_emoji_url {"to_username":"wxid_zhangsan","url":"https://example.com/emoji.gif"}
Agent:表情已发送给张三。wx msg send_location — 发送位置
发送地理位置信息给指定联系人。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
latitude | float | 纬度 | [用户提供] |
longitude | float | 经度 | [用户提供] |
text
用户:发位置给赵六,纬度39.9,经度116.4
Agent:好的,我来发送。
→ 调用 db contact search {"keyword":"赵六"} → 获取 wxid_zhaoliu
→ 调用 wx msg send_location {"to_username":"wxid_zhaoliu","latitude":39.9,"longitude":116.4}
Agent:位置已发送给赵六。wx msg send_share_card — 发送名片分享
将某个联系人的名片分享给另一个人。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
username | string | 被分享人 | [需查询] |
nickname | string | 被分享人昵称 | 可从查询结果获取 |
text
用户:把张三的名片分享给李四
Agent:好的,我来查找两人信息。
→ 调用 db contact search {"keyword":"李四"} → 获取接收人 wxid_lisi
→ 调用 db contact search {"keyword":"张三"} → 获取被分享人 wxid_zhangsan 和昵称
→ 调用 wx msg send_share_card {"to_username":"wxid_lisi","username":"wxid_zhangsan","nickname":"张三"}
Agent:已将张三的名片分享给李四。wx msg send_refer — 发送引用回复
引用某条消息进行回复。Agent 需从消息记录中获取原始消息信息。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
content | string | 回复内容 | [用户提供] |
refer_msg | object | 被引用的原始消息 | [来自消息记录] |
text
用户:回复张三刚才说的"明天开会"说"收到"
Agent:好的,我先获取张三的消息记录。
→ 调用 db contact search {"keyword":"张三"} → 获取 wxid_zhangsan
→ 调用 db msg list 获取原始消息
→ 调用 wx msg send_refer {"to_username":"wxid_zhangsan","content":"收到","refer_msg":{"msg_type":1,"msg_id":"xxx","from_username":"wxid_zhangsan","content":"明天开会"}}
Agent:已回复张三"收到"。wx msg revoke — 撤回消息
撤回已发送的消息。有 2 分钟时间限制,Agent 应在发送消息后保存 msg_id 以备撤回。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 消息接收人 | [需查询] |
msg_id | string | 消息 ID | [来自发送返回值] |
撤回消息有 2 分钟时间限制,超时后将无法撤回。
text
用户:撤回刚才发的消息
Agent:好的,正在撤回。
→ 使用上次发送返回的 msg_id
→ 调用 wx msg revoke {"to_username":"wxid_xxx","msg_id":"..."}
Agent:消息已撤回。wx msg send_pat — 拍一拍
在群聊中"拍一拍"某个成员。仅在群聊场景中使用。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 群 ID | [需查询] |
patted_username | string | 被拍的人 | [需查询] |
text
用户:拍一拍张三
Agent:好的,我来查找群和张三。
→ 调用 db contact search {"keyword":"张三"} → 获取 wxid_zhangsan
→ 调用 db room list → 获取所在群 ID
→ 调用 wx msg send_pat {"to_username":"xxx@chatroom","patted_username":"wxid_zhangsan"}
Agent:已拍一拍张三。wx msg set_read — 标记会话已读
将某个会话标记为已读状态。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 会话 username | [需查询] |
text
用户:标记张三的会话为已读
Agent:好的,正在标记。
→ 调用 db contact search {"keyword":"张三"} → 获取 wxid_zhangsan
→ 调用 wx msg set_read {"to_username":"wxid_zhangsan"}
Agent:已标记张三的会话为已读。wx msg send_mini_app — 发送小程序
发送小程序消息卡片给指定联系人。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
app_id | string | 小程序 AppID | [用户提供] |
page_path | string | 小程序页面路径 | [用户提供] |
title | string | 卡片标题 | [用户提供] |
text
用户:给张三发小程序卡片
Agent:好的,请提供小程序的 AppID、页面路径和标题。
用户:AppID 是 wx123,路径是 pages/index,标题是"首页"
Agent:正在发送。
→ 调用 db contact search {"keyword":"张三"} → 获取 wxid_zhangsan
→ 调用 wx msg send_mini_app {"to_username":"wxid_zhangsan","app_id":"wx123","page_path":"pages/index","title":"首页"}
Agent:小程序卡片已发送给张三。wx msg send_finder_video — 发送视频号视频
分享视频号视频给指定联系人。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
to_username | string | 接收人 | [需查询] |
finder_username | string | 视频号 username | [用户提供] |
feed_id | string | 视频 feed ID | [用户提供] |
text
用户:给张三分享视频号视频
Agent:好的,请提供视频号的 username 和 feed ID。
用户:finder_username 是 finder_xxx,feed_id 是 feed_123
Agent:正在分享。
→ 调用 db contact search {"keyword":"张三"} → 获取 wxid_zhangsan
→ 调用 wx msg send_finder_video {"to_username":"wxid_zhangsan","finder_username":"finder_xxx","feed_id":"feed_123"}
Agent:视频号视频已分享给张三。语音转文字(三步流程)
将语音消息转为文字,需要依次调用三个命令完成:
wx msg new_trans_voice— 发起语音转写wx msg check_voice_trans— 检查转写状态(轮询直到完成)wx msg upload_voice_trans+wx msg get_voice_trans— 上传并获取转写结果
text
用户:把张三发的语音转成文字
Agent:好的,我来发起语音转写。
→ 调用 wx msg new_trans_voice 发起转写
→ 轮询 wx msg check_voice_trans 直到转写完成
→ 调用 wx msg upload_voice_trans + wx msg get_voice_trans 获取结果
Agent:张三的语音内容是:"明天下午三点开会"。参数来源说明
| 参数 | 来源标记 | 获取方式 |
|---|---|---|
to_username | [需查询] | db contact search 按姓名查询 |
content / file_name | [用户提供] | 用户直接提供 |
file_id / aes_key / file_md5 | [需上传获取] | 先通过 wx cloud upload 获取 |
msg_id | [来自发送返回值] | 发送消息后 API 返回 |
典型工作流
- 发文本:
db contact search获取 to_username →wx msg send_text - 发图片:
db contact search→wx cloud upload上传 →wx msg send_image - 发文件:
db contact search→wx cloud upload_file→wx msg send_file - 撤回消息:发送消息后保存 msg_id →
wx msg revoke(2 分钟内) - 回复消息:
db msg list获取原始消息 →wx msg send_refer - 语音转文字:
new_trans_voice→check_voice_trans→upload_voice_trans→get_voice_trans
错误处理
- to_username 不存在:Agent 应提示发送失败并建议检查联系人
- file_id 无效:Agent 应检查
wx cloud upload上传是否成功后重试 - 撤回超时:超过 2 分钟无法撤回,Agent 应提示用户
- 群@缺少 at_list:at_list 不能为空数组,Agent 需确保至少包含一个 username