wechatbot
English

Python SDK 基于 aiohttp + asyncio，异步优先。装饰器风格消息处理器，dataclass 类型，17 个测试。需要 Python ≥ 3.9。

安装

pip install wechatbot-sdk

快速开始

from wechatbot import WeChatBot

bot = WeChatBot()

@bot.on_message
async def handle(msg):
    await bot.send_typing(msg.user_id)
    await bot.reply(msg, f"Echo: {msg.text}")

bot.run()  # 一键登录 + 启动

配置

bot = WeChatBot(
    base_url="https://ilinkai.weixin.qq.com",
    cred_path="~/.wechatbot/credentials.json",
    on_qr_url=lambda url: print(f"扫码: {url}"),
    on_scanned=lambda: print("已扫码！"),
    on_expired=lambda: print("已过期..."),
    on_error=lambda err: print(f"错误: {err}"),
)

消息处理

@bot.on_message
async def handle(msg):
    print(f"[{msg.type}] {msg.user_id}: {msg.text}")

    for img in msg.images:
        print(f"  图片: {img.url}")
    for voice in msg.voices:
        print(f"  语音: {voice.text} ({voice.duration_ms}ms)")
    for file in msg.files:
        print(f"  文件: {file.file_name} ({file.size} 字节)")
    if msg.quoted_message:
        print(f"  引用: {msg.quoted_message.title}")

发送

await bot.reply(msg, "你好！")              # 回复（自动 context_token）
await bot.send(user_id, "主动消息")          # 发送（需先有 context）
await bot.send_typing(user_id)              # 显示输入中
await bot.stop_typing(user_id)              # 取消输入中

AES-128-ECB 加密

from wechatbot import generate_aes_key, encrypt_aes_ecb, decrypt_aes_ecb, decode_aes_key

key = generate_aes_key()
ct = encrypt_aes_ecb(b"Hello", key)
pt = decrypt_aes_ecb(ct, key)

k = decode_aes_key("ABEiM0RVZneImaq7zN3u/w==")       # base64
k = decode_aes_key("00112233445566778899aabbccddeeff") # hex

类型（dataclasses）

@dataclass
class IncomingMessage:
    user_id: str
    text: str
    type: Literal["text", "image", "voice", "file", "video"]
    timestamp: datetime
    images: list[ImageContent]
    voices: list[VoiceContent]
    files: list[FileContent]
    videos: list[VideoContent]
    quoted_message: QuotedMessage | None
    raw: dict

错误层次：WeChatBotError → ApiError、AuthError、NoContextError、MediaError

Python SDK — wechatbot-sdk