qqbotsdk-py 2.1.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.1.0 → qqbotsdk_py-2.2.0}/PKG-INFO +3 -3
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/pyproject.toml +3 -3
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/pyproject.toml.orig +3 -3
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/__init__.py +3 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/api.py +79 -3
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/bot.py +72 -8
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/context.py +221 -38
- {qqbotsdk_py-2.1.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.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/c2c.py +12 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/group.py +12 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/interaction.py +25 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/messages.py +8 -1
- {qqbotsdk_py-2.1.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.1.0 → qqbotsdk_py-2.2.0}/README.md +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/agent.md +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/bot.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/agent.md +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/blacklist.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/join_request.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/manage.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/messages.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/mute.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/group/strategy.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/interaction.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/media.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/menu.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/panel.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/api/user.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/agent.md +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/app/keyboard.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/agent.md +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/bot.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/__init__.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/event/agent.md +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/agent.md +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/blacklist.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/join_request.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/member.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/mute.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/group/strategy.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/interaction.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/media.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/menu.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/panel.py +0 -0
- {qqbotsdk_py-2.1.0 → qqbotsdk_py-2.2.0}/src/qqbotsdk/model/user/agent.md +0 -0
- {qqbotsdk_py-2.1.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
|
|
|
@@ -297,6 +295,84 @@ class SceneApi:
|
|
|
297
295
|
seq_key=seq_key,
|
|
298
296
|
)
|
|
299
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
|
+
)
|
|
375
|
+
|
|
300
376
|
async def recall(self, message_id: str) -> None:
|
|
301
377
|
"""撤回一条消息: 群聊走群撤回接口, 单聊走单聊撤回接口."""
|
|
302
378
|
scene, openid = self._target()
|
|
@@ -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,6 +48,13 @@ 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
|
+
|
|
50
58
|
# 被动回复锚点(事件 ID 或消息 ID) -> 已用到的最大 msg_seq.
|
|
51
59
|
# 放模块级而不是 Bot 实例上: 平台只认「msg_id + msg_seq」是否重复, 与是哪个 Bot
|
|
52
60
|
# 实例发的无关. 多实例(分片 / 多机器人代管同一批会话)共用一份计数才不会各自从 1
|
|
@@ -67,11 +75,40 @@ def _remember_msg_seq(key: str, seq: int) -> None:
|
|
|
67
75
|
_MSG_SEQ_CACHE.pop(next(iter(_MSG_SEQ_CACHE)))
|
|
68
76
|
|
|
69
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
|
+
|
|
105
|
+
|
|
70
106
|
class Bot:
|
|
71
107
|
"""把网关连接和事件注册表绑在一起的机器人实例.
|
|
72
108
|
|
|
73
109
|
Args:
|
|
74
|
-
intents:
|
|
110
|
+
intents: 订阅的事件位. 省略时依次回退到 ``INTENTS`` 环境变量(十进制或
|
|
111
|
+
``0x`` 十六进制掩码)与 ``DEFAULT_INTENTS``, 见 :func:`resolve_intents`.
|
|
75
112
|
url: 网关地址, 省略时由 ``QQBotWebSocket`` 在每次连接前自动获取.
|
|
76
113
|
auto_reconnect: 断线后是否自动重连.
|
|
77
114
|
"""
|
|
@@ -79,11 +116,11 @@ class Bot:
|
|
|
79
116
|
def __init__(
|
|
80
117
|
self,
|
|
81
118
|
*,
|
|
82
|
-
intents: Intents =
|
|
119
|
+
intents: Intents | None = None,
|
|
83
120
|
url: str | None = None,
|
|
84
121
|
auto_reconnect: bool = True,
|
|
85
122
|
) -> None:
|
|
86
|
-
self._intents = intents
|
|
123
|
+
self._intents = resolve_intents(intents)
|
|
87
124
|
self._url = url
|
|
88
125
|
self._auto_reconnect = auto_reconnect
|
|
89
126
|
self._dispatcher = Dispatcher()
|
|
@@ -91,6 +128,11 @@ class Bot:
|
|
|
91
128
|
self._stop_event = asyncio.Event()
|
|
92
129
|
self._running = False
|
|
93
130
|
|
|
131
|
+
@property
|
|
132
|
+
def intents(self) -> Intents:
|
|
133
|
+
"""当前生效的订阅位(已解析环境变量与默认值)."""
|
|
134
|
+
return self._intents
|
|
135
|
+
|
|
94
136
|
def __repr__(self) -> str:
|
|
95
137
|
return (
|
|
96
138
|
f"Bot(running={self._running}, "
|
|
@@ -265,18 +307,40 @@ class Bot:
|
|
|
265
307
|
await ws.close()
|
|
266
308
|
await self._dispatcher.cancel_tasks()
|
|
267
309
|
|
|
268
|
-
|
|
269
|
-
"""
|
|
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
|
+
"""
|
|
270
328
|
if payload.op != OpCode.DISPATCH:
|
|
271
|
-
return
|
|
329
|
+
return None
|
|
272
330
|
if self._stop_event.is_set():
|
|
273
|
-
return
|
|
331
|
+
return None
|
|
274
332
|
context = Context(bot=self, payload=payload, event=resolve_event(payload))
|
|
275
|
-
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)
|
|
276
338
|
|
|
277
339
|
|
|
278
340
|
__all__ = [
|
|
341
|
+
"INTENTS_ENV",
|
|
279
342
|
"MSG_SEQ_CACHE_LIMIT",
|
|
280
343
|
"Bot",
|
|
281
344
|
"reset_msg_seq_cache",
|
|
345
|
+
"resolve_intents",
|
|
282
346
|
]
|
|
@@ -6,8 +6,10 @@ handler / 中间件都拿它当唯一入参, 并通过它回消息::
|
|
|
6
6
|
@bot.on_message()
|
|
7
7
|
async def echo(ctx: Context) -> None:
|
|
8
8
|
await ctx.reply(ctx.event.content or "")
|
|
9
|
+
await ctx.reply_markdown("## 标题\\n正文", keyboard=kb)
|
|
10
|
+
await ctx.reply_media(file_info, content="看图")
|
|
9
11
|
|
|
10
|
-
|
|
12
|
+
回复的锚点与 msg_seq 规则见 :meth:`Context.build_reply`.
|
|
11
13
|
"""
|
|
12
14
|
|
|
13
15
|
from typing import TYPE_CHECKING, Any, Final, cast
|
|
@@ -15,9 +17,15 @@ from typing import TYPE_CHECKING, Any, Final, cast
|
|
|
15
17
|
from qqbotsdk.api import user as user_api
|
|
16
18
|
from qqbotsdk.api.group import messages as group_messages
|
|
17
19
|
from qqbotsdk.app.api import SceneApi
|
|
20
|
+
from qqbotsdk.app.types import PreparedReply, Scene
|
|
18
21
|
from qqbotsdk.model.core import QQBotBaseModel
|
|
19
22
|
from qqbotsdk.model.group.messages import SendGroupMessagesRequest
|
|
20
|
-
from qqbotsdk.model.sub.messages import
|
|
23
|
+
from qqbotsdk.model.sub.messages import (
|
|
24
|
+
Keyboard,
|
|
25
|
+
MediaInfo,
|
|
26
|
+
MessageCard,
|
|
27
|
+
MessageMarkdown,
|
|
28
|
+
)
|
|
21
29
|
from qqbotsdk.model.user.messages import SendUserMessagesRequest
|
|
22
30
|
from qqbotsdk.ws.payload import GatewayPayload
|
|
23
31
|
|
|
@@ -47,31 +55,62 @@ def _str_field(data: Any, key: str) -> str | None:
|
|
|
47
55
|
return None
|
|
48
56
|
|
|
49
57
|
|
|
50
|
-
def
|
|
51
|
-
|
|
58
|
+
def _markdown_of(markdown: str | MessageMarkdown | None) -> MessageMarkdown | None:
|
|
59
|
+
"""把 Markdown 文本包装成模型; 已经是模型就原样返回."""
|
|
60
|
+
if markdown is None or isinstance(markdown, MessageMarkdown):
|
|
61
|
+
return markdown
|
|
62
|
+
return MessageMarkdown.model_validate({"content": markdown})
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def _media_of(media: str | MediaInfo | None) -> MediaInfo | None:
|
|
66
|
+
"""把 ``file_info`` 包装成模型; 已经是模型就原样返回."""
|
|
67
|
+
if media is None or isinstance(media, MediaInfo):
|
|
68
|
+
return media
|
|
69
|
+
return MediaInfo.model_validate({"file_info": media})
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _reply_body(
|
|
52
73
|
*,
|
|
74
|
+
content: str | None,
|
|
75
|
+
markdown: str | MessageMarkdown | None,
|
|
76
|
+
media: str | MediaInfo | None,
|
|
77
|
+
card: MessageCard | None,
|
|
78
|
+
keyboard: Keyboard | None,
|
|
53
79
|
event_id: str | None,
|
|
54
80
|
msg_id: str | None,
|
|
55
81
|
msg_seq: int | None,
|
|
56
|
-
keyboard: Keyboard | None = None,
|
|
57
82
|
) -> dict[str, Any]:
|
|
58
|
-
"""
|
|
83
|
+
"""拼被动回复的请求体.
|
|
59
84
|
|
|
60
85
|
``event_id`` 与 ``msg_id`` 互斥: 有事件 ID 时只填 ``event_id``, 否则才填
|
|
61
86
|
``msg_id``; 主动消息两者都不填.
|
|
62
87
|
|
|
88
|
+
``msg_type`` 不在这里写死, 交给 ``SendXxxMessagesRequest`` 按填了哪个内容
|
|
89
|
+
字段推导(见 :class:`qqbotsdk.model.sub.messages.MessageSendRequestBase`),
|
|
90
|
+
这样 Markdown / 富媒体 / 卡片都走同一条路径.
|
|
91
|
+
|
|
63
92
|
用字典加 ``model_validate`` 而不是直接构造 ``SendXxxMessagesRequest``,
|
|
64
93
|
因为 pyright 识别不到那些 ``Field(None, ...)`` 的默认值, 直接构造会报错.
|
|
65
94
|
"""
|
|
66
|
-
body: dict[str, Any] = {
|
|
95
|
+
body: dict[str, Any] = {}
|
|
96
|
+
if content is not None:
|
|
97
|
+
body["content"] = content
|
|
98
|
+
resolved_markdown = _markdown_of(markdown)
|
|
99
|
+
if resolved_markdown is not None:
|
|
100
|
+
body["markdown"] = resolved_markdown
|
|
101
|
+
resolved_media = _media_of(media)
|
|
102
|
+
if resolved_media is not None:
|
|
103
|
+
body["media"] = resolved_media
|
|
104
|
+
if card is not None:
|
|
105
|
+
body["card"] = card
|
|
106
|
+
if keyboard is not None:
|
|
107
|
+
body["keyboard"] = keyboard
|
|
67
108
|
if event_id is not None:
|
|
68
109
|
body["event_id"] = event_id
|
|
69
110
|
elif msg_id is not None:
|
|
70
111
|
body["msg_id"] = msg_id
|
|
71
112
|
if msg_seq is not None:
|
|
72
113
|
body["msg_seq"] = msg_seq
|
|
73
|
-
if keyboard is not None:
|
|
74
|
-
body["keyboard"] = keyboard
|
|
75
114
|
return body
|
|
76
115
|
|
|
77
116
|
|
|
@@ -156,7 +195,7 @@ class Context:
|
|
|
156
195
|
message_id = _str_field(self.payload.d, "id")
|
|
157
196
|
return event_id, message_id
|
|
158
197
|
|
|
159
|
-
def _reply_target(self) -> tuple[
|
|
198
|
+
def _reply_target(self) -> tuple[Scene, str] | None:
|
|
160
199
|
"""被动回复的目标: 返回 ``(场景, openid)``, 不可回复时返回 None."""
|
|
161
200
|
event_name = self.payload.t or ""
|
|
162
201
|
if event_name in GROUP_REPLY_EVENTS:
|
|
@@ -167,23 +206,29 @@ class Context:
|
|
|
167
206
|
if event_name in C2C_REPLY_EVENTS:
|
|
168
207
|
user_openid = self.user_openid
|
|
169
208
|
if user_openid:
|
|
170
|
-
return "
|
|
209
|
+
return "c2c", user_openid
|
|
171
210
|
return None
|
|
172
211
|
return None
|
|
173
212
|
|
|
174
|
-
|
|
213
|
+
def build_reply(
|
|
175
214
|
self,
|
|
176
|
-
content: str,
|
|
177
215
|
*,
|
|
178
|
-
|
|
216
|
+
content: str | None = None,
|
|
217
|
+
markdown: str | MessageMarkdown | None = None,
|
|
218
|
+
media: str | MediaInfo | None = None,
|
|
219
|
+
card: MessageCard | None = None,
|
|
179
220
|
keyboard: Keyboard | None = None,
|
|
221
|
+
msg_seq: int | None = None,
|
|
180
222
|
seq_key: str | None = None,
|
|
181
|
-
) ->
|
|
182
|
-
"""
|
|
223
|
+
) -> PreparedReply | None:
|
|
224
|
+
"""生成一条被动回复的请求体, **不发送**.
|
|
225
|
+
|
|
226
|
+
锚点、``msg_seq``、``msg_type`` 全部由 SDK 算好, 调用方拿到就能直接发::
|
|
183
227
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
228
|
+
prepared = ctx.build_reply(markdown="**hi**", keyboard=kb)
|
|
229
|
+
if prepared is not None:
|
|
230
|
+
scene, openid, request = prepared
|
|
231
|
+
await group_messages.send_group_messages(openid, request)
|
|
187
232
|
|
|
188
233
|
锚点规则是**事件 ID 优先**:
|
|
189
234
|
|
|
@@ -196,15 +241,22 @@ class Context:
|
|
|
196
241
|
传了则以传入值为准, 并把该锚点的计数推进到该值. 平台上限是群聊 5 次、
|
|
197
242
|
单聊 4 次, 超出会被拒发.
|
|
198
243
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
244
|
+
Args:
|
|
245
|
+
content: 纯文本内容. 与 ``markdown`` 互斥, 但可以和 ``media`` 共存
|
|
246
|
+
作为富媒体的附带文本.
|
|
247
|
+
markdown: Markdown 文本, 或已构造好的 ``MessageMarkdown``.
|
|
248
|
+
media: 上传接口返回的 ``file_info``, 或已构造好的 ``MediaInfo``.
|
|
249
|
+
card: 图文卡片模型.
|
|
250
|
+
keyboard: 内嵌键盘(可带按钮).
|
|
251
|
+
msg_seq: 显式指定序号; 省略则按锚点自增.
|
|
252
|
+
seq_key: 计数用的键, 省略时用锚点本身.
|
|
253
|
+
|
|
254
|
+
Returns:
|
|
255
|
+
算好的 :class:`PreparedReply`; 当前事件不可被动回复时返回 None.
|
|
256
|
+
|
|
257
|
+
Raises:
|
|
258
|
+
ValueError: 当前事件不可被动回复 **且** 传了无法自洽的内容组合
|
|
259
|
+
(互斥校验由请求模型负责, 见 ``MessageSendRequestBase``).
|
|
208
260
|
"""
|
|
209
261
|
target = self._reply_target()
|
|
210
262
|
if target is None:
|
|
@@ -214,14 +266,121 @@ class Context:
|
|
|
214
266
|
if anchor is None:
|
|
215
267
|
return None
|
|
216
268
|
seq = self.bot.next_msg_seq(anchor, msg_seq, seq_key=seq_key)
|
|
217
|
-
body =
|
|
218
|
-
content,
|
|
269
|
+
body = _reply_body(
|
|
270
|
+
content=content,
|
|
271
|
+
markdown=markdown,
|
|
272
|
+
media=media,
|
|
273
|
+
card=card,
|
|
274
|
+
keyboard=keyboard,
|
|
219
275
|
event_id=event_id,
|
|
220
276
|
msg_id=None if event_id is not None else message_id,
|
|
221
277
|
msg_seq=seq,
|
|
278
|
+
)
|
|
279
|
+
scene, openid = target
|
|
280
|
+
return PreparedReply(
|
|
281
|
+
scene=scene,
|
|
282
|
+
openid=openid,
|
|
283
|
+
request=_make_request(scene, body),
|
|
284
|
+
)
|
|
285
|
+
|
|
286
|
+
async def send_reply(
|
|
287
|
+
self,
|
|
288
|
+
*,
|
|
289
|
+
content: str | None = None,
|
|
290
|
+
markdown: str | MessageMarkdown | None = None,
|
|
291
|
+
media: str | MediaInfo | None = None,
|
|
292
|
+
card: MessageCard | None = None,
|
|
293
|
+
keyboard: Keyboard | None = None,
|
|
294
|
+
msg_seq: int | None = None,
|
|
295
|
+
seq_key: str | None = None,
|
|
296
|
+
) -> str | None:
|
|
297
|
+
"""一步完成「算锚点 + 发出去」, 返回新消息 id.
|
|
298
|
+
|
|
299
|
+
参数与 :meth:`build_reply` 完全一致, 只是顺手发送. 不可被动回复的事件
|
|
300
|
+
返回 None.
|
|
301
|
+
"""
|
|
302
|
+
prepared = self.build_reply(
|
|
303
|
+
content=content,
|
|
304
|
+
markdown=markdown,
|
|
305
|
+
media=media,
|
|
306
|
+
card=card,
|
|
307
|
+
keyboard=keyboard,
|
|
308
|
+
msg_seq=msg_seq,
|
|
309
|
+
seq_key=seq_key,
|
|
310
|
+
)
|
|
311
|
+
if prepared is None:
|
|
312
|
+
return None
|
|
313
|
+
return await _post(prepared.scene, prepared.openid, prepared.request)
|
|
314
|
+
|
|
315
|
+
async def reply(
|
|
316
|
+
self,
|
|
317
|
+
content: str,
|
|
318
|
+
*,
|
|
319
|
+
msg_seq: int | None = None,
|
|
320
|
+
keyboard: Keyboard | None = None,
|
|
321
|
+
seq_key: str | None = None,
|
|
322
|
+
) -> str | None:
|
|
323
|
+
"""被动回复一条纯文本消息, 返回新消息 id.
|
|
324
|
+
|
|
325
|
+
等价于 ``send_reply(content=...)``; 规则见 :meth:`build_reply`.
|
|
326
|
+
需要 Markdown / 富媒体 / 卡片时用 :meth:`reply_markdown` /
|
|
327
|
+
:meth:`reply_media` / :meth:`send_reply`.
|
|
328
|
+
"""
|
|
329
|
+
return await self.send_reply(
|
|
330
|
+
content=content,
|
|
222
331
|
keyboard=keyboard,
|
|
332
|
+
msg_seq=msg_seq,
|
|
333
|
+
seq_key=seq_key,
|
|
334
|
+
)
|
|
335
|
+
|
|
336
|
+
async def reply_markdown(
|
|
337
|
+
self,
|
|
338
|
+
content: str,
|
|
339
|
+
*,
|
|
340
|
+
keyboard: Keyboard | None = None,
|
|
341
|
+
msg_seq: int | None = None,
|
|
342
|
+
seq_key: str | None = None,
|
|
343
|
+
) -> str | None:
|
|
344
|
+
"""被动回复一条 Markdown 消息(``msg_type=2``), 返回新消息 id.
|
|
345
|
+
|
|
346
|
+
Args:
|
|
347
|
+
content: Markdown 文本.
|
|
348
|
+
keyboard: 内嵌键盘, 按钮一般挂在 Markdown 消息上.
|
|
349
|
+
msg_seq: 显式指定序号; 省略则按锚点自增.
|
|
350
|
+
seq_key: 计数用的键, 省略时用锚点本身.
|
|
351
|
+
"""
|
|
352
|
+
return await self.send_reply(
|
|
353
|
+
markdown=content,
|
|
354
|
+
keyboard=keyboard,
|
|
355
|
+
msg_seq=msg_seq,
|
|
356
|
+
seq_key=seq_key,
|
|
357
|
+
)
|
|
358
|
+
|
|
359
|
+
async def reply_media(
|
|
360
|
+
self,
|
|
361
|
+
file_info: str,
|
|
362
|
+
*,
|
|
363
|
+
content: str | None = None,
|
|
364
|
+
keyboard: Keyboard | None = None,
|
|
365
|
+
msg_seq: int | None = None,
|
|
366
|
+
seq_key: str | None = None,
|
|
367
|
+
) -> str | None:
|
|
368
|
+
"""被动回复一条富媒体消息(``msg_type=7``), 返回新消息 id.
|
|
369
|
+
|
|
370
|
+
Args:
|
|
371
|
+
file_info: 上传接口返回的 ``file_info``.
|
|
372
|
+
content: 附带的说明文本, 省略则只发媒体.
|
|
373
|
+
keyboard: 内嵌键盘.
|
|
374
|
+
msg_seq: 显式指定序号; 省略则按锚点自增.
|
|
375
|
+
seq_key: 计数用的键, 省略时用锚点本身.
|
|
376
|
+
"""
|
|
377
|
+
return await self.send_reply(
|
|
378
|
+
media=file_info,
|
|
379
|
+
content=content,
|
|
380
|
+
keyboard=keyboard,
|
|
381
|
+
msg_seq=msg_seq,
|
|
382
|
+
seq_key=seq_key,
|
|
223
383
|
)
|
|
224
|
-
return await _send_to(*target, body)
|
|
225
384
|
|
|
226
385
|
async def send(self, content: str) -> str | None:
|
|
227
386
|
"""发一条主动消息(不带 ``event_id`` / ``msg_id``), 返回新消息 id.
|
|
@@ -230,30 +389,53 @@ class Context:
|
|
|
230
389
|
主动消息受平台推送频次限制, 能用 :meth:`reply` 就不要用这个.
|
|
231
390
|
"""
|
|
232
391
|
openid: str | None = None
|
|
233
|
-
scene = "group"
|
|
392
|
+
scene: Scene = "group"
|
|
234
393
|
group_openid = self.group_openid
|
|
235
394
|
if group_openid:
|
|
236
395
|
openid = group_openid
|
|
237
396
|
else:
|
|
238
|
-
scene = "
|
|
397
|
+
scene = "c2c"
|
|
239
398
|
openid = self.user_openid
|
|
240
399
|
if not openid:
|
|
241
400
|
return None
|
|
242
|
-
body =
|
|
243
|
-
|
|
401
|
+
body = _reply_body(
|
|
402
|
+
content=content,
|
|
403
|
+
markdown=None,
|
|
404
|
+
media=None,
|
|
405
|
+
card=None,
|
|
406
|
+
keyboard=None,
|
|
407
|
+
event_id=None,
|
|
408
|
+
msg_id=None,
|
|
409
|
+
msg_seq=None,
|
|
410
|
+
)
|
|
411
|
+
return await _post(scene, openid, _make_request(scene, body))
|
|
412
|
+
|
|
413
|
+
|
|
414
|
+
def _make_request(
|
|
415
|
+
scene: Scene,
|
|
416
|
+
body: dict[str, Any],
|
|
417
|
+
) -> SendGroupMessagesRequest | SendUserMessagesRequest:
|
|
418
|
+
"""按场景把请求体校验成对应的请求模型."""
|
|
419
|
+
if scene == "group":
|
|
420
|
+
return SendGroupMessagesRequest.model_validate(body)
|
|
421
|
+
return SendUserMessagesRequest.model_validate(body)
|
|
244
422
|
|
|
245
423
|
|
|
246
|
-
async def
|
|
424
|
+
async def _post(
|
|
425
|
+
scene: Scene,
|
|
426
|
+
openid: str,
|
|
427
|
+
request: SendGroupMessagesRequest | SendUserMessagesRequest,
|
|
428
|
+
) -> str:
|
|
247
429
|
"""按场景调用群聊或单聊发送接口, 返回新消息 id."""
|
|
248
430
|
if scene == "group":
|
|
249
431
|
response = await group_messages.send_group_messages(
|
|
250
432
|
openid,
|
|
251
|
-
SendGroupMessagesRequest
|
|
433
|
+
cast("SendGroupMessagesRequest", request),
|
|
252
434
|
)
|
|
253
435
|
return response.id
|
|
254
436
|
user_response = await user_api.send_user_messages(
|
|
255
437
|
openid,
|
|
256
|
-
SendUserMessagesRequest
|
|
438
|
+
cast("SendUserMessagesRequest", request),
|
|
257
439
|
)
|
|
258
440
|
return user_response.id
|
|
259
441
|
|
|
@@ -262,4 +444,5 @@ __all__ = [
|
|
|
262
444
|
"C2C_REPLY_EVENTS",
|
|
263
445
|
"GROUP_REPLY_EVENTS",
|
|
264
446
|
"Context",
|
|
447
|
+
"PreparedReply",
|
|
265
448
|
]
|
|
@@ -121,11 +121,16 @@ class Dispatcher:
|
|
|
121
121
|
return wildcard
|
|
122
122
|
return [*self._handlers.get(event_name, ()), *wildcard]
|
|
123
123
|
|
|
124
|
-
def submit(self, context: Context) -> None:
|
|
125
|
-
"""把一次事件处理丢进独立任务, 不阻塞 WebSocket 收包循环.
|
|
124
|
+
def submit(self, context: Context) -> asyncio.Task[None]:
|
|
125
|
+
"""把一次事件处理丢进独立任务, 不阻塞 WebSocket 收包循环.
|
|
126
|
+
|
|
127
|
+
Returns:
|
|
128
|
+
正在处理该事件的任务, 调用方可以 ``await`` 它在测试里等处理完成.
|
|
129
|
+
"""
|
|
126
130
|
task = asyncio.create_task(self._run(context), name=TASK_NAME)
|
|
127
131
|
self._tasks.add(task)
|
|
128
132
|
task.add_done_callback(self._tasks.discard)
|
|
133
|
+
return task
|
|
129
134
|
|
|
130
135
|
async def cancel_tasks(self) -> None:
|
|
131
136
|
"""取消并回收全部未完成的处理任务, 可重复调用.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""``qqbotsdk.app`` 内部共享的类型.
|
|
2
|
+
|
|
3
|
+
单独放一个叶子模块, 是为了让 :mod:`qqbotsdk.app.api` 与 :mod:`qqbotsdk.app.context`
|
|
4
|
+
都能引用这些类型而不产生循环导入: ``context`` 要用 ``SceneApi``, ``api`` 的返回值
|
|
5
|
+
又要标注 ``PreparedReply``, 两边直接互相 import 会成环.
|
|
6
|
+
|
|
7
|
+
本模块不导入 ``qqbotsdk.app`` 下的任何模块, 只依赖 ``qqbotsdk.model``。
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from typing import Literal, NamedTuple
|
|
11
|
+
|
|
12
|
+
from qqbotsdk.model.group.messages import SendGroupMessagesRequest
|
|
13
|
+
from qqbotsdk.model.user.messages import SendUserMessagesRequest
|
|
14
|
+
|
|
15
|
+
Scene = Literal["group", "c2c", "other"]
|
|
16
|
+
"""场景: 群聊 / 单聊 / 其它(既没有群 OpenID 也没有单聊用户 OpenID)."""
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class PreparedReply(NamedTuple):
|
|
20
|
+
"""一条已经算好锚点、序号与 ``msg_type`` 的被动回复.
|
|
21
|
+
|
|
22
|
+
由 :meth:`qqbotsdk.app.context.Context.build_reply` 产出, 三个字段可以按位置
|
|
23
|
+
解包::
|
|
24
|
+
|
|
25
|
+
scene, openid, request = ctx.build_reply(markdown="**hi**")
|
|
26
|
+
|
|
27
|
+
Attributes:
|
|
28
|
+
scene: 发送场景, ``"group"`` 或 ``"c2c"``.
|
|
29
|
+
openid: 目标群 / 用户的 openid.
|
|
30
|
+
request: 可以直接交给 ``send_group_messages`` / ``send_user_messages``
|
|
31
|
+
的请求模型.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
scene: Scene
|
|
35
|
+
openid: str
|
|
36
|
+
request: SendGroupMessagesRequest | SendUserMessagesRequest
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
__all__ = [
|
|
40
|
+
"PreparedReply",
|
|
41
|
+
"Scene",
|
|
42
|
+
]
|
|
@@ -63,6 +63,18 @@ class C2CMessageCreateEvent(QQBotBaseModel):
|
|
|
63
63
|
description="消息元素列表,message_type=103 引用消息时包含被引用内容",
|
|
64
64
|
)
|
|
65
65
|
|
|
66
|
+
@property
|
|
67
|
+
def sender_openid(self) -> str | None:
|
|
68
|
+
"""发送者的 openid, 不用自己判断该取哪个字段.
|
|
69
|
+
|
|
70
|
+
单聊场景取 ``author.user_openid``, 没有则回退 ``author.member_openid``,
|
|
71
|
+
最后才回退 ``author.id``; 取不到时返回 None.
|
|
72
|
+
"""
|
|
73
|
+
author = self.author
|
|
74
|
+
if author is None:
|
|
75
|
+
return None
|
|
76
|
+
return author.user_openid or author.member_openid or author.id
|
|
77
|
+
|
|
66
78
|
|
|
67
79
|
class C2CMsgReceiveEvent(QQBotBaseModel):
|
|
68
80
|
"""用户在机器人资料卡开启主动消息推送 (C2C_MSG_RECEIVE)."""
|
|
@@ -214,6 +214,18 @@ class GroupMessageEventBase(QQBotBaseModel):
|
|
|
214
214
|
description="消息元素列表,message_type=103 引用消息时包含被引用内容",
|
|
215
215
|
)
|
|
216
216
|
|
|
217
|
+
@property
|
|
218
|
+
def sender_openid(self) -> str | None:
|
|
219
|
+
"""发送者的 openid, 不用自己判断该取哪个字段.
|
|
220
|
+
|
|
221
|
+
群聊场景取 ``author.member_openid``, 没有则回退 ``author.user_openid``,
|
|
222
|
+
最后才回退 ``author.id``; 取不到时返回 None.
|
|
223
|
+
"""
|
|
224
|
+
author = self.author
|
|
225
|
+
if author is None:
|
|
226
|
+
return None
|
|
227
|
+
return author.member_openid or author.user_openid or author.id
|
|
228
|
+
|
|
217
229
|
|
|
218
230
|
class GroupAtMessageCreateEvent(GroupMessageEventBase):
|
|
219
231
|
"""用户在群里@机器人发送消息 (GROUP_AT_MESSAGE_CREATE)."""
|
|
@@ -154,6 +154,31 @@ class InteractionCreateEvent(QQBotBaseModel):
|
|
|
154
154
|
description="机器人 AppID",
|
|
155
155
|
)
|
|
156
156
|
|
|
157
|
+
@property
|
|
158
|
+
def button_data(self) -> str | None:
|
|
159
|
+
"""被点击按钮的 ``data`` 字段, 免去逐层钻 ``data.resolved``.
|
|
160
|
+
|
|
161
|
+
非按钮场景(快捷菜单用 ``feature_id``、消息反馈用 ``feedback_opt``)
|
|
162
|
+
也返回 ``resolved.button_data``, 平台在反馈场景下把回调数据放在这里.
|
|
163
|
+
"""
|
|
164
|
+
resolved = self.data.resolved if self.data is not None else None
|
|
165
|
+
return resolved.button_data if resolved is not None else None
|
|
166
|
+
|
|
167
|
+
@property
|
|
168
|
+
def button_id(self) -> str | None:
|
|
169
|
+
"""被点击按钮的 ``id`` 字段, 取不到时返回 None."""
|
|
170
|
+
resolved = self.data.resolved if self.data is not None else None
|
|
171
|
+
return resolved.button_id if resolved is not None else None
|
|
172
|
+
|
|
173
|
+
@property
|
|
174
|
+
def clicker_openid(self) -> str | None:
|
|
175
|
+
"""点按钮的人的 openid: 群聊取 ``group_member_openid``, 单聊取 ``user_openid``.
|
|
176
|
+
|
|
177
|
+
这两个字段的域差异是每个 bot 都会踩一次的点, 这里统一成一个名字.
|
|
178
|
+
频道场景两者都没有, 返回 None(频道用 ``InteractionResolved.user_id``).
|
|
179
|
+
"""
|
|
180
|
+
return self.group_member_openid or self.user_openid
|
|
181
|
+
|
|
157
182
|
|
|
158
183
|
__all__ = [
|
|
159
184
|
"InteractionAuthorizeData",
|
|
@@ -10,11 +10,18 @@ from qqbotsdk.model.sub.messages import (
|
|
|
10
10
|
MessageExtInfo,
|
|
11
11
|
MessageMarkdown,
|
|
12
12
|
MessageReference,
|
|
13
|
+
MessageSendRequestBase,
|
|
13
14
|
)
|
|
14
15
|
from qqbotsdk.model.sub.upload import UploadPrepareResponse
|
|
15
16
|
|
|
16
17
|
|
|
17
|
-
class SendGroupMessagesRequest(
|
|
18
|
+
class SendGroupMessagesRequest(MessageSendRequestBase):
|
|
19
|
+
"""发送群聊消息请求.
|
|
20
|
+
|
|
21
|
+
``msg_type`` 可省略: 会按填入的内容字段自动推导(``content``→0、
|
|
22
|
+
``markdown``→2、``media``→7、``card``→8), 并校验内容字段互斥.
|
|
23
|
+
"""
|
|
24
|
+
|
|
18
25
|
msg_type: Literal[0, 2, 7, 8] | None = Field(
|
|
19
26
|
default=None,
|
|
20
27
|
description="消息类型:0=纯文本(content),2=Markdown(markdown),7=富媒体(media),8=图文卡片(card)",
|
|
@@ -11,11 +11,18 @@ from qqbotsdk.model.sub.messages import (
|
|
|
11
11
|
MessageExtInfo,
|
|
12
12
|
MessageMarkdown,
|
|
13
13
|
MessageReference,
|
|
14
|
+
MessageSendRequestBase,
|
|
14
15
|
)
|
|
15
16
|
from qqbotsdk.model.sub.upload import UploadPrepareResponse
|
|
16
17
|
|
|
17
18
|
|
|
18
|
-
class SendUserMessagesRequest(
|
|
19
|
+
class SendUserMessagesRequest(MessageSendRequestBase):
|
|
20
|
+
"""发送单聊消息请求.
|
|
21
|
+
|
|
22
|
+
``msg_type`` 可省略: 会按填入的内容字段自动推导(``content``→0、
|
|
23
|
+
``markdown``→2、``input_notify``→6、``media``→7、``card``→8), 并校验内容字段互斥.
|
|
24
|
+
"""
|
|
25
|
+
|
|
19
26
|
msg_type: Literal[0, 2, 6, 7, 8] | None = Field(
|
|
20
27
|
default=None,
|
|
21
28
|
description="消息类型:0=纯文本(content),2=Markdown(markdown),6=输入中状态(input_notify),7=富媒体(media),8=图文卡片(card)",
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
"""测试辅助: 不连网关也能喂事件、不连 OpenAPI 也能断言请求.
|
|
2
|
+
|
|
3
|
+
用法::
|
|
4
|
+
|
|
5
|
+
import pytest
|
|
6
|
+
|
|
7
|
+
from qqbotsdk.app import Bot, Context
|
|
8
|
+
from qqbotsdk.testing import dispatch
|
|
9
|
+
|
|
10
|
+
async def test_echo() -> None:
|
|
11
|
+
bot = Bot()
|
|
12
|
+
seen: list[str | None] = []
|
|
13
|
+
|
|
14
|
+
@bot.on("GROUP_AT_MESSAGE_CREATE")
|
|
15
|
+
async def handler(ctx: Context) -> None:
|
|
16
|
+
seen.append(ctx.payload.id)
|
|
17
|
+
|
|
18
|
+
await dispatch(bot, "GROUP_AT_MESSAGE_CREATE", {"id": "m1", "content": "hi"})
|
|
19
|
+
assert seen == ["evt-1"]
|
|
20
|
+
|
|
21
|
+
HTTP 侧的可测入口在 :mod:`qqbotsdk.api.core` 的 ``use_session`` / ``set_session``,
|
|
22
|
+
两边合起来就是一套完整的离网测试面: 事件用 ``dispatch``, 请求用 ``use_session``.
|
|
23
|
+
|
|
24
|
+
本模块只依赖公开 API, 不碰任何私有实现.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
import json
|
|
28
|
+
from typing import Any
|
|
29
|
+
|
|
30
|
+
from qqbotsdk.app.bot import Bot
|
|
31
|
+
from qqbotsdk.ws.payload import GatewayPayload, OpCode
|
|
32
|
+
|
|
33
|
+
DEFAULT_EVENT_ID = "evt-1"
|
|
34
|
+
"""``make_payload`` 默认使用的事件 ID."""
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def make_payload(
|
|
38
|
+
event_name: str,
|
|
39
|
+
data: Any,
|
|
40
|
+
*,
|
|
41
|
+
event_id: str | None = DEFAULT_EVENT_ID,
|
|
42
|
+
seq: int = 1,
|
|
43
|
+
) -> GatewayPayload:
|
|
44
|
+
"""构造一帧 Dispatch 事件.
|
|
45
|
+
|
|
46
|
+
Args:
|
|
47
|
+
event_name: 事件名, 即网关帧的 ``t``.
|
|
48
|
+
data: 事件体, 即网关帧的 ``d``.
|
|
49
|
+
event_id: 事件 ID(信封 ``id``), 被动回复时作为 ``event_id``; 传 None 表示
|
|
50
|
+
不带事件 ID, 用于验证回退到 ``msg_id`` 的分支.
|
|
51
|
+
seq: 事件序号 ``s``.
|
|
52
|
+
|
|
53
|
+
Returns:
|
|
54
|
+
可以直接交给 :meth:`Bot.dispatch` 的 :class:`GatewayPayload`.
|
|
55
|
+
"""
|
|
56
|
+
return GatewayPayload.model_validate(
|
|
57
|
+
{
|
|
58
|
+
"op": OpCode.DISPATCH,
|
|
59
|
+
"s": seq,
|
|
60
|
+
"t": event_name,
|
|
61
|
+
"id": event_id,
|
|
62
|
+
"d": data,
|
|
63
|
+
}
|
|
64
|
+
)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def parse_frame(frame: str | bytes | dict[str, Any]) -> GatewayPayload:
|
|
68
|
+
"""把原始帧(JSON 文本或已解析的 dict)解析成 :class:`GatewayPayload`."""
|
|
69
|
+
if isinstance(frame, dict):
|
|
70
|
+
return GatewayPayload.model_validate(frame)
|
|
71
|
+
return GatewayPayload.model_validate(json.loads(frame))
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
async def dispatch(
|
|
75
|
+
bot: Bot,
|
|
76
|
+
event_name: str,
|
|
77
|
+
data: Any,
|
|
78
|
+
*,
|
|
79
|
+
event_id: str | None = DEFAULT_EVENT_ID,
|
|
80
|
+
seq: int = 1,
|
|
81
|
+
) -> None:
|
|
82
|
+
"""构造一帧事件并**等待**处理完成.
|
|
83
|
+
|
|
84
|
+
handler / 中间件抛出的异常会按正常路径交给 ``on_error``, 不会从这里冒出来;
|
|
85
|
+
要断言异常请注册 ``on_error`` 并收集参数.
|
|
86
|
+
|
|
87
|
+
Args:
|
|
88
|
+
bot: 目标机器人.
|
|
89
|
+
event_name: 事件名.
|
|
90
|
+
data: 事件体.
|
|
91
|
+
event_id: 事件 ID, 传 None 表示不带.
|
|
92
|
+
seq: 事件序号.
|
|
93
|
+
"""
|
|
94
|
+
payload = make_payload(event_name, data, event_id=event_id, seq=seq)
|
|
95
|
+
task = bot.dispatch(payload)
|
|
96
|
+
if task is not None:
|
|
97
|
+
await task
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
async def dispatch_frame(bot: Bot, frame: str | bytes | dict[str, Any]) -> None:
|
|
101
|
+
"""把一段原始网关帧喂给 bot 并等待处理完成.
|
|
102
|
+
|
|
103
|
+
与 :func:`dispatch` 的区别是接收**原始帧**, 便于直接把网关日志里的报文
|
|
104
|
+
复制过来做回归测试.
|
|
105
|
+
"""
|
|
106
|
+
task = bot.dispatch(parse_frame(frame))
|
|
107
|
+
if task is not None:
|
|
108
|
+
await task
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
__all__ = [
|
|
112
|
+
"DEFAULT_EVENT_ID",
|
|
113
|
+
"dispatch",
|
|
114
|
+
"dispatch_frame",
|
|
115
|
+
"make_payload",
|
|
116
|
+
"parse_frame",
|
|
117
|
+
]
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|