infinity-qqbot 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. infinity_qqbot-0.1.0/LICENSE.md +21 -0
  2. infinity_qqbot-0.1.0/PKG-INFO +300 -0
  3. infinity_qqbot-0.1.0/README.md +264 -0
  4. infinity_qqbot-0.1.0/pyproject.toml +134 -0
  5. infinity_qqbot-0.1.0/pyproject.toml.orig +122 -0
  6. infinity_qqbot-0.1.0/src/infinity_qqbot/__init__.py +78 -0
  7. infinity_qqbot-0.1.0/src/infinity_qqbot/api.py +1625 -0
  8. infinity_qqbot-0.1.0/src/infinity_qqbot/engine.py +98 -0
  9. infinity_qqbot-0.1.0/src/infinity_qqbot/events.py +973 -0
  10. infinity_qqbot-0.1.0/src/infinity_qqbot/gateway.py +337 -0
  11. infinity_qqbot-0.1.0/src/infinity_qqbot/handlers.py +281 -0
  12. infinity_qqbot-0.1.0/src/infinity_qqbot/models/__init__.py +146 -0
  13. infinity_qqbot-0.1.0/src/infinity_qqbot/models/base.py +13 -0
  14. infinity_qqbot-0.1.0/src/infinity_qqbot/models/common.py +94 -0
  15. infinity_qqbot-0.1.0/src/infinity_qqbot/models/enums.py +97 -0
  16. infinity_qqbot-0.1.0/src/infinity_qqbot/models/group.py +190 -0
  17. infinity_qqbot-0.1.0/src/infinity_qqbot/models/interaction.py +49 -0
  18. infinity_qqbot-0.1.0/src/infinity_qqbot/models/menu.py +105 -0
  19. infinity_qqbot-0.1.0/src/infinity_qqbot/models/message.py +204 -0
  20. infinity_qqbot-0.1.0/src/infinity_qqbot/models/payloads.py +253 -0
  21. infinity_qqbot-0.1.0/src/infinity_qqbot/models/responses.py +309 -0
  22. infinity_qqbot-0.1.0/src/infinity_qqbot/py.typed +0 -0
  23. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/__init__.py +27 -0
  24. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/channels.py +3887 -0
  25. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/groups.py +1204 -0
  26. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/handlers/__init__.py +40 -0
  27. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/handlers/channels.py +1019 -0
  28. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/handlers/groups.py +325 -0
  29. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/handlers/interactions.py +224 -0
  30. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/handlers/messages.py +268 -0
  31. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/interactions.py +820 -0
  32. infinity_qqbot-0.1.0/src/infinity_qqbot/rpc/messages.py +930 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 InfinitySystem (yin_bailiang)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,300 @@
