qqbotsdk-py 2.0.0__tar.gz → 2.1.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 (46) hide show
  1. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/PKG-INFO +3 -3
  2. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/pyproject.toml +3 -3
  3. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/pyproject.toml.orig +3 -3
  4. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/app/api.py +20 -2
  5. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/app/bot.py +38 -15
  6. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/app/context.py +27 -4
  7. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/README.md +0 -0
  8. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/agent.md +0 -0
  9. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/bot.py +0 -0
  10. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/group/agent.md +0 -0
  11. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/group/blacklist.py +0 -0
  12. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/group/join_request.py +0 -0
  13. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/group/manage.py +0 -0
  14. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/group/messages.py +0 -0
  15. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/group/mute.py +0 -0
  16. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/group/strategy.py +0 -0
  17. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/interaction.py +0 -0
  18. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/media.py +0 -0
  19. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/menu.py +0 -0
  20. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/panel.py +0 -0
  21. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/api/user.py +0 -0
  22. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/app/__init__.py +0 -0
  23. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/app/agent.md +0 -0
  24. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/app/dispatch.py +0 -0
  25. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/app/keyboard.py +0 -0
  26. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/agent.md +0 -0
  27. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/bot.py +0 -0
  28. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/event/__init__.py +0 -0
  29. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/event/agent.md +0 -0
  30. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/event/c2c.py +0 -0
  31. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/event/group.py +0 -0
  32. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/event/interaction.py +0 -0
  33. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/group/agent.md +0 -0
  34. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/group/blacklist.py +0 -0
  35. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/group/join_request.py +0 -0
  36. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/group/member.py +0 -0
  37. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/group/messages.py +0 -0
  38. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/group/mute.py +0 -0
  39. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/group/strategy.py +0 -0
  40. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/interaction.py +0 -0
  41. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/media.py +0 -0
  42. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/menu.py +0 -0
  43. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/panel.py +0 -0
  44. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/user/agent.md +0 -0
  45. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.0}/src/qqbotsdk/model/user/messages.py +0 -0
  46. {qqbotsdk_py-2.0.0 → qqbotsdk_py-2.1.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.1.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.1.0
8
+ Requires-Dist: qqbotsdk-guild-py>=2.1.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.1.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.1.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.1.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.1.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.1.0",
12
12
  ]
13
13
 
14
14
  [project.optional-dependencies]
15
- guild = ["qqbotsdk-guild-py>=2.0.0"]
15
+ guild = ["qqbotsdk-guild-py>=2.1.0"]
16
16
 
17
17
  [build-system]
18
18
  requires = ["uv_build>=0.13.5,<0.14.0"]
@@ -271,13 +271,31 @@ class SceneApi:
271
271
  body["content"] = content
272
272
  return await _send(scene, openid, body)
273
273
 
274
- async def reply(self, content: str, *, msg_seq: int | None = None) -> str | None:
274
+ async def reply(
275
+ self,
276
+ content: str,
277
+ *,
278
+ msg_seq: int | None = None,
279
+ keyboard: Keyboard | None = None,
280
+ seq_key: str | None = None,
281
+ ) -> str | None:
275
282
  """被动回复一条文本消息, 直接委托 :meth:`Context.reply`.
276
283
 
277
284
  锚点(event_id 优先, 其次 msg_id)与 msg_seq 自增都在 Context / Bot 里,
278
285
  这里不重复实现; 不可回复的事件返回 None.
286
+
287
+ Args:
288
+ content: 文本内容.
289
+ msg_seq: 显式指定序号; 省略则由 Bot 按锚点自增.
290
+ keyboard: 内嵌键盘, 省略则不带键盘.
291
+ seq_key: 计数用的键, 省略时用锚点本身.
279
292
  """
280
- return await self._ctx.reply(content, msg_seq=msg_seq)
293
+ return await self._ctx.reply(
294
+ content,
295
+ msg_seq=msg_seq,
296
+ keyboard=keyboard,
297
+ seq_key=seq_key,
298
+ )
281
299
 
282
300
  async def recall(self, message_id: str) -> None:
283
301
  """撤回一条消息: 群聊走群撤回接口, 单聊走单聊撤回接口."""
@@ -47,6 +47,25 @@ from qqbotsdk.ws.payload import GatewayPayload, OpCode
47
47
  MSG_SEQ_CACHE_LIMIT: Final = 512
48
48
  """msg_seq 缓存的最大锚点数, 超出后淘汰最久未使用的锚点."""
49
49
 
