qqbotsdk-base-py 2.0.0__tar.gz

qqbotsdk_base_py-2.0.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.3
+Name: qqbotsdk-base-py
+Version: 2.0.0
+Summary: QQ 官方机器人 SDK 基座包：模型基类、共享消息模型与 HTTP 会话
+Author: snowy-yang
+Author-email: snowy-yang <102860110+snowy-yang@users.noreply.github.com>
+Requires-Dist: aiohttp>=3.14.5
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: python-dotenv>=1.2.4
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# qqbotsdk-base-py
+
+QQ 官方机器人 SDK 基座包。各业务域包共用的最小依赖面与共享代码：
+
+- `qqbotsdk.model.core`：`QQBotBaseModel`（pydantic 基类）
+- `qqbotsdk.model.sub.messages`：共享消息模型（键盘、Markdown、引用、富媒体等）
+- `qqbotsdk.api.core`：懒加载的共享 `session`（指向 `https://api.bot.qq.com`，自动注入鉴权头）
+- `qqbotsdk.api.auth`：`access_token` 的获取、缓存与自动刷新
+- `qqbotsdk.ws`：网关 WebSocket 客户端
+- 依赖：`aiohttp`、`pydantic`、`loguru`、`python-dotenv`
+
+## 安装
+
+```bash
+pip install qqbotsdk-base-py
+```
+
+通常不需要直接安装；装 `qqbotsdk-py` 或 `qqbotsdk-guild-py` 时会自动带上。
+
+## 鉴权
+
+在 `.env` 或环境变量里配置 `APPID` / `APPSECRET`（可选 `TIMEOUT`，单位毫秒）：
+
+```python
+from qqbotsdk.api.auth import get_access_token
+from qqbotsdk.api.bot import get_me  # 请求会自动带上 Authorization: QQBot <token>
+from qqbotsdk.api.core import session
+
+me = await get_me()  # 不用手写请求头
+token = await get_access_token()  # 需要自己持有时
+await session.close()  # 进程退出前收尾
+```
+
+- 凭证进程内缓存，有效期 7200 秒，剩余不足 60 秒时自动换取；并发调用只换一次。
+- 换取凭证的接口本身不带鉴权头；发往其它域名的绝对地址（如 COS 预签名上传）也不带。
+- `session` 在首次使用时才创建，因此可以在任意位置 import，不需要先有事件循环。
+
+## 命名空间
+
+三个发行包共享 `qqbotsdk` 导入命名空间（各包的 `qqbotsdk/` 顶层目录不含 `__init__.py`，子包如 `qqbotsdk/ws/` 仍带自己的 `__init__.py` 以汇总导出），可任意组合安装。
+
+## WebSocket 网关
+
+`qqbotsdk.ws` 提供网关客户端（只依赖 aiohttp 与 pydantic，不含业务模型）：
+
+```python
+import asyncio
+
+from qqbotsdk.ws import DEFAULT_INTENTS, QQBotWebSocket
+
+
+async def main() -> None:
+    async with QQBotWebSocket(intents=DEFAULT_INTENTS) as ws:  # 网关地址自动获取
+        await ws.wait_ready()
+        async for payload in ws:
+            print(payload.t, payload.d)
+
+
+asyncio.run(main())
+```
+
+要点：
+
+- `Intents`（`IntFlag`）声明订阅的事件位；`DEFAULT_INTENTS` = 群与单聊消息 + 公域频道消息 + 频道成员 + 交互事件。
+- `async for` 只产出 `op=0` 的 Dispatch 事件（`payload.t` / `payload.d` / `payload.s` / `payload.id`），READY 与 RESUMED 也会产出；READY 的事件体可用 `ReadyContent` 解析。
+- **不做分片**：固定单连接，`Identify` 一律上报 `shard=[0, 1]`，没有 `shard` 参数，也不封装 `GET /gateway/bot`；需要多连接负载均衡请自行拆分。
+- 心跳按 Hello 下发的 `heartbeat_interval` 由独立 `asyncio.Task` 定时发送，收到 op=11 ACK 后复位，退出时自动取消。
+- 断线自动重连（指数退避）：仍持有 `session_id` 与 `seq` 时走 Resume，否则重新 Identify；不可重试的关闭码（4001、4002、4010~4014、4914、4915）会直接终止。
+- `url` 省略时**每次建连前自动调用 `GET /gateway` 获取**（地址可能随调度变化，不硬编码域名）；也可显式传 `url=` 覆盖。
+- 因致命关闭码停止时，`ws.last_error` 是 `QQBotGatewayError`（带 `code`，例如 `4914` 已下架、`4915` 已封禁）。
+- `await ws.wait_ready()` 等到 READY 或 RESUMED；`await ws.close()` 或退出 `async with` 时关闭连接并取消后台任务；日志不会打印 access_token。
+- 可注册回调：`ws.on("GROUP_AT_MESSAGE_CREATE", handler)` / `ws.on(WILDCARD_EVENT, handler)`，回调以独立任务派发、不阻塞收包，异常只记日志；`ws.off(...)` 取消，注册回调后 `async for` 仍可用。
+- HTTP 429 自动重试（最多 3 次、`Retry-After` 优先、指数退避 + 抖动、总等待 ≤ 30 秒），可用 `MAX_RETRIES` / `RETRY_BASE_SECONDS` 调整。
+
+## 错误体系
+
+`qqbotsdk.errors` 定义三级错误，全部继承 `QQBotError`：
+
+- `QQBotAPIError`：HTTP 4xx/5xx、body 带非零 `err_code`/`code`、201/202 错误体（`status`/`err_code`/`message`/`trace_id`）。
+- `QQBotAuthError`：凭证缺失或换取 access_token 失败。
+- `QQBotGatewayError`：网关致命关闭码、网关响应缺少 `url`。
+
+`api/core.py` 通过自定义 `response_class` 统一做这套检查，因此业务 api 函数里看不到任何错误处理代码。

