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.
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/PKG-INFO +3 -3
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/pyproject.toml +3 -3
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/pyproject.toml.orig +3 -3
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/__init__.py +3 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/api.py +99 -5
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/bot.py +110 -23
- qqbotsdk_py-2.2.0/src/qqbotsdk/app/context.py +448 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/dispatch.py +7 -2
- qqbotsdk_py-2.2.0/src/qqbotsdk/app/types.py +42 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/c2c.py +12 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/group.py +12 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/interaction.py +25 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/messages.py +8 -1
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/user/messages.py +8 -1
- qqbotsdk_py-2.2.0/src/qqbotsdk/testing.py +117 -0
- qqbotsdk_py-2.0.0/src/qqbotsdk/app/context.py +0 -242
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/README.md +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/agent.md +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/bot.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/agent.md +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/blacklist.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/join_request.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/manage.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/messages.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/mute.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/strategy.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/interaction.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/media.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/menu.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/panel.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/user.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/agent.md +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/keyboard.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/agent.md +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/bot.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/__init__.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/agent.md +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/agent.md +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/blacklist.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/join_request.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/member.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/mute.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/strategy.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/interaction.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/media.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/menu.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/panel.py +0 -0
- {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/user/agent.md +0 -0
- {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.
|
|
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.
|
|
8
|
-
Requires-Dist: qqbotsdk-guild-py>=2.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
11
|
+
"qqbotsdk-base-py>=2.2.0",
|
|
12
12
|
]
|
|
13
13
|
|
|
14
14
|
[project.optional-dependencies]
|
|
15
|
-
guild = ["qqbotsdk-guild-py>=2.
|
|
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(
|
|
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(
|
|
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:
|
|
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 =
|
|
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
|
-
|
|
75
|
-
|
|
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(
|
|
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
|
-
``
|
|
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
|
-
|
|
255
|
+
_remember_msg_seq(key, msg_seq)
|
|
185
256
|
return msg_seq
|
|
186
|
-
seq =
|
|
187
|
-
|
|
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
|
-
|
|
247
|
-
"""
|
|
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
|
]
|