50
+ # 被动回复锚点(事件 ID 或消息 ID) -> 已用到的最大 msg_seq.
51
+ # 放模块级而不是 Bot 实例上: 平台只认「msg_id + msg_seq」是否重复, 与是哪个 Bot
52
+ # 实例发的无关. 多实例(分片 / 多机器人代管同一批会话)共用一份计数才不会各自从 1
53
+ # 重来. 键是普通字符串, 不会因此持有 Bot 或会话相关的引用.
54
+ _MSG_SEQ_CACHE: dict[str, int] = {}
55
+
56
+
57
+ def reset_msg_seq_cache() -> None:
58
+ """清空全局 msg_seq 计数, 仅供测试与长驻进程的兜底清理使用."""
59
+ _MSG_SEQ_CACHE.clear()
60
+
61
+
62
+ def _remember_msg_seq(key: str, seq: int) -> None:
63
+ """写入锚点的序号(只增不减)并按上限淘汰最久未使用的条目."""
64
+ previous = _MSG_SEQ_CACHE.pop(key, 0)
65
+ _MSG_SEQ_CACHE[key] = seq if seq > previous else previous
66
+ while len(_MSG_SEQ_CACHE) > MSG_SEQ_CACHE_LIMIT:
67
+ _MSG_SEQ_CACHE.pop(next(iter(_MSG_SEQ_CACHE)))
68
+
50
69
 
51
70
  class Bot:
52
71
  """把网关连接和事件注册表绑在一起的机器人实例.
@@ -71,8 +90,6 @@ class Bot:
71
90
  self._ws: QQBotWebSocket | None = None
72
91
  self._stop_event = asyncio.Event()
73
92
  self._running = False
74
- # 被动回复锚点(事件 ID 或消息 ID) -> 已用到的最大 msg_seq
75
- self._msg_seq_cache: dict[str, int] = {}
76
93
 
77
94
  def __repr__(self) -> str:
78
95
  return (
@@ -168,32 +185,37 @@ class Bot:
168
185
 
169
186
  # ------------------------------------------------------------ msg_seq
170
187
 
171
- def next_msg_seq(self, anchor: str, msg_seq: int | None = None) -> int:
188
+ def next_msg_seq(
189
+ self,
190
+ anchor: str,
191
+ msg_seq: int | None = None,
192
+ *,
193
+ seq_key: str | None = None,
194
+ ) -> int:
172
195
  """返回该被动回复锚点本次使用的 ``msg_seq``, 供 :meth:`Context.reply` 调用.
173
196
 
174
197
  Args:
175
198
  anchor: 本次被动回复的锚点, 即事件 ID 或消息 ID.
176
199
  msg_seq: 调用方显式指定的序号; 传了就以它为准, 并把该锚点的计数
177
200
  推进到该值, 之后的自增不会回头撞上已用过的序号.
201
+ seq_key: 计数用的键, 省略时用 ``anchor``. 自己拼请求直连
202
+ ``send_group_messages`` 时, 用同一个键调一次本方法登记, 再回来
203
+ 的 ``ctx.reply`` 就不会从 1 重新开始而触发 40054005.
178
204
 
179
205
  不显式指定时按锚点自增: 同一锚点第一次是 1, 第二次是 2, 以此类推,
