feat:初版

2025-12-03 15:48:44 +08:00
commit b4df26f61d
199 changed files with 23434 additions and 0 deletions
--- a/docs/API文档.md
+++ b/docs/API文档.md
@@ -0,0 +1,694 @@
+# WechatHookBot API 文档
+
+## WechatHookClient API 参考
+
+基于个微大客户版 Hook API 封装的 Python 客户端。
+
+## 消息发送
+
+### send_text - 发送文本消息
+
+```python
+await client.send_text(to_wxid: str, content: str) -> bool
+```
+
+**参数：**
+- `to_wxid`: 接收者 wxid（个人或群聊）
+- `content`: 文本内容
+
+**返回：** 是否发送成功
+
+**示例：**
+```python
+await client.send_text("wxid_xxx", "你好，世界")
+await client.send_text("123@chatroom", "群聊消息")
+```
+
+---
+
+### send_image - 发送图片
+
+```python
+await client.send_image(to_wxid: str, image_path: str) -> bool
+```
+
+**参数：**
+- `to_wxid`: 接收者 wxid
+- `image_path`: 图片文件路径
+
+**支持格式：** jpg, png, gif
+
+**示例：**
+```python
+await client.send_image("wxid_xxx", "D:/images/photo.jpg")
+```
+
+---
+
+### send_file - 发送文件
+
+```python
+await client.send_file(to_wxid: str, file_path: str) -> bool
+```
+
+**参数：**
+- `to_wxid`: 接收者 wxid
+- `file_path`: 文件路径
+
+**示例：**
+```python
+await client.send_file("wxid_xxx", "D:/documents/report.pdf")
+```
+
+---
+
+### send_video - 发送视频
+
+```python
+await client.send_video(to_wxid: str, video_path: str) -> bool
+```
+
+**参数：**
+- `to_wxid`: 接收者 wxid
+- `video_path`: 视频文件路径
+
+**示例：**
+```python
+await client.send_video("wxid_xxx", "D:/videos/demo.mp4")
+```
+
+---
+
+### send_card - 发送名片
+
+```python
+await client.send_card(to_wxid: str, card_wxid: str, card_nickname: str) -> bool
+```
+
+**参数：**
+- `to_wxid`: 接收者 wxid
+- `card_wxid`: 名片的 wxid
+- `card_nickname`: 名片昵称
+
+**示例：**
+```python
+await client.send_card("wxid_xxx", "wxid_yyy", "张三")
+```
+
+---
+
+### send_location - 发送位置
+
+```python
+await client.send_location(
+    to_wxid: str,
+    latitude: float,
+    longitude: float,
+    title: str,
+    address: str
+) -> bool
+```
+
+**参数：**
+- `to_wxid`: 接收者 wxid
+- `latitude`: 纬度
+- `longitude`: 经度
+- `title`: 位置标题
+- `address`: 详细地址
+
+**示例：**
+```python
+await client.send_location(
+    "wxid_xxx",
+    39.9042,
+    116.4074,
+    "天安门",
+    "北京市东城区"
+)
+```
+
+---
+
+### send_link - 发送链接
+
+```python
+await client.send_link(
+    to_wxid: str,
+    title: str,
+    desc: str,
+    url: str,
+    thumb_url: str = ""
+) -> bool
+```
+
+**参数：**
+- `to_wxid`: 接收者 wxid
+- `title`: 链接标题
+- `desc`: 链接描述
+- `url`: 链接地址
+- `thumb_url`: 缩略图 URL（可选）
+
+**示例：**
+```python
+await client.send_link(
+    "wxid_xxx",
+    "新闻标题",
+    "新闻摘要",
+    "https://example.com/news",
+    "https://example.com/thumb.jpg"
+)
+```
+
+---
+
+### send_miniapp - 发送小程序
+
+```python
+await client.send_miniapp(
+    to_wxid: str,
+    appid: str,
+    title: str,
+    page_path: str,
+    thumb_url: str = ""
+) -> bool
+```
+
+**参数：**
+- `to_wxid`: 接收者 wxid
+- `appid`: 小程序 appid
+- `title`: 小程序标题
+- `page_path`: 小程序页面路径
+- `thumb_url`: 缩略图 URL（可选）
+
+**示例：**
+```python
+await client.send_miniapp(
+    "wxid_xxx",
+    "wx1234567890",
+    "小程序标题",
+    "pages/index/index"
+)
+```
+
+---
+
+### send_at_message - 发送群聊@消息
+
+```python
+await client.send_at_message(
+    chatroom_id: str,
+    content: str,
+    at_list: list[str]
+) -> bool
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+- `content`: 消息内容
+- `at_list`: 要@的 wxid 列表
+
+**示例：**
+```python
+# @指定用户
+await client.send_at_message(
+    "123@chatroom",
+    "大家好",
+    ["wxid_aaa", "wxid_bbb"]
+)
+
+# @所有人
+await client.send_at_message(
+    "123@chatroom",
+    "重要通知",
+    ["notify@all"]
+)
+```
+
+---
+
+### revoke_message - 撤回消息
+
+```python
+await client.revoke_message(msg_id: str) -> bool
+```
+
+**参数：**
+- `msg_id`: 消息 ID
+
+**示例：**
+```python
+await client.revoke_message("1234567890")
+```
+
+---
+
+## 好友管理
+
+### get_friend_list - 获取好友列表
+
+```python
+await client.get_friend_list() -> list[dict]
+```
+
+**返回：** 好友列表
+
+**示例：**
+```python
+friends = await client.get_friend_list()
+for friend in friends:
+    print(friend["wxid"], friend["nickname"])
+```
+
+---
+
+### get_friend_info - 获取好友信息
+
+```python
+await client.get_friend_info(wxid: str) -> dict
+```
+
+**参数：**
+- `wxid`: 好友 wxid
+
+**返回：** 好友详细信息
+
+**示例：**
+```python
+info = await client.get_friend_info("wxid_xxx")
+print(info["nickname"], info["remark"])
+```
+
+---
+
+### search_user - 搜索用户
+
+```python
+await client.search_user(keyword: str) -> dict
+```
+
+**参数：**
+- `keyword`: 搜索关键词（wxid、手机号、微信号）
+
+**返回：** 用户信息
+
+**示例：**
+```python
+result = await client.search_user("wxid_xxx")
+if result:
+    print(result["nickname"])
+```
+
+---
+
+### add_friend - 添加好友
+
+```python
+await client.add_friend(
+    wxid: str,
+    verify_msg: str = "",
+    scene: int = 3
+) -> bool
+```
+
+**参数：**
+- `wxid`: 要添加的 wxid
+- `verify_msg`: 验证消息
+- `scene`: 添加场景（3=搜索，15=名片）
+
+**示例：**
+```python
+await client.add_friend("wxid_xxx", "你好，我是...")
+```
+
+---
+
+### accept_friend - 同意好友请求
+
+```python
+await client.accept_friend(v3: str, v4: str, scene: int) -> bool
+```
+
+**参数：**
+- `v3`: 好友请求的 v3 参数
+- `v4`: 好友请求的 v4 参数
+- `scene`: 场景值
+
+**示例：**
+```python
+# 从好友请求消息中获取参数
+await client.accept_friend(v3, v4, scene)
+```
+
+---
+
+### delete_friend - 删除好友
+
+```python
+await client.delete_friend(wxid: str) -> bool
+```
+
+**参数：**
+- `wxid`: 要删除的好友 wxid
+
+**示例：**
+```python
+await client.delete_friend("wxid_xxx")
+```
+
+---
+
+### set_friend_remark - 修改好友备注
+
+```python
+await client.set_friend_remark(wxid: str, remark: str) -> bool
+```
+
+**参数：**
+- `wxid`: 好友 wxid
+- `remark`: 新备注
+
+**示例：**
+```python
+await client.set_friend_remark("wxid_xxx", "张三")
+```
+
+---
+
+### check_friend_status - 检测好友状态
+
+```python
+await client.check_friend_status(wxid: str) -> dict
+```
+
+**参数：**
+- `wxid`: 好友 wxid
+
+**返回：** 好友状态信息
+
+**示例：**
+```python
+status = await client.check_friend_status("wxid_xxx")
+print(status["is_friend"])  # 是否是好友
+```
+
+---
+
+## 群聊管理
+
+### get_chatroom_list - 获取群聊列表
+
+```python
+await client.get_chatroom_list() -> list[dict]
+```
+
+**返回：** 群聊列表
+
+**示例：**
+```python
+chatrooms = await client.get_chatroom_list()
+for room in chatrooms:
+    print(room["chatroom_id"], room["name"])
+```
+
+---
+
+### get_chatroom_members - 获取群成员
+
+```python
+await client.get_chatroom_members(chatroom_id: str) -> list[dict]
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+
+**返回：** 群成员列表
+
+**示例：**
+```python
+members = await client.get_chatroom_members("123@chatroom")
+for member in members:
+    print(member["wxid"], member["nickname"])
+```
+
+---
+
+### get_chatroom_info - 获取群信息
+
+```python
+await client.get_chatroom_info(chatroom_id: str) -> dict
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+
+**返回：** 群聊详细信息
+
+**示例：**
+```python
+info = await client.get_chatroom_info("123@chatroom")
+print(info["name"], info["member_count"])
+```
+
+---
+
+### create_chatroom - 创建群聊
+
+```python
+await client.create_chatroom(member_list: list[str]) -> str
+```
+
+**参数：**
+- `member_list`: 成员 wxid 列表（至少2人）
+
+**返回：** 新群聊的 chatroom_id
+
+**示例：**
+```python
+chatroom_id = await client.create_chatroom(["wxid_aaa", "wxid_bbb"])
+```
+
+---
+
+### invite_to_chatroom - 邀请进群
+
+```python
+await client.invite_to_chatroom(
+    chatroom_id: str,
+    wxid_list: list[str]
+) -> bool
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+- `wxid_list`: 要邀请的 wxid 列表
+
+**示例：**
+```python
+await client.invite_to_chatroom("123@chatroom", ["wxid_xxx", "wxid_yyy"])
+```
+
+---
+
+### remove_chatroom_member - 踢出群成员
+
+```python
+await client.remove_chatroom_member(
+    chatroom_id: str,
+    wxid_list: list[str]
+) -> bool
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+- `wxid_list`: 要踢出的 wxid 列表
+
+**示例：**
+```python
+await client.remove_chatroom_member("123@chatroom", ["wxid_xxx"])
+```
+
+---
+
+### quit_chatroom - 退出群聊
+
+```python
+await client.quit_chatroom(chatroom_id: str) -> bool
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+
+**示例：**
+```python
+await client.quit_chatroom("123@chatroom")
+```
+
+---
+
+### set_chatroom_name - 修改群名称
+
+```python
+await client.set_chatroom_name(chatroom_id: str, name: str) -> bool
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+- `name`: 新群名称
+
+**示例：**
+```python
+await client.set_chatroom_name("123@chatroom", "新群名")
+```
+
+---
+
+### set_chatroom_announcement - 修改群公告
+
+```python
+await client.set_chatroom_announcement(
+    chatroom_id: str,
+    announcement: str
+) -> bool
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+- `announcement`: 群公告内容
+
+**示例：**
+```python
+await client.set_chatroom_announcement("123@chatroom", "群公告内容")
+```
+
+---
+
+### set_my_chatroom_nickname - 修改我的群昵称
+
+```python
+await client.set_my_chatroom_nickname(
+    chatroom_id: str,
+    nickname: str
+) -> bool
+```
+
+**参数：**
+- `chatroom_id`: 群聊 ID
+- `nickname`: 新昵称
+
+**示例：**
+```python
+await client.set_my_chatroom_nickname("123@chatroom", "我的群昵称")
+```
+
+---
+
+## 登录信息
+
+### get_login_info - 获取当前登录信息
+
+```python
+await client.get_login_info() -> dict
+```
+
+**返回：** 登录账号信息
+
+**示例：**
+```python
+info = await client.get_login_info()
+print(info["wxid"], info["nickname"])
+```
+
+---
+
+## CDN 功能
+
+### cdn_upload - CDN 上传
+
+```python
+await client.cdn_upload(file_path: str) -> dict
+```
+
+**参数：**
+- `file_path`: 文件路径
+
+**返回：** CDN 信息（包含 aes_key, file_id 等）
+
+**示例：**
+```python
+cdn_info = await client.cdn_upload("D:/files/image.jpg")
+```
+
+---
+
+### cdn_download - CDN 下载
+
+```python
+await client.cdn_download(
+    aes_key: str,
+    file_id: str,
+    save_path: str
+) -> bool
+```
+
+**参数：**
+- `aes_key`: AES 密钥
+- `file_id`: 文件 ID
+- `save_path`: 保存路径
+
+**示例：**
+```python
+await client.cdn_download(aes_key, file_id, "D:/downloads/file.jpg")
+```
+
+---
+
+## 企业微信
+
+### get_work_chatroom_list - 获取企业群列表
+
+```python
+await client.get_work_chatroom_list() -> list[dict]
+```
+
+---
+
+### get_work_friend_list - 获取企业好友列表
+
+```python
+await client.get_work_friend_list() -> list[dict]
+```
+
+---
+
+### get_work_chatroom_members - 获取企业群成员
+
+```python
+await client.get_work_chatroom_members(chatroom_id: str) -> list[dict]
+```
+
+---
+
+## 错误处理
+
+所有 API 调用失败时会抛出异常或返回 False/None，建议使用 try-except 处理：
+
+```python
+try:
+    result = await client.send_text("wxid_xxx", "消息")
+    if result:
+        logger.info("发送成功")
+    else:
+        logger.error("发送失败")
+except Exception as e:
+    logger.error(f"发送异常: {e}")
+```
+
+---
+
+## 注意事项
+
+1. 所有 API 都是异步函数，必须使用 `await` 调用
+2. wxid 格式：个人为 `wxid_xxx`，群聊为 `xxx@chatroom`
+3. 文件路径建议使用绝对路径
+4. 部分 API 需要特定权限（如群主才能踢人）
+5. API 调用频率不宜过高，避免风控