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

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/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",
+]

qqbotsdk/api/core.py

@@ -0,0 +1,449 @@
+"""HTTP 会话: 懒加载 aiohttp 会话并自动注入鉴权请求头.
+
+对外暴露单例 ``session``, 用法与 ``aiohttp.ClientSession`` 一致::
+
+    async with session.get("/users/@me") as resp:
+        data = await resp.json()
+
+会话在首次使用时才创建, 因此可以在任意位置 import 本模块, 无需先有事件循环;
+发往 OpenAPI 域名的请求会自动附加 ``Authorization: QQBot <access_token>``,
+发往其它域名的绝对地址(例如素材上传的 COS 预签名 URL)则不附加该请求头.
+
+响应侧统一交给 :class:`QQBotResponse` 处理, 业务模块无需改动:
+
+- 空响应 (204, 无 content-type, 空 body) 返回 ``{}``, 不再抛 ``ContentTypeError``;
+- 非 JSON content-type 返回 ``{}``;
+- OpenAPI 域名下 body 含非零 ``err_code`` / ``code`` 时抛 ``QQBotAPIError``;
+- 命中 HTTP 429 (限频) 时自动退避重试, 最多 ``MAX_RETRIES`` 次, 见
+  :class:`_RetryingRequestContext`; 业务函数仍然只写 ``async with session.get(...)``.
+"""
+
+import asyncio
+import os
+import random
+from collections.abc import Awaitable, Callable, Generator, Mapping
+from types import TracebackType
+from typing import Any, Final, cast
+from urllib.parse import urlparse
+
+from aiohttp import ClientResponse, ClientSession, ClientTimeout, TraceConfig
+from aiohttp.tracing import TraceRequestStartParams
+from aiohttp.typedefs import DEFAULT_JSON_DECODER, JSONDecoder
+from loguru import logger
+
+from qqbotsdk.api.auth import get_authorization
+from qqbotsdk.errors import QQBotAPIError
+
+# OpenAPI 统一域名
+BASE_URL: Final = "https://api.bot.qq.com"
+
+# 默认请求超时(毫秒), 可由环境变量 TIMEOUT 覆盖
+DEFAULT_TIMEOUT_MS: Final = 5000
+
+# 429 自动重试: 最多重试次数(不含首次请求)
+MAX_RETRIES: Final = 3
+
+# 退避基准秒数: 第 n 次重试等待 RETRY_BASE_SECONDS * 2 ** n, 再叠加抖动
+RETRY_BASE_SECONDS: Final = 1.0
+
+# 一次请求的所有重试等待总和上限(秒)
+RETRY_TOTAL_WAIT_SECONDS: Final = 30.0
+
+# 抖动比例: 在退避时长上叠加 0~10% 随机量, 避免多客户端同时重试
+_RETRY_JITTER_RATIO: Final = 0.1
+
+# 需要自动重试的状态码. 429 表示请求未被处理, 重发不会重复产生副作用
+_TOO_MANY_REQUESTS: Final = 429
+
+# 换取凭证的接口本身不需要也不应该带鉴权头
+_NO_AUTH_PATHS: Final = frozenset({"/app/getAppAccessToken"})
+
+_API_HOST: Final[str] = urlparse(BASE_URL).hostname or ""
+
+# 统一错误检查生效的域名. 默认只有 OpenAPI 域名, 其它域名(COS 预签名等)保持原样;
+# 测试把本地假服务端的 host 加进来即可走同一段检查逻辑.
+CHECKED_HOSTS: set[str] = {_API_HOST}
+
+# OpenAPI 在响应头里回传的追踪 ID
+_TRACE_ID_HEADER: Final = "X-Tps-trace-ID"
+
+# 业务错误码字段: err_code 为通用字段, code 用于 /app/getAppAccessToken
+_ERROR_CODE_KEYS: Final = ("err_code", "code")
+
+# 错误体可能只含这些字段
+_ERROR_BODY_KEYS: Final = frozenset({"code", "err_code", "message", "trace_id"})
+
+# 官方说明 201/202 表示异步受理, 正常无响应体; 有错误体时按错误处理
+_ASYNC_STATUSES: Final = frozenset({201, 202})
+
+
+def _timeout_ms() -> int:
+    raw = os.getenv("TIMEOUT")
+    if not raw:
+        return DEFAULT_TIMEOUT_MS
+    try:
+        return int(raw)
+    except ValueError:
+        return DEFAULT_TIMEOUT_MS
+
+
+def _client_timeout() -> ClientTimeout:
+    return ClientTimeout(total=_timeout_ms() / 1000)
+
+
+def _is_checked_host(host: str | None) -> bool:
+    """该域名的响应是否走统一错误检查."""
+    return host is not None and host in CHECKED_HOSTS
+
+
+def _is_json_content_type(content_type: str) -> bool:
+    """content-type 是否为 JSON, 含 ``+json`` 后缀."""
+    mime = content_type.split(";", 1)[0].strip().lower()
+    return mime == "application/json" or mime.endswith("+json")
+
+
+def _as_int(value: object) -> int | None:
+    """把业务码规范成 int, 无法解析时返回 None."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        try:
+            return int(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _error_code(body: Mapping[str, Any]) -> int | None:
+    """返回 body 中的非零业务错误码, 无错误时返回 None."""
+    for key in _ERROR_CODE_KEYS:
+        raw = body.get(key)
+        if raw is None or isinstance(raw, bool):
+            continue
+        code = _as_int(raw)
+        if code is None:
+            # 字段存在但不是数字(例如字符串错误标识), 同样视为错误
+            if isinstance(raw, str) and raw.strip():
+                return 0
+            continue
+        if code != 0:
+            return code
+    return None
+
+
+def _message_of(body: Mapping[str, Any]) -> str:
+    """取服务端返回的错误描述."""
+    raw = body.get("message")
+    if raw is None:
+        return ""
+    return raw if isinstance(raw, str) else str(raw)
+
+
+def _trace_id_of(headers: Mapping[str, str], body: Mapping[str, Any]) -> str | None:
+    """取追踪 ID: 优先响应头, 回退到 body 的 trace_id."""
+    header = headers.get(_TRACE_ID_HEADER)
+    if header:
+        return header
+    raw = body.get("trace_id")
+    return raw if isinstance(raw, str) and raw else None
+
+
+def _looks_like_error_body(body: Mapping[str, Any]) -> bool:
+    """判断 201/202 的 body 是否只有错误字段."""
+    return "message" in body and set(body) <= _ERROR_BODY_KEYS
+
+
+def _as_dict(payload: object) -> dict[str, Any] | None:
+    """payload 为 dict 时返回带类型注解的视图, 否则返回 None."""
+    if isinstance(payload, dict):
+        return cast("dict[str, Any]", payload)
+    return None
+
+
+def _check_api_error(
+    body: Mapping[str, Any],
+    *,
+    status: int,
+    trace_id: str | None,
+) -> None:
+    """body 表示业务错误时抛 ``QQBotAPIError``."""
+    code = _error_code(body)
+    if code is not None:
+        raise QQBotAPIError(status, code, _message_of(body), trace_id)
+    if status in _ASYNC_STATUSES and _looks_like_error_body(body):
+        raise QQBotAPIError(status, 0, _message_of(body), trace_id)
+
+
+class QQBotResponse(ClientResponse):
+    """带统一错误检查的 ``ClientResponse``, 由 ``ClientSession(response_class=...)`` 注入.
+
+    只处理 ``CHECKED_HOSTS`` 里的域名, 其它域名(如 COS 预签名上传)走 aiohttp 原逻辑.
+    """
+
+    async def json(
+        self,
+        *,
+        encoding: str | None = None,
+        loads: JSONDecoder = DEFAULT_JSON_DECODER,
+        content_type: str | None = "application/json",
+    ) -> Any:
+        """解析响应体, 顺带做统一错误检查.
+
+        Args:
+            encoding: 显式指定编码, 缺省按 content-type 推导.
+            loads: JSON 解析函数, 默认 ``json.loads``.
+            content_type: 期望的 content-type, 传 None 跳过校验.
+
+        Raises:
+            QQBotAPIError: body 携带非零业务错误码, 或 201/202 只返回了错误体.
+        """
+        if not _is_checked_host(self.url.host):
+            return await super().json(
+                encoding=encoding,
+                loads=loads,
+                content_type=content_type,
+            )
+
+        # 只读取一次 body, 后续都复用 aiohttp 的缓存, 避免二次消费
+        raw = await self.read()
+        if not raw.strip():
+            return {}
+        if content_type and not _is_json_content_type(
+            self.headers.get("Content-Type", "")
+        ):
+            return {}
+
+        payload: Any = loads(raw.decode(encoding or self.get_encoding()))
+        body = _as_dict(payload)
+        if body is not None:
+            trace_id = _trace_id_of(self.headers, body)
+            _check_api_error(body, status=self.status, trace_id=trace_id)
+        return payload
+
+    def raise_for_status(self) -> None:
+        """HTTP 4xx/5xx 统一换成 ``QQBotAPIError``.
+
+        OpenAPI 域名下的状态码错误也归入同一异常体系, 调用方只需 ``except QQBotAPIError``;
+        其它域名(如 COS 预签名上传)保持 aiohttp 原行为.
+        """
+        if not _is_checked_host(self.url.host):
+            super().raise_for_status()
+            return
+        if self.status < 400:
+            return
+        reason = f"HTTP {self.status} {self.reason}".strip()
+        raise QQBotAPIError(
+            self.status,
+            0,
+            reason,
+            self.headers.get(_TRACE_ID_HEADER),
+        )
+
+
+def _retry_after_seconds(headers: Mapping[str, str]) -> float | None:
+    """从 ``Retry-After`` 响应头取等待秒数, 缺失或不是合法秒数时返回 None."""
+    raw = headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        seconds = float(raw.strip())
+    except ValueError:
+        # HTTP-date 形式不解析, 直接退回指数退避
+        return None
+    return seconds if seconds >= 0 else None
+
+
+def _retry_delay(attempt: int, headers: Mapping[str, str], *, waited: float) -> float:
+    """计算第 ``attempt`` 次(从 0 开始)重试前应等待的秒数.
+
+    优先使用 ``Retry-After``; 否则按 ``RETRY_BASE_SECONDS * 2 ** attempt`` 并叠加
+    抖动. 结果还要受 ``RETRY_TOTAL_WAIT_SECONDS`` 约束, 且不小于 0.
+    """
+    delay = _retry_after_seconds(headers)
+    if delay is None:
+        delay = RETRY_BASE_SECONDS * (2**attempt)
+        delay += delay * _RETRY_JITTER_RATIO * random.random()
+    return max(0.0, min(delay, RETRY_TOTAL_WAIT_SECONDS - waited))
+
+
+class _RetryingRequestContext:
+    """``async with session.get(...) as resp`` 的替身, 命中 HTTP 429 时自动重试.
+
+    429 表示服务端因限频**没有处理**该请求, 因此重发不会重复产生副作用, 即便
+    ``POST`` 也可以安全重试; 其它状态码(含 4xx/5xx 业务错误)一律不重试, 原样抛出.
+
+    会话级 ``raise_for_status`` 在这里统一关掉: 先自行判定 429, 其余交给
+    :meth:`QQBotResponse.raise_for_status` 抛 ``QQBotAPIError``, 调用方感知不到差异.
+    """
+
+    __slots__ = ("_label", "_request", "_response")
+
+    def __init__(
+        self,
+        request: Callable[[], Awaitable[ClientResponse]],
+        *,
+        label: str = "",
+    ) -> None:
+        self._request = request
+        self._label = label
+        self._response: ClientResponse | None = None
+
+    def __await__(self) -> Generator[Any, None, ClientResponse]:
+        """保留 ``resp = await session.get(...)`` 的旧写法, 等价于直接进入上下文."""
+        return self.__aenter__().__await__()
+
+    async def __aenter__(self) -> ClientResponse:
+        waited = 0.0
+        for attempt in range(MAX_RETRIES + 1):
+            response = await self._request()
+            if response.status == _TOO_MANY_REQUESTS and attempt < MAX_RETRIES:
+                delay = _retry_delay(attempt, response.headers, waited=waited)
+                waited += delay
+                logger.warning(
+                    f"请求被限频(429)，{delay:.2f} 秒后重试第 {attempt + 1} 次："
+                    f"{self._label}"
+                )
+                response.release()
+                await asyncio.sleep(delay)
+                continue
+            self._raise_for_status(response)
+            self._response = response
+            return response
+        raise RuntimeError("429 重试流程异常")
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        response = self._response
+        self._response = None
+        if response is not None:
+            response.release()
+
+    def _raise_for_status(self, response: ClientResponse) -> None:
+        """等价于 ``raise_for_status=True``: 非 2xx 抛错, 并释放连接避免泄漏."""
+        try:
+            response.raise_for_status()
+        except BaseException:
+            response.release()
+            raise
+
+
+async def _inject_authorization(
+    _session: ClientSession,
+    _ctx: object,
+    params: TraceRequestStartParams,
+) -> None:
+    """请求发出前注入鉴权头, aiohttp 会 await 协程形式的 trace 回调."""
+    if params.url.host != _API_HOST:
+        return
+    if params.url.path in _NO_AUTH_PATHS:
+        return
+    params.headers["Authorization"] = await get_authorization()
+
+
+def _build_trace_config() -> TraceConfig:
+    trace_config = TraceConfig()
+    trace_config.on_request_start.append(_inject_authorization)
+    return trace_config
+
+
+class QQBotSession:
+    """``aiohttp.ClientSession`` 的懒加载包装, 方法签名与 aiohttp 一致."""
+
+    __slots__ = ("_client",)
+
+    def __init__(self) -> None:
+        self._client: ClientSession | None = None
+
+    def _ensure(self) -> ClientSession:
+        if self._client is None or self._client.closed:
+            self._client = ClientSession(
+                base_url=BASE_URL,
+                raise_for_status=True,
+                timeout=_client_timeout(),
+                trace_configs=[_build_trace_config()],
+                response_class=QQBotResponse,
+            )
+        return self._client
+
+    def _request_context(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> _RetryingRequestContext:
+        """构造可重试的请求上下文, 统一关闭 aiohttp 的会话级 ``raise_for_status``.
+
+        业务函数照旧写 ``async with session.get(...) as resp``, 无需感知重试.
+        """
+
+        def send() -> Awaitable[ClientResponse]:
+            return self._ensure().request(
+                method,
+                url,
+                raise_for_status=False,
+                **kwargs,
+            )
+
+        # 日志标签去掉 query, 避免把 COS 预签名 URL 里的签名写进日志
+        return _RetryingRequestContext(send, label=f"{method} {url.split('?', 1)[0]}")
+
+    def get(self, url: str, **kwargs: Any) -> _RetryingRequestContext:
+        return self._request_context("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> _RetryingRequestContext:
+        return self._request_context("POST", url, **kwargs)
+
+    def put(self, url: str, **kwargs: Any) -> _RetryingRequestContext:
+        return self._request_context("PUT", url, **kwargs)
+
+    def patch(self, url: str, **kwargs: Any) -> _RetryingRequestContext:
+        return self._request_context("PATCH", url, **kwargs)
+
+    def delete(self, url: str, **kwargs: Any) -> _RetryingRequestContext:
+        return self._request_context("DELETE", url, **kwargs)
+
+    @property
+    def client(self) -> ClientSession:
+        """底层 aiohttp 会话, 供 WebSocket 等需要原生能力的场景使用."""
+        return self._ensure()
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> ClientResponse:
+        """返回已读取完成的响应, 便于需要自行处理状态码的场景."""
+        return await self._ensure().request(method, url, **kwargs)
+
+    @property
+    def closed(self) -> bool:
+        return self._client is None or self._client.closed
+
+    async def close(self) -> None:
+        if self._client is not None and not self._client.closed:
+            await self._client.close()
+        self._client = None
+
+    async def __aenter__(self) -> "QQBotSession":
+        self._ensure()
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()
+
+
+session = QQBotSession()
+
+__all__ = [
+    "BASE_URL",
+    "CHECKED_HOSTS",
+    "DEFAULT_TIMEOUT_MS",
+    "MAX_RETRIES",
+    "RETRY_BASE_SECONDS",
+    "RETRY_TOTAL_WAIT_SECONDS",
+    "QQBotResponse",
+    "QQBotSession",
+    "session",
+]

qqbotsdk/api/gateway.py

@@ -0,0 +1,43 @@
+"""网关地址获取.
+
+网关 WebSocket 地址由 ``GET /gateway`` 下发, 可能随服务端调度变化, 因此每次建立
+连接前实时获取, 不在代码里硬编码域名.
+"""
+
+from typing import Any, Final, cast
+
+from qqbotsdk.api.core import session
+from qqbotsdk.errors import QQBotGatewayError
+
+# 网关地址接口路径
+GATEWAY_PATH: Final = "/gateway"
+
+
+async def fetch_gateway_url() -> str:
+    """调用 ``GET /gateway`` 并返回其中的 ``url`` 字段.
+
+    鉴权请求头由 :mod:`qqbotsdk.api.core` 的会话自动注入, HTTP 错误由该会话的
+    ``raise_for_status`` 抛出, 这里不再包装.
+
+    Returns:
+        网关 WebSocket 地址, 例如 ``wss://api.sgroup.qq.com/websocket``.
+
+    Raises:
+        QQBotGatewayError: 响应体缺少可用的 ``url`` 字段.
+    """
+    async with session.get(GATEWAY_PATH) as resp:
+        raw = await resp.json()
+
+    if not isinstance(raw, dict):
+        raise QQBotGatewayError("网关响应缺少 url")
+    body = cast("dict[str, Any]", raw)
+    url = body.get("url")
+    if not isinstance(url, str) or not url:
+        raise QQBotGatewayError("网关响应缺少 url")
+    return url
+
+
+__all__ = [
+    "GATEWAY_PATH",
+    "fetch_gateway_url",
+]