qqbotsdk_base_py-2.0.0/README.md

@@ -0,0 +1,83 @@
+# qqbotsdk-base-py
+
+QQ 官方机器人 SDK 基座包。各业务域包共用的最小依赖面与共享代码：
+
+- `qqbotsdk.model.core`：`QQBotBaseModel`（pydantic 基类）
+- `qqbotsdk.model.sub.messages`：共享消息模型（键盘、Markdown、引用、富媒体等）
+- `qqbotsdk.api.core`：懒加载的共享 `session`（指向 `https://api.bot.qq.com`，自动注入鉴权头）
+- `qqbotsdk.api.auth`：`access_token` 的获取、缓存与自动刷新
+- `qqbotsdk.ws`：网关 WebSocket 客户端
+- 依赖：`aiohttp`、`pydantic`、`loguru`、`python-dotenv`
+
+## 安装
+
+```bash
+pip install qqbotsdk-base-py
+```
+
+通常不需要直接安装；装 `qqbotsdk-py` 或 `qqbotsdk-guild-py` 时会自动带上。
+
+## 鉴权
+
+在 `.env` 或环境变量里配置 `APPID` / `APPSECRET`（可选 `TIMEOUT`，单位毫秒）：
+
+```python
+from qqbotsdk.api.auth import get_access_token
+from qqbotsdk.api.bot import get_me  # 请求会自动带上 Authorization: QQBot <token>
+from qqbotsdk.api.core import session
+
+me = await get_me()  # 不用手写请求头
+token = await get_access_token()  # 需要自己持有时
+await session.close()  # 进程退出前收尾
+```
+
+- 凭证进程内缓存，有效期 7200 秒，剩余不足 60 秒时自动换取；并发调用只换一次。
+- 换取凭证的接口本身不带鉴权头；发往其它域名的绝对地址（如 COS 预签名上传）也不带。
+- `session` 在首次使用时才创建，因此可以在任意位置 import，不需要先有事件循环。
+
+## 命名空间
+
+三个发行包共享 `qqbotsdk` 导入命名空间（各包的 `qqbotsdk/` 顶层目录不含 `__init__.py`，子包如 `qqbotsdk/ws/` 仍带自己的 `__init__.py` 以汇总导出），可任意组合安装。
+
+## WebSocket 网关
+
+`qqbotsdk.ws` 提供网关客户端（只依赖 aiohttp 与 pydantic，不含业务模型）：
+
+```python
+import asyncio
+
+from qqbotsdk.ws import DEFAULT_INTENTS, QQBotWebSocket
+
+
+async def main() -> None:
+    async with QQBotWebSocket(intents=DEFAULT_INTENTS) as ws:  # 网关地址自动获取
+        await ws.wait_ready()
+        async for payload in ws:
+            print(payload.t, payload.d)
+
+
+asyncio.run(main())
+```
+
+要点：
+
+- `Intents`（`IntFlag`）声明订阅的事件位；`DEFAULT_INTENTS` = 群与单聊消息 + 公域频道消息 + 频道成员 + 交互事件。
+- `async for` 只产出 `op=0` 的 Dispatch 事件（`payload.t` / `payload.d` / `payload.s` / `payload.id`），READY 与 RESUMED 也会产出；READY 的事件体可用 `ReadyContent` 解析。
+- **不做分片**：固定单连接，`Identify` 一律上报 `shard=[0, 1]`，没有 `shard` 参数，也不封装 `GET /gateway/bot`；需要多连接负载均衡请自行拆分。
+- 心跳按 Hello 下发的 `heartbeat_interval` 由独立 `asyncio.Task` 定时发送，收到 op=11 ACK 后复位，退出时自动取消。
+- 断线自动重连（指数退避）：仍持有 `session_id` 与 `seq` 时走 Resume，否则重新 Identify；不可重试的关闭码（4001、4002、4010~4014、4914、4915）会直接终止。
+- `url` 省略时**每次建连前自动调用 `GET /gateway` 获取**（地址可能随调度变化，不硬编码域名）；也可显式传 `url=` 覆盖。
+- 因致命关闭码停止时，`ws.last_error` 是 `QQBotGatewayError`（带 `code`，例如 `4914` 已下架、`4915` 已封禁）。
+- `await ws.wait_ready()` 等到 READY 或 RESUMED；`await ws.close()` 或退出 `async with` 时关闭连接并取消后台任务；日志不会打印 access_token。
+- 可注册回调：`ws.on("GROUP_AT_MESSAGE_CREATE", handler)` / `ws.on(WILDCARD_EVENT, handler)`，回调以独立任务派发、不阻塞收包，异常只记日志；`ws.off(...)` 取消，注册回调后 `async for` 仍可用。
+- HTTP 429 自动重试（最多 3 次、`Retry-After` 优先、指数退避 + 抖动、总等待 ≤ 30 秒），可用 `MAX_RETRIES` / `RETRY_BASE_SECONDS` 调整。
+
+## 错误体系
+
+`qqbotsdk.errors` 定义三级错误，全部继承 `QQBotError`：
+
+- `QQBotAPIError`：HTTP 4xx/5xx、body 带非零 `err_code`/`code`、201/202 错误体（`status`/`err_code`/`message`/`trace_id`）。
+- `QQBotAuthError`：凭证缺失或换取 access_token 失败。
+- `QQBotGatewayError`：网关致命关闭码、网关响应缺少 `url`。
+
+`api/core.py` 通过自定义 `response_class` 统一做这套检查，因此业务 api 函数里看不到任何错误处理代码。

