qqbotsdk-py 2.2.0__tar.gz → 2.3.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.2.0 → qqbotsdk_py-2.3.0}/PKG-INFO +3 -3
  2. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/pyproject.toml +3 -3
  3. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/pyproject.toml.orig +3 -3
  4. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/user.py +17 -0
  5. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/bot.py +28 -8
  6. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/context.py +3 -2
  7. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/__init__.py +2 -0
  8. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/group.py +41 -4
  9. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/member.py +4 -0
  10. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/messages.py +1 -1
  11. qqbotsdk_py-2.3.0/src/qqbotsdk/model/user/info.py +40 -0
  12. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/user/messages.py +1 -1
  13. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/README.md +0 -0
  14. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/agent.md +0 -0
  15. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/bot.py +0 -0
  16. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/agent.md +0 -0
  17. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/blacklist.py +0 -0
  18. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/join_request.py +0 -0
  19. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/manage.py +0 -0
  20. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/messages.py +0 -0
  21. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/mute.py +0 -0
  22. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/strategy.py +0 -0
  23. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/interaction.py +0 -0
  24. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/media.py +0 -0
  25. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/menu.py +0 -0
  26. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/panel.py +0 -0
  27. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/__init__.py +0 -0
  28. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/agent.md +0 -0
  29. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/api.py +0 -0
  30. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/dispatch.py +0 -0
  31. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/keyboard.py +0 -0
  32. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/types.py +0 -0
  33. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/agent.md +0 -0
  34. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/bot.py +0 -0
  35. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/agent.md +0 -0
  36. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/c2c.py +0 -0
  37. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/interaction.py +0 -0
  38. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/agent.md +0 -0
  39. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/blacklist.py +0 -0
  40. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/join_request.py +0 -0
  41. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/mute.py +0 -0
  42. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/strategy.py +0 -0
  43. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/interaction.py +0 -0
  44. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/media.py +0 -0
  45. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/menu.py +0 -0
  46. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/panel.py +0 -0
  47. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/user/agent.md +0 -0
  48. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/user/stream_messages.py +0 -0
  49. {qqbotsdk_py-2.2.0 → qqbotsdk_py-2.3.0}/src/qqbotsdk/testing.py +0 -0
@@ -1,11 +1,11 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: qqbotsdk-py
3
- Version: 2.2.0
3
+ Version: 2.3.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.2.0
8
- Requires-Dist: qqbotsdk-guild-py>=2.2.0 ; extra == 'guild'
7
+ Requires-Dist: qqbotsdk-base-py>=2.3.0
8
+ Requires-Dist: qqbotsdk-guild-py>=2.3.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.2.0"
3
+ version = "2.3.0"
4
4
  description = "QQ 官方机器人 SDK:群聊 / 单聊 / 素材 / 互动"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
7
- dependencies = ["qqbotsdk-base-py>=2.2.0"]
7
+ dependencies = ["qqbotsdk-base-py>=2.3.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.2.0"]
14
+ guild = ["qqbotsdk-guild-py>=2.3.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.2.0"
3
+ version = "2.3.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.2.0",
11
+ "qqbotsdk-base-py>=2.3.0",
12
12
  ]
13
13
 
14
14
  [project.optional-dependencies]
15
- guild = ["qqbotsdk-guild-py>=2.2.0"]
15
+ guild = ["qqbotsdk-guild-py>=2.3.0"]
16
16
 
17
17
  [build-system]
18
18
  requires = ["uv_build>=0.13.5,<0.14.0"]
@@ -3,6 +3,7 @@ from qqbotsdk.model.sub.upload import (
3
3
  UploadPartFinishRequest,
4
4
  UploadPrepareRequest,
5
5
  )