1
+ Metadata-Version: 2.4
2
+ Name: infinity-qqbot
3
+ Version: 0.1.0
4
+ Summary: 基于 infinity_bus 事件总线的强类型 QQ 机器人引擎(aiohttp 网关 + 强类型 RPC)
5
+ Keywords: qq,qqbot,qq-bot,chatbot,event-bus,asyncio,websocket,pydantic
6
+ Author: infinity_system: yin_bailiang
7
+ License-Expression: MIT
8
+ License-File: LICENSE.md
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Framework :: AsyncIO
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Topic :: Communications :: Chat
17
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
+ Classifier: Typing :: Typed
19
+ Requires-Dist: aiohttp>=3.14.4
20
+ Requires-Dist: certifi>=2026.7.22
21
+ Requires-Dist: infinity-bus[templates]>=6.0.0
22
+ Requires-Dist: infinity-parse>=0.1.2
23
+ Requires-Dist: infinity-agent-kit>=1.0.0 ; extra == 'dev'
24
+ Requires-Dist: interrogate ; extra == 'dev'
25
+ Requires-Dist: pre-commit ; extra == 'dev'
26
+ Requires-Dist: pyright ; extra == 'dev'
27
+ Requires-Dist: ruff ; extra == 'dev'
28
+ Maintainer: yin_bailiang
29
+ Requires-Python: >=3.14
30
+ Project-URL: Homepage, https://github.com/yinbailiang/infinity_qqbot
31
+ Project-URL: Repository, https://github.com/yinbailiang/infinity_qqbot
32
+ Project-URL: Issues, https://github.com/yinbailiang/infinity_qqbot/issues
33
+ Project-URL: Changelog, https://github.com/yinbailiang/infinity_qqbot/releases
34
+ Provides-Extra: dev
35
+ Description-Content-Type: text/markdown
36
+
37
+ # infinity-qqbot
38
+
39
+ 基于 [infinity_bus](https://github.com/yinbailiang/infinity_bus) 的 QQ 机器人引擎。
40
+
41
+ - **`QQBotAPI`**:使用 `aiohttp` + `certifi` 完整封装 QQ 机器人开放平台 v2 接口
42
+ (消息收发、富媒体上传、群管理、频道管理(子频道权限、禁言、论坛、音频等)、
43
+ 互动回调、菜单面板等;HTTP 429 自动退避重试、201/202 异步受理语义);
44
+ - **`QQBotGateway` / `QQBot`**:WebSocket 网关客户端(心跳、Identify/Resume、
45
+ 自动重连、断线补发),输出类型化事件流;
46
+ - **`QQBotEventHandler`**:接受 `QQBotAPI`,随总线激活自动连接网关,
47
+ 并把每个事件自动发布为 `qqbot.event.<type>`(如 `qqbot.event.group_at_message_create`);
48
+ - **`QQBotAPIHandler` + 强类型客户端**:集成 `ServiceHandler`,95 个 API 方法逐一暴露为
49
+ 总线 RPC(请求 / 响应模型、事件声明、客户端函数由 `tools/gen_rpc.py` 从规格生成,
50
+ 运行期零元编程),调用 `await send_c2c_message(...)` 即完成一次强类型 RPC;
51
+ - 数据模型按域拆分在 `models/` 包;事件声明采用嵌套 `Payload` 风格,全部由 Pydantic 校验。
52
+
53
+ ## 安装
54
+
55
+ ```bash
56
+ uv sync
57
+ ```
58
+
59
+ ## 快速开始
60
+
61
+ ```python
62
+ import asyncio
63
+
64
+ from infinity_bus import EventBus, EventHandler, EventHandlerRegistry, EventRegistry, Regex
65
+
66
+ from infinity_qqbot import (
67
+ QQBotAPI,
68
+ qqbot_events,
69
+ register_handlers,
70
+ send_c2c_message,
71
+ )
72
+
73
+
74
+ class Echo(EventHandler):
75
+ """订阅单聊消息,通过总线 RPC 回复。"""
76
+
77
+ def __init__(self) -> None:
78
+ super().__init__(subscriptions=[Regex(r'qqbot\.event\.c2c_message_create')])
79
+
80
+ async def handle(self, payload, bus_proxy, raw_event) -> None:
81
+ await send_c2c_message(
82
+ bus_proxy,
83
+ user_openid=payload.user_openid,
84
+ content=f'收到:{payload.content}',
85
+ msg_id=payload.id, # 被动回复(也可使用 event_id)
86
+ )
87
+
88
+
89
+ async def main() -> None:
90
+ api = QQBotAPI('你的AppID', '你的AppSecret')
91
+
92
+ registry = EventRegistry()
93
+ qqbot_events.register_all_events(registry) # 注册全部事件声明(ModuleEventRegister)
94
+
95
+ handlers = EventHandlerRegistry()
96
+ await handlers.register(Echo())
97
+ await register_handlers(handlers, api) # 入站:网关事件 -> 总线;出站:总线 RPC -> OpenAPI
98
+
99
+ async with EventBus(registry, handlers):
100
+ await asyncio.Event().wait() # 常驻运行
101
+
102
+
103
+ asyncio.run(main())
104
+ ```
105
+
106
+ ## 事件订阅
107
+
108
+ 总线事件名 = `qqbot.event.` + 平台事件名小写,例如:
109
+
110
+ | 平台事件 | 总线事件 | 声明类 |
111
+ | - | - | - |
112
+ | `C2C_MESSAGE_CREATE` | `qqbot.event.c2c_message_create` | `C2CMessageCreateEvent` |
113
+ | `GROUP_AT_MESSAGE_CREATE` | `qqbot.event.group_at_message_create` | `GroupAtMessageCreateEvent` |
114
+ | `AT_MESSAGE_CREATE` | `qqbot.event.at_message_create` | `MessageCreateEvent` 系列 |
115
+ | `INTERACTION_CREATE` | `qqbot.event.interaction_create` | `InteractionCreateEvent` |
116
+ | `GROUP_ADD_ROBOT` | `qqbot.event.group_add_robot` | `GroupAddRobotEvent` |
117
+ | …(共 58 个平台事件) | | |
118
+
119
+ 订阅方式二选一:
120
+
121
+ - 精确订阅:`super().__init__(subscriptions=['qqbot.event.c2c_message_create'])`;
122
+ - 通配订阅:`super().__init__(subscriptions=[Regex(r'qqbot\.event\..*')])`。
123
+
124
+ 未建模的新事件会被兜底发布到 `qqbot.event.unknown`(负载含 `type` 与原始 `data`),
125
+ 不会导致引擎崩溃。
126
+
127
+ 事件声明在定义时由 `ModuleEventRegister` 自动收集(`infinity_qqbot.qqbot_events`),
128
+ 注册时直接调用 `qqbot_events.register_all_events(registry)`,新增声明无需手工维护清单。
129
+
130
+ ## 强类型 RPC 调用 API
131
+
132
+ 每个 API 方法都有生成的**请求模型、响应模型、事件声明与强类型客户端**
133
+ (`tools/gen_rpc.py` 从方法规格生成,纯显式代码、运行期零元编程):
134
+
135
+ ```python
136
+ from infinity_qqbot import send_group_message
137
+
138
+ message = await send_group_message(
139
+ bus_proxy,
140
+ group_openid=group_openid,
141
+ content='hello',
142
+ msg_id=message_id, # 被动回复(也可使用 event_id)
143
+ )
144
+ print(message.id) # MessageResponse(类型由客户端签名给出)
145
+ ```
146
+
147
+ - 客户端底层**直接使用** `infinity_bus.templates.request` 模板,自动以
148
+ `session_id + request_id` 关联请求与响应;
149
+ - 事件名:`qqbot.api.<method>.request` / `qqbot.api.<method>.response`,
150
+ 可直接订阅任意方法的请求 / 响应事件;
151
+ - 请求 / 响应模型**直接继承**库的 `RequestProtocol` / `ResponseProtocol`;
152
+ - 失败时抛出 `QQBotAPIError`(`error_msg` 含平台错误码,跨总线保留);
153
+ - 需要修改 / 新增方法时,编辑 `tools/gen_rpc.py` 中的规格并重新生成:
154
+
155
+ ```bash
156
+ uv run python tools/gen_rpc.py
157
+ uv run ruff check --fix src
158
+ ```
159
+
160
+ 链路:客户端 → `request()` 模板 → `qqbot.api.<method>.request`
161
+ → `QQBotAPIHandler.<method>` → `QQBotAPI.<method>` → `qqbot.api.<method>.response`。
162
+
163
+ ## 模板能力(infinity_bus.templates)
164
+
165
+ 本项目尽可能复用了 `infinity_bus` 的模板能力,业务侧也可直接使用:
166
+
167
+ - **批量处理器注册**:`await register_handlers(handlers, api)` 基于 `ModuleHandlerRegister`
168
+ 一次性注册入站 / 出站处理器;
169
+ - **幂等去重**:QQ 可能重复推送同一事件,注入 `IdempotencyRecorder` 即可按事件 ID 去重
170
+ (发布成功才记录):
171
+
172
+ ```python
173
+ from infinity_bus.templates import InMemoryIdempotencyRecorder
174
+
175
+ from infinity_qqbot import register_handlers
176
+
177
+ await register_handlers(
178
+ handlers,
179
+ api,
180
+ dedup_recorder=InMemoryIdempotencyRecorder(), # 或 SqliteIdempotencyRecorder('bot.db')
181
+ )
182
+ ```
183
+
184
+ - **等待事件**:`wait_for_event()` 基于 `expect` 模板注册一次性监听:
185
+
186
+ ```python
187
+ from infinity_qqbot import ReadyEvent, wait_for_event
188
+
189
+ await wait_for_event(bus.proxy('app'), ReadyEvent.name, timeout=30)
190
+ ```
191
+
192
+ - **中间件**:`infinity_bus.templates.middlewares` 提供的日志(JSONL / SQLite)、限流、
193
+ 递归防护、事件转换等中间件可直接挂到总线:
194
+
195
+ ```python
196
+ from infinity_bus.templates import RecursionGuardMiddleware
197
+
198
+ await bus.proxy('app').middleware.add(RecursionGuardMiddleware())
199
+ ```
200
+
201
+ - **简化处理器**:`infinity_bus.templates.handler` 可把普通异步函数直接包装为处理器类:
202
+
203
+ ```python
204
+ from infinity_bus.templates import handler
205
+
206
+ @handler(C2CMessageCreateEvent)
207
+ async def echo(payload: C2CMessageCreateEvent.Payload) -> None:
208
+ ...
209
+
210
+ await handlers.register(echo())
211
+ ```
212
+
213
+ - **其他模板**:`expect` / `temporary_handler` / `pipe` / `request` 等均可按需组合
214
+ (本库的 RPC 客户端直接使用 `request` 模板,`wait_for_event` 使用 `expect`)。
215
+
216
+ ## 独立使用引擎(不经总线)
217
+
218
+ ```python
219
+ from infinity_qqbot import QQBot, QQBotAPI
220
+
221
+ async with QQBot(QQBotAPI(app_id, secret)) as bot:
222
+ async for event in bot.stream():
223
+ print(event.type, event.payload)
224
+ ```
225
+
226
+ ## API 覆盖范围
227
+
228
+ | 分类 | 代表接口 |
229
+ | - | - |
230
+ | 凭证 / 网关 | `get_access_token`、`fetch_access_token`、`get_gateway`、`get_gateway_bot` |
231
+ | 机器人 | `get_me`、`get_my_guilds`、`generate_url_link` |
232
+ | 单聊 | 发送 / 流式发送 / 撤回 / 富媒体上传(URL、分片预上传、分片完成) |
233
+ | 群聊 | 发送 / 撤回 / 富媒体上传 / 群信息 / 群成员 / 入群申请 / 自动审批策略 / 黑名单 / 禁言 |
234
+ | 互动 | `respond_interaction`、自定义菜单、指令面板 CRUD |
235
+ | 频道 | 子频道 CRUD、消息发送 / 查询 / 撤回、私信、成员、身份组、禁言、公告、API 权限、表情表态、精华消息、日程 |
236
+
237
+ > 少数接口的请求体字段会随平台更新(如入群自动审批策略、黑名单操作等),
238
+ > 相应的请求模型声明 `extra='allow'`,生成客户端的 `**extra` 可透传任意字段。
239
+
240
+ ## 说明
241
+
242
+ - **证书**:始终使用 `certifi` 的 CA 包(`ssl.create_default_context(cafile=certifi.where())`),
243
+ 也支持注入自定义 `aiohttp.ClientSession` / `SSLContext`;
244
+ - **token**:`access_token` 自动缓存,有效期前 60 秒自动刷新,并发安全(`asyncio.Lock`);
245
+ - **重连**:网关断线指数退避重连,优先 `Resume` 补发遗漏事件;
246
+ 致命关闭码(4001/4002/401x/4914/4915 等)抛出 `QQBotGatewayClosed` 停止重试;
247
+ - **停机**:总线 `stop()` 会注销处理器,事件泵随之取消并断开网关。
248
+
249
+ ## 开发
250
+
251
+ ```bash
252
+ uv sync --extra dev # 安装开发依赖(ruff / pyright / interrogate / pre-commit / agent-kit)
253
+ uv run pre-commit install # 挂载提交钩子(一次性)
254
+
255
+ uv run python tools/gen_rpc.py # 生成 RPC 模型 / 事件 / 客户端 / 处理器
256
+ uv run ruff check . --fix # 静态检查(含 RUF022:`__all__` 自动排序)
257
+ uv run ruff format . # 代码格式化
258
+ uv run pyright # 类型检查(strict 模式,零错误门禁)
259
+ uv run python tests/smoke.py # 冒烟测试(不联网:事件收集 / token 缓存 / 强类型 RPC / 去重)
260
+
261
+ uv run pre-commit run --all-files # 全量质量门(lint / 格式化 / pyright / docstring 覆盖 / 冒烟 / 规则防漂移)
262
+ ```
263
+
264
+ - **质量门**(`.pre-commit-config.yaml`):ruff、pyright(strict)、interrogate(docstring ≥ 90%)、
265
+ 冒烟测试、agent-kit 漂移检查;CI(`.github/workflows/test.yml`)在三平台复跑同一把门;
266
+ 推送 `v*` 标签触发 `publish.yml` 构建并发布(PyPI Trusted Publisher)。
267
+ - **智能体规则**(`AGENT.md` + `.agents/`):由 [agent-kit](https://pypi.org/project/infinity-agent-kit/)
268
+ 统一同步(`uv run agent-kit update`),提交前检查见 `.agents/SKILLS/pre-commit-check.md`。
269
+
270
+ Ruff 配置见 `pyproject.toml`:`select = ["B", "C4", "E", "F", "I", "RUF", "SIM", "UP", "W"]`,
271
+ 其中 `RUF022` 负责 `__all__` 的自动排序(`uv run ruff check --fix .` 直接修复)。
272
+
273
+ ## 目录结构
274
+
275
+ ```
276
+ src/infinity_qqbot/
277
+ ├── __init__.py # 公开导出
278
+ ├── models/ # Pydantic 数据模型(按域拆分:common / message / group / menu / responses / payloads……)
279
+ ├── rpc/ # 强类型 RPC(生成代码:模型 / 事件 / 客户端;handlers/ 为处理器)
280
+ ├── events.py # QQ 网关事件声明(嵌套 Payload 风格,定义即自动收集)
281
+ ├── api.py # QQBotAPI(aiohttp + certifi)
282
+ ├── gateway.py # QQBotGateway(WebSocket 心跳 / resume / 重连)
283
+ ├── engine.py # QQBot 引擎
284
+ └── handlers.py # QQBotEventHandler / register_handlers / wait_for_event
285
+
286
+ tools/
287
+ └── gen_rpc.py # RPC 代码生成器(方法规格 + 模板)
288
+
289
+ tests/
290
+ └── smoke.py # 冒烟测试
291
+ ```
292
+
293
+ 工程化资产(家族标准,见 `AGENT.md` 与 `.agents/`):
294
+
295
+ ```text
296
+ AGENT.md # 智能体引导入口(agent-kit 渲染)
297
+ .agents/ # 智能体静态规则(SKILLS / MEMORY / TEMP_FILES)
298
+ .github/workflows/ # CI/CD:test.yml(质量门 + 冒烟矩阵)、publish.yml(v* 标签发布)
299
+ .pre-commit-config.yaml # 本地质量门(ruff / pyright / interrogate / 冒烟 / 规则防漂移)
300
+ ```
@@ -0,0 +1,264 @@
1
+ # infinity-qqbot
2
+
3
+ 基于 [infinity_bus](https://github.com/yinbailiang/infinity_bus) 的 QQ 机器人引擎。
4
+
5
+ - **`QQBotAPI`**:使用 `aiohttp` + `certifi` 完整封装 QQ 机器人开放平台 v2 接口
6
+ (消息收发、富媒体上传、群管理、频道管理(子频道权限、禁言、论坛、音频等)、
7
+ 互动回调、菜单面板等;HTTP 429 自动退避重试、201/202 异步受理语义);
8
+ - **`QQBotGateway` / `QQBot`**:WebSocket 网关客户端(心跳、Identify/Resume、
9
+ 自动重连、断线补发),输出类型化事件流;
10
+ - **`QQBotEventHandler`**:接受 `QQBotAPI`,随总线激活自动连接网关,
11
+ 并把每个事件自动发布为 `qqbot.event.<type>`(如 `qqbot.event.group_at_message_create`);
12
+ - **`QQBotAPIHandler` + 强类型客户端**:集成 `ServiceHandler`,95 个 API 方法逐一暴露为
13
+ 总线 RPC(请求 / 响应模型、事件声明、客户端函数由 `tools/gen_rpc.py` 从规格生成,
14
+ 运行期零元编程),调用 `await send_c2c_message(...)` 即完成一次强类型 RPC;
15
+ - 数据模型按域拆分在 `models/` 包;事件声明采用嵌套 `Payload` 风格,全部由 Pydantic 校验。
16
+
17
+ ## 安装
18
+
19
+ ```bash
20
+ uv sync
21
+ ```
22
+
23
+ ## 快速开始
24
+
25
+ ```python
26
+ import asyncio
27
+
28
+ from infinity_bus import EventBus, EventHandler, EventHandlerRegistry, EventRegistry, Regex
29
+
30
+ from infinity_qqbot import (
31
+ QQBotAPI,
32
+ qqbot_events,
33
+ register_handlers,
34
+ send_c2c_message,
35
+ )
36
+
37
+
38
+ class Echo(EventHandler):
39
+ """订阅单聊消息,通过总线 RPC 回复。"""
40
+
41
+ def __init__(self) -> None:
42
+ super().__init__(subscriptions=[Regex(r'qqbot\.event\.c2c_message_create')])
43
+
44
+ async def handle(self, payload, bus_proxy, raw_event) -> None:
45
+ await send_c2c_message(
46
+ bus_proxy,
47
+ user_openid=payload.user_openid,
48
+ content=f'收到:{payload.content}',
49
+ msg_id=payload.id, # 被动回复(也可使用 event_id)
50
+ )
51
+
52
+
53
+ async def main() -> None:
54
+ api = QQBotAPI('你的AppID', '你的AppSecret')
55
+
56
+ registry = EventRegistry()
57
+ qqbot_events.register_all_events(registry) # 注册全部事件声明(ModuleEventRegister)
58
+
59
+ handlers = EventHandlerRegistry()
60
+ await handlers.register(Echo())
61
+ await register_handlers(handlers, api) # 入站:网关事件 -> 总线;出站:总线 RPC -> OpenAPI
62
+
63
+ async with EventBus(registry, handlers):
64
+ await asyncio.Event().wait() # 常驻运行
65
+
66
+
67
+ asyncio.run(main())
68
+ ```
69
+
70
+ ## 事件订阅
71
+
72
+ 总线事件名 = `qqbot.event.` + 平台事件名小写,例如:
73
+
74
+ | 平台事件 | 总线事件 | 声明类 |
75
+ | - | - | - |
76
+ | `C2C_MESSAGE_CREATE` | `qqbot.event.c2c_message_create` | `C2CMessageCreateEvent` |
77
+ | `GROUP_AT_MESSAGE_CREATE` | `qqbot.event.group_at_message_create` | `GroupAtMessageCreateEvent` |
78
+ | `AT_MESSAGE_CREATE` | `qqbot.event.at_message_create` | `MessageCreateEvent` 系列 |
79
+ | `INTERACTION_CREATE` | `qqbot.event.interaction_create` | `InteractionCreateEvent` |
80
+ | `GROUP_ADD_ROBOT` | `qqbot.event.group_add_robot` | `GroupAddRobotEvent` |
81
+ | …(共 58 个平台事件) | | |
82
+
83
+ 订阅方式二选一:
84
+
85
+ - 精确订阅:`super().__init__(subscriptions=['qqbot.event.c2c_message_create'])`;
86
+ - 通配订阅:`super().__init__(subscriptions=[Regex(r'qqbot\.event\..*')])`。
87
+
88
+ 未建模的新事件会被兜底发布到 `qqbot.event.unknown`(负载含 `type` 与原始 `data`),
89
+ 不会导致引擎崩溃。
90
+
91
+ 事件声明在定义时由 `ModuleEventRegister` 自动收集(`infinity_qqbot.qqbot_events`),
92
+ 注册时直接调用 `qqbot_events.register_all_events(registry)`,新增声明无需手工维护清单。
93
+
94
+ ## 强类型 RPC 调用 API
95
+
96
+ 每个 API 方法都有生成的**请求模型、响应模型、事件声明与强类型客户端**
97
+ (`tools/gen_rpc.py` 从方法规格生成,纯显式代码、运行期零元编程):
98
+
99
+ ```python
100
+ from infinity_qqbot import send_group_message
101
+
102
+ message = await send_group_message(
103
+ bus_proxy,
104
+ group_openid=group_openid,
105
+ content='hello',
106
+ msg_id=message_id, # 被动回复(也可使用 event_id)
107
+ )
108
+ print(message.id) # MessageResponse(类型由客户端签名给出)
109
+ ```
110
+
111
+ - 客户端底层**直接使用** `infinity_bus.templates.request` 模板,自动以
112
+ `session_id + request_id` 关联请求与响应;
113
+ - 事件名:`qqbot.api.<method>.request` / `qqbot.api.<method>.response`,
114
+ 可直接订阅任意方法的请求 / 响应事件;
115
+ - 请求 / 响应模型**直接继承**库的 `RequestProtocol` / `ResponseProtocol`;
116
+ - 失败时抛出 `QQBotAPIError`(`error_msg` 含平台错误码,跨总线保留);
117
+ - 需要修改 / 新增方法时,编辑 `tools/gen_rpc.py` 中的规格并重新生成:
118
+
119
+ ```bash
120
+ uv run python tools/gen_rpc.py
121
+ uv run ruff check --fix src
122
+ ```
123
+
124
+ 链路:客户端 → `request()` 模板 → `qqbot.api.<method>.request`
125
+ → `QQBotAPIHandler.<method>` → `QQBotAPI.<method>` → `qqbot.api.<method>.response`。
126
+
127
+ ## 模板能力(infinity_bus.templates)
128
+
129
+ 本项目尽可能复用了 `infinity_bus` 的模板能力,业务侧也可直接使用:
130
+
131
+ - **批量处理器注册**:`await register_handlers(handlers, api)` 基于 `ModuleHandlerRegister`
132
+ 一次性注册入站 / 出站处理器;
133
+ - **幂等去重**:QQ 可能重复推送同一事件,注入 `IdempotencyRecorder` 即可按事件 ID 去重
134
+ (发布成功才记录):
135
+
136
+ ```python
137
+ from infinity_bus.templates import InMemoryIdempotencyRecorder
138
+
139
+ from infinity_qqbot import register_handlers
140
+
141
+ await register_handlers(
142
+ handlers,
143
+ api,
144
+ dedup_recorder=InMemoryIdempotencyRecorder(), # 或 SqliteIdempotencyRecorder('bot.db')
145
+ )
146
+ ```
147
+
148
+ - **等待事件**:`wait_for_event()` 基于 `expect` 模板注册一次性监听:
149
+
150
+ ```python
151
+ from infinity_qqbot import ReadyEvent, wait_for_event
152
+
153
+ await wait_for_event(bus.proxy('app'), ReadyEvent.name, timeout=30)
154
+ ```
155
+
156
+ - **中间件**:`infinity_bus.templates.middlewares` 提供的日志(JSONL / SQLite)、限流、
157
+ 递归防护、事件转换等中间件可直接挂到总线:
158
+
159
+ ```python
160
+ from infinity_bus.templates import RecursionGuardMiddleware
161
+
162
+ await bus.proxy('app').middleware.add(RecursionGuardMiddleware())
163
+ ```
164
+
165
+ - **简化处理器**:`infinity_bus.templates.handler` 可把普通异步函数直接包装为处理器类:
166
+
167
+ ```python
168
+ from infinity_bus.templates import handler
169
+
170
+ @handler(C2CMessageCreateEvent)
171
+ async def echo(payload: C2CMessageCreateEvent.Payload) -> None:
172
+ ...
173
+
174
+ await handlers.register(echo())
175
+ ```
176
+
177
+ - **其他模板**:`expect` / `temporary_handler` / `pipe` / `request` 等均可按需组合
178
+ (本库的 RPC 客户端直接使用 `request` 模板,`wait_for_event` 使用 `expect`)。
179
+
180
+ ## 独立使用引擎(不经总线)
181
+
182
+ ```python
183
+ from infinity_qqbot import QQBot, QQBotAPI
184
+
185
+ async with QQBot(QQBotAPI(app_id, secret)) as bot:
186
+ async for event in bot.stream():
187
+ print(event.type, event.payload)
188
+ ```
189
+
190
+ ## API 覆盖范围
191
+
192
+ | 分类 | 代表接口 |
193
+ | - | - |
194
+ | 凭证 / 网关 | `get_access_token`、`fetch_access_token`、`get_gateway`、`get_gateway_bot` |
195
+ | 机器人 | `get_me`、`get_my_guilds`、`generate_url_link` |
196
+ | 单聊 | 发送 / 流式发送 / 撤回 / 富媒体上传(URL、分片预上传、分片完成) |
197
+ | 群聊 | 发送 / 撤回 / 富媒体上传 / 群信息 / 群成员 / 入群申请 / 自动审批策略 / 黑名单 / 禁言 |
198
+ | 互动 | `respond_interaction`、自定义菜单、指令面板 CRUD |
199
+ | 频道 | 子频道 CRUD、消息发送 / 查询 / 撤回、私信、成员、身份组、禁言、公告、API 权限、表情表态、精华消息、日程 |
200
+
201
+ > 少数接口的请求体字段会随平台更新(如入群自动审批策略、黑名单操作等),
202
+ > 相应的请求模型声明 `extra='allow'`,生成客户端的 `**extra` 可透传任意字段。
203
+
204
+ ## 说明
205
+
206
+ - **证书**:始终使用 `certifi` 的 CA 包(`ssl.create_default_context(cafile=certifi.where())`),
207
+ 也支持注入自定义 `aiohttp.ClientSession` / `SSLContext`;
208
+ - **token**:`access_token` 自动缓存,有效期前 60 秒自动刷新,并发安全(`asyncio.Lock`);
209
+ - **重连**:网关断线指数退避重连,优先 `Resume` 补发遗漏事件;
210
+ 致命关闭码(4001/4002/401x/4914/4915 等)抛出 `QQBotGatewayClosed` 停止重试;
211
+ - **停机**:总线 `stop()` 会注销处理器,事件泵随之取消并断开网关。
212
+
213
+ ## 开发
214
+
215
+ ```bash
216
+ uv sync --extra dev # 安装开发依赖(ruff / pyright / interrogate / pre-commit / agent-kit)
217
+ uv run pre-commit install # 挂载提交钩子(一次性)
218
+
219
+ uv run python tools/gen_rpc.py # 生成 RPC 模型 / 事件 / 客户端 / 处理器
220
+ uv run ruff check . --fix # 静态检查(含 RUF022:`__all__` 自动排序)
221
+ uv run ruff format . # 代码格式化
222
+ uv run pyright # 类型检查(strict 模式,零错误门禁)
223
+ uv run python tests/smoke.py # 冒烟测试(不联网:事件收集 / token 缓存 / 强类型 RPC / 去重)
224
+
225
+ uv run pre-commit run --all-files # 全量质量门(lint / 格式化 / pyright / docstring 覆盖 / 冒烟 / 规则防漂移)
226
+ ```
227
+
228
+ - **质量门**(`.pre-commit-config.yaml`):ruff、pyright(strict)、interrogate(docstring ≥ 90%)、
229
+ 冒烟测试、agent-kit 漂移检查;CI(`.github/workflows/test.yml`)在三平台复跑同一把门;
230
+ 推送 `v*` 标签触发 `publish.yml` 构建并发布(PyPI Trusted Publisher)。
231
+ - **智能体规则**(`AGENT.md` + `.agents/`):由 [agent-kit](https://pypi.org/project/infinity-agent-kit/)
232
+ 统一同步(`uv run agent-kit update`),提交前检查见 `.agents/SKILLS/pre-commit-check.md`。
233
+
234
+ Ruff 配置见 `pyproject.toml`:`select = ["B", "C4", "E", "F", "I", "RUF", "SIM", "UP", "W"]`,
235
+ 其中 `RUF022` 负责 `__all__` 的自动排序(`uv run ruff check --fix .` 直接修复)。
236
+
237
+ ## 目录结构
238
+
239
+ ```
240
+ src/infinity_qqbot/
241
+ ├── __init__.py # 公开导出
242
+ ├── models/ # Pydantic 数据模型(按域拆分:common / message / group / menu / responses / payloads……)
243
+ ├── rpc/ # 强类型 RPC(生成代码:模型 / 事件 / 客户端;handlers/ 为处理器)
244
+ ├── events.py # QQ 网关事件声明(嵌套 Payload 风格,定义即自动收集)
245
+ ├── api.py # QQBotAPI(aiohttp + certifi)
246
+ ├── gateway.py # QQBotGateway(WebSocket 心跳 / resume / 重连)
247
+ ├── engine.py # QQBot 引擎
248
+ └── handlers.py # QQBotEventHandler / register_handlers / wait_for_event
249
+
250
+ tools/
251
+ └── gen_rpc.py # RPC 代码生成器(方法规格 + 模板)
252
+
253
+ tests/
254
+ └── smoke.py # 冒烟测试
255
+ ```
256
+
257
+ 工程化资产(家族标准,见 `AGENT.md` 与 `.agents/`):
258
+
259
+ ```text
260
+ AGENT.md # 智能体引导入口(agent-kit 渲染)
261
+ .agents/ # 智能体静态规则(SKILLS / MEMORY / TEMP_FILES)
262
+ .github/workflows/ # CI/CD:test.yml(质量门 + 冒烟矩阵)、publish.yml(v* 标签发布)
263
+ .pre-commit-config.yaml # 本地质量门(ruff / pyright / interrogate / 冒烟 / 规则防漂移)
264
+ ```