qqbotsdk-base-py 2.0.0__py3-none-any.whl

qqbotsdk/errors.py

@@ -0,0 +1,92 @@
+"""统一异常体系: 业务层, 凭证层与网关层三级分类.
+
+层次::
+
+    QQBotError                  SDK 所有异常的基类
+    +-- QQBotAPIError           OpenAPI 返回的业务/HTTP 错误
+    +-- QQBotAuthError          凭证缺失或换取 access_token 失败
+    +-- QQBotGatewayError       WebSocket 网关层错误
+
+调用方 ``except QQBotError`` 可以兜住全部错误, 也可以按层分别处理.
+"""
+
+__all__ = [
+    "QQBotAPIError",
+    "QQBotAuthError",
+    "QQBotError",
+    "QQBotGatewayError",
+]
+
+
+class QQBotError(Exception):
+    """SDK 所有异常的基类."""
+
+
+class QQBotAPIError(QQBotError):
+    """OpenAPI 返回的业务错误.
+
+    Attributes:
+        status: HTTP 状态码.
+        err_code: 业务错误码 (body 中的 ``err_code`` 或 ``code``), 0 表示未知.
+        message: 服务端返回的错误描述.
+        trace_id: 服务端追踪 ID, 提交工单时需要提供.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        err_code: int = 0,
+        message: str = "",
+        trace_id: str | None = None,
+    ) -> None:
+        self.status = status
+        self.err_code = err_code
+        self.message = message
+        self.trace_id = trace_id
+        super().__init__(status, err_code, message, trace_id)
+
+    def __str__(self) -> str:
+        parts = [
+            f"status={self.status}",
+            f"err_code={self.err_code}",
+            f"message={self.message!r}",
+        ]
+        if self.trace_id:
+            parts.append(f"trace_id={self.trace_id}")
+        return f"QQBotAPIError({', '.join(parts)})"
+
+
+class QQBotAuthError(QQBotError):
+    """凭证缺失或换取 access_token 失败.
+
+    Attributes:
+        message: 失败原因, 换取失败时包含服务端返回的 ``code`` 与 ``message``.
+        code: 服务端业务码, 本地凭证缺失时为 None.
+    """
+
+    def __init__(self, message: str = "", *, code: int | None = None) -> None:
+        self.message = message
+        self.code = code
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"QQBotAuthError({self.message})"
+
+
+class QQBotGatewayError(QQBotError):
+    """WebSocket 网关层错误.
+
+    Attributes:
+        reason: 错误原因描述.
+        code: 网关返回的错误码 (op 9 无效会话或 close code), 未知时为 None.
+    """
+
+    def __init__(self, reason: str = "", code: int | None = None) -> None:
+        self.reason = reason
+        self.code = code
+        super().__init__(code, reason)
+
+    def __str__(self) -> str:
+        if self.code is None:
+            return f"QQBotGatewayError({self.reason})"
+        return f"QQBotGatewayError(code={self.code}, reason={self.reason})"

qqbotsdk/model/agent.md

@@ -0,0 +1,48 @@
+# agent.md — qqbotsdk-base/model（基类与共享子模型）
+
+适用范围：`packages/qqbotsdk-base/src/qqbotsdk/model/**`（`core.py`、`sub/messages.py`、`sub/upload.py`）。
+
+## MUST（必须做）
+
+- MUST 让所有模型继承 `QQBotBaseModel`（已配置 `validate_by_name`、`serialize_by_alias`、`extra="allow"`）；禁止直接继承 `pydantic.BaseModel`。
+- MUST 用「字段名 + 多行 `Field`」的固定写法，尾逗号：
+
+```python
+msg_type: Literal[0, 2, 7, 8] | None = Field(
+    default=None,
+    description="消息类型：0=纯文本，2=Markdown，7=富媒体，8=图文卡片",
+)
+required_name: str = Field(
+    ...,
+    description="必填字段用省略号",
+)
+```
+
+- MUST 可选字段写成 `Field(default=None, ...)` 而不是 `Field(None, ...)`：pydantic 2.14 + pyright 会把后者当成必填，导致用户侧任何「部分构造」（如 `SendGroupMessagesRequest(content="x")`）都报 `reportCallIssue`。
+- MUST 严格照文档定必填性：「必填=是」→ `Field(...)`；「必填=否」→ `Field(default=None, ...)`。
+- MUST 让 `description` 用中文、单句、**不加结尾句号**，并尽量沿用文档原词。
+- MUST 在收紧取值时用 `Literal[...]`，在有明确上下限时加 `ge`/`le`/`max_length`/`min_length`。
+- MUST 保持向后兼容：只允许新增字段、放宽类型、改描述；删除/改名/收窄公开字段前必须取得许可。
+
+## SHOULD（应当做）
+
+- SHOULD 把「多业务域共用」的结构放这里（键盘、Markdown、引用、富媒体、卡片、分片上传）；单一业务域专有的模型放各自包。
+- SHOULD 用 `list[X] | None` 而不是 `list[X] = []`；需要可变默认值时用 `Field(default_factory=list)`。
+- SHOULD 用 `RootModel` 表达「裸数组」响应，用普通模型表达对象响应。
+
+## MUST NOT（禁止做）
+
+- MUST NOT 建模已废弃/不可用字段：`Keyboard.id`（内嵌键盘模板）、群/单聊 `MessageMarkdown.template_id` / `custom_template_id`、`Action.click_limit`、`Action.at_bot_show_channel_list`。
+- MUST NOT 按「码点」加中文字符数上限——文档说「一个中文汉字算 2 个字符」时，把限制写进 `description`，不要加 `max_length`（会比文档更严，误拒合法输入）。
+- MUST NOT 在这里 import 任何业务包（`qqbotsdk.model.group` / `guild` / `event` 等）。
+- MUST NOT 为同一个结构重复造多个类；共享子模型只有一个定义。
+
+## 自检
+
+```powershell
+cd D:\QQBotSDK
+.venv\Scripts\ruff.exe check packages\qqbotsdk-base\src\qqbotsdk\model
+.venv\Scripts\pyright.exe
+```
+
+改动的字段会影响 `qqbotsdk-py` 与 `qqbotsdk-guild-py` 的所有请求模型，改完必须全仓跑质量门。

qqbotsdk/model/core.py

@@ -0,0 +1,30 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class QQBotBaseModel(BaseModel):
+    """响应/事件模型基类: 宽容未知字段, 服务端新增字段不会导致解析失败."""
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        serialize_by_alias=True,
+        extra="allow",
+    )
+
+
+class QQBotRequestModel(QQBotBaseModel):
+    """请求体基类: 禁止未知字段.
+
+    字段名拼错时会立刻抛 ``ValidationError``, 而不是把错误字段静默发给服务端.
+    """
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        serialize_by_alias=True,
+        extra="forbid",
+    )
+
+
+__all__ = [
+    "QQBotBaseModel",
+    "QQBotRequestModel",
+]

qqbotsdk/model/sub/messages.py

@@ -0,0 +1,209 @@
+from typing import Literal
+
+from pydantic import Field
+
+from qqbotsdk.model.core import QQBotBaseModel
+
+
+class Permission(QQBotBaseModel):
+    type: Literal[0, 1, 2, 3] | None = Field(
+        default=None,
+        description="0=指定用户, 1=管理员, 2=所有人, 3=指定身份组（仅频道可用）",
+    )
+    specify_user_ids: list[str] | None = Field(
+        default=None,
+        description="有权限的用户 id 的列表",
+    )
+    specify_role_ids: list[str] | None = Field(
+        default=None,
+        description="有权限的身份组 id 的列表（仅频道可用）",
+    )
+
+
+class Modal(QQBotBaseModel):
+    content: str | None = Field(
+        default=None,
+        max_length=40,
+        description="二次确认的提示文本，不为空则进行二次确认，最多 40 个字符，不能有 URL",
+    )
+    confirm_text: str | None = Field(
+        default=None,
+        max_length=4,
+        description='二次确认提示确认按钮文字，默认为"确认"，最多 4 个字符',
+    )
+    cancel_text: str | None = Field(
+        default=None,
+        max_length=4,
+        description='二次确认提示取消按钮文字，默认为"取消"，最多 4 个字符',
+    )
+
+
+class Action(QQBotBaseModel):
+    type: Literal[0, 1, 2] | None = Field(
+        default=None,
+        description="0=跳转按钮，1=回调按钮，2=指令按钮",
+    )
+    permission: Permission | None = Field(
+        default=None,
+        description="操作权限",
+    )
+    data: str | None = Field(
+        default=None,
+        description="回调数据。type=1/2 时必填",
+    )
+    unsupport_tips: str | None = Field(
+        default=None,
+        description="版本过低时提示文案",
+    )
+    enter: bool | None = Field(
+        default=None,
+        description="指令按钮可用，点击按钮后直接自动发送 data，仅单聊可用，默认 false",
+    )
+    reply: bool | None = Field(
+        default=None,
+        description="指令按钮可用，指令是否带引用回复本消息，默认 false",
+    )
+    anchor: int | None = Field(
+        default=None,
+        description="仅指令按钮下有效，设置后忽略 action.enter，设置为 1 时点击按钮自动唤起手Q选图器",
+    )
+    modal: Modal | None = Field(
+        default=None,
+        description="用户点击二次确认操作",
+    )
+
+
+class RenderData(QQBotBaseModel):
+    label: str | None = Field(
+        default=None,
+        max_length=10,
+        description="按钮文字，最多 10 字符",
+    )
+    visited_label: str | None = Field(
+        default=None,
+        description="点击后文字，不传则保持不变",
+    )
+    style: Literal[0, 1, 3, 4] | None = Field(
+        default=None,
+        description="0=灰色线框，1=蓝色线框，3=白色背景+红色字体，4=蓝色背景+白色字体",
+    )
+
+
+class Button(QQBotBaseModel):
+    id: str | None = Field(
+        default=None,
+        description="按钮 ID。同一键盘内唯一",
+    )
+    render_data: RenderData | None = Field(
+        default=None,
+        description="按钮渲染",
+    )
+    action: Action | None = Field(
+        default=None,
+        description="按钮点击行为",
+    )
+    group_id: str | None = Field(
+        default=None,
+        description="分组ID，同一分组内有一个按钮操作后其它按钮变灰不可点击，仅当 action.type = 1 时有效",
+    )
+
+
+class Row(QQBotBaseModel):
+    buttons: list[Button] | None = Field(
+        default=None,
+        description="行内按钮，从左到右排列",
+    )
+
+
+class KeyboardContent(QQBotBaseModel):
+    rows: list[Row] | None = Field(
+        default=None,
+        description="按钮行列表",
+    )
+
+
+class Keyboard(QQBotBaseModel):
+    content: KeyboardContent | None = Field(
+        default=None,
+        description="自定义键盘布局，用于自定义按钮",
+    )
+
+
+class MessageMarkdown(QQBotBaseModel):
+    content: str | None = Field(
+        default=None,
+        description="Markdown 内容",
+    )
+    force_verify_image_resource: bool | None = Field(
+        default=None,
+        description="是否校验图片转存结果，为 true 时图片转存失败会返回错误且消息不发送，默认 false",
+    )
+
+
+class MediaInfo(QQBotBaseModel):
+    file_info: str | None = Field(
+        default=None,
+        description="文件数据。来自文件上传接口返回值",
+    )
+
+
+class MessageReference(QQBotBaseModel):
+    message_id: str | None = Field(
+        default=None,
+        description="被引用消息 ID，例如 REFIDX_xxxxxx",
+    )
+
+
+class InputNotify(QQBotBaseModel):
+    input_type: Literal[1] | None = Field(
+        default=None,
+        description="填 1",
+    )
+    input_second: int | None = Field(
+        default=None,
+        le=60,
+        description="状态持续时间，最长 60s",
+    )
+
+
+class MessageExtInfo(QQBotBaseModel):
+    ref_idx: str | None = Field(
+        default=None,
+        description="引用消息索引。对应消息时间 ext 里的 msg_idx 与 ref_msg_idx",
+    )
+
+
+class MessageCardContent(QQBotBaseModel):
+    title: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=50,
+        description="卡片标题，1-50 字符",
+    )
+    description: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=200,
+        description="卡片描述，1-200 字符",
+    )
+    url: str | None = Field(
+        default=None,
+        max_length=1024,
+        description="跳转链接，必须为 https，长度 <= 1024 字符",
+    )
+    pic_url: str | None = Field(
+        default=None,
+        max_length=1024,
+        description="封面图链接，必须为 https，长度 <= 1024 字符",
+    )
+
+
+class MessageCard(QQBotBaseModel):
+    type: Literal["tuwen"] | None = Field(
+        default=None,
+        description="卡片类型：tuwen=图文卡片",
+    )
+    content: MessageCardContent | None = Field(
+        default=None,
+        description="卡片元素；type=tuwen 时必须包含 title/description/url/pic_url",
+    )

qqbotsdk/model/sub/upload.py

@@ -0,0 +1,100 @@
+from typing import Literal
+
+from pydantic import Field
+
+from qqbotsdk.model.core import QQBotBaseModel, QQBotRequestModel
+
+
+class UploadPart(QQBotBaseModel):
+    index: int | None = Field(
+        default=None,
+        description="分片序号，从 0 开始",
+    )
+    presigned_url: str | None = Field(
+        default=None,
+        description="预签名上传 URL，客户端通过 HTTP PUT 将分片数据上传到此 URL",
+    )
+    block_size: str | None = Field(
+        default=None,
+        description="该分块的大小（字节）",
+    )
+
+
+class UploadConfig(QQBotBaseModel):
+    concurrency: int | None = Field(
+        default=None,
+        description="上传并发数，默认 1",
+    )
+    retry_timeout: int | None = Field(
+        default=None,
+        description="重试超时时间（秒），默认 300（5 分钟）",
+    )
+    retry_delay: int | None = Field(
+        default=None,
+        description="重试延迟（秒），默认 1",
+    )
+
+
+class UploadPrepareResponse(QQBotBaseModel):
+    upload_id: str | None = Field(
+        default=None,
+        description="上传任务 ID，后续分片上传和完成合并时需携带",
+    )
+    block_size: str | None = Field(
+        default=None,
+        description="分块大小（字节），默认 5MB",
+    )
+    parts: list[UploadPart] | None = Field(
+        default=None,
+        description="分片列表，每个分片包含一个预签名上传 URL",
+    )
+    upload_config: UploadConfig | None = Field(
+        default=None,
+        description="上传配置，控制客户端上传行为",
+    )
+
+
+class UploadPartFinishRequest(QQBotRequestModel):
+    upload_id: str | None = Field(
+        default=None,
+        description="上传任务 ID，来自预上传响应",
+    )
+    part_index: int | None = Field(
+        default=None,
+        description="分片序号，对应 UploadPart.index",
+    )
+    block_size: str | None = Field(
+        default=None,
+        description="该分块的实际大小（字节）",
+    )
+    md5: str | None = Field(
+        default=None,
+        description="该分片的 MD5 校验值",
+    )
+
+
+class UploadPrepareRequest(QQBotRequestModel):
+    file_type: Literal[1, 2, 3, 4] = Field(
+        ...,
+        description="业务类型：1=图片，2=视频，3=语音，4=文件，超过软限制会降级为文件类型",
+    )
+    file_size: str = Field(
+        ...,
+        description="文件大小（字节），字符串形式",
+    )
+    file_name: str = Field(
+        ...,
+        description="文件名",
+    )
+    md5: str = Field(
+        ...,
+        description="整个文件的 MD5 校验值",
+    )
+    sha1: str = Field(
+        ...,
+        description="整个文件的 SHA1 校验值",
+    )
+    md5_10m: str = Field(
+        ...,
+        description="文件前 10002432 字节（约 10MB）的 MD5 校验值",
+    )

qqbotsdk/ws/__init__.py

@@ -0,0 +1,22 @@
+"""网关 WebSocket 客户端.
+
+对外只需要几个名字: ``Intents``(事件订阅位), ``DEFAULT_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.payload import GatewayPayload, OpCode, ReadyContent, ReadyUser
+
+__all__ = [
+    "DEFAULT_INTENTS",
+    "WILDCARD_EVENT",
+    "GatewayPayload",
+    "Handler",
+    "Intents",
+    "OpCode",
+    "QQBotWebSocket",
+    "ReadyContent",
+    "ReadyUser",
+]