6
+ from qqbotsdk.model.user.info import GetUserInfoResponse
6
7
  from qqbotsdk.model.user.messages import (
7
8
  PrepareUserUploadResponse,
8
9
  SendUserMessagesRequest,
@@ -16,6 +17,22 @@ from qqbotsdk.model.user.stream_messages import (
16
17
  )
17
18
 
18
19
 
20
+ async def get_user_info(
21
+ user_openid: str,
22
+ ) -> GetUserInfoResponse:
23
+ """获取用户基本信息.
24
+
25
+ 官方 2026-11-16 新增, 频率 10 QPS. 与好友无关系时平台返回 ``40184001``.
26
+ 响应里的 ``allow_proactive_msg`` 可用于判断能否给该用户下发主动消息.
27
+ """
28
+ async with session.get(
29
+ f"/v2/users/{user_openid}/info",
30
+ ) as resp:
31
+ result = await resp.json()
32
+
33
+ return GetUserInfoResponse.model_validate(result)
34
+
35
+
19
36
  async def send_user_messages(
20
37
  user_openid: str,
21
38
  payload: SendUserMessagesRequest,
@@ -75,23 +75,24 @@ def _remember_msg_seq(key: str, seq: int) -> None:
75
75
  _MSG_SEQ_CACHE.pop(next(iter(_MSG_SEQ_CACHE)))
76
76
 
77
77
 
78
- def resolve_intents(intents: Intents | None = None) -> Intents:
79
- """决定本次使用的订阅位: 显式入参 > ``INTENTS`` 环境变量 > ``DEFAULT_INTENTS``.
78
+ def _resolve_intents_with_source(intents: Intents | None) -> tuple[Intents, str]:
79
+ """解析订阅位, 同时返回它的来源(用于启动日志).
80
80
 
81
81
  Args:
82
- intents: 代码里显式指定的订阅位, 传了就直接用, 不读环境变量.
82
+ intents: 代码里显式指定的订阅位; 传 None 表示没指定.
83
83
 
84
84
  Returns:
85
- 最终生效的 :class:`Intents`.
85
+ ``(订阅位, 来源说明)``, 来源是 ``"显式入参"`` / ``"INTENTS 环境变量"`` /
86
+ ``"默认值"`` 之一.
86
87
 
87
88
  Raises:
88
89
  ValueError: ``INTENTS`` 环境变量不是合法的十进制 / ``0x`` 十六进制掩码.
89
90
  """
90
91
  if intents is not None:
91
- return intents
92
+ return intents, "显式入参"
92
93
  raw = os.getenv(INTENTS_ENV, "").strip()
93
94
  if not raw:
94
- return DEFAULT_INTENTS
95
+ return DEFAULT_INTENTS, "默认值"
95
96
  try:
96
97
  mask = int(raw, 0) # 十进制或 0x 十六进制
97
98
  except ValueError:
@@ -100,7 +101,22 @@ def resolve_intents(intents: Intents | None = None) -> Intents:
100
101
  ) from None
101
102
  if mask < 0:
102
103
  raise ValueError(f"{INTENTS_ENV} 不能为负数,实际: {mask}")
103
- return Intents(mask)
104
+ return Intents(mask), f"{INTENTS_ENV} 环境变量"
105
+
106
+
107
+ def resolve_intents(intents: Intents | None = None) -> Intents:
108
+ """决定本次使用的订阅位: 显式入参 > ``INTENTS`` 环境变量 > ``DEFAULT_INTENTS``.
109
+
110
+ Args:
111
+ intents: 代码里显式指定的订阅位, 传了就直接用, 不读环境变量.
112
+
113
+ Returns:
114
+ 最终生效的 :class:`Intents`.
115
+
116
+ Raises:
117
+ ValueError: ``INTENTS`` 环境变量不是合法的十进制 / ``0x`` 十六进制掩码.
118
+ """
119
+ return _resolve_intents_with_source(intents)[0]
104
120
 
105
121
 
106
122
  class Bot:
@@ -120,13 +136,17 @@ class Bot:
120
136
  url: str | None = None,
121
137
  auto_reconnect: bool = True,
122
138
  ) -> None:
123
- self._intents = resolve_intents(intents)
139
+ resolved, source = _resolve_intents_with_source(intents)
140
+ self._intents = resolved
124
141
  self._url = url
125
142
  self._auto_reconnect = auto_reconnect
126
143
  self._dispatcher = Dispatcher()
127
144
  self._ws: QQBotWebSocket | None = None
128
145
  self._stop_event = asyncio.Event()
129
146
  self._running = False
147
+ # 订阅位来源写进启动日志: INTENTS 环境变量是运维侧的静默覆盖开关,
148
+ # 出错时(例如误收窄导致收不到事件)要能一眼看出订阅范围是从哪来的.
149
+ logger.info(f"订阅位 intents={int(self._intents)} 来源={source}")
130
150
 
131
151
  @property
132
152
  def intents(self) -> Intents:
@@ -238,8 +238,9 @@ class Context:
238
238
 
239
239
  ``msg_seq`` 用于同一锚点上的多条回复去重(平台对同一个 msg_id + msg_seq
240
240
  重复发送会返回 40054005): 不传时由 Bot 按锚点自增(首次 1, 第二次 2),
241
- 传了则以传入值为准, 并把该锚点的计数推进到该值. 平台上限是群聊 5 次、
242
- 单聊 4 次, 超出会被拒发.
241
+ 传了则以传入值为准, 并把该锚点的计数推进到该值. 平台上限是群聊 5 次
242
+ (机器人开发者是群主/管理员时 50 次)、单聊 4 次, 超出会被拒发; 群聊被动
243
+ 回复窗口自 2026-11-17 起是 60 分钟(此前 5 分钟).
243
244
 
244
245
  Args:
245
246
  content: 纯文本内容. 与 ``markdown`` 互斥, 但可以和 ``media`` 共存
@@ -23,6 +23,7 @@ from qqbotsdk.model.event.c2c import (
23
23
  )
24
24
  from qqbotsdk.model.event.group import (
25
25
  EventArkData,
26
+ EventMentionUser,
26
27
  EventMessageAttachment,
27
28
  EventMessageScene,
28
29
  EventMsgElement,
@@ -84,6 +85,7 @@ __all__ = [
84
85
  "C2CMsgReceiveEvent",
85
86
  "C2CMsgRejectEvent",
86
87
  "EventArkData",
88
+ "EventMentionUser",
87
89
  "EventMessageAttachment",
88
90
  "EventMessageScene",
89
91
  "EventMsgElement",
@@ -20,8 +20,8 @@ class EventUser(QQBotBaseModel):
20
20
  """群聊与单聊事件里的发送者 / 被@用户.
21
21
 
22
22
  与 ``qqbotsdk.model.guild.member.User`` 不同: 这里带有 ``user_openid`` /
23
- ``member_openid`` / ``member_role`` 三个 QQ 单群聊场景专用字段, 且不含
24
- ``avatar``. guild 包是可选依赖, 本包不能反向引用.
23
+ ``member_openid`` / ``member_role`` 三个 QQ 单群聊场景专用字段. guild 包是
24
+ 可选依赖, 本包不能反向引用.
25
25
  """
26
26
 
27
27
  id: str | None = Field(
@@ -32,6 +32,10 @@ class EventUser(QQBotBaseModel):
32
32
  default=None,
33
33
  description="用户昵称",
34
34
  )
35
+ avatar: str | None = Field(
36
+ default=None,
37
+ description="用户头像 URL(2026-11-16 起随消息事件下发)",
38
+ )
35
39
  bot: bool | None = Field(
36
40
  default=None,
37
41
  description="是否为机器人",
@@ -56,6 +60,27 @@ class EventUser(QQBotBaseModel):
56
60
  default=None,
57
61
  description="群内角色:member=普通成员,admin=管理员,owner=群主",
58
62
  )
63
+ member_nickname: str | None = Field(
64
+ default=None,
65
+ description="群成员昵称(2026-11-16 起随群消息事件下发,可不同于 username)",
66
+ )
67
+
68
+
69
+ class EventMentionUser(EventUser):
70
+ """``mentions`` 数组里的被@用户.
71
+
72
+ 比 ``EventUser`` 多两个只在 mentions 元素里出现的字段: ``is_you``
73
+ (是否@的是机器人自己) 与 ``scope`` (@全体还是@单个成员).
74
+ """
75
+
76
+ is_you: bool | None = Field(
77
+ default=None,
78
+ description="是否@的是机器人自己",
79
+ )
80
+ scope: Literal["all", "single"] | None = Field(
81
+ default=None,
82
+ description="@ 的范围:all=@全体成员,single=@单个成员",
83
+ )
59
84
 
60
85
 
61
86
  class EventMessageScene(QQBotBaseModel):
@@ -185,6 +210,10 @@ class GroupMessageEventBase(QQBotBaseModel):
185
210
  default=None,
186
211
  description="群 OpenID",
187
212
  )
213
+ union_group_openid: str | None = Field(
214
+ default=None,
215
+ description="群统一标识(2026-11-16 起下发,跨应用关联同一群时有效)",
216
+ )
188
217
  timestamp: str | None = Field(
189
218
  default=None,
190
219
  description="消息发送时间,RFC3339 格式",
@@ -201,9 +230,9 @@ class GroupMessageEventBase(QQBotBaseModel):
201
230
  default=None,
202
231
  description="消息附件",
203
232
  )
204
- mentions: list[EventUser] | None = Field(
233
+ mentions: list[EventMentionUser] | None = Field(
205
234
  default=None,
206
- description="消息中@的用户列表,不含@机器人自身",
235
+ description="消息中@的用户列表,不含@机器人自身;元素带 is_you/scope",
207
236
  )
208
237
  ark_data: EventArkData | None = Field(
209
238
  default=None,
@@ -250,6 +279,10 @@ class GroupRobotOperationEvent(QQBotBaseModel):
250
279
  default=None,
251
280
  description="群 OpenID",
252
281
  )
282
+ union_group_openid: str | None = Field(
283
+ default=None,
284
+ description="群统一标识(2026-11-16 起下发)",
285
+ )
253
286
  op_member_openid: str | None = Field(
254
287
  default=None,
255
288
  description="执行操作的群成员 OpenID",
@@ -283,6 +316,10 @@ class GroupMemberChangeEvent(QQBotBaseModel):
283
316
  default=None,
284
317
  description="群 OpenID",
285
318
  )
319
+ union_group_openid: str | None = Field(
320
+ default=None,
321
+ description="群统一标识(2026-11-16 起下发)",
322
+ )
286
323
  member_openid: str | None = Field(
287
324
  default=None,
288
325
  description="成员的 OpenID",
@@ -10,6 +10,10 @@ class GroupInfo(QQBotBaseModel):
10
10
  default=None,
11
11
  description="群 OpenID",
12
12
  )
13
+ union_group_openid: str | None = Field(
14
+ default=None,
15
+ description="群统一标识(2026-11-16 起返回,跨应用关联同一群时有效)",
16
+ )
13
17
  group_name: str | None = Field(
14
18
  default=None,
15
19
  description="群名称",
@@ -40,7 +40,7 @@ class SendGroupMessagesRequest(MessageSendRequestBase):
40
40
  )
41
41
  msg_id: str | None = Field(
42
42
  default=None,
43
- description="被动回复的消息 ID,从 GROUP_AT_MESSAGE_CREATE 等事件的 d.id 获取,5 分钟内有效",
43
+ description="被动回复的消息 ID,从 GROUP_AT_MESSAGE_CREATE 等事件的 d.id 获取,60 分钟内有效(2026-11-17 起,此前为 5 分钟)",
44
44
  )
45
45
  event_id: str | None = Field(
46
46
  default=None,
@@ -0,0 +1,40 @@
1
+ """用户信息模型 (2026-11-16 新增 ``GET /v2/users/{user_openid}/info``)."""
2
+
3
+ from pydantic import Field
4
+
5
+ from qqbotsdk.model.core import QQBotBaseModel
6
+
7
+
8
+ class UserInfo(QQBotBaseModel):
9
+ """用户基本信息.
10
+
11
+ 官方 2026-11-16 新增. 与 ``C2CUser``(事件里的发送者) 不同, 这里还带
12
+ ``allow_proactive_msg``, 可以用来判断能否给该用户发主动消息.
13
+ """
14
+
15
+ union_openid: str | None = Field(
16
+ default=None,
17
+ description="跨应用关联用户 openid,当绑定了 3 方应用时有效",
18
+ )
19
+ username: str | None = Field(
20
+ default=None,
21
+ description="用户名",
22
+ )
23
+ avatar: str | None = Field(
24
+ default=None,
25
+ description="用户头像原图 URL",
26
+ )
27
+ allow_proactive_msg: bool | None = Field(
28
+ default=None,
29
+ description="是否接收主动推送,true 表示接受主动推送",
30
+ )
31
+
32
+
33
+ class GetUserInfoResponse(UserInfo):
34
+ """获取用户基本信息响应 (``GET /v2/users/{user_openid}/info``)."""
35
+
36
+
37
+ __all__ = [
38
+ "GetUserInfoResponse",
39
+ "UserInfo",
40
+ ]
@@ -41,7 +41,7 @@ class SendUserMessagesRequest(MessageSendRequestBase):
41
41
  )
42
42
  msg_id: str | None = Field(
43
43
  default=None,
44
- description="被动回复的消息 ID,从 C2C_MESSAGE_CREATE 等事件的 d.id 获取,5 分钟内有效",
44
+ description="被动回复的消息 ID,从 C2C_MESSAGE_CREATE 等事件的 d.id 获取。也可传 GROUP_AT_MESSAGE_CREATE / GROUP_MESSAGE_CREATE 事件的 d.id 私聊回复该群消息发送者(要求好友关系,user_openid 必须是该消息发送者,次数与群内回复共用同一 msg_id 的上限)",
45
45
  )
46
46
  event_id: str | None = Field(
47
47
  default=None,
File without changes