WeChatHookBot/docs/封装接口清单.md

封装接口清单（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) 发送图片（兼容接口）