qqbotsdk-py 0.1.0__py3-none-any.whl

qqbotsdk/__init__.py

@@ -0,0 +1,83 @@
+"""qqbotsdk：QQ 官方机器人 SDK 入口。
+
+用法：构造 `EventEmitter()` 注册 handler，交给 `main(ee)`
+启动；连接方式由 .env 的 CONNECTER 决定（websocket / webhook）。
+架构详情见 docs/ARCHITECTURE.md。
+"""
+
+import asyncio
+
+from aiohttp import ClientSession
+from dotenv import load_dotenv
+from loguru import logger
+
+from .api import BotApi
+from .config import Config
+from .connecter import Connecter as Connecter
+from .connecter import WebhookConnecter, WebsocketConnecter
+from .emitter import EventEmitter as EventEmitter
+from .protocol import BaseProtocol as BaseProtocol
+from .queue import EventQueue as EventQueue
+from .session import Session
+from .token import AccessToken
+from .webhook_protocol import WebhookProtocol
+from .ws_protocol import WebsocketProtocol
+
+load_dotenv()
+
+
+async def run_loop(emitter: EventEmitter | None = None) -> None:
+    """启动 SDK。可传入外部构造的 EventEmitter 以注册 handler；不传时自建。
+
+    全部组件在此显式装配，并按类型登记到 emitter.services 供 handler
+    参数注入；共享的 HTTP 连接池随 run_loop 结束释放。
+    """
+    if emitter is None:
+        emitter = EventEmitter()
+
+    config = Config.load()
+    http = ClientSession(timeout=config.timeout)
+    session = Session()
+    token = AccessToken(config, http)
+    api = BotApi(config, http, token)
+    emitter.services.update(
+        {
+            EventEmitter: emitter,
+            EventQueue: emitter.queue,
+            Config: config,
+            Session: session,
+            ClientSession: http,
+            AccessToken: token,
+            BotApi: api,
+        }
+    )
+
+    # 各接入方式配自己的协议处理器：协议帧由适配器就近处理，只有业务事件
+    # （op=0）入队交给 emitter 分发（见 protocol.py / connecter.py）
+    match config.connecter:
+        case "websocket":
+            protocol = WebsocketProtocol(config, session, token)
+            connecter = WebsocketConnecter(
+                config, http, token, session, emitter.queue, protocol
+            )
+        case "webhook":
+            protocol = WebhookProtocol(config)
+            connecter = WebhookConnecter(config, emitter.queue, protocol)
+        case unknown:
+            raise ValueError(f"未知的 CONNECTER: {unknown}")
+
+    logger.info(f"qqbotsdk 启动，连接方式: {config.connecter}")
+    try:
+        await asyncio.gather(emitter.dispatch(), connecter.run())
+    finally:
+        # 在飞的后台 handler 先于连接池收尾，避免用到已关闭的 ClientSession
+        await emitter.close()
+        # 全 SDK 共享一个连接池，统一在此释放
+        await http.close()
+
+
+def main(emitter: EventEmitter | None = None) -> None:
+    try:
+        asyncio.run(run_loop(emitter))
+    except KeyboardInterrupt:
+        logger.info("qqbotsdk 已退出")

qqbotsdk/api/__init__.py

@@ -0,0 +1,39 @@
+"""OpenAPI 客户端：BotApi 按域组合——v2 群/单聊、频道消息、频道管理、
+指令面板（斜线指令）与全局菜单、群管理、音频、论坛。
+
+各域模块是方法集（继承 BaseApi 共享请求内核：鉴权头注入、429 自动
+重试、401 刷新 token 重试、统一 ApiError），方法名与拆分前完全一致。
+"""
+
+from .audio import AudioApi
+from .channel import ChannelApi
+from .core import ApiError
+from .core import BaseApi as BaseApi
+from .forum import ForumApi
+from .group import GroupApi
+from .guild import GuildApi
+from .panel import PanelApi
+from .v2 import V2Api, button, keyboard
+
+
+class BotApi(V2Api, ChannelApi, GuildApi, PanelApi, GroupApi, AudioApi, ForumApi):
+    """通用 REST 封装；具体业务接口见各域方法集。
+
+    BaseApi（请求内核）经域方法集继承自然落在 MRO 末尾，
+    构造签名 (config, http, token) 由它提供。
+    """
+
+
+__all__ = [
+    "ApiError",
+    "AudioApi",
+    "BotApi",
+    "ChannelApi",
+    "ForumApi",
+    "GroupApi",
+    "GuildApi",
+    "PanelApi",
+    "V2Api",
+    "button",
+    "keyboard",
+]

