跳转到主要内容

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_idaes_keyfile_md5 等参数后再发送。

触发方式

当用户说出以下内容时,Agent 应触发此 SKILL:

  • "给张三发消息 hello"
  • "发送图片给李四"
  • "撤回消息"
  • "在群里@张三"
  • "拍一拍张三"
  • "给王五发文件"
  • "发送位置给赵六"
  • "回复张三的消息"
  • "标记已读"

SKILL 包

SKILL 名称说明
juhecli-wx-msg个微消息管理 - 发送文本/图片/视频/文件/表情/名片/位置/链接/小程序/视频号,撤回/引用/标记已读/语音转文字

命令详细说明与 Agent 交互示例

wx msg send_text — 发送文本消息

发送纯文本消息给指定联系人或群组。Agent 需先通过 db contact search 查询接收人 username。

参数类型说明来源
to_usernamestring接收人 username[需查询]
contentstring消息内容[用户提供]
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_usernamestring群 ID[需查询]
contentstring消息内容(含 @文本)[用户提供]
at_listarray被@人的 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_usernamestring接收人[需查询]
file_idstringCDN 文件 ID[需上传获取]
aes_keystring加密密钥[需上传获取]
file_sizeint文件大小[需上传获取]
前置步骤:需先调用 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_usernamestring接收人[需查询]
file_id / aes_key / file_sizestring/intCDN 上传参数[需上传获取]
video_durationint视频时长(秒)[用户提供]
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_usernamestring接收人[需查询]
file_id / aes_key / file_sizestring/intCDN 上传参数[需上传获取]
file_namestring文件名[用户提供]
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_usernamestring接收人[需查询]
urlstring表情图片 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_usernamestring接收人[需查询]
latitudefloat纬度[用户提供]
longitudefloat经度[用户提供]
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_usernamestring接收人[需查询]
usernamestring被分享人[需查询]
nicknamestring被分享人昵称可从查询结果获取
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_usernamestring接收人[需查询]
contentstring回复内容[用户提供]
refer_msgobject被引用的原始消息[来自消息记录]
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_usernamestring消息接收人[需查询]
msg_idstring消息 ID[来自发送返回值]
撤回消息有 2 分钟时间限制,超时后将无法撤回。
text
用户:撤回刚才发的消息
Agent:好的,正在撤回。
→ 使用上次发送返回的 msg_id
→ 调用 wx msg revoke {"to_username":"wxid_xxx","msg_id":"..."}
Agent:消息已撤回。

wx msg send_pat — 拍一拍

在群聊中"拍一拍"某个成员。仅在群聊场景中使用。

参数类型说明来源
to_usernamestring群 ID[需查询]
patted_usernamestring被拍的人[需查询]
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_usernamestring会话 username[需查询]
text
用户:标记张三的会话为已读
Agent:好的,正在标记。
→ 调用 db contact search {"keyword":"张三"} → 获取 wxid_zhangsan
→ 调用 wx msg set_read {"to_username":"wxid_zhangsan"}
Agent:已标记张三的会话为已读。

wx msg send_mini_app — 发送小程序

发送小程序消息卡片给指定联系人。

参数类型说明来源
to_usernamestring接收人[需查询]
app_idstring小程序 AppID[用户提供]
page_pathstring小程序页面路径[用户提供]
titlestring卡片标题[用户提供]
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_usernamestring接收人[需查询]
finder_usernamestring视频号 username[用户提供]
feed_idstring视频 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:视频号视频已分享给张三。

语音转文字(三步流程)

将语音消息转为文字,需要依次调用三个命令完成:

  1. wx msg new_trans_voice — 发起语音转写
  2. wx msg check_voice_trans — 检查转写状态(轮询直到完成)
  3. 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 返回

典型工作流

  1. 发文本:db contact search 获取 to_username → wx msg send_text
  2. 发图片:db contact searchwx cloud upload 上传 → wx msg send_image
  3. 发文件:db contact searchwx cloud upload_filewx msg send_file
  4. 撤回消息:发送消息后保存 msg_id → wx msg revoke(2 分钟内)
  5. 回复消息:db msg list 获取原始消息 → wx msg send_refer
  6. 语音转文字:new_trans_voicecheck_voice_transupload_voice_transget_voice_trans

错误处理

  • to_username 不存在:Agent 应提示发送失败并建议检查联系人
  • file_id 无效:Agent 应检查 wx cloud upload 上传是否成功后重试
  • 撤回超时:超过 2 分钟无法撤回,Agent 应提示用户
  • 群@缺少 at_list:at_list 不能为空数组,Agent 需确保至少包含一个 username