基本概念

架构概述

PyWechat 采用 Hook + Socket 的架构：

1. 通过 DLL 注入微信客户端，Hook 关键函数
2. 微信客户端事件通过 HTTP 回调发送到 Python 服务
3. Python 通过 HTTP API 向微信客户端发送指令

┌─────────────┐     HTTP 回调      ┌──────────────┐
│  微信客户端  │  ───────────────►  │  Python 服务  │
│  (被Hook)   │  ◄───────────────  │  (PyWechat)  │
└─────────────┘     HTTP API       └──────────────┘

WeChat 类

WeChat 是框架的核心类，负责：

• 启动 Hook 服务进程
• 管理微信客户端连接
• 事件分发和处理
• 提供所有 API 方法

构造参数

wechat = WeChat(
    version="4.1.2.17",        # 微信版本号（必须）
    smart=True,                # 是否自动接管微信
    mutex=True,                # 是否互斥（关闭已有的Hook进程）
    bypass_version=False,      # 是否解除3.x低版本限制
    host="127.0.0.1",         # API服务地址
    port=19088,               # API服务端口
    server_host="127.0.0.1",  # 回调服务地址
    server_port=18999,        # 回调服务端口
    max_retry=10,             # API请求最大重试次数
    retry_interval=1,         # 重试间隔（秒）
    timeout=10                # 同步请求超时时间（秒）
)

client_id

每个被接管的微信客户端实例都有一个唯一的 client_id。所有 API 调用都需要指定 client_id 来标识操作哪个微信。

可以通过以下方式获取 client_id：

# 从事件回调中获取
@wechat.handle(events.TEXT_MESSAGE)
def on_text(bot: WeChat, event: dict):
    client_id = event["client_id"]

# 通过索引获取
client_id = wechat.get_client_id("index", 0)

# 通过 wxid 获取
client_id = wechat.get_client_id("wxid", "wxid_xxxx")

# 通过昵称获取
client_id = wechat.get_client_id("nickname", "用户名")

事件系统

PyWechat 使用装饰器模式注册事件处理函数：

@wechat.handle(events.TEXT_MESSAGE)
def on_text(bot: WeChat, event: dict):
    # bot: WeChat 实例，可调用所有 API
    # event: 事件数据字典
    pass

回调函数接收两个参数：

• bot：WeChat 实例，可以通过它调用任何 API 方法
• event：事件数据字典，包含 client_id、type、data 等字段

同步 vs 异步发送

• send()：异步发送，不等待响应
• send_sync()：同步发送，等待响应返回

大多数封装好的 API 方法（如 get_contacts、get_rooms）内部使用 send_sync，会阻塞直到收到响应或超时。

消息发送方法（如 send_text、send_image）使用 send，不阻塞等待。

bot.client

在事件回调中，bot.client 是当前触发事件的微信客户端信息字典：

{
    "id": 1,              # client_id
    "pid": 12345,         # 微信进程PID
    "wxid": "wxid_xxx",  # 微信ID
    "account": "xxx",    # 微信号
    "nickname": "昵称",   # 昵称
    "create_time": "2024-01-01 00:00:00"
}