qqbotsdk/ws/agent.md

@@ -0,0 +1,39 @@
+# agent.md — qqbotsdk-base/ws（网关 WebSocket）
+
+适用范围：`packages/qqbotsdk-base/src/qqbotsdk/ws/**`（`intents.py`、`payload.py`、`client.py`、`__init__.py`）。
+
+职责：网关长连接的状态机——握手、心跳、重连、Resume、事件分发。**不含任何业务模型**。
+
+## MUST（必须做）
+
+- MUST 按官方顺序驱动状态机：等 `op=10 Hello` → 取 `heartbeat_interval` → 启动心跳 Task → 有 `session_id` 且 `seq` 非空发 `op=6 Resume`，否则发 `op=2 Identify`。
+- MUST 在 `Identify` 里固定上报 `"shard": [0, 1]`（本 SDK 不做分片）。
+- MUST 让心跳携带**最近一次收到的 `s`**（首次为 `None`），并处理 `op=11` ACK。
+- MUST 按关闭码分三类处理：`4009` 保留会话走 Resume；`4001`/`4002`/`4010~4014`/`4914`/`4915` 直接终止不再重连；其余（含 `4006`/`4007`/`4900~4913`/`None`）清空会话重新 Identify。
+- MUST 重连使用指数退避（`min(base * 2**(n-1), max)`，指数封顶避免溢出），并在 READY/RESUMED 成功后归零。
+- MUST 让 `close()` 幂等：停心跳、关 ws、取消后台任务、投递结束哨兵；`async for` 在停止后以 `StopAsyncIteration` 结束。
+- MUST 保持 `__aiter__` 只产出 `op=0` 的 Dispatch 帧（READY / RESUMED 也产出）。
+
+## SHOULD（应当做）
+
+- SHOULD 把无法解析或校验失败的帧记 `warning` 后忽略，而不是让整个连接崩掉。
+- SHOULD 让 `wait_ready(timeout=...)` 同时等待「就绪」与「已停止」两个事件，避免无限挂起。
+- SHOULD 复用 `qqbotsdk.api.core` 的 `session.client` 与 `qqbotsdk.api.auth.get_access_token()`，不要自建 HTTP 会话。
+
+## MUST NOT（禁止做）
+
+- MUST NOT 打印或记录 `access_token`（包括拼好的 `QQBot <token>`）；调试时只允许打印长度或事件名。
+- MUST NOT 实现分片/负载均衡：不接 `shard` 参数、不封装 `GET /gateway/bot`。
+- MUST NOT 在 `ws/` 里 import 业务包模型；事件体由业务包自己的 `parse_event` 解析。
+- MUST NOT 依赖 aiohttp 的内建心跳（`ws_connect(heartbeat=...)` 必须为 `None`），心跳由本模块自己发。
+- MUST NOT 让异常静默死亡：不可重试的终止必须留下 `error` 级日志。
+
+## 自检
+
+```powershell
+cd D:\QQBotSDK
+.venv\Scripts\ruff.exe check packages\qqbotsdk-base\src\qqbotsdk\ws
+.venv\Scripts\pyright.exe
+```
+
+回归方式：用 `aiohttp.web` 起本地假网关（Hello → Identify → READY → 心跳/ACK → Dispatch → `close(4009)` → Resume → RESUMED），断言事件顺序、`Identify` 的 `shard == [0, 1]`、Resume 携带的 `session_id`/`seq`。真机联调用 `get_gateway()` 拿地址后连一次，确认能收到 READY 后正常关闭。