@chen_hu_hu/pi-qq 1.3.1 → 1.3.2

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 ADDED
@@ -0,0 +1,61 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [1.3.2] - 2026-11-04
11
+
12
+ ### Added
13
+
14
+ - GitHub Releases now attach the npm tarball and a `SHA256SUMS` file.
15
+
16
+ ### Changed
17
+
18
+ - Log records are written asynchronously, and debug payload previews are only built when debug logging is enabled.
19
+ - Historical delivery records moved to `doc/archive/` and are marked unmaintained.
20
+ - Relay composition and inbound command/attachment handling were split into smaller modules for maintainability.
21
+
22
+ ## [1.3.1] - 2026-11-04
23
+
24
+ ### Added
25
+
26
+ - CI workflow for pushes and pull requests.
27
+ - Regression coverage for session lifecycle, mixed voice attachments, and image handling.
28
+ - Automated release notes sourced from this changelog.
29
+
30
+ ### Changed
31
+
32
+ - Images now use the same save/pending pipeline as files. The next instruction reads them through pi's `read` tool.
33
+ - Attachment prompts use workspace-relative paths and the concise `# Attachments:` / `# User message:` format.
34
+ - Settings are validated and resolved once per session. `fileMaxSize` now applies to all attachments; `imageMaxSize` was removed.
35
+ - README rewritten for users and developers.
36
+
37
+ ### Fixed
38
+
39
+ - Invalid config shapes such as `null` or arrays no longer crash startup.
40
+ - Cancelling QR login no longer reports a failure.
41
+ - `/stop` clears model-error recovery even when idle.
42
+ - Login/logout and session shutdown dispose the active relay.
43
+ - Voice messages preserve other attachments in the same message.
44
+ - `chunkText` no longer loops forever on an invalid limit.
45
+
46
+ ### Security
47
+
48
+ - The bot now requires a bound openid and always installs an allowlist.
49
+
50
+ ## [1.3.0] - 2026-11-03
51
+
52
+ ### Changed
53
+
54
+ - Reworked relay output into per-content-block streamed bubbles.
55
+ - Added thinking labels, per-tool icons, model-error recovery, and idle-safe session handling.
56
+ - Reorganized modules by bounded context and updated settings and delivery documentation.
57
+
58
+ [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.2...HEAD
59
+ [1.3.2]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.1...v1.3.2
60
+ [1.3.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.0...v1.3.1
61
+ [1.3.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.2.3...v1.3.0
@@ -0,0 +1,18 @@
1
+ # Archived delivery records
2
+
3
+ These documents record how pi-qq was delivered at each milestone. They are
4
+ historical snapshots, not current documentation.
5
+
6
+ - They may reference modules, settings, or behaviors that have since been
7
+ removed (for example the image-specific pipeline and `imageMaxSize`).
8
+ - Do not update them to match current behavior; write current documentation in
9
+ `README.md`, `README-zh.md`, and `CHANGELOG.md` instead.
10
+ - File and line details in these records are intentionally frozen.
11
+
12
+ # 归档交付记录
13
+
14
+ 本目录保存 pi-qq 各里程碑的交付记录,仅作历史快照,不是当前文档。
15
+
16
+ - 文中可能引用已删除的模块、配置或行为(例如图片专用链路和 `imageMaxSize`)。
17
+ - 不要把这些文档更新为当前行为;现行说明请写入 `README.md`、`README-zh.md` 和 `CHANGELOG.md`。
18
+ - 文件与行号等细节按当时状态保留。
@@ -1,7 +1,8 @@
1
1
  # pi-qq delivery-v1
2
2
 
3
+ > **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
3
4
  > 状态:v1 已交付,作为后续版本的历史基线。
4
- > 当前行为以 [README-zh.md](../README-zh.md) 为准;后续版本见 [delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
5
+ > 后续版本见 [delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
5
6
 
6
7
  ## 1. 交付范围
7
8
 
@@ -1,7 +1,8 @@
1
1
  # pi-qq delivery-v1
2
2
 
3
+ > **Archived record.** Content reflects the delivery at that time and may reference removed modules or settings. See [README](../../README.md) for current behavior.
3
4
  > Status: v1 delivered; this is a historical baseline for later versions.
4
- > Current behavior is documented in [README](../README.md); later versions: [delivery-v2.md](./delivery-v2.md), [delivery-v3.md](./delivery-v3.md).
5
+ > Later versions: [delivery-v2.md](./delivery-v2.md), [delivery-v3.md](./delivery-v3.md).
5
6
 
6
7
  ## 1. Scope
7
8
 
@@ -1,7 +1,8 @@
1
1
  # pi-qq delivery-v2
2
2
 
3
+ > **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
3
4
  > 状态:v2 已交付,本文为历史记录。
4
- > 当前行为以 [README-zh.md](../README-zh.md) 为准;前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md);后续版本:[delivery-v3-zh.md](./delivery-v3-zh.md)。
5
+ > 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md);后续版本:[delivery-v3-zh.md](./delivery-v3-zh.md)。
5
6
 
6
7
  ## 1. 交付范围
7
8
 
@@ -1,7 +1,8 @@
1
1
  # pi-qq delivery-v2
2
2
 
3
+ > **Archived record.** Content reflects the delivery at that time and may reference removed modules or settings. See [README](../../README.md) for current behavior.
3
4
  > Status: v2 delivered; this is a historical record.
4
- > Current behavior is documented in [README](../README.md); previous: [delivery-v1.md](./delivery-v1.md); next: [delivery-v3.md](./delivery-v3.md).
5
+ > Previous: [delivery-v1.md](./delivery-v1.md); next: [delivery-v3.md](./delivery-v3.md).
5
6
 
6
7
  ## 1. Scope
7
8
 
@@ -1,7 +1,8 @@
1
1
  # pi-qq delivery-v3
2
2
 
3
+ > **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
3
4
  > 状态:v3 已实现并完成主链路真机验证;按块切泡、错误恢复、列表切分等最终细节仍需在目标 QQ 客户端做一次完整复验。
4
- > 说明:后续变更删除了图片专用链路,图片与文件共用保存/pending 流程。当前行为见 [README-zh.md](../README-zh.md)。
5
+ > 说明:后续变更删除了图片专用链路,图片与文件共用保存/pending 流程。
5
6
  > 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md)、[delivery-v2-zh.md](./delivery-v2-zh.md)。
6
7
 
7
8
  ## 1. 交付范围
@@ -1,7 +1,8 @@
1
1
  # pi-qq delivery-v3
2
2
 
3
- > Status: v3 implemented and the main path has been verified on real QQ. Final details such as long-list splitting and recovery edge cases still need one complete pass on the target client.
4
- > Note: later changes removed the image-specific pipeline; images now use the same save/pending path as files. See [README](../README.md) for current behavior.
3
+ > **Archived record.** Content reflects the delivery at that time and may reference removed modules or settings. See [README](../../README.md) for current behavior.
4
+ > Status: v3 implemented and the main path has been verified on real QQ.
5
+ > Note: later changes removed the image-specific pipeline; images now use the same save/pending path as files.
5
6
  > Previous: [delivery-v1.md](./delivery-v1.md), [delivery-v2.md](./delivery-v2.md).
6
7
 
7
8
  ## 1. Scope
package/index.ts CHANGED
@@ -9,7 +9,7 @@ import { markdownToPlain, sendReply } from "./src/qq/reply-sender";
9
9
  import { ReplyBudget } from "./src/quota/reply-quota";
10
10
  import { RunFeedback } from "./src/relay/run-stream-relay";
11
11
  import { formatTokenCount } from "./src/infra/display-format";
12
- import { configureLogger, log, previewForLog } from "./src/infra/file-logger";
12
+ import { configureLogger, flushLogs, isLogEnabled, log, previewForLog } from "./src/infra/file-logger";
13
13
  import { pruneUploadIndex, sessionUploadDir } from "./src/attachments/file-attachments";
14
14
 
15
15
  interface LoginState {
@@ -149,9 +149,10 @@ export default function (pi: ExtensionAPI) {
149
149
  }
150
150
  });
151
151
 
152
- pi.on("session_shutdown", () => {
152
+ pi.on("session_shutdown", async () => {
153
153
  log.info("session", "shutting down");
154
154
  stopIfRunning();
155
+ await flushLogs();
155
156
  });
156
157
 
157
158
  pi.on("agent_start", () => {
@@ -165,21 +166,25 @@ export default function (pi: ExtensionAPI) {
165
166
  });
166
167
 
167
168
  pi.on("tool_execution_start", (event) => {
168
- log.debug("tool", "start", {
169
- toolName: event.toolName,
170
- toolCallId: event.toolCallId,
171
- args: previewForLog(event.args),
172
- });
169
+ if (isLogEnabled("debug")) {
170
+ log.debug("tool", "start", {
171
+ toolName: event.toolName,
172
+ toolCallId: event.toolCallId,
173
+ args: previewForLog(event.args),
174
+ });
175
+ }
173
176
  void runFeedback.onToolStart(event.toolName, event.args, event.toolCallId);
174
177
  });
175
178
 
176
179
  pi.on("tool_execution_end", (event) => {
177
- log.debug("tool", "end", {
178
- toolName: event.toolName,
179
- toolCallId: event.toolCallId,
180
- isError: event.isError,
181
- result: previewForLog(event.result),
182
- });
180
+ if (isLogEnabled("debug")) {
181
+ log.debug("tool", "end", {
182
+ toolName: event.toolName,
183
+ toolCallId: event.toolCallId,
184
+ isError: event.isError,
185
+ result: previewForLog(event.result),
186
+ });
187
+ }
183
188
  runFeedback.onToolEnd(event.toolName, event.isError, event.result, event.toolCallId);
184
189
  });
185
190
 
@@ -202,17 +207,19 @@ export default function (pi: ExtensionAPI) {
202
207
  if (msg.role !== "assistant" || !running) return;
203
208
 
204
209
  const fromQQ = runFeedback.isQQRunActive();
205
- log.debug("pi", "assistant message ended", {
206
- fromQQ,
207
- stopReason: msg.stopReason,
208
- contentTypes: msg.content.map((block) => block.type),
209
- textPreview: previewForLog(
210
- msg.content
211
- .filter((block) => block.type === "text")
212
- .map((block) => block.text)
213
- .join("\n"),
214
- ),
215
- });
210
+ if (isLogEnabled("debug")) {
211
+ log.debug("pi", "assistant message ended", {
212
+ fromQQ,
213
+ stopReason: msg.stopReason,
214
+ contentTypes: msg.content.map((block) => block.type),
215
+ textPreview: previewForLog(
216
+ msg.content
217
+ .filter((block) => block.type === "text")
218
+ .map((block) => block.text)
219
+ .join("\n"),
220
+ ),
221
+ });
222
+ }
216
223
  if (!fromQQ) return;
217
224
 
218
225
  const isError = msg.stopReason === "error";
@@ -234,7 +241,9 @@ export default function (pi: ExtensionAPI) {
234
241
  }
235
242
 
236
243
  const streamTookOver = await runFeedback.onAssistantFinal(text, isError);
237
- log.debug("pi", "stream takeover decision", { streamTookOver, isError, textPreview: previewForLog(text) });
244
+ if (isLogEnabled("debug")) {
245
+ log.debug("pi", "stream takeover decision", { streamTookOver, isError, textPreview: previewForLog(text) });
246
+ }
238
247
  if (streamTookOver) return;
239
248
 
240
249
  const payload = markdownToPlain(text);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chen_hu_hu/pi-qq",
3
- "version": "1.3.1",
3
+ "version": "1.3.2",
4
4
  "description": "Connect pi to QQ private chats.",
5
5
  "license": "MIT",
6
6
  "author": "CQ-Developer",
@@ -37,6 +37,7 @@
37
37
  "index.ts",
38
38
  "src",
39
39
  "doc",
40
+ "CHANGELOG.md",
40
41
  "README.md",
41
42
  "README-zh.md",
42
43
  "LICENSE"
@@ -1,4 +1,4 @@
1
- import { appendFileSync, mkdirSync } from "node:fs";
1
+ import { appendFile, mkdir } from "node:fs/promises";
2
2
  import { join } from "node:path";
3
3
 
4
4
  export type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
@@ -16,6 +16,7 @@ const DEFAULT_LOG_LEVEL: LogLevel = "silent";
16
16
 
17
17
  let activeLevel: LogLevel = DEFAULT_LOG_LEVEL;
18
18
  let activeDir: string | undefined;
19
+ let writeQueue: Promise<void> = Promise.resolve();
19
20
 
20
21
  function isLogLevel(value: unknown): value is LogLevel {
21
22
  return typeof value === "string" && Object.hasOwn(LEVEL_WEIGHT, value);
@@ -29,6 +30,15 @@ export function isLevelEnabled(configured: LogLevel, level: Exclude<LogLevel, "s
29
30
  return configured !== "silent" && LEVEL_WEIGHT[level] >= LEVEL_WEIGHT[configured];
30
31
  }
31
32
 
33
+ export function isLogEnabled(level: Exclude<LogLevel, "silent">): boolean {
34
+ return isLevelEnabled(activeLevel, level);
35
+ }
36
+
37
+ /** Resolve once every queued log record has been written (or dropped). */
38
+ export async function flushLogs(): Promise<void> {
39
+ await writeQueue;
40
+ }
41
+
32
42
  export function configureLogger(level: LogLevel, dir?: string): void {
33
43
  activeLevel = normalizeLogLevel(level);
34
44
  activeDir = dir;
@@ -100,11 +110,16 @@ function writeRecord(level: Exclude<LogLevel, "silent">, scope: string, message:
100
110
  });
101
111
  }
102
112
 
103
- try {
104
- const dir = resolveLogDir();
105
- mkdirSync(dir, { recursive: true });
106
- appendFileSync(join(dir, logFileName()), `${line}\n`, "utf8");
107
- } catch {}
113
+ const dir = resolveLogDir();
114
+ const path = join(dir, logFileName());
115
+ writeQueue = writeQueue
116
+ .then(async () => {
117
+ try {
118
+ await mkdir(dir, { recursive: true });
119
+ await appendFile(path, `${line}\n`, "utf8");
120
+ } catch {}
121
+ })
122
+ .catch(() => {});
108
123
  }
109
124
 
110
125
  export const log = {
@@ -0,0 +1,101 @@
1
+ import type { QQBotInboundMessage } from "@tencent-connect/qqbot-nodejs";
2
+ import type { AttachmentFailure } from "../attachments/attachment-failure";
3
+ import { saveInboundFiles, type SavedFile } from "../attachments/file-attachments";
4
+ import { log } from "../infra/file-logger";
5
+ import { isVoiceAttachment, resolveVoiceTranscript } from "../attachments/voice-transcript";
6
+
7
+ export interface ResolveInboundOptions {
8
+ contentText: string;
9
+ maxSize: number;
10
+ uploadDir: string;
11
+ saveFiles: typeof saveInboundFiles;
12
+ }
13
+
14
+ export type ResolvedInbound =
15
+ | { status: "rejected"; reply: string }
16
+ | {
17
+ status: "resolved";
18
+ text: string;
19
+ files: SavedFile[];
20
+ failures: AttachmentFailure[];
21
+ voiceCount: number;
22
+ };
23
+
24
+ /**
25
+ * Turn one inbound message into injectable content: prefer ASR for voice,
26
+ * persist every non-voice attachment, and report per-file failures.
27
+ */
28
+ export async function resolveInboundContent(
29
+ msg: QQBotInboundMessage,
30
+ options: ResolveInboundOptions,
31
+ ): Promise<ResolvedInbound> {
32
+ const attachments = msg.attachments ?? [];
33
+ let text = options.contentText;
34
+
35
+ const voiceAttachments = attachments.filter(isVoiceAttachment);
36
+ if (voiceAttachments.length > 0) {
37
+ const transcript = resolveVoiceTranscript(voiceAttachments);
38
+ log.info("inbound", "voice message", {
39
+ messageId: msg.messageId,
40
+ hasAsr: Boolean(transcript),
41
+ asrLength: transcript?.length ?? 0,
42
+ });
43
+ if (!transcript) {
44
+ if (!options.contentText) {
45
+ log.warn("inbound", "voice ASR returned no text", { messageId: msg.messageId });
46
+ return {
47
+ status: "rejected",
48
+ reply: "Could not transcribe this voice message; please resend or type it.",
49
+ };
50
+ }
51
+ log.warn("inbound", "voice ASR returned no text; using text content", { messageId: msg.messageId });
52
+ } else {
53
+ log.debug("inbound", "voice transcript", { messageId: msg.messageId, transcript });
54
+ text = options.contentText ? `${options.contentText}\n${transcript}` : transcript;
55
+ }
56
+ }
57
+
58
+ // Voice attachments are handled above; all other attachments are stored as files.
59
+ const attachmentsToSave = attachments.filter((attachment) => !isVoiceAttachment(attachment));
60
+ const failures: AttachmentFailure[] = [];
61
+ let files: SavedFile[] = [];
62
+
63
+ if (attachmentsToSave.length > 0) {
64
+ log.debug("inbound", "saving attachments", {
65
+ messageId: msg.messageId,
66
+ count: attachmentsToSave.length,
67
+ uploadDir: options.uploadDir,
68
+ });
69
+ const result = await options.saveFiles(attachmentsToSave, {
70
+ maxSize: options.maxSize,
71
+ uploadDir: options.uploadDir,
72
+ });
73
+ files = result.files;
74
+ failures.push(...result.failures);
75
+ }
76
+
77
+ return { status: "resolved", text, files, failures, voiceCount: voiceAttachments.length };
78
+ }
79
+
80
+ /** Attachments that arrived without an instruction, consumed by the next text or voice message. */
81
+ export class PendingAttachments {
82
+ private files: SavedFile[] = [];
83
+
84
+ get count(): number {
85
+ return this.files.length;
86
+ }
87
+
88
+ add(files: SavedFile[]): void {
89
+ if (files.length > 0) this.files.push(...files);
90
+ }
91
+
92
+ take(): SavedFile[] {
93
+ const files = this.files;
94
+ this.files = [];
95
+ return files;
96
+ }
97
+
98
+ clear(): void {
99
+ this.files = [];
100
+ }
101
+ }
@@ -0,0 +1,74 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+
3
+ /** The slice of ExtensionContext used by QQ inbound handling. */
4
+ export interface InboundContext {
5
+ readonly cwd: string;
6
+ isIdle(): boolean;
7
+ abort(): void;
8
+ compact(): void;
9
+ sessionManager: { getSessionId(): string };
10
+ }
11
+
12
+ export type InboundPi = Pick<ExtensionAPI, "sendUserMessage">;
13
+
14
+ export interface InboundCommandDeps {
15
+ pi: InboundPi;
16
+ ctx: InboundContext;
17
+ getStatusLines: () => string[];
18
+ onStop?: () => void;
19
+ waitForEnd?: () => Promise<void>;
20
+ }
21
+
22
+ export async function handleInboundCommand(
23
+ text: string,
24
+ reply: (t: string) => Promise<void>,
25
+ deps: InboundCommandDeps,
26
+ ): Promise<void> {
27
+ const cmd = text.split(/\s+/)[0];
28
+ switch (cmd) {
29
+ case "/help":
30
+ await reply(
31
+ [
32
+ "pi-qq commands:",
33
+ "• /stop — abort the current task",
34
+ "• /compact — compact the context",
35
+ "• /status — show status",
36
+ "• /new — reset the session",
37
+ "• /help — this help",
38
+ "Other text is sent to pi.",
39
+ ].join("\n"),
40
+ );
41
+ break;
42
+ case "/stop":
43
+ deps.onStop?.();
44
+ if (deps.ctx.isIdle()) {
45
+ await reply("No task is running.");
46
+ } else {
47
+ deps.ctx.abort();
48
+ await deps.waitForEnd?.();
49
+ await reply("Abort requested.");
50
+ }
51
+ break;
52
+ case "/compact":
53
+ if (deps.ctx.isIdle()) {
54
+ deps.ctx.compact();
55
+ await reply("Context compaction triggered.");
56
+ } else {
57
+ await reply("Task is running; use /stop before /compact.");
58
+ }
59
+ break;
60
+ case "/status":
61
+ await reply(deps.getStatusLines().join("\n"));
62
+ break;
63
+ case "/new":
64
+ if (!deps.ctx.isIdle()) {
65
+ await reply("Task is running; use /stop before resetting.");
66
+ } else {
67
+ await reply("Resetting the session…");
68
+ deps.pi.sendUserMessage("/qq-new", { expandPromptTemplates: true });
69
+ }
70
+ break;
71
+ default:
72
+ await reply(`Unknown command ${cmd}; use /help.`);
73
+ }
74
+ }