qqbotsdk/api/audio.py

@@ -0,0 +1,45 @@
+"""音频方法集（仅音频类机器人）：子频道播放控制与上/下麦。
+
+需联系平台开通权限后调用；控制与上/下麦均触发 AUDIO_ACTION 事件。
+"""
+
+from typing import Any
+
+from .core import BaseApi
+
+# 播放状态（AudioControl.status）
+AUDIO_STATUS_START = 0
+AUDIO_STATUS_PAUSE = 1
+AUDIO_STATUS_RESUME = 2
+AUDIO_STATUS_STOP = 3
+
+
+class AudioApi(BaseApi):
+    """音频方法集；请求内核（鉴权/重试/错误）由 BaseApi 提供。"""
+
+    async def control_channel_audio(
+        self,
+        channel_id: str,
+        audio_url: str | None = None,
+        text: str | None = None,
+        status: int = AUDIO_STATUS_START,
+    ) -> dict:
+        """控制子频道音频播放（POST /channels/{channel_id}/audio）。
+
+        status 为 START/PAUSE/RESUME/STOP（AUDIO_STATUS_* 常量）；
+        audio_url 与状态文本 text 仅 START 时传。
+        """
+        body: dict[str, Any] = {"status": status}
+        if audio_url is not None:
+            body["audio_url"] = audio_url
+        if text is not None:
+            body["text"] = text
+        return await self.post(f"/channels/{channel_id}/audio", json=body)
+
+    async def put_channel_mic(self, channel_id: str) -> dict:
+        """机器人上麦（PUT /channels/{channel_id}/mic）。"""
+        return await self.put(f"/channels/{channel_id}/mic")
+
+    async def delete_channel_mic(self, channel_id: str) -> dict:
+        """机器人下麦（DELETE /channels/{channel_id}/mic）。"""
+        return await self.delete(f"/channels/{channel_id}/mic")

qqbotsdk/api/channel.py

