qqbotsdk-py 2.0.0__tar.gz → 2.2.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 (49) hide show
  1. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/PKG-INFO +3 -3
  2. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/pyproject.toml +3 -3
  3. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/pyproject.toml.orig +3 -3
  4. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/__init__.py +3 -0
  5. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/api.py +99 -5
  6. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/bot.py +110 -23
  7. qqbotsdk_py-2.2.0/src/qqbotsdk/app/context.py +448 -0
  8. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/dispatch.py +7 -2
  9. qqbotsdk_py-2.2.0/src/qqbotsdk/app/types.py +42 -0
  10. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/c2c.py +12 -0
  11. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/group.py +12 -0
  12. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/interaction.py +25 -0
  13. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/messages.py +8 -1
  14. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/user/messages.py +8 -1
  15. qqbotsdk_py-2.2.0/src/qqbotsdk/testing.py +117 -0
  16. qqbotsdk_py-2.0.0/src/qqbotsdk/app/context.py +0 -242
  17. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/README.md +0 -0
  18. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/agent.md +0 -0
  19. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/bot.py +0 -0
  20. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/agent.md +0 -0
  21. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/blacklist.py +0 -0
  22. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/join_request.py +0 -0
  23. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/manage.py +0 -0
  24. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/messages.py +0 -0
  25. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/mute.py +0 -0
  26. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/strategy.py +0 -0
  27. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/interaction.py +0 -0
  28. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/media.py +0 -0
  29. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/menu.py +0 -0
  30. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/panel.py +0 -0
  31. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/user.py +0 -0
  32. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/agent.md +0 -0
  33. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/keyboard.py +0 -0
  34. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/agent.md +0 -0
  35. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/bot.py +0 -0
  36. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/__init__.py +0 -0
  37. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/agent.md +0 -0
  38. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/agent.md +0 -0
  39. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/blacklist.py +0 -0
  40. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/join_request.py +0 -0
  41. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/member.py +0 -0
  42. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/mute.py +0 -0
  43. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/strategy.py +0 -0
  44. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/interaction.py +0 -0
  45. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/media.py +0 -0
  46. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/menu.py +0 -0
  47. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/panel.py +0 -0
  48. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/user/agent.md +0 -0
  49. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/user/stream_messages.py +0 -0
@@ -1,11 +1,11 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: qqbotsdk-py
3
- Version: 2.0.0
3
+ Version: 2.2.0
4
4
  Summary: QQ 官方机器人 SDK:群聊 / 单聊 / 素材 / 互动
5
5
  Author: snowy-yang
6
6
  Author-email: snowy-yang <102860110+snowy-yang@users.noreply.github.com>
7
- Requires-Dist: qqbotsdk-base-py>=2.0.0
8
- Requires-Dist: qqbotsdk-guild-py>=2.0.0 ; extra == 'guild'
7
+ Requires-Dist: qqbotsdk-base-py>=2.2.0
8
+ Requires-Dist: qqbotsdk-guild-py>=2.2.0 ; extra == 'guild'
9
9
  Requires-Python: >=3.12
10
10
  Provides-Extra: guild
11
11
  Description-Content-Type: text/markdown
@@ -1,17 +1,17 @@
1
1
  [project]
2
2
  name = "qqbotsdk-py"
3
- version = "2.0.0"
3
+ version = "2.2.0"
4
4
  description = "QQ 官方机器人 SDK:群聊 / 单聊 / 素材 / 互动"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
7
- dependencies = ["qqbotsdk-base-py>=2.0.0"]
7
+ dependencies = ["qqbotsdk-base-py>=2.2.0"]
8
8
 
9
9
  [[project.authors]]
10
10
  name = "snowy-yang"
11
11
  email = "102860110+snowy-yang@users.noreply.github.com"
12
12
 
13
13
  [project.optional-dependencies]
14
- guild = ["qqbotsdk-guild-py>=2.0.0"]
14
+ guild = ["qqbotsdk-guild-py>=2.2.0"]
15
15
 
16
16
  [build-system]
17
17
  requires = ["uv_build>=0.13.5,<0.14.0"]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "qqbotsdk-py"
3
- version = "2.0.0"
3
+ version = "2.2.0"
4
4
  description = "QQ 官方机器人 SDK:群聊 / 单聊 / 素材 / 互动"
5
5
  readme = "README.md"