180
- 避免平台返回 40054005 (相同 msg_id + msg_seq 重复发送). 缓存按
181
- ``MSG_SEQ_CACHE_LIMIT`` 限制条目数, 超出后淘汰最久未使用的锚点.
206
+ 避免平台返回 40054005 (相同 msg_id + msg_seq 重复发送). 计数**按锚点全局
207
+ 共享**, 不随 ``Bot`` 实例隔离: 同一进程内多个 ``Bot`` 实例命中同一锚点时
208
+ 继续往下排, 而不是各自从 1 开始. 缓存按 ``MSG_SEQ_CACHE_LIMIT`` 限制
209
+ 条目数, 超出后淘汰最久未使用的锚点.
182
210
  """
211
+ key = seq_key or anchor
183
212
  if msg_seq is not None:
184
- self._remember_msg_seq(anchor, msg_seq)
213
+ _remember_msg_seq(key, msg_seq)
185
214
  return msg_seq
186
- seq = self._msg_seq_cache.get(anchor, 0) + 1
187
- self._remember_msg_seq(anchor, seq)
215
+ seq = _MSG_SEQ_CACHE.get(key, 0) + 1
216
+ _remember_msg_seq(key, seq)
188
217
  return seq
189
218
 
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
219
  # ------------------------------------------------------------ 生命周期
198
220
 
199
221
  async def start(self) -> None:
@@ -256,4 +278,5 @@ class Bot:
256
278
  __all__ = [
257
279
  "MSG_SEQ_CACHE_LIMIT",
258
280
  "Bot",
281
+ "reset_msg_seq_cache",
259
282
  ]
@@ -17,6 +17,7 @@ from qqbotsdk.api.group import messages as group_messages
17
17
  from qqbotsdk.app.api import SceneApi
18
18
  from qqbotsdk.model.core import QQBotBaseModel
19
19
  from qqbotsdk.model.group.messages import SendGroupMessagesRequest
20
+ from qqbotsdk.model.sub.messages import Keyboard
20
21
  from qqbotsdk.model.user.messages import SendUserMessagesRequest
21
22
  from qqbotsdk.ws.payload import GatewayPayload
22
23
 
@@ -52,6 +53,7 @@ def _request_body(
52
53
  event_id: str | None,
53
54
  msg_id: str | None,
54
55
  msg_seq: int | None,
56
+ keyboard: Keyboard | None = None,
55
57
  ) -> dict[str, Any]:
56
58
  """拼纯文本消息的请求体.
57
59
 
@@ -68,6 +70,8 @@ def _request_body(
68
70
  body["msg_id"] = msg_id
69
71
  if msg_seq is not None:
70
72
  body["msg_seq"] = msg_seq
73
+ if keyboard is not None:
74
+ body["keyboard"] = keyboard
71
75
  return body
72
76
 
73
77
 
@@ -167,8 +171,15 @@ class Context:
167
171
  return None
168
172
  return None
169
173
 
170
- async def reply(self, content: str, *, msg_seq: int | None = None) -> str | None:
171
- """被动回复一条纯文本消息, 返回新消息 id.
174
+ async def reply(
175
+ self,
176
+ content: str,
177
+ *,
178
+ msg_seq: int | None = None,
179
+ keyboard: Keyboard | None = None,
180
+ seq_key: str | None = None,
181
+ ) -> str | None:
182
+ """被动回复一条文本消息, 返回新消息 id.
172
183
 
173
184
  只支持消息类事件: ``GROUP_AT_MESSAGE_CREATE`` / ``GROUP_MESSAGE_CREATE``
174
185
  走群聊接口(目标取 ``d.group_openid``), ``C2C_MESSAGE_CREATE`` 走单聊接口
@@ -182,7 +193,18 @@ class Context:
182
193
 
183
194
  ``msg_seq`` 用于同一锚点上的多条回复去重(平台对同一个 msg_id + msg_seq
184
195
  重复发送会返回 40054005): 不传时由 Bot 按锚点自增(首次 1, 第二次 2),
185
- 传了则以传入值为准, 并把该锚点的计数推进到该值.
196
+ 传了则以传入值为准, 并把该锚点的计数推进到该值. 平台上限是群聊 5 次、
197
+ 单聊 4 次, 超出会被拒发.
198
+
199
+ ``keyboard`` 是内嵌键盘(可带按钮), 省略则不带键盘. 群聊与单聊共用同一种
200
+ 键盘结构, 因此这里直接透传; 用它就能在被动回复里带上按钮而不用绕开框架
201
+ 直连 ``send_group_messages``::
202
+
203
+ await ctx.reply("来答题", keyboard=keyboard)
204
+
205
+ ``seq_key`` 只影响计数用哪个键, 省略时用锚点本身. 如果你自己拼请求直连
206
+ ``send_group_messages`` 发过一条被动回复, 先 ``bot.next_msg_seq(锚点)``
207
+ 登记, 或把那次也算成同一个 ``seq_key``, 就不会撞上 40054005.
186
208
  """
187
209
  target = self._reply_target()
188
210
  if target is None:
@@ -191,12 +213,13 @@ class Context:
191
213
  anchor = event_id or message_id
192
214
  if anchor is None:
193
215
  return None
194
- seq = self.bot.next_msg_seq(anchor, msg_seq)
216
+ seq = self.bot.next_msg_seq(anchor, msg_seq, seq_key=seq_key)
195
217
  body = _request_body(
196
218
  content,
197
219
  event_id=event_id,
198
220
  msg_id=None if event_id is not None else message_id,
199
221
  msg_seq=seq,
222
+ keyboard=keyboard,
200
223
  )
201
224
  return await _send_to(*target, body)
202
225
 
File without changes