84 lines
4.5 KiB
Markdown
84 lines
4.5 KiB
Markdown
# 封装接口清单（WechatHookClient）
|
||
|
||
本文档整理当前项目内已封装的对外接口，插件开发请优先使用 `WechatHookClient`，避免直接调用 HTTP API。
|
||
|
||
说明：
|
||
- 插件回调里通常会拿到 `bot` 参数，它就是 `WechatHookClient` 实例。
|
||
- 统一发送：`send_message` / `send_media`。
|
||
- 统一下载：`download_wechat_media`（带锁与缓存，TTL=60分钟）。
|
||
- 群成员信息建议优先使用 `utils.member_info_service`（MemberSync 数据库）。
|
||
|
||
## 基础信息
|
||
|
||
- `bot.wxid` 获取当前登录 wxid
|
||
- `bot.nickname` 获取当前登录昵称
|
||
- `await bot.update_profile(wxid, nickname)` 手动更新缓存信息
|
||
|
||
## 初始化与登录
|
||
|
||
- `await bot.wechat_init()` 初始化好友/群列表缓存
|
||
- `await bot.get_login_info()` 获取当前登录信息（并更新 `bot.wxid`/`bot.nickname`）
|
||
|
||
## 消息发送
|
||
|
||
- `await bot.send_message(to_wxid, msg_type, content)` 统一发送入口（text/image/video/file/xml）
|
||
- `await bot.send_text(to_wxid, content)` 发送文本
|
||
- `await bot.send_image(to_wxid, image_path)` 发送图片
|
||
- `await bot.send_video(to_wxid, video_path)` 发送视频
|
||
- `await bot.send_file(to_wxid, file_path)` 发送文件
|
||
- `await bot.send_media(to_wxid, file_path, media_type="")` 统一媒体发送（支持按扩展名自动判断）
|
||
- `await bot.send_at_message(chatroom_id, content, at_list)` 群聊 @ 消息
|
||
- `await bot.send_xml(to_wxid, xml)` 发送 XML 消息
|
||
- `await bot.send_card(to_wxid, card_wxid, card_nickname="")` 发送名片
|
||
- `await bot.send_link(to_wxid, title, desc, url, thumb_url="")` 发送链接
|
||
- `await bot.send_link_card(to_wxid, title, desc, url, image_url="")` 发送链接卡片
|
||
- `await bot.revoke_message(msg_id)` 撤回消息
|
||
|
||
## 群聊管理
|
||
|
||
- `await bot.get_chatroom_list(force_refresh=False)` 获取群聊列表（好友列表 + 本地数据库兜底）
|
||
- `await bot.get_chatroom_members(chatroom_id)` 获取群成员列表（优先全量名单，不足时数据库兜底）
|
||
- 返回字段：`wxid` / `nickname` / `display_name` / `avatar`
|
||
- `await bot.get_chatroom_info(chatroom_id)` 获取群信息
|
||
- `await bot.create_chatroom(member_list)` 创建群聊
|
||
- `await bot.invite_to_chatroom(chatroom_id, wxid_list)` 邀请进群
|
||
- `await bot.remove_chatroom_member(chatroom_id, wxid_list)` 踢出群成员
|
||
- `await bot.quit_chatroom(chatroom_id)` 退出群聊
|
||
- `await bot.set_chatroom_announcement(chatroom_id, announcement)` 修改群公告
|
||
- `await bot.set_chatroom_name(chatroom_id, name)` 修改群名称（新协议可能不可用）
|
||
- `await bot.set_my_chatroom_nickname(chatroom_id, nickname)` 修改我的群昵称（新协议可能不可用）
|
||
|
||
## 群成员信息
|
||
|
||
- `await bot.get_group_member_contact(room_id, member_wxid)` 获取群成员详细信息（含头像）
|
||
- `await bot.get_user_info_in_chatroom(chatroom_id, user_wxid, max_retries=1)` 从缓存/群成员列表获取信息
|
||
- `bot.update_chatroom_members_cache(chatroom_id, members)` 更新群成员缓存
|
||
- `bot.get_cached_member_info(chatroom_id, user_wxid)` 从缓存获取群成员信息
|
||
|
||
## 好友管理
|
||
|
||
- `await bot.get_friend_list()` 获取好友列表（失败会自动触发初始化/全量更新）
|
||
- `await bot.get_friend_info(wxid)` 获取好友资料（网络）
|
||
- `await bot.add_friend(wxid, verify_msg="", scene=3)` 添加好友
|
||
- `await bot.accept_friend(v3, v4, scene)` 同意好友请求
|
||
- `await bot.delete_friend(wxid)` 删除好友
|
||
- `await bot.set_friend_remark(wxid, remark)` 修改好友备注
|
||
|
||
## 微信消息媒体下载（图片/视频）
|
||
|
||
- `await bot.download_wechat_media(media_type, save_path, message=None, msg_id=None, total_len=0, to_user="", from_user="", file_id="", aes_key="", prefer_original=True, timeout=60.0)`
|
||
- 统一入口：带缓存与锁，避免重复下载
|
||
|
||
- `await bot.download_image(message, save_path)` 从消息 XML 下载图片
|
||
- `await bot.download_image_by_id(msg_id, total_len, save_path, to_user="", from_user="")` 引用消息图片下载
|
||
- `await bot.download_image_by_cdn(file_id, aes_key, save_path, prefer_original=True, timeout=60.0)` CDN 参数下载图片
|
||
- `await bot.download_video(message, save_path)` 从消息 XML 下载视频
|
||
- `await bot.download_video_by_id(msg_id, total_len, save_path)` 引用消息视频下载
|
||
|
||
## 兼容/保留接口（新协议一般不需要）
|
||
|
||
- `await bot.cdn_init()` CDN 初始化（新协议无需）
|
||
- `await bot.cdn_download(...)` CDN 下载（新协议不推荐）
|
||
- `await bot.cdn_upload(...)` CDN 上传（新协议不推荐）
|
||
- `await bot.send_cdn_image(to_wxid, file_path)` 发送图片（兼容接口）
|