0 Fork 0

mirror of https://github.com/snowy-yang/qqbotsdk.git synced 2026-10-21 09:56:17 +00:00

Files

T

snowy-yang 7e8794bf5f feat: intents 掩码直传——Bot(intents=) 参数与 INTENTS 环境变量，优先于 intents.toml

Intent 枚举（IntFlag）提升到顶层导出可直接 OR；掩码含未收录位仅告警不拦截。

2026-10-03 20:07:56 +08:00

4.8 KiB

Raw Permalink Blame History

配置与订阅

.env 环境变量、intents.toml 事件订阅与接入方式选择。完整字段参考只在本文。

.env 配置

SDK 启动时自动加载项目根目录的 .env，APPID/APPSECRET 缺失启动即报错：

APPID=你的AppID
APPSECRET=你的AppSecret
CONNECTER=websocket               # websocket 或 webhook，默认 websocket

BASE_URL=https://api.bot.qq.com   # 可选，官方 API 地址
TIMEOUT=5000                      # 可选，HTTP 请求超时（毫秒）
INTENTS_FILE=intents.toml         # 可选，事件订阅配置文件路径
INTENTS=                          # 可选，订阅掩码直传（十进制或 0x 十六进制），优先于 intents.toml

WEBHOOK_HOST=0.0.0.0              # 以下仅 webhook 接入时生效
WEBHOOK_PORT=8080
WEBHOOK_PATH=/qqbot/webhook

字段	环境变量	默认	说明
`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`	事件订阅配置路径
`intents`	`INTENTS`	空	订阅掩码直传，见掩码直传
`webhook_host`	`WEBHOOK_HOST`	`0.0.0.0`	webhook 监听地址
`webhook_port`	`WEBHOOK_PORT`	`8080`	webhook 监听端口
`webhook_path`	`WEBHOOK_PATH`	`/qqbot/webhook`	webhook 回调路径

Config 是 frozen dataclass，Bot() 构造时一次性读齐；handler 可标注 config: Config 注入。

事件订阅（intents.toml）

SDK 启动时读取 intents.toml 计算订阅掩码。订阅粒度就是下面表格里的大类（Intents 分组），把某组设为 true 即订阅该组下的全部事件：

GROUP_AND_C2C_EVENT = true   # 群/单聊消息与关注事件
INTERACTION = true           # 互动事件（卡片按钮回调）
GUILDS = false               # 频道/子频道增删改

QQ 网关只认分组位掩码，组内单个事件无法单独开关——能收到哪些事件由订阅了哪些分组决定（各组包含哪些事件见事件 payload 对照）。分组与特权要求：

分组	位掩码	说明
`GUILDS`	1 << 0	频道/子频道增删改
`GUILD_MEMBERS`	1 << 1	成员增删改
`GUILD_MESSAGES`	1 << 9	频道全量消息，仅私域机器人
`GUILD_MESSAGE_REACTIONS`	1 << 10	频道表情表态
`DIRECT_MESSAGE`	1 << 12	频道私信
`GROUP_AND_C2C_EVENT`	1 << 25	群/单聊消息与关注事件（群机器人核心）
`INTERACTION`	1 << 26	互动事件
`MESSAGE_AUDIT`	1 << 27	消息审核结果
`FORUMS_EVENT`	1 << 28	论坛事件，仅私域机器人
`AUDIO_ACTION`	1 << 29	音频播放/上麦下麦
`PUBLIC_GUILD_MESSAGES`	1 << 30	频道公域消息（AT_MESSAGE_CREATE）

分组名即 Intent 枚举成员名。配置只接受 分组名 = true/false；拼错的分组名、非布尔值，以及旧版"表内逐事件开关"的写法都会在启动时直接抛 ValueError（与其静默少订阅，不如启动即报错）。文件缺失则告警并按不订阅任何事件启动。

掩码直传

不想用配置文件的，可以直接传订阅掩码，三种入口按优先级取先命中者：

Bot 参数（推荐写法，Intent 是 IntFlag 可直接 OR）：

from qqbotsdk import Bot, Intent

bot = Bot(intents=Intent.GROUP_AND_C2C_EVENT | Intent.INTERACTION)

INTENTS 环境变量：十进制或 0x 十六进制字符串，如 INTENTS=1073741824 或 INTENTS=0x40000000；
都没给才回落 intents.toml。

掩码原样下发给网关，含 Intent 枚举未收录的位时仅告警不拦截（平台可能新增 SDK 尚未收录的分组）。Intent 从包顶层导出（from qqbotsdk import Intent），各位值见上面的分组表。

接入方式选择

	WebSocket	Webhook
网络要求	能访问外网即可，本地开发友好	需公网可达 + HTTPS，仅支持 80/443/8080/8443 端口
配置	无额外配置	平台回调地址填 `https://<域名>:<端口><WEBHOOK_PATH>`
连接维护	SDK 自动心跳、断线指数退避重连并 RESUME 续传；服务端约 1 小时会断开连接，SDK 会在临到期前（约 50 分钟）主动重连续传	SDK 处理 Ed25519 验签、op=13 验证应答、60s TTL 事件去重
适用	长驻进程、需要会话与重连保障	无状态部署、回调型服务

两种方式下 handler 的写法完全一致，切换只需改 CONNECTER。

4.8 KiB Raw Permalink Blame History Unescape Escape