qqbotsdk-base-py 2.1.0__tar.gz → 2.2.0__tar.gz

{qqbotsdk_base_py-2.1.0 → qqbotsdk_base_py-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: qqbotsdk-base-py
-Version: 2.1.0
+Version: 2.2.0
 Summary: QQ 官方机器人 SDK 基座包：模型基类、共享消息模型与 HTTP 会话
 Author: snowy-yang
 Author-email: snowy-yang <102860110+snowy-yang@users.noreply.github.com>

{qqbotsdk_base_py-2.1.0 → qqbotsdk_base_py-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qqbotsdk-base-py"
-version = "2.1.0"
+version = "2.2.0"
 description = "QQ 官方机器人 SDK 基座包：模型基类、共享消息模型与 HTTP 会话"
 readme = "README.md"
 requires-python = ">=3.12"

{qqbotsdk_base_py-2.1.0 → qqbotsdk_base_py-2.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "qqbotsdk-base-py"
-version = "2.1.0"
+version = "2.2.0"
 description = "QQ 官方机器人 SDK 基座包：模型基类、共享消息模型与 HTTP 会话"
 readme = "README.md"
 authors = [

{qqbotsdk_base_py-2.1.0 → qqbotsdk_base_py-2.2.0}/src/qqbotsdk/api/core.py

@@ -415,8 +415,24 @@ class QQBotSession:
         return self._ensure()
 
     async def request(self, method: str, url: str, **kwargs: Any) -> ClientResponse:
-        """返回已读取完成的响应, 便于需要自行处理状态码的场景."""
-        return await self._ensure().request(method, url, **kwargs)
+        """通用 verb 请求: 与 ``get`` / ``post`` 等完全同构, 同样走 429 重试.
+
+        ``method`` 可以是任意 HTTP verb, 便于按配置分发。行为与
+        ``get`` / ``post`` / ``put`` / ``patch`` / ``delete`` 一致:
+
+        - 命中 HTTP 429 时按 ``Retry-After`` / 指数退避自动重试, 最多
+          ``MAX_RETRIES`` 次;
+        - 非 2xx 抛 :class:`qqbotsdk.errors.QQBotAPIError`(OpenAPI 域名下);
+        - 返回的响应**未**读取 body, 调用方自己 ``await resp.json()`` 或
+          ``await resp.read()``, 用完由本方法的上下文管理器释放连接::
+
+            async with session.request("GET", "/users/@me") as resp:
+                data = await resp.json()
+
+        注意: 直接 ``await session.request(...)`` 拿到的响应不会自动释放,
+        与 aiohttp 原生语义一致, 建议一律用 ``async with``.
+        """
+        return await self._request_context(method, url, **kwargs)
 
     @property
     def closed(self) -> bool:

qqbotsdk_base_py-2.1.0/src/qqbotsdk/errors.py → qqbotsdk_base_py-2.2.0/src/qqbotsdk/errors/__init__.py

@@ -8,13 +8,23 @@
     +-- QQBotGatewayError       WebSocket 网关层错误
 
 调用方 ``except QQBotError`` 可以兜住全部错误, 也可以按层分别处理.
+
+业务错误码常量见子模块 :mod:`qqbotsdk.errors.codes`::
+
+    from qqbotsdk.errors import QQBotAPIError, codes
+
+    if exc.err_code == codes.MSG_DEDUPLICATED:
+        ...
 """
 
+from qqbotsdk.errors import codes
+
 __all__ = [
     "QQBotAPIError",
     "QQBotAuthError",
     "QQBotError",
     "QQBotGatewayError",
+    "codes",
 ]
 
 

qqbotsdk_base_py-2.2.0/src/qqbotsdk/errors/codes.py

@@ -0,0 +1,129 @@
+"""OpenAPI 业务错误码常量.
+
+``QQBotAPIError.err_code`` 是**业务错误码**, 与 HTTP 状态码分开: HTTP 200 时
+也可能带非零 ``err_code``. 用这里的常量替代魔法数字::
+
+    from qqbotsdk.errors import QQBotAPIError, codes
+
+    try:
+        await ctx.reply("...")
+    except QQBotAPIError as exc:
+        if exc.err_code == codes.MSG_MSG_ID_EXPIRED:
+            ...
+
+命名规范: 前缀是错误码所属的域(``MSG_`` 消息、``APP_`` 应用权限、
+``FILE_`` 文件), 名字取官方错误表里英文标识的大写形式; 官方只给了中文描述的,
+按描述意译.
+
+来源: 官方 [API 调用指南 · 公共错误码] 与各接口页的「错误码」表. 标注为
+「实践观察」的几条未收录在官方公共错误表中, 来自真实 bot 的调用日志, 平台可能
+调整, 不要把它们当成稳定契约.
+"""
+
+from typing import Final
+
+# ---------------------------------------------------------------- 消息收发
+
+MSG_DEDUPLICATED: Final = 40054005
+"""相同 msg_id + msg_seq 重复发送被去重. 递增 msg_seq 即可."""
+
+MSG_ID_EXPIRED: Final = 40034005
+"""回复消息的 msg_id 已过期, 请在收到消息后尽快回复."""
+
+EVENT_ID_INVALID: Final = 40034025
+"""请求参数 event_id 无效或越权."""
+
+EVENT_ID_EXPIRED: Final = 40034026
+"""请求参数 event_id 已过期, 请在收到事件后尽快回复."""
+
+EVENT_NOT_REPLYABLE: Final = 40034027
+"""该事件不支持回复消息. 例如 GROUP_MEMBER_ADD 只能发主动消息."""
+
+MSG_TYPE_MISMATCH: Final = 22006
+"""消息类型与内容不匹配(例如 msg_type=2 却只传了 content)."""
+
+MSG_TYPE_INVALID: Final = 340069
+"""消息类型无效, 检查 msg_type 取值."""
+
+MSG_CONTENT_INVALID: Final = 304061
+"""消息内容无效, 检查消息格式."""
+
+MSG_LENGTH_EXCEEDED: Final = 40054007
+"""消息长度超限."""
+
+MSG_URL_NOT_ALLOWED: Final = 40054010
+"""不允许发送 URL."""
+
+MSG_PASSIVE_LIMIT: Final = 40034128
+"""被动回复时间或次数超限(群聊 5 次 / 单聊 4 次)."""
+
+MSG_ACTIVE_RATE_LIMITED: Final = 40034100
+"""主动消息发送超过频控限制."""
+
+BOT_NOT_IN_GROUP: Final = 40054003
+"""机器人不是群成员."""
+
+BOT_MUTED: Final = 40054002
+"""机器人被禁言, 等解禁后再发送."""
+
+BOT_OFFLINE: Final = 40054016
+"""机器人已下线, 检查网关连接状态."""
+
+MEDIA_TRANSFER_FAILED: Final = 40034004
+"""富媒体信息转存失败, 可重试."""
+
+FILE_INFO_INVALID: Final = 304080
+"""文件信息无效, 检查 file_info 格式."""
+
+MSG_ID_EXPIRED_ALT: Final = 304103
+"""消息 ID 已过期, 不能回复."""
+
+# ---------------------------------------------------------------- 应用与权限
+
+APP_PRIVILEGE_NOT_PASS: Final = 11253
+"""应用权限不通过: 该机器人未获得调用该接口的权限, 需要向平台申请."""
+
+APP_PRIVILEGE_CHECK_FAILED: Final = 11252
+"""检查应用权限失败(系统错误), 通常重试一次即可."""
+
+APP_INTERFACE_FORBIDDEN: Final = 11254
+"""应用接口被封禁: 有该接口权限但被封禁."""
+
+BOT_BANNED: Final = 11265
+"""机器人已经被封禁."""
+
+# ---------------------------------------------------------------- 实践观察
+# 以下未收录在官方公共错误码表中, 来自真实 bot 的调用日志, 平台可能调整.
+
+GROUP_FILE_NO_PERMISSION: Final = 40093005
+"""群文件无权限(实践观察). 常见于机器人缺少群文件读写权限时."""
+
+QQ_STREAM_FETCH_FAILED: Final = 40093007
+"""QQ 抓流失败(实践观察). 常见于语音 / 视频链接平台侧拉取失败."""
+
+__all__ = [
+    "APP_INTERFACE_FORBIDDEN",
+    "APP_PRIVILEGE_CHECK_FAILED",
+    "APP_PRIVILEGE_NOT_PASS",
+    "BOT_BANNED",
+    "BOT_MUTED",
+    "BOT_NOT_IN_GROUP",
+    "BOT_OFFLINE",
+    "EVENT_ID_EXPIRED",
+    "EVENT_ID_INVALID",
+    "EVENT_NOT_REPLYABLE",
+    "FILE_INFO_INVALID",
+    "GROUP_FILE_NO_PERMISSION",
+    "MEDIA_TRANSFER_FAILED",
+    "MSG_ACTIVE_RATE_LIMITED",
+    "MSG_CONTENT_INVALID",
+    "MSG_DEDUPLICATED",
+    "MSG_ID_EXPIRED",
+    "MSG_ID_EXPIRED_ALT",
+    "MSG_LENGTH_EXCEEDED",
+    "MSG_PASSIVE_LIMIT",
+    "MSG_TYPE_INVALID",
+    "MSG_TYPE_MISMATCH",
+    "MSG_URL_NOT_ALLOWED",
+    "QQ_STREAM_FETCH_FAILED",
+]

{qqbotsdk_base_py-2.1.0 → qqbotsdk_base_py-2.2.0}/src/qqbotsdk/model/sub/messages.py

@@ -1,8 +1,8 @@
-from typing import Literal
+from typing import Any, ClassVar, Literal, cast
 
-from pydantic import Field
+from pydantic import Field, model_validator
 
-from qqbotsdk.model.core import QQBotBaseModel
+from qqbotsdk.model.core import QQBotBaseModel, QQBotRequestModel
 
 
 class Permission(QQBotBaseModel):
@@ -76,8 +76,10 @@ class Action(QQBotBaseModel):
 class RenderData(QQBotBaseModel):
     label: str | None = Field(
         default=None,
-        max_length=10,
-        description="按钮文字，最多 10 字符",
+        description=(
+            "按钮文字。平台限制为最多 10 字符，超出部分由平台自行裁剪；"
+            "SDK 不在此处校验长度，避免用热词/标题等业务数据时被 ValidationError 卡住"
+        ),
     )
     visited_label: str | None = Field(
         default=None,
@@ -207,3 +209,65 @@ class MessageCard(QQBotBaseModel):
         default=None,
         description="卡片元素；type=tuwen 时必须包含 title/description/url/pic_url",
     )
+
+
+class MessageSendRequestBase(QQBotRequestModel):
+    """发送消息请求的公共校验: 按内容字段推导 ``msg_type``, 并校验内容互斥.
+
+    平台的 ``msg_type`` 与内容字段是一一对应的(``content``→0、``markdown``→2、
+    ``input_notify``→6、``media``→7、``card``→8), 但两个字段都是可选的: 只填
+    ``markdown`` 而不填 ``msg_type`` 时, 请求体会缺 ``msg_type`` 而只剩内容字段,
+    语义全靠平台默认推断. 这里在**校验前**按填入的字段补齐 ``msg_type``, 让
+    ``SendXxxMessagesRequest(markdown=...)`` 直接就是一个合法的请求.
+
+    同时把原来只写在 docstring 里的互斥关系变成真校验:
+
+    - ``markdown`` / ``media`` / ``card`` / ``input_notify`` 四者至多填一个;
+    - ``content`` 与 ``markdown`` 互斥(官方: 传了 markdown 后 content 必须为空);
+    - ``content`` 可以与 ``media`` 共存, 作为富媒体的附带文本.
+
+    显式传了 ``msg_type`` 但与内容字段对不上时直接报错, 而不是把矛盾发给服务端.
+    """
+
+    # 内容字段 -> 该字段对应的 msg_type
+    _MSG_TYPE_BY_FIELD: ClassVar[dict[str, int]] = {
+        "markdown": 2,
+        "media": 7,
+        "card": 8,
+        "input_notify": 6,
+    }
+
+    @model_validator(mode="before")
+    @classmethod
+    def _infer_msg_type(cls, data: Any) -> Any:
+        """补齐 ``msg_type`` 并校验内容字段互斥."""
+        if not isinstance(data, dict):
+            return data
+        raw = cast("dict[str, Any]", data)
+        filled = [name for name in cls._MSG_TYPE_BY_FIELD if raw.get(name) is not None]
+        if len(filled) > 1:
+            raise ValueError(f"消息内容字段互斥，不能同时传 {filled}")
+        has_content = raw.get("content") is not None
+        if has_content and "markdown" in filled:
+            raise ValueError(
+                "content 与 markdown 互斥：传了 markdown 时 content 必须为空"
+            )
+
+        if filled:
+            inferred = cls._MSG_TYPE_BY_FIELD[filled[0]]
+        elif has_content:
+            inferred = 0
+        else:
+            # 没有任何内容字段(例如只带键盘), 保持原样交给平台判断
+            return raw
+
+        declared = raw.get("msg_type")
+        if declared is None:
+            return {**raw, "msg_type": inferred}
+        if declared != inferred:
+            source = filled[0] if filled else "content"
+            raise ValueError(
+                f"msg_type={declared!r} 与内容字段 {source!r} 不匹配，"
+                f"按 {source!r} 应为 {inferred}"
+            )
+        return raw

{qqbotsdk_base_py-2.1.0 → qqbotsdk_base_py-2.2.0}/src/qqbotsdk/ws/__init__.py

@@ -1,16 +1,18 @@
 """网关 WebSocket 客户端.
 
 对外只需要几个名字: ``Intents``(事件订阅位), ``DEFAULT_INTENTS``(默认订阅),
-``GatewayPayload``(事件数据包), ``ReadyContent``(READY 事件体),
-``QQBotWebSocket``(连接客户端), ``WILDCARD_EVENT``(通配事件名) 与 ``Handler``(回调类型).
+``GROUP_BOT_INTENTS``(只做群聊 / 单聊的订阅位), ``GatewayPayload``(事件数据包),
+``ReadyContent``(READY 事件体), ``QQBotWebSocket``(连接客户端),
+``WILDCARD_EVENT``(通配事件名) 与 ``Handler``(回调类型).
 """
 
 from qqbotsdk.ws.client import WILDCARD_EVENT, Handler, QQBotWebSocket
-from qqbotsdk.ws.intents import DEFAULT_INTENTS, Intents
+from qqbotsdk.ws.intents import DEFAULT_INTENTS, GROUP_BOT_INTENTS, Intents
 from qqbotsdk.ws.payload import GatewayPayload, OpCode, ReadyContent, ReadyUser
 
 __all__ = [
     "DEFAULT_INTENTS",
+    "GROUP_BOT_INTENTS",
     "WILDCARD_EVENT",
     "GatewayPayload",
     "Handler",

{qqbotsdk_base_py-2.1.0 → qqbotsdk_base_py-2.2.0}/src/qqbotsdk/ws/client.py

@@ -71,6 +71,26 @@ _FATAL_CLOSE_CODES: Final = frozenset(
     {4001, 4002, 4010, 4011, 4012, 4013, 4014, 4914, 4915}
 )
 
+# 不可重连关闭码的可读原因, 让报错直接指向怎么修
+_FATAL_CLOSE_REASONS: Final = {
+    4001: "无效的 opcode",
+    4002: "无效的 payload",
+    4010: "无效的 shard",
+    4011: "连接数超过限制",
+    4012: "无效的 API 版本",
+    4013: (
+        "无效的 intents：其中有当前应用不可订阅的事件位；"
+        "到开放平台确认该 intents 已在「事件订阅」中开通"
+    ),
+    4014: (
+        "无权限的 intents：该 intents 未在开放平台开通；"
+        "到「开发设置 → 事件订阅」申请对应事件，或改用 "
+        "GROUP_BOT_INTENTS 收窄订阅范围"
+    ),
+    4914: "机器人已下架, 请到开放平台检查应用状态",
+    4915: "机器人已被封禁",
+}
+
 # 其余关闭码(含 4006, 4007, 4900~4913)一律清空会话后重新 Identify
 
 
@@ -509,7 +529,11 @@ class QQBotWebSocket:
             # 主动关闭, 无需重连
             return
         if code in _FATAL_CLOSE_CODES:
-            error = QQBotGatewayError("网关拒绝连接，不可重连", code=code)
+            reason = _FATAL_CLOSE_REASONS.get(code)
+            message = "网关拒绝连接，不可重连"
+            if reason is not None:
+                message = f"{message}：{reason}"
+            error = QQBotGatewayError(message, code=code)
             self._last_error = error
             raise _StopGateway(str(error))
         if code in _RESUMABLE_CLOSE_CODES:

{qqbotsdk_base_py-2.1.0 → qqbotsdk_base_py-2.2.0}/src/qqbotsdk/ws/intents.py

@@ -42,7 +42,21 @@ DEFAULT_INTENTS: Final = (
     | Intents.INTERACTION
 )
 
+# 只做群聊 / 单聊的机器人用这一组: 不含任何频道域订阅位
+GROUP_BOT_INTENTS: Final = Intents.GROUP_AND_C2C_EVENT | Intents.INTERACTION
+"""群聊 / 单聊机器人的订阅位.
+
+``DEFAULT_INTENTS`` 带两个频道位(``GUILD_MEMBERS`` / ``PUBLIC_GUILD_MESSAGES``,
+按官方文档它们属于基础事件、默认有权限, 不会导致连接被拒), 只做群聊的机器人用
+这组更贴合实际订阅范围, 也少一位需要考虑权限的位.
+
+注意 ``INTERACTION`` 属于需要申请的特殊事件: 如果机器人不用消息按钮 / 快捷菜单,
+可以进一步收窄成 ``Intents.GROUP_AND_C2C_EVENT``. 订阅了没开通的 intent, 网关会用
+关闭码 4013 / 4014 直接断开.
+"""
+
 __all__ = [
     "DEFAULT_INTENTS",
+    "GROUP_BOT_INTENTS",
     "Intents",
 ]