@@ -0,0 +1,175 @@
+"""频道消息方法集（channel_id 接入面）：发送、撤回、表情表态、
+子频道权限与频道私信。"""
+
+from typing import Any
+
+from .core import BaseApi
+
+
+def _message_body(
+    content: str,
+    msg_id: str | None,
+    msg_seq: int,
+    image: str | None,
+    extra: dict[str, Any],
+) -> dict[str, Any]:
+    """频道系消息（频道/私信）的请求体：msg_seq 必带，其余按需。"""
+    body: dict[str, Any] = {"msg_seq": msg_seq}
+    if content:
+        body["content"] = content
+    if msg_id:
+        body["msg_id"] = msg_id
+    if image:
+        body["image"] = image
+    body.update(extra)
+    return body
+
+
+class ChannelApi(BaseApi):
+    """频道消息方法集；请求内核（鉴权/重试/错误）由 BaseApi 提供。"""
+
+    async def post_channel_message(
+        self,
+        channel_id: str,
+        content: str = "",
+        msg_id: str | None = None,
+        msg_seq: int = 1,
+        image: str | None = None,
+        **extra: Any,
+    ) -> dict:
+        """发频道消息（POST /channels/{channel_id}/messages）。
+
+        image 为图片 URL；其余字段（embed/ark/markdown 等）经 extra 透传。
+        """
+        body = _message_body(content, msg_id, msg_seq, image, extra)
+        return await self.post(f"/channels/{channel_id}/messages", json=body)
+
+    async def withdraw_channel_message(
+        self, channel_id: str, message_id: str, hide_tip: bool = False
+    ) -> dict:
+        """撤回频道消息（DELETE /channels/{channel_id}/messages/{message_id}）。
+
+        hide_tip 控制是否隐藏撤回提示小灰条（官方参数名为 hidetip）；
+        仅私域机器人可用。
+        """
+        return await self.delete(
+            f"/channels/{channel_id}/messages/{message_id}",
+            params={"hidetip": str(hide_tip).lower()},
+        )
+
+    async def put_channel_reaction(
+        self, channel_id: str, message_id: str, emoji_type: int, emoji_id: str
+    ) -> dict:
+        """对频道消息表态（PUT .../reactions/{type}/{emoji_id}）。
+
+        emoji_type=1 为系统表情，emoji_id 为系统表情序号（字符串）。
+        """
+        return await self.put(
+            f"/channels/{channel_id}/messages/{message_id}"
+            f"/reactions/{emoji_type}/{emoji_id}"
+        )
+
+    async def delete_channel_reaction(
+        self, channel_id: str, message_id: str, emoji_type: int, emoji_id: str
+    ) -> dict:
+        """删除自己对该消息的表态（DELETE .../reactions/{type}/{emoji_id}）。"""
+        return await self.delete(
+            f"/channels/{channel_id}/messages/{message_id}"
+            f"/reactions/{emoji_type}/{emoji_id}"
+        )
+
+    # ---------- 子频道权限 ----------
+
+    async def get_channel_permissions(self, channel_id: str, user_id: str) -> dict:
+        """获取子频道指定用户的权限（GET .../members/{user_id}/permissions）。
+
+        返回 permissions 字符串形式的权限位图（各权限位含义见官方文档）。
+        """
+        return await self.get(f"/channels/{channel_id}/members/{user_id}/permissions")
+
+    async def get_channel_role_permissions(self, channel_id: str, role_id: str) -> dict:
+        """获取子频道指定身份组的权限（GET .../roles/{role_id}/permissions）。"""
+        return await self.get(f"/channels/{channel_id}/roles/{role_id}/permissions")
+
+    async def update_channel_permissions(
+        self,
+        channel_id: str,
+        user_id: str,
+        *,
+        add: str | None = None,
+        remove: str | None = None,
+    ) -> dict:
+        """修改子频道指定用户的权限（PUT .../members/{user_id}/permissions）。
+
+        add/remove 为字符串形式的权限位图（要赋予/删除的权限位），
+        至少传一个；需要管理员权限。
+        """
+        body: dict[str, Any] = {}
+        if add is not None:
+            body["add"] = add
+        if remove is not None:
+            body["remove"] = remove
+        return await self.put(
+            f"/channels/{channel_id}/members/{user_id}/permissions", json=body
+        )
+
+    async def update_channel_role_permissions(
+        self,
+        channel_id: str,
+        role_id: str,
+        *,
+        add: str | None = None,
+        remove: str | None = None,
+    ) -> dict:
+        """修改子频道指定身份组的权限（PUT .../roles/{role_id}/permissions）。"""
+        body: dict[str, Any] = {}
+        if add is not None:
+            body["add"] = add
+        if remove is not None:
+            body["remove"] = remove
+        return await self.put(
+            f"/channels/{channel_id}/roles/{role_id}/permissions", json=body
+        )
+
+    # ---------- 频道私信 ----------
+
+    async def create_dms(self, recipient_id: str, source_guild_id: str) -> dict:
+        """创建私信会话（POST /users/@me/dms）。
+
+        机器人和用户存在共同频道才能创建；返回私信的 guild_id 与
+        channel_id，后续发/撤私信用它作路径参数。
+        """
+        return await self.post(
+            "/users/@me/dms",
+            json={"recipient_id": recipient_id, "source_guild_id": source_guild_id},
+        )
+
+    async def post_dms_message(
+        self,
+        guild_id: str,
+        content: str = "",
+        msg_id: str | None = None,
+        msg_seq: int = 1,
+        image: str | None = None,
+        **extra: Any,
+    ) -> dict:
+        """发私信消息（POST /dms/{guild_id}/messages）。
+
+        guild_id 为 create_dms 返回（或 DIRECT_MESSAGE_CREATE 事件携带）
+        的私信频道 id；参数与 post_channel_message 一致。私信每天可对单
+        用户发 2 条主动消息、累计 200 条，被动消息不限。
+        """
+        body = _message_body(content, msg_id, msg_seq, image, extra)
+        return await self.post(f"/dms/{guild_id}/messages", json=body)
+
+    async def withdraw_dms_message(
+        self, guild_id: str, message_id: str, hide_tip: bool = False
+    ) -> dict:
+        """撤回私信消息（DELETE /dms/{guild_id}/messages/{message_id}）。私域接口。
+
+        只能撤回机器人自己发送的私信；hide_tip 隐藏撤回提示小灰条。
+        """
+        return await self.delete(
+            f"/dms/{guild_id}/messages/{message_id}",
+            params={"hidetip": str(hide_tip).lower()},
+        )

