微信机器人 SDK (Weixin Bot SDK)

一个功能完整、易于集成的微信机器人软件开发工具包，提供消息收发、二维码登录、输入状态等核心功能。

功能特性

• 用户登录认证模块 - 支持扫码登录，自动获取和管理Token
• 二维码生成与显示 - 获取登录二维码，支持终端显示
• 消息发送模块 - 支持文本、图片、语音、文件等多种消息类型
• 消息接收处理 - 长轮询获取消息，支持消息处理器链
• 输入状态发送 - 发送"正在输入"状态，提升交互体验
• 完整的错误处理 - 细粒度的异常类型，便于错误处理
• 详细日志记录 - 可配置的日志级别，便于调试

快速开始

安装

# 基础安装
pip install weixin-bot-sdk

# 带二维码显示功能
pip install weixin-bot-sdk[qrcode]

# 开发模式安装
pip install weixin-bot-sdk[dev]

本地安装

git clone https://github.com/yourusername/weixin-bot-sdk.git
cd weixin-bot-sdk
pip install -e .

1. 登录获取Token

from weixin_bot_sdk.auth import AuthManager

# 创建认证管理器
auth = AuthManager()

# 执行登录流程
result = auth.login(
    timeout=300,
    on_status_change=lambda msg: print(f"状态: {msg}"),
    auto_display_qr=True
)

if result.success:
    print(f"登录成功！Token: {result.bot_token}")
    # 保存Token
    auth.save_token(result, "weixin_token.txt")

2. 创建机器人

from weixin_bot_sdk import WeixinClient, WeixinConfig
from weixin_bot_sdk.models import Message

# 加载配置
config = WeixinConfig.from_token_file("weixin_token.txt")

# 创建客户端
client = WeixinClient(config)

# 定义消息处理器
def handle_message(message: Message):
    text = message.get_text()
    from_user = message.from_user_id
    context = message.context_token

    if text.lower() == "hello":
        # 发送输入状态
        client.send_typing(from_user, True)

        # 发送回复
        client.send_text_message(
            from_user,
            "你好！我是微信机器人 🤖",
            context
        )

        # 停止输入状态
        client.send_typing(from_user, False)

# 注册处理器
client.on_message(handle_message)

# 开始接收消息
client.start_polling()

API 文档

WeixinClient - 核心客户端

初始化

from weixin_bot_sdk import WeixinClient, WeixinConfig

# 方式1: 从配置文件
config = WeixinConfig.from_token_file("weixin_token.txt")
client = WeixinClient(config)

# 方式2: 手动配置
config = WeixinConfig(
    token="your_token",
    base_url="https://ilinkai.weixin.qq.com"
)
client = WeixinClient(config)

# 方式3: 从环境变量
# 设置 WEIXIN_TOKEN, WEIXIN_BOT_ID 环境变量
client = WeixinClient()  # 自动加载

消息发送

# 发送文本消息
result = client.send_text_message(
    to_user="user_id",
    text="Hello World",
    context_token="optional_context_token"
)
print(result.success)  # True/False

# 发送图片消息
result = client.send_image_message(
    to_user="user_id",
    image_url="http://example.com/image.jpg",
    context_token="context_token"
)

# 发送语音消息
result = client.send_voice_message(
    to_user="user_id",
    voice_url="http://example.com/voice.mp3",
    duration=5,  # 秒
    context_token="context_token"
)

# 发送文件消息
result = client.send_file_message(
    to_user="user_id",
    file_url="http://example.com/file.pdf",
    file_name="document.pdf",
    file_size=1024,
    context_token="context_token"
)

输入状态

# 发送输入状态
client.send_typing("user_id", True)   # 开始输入
client.send_typing("user_id", False)  # 停止输入

# 便捷方法
client.start_typing("user_id")
client.stop_typing("user_id")

消息接收

# 注册消息处理器
client.on_message(lambda msg: print(f"收到: {msg.get_text()}"))

# 注册多个处理器
client.on_message(handler1)
client.on_message(handler2)

# 注册错误处理器
client.on_error(lambda e: print(f"错误: {e}"))

轮询模式

