@chen_hu_hu/pi-qq 1.6.2 → 1.7.0

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.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.7.0] - 2026-11-11
11
+
12
+ ### Fixed
13
+
14
+ - Stream and outbound message sends now allocate `msg_seq` monotonically per inbound `msgId` instead of using the SDK's random helper, avoiding duplicate sequences within a message.
15
+
10
16
  ## [1.6.2] - 2026-11-11
11
17
 
12
18
  ### Changed
@@ -179,7 +185,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
179
185
  - Added thinking labels, per-tool icons, model-error recovery, and idle-safe session handling.
180
186
  - Reorganized modules by bounded context and updated settings and delivery documentation.
181
187
 
182
- [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.6.2...HEAD
188
+ [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.7.0...HEAD
189
+ [1.7.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.6.2...v1.7.0
183
190
  [1.6.2]: https://github.com/CQ-Developer/pi-qq/compare/v1.6.1...v1.6.2
184
191
  [1.6.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.6.0...v1.6.1
185
192
  [1.6.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.5.1...v1.6.0
@@ -0,0 +1,96 @@
1
+ # pi-qq delivery 1.7.0
2
+
3
+ > **Delivery record.** 1.7.0 replaces the SDK's random `msg_seq` helper with a monotonic per-`msgId` allocator for every outbound message path. See [README](../../README.md) for current user-facing behavior.
4
+ > Version: 1.7.0
5
+ > Date: 2026-11-11
6
+ > Previous: [delivery.1.6.2.md](./delivery.1.6.2.md).
7
+ > Open work: [doc/todo.md](../todo.md).
8
+
9
+ ## 1. Scope
10
+
11
+ 1.6.2 added recovery for `40054005` after a duplicate `msgseq`, but kept the SDK's random `getNextMsgSeq()` helper. Random values in the range `0..65535` can collide within one inbound message, especially in long runs with hundreds of stream bubbles.
12
+
13
+ 1.7.0 removes the randomness:
14
+
15
+ - allocate `msg_seq` monotonically per inbound `msgId`;
16
+ - use the allocator for custom stream messages;
17
+ - use the allocator for passive text, media, and diagnostic Markdown sends;
18
+ - keep proactive sends unchanged because they have no `msgId`;
19
+ - keep the existing fresh-stream recovery as a defensive fallback.
20
+
21
+ Out of scope:
22
+
23
+ - changing the QQ protocol range or `index` semantics;
24
+ - modifying the SDK package itself;
25
+ - changing proactive message sequencing;
26
+ - changing message formatting or relay behavior.
27
+
28
+ ## 2. Final decisions
29
+
30
+ | # | Question | Decision |
31
+ | --- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
32
+ | D1 | Where does `msg_seq` come from? | A pi-qq-owned allocator keyed by `msgId`, not the SDK's random helper. |
33
+ | D2 | What values are allocated? | `0, 1, 2, ...` independently for each `msgId`. |
34
+ | D3 | What happens after 65535 allocations for one message? | Throw `msg_seq exhausted for message` instead of wrapping and risking a duplicate. |
35
+ | D4 | Which sends use the allocator? | Custom `stream_messages`, passive text replies, media sends, and diagnostic Markdown. |
36
+ | D5 | Which sends do not? | Proactive sends have no `msgId`; typing has no `msgId` and does not participate in message deduplication. |
37
+ | D6 | Is `40054005` recovery still needed? | Yes, as a fallback for any remaining or future collision source. |
38
+
39
+ ## 3. Implementation
40
+
41
+ New module:
42
+
43
+ | File | Responsibility |
44
+ | ------------------------ | ----------------------------------------------------------------------------------------- |
45
+ | `src/relay/msg-seq.ts` | `allocateMsgSeq(msgId)` and test reset; per-`msgId` monotonic counter |
46
+ | `src/qq/msg-seq-send.ts` | `sendWithMsgSeq(bot, options)`; injects an allocated `msg_seq` for targets with a `msgId` |
47
+
48
+ Updated call sites:
49
+
50
+ | File | Change |
51
+ | ----------------------------- | -------------------------------------------------------- |
52
+ | `src/relay/stream-session.ts` | Uses `allocateMsgSeq()` instead of SDK `getNextMsgSeq()` |
53
+ | `src/qq/reply-sender.ts` | Text chunks use `sendWithMsgSeq()` |
54
+ | `src/qq/media-tool.ts` | Media sends use `sendWithMsgSeq()` |
55
+ | `src/qq/qq-diagnostics.ts` | Diagnostic Markdown uses `sendWithMsgSeq()` |
56
+
57
+ The helper calls the SDK's generic `send()` path with `extra.msg_seq`, so message type detection remains unchanged:
58
+
59
+ - `content` → text message;
60
+ - `markdown` → Markdown message;
61
+ - `media` → rich-media message.
62
+
63
+ ## 4. Verification
64
+
65
+ Automated:
66
+
67
+ - **238 tests** across 24 files.
68
+ - `npm run lint`, `npm run typecheck`, `npm run format:check`, and `npm pack --dry-run` pass.
69
+ - New tests cover:
70
+ - independent counters for different `msgId` values;
71
+ - reset behavior;
72
+ - unique `msg_seq` for repeated text sends;
73
+ - media sends through `sendWithMsgSeq()`;
74
+ - no direct `sendText`, `sendMarkdown`, `sendMediaMessage`, or `getNextMsgSeq` use in pi-qq.
75
+
76
+ Not covered by a real QQ run in this release:
77
+
78
+ - exhaustion of all 65536 values for one message;
79
+ - a real collision after the allocator change (the automated allocator tests make this deterministic).
80
+
81
+ The 1.6.2 manual test remains the latest real QQ smoke test; it covered `/last`, `/status`, `/stop`, and normal text/stream output.
82
+
83
+ ## 5. Risks and limitations
84
+
85
+ | Risk | Impact | Handling |
86
+ | ----------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
87
+ | `msgId -> next` map growth | One number per inbound message for the process lifetime | Small per entry; can be pruned later if needed |
88
+ | Sequence exhaustion | A single message cannot create more than 65536 outbound sends | Explicit error instead of silent reuse |
89
+ | Proactive sends still use SDK sequencing | They have no `msgId` and do not participate in per-message dedupe | Accepted |
90
+ | SDK direct sends remain possible in future code | A new call could bypass the allocator | Code review and grep check for direct SDK send helpers |
91
+
92
+ ## 6. References
93
+
94
+ - User-facing behavior: [README.md](../../README.md), [README-zh.md](../../README-zh.md).
95
+ - Previous delivery: [delivery.1.6.2.md](./delivery.1.6.2.md).
96
+ - Message sequence implementation: `src/relay/msg-seq.ts`, `src/qq/msg-seq-send.ts`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chen_hu_hu/pi-qq",
3
- "version": "1.6.2",
3
+ "version": "1.7.0",
4
4
  "description": "Connect pi to QQ private chats.",
5
5
  "license": "MIT",
6
6
  "author": "CQ-Developer",
@@ -18,6 +18,7 @@ import { log } from "../infra/file-logger";
18
18
  import { t } from "../infra/i18n";
19
19
  import type { ReplyBudget } from "../quota/reply-quota";
20
20
  import { TEXT_CHUNK_LIMIT } from "./reply-sender";
21
+ import { sendWithMsgSeq } from "./msg-seq-send";
21
22
 
22
23
  export const MEDIA_TOOL_NAME = "qq_send_media";
23
24
 
@@ -298,9 +299,14 @@ function createTool(deps: MediaToolDeps): ToolDefinition<typeof mediaParams, Med
298
299
  });
299
300
 
300
301
  const sendMedia = (target: string, passiveMsgId?: string) =>
301
- bot.mediaApi.sendMediaMessage("c2c", target, upload.file_info, bot.getCredentials(), {
302
- ...(passiveMsgId ? { msgId: passiveMsgId } : {}),
303
- content: caption,
302
+ sendWithMsgSeq(bot, {
303
+ target: {
304
+ scope: "c2c",
305
+ targetId: target,
306
+ ...(passiveMsgId ? { msgId: passiveMsgId } : {}),
307
+ },
308
+ media: { file_info: upload.file_info },
309
+ ...(caption ? { content: caption } : {}),
304
310
  });
305
311
  const buildResult = (
306
312
  messageId: string,
@@ -0,0 +1,11 @@
1
+ import type { QQBot, SendMessageOptions } from "@tencent-connect/qqbot-nodejs";
2
+ import { allocateMsgSeq } from "../relay/msg-seq";
3
+
4
+ export function sendWithMsgSeq(bot: QQBot, options: SendMessageOptions) {
5
+ const msgId = options.target.msgId;
6
+ if (!msgId) return bot.send(options);
7
+ return bot.send({
8
+ ...options,
9
+ extra: { ...options.extra, msg_seq: allocateMsgSeq(msgId) },
10
+ });
11
+ }
@@ -5,6 +5,7 @@ import { AppendStream } from "../relay/stream-session";
5
5
  import type { RunningBot } from "./qq-bot";
6
6
  import { t } from "../infra/i18n";
7
7
  import { thinkingHeader } from "../relay/stream-block-format";
8
+ import { sendWithMsgSeq } from "./msg-seq-send";
8
9
 
9
10
  interface QQDiagnosticsDeps {
10
11
  getRunning: () => RunningBot | undefined;
@@ -42,7 +43,7 @@ export function registerQQDiagnostics(pi: ExtensionAPI, deps: QQDiagnosticsDeps)
42
43
  }
43
44
  const content = args?.trim() || "**Markdown test**\n# Heading\n- Item one\n- Item two\n[Link](https://qq.com)";
44
45
  try {
45
- await running.bot.sendMarkdown(target, content);
46
+ await sendWithMsgSeq(running.bot, { target, markdown: { content } });
46
47
  ctx.ui.notify(t("diagnostics.mdSent"), "info");
47
48
  } catch (err) {
48
49
  ctx.ui.notify(t("diagnostics.mdFailed", { message: (err as Error).message }), "error");
@@ -1,6 +1,7 @@
1
1
  import type { QQBot } from "@tencent-connect/qqbot-nodejs";
2
2
  import { ReplyBudget } from "../quota/reply-quota";
3
3
  import { AppendStream } from "../relay/stream-session";
4
+ import { sendWithMsgSeq } from "./msg-seq-send";
4
5
  import { log } from "../infra/file-logger";
5
6
  import { t } from "../infra/i18n";
6
7
 
@@ -122,7 +123,7 @@ export async function sendReply(bot: QQBot, text: string, ch: ReplyChannel): Pro
122
123
  length: chunk.length,
123
124
  text: chunk,
124
125
  });
125
- await bot.sendText(replyTarget, chunk);
126
+ await sendWithMsgSeq(bot, { target: replyTarget, content: chunk });
126
127
  if (mode === "passive" && msgId) ch.budget.commitPassive(msgId);
127
128
  log.info("outbound", "text chunk sent", { mode, targetId, length: chunk.length });
128
129
  } catch (err) {
@@ -135,7 +136,10 @@ export async function sendReply(bot: QQBot, text: string, ch: ReplyChannel): Pro
135
136
  if (mode === "passive") {
136
137
  try {
137
138
  log.warn("outbound", "passive send failed; retrying proactively", { targetId: ch.boundOpenid });
138
- await bot.sendText({ scope: "c2c", targetId: ch.boundOpenid }, chunk);
139
+ await sendWithMsgSeq(bot, {
140
+ target: { scope: "c2c", targetId: ch.boundOpenid },
141
+ content: chunk,
142
+ });
139
143
  ch.onWarn?.(t("outbound.passiveFailed"));
140
144
  continue;
141
145
  } catch (retryErr) {
@@ -0,0 +1,15 @@
1
+ const MAX_MSG_SEQ = 0xffff;
2
+ const nextByMsgId = new Map<string, number>();
3
+
4
+ export function allocateMsgSeq(msgId: string): number {
5
+ const next = nextByMsgId.get(msgId) ?? 0;
6
+ if (next > MAX_MSG_SEQ) {
7
+ throw new Error("msg_seq exhausted for message");
8
+ }
9
+ nextByMsgId.set(msgId, next + 1);
10
+ return next;
11
+ }
12
+
13
+ export function resetMsgSeqAllocator(): void {
14
+ nextByMsgId.clear();
15
+ }
@@ -1,4 +1,5 @@
1
- import { getNextMsgSeq, StreamContentType, StreamInputState } from "@tencent-connect/qqbot-nodejs/protocol";
1
+ import { StreamContentType, StreamInputState } from "@tencent-connect/qqbot-nodejs/protocol";
2
+ import { allocateMsgSeq } from "./msg-seq";
2
3
  import type {
3
4
  Credentials,
4
5
  MessageApi,
@@ -145,7 +146,7 @@ export class AppendStream {
145
146
  this.flushing = true;
146
147
  let failed = false;
147
148
  try {
148
- if (this.msgSeq === null) this.msgSeq = getNextMsgSeq(this.msgId);
149
+ if (this.msgSeq === null) this.msgSeq = allocateMsgSeq(this.msgId);
149
150
  const index = this.index++;
150
151
  const req = {
151
152
  input_mode: "append",