aioqzone：当 Python 异步遇上 QQ 空间，一个开源 SDK 的诞生

告别手工搬运，用代码重新定义你与 Qzone 的交互方式

前言

QQ 空间（Qzone）承载了一代人的社交记忆，但它的开放接口却长期缺乏优秀的 Python 封装。如果你做过 Qzone 相关的自动化项目，大概率经历过这样的痛苦：手动逆向 HTTP 接口、硬编码登录流程、被验证码卡住、没有类型提示靠猜字段名……

aioqzone 正是为了解决这些问题而生。它是一个基于 asyncio 的 Python SDK，封装了 Qzone 的 Web 登录与 H5 API，提供完整的类型注解、pydantic 数据校验和插件化的验证码处理机制。项目已在 GitHub 开源，采用 AGPL-3.0 协议。

核心架构：双包设计

aioqzone 由两个子包构成，职责清晰：

• qqqr：Qzone 登录引擎。支持二维码登录和密码登录，封装了腾讯复杂的登录协议，包括密码加密（TeaEncoder）、验证码处理、短信验证等完整流程。
• aioqzone：Qzone H5 API 客户端。登录后的一切操作——获取说说、发布/编辑/删除、点赞/取消赞、评论/删评论——都在这里。

这种分层设计使得你可以单独使用 qqqr 处理登录，也可以用 aioqzone 做二次开发，互不耦合。

登录：最难的坎，我们替你过了

Qzone 的登录协议是出了名的复杂。qqqr 模块将其抽象为清晰的流水线：

1. UpWebLogin.new()：发起 xlogin 请求，获取 session
2. UpWebLogin.check()：调用 check API，返回登录是否需要验证码、短信等
3. 自动验证码处理：若需验证码，自动识别滑动验证码或图片选择验证码
4. try_login() 循环：持续尝试登录，支持短信验证码输入

密码加密使用了腾讯的 TEA 算法实现，验证码环节则通过插件化的 hook 机制支持人工介入或第三方识别库（如 slide-tc）。整个流程都在 LoginBase 的 login() 方法中编排完成，下游开发者只需调用这个方法即可拿到登录态 Cookie。

Hook 机制：让扩展变得优雅

aioqzone 使用自研的 tylisten 库实现事件钩子系统，核心登录流程中暴露了多个 hook 点：

• qr_fetched：二维码生成/刷新时触发
• sms_code_input：需要短信验证时回调
• solve_slide_captcha：滑动验证码求解钩子
• solve_select_captcha：图片选择验证码求解钩子

这意味着你不必继承或重写任何类——只需要订阅对应的 hook，就能插入自己的逻辑。想接入打码平台？写个 hook 函数即可。想推送二维码到手机？同样是一个 hook 的事。

H5 API：覆盖日常操作

aioqzone 包提供了完整的 Qzone H5 接口封装：

• 获取 HTML 格式的完整说说内容
• 说说详情（富文本、图片、视频）
• 发布/修改/删除说说（图文）
• 添加/删除评论（图文）
• 点赞/取消赞

所有 API 均基于 aiohttp 异步实现，支持高并发场景。返回值通过 pydantic 模型校验，IDE 中可获得完整的类型提示和自动补全。

技术亮点

类型安全优先：全项目严格 typing，所有 API 出入参均有类型声明。配合 pydantic v2 的数据校验，从 HTTP 响应到 Python 对象的转换过程零失误。

异步原生：基于 asyncio 的事件驱动设计，单个进程中可以同时处理多个 Qzone 账号的登录和数据抓取，资源开销远低于多线程方案。

插件生态：围绕 aioqzone 已建立了多个子项目：

• aioqzone-feed：提供更高层的 feed 处理接口
• slide-tc：滑动验证码自动识别插件
• pychaosvm：腾讯 ChaosVM 的 Python 运行时环境

这些插件通过自定义 PyPI 索引发布，与主项目版本解耦。

谁在用 aioqzone？

aioqzone 最知名的下游项目是 Qzone2TG（Qzone3TG），一个将 Qzone 说说实时转发到 Telegram 的机器人。它使用 aioqzone 完成登录认证和说说抓取，在此基础上构建了完整的消息队列、内容分割、内联交互等功能。

此外，项目文档提供了丰富的示例代码，覆盖登录、API 调用、插件开发等场景，新用户可以在几分钟内跑通第一个 demo。

结语

aioqzone 不是一个"大而全"的框架，它选择了一条更务实的路：把最难的登录和最常用的 API 封装好，然后通过 hook 和插件让开发者自由扩展。无论你是想备份自己的 Qzone 数据、做社交数据分析，还是构建自动化工具，aioqzone 都提供了一个坚实且愉悦的开发起点。

---

GitHub: github.com/aioqzone/aioqzone

文档: aioqzone.github.io/aioqzone

讨论群: t.me/aioqzone_chatroom