# 阻塞模式（推荐用于简单脚本）
try:
    client.start_polling(poll_interval=0.1)
except KeyboardInterrupt:
    client.stop_polling()

# 异步模式（推荐用于复杂应用）
client.start_polling_async(
    poll_interval=0.1,
    on_start=lambda: print("轮询已启动")
)

# 做其他事情...
time.sleep(60)

# 停止轮询
client.stop_polling()

AuthManager - 认证管理

from weixin_bot_sdk.auth import AuthManager, QRCodeStatus

auth = AuthManager()

# 获取二维码
qr = auth.fetch_qrcode()
print(qr.qrcode_url)  # 扫码链接

# 在终端显示二维码
auth.display_qrcode_terminal(qr.qrcode_url)

# 检查状态
status = auth.check_qrcode_status(qr.qrcode)
if status.status == QRCodeStatus.CONFIRMED:
    print(f"Token: {status.bot_token}")

# 完整登录流程
result = auth.login(
    timeout=300,
    on_status_change=lambda msg: print(msg),
    auto_display_qr=True
)

# 保存Token
auth.save_token(result, "weixin_token.txt")

数据模型

from weixin_bot_sdk.models import Message, MessageType

# 消息类型判断
message: Message = ...

if message.is_text():
    print(f"文本: {message.get_text()}")

if message.is_image():
    print("包含图片")

if message.is_voice():
    print("包含语音")

# 访问原始数据
raw = message.raw_data

异常处理

from weixin_bot_sdk import (
    WeixinClient, WeixinConfig,
    AuthenticationError, NetworkError, APIError,
    MessageSendError, LoginError, QRCodeExpiredError
)

try:
    client = WeixinClient(config)
    client.send_text_message("user", "Hello")
except AuthenticationError as e:
    print(f"认证失败: {e}")
except NetworkError as e:
    print(f"网络错误: {e}")
except APIError as e:
    print(f"API错误 {e.code}: {e}")
except QRCodeExpiredError:
    print("二维码已过期，请重新登录")

日志配置

from weixin_bot_sdk import Logger, LogLevel

# 设置日志级别
logger = Logger.get_logger("weixin_bot_sdk", LogLevel.DEBUG)
logger.set_level(LogLevel.INFO)

# 或使用便捷函数
from weixin_bot_sdk.logger import get_logger
logger = get_logger("my_bot", "DEBUG")

配置选项

配置项	类型	默认值	说明
token	str	""	Bot认证Token
base_url	str	"https://ilinkai.weixin.qq.com"	API基础URL
bot_id	str	""	Bot ID
timeout_ms	int	15000	请求超时（毫秒）
long_poll_timeout_ms	int	35000	长轮询超时（毫秒）
log_level	str	"INFO"	日志级别
auto_reconnect	bool	True	自动重连
max_retry	int	3	最大重试次数
retry_delay	float	1.0	重试延迟（秒）

示例

基础机器人

# examples/basic_bot.py
# 简单的自动回复机器人

高级机器人

# examples/advanced_bot.py
# 带命令处理、统计、异步轮询

登录示例

# examples/login_example.py
# 展示登录流程的各种方式

运行测试

# 安装测试依赖
pip install -e ".[dev]"

# 运行所有测试
pytest tests/

# 带覆盖率报告
pytest --cov=weixin_bot_sdk tests/

# 运行特定测试
pytest tests/test_client.py

项目结构

weixin_bot_sdk/
├── __init__.py          # 包入口，导出主要类
├── auth.py              # 认证模块（二维码登录）
├── client.py            # 核心客户端
├── config.py            # 配置管理
├── exceptions.py        # 异常定义
├── logger.py            # 日志工具
└── models.py            # 数据模型

tests/                   # 单元测试
examples/                # 使用示例
setup.py                 # 安装配置
README.md               # 本文档

环境要求

• Python 3.7+
• 可选依赖: qrcode[pil] 用于终端显示二维码

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎提交Issue和Pull Request！

更新日志

v1.0.0

• 初始版本发布
• 支持文本发送
• 支持消息接收和处理器链
• 支持输入状态发送
• 支持扫码登录
• 完整的单元测试覆盖
• 一个web例子