mirror of
https://github.com/snowy-yang/qqbotsdk.git
synced 2026-10-21 11:54:48 +00:00
snowy-yang
4d19db24e1
协议分流后 reply_queue 只剩 WebsocketConnecter 一个使用者（emitter 不再 回流应答、webhook 完全不用），它已不是"连接层与分发层之间的通道"，而是 ws 私有的出站缓冲，却仍挂在共享 EventQueue 上——queue.py 的模块注释 "连接层与分发层之间唯一的跨任务通道"对 reply_queue 不再成立。 删除 EventQueue.reply_queue 与 put_reply/get_reply，EventQueue 只承载 业务事件（op=0，单向）。ws 的出站帧改由 WebsocketConnecter 私有 _outbound 队列承载，heartbeat_helper 与协议应答生产者投递、reply_helper 单任务发送——维持 aiohttp ws 单写者不变量，生产者也不会被发送阻塞。 破坏性变更：EventQueue.reply_queue / put_reply / get_reply 不再存在 （这两个方法本就只由 SDK 内部使用，非用户面）。 文档同步 queue.py 注释、ARCHITECTURE（图与心跳/应答路径）、API 的 EventQueue 说明、CHANGELOG；测试 80 全绿，ruff/pyright 干净。
242 lines
15 KiB
Markdown
242 lines
15 KiB
Markdown
# qqbotsdk API 参考
|
||
|
||
按公开使用面组织。上手流程见 [GUIDE.md](GUIDE.md)，分层与装配见 [ARCHITECTURE.md](ARCHITECTURE.md)。
|
||
|
||
## 顶层导出
|
||
|
||
```python
|
||
from qqbotsdk import (
|
||
main, run_loop, # 入口（组件在 run_loop 显式装配）
|
||
EventEmitter, EventQueue, # 分发层
|
||
BaseProtocol, # 协议处理器接口（自定义接入方式时继承）
|
||
Config, Connecter, # 配置与连接器接口
|
||
)
|
||
```
|
||
|
||
| 名称 | 说明 |
|
||
|---|---|
|
||
| `main(emitter=None)` | 同步入口：装配组件并阻塞运行，Ctrl+C 优雅退出 |
|
||
| `run_loop(emitter=None)` | 异步入口：`asyncio.run(run_loop(ee))` 的内部实现，可自行 await |
|
||
| `EventEmitter(queue=None)` | 分发主体，`@ee.on(..., background=True)` 注册 handler（可选后台并发）；`queue` 不传自动创建 |
|
||
| `ee.services` | `dict[type, Any]`，按类型登记可注入组件；`run_loop` 装配 SDK 内置组件，也可登记自定义类型 |
|
||
| `EventQueue()` | 业务事件通道（连接层 → 分发层，单向）；`EventEmitter` 默认自建，需多处共享时手动传入（`ee.queue` 取实例） |
|
||
| `Config` | frozen dataclass，环境变量一次性读齐（见下文） |
|
||
| `Connecter` | 连接适配器 Protocol（接口），按 `CONNECTER` 自动选择实现 |
|
||
| `BaseProtocol` | 协议处理器抽象基类（`protocol.py`），自定义接入方式时继承并实现 `on_frame(payload)` |
|
||
|
||
子包按需导入：
|
||
|
||
```python
|
||
from qqbotsdk.api import BotApi, ApiError
|
||
from qqbotsdk.payloads import GroupAtMessage, EVENT_TYPES, parse_event
|
||
from qqbotsdk.events import Event
|
||
```
|
||
|
||
## EventEmitter
|
||
|
||
```python
|
||
ee = EventEmitter()
|
||
|
||
@ee.on("GROUP_AT_MESSAGE_CREATE") # 业务事件用 t 名（仅 op=0 会分发到这里）
|
||
async def handler(...): ...
|
||
|
||
@ee.on("GROUP_AT_MESSAGE_CREATE", background=True) # 后台并发执行，不阻塞事件流
|
||
async def slow(...): ...
|
||
```
|
||
|
||
- **只分发业务事件**：`EventEmitter` 只处理 op=0（DISPATCH）事件，按 payload 的 `t` 名路由。协议帧（HELLO/READY/INVALID_SESSION/op=13 等）由各接入方式的协议处理器（`WebsocketProtocol`/`WebhookProtocol`）在连接器内就地处理，不进事件队列、也不会触达你的 handler。
|
||
- **异常隔离**：handler 异常就地记录（loguru），不影响同事件其他 handler 与主循环。
|
||
- **后台并发**：`background=True` 的 handler 进后台任务，emit 不等它；同一事件内失去先后保证，仅用于业务 handler。`run_loop` 退出时统一取消在飞后台任务（`ee.close()`）。
|
||
- 业务 handler 的返回值不回流；回复消息请在 handler 里显式调 `BotApi`。
|
||
|
||
### handler 参数注入约定
|
||
|
||
按参数类型标注解析，可任意混用：
|
||
|
||
| 标注 | 得到 | 未命中时 |
|
||
|---|---|---|
|
||
| payload dataclass（`payloads` 中的类型） | `Event.typed` 解析对象 | 回退传原始 d |
|
||
| `Event` | 事件封装对象 | — |
|
||
| 组件类型（`BotApi`/`Session`/`Config` 等已登记进 `ee.services` 的类型） | 登记的实例 | 回退传原始 d |
|
||
| 无标注 | 原始 d（业务事件即事件 dict；协议事件可能是标量，如 `INVALID_SESSION` 的 `resumable: bool`） | — |
|
||
|
||
## Event
|
||
|
||
`from qqbotsdk.events import Event`，一条 DISPATCH 事件的轻量封装，属性兼容群（openid）与频道两套字段名：
|
||
|
||
| 属性 | 说明 |
|
||
|---|---|
|
||
| `.raw` | 完整线上 payload（含 op/t/d） |
|
||
| `.data` | `d` 的 dict 拷贝 |
|
||
| `.typed` | `d` 的 dataclass 解析结果（未知事件类型为 dict） |
|
||
| `.type` | 事件 t 名 |
|
||
| `.user_id` | 用户标识（兼容 `user_id`/`from_user_id`） |
|
||
| `.group_id` | `group_openid` |
|
||
| `.content` | 消息文本 |
|
||
| `.message_id` | `d["id"]`，消息事件的被动回复凭据（msg_id） |
|
||
| `.event_id` | 推送信封顶层的事件 id（与 op/t/d 平级，形如 `INTERACTION_CREATE:uuid`）；非消息事件（`INTERACTION_CREATE`/`GROUP_ADD_ROBOT` 等）的被动回复凭据只有这里能拿到，事件体里的裸 UUID 不行（官方点名的常见坑） |
|
||
|
||
## Config
|
||
|
||
`Config.load()` 从环境变量一次性读齐（frozen，启动后不变）：
|
||
|
||
| 字段 | 环境变量 | 默认 | 说明 |
|
||
|---|---|---|---|
|
||
| `app_id` | `APPID` | 必填 | 缺失启动即 ValueError |
|
||
| `app_secret` | `APPSECRET` | 必填 | 同上 |
|
||
| `connecter` | `CONNECTER` | `websocket` | 仅允许 `websocket`/`webhook` |
|
||
| `base_url` | `BASE_URL` | `https://api.bot.qq.com` | 官方 API 根地址 |
|
||
| `timeout` | `TIMEOUT` | `5000`（毫秒） | 转为 aiohttp `ClientTimeout(total=…)` |
|
||
| `intents_file` | `INTENTS_FILE` | `intents.toml` | 事件订阅配置路径 |
|
||
| `webhook_host` | `WEBHOOK_HOST` | `0.0.0.0` | webhook 监听地址 |
|
||
| `webhook_port` | `WEBHOOK_PORT` | `8080` | webhook 监听端口 |
|
||
| `webhook_path` | `WEBHOOK_PATH` | `/qqbot/webhook` | webhook 回调路径 |
|
||
|
||
## BotApi
|
||
|
||
`from qqbotsdk.api import BotApi`。经参数注入（`api: BotApi`）。自动附带 `Authorization: QQBot <token>` 鉴权头并刷新 token；HTTP ≥400 抛 `ApiError`。
|
||
|
||
实现按域拆在 `qqbotsdk/api/` 包内（`core` 请求内核 + `v2`/`channel`/`guild` 方法集组合成 `BotApi`），方法名与下表一致；429 限流自动重试（最多 3 次，优先 `Retry-After`，退避封顶 30s），401 强制刷新 token 后重试一次。
|
||
|
||
### 通用
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| `request(method, path, **kwargs)` | 通用请求，kwargs 透传 aiohttp（`json=`/`params=` 等） |
|
||
| `get` / `post` / `delete` / `put` / `patch`(path, **kwargs) | `request` 快捷方式 |
|
||
| `me()` | 机器人自身信息（GET /users/@me） |
|
||
| `respond_interaction(interaction_id, code=0)` | 回应互动事件（PUT /interactions/{id}）；按钮点击（INTERACTION_CREATE type=11）收到后必须回应，否则客户端持续 loading，同一 id 仅可回应一次 |
|
||
|
||
常量：`MSG_TYPE_TEXT=0`、`MSG_TYPE_MARKDOWN=2`、`MSG_TYPE_MEDIA=7`；`FILE_TYPE_IMAGE=1`、`FILE_TYPE_VIDEO=2`、`FILE_TYPE_VOICE=3`、`FILE_TYPE_FILE=4`。
|
||
|
||
按钮构造：`button(label, data, *, type=1, permission=2, style=1)` 生成单个按钮 dict，`keyboard(*rows)` 组装为 `keyboard=` 参数（单按钮独占一行，按钮列表同行并排）。点击回调经 `INTERACTION_CREATE` 事件处理：`Interaction.button_data` 取被点按钮的 `data`，`Interaction.id` 用于 `respond_interaction`，**被动回复的 `event_id` 用 `Event.event_id`（网关帧最外层 id），不能用 `Interaction.id`**。
|
||
|
||
### v2 群聊（群 openid）
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|---|---|---|
|
||
| `post_group_message(group_openid, content="", msg_id=None, msg_seq=1, media=None, event_id=None, markdown=None, keyboard=None, **extra)` | POST /v2/groups/{group_openid}/messages | `msg_id`/`event_id` 二选一即被动回复（`event_id` 支持 GROUP_ADD_ROBOT / INTERACTION_CREATE 等事件）；`media` 传上传返回的 `{"file_info": …}`（自动 msg_type=7）；`markdown` 为字符串或完整 dict（自动 msg_type=2，与 content 互斥）；`keyboard` 为内嵌键盘 `{"content": {"rows": [...]}}` 或 `{"id": …}`；其余字段经 `extra` 透传 |
|
||
| `upload_group_file(group_openid, file_type, url, srv_send_msg=False)` | POST /v2/groups/{group_openid}/files | 富媒体上传，返回含 `file_info`；`srv_send_msg=True` 上传即发送 |
|
||
| `withdraw_group_message(group_openid, message_id)` | DELETE /v2/groups/{group_openid}/messages/{message_id} | 发出 2 分钟内可撤回 |
|
||
| `mute_group_member(group_openid, mute_expire_at)` | POST /v2/groups/{group_openid}/restrict_chat_setting | `mute_expire_at` 为 RFC3339 到期时间；传早于当前的时间即解禁 |
|
||
|
||
### v2 单聊（用户 openid）
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|---|---|---|
|
||
| `post_c2c_message(openid, content="", msg_id=None, msg_seq=1, media=None, event_id=None, markdown=None, keyboard=None, **extra)` | POST /v2/users/{openid}/messages | 同 `post_group_message` |
|
||
| `upload_c2c_file(openid, file_type, url, srv_send_msg=False)` | POST /v2/users/{openid}/files | 同 `upload_group_file` |
|
||
| `withdraw_c2c_message(openid, message_id)` | DELETE /v2/users/{openid}/messages/{message_id} | 2 分钟内可撤回 |
|
||
|
||
### 频道消息（channel_id / guild_id）
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|---|---|---|
|
||
| `post_channel_message(channel_id, content="", msg_id=None, msg_seq=1, image=None, **extra)` | POST /channels/{channel_id}/messages | `image` 为图片 URL；embed/ark/markdown 等经 `extra` 透传 |
|
||
| `withdraw_channel_message(channel_id, message_id, hide_tip=False)` | DELETE /channels/{channel_id}/messages/{message_id} | **仅私域机器人**；`hide_tip` 对应官方 `hidetip` |
|
||
| `put_channel_reaction(channel_id, message_id, emoji_type, emoji_id)` | PUT …/reactions/{type}/{emoji_id} | `emoji_type=1` 系统表情，`emoji_id` 为序号字符串 |
|
||
| `delete_channel_reaction(channel_id, message_id, emoji_type, emoji_id)` | DELETE …/reactions/{type}/{emoji_id} | 删除自己的表态 |
|
||
|
||
### 频道管理
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|---|---|---|
|
||
| `create_guild_announce(guild_id, channel_id, message_id, announces_type=0, **extra)` | POST /guilds/{guild_id}/announces | `announces_type`：0 成员公告 / 1 欢迎公告；推荐频道公告经 extra（与消息公告互斥） |
|
||
| `delete_guild_announce(guild_id, message_id)` | DELETE /guilds/{guild_id}/announces/{message_id} | 推荐频道公告传 `message_id="all"` |
|
||
| `pin_channel_message(channel_id, message_id)` | PUT /channels/{channel_id}/pins/{message_id} | 添加精华消息 |
|
||
| `unpin_channel_message(channel_id, message_id)` | DELETE /channels/{channel_id}/pins/{message_id} | 移出精华消息 |
|
||
| `get_channel_pins(channel_id)` | GET /channels/{channel_id}/pins | 精华消息列表 |
|
||
| `get_channel_schedules(channel_id, since=None)` | GET /channels/{channel_id}/schedules | 默认当天日程；`since` 毫秒时间戳 |
|
||
| `get_channel_schedule(channel_id, schedule_id)` | GET /channels/{channel_id}/schedules/{schedule_id} | 单个日程 |
|
||
| `create_channel_schedule(channel_id, name, start_timestamp, end_timestamp, jump_channel_id, remind_type="0", description="")` | POST /channels/{channel_id}/schedules | 时间为毫秒时间戳字符串；`remind_type` "0" 不提醒 / "1" 开始时；请求体自动包在 `schedule` 字段；单管理员每天限 10 次 |
|
||
| `update_channel_schedule(channel_id, schedule_id, **fields)` | PATCH /channels/{channel_id}/schedules/{schedule_id} | `fields` 为 schedule 内字段透传 |
|
||
| `delete_channel_schedule(channel_id, schedule_id)` | DELETE /channels/{channel_id}/schedules/{schedule_id} | 删除日程 |
|
||
| `mute_guild_member(guild_id, user_id, mute_seconds=0)` | PATCH /guilds/{guild_id}/members/{user_id}/mute | 禁言秒数（上限 28 天），0 解禁 |
|
||
|
||
### 频道查询
|
||
|
||
| 方法 | 端点 |
|
||
|---|---|
|
||
| `get_guild(guild_id)` | GET /guilds/{guild_id} |
|
||
| `get_guild_channels(guild_id)` | GET /channels/{guild_id}/channels |
|
||
| `get_channel(channel_id)` | GET /channels/{channel_id} |
|
||
| `get_guild_roles(guild_id)` | GET /guilds/{guild_id}/roles |
|
||
| `get_guild_member(guild_id, user_id)` | GET /guilds/{guild_id}/members/{user_id} |
|
||
|
||
### ApiError
|
||
|
||
`ApiError(RuntimeError)`，重试后仍失败（HTTP ≥400）时抛出：
|
||
|
||
| 属性 | 说明 |
|
||
|---|---|
|
||
| `.status` | HTTP 状态码 |
|
||
| `.code` | 官方业务 code（响应体中的 `code`） |
|
||
| `.message` | 官方错误描述 |
|
||
|
||
鉴权阶段（换取 access_token）的失败抛 `TokenError`（`from qqbotsdk.token import TokenError`），与 `ApiError` 同构（`RuntimeError` 子类，同样携带 `.status`/`.code`/`.message`）——appid/secret 配置错误在这里暴露 QQ 返回的真实原因。
|
||
|
||
## 事件 payload
|
||
|
||
`qqbotsdk.payloads` 定义事件 `d` 的 dataclass。handler 标注类型即得解析对象；未知事件类型回退原始 dict。所有字段均可为 None（线上缺省即 None），嵌套 `author` 自动解析为 `Author`。
|
||
|
||
### 事件名 → dataclass 对照
|
||
|
||
下表左列是 intents.toml 的订阅分组（订阅粒度即分组，组内事件无法单独开关），中列是同时属于该分组、会被一起推送的事件 `t` 名：
|
||
|
||
| intents 分组 | 事件 t 名 | dataclass |
|
||
|---|---|---|
|
||
| GROUP_AND_C2C_EVENT | `C2C_MESSAGE_CREATE` | `C2CMessage` |
|
||
| | `GROUP_AT_MESSAGE_CREATE` / `GROUP_MESSAGE_CREATE` | `GroupAtMessage` |
|
||
| | `FRIEND_ADD` / `FRIEND_DEL` | `FriendAdd` / `FriendDel` |
|
||
| | `GROUP_ADD_ROBOT` / `GROUP_DEL_ROBOT` | `GroupAddRobot` / `GroupDelRobot` |
|
||
| | `C2C_MSG_REJECT` / `C2C_MSG_RECEIVE` | `C2CMsgReject` / `C2CMsgReceive` |
|
||
| | `GROUP_MSG_REJECT` / `GROUP_MSG_RECEIVE` | `GroupMsgReject` / `GroupMsgReceive` |
|
||
| PUBLIC_GUILD_MESSAGES | `AT_MESSAGE_CREATE` | `AtMessage` |
|
||
| | `PUBLIC_MESSAGE_DELETE` | `MessageDelete` |
|
||
| GUILD_MESSAGES（私域） | `MESSAGE_DELETE` | `MessageDelete` |
|
||
| DIRECT_MESSAGE | `DIRECT_MESSAGE_CREATE` | `DirectMessage` |
|
||
| GUILDS | `GUILD_CREATE` / `GUILD_UPDATE` / `GUILD_DELETE` | `Guild` |
|
||
| | `CHANNEL_CREATE` / `CHANNEL_UPDATE` / `CHANNEL_DELETE` | `Channel` |
|
||
| GUILD_MESSAGE_REACTIONS | `MESSAGE_REACTION_ADD` / `…_REMOVE` | `MessageReaction` |
|
||
| MESSAGE_AUDIT | `MESSAGE_AUDIT_PASS` / `…_REJECT` | `MessageAudit` |
|
||
| INTERACTION | `INTERACTION_CREATE` | `Interaction` |
|
||
| FORUMS_EVENT（私域） | `FORUM_THREAD_CREATE` / `…_UPDATE` / `…_DELETE` | `ForumThread` |
|
||
| | `FORUM_POST_CREATE` / `…_DELETE` | `ForumPost` |
|
||
| | `FORUM_REPLY_CREATE` / `…_DELETE` | `ForumReply` |
|
||
| AUDIO_ACTION | `AUDIO_START` / `AUDIO_FINISH` / `AUDIO_ON_MIC` / `AUDIO_OFF_MIC` | `AudioAction` |
|
||
| —（DISPATCH 协议事件） | `READY` | `Ready` |
|
||
|
||
未收录的事件（如私域 `MESSAGE_CREATE`、`DIRECT_MESSAGE_DELETE`、`GUILD_MEMBER_*`）handler 收到原始 dict；新增事件在 `payloads.py` 加 dataclass 并登记 `EVENT_TYPES` 即可。
|
||
|
||
`GROUP_MESSAGE_CREATE` 是群消息**全量模式**：需在开放平台开通"接收所有消息"权限，群里每条消息（不限 @机器人）都推送此事件，与 `GROUP_AT_MESSAGE_CREATE` 共用 `GroupAtMessage`。官方提示同一 msg_id 可能重复推送，业务侧需按 `id` 去重。
|
||
|
||
### 常用 dataclass 字段
|
||
|
||
```python
|
||
Author # id, user_openid, member_openid, username, bot
|
||
GroupAtMessage # id, content, group_openid, author, timestamp,
|
||
# message_type, message_scene, attachments, mentions, ark_data, msg_elements
|
||
C2CMessage # id, content, author, attachments, timestamp
|
||
AtMessage # id, content, channel_id, guild_id, author, member, timestamp
|
||
DirectMessage # 同 AtMessage
|
||
```
|
||
|
||
- `GroupAtMessage.user_openid` / `C2CMessage.user_openid`：便利属性，从 `author.member_openid`/`author.user_openid` 取发言人标识。
|
||
- 群/单聊场景拿不到用户真实 QQ 号，只有 openid；频道场景 `Author.id`/`username` 有效。
|
||
- 其余事件 dataclass 为 2~5 个平铺字段的同构结构（openid/时间戳/信息 dict），字段名即官方文档字段。
|
||
|
||
`parse_event(t, d)`：把事件 `d` 解析为对应 dataclass（`Event.typed` 的内部实现），`EVENT_TYPES` 为事件名 → 类的完整登记表。
|
||
|
||
## 内部模块索引
|
||
|
||
维护者视角的分层与装配见 [ARCHITECTURE.md](ARCHITECTURE.md)：
|
||
|
||
| 模块 | 职责 |
|
||
|---|---|
|
||
| `connecter.py` | `WebsocketConnecter` / `WebhookConnecter`：接入归一为事件流入、reply 流出 |
|
||
| `ws_protocol.py` | IDENTIFY/RESUME 鉴权、apscheduler 心跳、会话序列号 |
|
||
| `webhook_protocol.py` | op=13 验证应答 |
|
||
| `queue.py` / `session.py` / `token.py` / `crypto.py` | 队列、ws 会话状态、token 缓存、Ed25519 签名 |
|
||
| `model.py` | Opcode、payload 类型、Intent 位掩码 |
|
||
| `__init__.py` | `main`/`run_loop` 入口与组件显式装配 |
|