qqbotsdk-py 2.2.1__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.1 → qqbotsdk_py-2.3.0}/PKG-INFO +3 -3
  2. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/pyproject.toml +3 -3
  3. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/pyproject.toml.orig +3 -3
  4. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/user.py +17 -0
  5. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/context.py +3 -2
  6. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/__init__.py +2 -0
  7. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/group.py +41 -4
  8. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/member.py +4 -0
  9. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/messages.py +1 -1
  10. qqbotsdk_py-2.3.0/src/qqbotsdk/model/user/info.py +40 -0
  11. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/user/messages.py +1 -1
  12. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/README.md +0 -0
  13. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/agent.md +0 -0
  14. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/bot.py +0 -0
  15. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/agent.md +0 -0
  16. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/blacklist.py +0 -0
  17. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/join_request.py +0 -0
  18. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/manage.py +0 -0
  19. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/messages.py +0 -0
  20. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/mute.py +0 -0
  21. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/group/strategy.py +0 -0
  22. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/interaction.py +0 -0
  23. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/media.py +0 -0
  24. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/menu.py +0 -0
  25. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/api/panel.py +0 -0
  26. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/__init__.py +0 -0
  27. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/agent.md +0 -0
  28. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/api.py +0 -0
  29. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/bot.py +0 -0
  30. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/dispatch.py +0 -0
  31. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/keyboard.py +0 -0
  32. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/app/types.py +0 -0
  33. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/agent.md +0 -0
  34. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/bot.py +0 -0
  35. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/agent.md +0 -0
  36. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/c2c.py +0 -0
  37. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/event/interaction.py +0 -0
  38. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/agent.md +0 -0
  39. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/blacklist.py +0 -0
  40. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/join_request.py +0 -0
  41. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/mute.py +0 -0
  42. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/group/strategy.py +0 -0
  43. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/interaction.py +0 -0
  44. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/media.py +0 -0
  45. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/menu.py +0 -0
  46. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/panel.py +0 -0
  47. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/user/agent.md +0 -0
  48. {qqbotsdk_py-2.2.1 → qqbotsdk_py-2.3.0}/src/qqbotsdk/model/user/stream_messages.py +0 -0
  49. {qqbotsdk_py-2.2.1 → 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.1
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.1
8
- Requires-Dist: qqbotsdk-guild-py>=2.2.1 ; 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.1"
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.1"]
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.1"]
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.1"
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.1",
11
+ "qqbotsdk-base-py>=2.3.0",
12
12
  ]
13
13
 
14
14
  [project.optional-dependencies]
15
- guild = ["qqbotsdk-guild-py>=2.2.1"]
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,
@@ -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