qqbotsdk/api/core.py

@@ -0,0 +1,112 @@
+"""OpenAPI 请求内核：鉴权头注入、限流/鉴权失败重试与统一错误。
+
+失败语义（官方文档 2026-07 核对）：
+- 429 触发令牌桶限流，请求未被服务端处理，重试安全——优先按
+  Retry-After 等待（线上见过 "30,120" 这类脏值，解析容错），缺失时
+  指数退避，最多重试 `_RETRY_LIMIT` 次，等待时长封顶 `_RETRY_CAP`；
+- 401 多为 token 被服务端提前作废，强制刷新 token 后重试一次；
+- 其余 HTTP ≥400 抛 ApiError，code/message 取自响应体。
+"""
+
+import asyncio
+from typing import Any
+
+import ujson
+from aiohttp import ClientResponse, ClientSession
+from loguru import logger
+
+from ..config import Config
+from ..model import error_parts
+from ..token import AccessToken
+
+
+class ApiError(RuntimeError):
+    """OpenAPI 调用失败：HTTP 非 2xx 或业务 code 非 0。"""
+
+    def __init__(self, status: int, code: Any, message: Any) -> None:
+        self.status = status
+        self.code = code
+        self.message = message
+        super().__init__(f"API 调用失败: HTTP {status}, code={code}, message={message}")
+
+
+class BaseApi:
+    """REST 请求内核；域方法集（v2/channel/guild）继承它做薄封装。"""
+
+    # 429 重试次数上限；Retry-After 缺失时的退避基数（秒）与等待封顶
+    _RETRY_LIMIT = 3
+    _RETRY_BASE = 1.0
+    _RETRY_CAP = 30.0
+
+    def __init__(self, config: Config, http: ClientSession, token: AccessToken) -> None:
+        self._config = config
+        self._http = http
+        self._token = token
+
+    async def request(self, method: str, path: str, **kwargs) -> Any:
+        auth_retried = False
+        for attempt in range(self._RETRY_LIMIT + 1):
+            access_token = await self._token.get_access_token()
+            headers = {"Authorization": f"QQBot {access_token}"}
+            async with self._http.request(
+                method,
+                f"{self._config.base_url}{path}",
+                headers=headers,
+                **kwargs,
+            ) as resp:
+                # 个别接口 200 响应的 Content-Type 不是 JSON（body 仍是 JSON，
+                # 如回应互动返回 200 text/plain + {}），跳过标头校验
+                data = await resp.json(loads=ujson.loads, content_type=None)
+                if resp.status == 429 and attempt < self._RETRY_LIMIT:
+                    delay = self._retry_delay(resp, attempt)
+                    logger.warning(f"{method} {path} 触发频率限制，{delay:.0f}s 后重试")
+                    await asyncio.sleep(delay)
+                    continue
+                if resp.status == 401 and not auth_retried:
+                    auth_retried = True
+                    self._token.invalidate()
+                    logger.warning(f"{method} {path} 鉴权失效，刷新 token 后重试")
+                    continue
+                if resp.status >= 400:
+                    logger.warning(f"{method} {path} 失败: {data}")
+                    raise ApiError(resp.status, *error_parts(data))
+                return data
+        raise ApiError(429, None, "频率限制重试次数用尽")  # 兜底，理论不可达
+
+    def _retry_delay(self, resp: ClientResponse, attempt: int) -> float:
+        raw = resp.headers.get("Retry-After")
+        if raw:
+            try:
+                return min(float(raw.split(",")[0].strip()), self._RETRY_CAP)
+            except ValueError:
+                pass
+        return min(self._RETRY_BASE * 2**attempt, self._RETRY_CAP)
+
+    # ---------- 通用 ----------
+
+    async def me(self) -> dict:
+        """机器人自身信息（GET /users/@me）。"""
+        return await self.get("/users/@me")
+
+    async def respond_interaction(self, interaction_id: str, code: int = 0) -> dict:
+        """回应互动事件（PUT /interactions/{interaction_id}）。
+
+        按钮点击（INTERACTION_CREATE type=11）等互动收到后必须回应，
+        否则客户端一直 loading 直到超时；同一 id 只能回应一次。
+        """
+        return await self.put(f"/interactions/{interaction_id}", json={"code": code})
+
+    async def get(self, path: str, **kwargs) -> Any:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs) -> Any:
+        return await self.request("POST", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs) -> Any:
+        return await self.request("DELETE", path, **kwargs)
+
+    async def put(self, path: str, **kwargs) -> Any:
+        return await self.request("PUT", path, **kwargs)
+
+    async def patch(self, path: str, **kwargs) -> Any:
+        return await self.request("PATCH", path, **kwargs)

