@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 +8 -1
- package/doc/archive/delivery.1.7.0.md +96 -0
- package/package.json +1 -1
- package/src/qq/media-tool.ts +9 -3
- package/src/qq/msg-seq-send.ts +11 -0
- package/src/qq/qq-diagnostics.ts +2 -1
- package/src/qq/reply-sender.ts +6 -2
- package/src/relay/msg-seq.ts +15 -0
- package/src/relay/stream-session.ts +3 -2
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.
|
|
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
package/src/qq/media-tool.ts
CHANGED
|
@@ -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
|
-
|
|
302
|
-
|
|
303
|
-
|
|
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
|
+
}
|
package/src/qq/qq-diagnostics.ts
CHANGED
|
@@ -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
|
|
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");
|
package/src/qq/reply-sender.ts
CHANGED
|
@@ -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
|
|
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
|
|
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 {
|
|
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 =
|
|
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",
|