mirror of
https://github.com/snowy-yang/qqbotsdk.git
synced 2026-10-21 11:54:48 +00:00
snowy-yang
71cbfdaf5d
破坏性变更：intents.toml 订阅粒度收敛到 Intents 大类（分组）—— 配置从「[分组] 表内逐事件开关」改为「分组名 = true/false」。网关只接受 分组位掩码，组内事件本就无法单独订阅，此前的逐事件开关仅是「组内任一 为 true 即订阅整组」的装饰。旧格式不再兼容，与拼错的分组名、非布尔值 一样在启动时直接抛 ValueError，而非静默少订阅。 新增： - GROUP_MESSAGE_CREATE 事件接收（群消息全量模式，与 GROUP_AT_MESSAGE_CREATE 共用 GroupAtMessage）；GroupAtMessage 补齐 message_type/message_scene/ attachments/mentions/ark_data/msg_elements 字段 优化： - 形参注入缓存化：合并缓存 handler 签名与类型标注解析（此前每条事件都重跑 inspect.signature/get_type_hints），services 命中改为每条事件实时判定， 保证「先注册 handler、后登记组件」的既有装配顺序不受影响 - EventQueue.put_event/put_reply 去掉多余的 return await - model.NoneType 联合成员顺序调整（None 置于末尾） 文档同步 GUIDE/API/README/CHANGELOG 与示例；测试 76 全绿，ruff/pyright 干净。
示例
可运行的完整示例，均以仓库根目录为工作目录启动（.env、intents.toml 放在根目录）。
| 示例 | 接入方式 | 内容 |
|---|---|---|
group_bot/main.py |
WebSocket | @消息被动回复、/img 富媒体图片、/btn Markdown 按钮卡片与点击回调、入群欢迎、单聊回复 |
webhook_bot/main.py |
Webhook | HTTP 回调收群 @消息并被动回复的最小接入 |
运行前提
- 根目录
.env配好APPID/APPSECRET（webhook_bot需另设CONNECTER=webhook）； intents.toml订阅对应分组（group_bot需GROUP_AND_C2C_EVENT与INTERACTION，webhook_bot需GROUP_AND_C2C_EVENT；仓库默认配置已满足两者）；group_bot要求机器人已开通群聊能力并拉入测试群；webhook_bot要求公网 HTTPS 部署（平台仅支持 80/443/8080/8443 端口，本地调试可用内网穿透）。
运行
uv run python examples/group_bot/main.py
uv run python examples/webhook_bot/main.py
Webhook 示例启动后，把 https://<你的域名>:<端口>/qqbot/webhook 填到开放平台回调地址；保存时平台先发 op=13 验证请求，SDK 自动完成签名应答。
接入方式切换与 handler 写法详见 使用指南。