python-weixin-ilink

微信 iLink 协议的纯 Python 3.13+ 同步实现库。

参考并移植自Tencent/openclaw-weixin

🌟 核心特性

• 纯协议层（Zero-Invasion & Pure Protocol）：只负责 iLink 协议编解码、网络通信与加解密，不绑定任何特定 Bot/Web 框架。
• 零磁盘持久化（Zero Disk Persistence）：严禁内部读写任何文件或持久化缓存；所有 Token、Session Key、上下文完全交由调用方自管并通过参数注入。
• 同步阻塞简洁模型（Sync-Only）：清晰、直观、可靠的同步网络模型。
• 现代强类型安全：基于 Pydantic V2 与 Python 3.13+ 强类型注解，支持 strict 模式类型检查。
• 完备的全中文协议文档：详尽的技术规范、架构图与 Mermaid 协议时序图。

📚 协议技术文档 (docs/)

• README.md：协议整体架构、模块调用依赖图（Mermaid）与端到端生命周期时序图。
• auth.md：二维码获取、8 种轮询状态机、Header 算法与 Token 换取/刷新时序。
• messages.md：消息信封结构、35s 长轮询机制、单项发送约束、Markdown 过滤与 Typing 状态。
• cdn.md：AES-128-ECB PKCS#7 加解密、双 AES Key 兼容解析、分片上传与流式下载。
• errors.md：微信状态码字典、STALE_TOKEN (-14) 冷却机制与异常继承体系。

🚀 快速上手

1. 安装

pip install python-weixin-ilink

2. 快速使用示例

二维码登录换取 Token

from python_weixin_ilink import SyncClient, QrStatus

client = SyncClient()

# 1. 获取登录二维码
qr_res = client.get_qrcode()
print(f"请使用微信扫描登录: {qr_res.qrcode_img_content}")

# 2. 轮询扫码状态（完全由调用方控制）
while True:
    poll_res = client.poll_qrcode_status(qr_res.qrcode)
    if poll_res.status == QrStatus.CONFIRMED:
        print(f"登录成功！Bot ID: {poll_res.ilink_bot_id}, Token: {poll_res.bot_token}")
        break

发送与接收消息（Session 由调用方注入）

💡 关于 base_url 的默认值：

• SyncClient 与 WeixinSession 中的 base_url 均有官方默认值 https://ilinkai.weixin.qq.com，初始化时无需手动指定。
• 在扫码登录过程中，如果微信服务器触发了跨 IDC 重定向（如香港或海外集群），库内部会自动更新为正确的 base_url。

from python_weixin_ilink import SyncClient, WeixinSession, TextItem

# 调用方自管的 Session（base_url 默认为 "https://ilinkai.weixin.qq.com"，可省略）
session = WeixinSession(
    bot_token="your_bot_token",
    bot_id="your_bot_id",
)

client = SyncClient(session=session)

# 发送文本消息
resp = client.send_text(
    to_user_id="user_wx_id",
    text="你好，这是来自 python-weixin-ilink 的纯协议消息！"
)

# 长轮询拉取新消息
updates = client.get_updates(timeout_s=35)
for msg in updates.messages:
    for item in msg.item_list:
        if isinstance(item, TextItem):
            print(f"收到用户 {msg.from_user_id} 发送的消息: {item.text}")

更多示例请参阅 examples/ 目录。

🛠️ 本地开发与测试

本项目采用 uv 进行环境与依赖管理。

环境准备与依赖同步

# 克隆项目后同步开发依赖
uv sync

运行测试与质量检查

本项目包含 268+ 个单元与集成测试，覆盖率达 100%（全 Mock 离线运行）：

# 运行全量单元测试
uv run pytest -v

# 代码风格与静态类型检查
uv run ruff check
uv run mypy src tests

包含专门的无副作用断言测试 test_no_disk_side_effects.py，确保执行任何协议流程均不会产生隐蔽的磁盘读写。

📄 开源许可证

MIT License