tuitui-bot

推推机器人异步 Python SDK，移植自 npm 包 @qihoo/tuitui-bot-sdk。支持 Python 3.10 及以上版本。

安装

pip install tuitui-bot

发送消息

import asyncio

from tuitui_bot import TuituiBotClient


async def main() -> None:
    client = TuituiBotClient("your-app-id", "your-app-secret")
    await client.im.send_text(
        to=client.to.account("user-account"),
        text="**你好**，这是一条 `Markdown` 消息。",
    )


asyncio.run(main())

TuituiBotClient 构造时不连接网络，默认 HTTP 会话由 SDK 在每次请求后自动关闭， 不需要 async with 或手动关闭客户端。

client.to 提供 account()、uid()、group()、accounts() 和 uids() 五种结构化目标。 IM 位于 client.im，频道和帖子能力位于 client.teams。

事件订阅

构造客户端或发送消息不会建立 WebSocket。只有调用 client.event.subscribe() 才会订阅事件：

import asyncio

from tuitui_bot import TuituiBotClient, TuituiSubscribeOptions


async def main() -> None:
    client = TuituiBotClient("...", "...")

    async def on_event(raw: dict[str, object]) -> None:
        print(raw)

    subscription = client.event.subscribe(
        TuituiSubscribeOptions(on_event=on_event),
    )
    try:
        await asyncio.Event().wait()
    finally:
        await subscription.unsubscribe()


asyncio.run(main())

SDK 自动处理鉴权、ACK、保活过滤、去重、心跳超时和断线重连。原始事件字段会被保留；需要正文或 媒体时，显式使用 client.event.render_message_body(data) 和 client.event.get_message_media(data)。

API 概览

• client.im：文本、图文混排、页面、链接、文件、交互卡片、编辑、表情和历史记录。
• client.teams：帖子、回复、编辑、文件、表情、频道、标签、公告、成员和帖子链。
• client.file：底层文件上传。
• client.file_space：文件空间节点、目录和文件。
• client.property：机器人信息、名称、头像、Webhook、交互地址和快捷指令。
• client.event：事件订阅、正文渲染和媒体提取。
• client.request()：调用尚未封装的 Bot API。

文本消息和帖子支持 Markdown；图文混排中的文字是纯文本。上传支持 bytes、Path、本地路径、二进制 文件对象、data URL 和 HTTP/HTTPS URL，最大 100MB。远程 URL 下载可通过 TuituiClientOptions(fetch_with_ssrf=...) 注入 SSRF 防护实现。