qqbotsdk_base_py-2.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "qqbotsdk-base-py"
+version = "2.0.0"
+description = "QQ 官方机器人 SDK 基座包：模型基类、共享消息模型与 HTTP 会话"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.14.5",
+    "loguru>=0.7.3",
+    "pydantic>=2.14.1",
+    "python-dotenv>=1.2.4",
+]
+
+[[project.authors]]
+name = "snowy-yang"
+email = "102860110+snowy-yang@users.noreply.github.com"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "qqbotsdk"
+namespace = true

qqbotsdk_base_py-2.0.0/pyproject.toml.orig

@@ -0,0 +1,23 @@
+[project]
+name = "qqbotsdk-base-py"
+version = "2.0.0"
+description = "QQ 官方机器人 SDK 基座包：模型基类、共享消息模型与 HTTP 会话"
+readme = "README.md"
+authors = [
+    { name = "snowy-yang", email = "102860110+snowy-yang@users.noreply.github.com" },
+]
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.14.5",
+    "loguru>=0.7.3",
+    "pydantic>=2.14.1",
+    "python-dotenv>=1.2.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "qqbotsdk"
+namespace = true

qqbotsdk_base_py-2.0.0/src/qqbotsdk/api/agent.md

@@ -0,0 +1,40 @@
+# agent.md — qqbotsdk-base/api（HTTP 会话与鉴权）
+
+适用范围：`packages/qqbotsdk-base/src/qqbotsdk/api/**`（`core.py`、`auth.py`）。
+
+职责：让所有业务包「不带任何鉴权代码」也能直接调用 OpenAPI。
+
+## MUST（必须做）
+
+- MUST 让 `session` 保持**懒加载单例**：首次使用时才创建 `aiohttp.ClientSession`；`import` 阶段不得触碰事件循环。
+- MUST 通过 `TraceConfig.on_request_start` 统一注入 `Authorization: QQBot <access_token>`，业务函数不得手写该请求头。
+- MUST 只对 `https://api.bot.qq.com` 的请求注入鉴权头：
+  - 发往其它域名的绝对地址（COS 预签名上传）MUST NOT 带；
+  - `/app/getAppAccessToken` 本身 MUST NOT 带。
+- MUST 在换取 token 时按**响应体 `code`** 判定失败（该接口业务错误仍返回 HTTP 200），失败抛 `QQBotAuthError`。
+- MUST 容忍 `expires_in` 为字符串（官方示例是 `"7200"`）。
+- MUST 在剩余有效期不足 60 秒时主动刷新，并用 `asyncio.Lock` 保证并发只换取一次。
+
+## SHOULD（应当做）
+
+- SHOULD 保持 `get_access_token()` / `get_authorization()` / `reset_access_token()` 三个公开入口的签名稳定。
+- SHOULD 让超时来自环境变量 `TIMEOUT`（毫秒，缺省 5000），便于部署调整。
+- SHOULD 提供 `session.client` 暴露底层 `ClientSession`，供 `ws` 等需要原生能力的场景使用。
+
+## MUST NOT（禁止做）
+
+- MUST NOT 在 `core.py` 里写业务接口逻辑；它只负责会话、请求头、错误面。
+- MUST NOT 缓存到磁盘或用全局可变状态以外的机制持久化 token。
+- MUST NOT 允许「无凭证时 import 就报错」：缺少 `APPID`/`APPSECRET` 只能在实际换取 token 时报错。
+- MUST NOT 把 token 写进日志、异常 message 或 `repr`；需要标识时只打印长度或前几位掩码。
+- MUST NOT 修改 `session` 的公开用法（`async with session.get(...) as resp`），否则 20+ 个业务模块会全部失效。
+
+## 自检
+
+```powershell
+cd D:\QQBotSDK
+.venv\Scripts\ruff.exe check packages\qqbotsdk-base\src\qqbotsdk\api
+.venv\Scripts\pyright.exe
+```
+
+联调：`QQBOT` 凭证配置好后，`await get_me()` 应能返回机器人信息；注入假 token 时应得到 HTTP 401（说明头已注入）。