qqbotsdk/api/forum.py

@@ -0,0 +1,59 @@
+"""论坛方法集（私域，仅论坛子频道）：帖子列表、详情、发帖与删帖。
+
+发帖/删帖为异步任务（返回 task_id），结果经 FORUM_* 事件推送；
+content 为 FORMAT_JSON 时参照官方 RichText 结构。仅私域机器人可用。
+"""
+
+from typing import Any
+
+from .core import BaseApi
+
+# 帖子内容格式（format）
+FORUM_FORMAT_TEXT = 1
+FORUM_FORMAT_HTML = 2
+FORUM_FORMAT_MARKDOWN = 3
+FORUM_FORMAT_JSON = 4
+
+
+class ForumApi(BaseApi):
+    """论坛方法集；请求内核（鉴权/重试/错误）由 BaseApi 提供。"""
+
+    async def get_channel_threads(self, channel_id: str) -> dict:
+        """获取帖子列表（GET /channels/{channel_id}/threads）。
+
+        返回 {"threads": [...], "is_finish": ...}（1 表示已拉取完毕）；
+        threads 内 content 为 RichText 结构。
+        """
+        return await self.get(f"/channels/{channel_id}/threads")
+
+    async def get_channel_thread(self, channel_id: str, thread_id: str) -> dict:
+        """获取帖子详情（GET .../threads/{thread_id}），含首楼与回复。"""
+        return await self.get(f"/channels/{channel_id}/threads/{thread_id}")
+
+    async def put_channel_thread(
+        self,
+        channel_id: str,
+        title: str,
+        content: str,
+        format: int = FORUM_FORMAT_TEXT,
+        **extra: Any,
+    ) -> dict:
+        """发表帖子（PUT /channels/{channel_id}/threads）。
+
+        format 为 FORUM_FORMAT_* 常量；返回 {"task_id": ...}，发表结果
+        经 FORUM_THREAD_CREATE 事件推送。
+        """
+        body: dict[str, Any] = {
+            "title": title,
+            "content": content,
+            "format": format,
+        }
+        body.update(extra)
+        return await self.put(f"/channels/{channel_id}/threads", json=body)
+
+    async def delete_channel_thread(self, channel_id: str, thread_id: str) -> dict:
+        """删除帖子（DELETE .../threads/{thread_id}）。
+
+        返回 {"task_id": ...}，删除结果经 FORUM_THREAD_DELETE 事件推送。
+        """
+        return await self.delete(f"/channels/{channel_id}/threads/{thread_id}")