6
6
  authors = [
@@ -8,11 +8,11 @@ authors = [
8
8
  ]
9
9
  requires-python = ">=3.12"
10
10
  dependencies = [
11
- "qqbotsdk-base-py>=2.0.0",
11
+ "qqbotsdk-base-py>=2.2.0",
12
12
  ]
13
13
 
14
14
  [project.optional-dependencies]
15
- guild = ["qqbotsdk-guild-py>=2.0.0"]
15
+ guild = ["qqbotsdk-guild-py>=2.2.0"]
16
16
 
17
17
  [build-system]
18
18
  requires = ["uv_build>=0.13.5,<0.14.0"]
@@ -61,6 +61,7 @@ from qqbotsdk.app.keyboard import (
61
61
  only_users,
62
62
  row,
63
63
  )
64
+ from qqbotsdk.app.types import PreparedReply, Scene
64
65
 
65
66
  __all__ = [
66
67
  "Bot",
@@ -69,6 +70,8 @@ __all__ = [
69
70
  "Handler",
70
71
  "KeyboardBuilder",
71
72
  "Middleware",
73
+ "PreparedReply",
74
+ "Scene",
72
75
  "SceneApi",
73
76
  "callback",
74
77
  "command",
@@ -29,6 +29,7 @@ from qqbotsdk.api import user as user_api
29
29
  from qqbotsdk.api.core import session
30
30
  from qqbotsdk.api.group import join_request as join_request_api
31
31
  from qqbotsdk.api.group import messages as group_messages
32
+ from qqbotsdk.app.types import PreparedReply, Scene
32
33
  from qqbotsdk.errors import QQBotError
33
34
  from qqbotsdk.model.group.join_request import ReviewGroupJoinRequest
34
35
  from qqbotsdk.model.group.messages import (
@@ -54,9 +55,6 @@ from qqbotsdk.model.user.messages import SendUserMessagesRequest, UploadUserFile
54
55
  if TYPE_CHECKING:
55
56
  from qqbotsdk.app.context import Context
56
57
 
57
- Scene = Literal["group", "c2c", "other"]
58
- """场景: 群聊 / 单聊 / 其它(既没有群 OpenID 也没有单聊用户 OpenID)."""
59
-
60
58
  INTERACTION_EVENT: str = "INTERACTION_CREATE"
61
59
  """互动事件名."""
62
60
 
@@ -271,13 +269,109 @@ class SceneApi:
271
269
  body["content"] = content
272
270
  return await _send(scene, openid, body)
273
271
 
274
- async def reply(self, content: str, *, msg_seq: int | None = None) -> str | None:
272
+ async def reply(
273
+ self,
274
+ content: str,
275
+ *,
276
+ msg_seq: int | None = None,
277
+ keyboard: Keyboard | None = None,
278
+ seq_key: str | None = None,
279
+ ) -> str | None:
275
280
  """被动回复一条文本消息, 直接委托 :meth:`Context.reply`.
276
281
 
277
282
  锚点(event_id 优先, 其次 msg_id)与 msg_seq 自增都在 Context / Bot 里,
278
283
  这里不重复实现; 不可回复的事件返回 None.
284
+
285
+ Args:
286
+ content: 文本内容.
287
+ msg_seq: 显式指定序号; 省略则由 Bot 按锚点自增.
288
+ keyboard: 内嵌键盘, 省略则不带键盘.
289
+ seq_key: 计数用的键, 省略时用锚点本身.
279
290
  """
280
- return await self._ctx.reply(content, msg_seq=msg_seq)
291
+ return await self._ctx.reply(
292
+ content,
293
+ msg_seq=msg_seq,
294
+ keyboard=keyboard,
295
+ seq_key=seq_key,
296
+ )
297
+
298
+ async def reply_markdown(
299
+ self,
300
+ content: str,
301
+ *,
302
+ keyboard: Keyboard | None = None,
303
+ msg_seq: int | None = None,
304
+ seq_key: str | None = None,
305
+ ) -> str | None:
306
+ """被动回复一条 Markdown 消息, 委托 :meth:`Context.reply_markdown`."""
307
+ return await self._ctx.reply_markdown(
308
+ content,
309
+ keyboard=keyboard,
310
+ msg_seq=msg_seq,
311
+ seq_key=seq_key,
312
+ )
313
+
314
+ async def reply_media(
315
+ self,
316
+ file_info: str,
317
+ *,
318
+ content: str | None = None,
319
+ keyboard: Keyboard | None = None,
320
+ msg_seq: int | None = None,
321
+ seq_key: str | None = None,
322
+ ) -> str | None:
323
+ """被动回复一条富媒体消息, 委托 :meth:`Context.reply_media`."""
324
+ return await self._ctx.reply_media(
325
+ file_info,
326
+ content=content,
327
+ keyboard=keyboard,
328
+ msg_seq=msg_seq,
329
+ seq_key=seq_key,
330
+ )
331
+
332
+ async def send_reply(
333
+ self,
334
+ *,
335
+ content: str | None = None,
336
+ markdown: str | MessageMarkdown | None = None,
337
+ media: str | MediaInfo | None = None,
338
+ card: MessageCard | None = None,
339
+ keyboard: Keyboard | None = None,
340
+ msg_seq: int | None = None,
341
+ seq_key: str | None = None,
342
+ ) -> str | None:
343
+ """一步完成「算锚点 + 发出去」, 委托 :meth:`Context.send_reply`."""
344
+ return await self._ctx.send_reply(
345
+ content=content,
346
+ markdown=markdown,
347
+ media=media,
348
+ card=card,
349
+ keyboard=keyboard,
350
+ msg_seq=msg_seq,
351
+ seq_key=seq_key,
352
+ )
353
+
354
+ def build_reply(
355
+ self,
356
+ *,
357
+ content: str | None = None,
358
+ markdown: str | MessageMarkdown | None = None,
359
+ media: str | MediaInfo | None = None,
360
+ card: MessageCard | None = None,
361
+ keyboard: Keyboard | None = None,
362
+ msg_seq: int | None = None,
363
+ seq_key: str | None = None,
364
+ ) -> PreparedReply | None:
365
+ """生成请求体但不发送, 委托 :meth:`Context.build_reply`."""
366
+ return self._ctx.build_reply(
367
+ content=content,
368
+ markdown=markdown,
369
+ media=media,
370
+ card=card,
371
+ keyboard=keyboard,
372
+ msg_seq=msg_seq,
373
+ seq_key=seq_key,
374
+ )
281
375
 
282
376
  async def recall(self, message_id: str) -> None:
283
377
  """撤回一条消息: 群聊走群撤回接口, 单聊走单聊撤回接口."""
@@ -26,6 +26,7 @@
26
26
  """
27
27
 
28
28
  import asyncio
29
+ import os
29
30
  from collections.abc import Callable
30
31
  from typing import Final
31
32
 
@@ -47,12 +48,67 @@ from qqbotsdk.ws.payload import GatewayPayload, OpCode
47
48
  MSG_SEQ_CACHE_LIMIT: Final = 512
48
49
  """msg_seq 缓存的最大锚点数, 超出后淘汰最久未使用的锚点."""
49
50
 
51
+ INTENTS_ENV: Final = "INTENTS"
52
+ """环境变量名: 用十进制或 ``0x`` 十六进制掩码覆盖订阅位, 优先于代码里的默认值.
53
+
54
+ 运维可以在不重新发版的情况下收窄订阅(例如临时关掉某个需要权限的事件位),
55
+ 避免因 intents 无权限导致网关卡在 4013/4014.
56
+ """
57
+
58
+ # 被动回复锚点(事件 ID 或消息 ID) -> 已用到的最大 msg_seq.
59
+ # 放模块级而不是 Bot 实例上: 平台只认「msg_id + msg_seq」是否重复, 与是哪个 Bot
60
+ # 实例发的无关. 多实例(分片 / 多机器人代管同一批会话)共用一份计数才不会各自从 1
61
+ # 重来. 键是普通字符串, 不会因此持有 Bot 或会话相关的引用.
62
+ _MSG_SEQ_CACHE: dict[str, int] = {}
63
+
64
+
65
+ def reset_msg_seq_cache() -> None:
66
+ """清空全局 msg_seq 计数, 仅供测试与长驻进程的兜底清理使用."""
67
+ _MSG_SEQ_CACHE.clear()
68
+
69
+
70
+ def _remember_msg_seq(key: str, seq: int) -> None:
71
+ """写入锚点的序号(只增不减)并按上限淘汰最久未使用的条目."""
72
+ previous = _MSG_SEQ_CACHE.pop(key, 0)
73
+ _MSG_SEQ_CACHE[key] = seq if seq > previous else previous
74
+ while len(_MSG_SEQ_CACHE) > MSG_SEQ_CACHE_LIMIT:
75
+ _MSG_SEQ_CACHE.pop(next(iter(_MSG_SEQ_CACHE)))
76
+
77
+
78
+ def resolve_intents(intents: Intents | None = None) -> Intents:
79
+ """决定本次使用的订阅位: 显式入参 > ``INTENTS`` 环境变量 > ``DEFAULT_INTENTS``.
80
+
81
+ Args:
82
+ intents: 代码里显式指定的订阅位, 传了就直接用, 不读环境变量.
83
+
84
+ Returns:
85
+ 最终生效的 :class:`Intents`.
86
+
87
+ Raises:
88
+ ValueError: ``INTENTS`` 环境变量不是合法的十进制 / ``0x`` 十六进制掩码.
89
+ """
90
+ if intents is not None:
91
+ return intents
92
+ raw = os.getenv(INTENTS_ENV, "").strip()
93
+ if not raw:
94
+ return DEFAULT_INTENTS
95
+ try:
96
+ mask = int(raw, 0) # 十进制或 0x 十六进制
97
+ except ValueError:
98
+ raise ValueError(
99
+ f"{INTENTS_ENV} 应为十进制或 0x 十六进制掩码,实际: {raw!r}"
100
+ ) from None
101
+ if mask < 0:
102
+ raise ValueError(f"{INTENTS_ENV} 不能为负数,实际: {mask}")
103
+ return Intents(mask)
104
+
50
105
 
51
106
  class Bot:
52
107
  """把网关连接和事件注册表绑在一起的机器人实例.
53
108
 
54
109
  Args:
55
- intents: 订阅的事件位, 默认 ``DEFAULT_INTENTS``.
110
+ intents: 订阅的事件位. 省略时依次回退到 ``INTENTS`` 环境变量(十进制或
111
+ ``0x`` 十六进制掩码)与 ``DEFAULT_INTENTS``, 见 :func:`resolve_intents`.
56
112
  url: 网关地址, 省略时由 ``QQBotWebSocket`` 在每次连接前自动获取.
57
113
  auto_reconnect: 断线后是否自动重连.
58
114
  """
@@ -60,19 +116,22 @@ class Bot:
60
116
  def __init__(
61
117
  self,
62
118
  *,
63
- intents: Intents = DEFAULT_INTENTS,
119
+ intents: Intents | None = None,
64
120
  url: str | None = None,
65
121
  auto_reconnect: bool = True,
66
122
  ) -> None:
67
- self._intents = intents
123
+ self._intents = resolve_intents(intents)
68
124
  self._url = url
69
125
  self._auto_reconnect = auto_reconnect
70
126
  self._dispatcher = Dispatcher()
71
127
  self._ws: QQBotWebSocket | None = None
72
128
  self._stop_event = asyncio.Event()
73
129
  self._running = False
74
- # 被动回复锚点(事件 ID 或消息 ID) -> 已用到的最大 msg_seq
75
- self._msg_seq_cache: dict[str, int] = {}
130
+
131
+ @property
132
+ def intents(self) -> Intents:
133
+ """当前生效的订阅位(已解析环境变量与默认值)."""
134
+ return self._intents
76
135
 
77
136
  def __repr__(self) -> str:
78
137
  return (
@@ -168,32 +227,37 @@ class Bot:
168
227
 
169
228
  # ------------------------------------------------------------ msg_seq
170
229
 
171
- def next_msg_seq(self, anchor: str, msg_seq: int | None = None) -> int:
230
+ def next_msg_seq(
231
+ self,
232
+ anchor: str,
233
+ msg_seq: int | None = None,
234
+ *,
235
+ seq_key: str | None = None,
236
+ ) -> int:
172
237
  """返回该被动回复锚点本次使用的 ``msg_seq``, 供 :meth:`Context.reply` 调用.
173
238
 
174
239
  Args:
175
240
  anchor: 本次被动回复的锚点, 即事件 ID 或消息 ID.
176
241
  msg_seq: 调用方显式指定的序号; 传了就以它为准, 并把该锚点的计数
177
242
  推进到该值, 之后的自增不会回头撞上已用过的序号.
243
+ seq_key: 计数用的键, 省略时用 ``anchor``. 自己拼请求直连
244
+ ``send_group_messages`` 时, 用同一个键调一次本方法登记, 再回来
245
+ 的 ``ctx.reply`` 就不会从 1 重新开始而触发 40054005.
178
246
 
179
247
  不显式指定时按锚点自增: 同一锚点第一次是 1, 第二次是 2, 以此类推,
180
- 避免平台返回 40054005 (相同 msg_id + msg_seq 重复发送). 缓存按
181
- ``MSG_SEQ_CACHE_LIMIT`` 限制条目数, 超出后淘汰最久未使用的锚点.
248
+ 避免平台返回 40054005 (相同 msg_id + msg_seq 重复发送). 计数**按锚点全局
249
+ 共享**, 不随 ``Bot`` 实例隔离: 同一进程内多个 ``Bot`` 实例命中同一锚点时
250
+ 继续往下排, 而不是各自从 1 开始. 缓存按 ``MSG_SEQ_CACHE_LIMIT`` 限制
251
+ 条目数, 超出后淘汰最久未使用的锚点.
182
252
  """
253
+ key = seq_key or anchor
183
254
  if msg_seq is not None:
184
- self._remember_msg_seq(anchor, msg_seq)
255
+ _remember_msg_seq(key, msg_seq)
185
256
  return msg_seq
186
- seq = self._msg_seq_cache.get(anchor, 0) + 1
187
- self._remember_msg_seq(anchor, seq)
257
+ seq = _MSG_SEQ_CACHE.get(key, 0) + 1
258
+ _remember_msg_seq(key, seq)
188
259
  return seq
189
260
 
190
- def _remember_msg_seq(self, anchor: str, seq: int) -> None:
191
- """写入锚点的序号(只增不减)并按上限淘汰最久未使用的条目."""
192
- previous = self._msg_seq_cache.pop(anchor, 0)
193
- self._msg_seq_cache[anchor] = seq if seq > previous else previous
194
- while len(self._msg_seq_cache) > MSG_SEQ_CACHE_LIMIT:
195
- self._msg_seq_cache.pop(next(iter(self._msg_seq_cache)))
196
-
197
261
  # ------------------------------------------------------------ 生命周期
198
262
 
199
263
  async def start(self) -> None:
@@ -243,17 +307,40 @@ class Bot:
243
307
  await ws.close()
244
308
  await self._dispatcher.cancel_tasks()
245
309
 
246
- async def _on_dispatch(self, payload: GatewayPayload) -> None:
247
- """网关回调: 为每个 Dispatch 建 Context 并丢进独立任务."""
310
+ def dispatch(self, payload: GatewayPayload) -> asyncio.Task[None] | None:
311
+ """把一帧当作网关下发的事件来处理, 返回处理任务.
312
+
313
+ 正常运行时由网关回调调用; 也可以在**不连网关**的情况下手动喂事件, 便于
314
+ 单元测试::
315
+
316
+ payload = GatewayPayload.model_validate(
317
+ {"op": 0, "t": "GROUP_AT_MESSAGE_CREATE", "d": {...}}
318
+ )
319
+ await bot.dispatch(payload) # 等 handler / 中间件跑完
320
+
321
+ Args:
322
+ payload: 网关数据包; ``op`` 不是 Dispatch 时忽略并返回 None.
323
+
324
+ Returns:
325
+ 正在处理该事件的任务, 可以直接 ``await``; 被忽略时返回 None.
326
+ 与网关路径一样, 处理是异步的, 不 ``await`` 也不影响收包。
327
+ """
248
328
  if payload.op != OpCode.DISPATCH:
249
- return
329
+ return None
250
330
  if self._stop_event.is_set():
251
- return
331
+ return None
252
332
  context = Context(bot=self, payload=payload, event=resolve_event(payload))
253
- self._dispatcher.submit(context)
333
+ return self._dispatcher.submit(context)
334
+
335
+ async def _on_dispatch(self, payload: GatewayPayload) -> None:
336
+ """网关回调: 交给 :meth:`dispatch`, 不等待处理完成."""
337
+ self.dispatch(payload)
254
338
 
255
339
 
256
340
  __all__ = [
341
+ "INTENTS_ENV",
257
342
  "MSG_SEQ_CACHE_LIMIT",
258
343
  "Bot",
344
+ "reset_msg_seq_cache",
345
+ "resolve_intents",
259
346
  ]