qqbotsdk_base_py-2.0.0/src/qqbotsdk/api/auth.py

@@ -0,0 +1,134 @@
+"""访问凭证(access_token)的获取, 缓存与自动刷新.
+
+凭证来自环境变量 ``APPID`` / ``APPSECRET``, 支持从项目根目录的 ``.env`` 读取.
+按官方文档, 凭证有效期 7200 秒, 且在过期前 60 秒内换取会直接返回新凭证, 因此这里
+在剩余有效时间不足 60 秒时主动刷新, 调用方无需关心过期.
+
+``QQBotAuthError`` 定义在 :mod:`qqbotsdk.errors`, 这里 re-export, 旧的
+``from qqbotsdk.api.auth import QQBotAuthError`` 仍然可用.
+"""
+
+import asyncio
+import os
+import time
+from typing import Final
+
+from aiohttp import ClientSession
+from dotenv import load_dotenv
+from loguru import logger
+
+from qqbotsdk.errors import QQBotAuthError
+
+# 获取凭证的接口地址, 不走 BASE_URL 以避免与 core 循环依赖
+TOKEN_URL: Final = "https://api.bot.qq.com/app/getAppAccessToken"
+
+# 提前刷新余量: 官方文档为过期前 60 秒内可换到新凭证
+REFRESH_MARGIN_SECONDS: Final = 60
+
+load_dotenv()
+
+_lock = asyncio.Lock()
+_token: str | None = None
+_expires_at: float = 0.0
+
+
+def _credentials() -> tuple[str, str] | None:
+    """读取 appId/appSecret, 缺任一项视为未配置."""
+    app_id = os.getenv("APPID") or os.getenv("QQBOT_APPID")
+    app_secret = os.getenv("APPSECRET") or os.getenv("QQBOT_APPSECRET")
+    if not app_id or not app_secret:
+        return None
+    return app_id, app_secret
+
+
+def _cached_token() -> str | None:
+    """命中缓存且未进入刷新窗口时返回当前凭证."""
+    if _token is not None and time.monotonic() < _expires_at - REFRESH_MARGIN_SECONDS:
+        return _token
+    return None
+
+
+async def _fetch_token() -> tuple[str, int]:
+    credentials = _credentials()
+    if credentials is None:
+        raise QQBotAuthError(
+            "缺少 APPID / APPSECRET：请在 .env 或环境变量中配置机器人凭证"
+        )
+    app_id, app_secret = credentials
+
+    async with (
+        ClientSession() as client,
+        client.post(
+            TOKEN_URL,
+            json={"appId": app_id, "clientSecret": app_secret},
+        ) as resp,
+    ):
+        body: dict[str, object] = await resp.json(content_type=None)
+
+    # 该接口业务错误仍返回 HTTP 200, 需按 code 判定
+    if (code := body.get("code")) is not None:
+        message = body.get("message")
+        raise QQBotAuthError(
+            f"获取 access_token 失败：code={code} message={message!r}",
+            code=code if isinstance(code, int) else None,
+        )
+
+    token = body.get("access_token")
+    expires_in = body.get("expires_in")
+    if not isinstance(token, str) or not token:
+        raise QQBotAuthError(
+            f"获取 access_token 失败：响应缺少 access_token（{body!r}）"
+        )
+
+    try:
+        # 文档示例中 expires_in 为字符串 "7200", 两种形态都接受
+        ttl = int(expires_in)  # pyright: ignore[reportArgumentType]
+    except (TypeError, ValueError):
+        ttl = 7200
+
+    return token, ttl
+
+
+async def get_access_token(*, force: bool = False) -> str:
+    """返回可用的 access_token, 必要时刷新.
+
+    Args:
+        force: 忽略缓存强制刷新.
+    """
+    global _token, _expires_at
+
+    if not force and (cached := _cached_token()) is not None:
+        return cached
+
+    async with _lock:
+        # 并发进入时可能已被其他协程刷新, 二次检查避免重复请求
+        if not force and (cached := _cached_token()) is not None:
+            return cached
+
+        token, ttl = await _fetch_token()
+        _token = token
+        _expires_at = time.monotonic() + ttl
+        logger.debug(f"access_token 已刷新，有效期 {ttl} 秒")
+        return token
+
+
+async def get_authorization() -> str:
+    """返回 Authorization 请求头的值, 格式为 ``QQBot ACCESS_TOKEN``."""
+    return f"QQBot {await get_access_token()}"
+
+
+def reset_access_token() -> None:
+    """清空缓存凭证, 供测试或主动失效时使用."""
+    global _token, _expires_at
+    _token = None
+    _expires_at = 0.0
+
+
+__all__ = [
+    "REFRESH_MARGIN_SECONDS",
+    "TOKEN_URL",
+    "QQBotAuthError",
+    "get_access_token",
+    "get_authorization",
+    "reset_access_token",
+]