@chen_hu_hu/pi-qq 1.0.1 → 1.1.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/doc/plan-v2.md ADDED
@@ -0,0 +1,245 @@
1
+ # pi-qq — plan-v2.md
2
+
3
+ > 执行计划。功能范围见 [features-v2.md](./features-v2.md);本文只回答:改哪些文件、按什么顺序做、每步怎么验收。
4
+ > V2 范围:F8 语音自动转写、F9 轻量日志基础设施。不引入新依赖。
5
+
6
+ ## 0. 前置与范围
7
+
8
+ - 无新增 npm 依赖;日志使用 Node 标准库自研。
9
+ - 基线:当前 v1 代码,`npm test` 77 个测试通过。
10
+ - 不实现:本地 Whisper、外部 STT、保存原始语音、语音命令解析。
11
+ - 语音只处理 `content_type === "voice"`;不扩展其他媒体类型。
12
+ - 日志默认 `silent`;需要排查时手动改为 `info` / `debug`。
13
+
14
+ ## 1. 目录与模块
15
+
16
+ ```text
17
+ pi-qq/
18
+ ├── src/
19
+ │ ├── logger.ts # 新增:级别过滤、JSONL、按天单文件、SDK logger 适配
20
+ │ ├── voice.ts # 新增:语音附件判断、ASR 文本提取
21
+ │ ├── config.ts # 修改:logLevel、旧 debug 迁移
22
+ │ ├── inbound.ts # 修改:语音分支 + 日志分级
23
+ │ ├── bot.ts # 修改:接入 logger,移除 debug 选项
24
+ │ ├── index.ts # 修改:配置 logger,移除 getDebug,日志分级
25
+ │ ├── outbound.ts # 修改:发送日志分级
26
+ │ └── run-feedback.ts # 修改:移除 debug 时间戳,改用 logger
27
+ ├── test/
28
+ │ ├── logger.test.ts # 新增
29
+ │ ├── voice.test.ts # 新增
30
+ │ ├── config.test.ts # 新增或扩展现有设置测试
31
+ │ ├── inbound.test.ts # 修改
32
+ │ └── run-feedback.test.ts # 修改
33
+ ├── README.md # 修改:logLevel、日志路径、语音说明
34
+ └── doc/features-v2.md # 已存在,按实现结果校正
35
+ ```
36
+
37
+ ## 2. 执行步骤
38
+
39
+ ### M5a-1 — 实现 logger
40
+
41
+ **改动**
42
+
43
+ 1. 新增 `src/logger.ts`:
44
+ - `LogLevel = "silent" | "error" | "warn" | "info" | "debug"`。
45
+ - `configureLogger(level, dir?)`、`getLogLevel()`。
46
+ - `log.error/warn/info/debug(scope, message, data?)`。
47
+ - `sdkLogger`:适配 SDK 的 `(message, meta?)` 接口,统一写入同一个 logger。
48
+ - `previewForLog(value, maxChars)`:截断工具参数/结果。
49
+ - 级别过滤:只输出当前级别及以上;`silent` 不写。
50
+ - 输出一行 JSON:`time`、`level`、`scope`、`msg` + 结构化字段。
51
+ - 文件路径:`<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。
52
+ - `PI_QQ_LOG_DIR` 可覆盖目录,供测试使用。
53
+ - 每次写入时重新计算日期;跨天自动换文件。
54
+ - 日志写入失败静默忽略,不影响消息处理。
55
+ 2. 不新增 `debug-log.ts`;不保留临时调试文件。
56
+
57
+ **验证**
58
+
59
+ - 单测覆盖:级别过滤、日期文件名、`previewForLog`、写入失败不抛错。
60
+ - `logLevel: "silent"` 不产生文件。
61
+ - `logLevel: "debug"` 能写入一行合法 JSON。
62
+ - `src/logger.ts` 不依赖第三方包。
63
+
64
+ ### M5a-2 — 配置与接线
65
+
66
+ **改动**
67
+
68
+ 1. `src/config.ts`:
69
+ - 新增 `logLevel?: LogLevel`,默认 `silent`。
70
+ - 保留 `debug?: boolean` 仅用于旧配置迁移:`debug: true` → `logLevel: "debug"`,其他情况默认 `silent`。
71
+ - `ResolvedSettings` 移除 `debug`。
72
+ 2. `src/index.ts`:
73
+ - 在 `session_start` / `startWithCredentials` 读取设置并 `configureLogger(settings.logLevel)`。
74
+ - 日志目录使用当前工作区 `ctx.cwd`;未配置时 logger 回退到 `process.cwd()`。
75
+ - 移除 `getDebug` 依赖和 `settings.debug` 传递。
76
+ 3. `src/bot.ts`:
77
+ - `StartBotOptions` 移除 `debug`。
78
+ - `new QQBot({ logger: sdkLogger })`。
79
+ - 连接状态用 info;连接失败/异常用 error;入站 raw 用 debug。
80
+ 4. `src/inbound.ts` / `src/outbound.ts`:
81
+ - 详细事件用 debug。
82
+ - 入站/出站摘要用 info。
83
+ - 附件失败、ASR 为空、发送降级用 warn。
84
+ - 发送失败、handler 异常用 error。
85
+ 5. `src/run-feedback.ts`:
86
+ - 移除 `getDebug` 和 QQ 气泡时间戳。
87
+ - 内部诊断改用 `log.debug` / `log.warn`。
88
+
89
+ **验证**
90
+
91
+ - `getSettings({}).logLevel === "silent"`。
92
+ - `getSettings({ debug: true }).logLevel === "debug"`。
93
+ - `getSettings({ logLevel: "info" }).logLevel === "info"`。
94
+ - 非法 `logLevel` 回退到 `silent`。
95
+ - 代码中除迁移读取外不再引用 `debug` 配置。
96
+ - `npm run typecheck` 通过。
97
+
98
+ ### M5a-3 — 日志行为验收
99
+
100
+ **验证**
101
+
102
+ 1. `logLevel: "silent"`:发送 QQ 消息后,`<cwd>/.pi/pi-qq/logs/` 不新增日志。
103
+ 2. `logLevel: "info"`:日志只含元数据,不含消息正文、prompt、工具参数。
104
+ 3. `logLevel: "debug"`:日志包含 raw 事件、附件、prompt、工具参数/结果、消息正文。
105
+ 4. 日期跨天:用注入时间或临时目录测试文件名从 `pi-qq-YYYY-MM-DD.log` 切换。
106
+ 5. 目录不可写:消息仍正常处理,进程不崩溃。
107
+
108
+ ### M5b-1 — 实现语音模块
109
+
110
+ **改动**
111
+
112
+ 1. 新增 `src/voice.ts`:
113
+ - `isVoiceAttachment(attachment)`:仅当 `content_type === "voice"` 返回 true。
114
+ - `resolveVoiceTranscript(attachments)`:
115
+ - 只读取语音附件。
116
+ - `asr_refer_text` 去首尾空白。
117
+ - 过滤空值;多个非空文本按附件顺序换行拼接。
118
+ - 无有效文本返回 `undefined`。
119
+ 2. 不下载 `url` / `voice_wav_url`,不保存语音文件。
120
+
121
+ **验证**
122
+
123
+ - `content_type === "voice"` 识别为语音。
124
+ - 普通文件、图片不识别为语音。
125
+ - `asr_refer_text` 为 `"测试。"` 返回 `"测试。"`。
126
+ - 空字符串、纯空白、缺失返回 `undefined`。
127
+ - 多个语音附件按顺序合并。
128
+
129
+ ### M5b-2 — 接入 inbound
130
+
131
+ **改动**
132
+
133
+ 1. `src/inbound.ts` 在图片/文件分流前增加语音分支:
134
+ - 提取 ASR 文本。
135
+ - 有文本:`markQQTrigger()` → `pi.sendUserMessage(text, { deliverAs })`,然后返回。
136
+ - 无文本:回复 `Could not transcribe this voice message; please resend or type it.`,不触发 run,然后返回。
137
+ 2. 语音分支不调用 `resolveInboundImages()`,不调用 `saveInboundFiles()`。
138
+ 3. 语音与文字不组合,语音转写不参与 QQ 命令解析。
139
+ 4. 更新 `test/inbound.test.ts`:
140
+ - 有 ASR:`sendUserMessage` 收到文本;`saveFiles` 未被调用;`markQQTrigger` 调用 1 次。
141
+ - 空 ASR:只回复提示;不发送 user message;不触发 run。
142
+ - 语音不产生文件保存调用。
143
+ - 文字、图片、文件现有用例不回归。
144
+
145
+ **验证**
146
+
147
+ - `npm test -- test/voice.test.ts test/inbound.test.ts` 通过。
148
+ - 语音消息不会出现在 `saveInboundFiles()` 的附件参数中。
149
+ - 空 ASR 不会启动 agent。
150
+
151
+ ### M5b-3 — 文档与清理
152
+
153
+ **改动**
154
+
155
+ 1. `README.md`:
156
+ - 设置表移除 `debug`,新增 `logLevel`(默认 `silent`)。
157
+ - 说明日志路径 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。
158
+ - Usage 增加语音:直接使用 QQ ASR,不保存语音文件。
159
+ 2. `doc/features-v2.md`:按最终实现校正配置、日志路径和验收项。
160
+ 3. 确认 `log/` 下历史调试日志不进入提交;不新增代码向 `log/` 写入。
161
+ 4. 检查全仓库不再有 `debug` 配置引用(迁移读取除外)。
162
+
163
+ **验证**
164
+
165
+ - README 的配置示例与实际 `getSettings` 一致。
166
+ - `rg "debug"` 只命中迁移代码、历史文档或无关的调试函数名。
167
+ - `npx prettier --check .` 通过。
168
+
169
+ ## 3. Todo-List
170
+
171
+ ### 准备
172
+
173
+ - [x] 阅读 `doc/features-v2.md`,确认范围仅为 F8/F9
174
+ - [x] 运行基线 `npm test`、`npm run typecheck`
175
+ - [x] 确认不新增 npm 依赖
176
+
177
+ ### F9 — 日志基础设施
178
+
179
+ - [x] `src/logger.ts`:级别、过滤、JSONL、按天单文件
180
+ - [x] `src/logger.ts`:`PI_QQ_LOG_DIR` 覆盖、写入失败降级
181
+ - [x] `src/logger.ts`:`sdkLogger` 适配器
182
+ - [x] `src/config.ts`:`logLevel` 默认 `silent`,旧 `debug` 迁移
183
+ - [x] `src/index.ts`:`configureLogger`、移除 `getDebug`
184
+ - [x] `src/bot.ts`:接入 `sdkLogger`,移除 `debug` 选项
185
+ - [x] `src/inbound.ts` / `src/outbound.ts`:日志分级
186
+ - [x] `src/run-feedback.ts`:移除 debug 时间戳,改用 logger
187
+ - [x] `test/logger.test.ts`:级别、文件名、截断、写入失败
188
+ - [x] `test/config.test.ts`:默认值、显式级别、旧配置迁移
189
+ - [x] `test/run-feedback.test.ts`:移除 debug 时间戳用例
190
+ - [x] 验证 silent / info / debug 三档行为
191
+
192
+ ### F8 — 语音自动转写
193
+
194
+ - [x] `src/voice.ts`:`isVoiceAttachment()`、`resolveVoiceTranscript()`
195
+ - [x] `test/voice.test.ts`:识别、trim、空值、多值合并
196
+ - [x] `src/inbound.ts`:语音分支前置
197
+ - [x] `src/inbound.ts`:有 ASR 发送文本,无 ASR 回复提示
198
+ - [x] `src/inbound.ts`:语音不下载、不保存、不走图片/文件
199
+ - [x] `test/inbound.test.ts`:有 ASR / 空 ASR / 不保存文件
200
+ - [x] 确认文字、图片、文件用例不回归
201
+
202
+ ### 文档与收尾
203
+
204
+ - [x] `README.md`:`logLevel`、日志路径、语音说明
205
+ - [x] `doc/features-v2.md`:与实现保持一致
206
+ - [x] 清理临时调试说明
207
+ - [x] `npm test`
208
+ - [x] `npm run typecheck`
209
+ - [x] `npm run format:check`
210
+ - [x] QQ 实机语音验收
211
+
212
+ ## 4. 整体验证标准
213
+
214
+ ### 自动化
215
+
216
+ - `npm test` 全部通过;新增 `logger` / `voice` / `inbound` 用例。
217
+ - `npm run typecheck` 无错误。
218
+ - `npm run format:check` 通过。
219
+ - 全仓库无第三方日志依赖,`package.json` 依赖不变。
220
+
221
+ ### 实机验收
222
+
223
+ 1. QQ 发送语音“测试”:pi 直接收到 `"测试。"`,不是 `.amr` / `.silk` 路径。
224
+ 2. 不出现 `ffmpeg`、`pilk`、`faster-whisper` 等工具调用。
225
+ 3. 工作区 `.pi/pi-qq/` 下不新增该语音文件。
226
+ 4. 发送无法识别的语音或模拟空 ASR:QQ 收到提示,pi 不启动 run。
227
+ 5. `logLevel: "silent"`:不产生日志文件。
228
+ 6. `logLevel: "debug"`:日志文件包含 `asr_refer_text` 和完整附件;`info` 不含正文。
229
+ 7. 旧配置 `debug: true` 仍能开启 debug 日志。
230
+ 8. 文字、图片、文件消息行为与 v1 一致。
231
+
232
+ ## 5. 风险与预案
233
+
234
+ | 风险 | 影响 | 预案 |
235
+ | --- | --- | --- |
236
+ | ASR 为空或识别不准 | 语音无法转写 | 回复提示重发或打字;V2 不做语音回退 |
237
+ | 平台只返回 `voice` 的假定失效 | 语音分支不触发 | 以实测字段为准;若变化再扩展识别条件 |
238
+ | 日志目录不可写 | 无日志 | 捕获写入异常,消息处理继续 |
239
+ | 默认 `silent` 导致排查时无日志 | 诊断困难 | README 明确开启 `logLevel: "info"` / `"debug"` |
240
+ | 移除 debug 时间戳影响现有诊断 | QQ 气泡少时间戳 | 已确认日志级别不影响聊天展示;需要时后续加独立开关 |
241
+
242
+ ## 6. 执行记录
243
+
244
+ - 2026-10-30:M5a / M5b 代码与单测完成;`npm test` 97 项通过,`npm run typecheck`、`npm run format:check` 通过。
245
+ - 2026-10-30:QQ 实机语音验收通过。两条语音均直接使用 `asr_refer_text` 进入 pi;未保存 `.amr`,未调用本地转写工具;`logLevel: "debug"` 日志包含 ASR 元数据与全文。
package/index.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import { join } from "node:path";
2
3
  import { getSettings, readConfig, type Credentials } from "./src/config";
3
4
  import { startBot, type BotState, type RunningBot } from "./src/bot";
4
5
  import { runQrLogin } from "./src/login";
@@ -7,8 +8,9 @@ import { markdownToPlain, sendReply } from "./src/outbound";
7
8
  import { ReplyBudget } from "./src/reply-budget";
8
9
  import { RunFeedback } from "./src/run-feedback";
9
10
  import { AppendStream } from "./src/append-stream";
10
- import { formatTokenCount, formatUsageSummary, sumUsageMessages, type UsageTotals } from "./src/usage";
11
+ import { formatTokenCount } from "./src/format";
11
12
  import { formatBudgetStatus } from "./src/budget-status";
13
+ import { configureLogger, log, previewForLog } from "./src/logger";
12
14
 
13
15
  /**
14
16
  * pi-qq extension entry.
@@ -48,7 +50,6 @@ const runFeedback = new RunFeedback({
48
50
  getHeartbeatMaxMessages: () => getSettings(readConfig().config).heartbeatMaxMessages,
49
51
  getStreamRelay: () => getSettings(readConfig().config).streamRelay,
50
52
  getStreamFlushMs: () => getSettings(readConfig().config).streamFlushMs,
51
- getDebug: () => getSettings(readConfig().config).debug,
52
53
  makeChannel: () => ({
53
54
  budget,
54
55
  boundOpenid: getLoginState()?.allowedOpenid ?? "",
@@ -62,7 +63,7 @@ const fmtTokens = (n: number | null): string => (n === null ? "unknown" : format
62
63
  export default function (pi: ExtensionAPI) {
63
64
  const maskAppId = (appId: string) => `${appId.slice(0, 4)}****`;
64
65
 
65
- // —— 实时配置读取器(绑定/设置变更即时生效)——
66
+ // Live settings reader (binding/settings changes apply immediately).
66
67
 
67
68
  const getAllowedOpenid = () => getLoginState()?.allowedOpenid;
68
69
  const getBoundOpenid = getAllowedOpenid;
@@ -70,32 +71,6 @@ export default function (pi: ExtensionAPI) {
70
71
 
71
72
  const onWarn = (ctx: ExtensionContext) => (msg: string) => ctx.ui.notify(`pi-qq ${msg}`, "warning");
72
73
 
73
- /** F5/F6:在 agent_end 时快照本次 run 用量,返回发送函数(等时间线封口后再调用) */
74
- const prepareUsageSummary = (ctx: ExtensionContext, usage: UsageTotals): (() => void) | null => {
75
- const { config } = readConfig();
76
- const settings = getSettings(config);
77
- if (!settings.usageRelay) return null;
78
-
79
- const bound = getLoginState()?.allowedOpenid;
80
- const bot = running?.bot;
81
- const hasUsage = usage.input + usage.output + usage.cacheRead + usage.cacheWrite > 0;
82
- if (!bound || !bot || !hasUsage) return null;
83
-
84
- const summary = formatUsageSummary({
85
- usage,
86
- context: ctx.getContextUsage(),
87
- });
88
- // 快照文本,避免等待时间线封口期间新 run 覆盖本次数据
89
- return () => {
90
- if (running?.bot !== bot) return;
91
- void sendReply(bot, summary, {
92
- budget,
93
- boundOpenid: bound,
94
- onWarn: onWarn(ctx),
95
- });
96
- };
97
- };
98
-
99
74
  const getStatusLines = (): string[] => {
100
75
  const login = getLoginState();
101
76
  const usage = sessionCtx?.getContextUsage();
@@ -117,6 +92,15 @@ export default function (pi: ExtensionAPI) {
117
92
 
118
93
  const startWithCredentials = (ctx: ExtensionContext, creds: Credentials, allowedOpenid: string) => {
119
94
  const settings = getSettings(readConfig().config);
95
+ configureLogger(settings.logLevel, join(ctx.cwd, ".pi", "pi-qq", "logs"));
96
+ log.info("session", "starting bot", {
97
+ appId: creds.appId,
98
+ allowedOpenid,
99
+ cwd: ctx.cwd,
100
+ model: ctx.model?.name ?? null,
101
+ markdownSupport: settings.markdownSupport,
102
+ logLevel: settings.logLevel,
103
+ });
120
104
  running?.stop();
121
105
  stateDetail = undefined;
122
106
  sessionCtx = ctx;
@@ -124,7 +108,6 @@ export default function (pi: ExtensionAPI) {
124
108
  credentials: creds,
125
109
  allowedOpenid,
126
110
  markdownSupport: settings.markdownSupport,
127
- debug: settings.debug,
128
111
  onMessage: createInboundHandler({
129
112
  pi,
130
113
  ctx,
@@ -161,10 +144,20 @@ export default function (pi: ExtensionAPI) {
161
144
  // —— Lifecycle ——
162
145
 
163
146
  pi.on("session_start", (_event, ctx) => {
164
- const { error } = readConfig();
147
+ const { config, error } = readConfig();
148
+ const settings = getSettings(config);
149
+ configureLogger(settings.logLevel, join(ctx.cwd, ".pi", "pi-qq", "logs"));
165
150
  if (error) ctx.ui.notify(`pi-qq ${error}`, "error");
166
151
 
167
152
  const login = getLoginState();
153
+ log.info("session", "started", {
154
+ cwd: ctx.cwd,
155
+ hasUI: ctx.hasUI,
156
+ model: ctx.model?.name ?? null,
157
+ logLevel: settings.logLevel,
158
+ login: login ? { appId: login.credentials.appId, allowedOpenid: login.allowedOpenid } : null,
159
+ configError: error ?? null,
160
+ });
168
161
  if (login) {
169
162
  startWithCredentials(ctx, login.credentials, login.allowedOpenid);
170
163
  } else if (ctx.hasUI) {
@@ -173,40 +166,40 @@ export default function (pi: ExtensionAPI) {
173
166
  });
174
167
 
175
168
  pi.on("session_shutdown", () => {
169
+ log.info("session", "shutting down");
176
170
  stopIfRunning();
177
171
  sessionCtx = undefined;
178
172
  runFeedback.dispose();
179
173
  });
180
174
 
181
- // —— F7 run 级反馈:agent 生命周期 / 工具计数 / 文本流式 ——
175
+ // F7 run feedback: agent lifecycle / tool counts / text streaming.
182
176
 
183
177
  pi.on("agent_start", () => {
178
+ log.info("agent", "run started");
184
179
  runFeedback.onAgentStart();
185
180
  });
186
181
 
187
- pi.on("agent_end", (event, ctx) => {
188
- const lastAssistant = [...event.messages].reverse().find((message) => message.role === "assistant");
189
- // 错误/中止的 run 不发摘要:自动重试时避免每轮失败都刷一条消息
190
- const completed =
191
- lastAssistant !== undefined && lastAssistant.stopReason !== "error" && lastAssistant.stopReason !== "aborted";
192
- const wasQQRun = runFeedback.isQQTriggeredRun();
193
- // 在异步封口时间线前快照本次 run 的用量,避免新 run 覆盖
194
- const runUsage = sumUsageMessages(event.messages);
195
- const sendSummary = wasQQRun && completed ? prepareUsageSummary(ctx, runUsage) : null;
196
- // 先封口时间线气泡,再发用量摘要(保证 QQ 消息顺序)
197
- void runFeedback
198
- .onAgentEnd()
199
- .then(() => {
200
- sendSummary?.();
201
- })
202
- .catch(() => {});
182
+ pi.on("agent_end", () => {
183
+ log.info("agent", "run ended");
184
+ void runFeedback.onAgentEnd();
203
185
  });
204
186
 
205
187
  pi.on("tool_execution_start", (event) => {
188
+ log.debug("tool", "start", {
189
+ toolName: event.toolName,
190
+ toolCallId: event.toolCallId,
191
+ args: previewForLog(event.args),
192
+ });
206
193
  void runFeedback.onToolStart(event.toolName);
207
194
  });
208
195
 
209
196
  pi.on("tool_execution_end", (event) => {
197
+ log.debug("tool", "end", {
198
+ toolName: event.toolName,
199
+ toolCallId: event.toolCallId,
200
+ isError: event.isError,
201
+ result: previewForLog(event.result),
202
+ });
210
203
  runFeedback.onToolEnd(event.toolName, event.isError);
211
204
  });
212
205
 
@@ -224,19 +217,30 @@ export default function (pi: ExtensionAPI) {
224
217
  void runFeedback.onAssistantDelta(snapshot, thinking);
225
218
  });
226
219
 
227
- // —— pi → QQ:assistant 消息回传(非流式路径 + F7 流接管)——
220
+ // pi → QQ: assistant message relay (non-streaming path + F7 stream takeover).
228
221
 
229
222
  pi.on("message_end", async (event, ctx) => {
230
223
  const msg = event.message;
231
224
  if (msg.role !== "assistant" || !running) return;
232
225
 
226
+ log.debug("pi", "assistant message ended", {
227
+ stopReason: msg.stopReason,
228
+ contentTypes: msg.content.map((block) => block.type),
229
+ textPreview: previewForLog(
230
+ msg.content
231
+ .filter((block) => block.type === "text")
232
+ .map((block) => block.text)
233
+ .join("\n"),
234
+ ),
235
+ });
236
+
233
237
  const { config } = readConfig();
234
238
  const settings = getSettings(config);
235
239
  const isError = msg.stopReason === "error";
236
240
 
237
241
  let text: string;
238
242
  if (isError) {
239
- text = `⚠️ 模型调用失败:${msg.errorMessage ?? "未知错误"}`;
243
+ text = `⚠️ Model error: ${msg.errorMessage ?? "unknown error"}`;
240
244
  } else {
241
245
  text = msg.content
242
246
  .filter((b) => b.type === "text")
@@ -245,23 +249,28 @@ export default function (pi: ExtensionAPI) {
245
249
  .trim();
246
250
  }
247
251
  if (!text) {
248
- // 无文本的 assistant 消息同样结束本轮反馈状态:重置 thinking 标记/快照,
249
- // 并把待发思考行刷入活动气泡,避免下一条消息的思考被吞掉。
252
+ log.debug("pi", "assistant message has no text", { isError });
253
+ // Textless assistant messages also end the feedback turn: reset thinking state
254
+ // and flush pending thinking rows so the next message does not swallow them.
250
255
  await runFeedback.onAssistantFinal("", isError);
251
256
  return;
252
257
  }
253
258
 
254
- // F7 流接管:流式帧按 markdown 渲染(实测表格/代码块正常),传原始文本保证增量长度一致
255
- if (await runFeedback.onAssistantFinal(text, isError)) return;
259
+ // F7 stream takeover: stream frames render Markdown; send raw text so lengths match.
260
+ const streamTookOver = await runFeedback.onAssistantFinal(text, isError);
261
+ log.debug("pi", "stream takeover decision", { streamTookOver, isError, textPreview: previewForLog(text) });
262
+ if (streamTookOver) return;
256
263
 
257
264
  const payload = settings.markdownSupport ? text : markdownToPlain(text);
258
265
 
259
266
  const bound = getLoginState()?.allowedOpenid;
260
267
  if (!bound) {
268
+ log.warn("pi", "no bound user; reply skipped");
261
269
  ctx.ui.notify("pi-qq: no bound QQ user; skipping reply.", "warning");
262
270
  return;
263
271
  }
264
272
 
273
+ log.info("pi", "sending reply", { textLength: text.length, payloadLength: payload.length });
265
274
  void sendReply(running.bot, payload, {
266
275
  budget,
267
276
  boundOpenid: bound,
@@ -299,7 +308,7 @@ export default function (pi: ExtensionAPI) {
299
308
  },
300
309
  });
301
310
 
302
- pi.registerCommand("qq-budget", {
311
+ pi.registerCommand("qq-test-budget", {
303
312
  description: "pi-qq: show passive reply budget, stream bubbles, and last inbound target",
304
313
  handler: async (_args, ctx) => {
305
314
  ctx.ui.notify(formatBudgetStatus(budget.snapshot(), budget.lastTarget).join("\n"), "info");
@@ -336,7 +345,7 @@ export default function (pi: ExtensionAPI) {
336
345
  return bound ? { scope: "c2c" as const, targetId: bound } : undefined;
337
346
  };
338
347
 
339
- pi.registerCommand("qq-md", {
348
+ pi.registerCommand("qq-test-md", {
340
349
  description: "pi-qq: send a Markdown message to verify QQ C2C Markdown rendering",
341
350
  handler: async (args, ctx) => {
342
351
  if (!running) {
@@ -358,7 +367,7 @@ export default function (pi: ExtensionAPI) {
358
367
  },
359
368
  });
360
369
 
361
- pi.registerCommand("qq-stream-test", {
370
+ pi.registerCommand("qq-test-stream", {
362
371
  description: "pi-qq: run a streamed timeline diagnostic (thinking/tools/text)",
363
372
  handler: async (_args, ctx) => {
364
373
  if (!running) {
@@ -373,11 +382,11 @@ export default function (pi: ExtensionAPI) {
373
382
  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
374
383
  try {
375
384
  const stream = new AppendStream(running.bot.messageApi, running.bot.getCredentials(), last.openid, last.msgId);
376
- await stream.append("Thinking...\n[3] 🔧 bash\n[2] 🔧 read\n");
385
+ await stream.append("[💭] Thinking...\n[🔧] [3] bash\n[🔧] [2] read\n");
377
386
  await sleep(1200);
378
387
  await stream.append("\n**Intermediate message**: first-turn reply.\n");
379
388
  await sleep(1200);
380
- await stream.append("[1] 🔧 edit\n");
389
+ await stream.append("[🔧] [1] edit\n");
381
390
  await sleep(800);
382
391
  await stream.append("\n**Final reply** (streamed append)");
383
392
  let doneNote = "DONE succeeded";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@chen_hu_hu/pi-qq",
3
- "version": "1.0.1",
4
- "description": "pi 扩展:通过 QQ 机器人把 pi 接入 QQ 单人私聊(C2C)",
3
+ "version": "1.1.0",
4
+ "description": "Connect pi to QQ private chats.",
5
5
  "license": "MIT",
6
6
  "author": "CQ-Developer",
7
7
  "repository": {
@@ -7,16 +7,17 @@ import type {
7
7
  } from "@tencent-connect/qqbot-nodejs/protocol";
8
8
 
9
9
  /**
10
- * 追加模式(input_mode="append")的最小流式发送器。
10
+ * Minimal append-mode (input_mode="append") stream sender.
11
11
  *
12
- * SDK 内置 StreamSession 硬编码 input_mode="replace",2026-10 实测平台返回
13
- * 「已经提交的消息内容不可修改」拒绝 replace。追加语义下每帧 content_raw
14
- * 为**新增文本**,与平台"已提交内容不可变"规则一致。
12
+ * The SDK StreamSession hardcodes input_mode="replace"; in 2026-10 the platform
13
+ * rejected it with "submitted message content cannot be modified". In append mode
14
+ * each content_raw frame carries only the **new** text, matching the platform rule
15
+ * that already-submitted content is immutable.
15
16
  *
16
- * 内建两项保护(对齐 SDK StreamSession 的最佳实践):
17
- * 1. 节流:token 级增量先入缓冲,按节流窗口(默认 500ms,最小 300ms)合并成帧,
18
- * 避免高频 message_update 打爆 API。
19
- * 2. 限流退避:429 / err_code 50002 按指数退避重试(1s→2s→4s,最多 3 次)。
17
+ * Two built-in safeguards (aligned with SDK StreamSession best practices):
18
+ * 1. Throttle: token increments are buffered and merged into frames per throttle
19
+ * window (default 500ms, minimum 300ms) to avoid flooding the API.
20
+ * 2. Rate-limit backoff: 429 / err_code 50002 retry exponentially (1s→2s→4s, max 3).
20
21
  */
21
22
 
22
23
  const MIN_INTERVAL_MS = 300;
@@ -24,13 +25,13 @@ const RATE_LIMIT_BASE_MS = 1000;
24
25
  const MAX_RETRIES = 3;
25
26
 
26
27
  export interface AppendStreamOptions {
27
- /** 两帧之间的最小间隔;期间增量合并为一帧 */
28
+ /** Minimum interval between frames; increments are merged during the window. */
28
29
  throttleMs?: number;
29
- /** 限流退避基数(ms),测试用 */
30
+ /** Rate-limit backoff base in ms (for tests). */
30
31
  retryBaseMs?: number;
31
- /** 后台节流 flush 失败回调(此时流已不可信,调用方应标记降级) */
32
+ /** Background throttle flush failure (stream is no longer trusted). */
32
33
  onError?: (err: Error) => void;
33
- /** 诊断日志(debug 模式):限流重试/最终失败 */
34
+ /** Diagnostic log via the shared logger: rate-limit retries/final failures. */
34
35
  onDebug?: (message: string) => void;
35
36
  }
36
37
 
@@ -56,12 +57,12 @@ export class AppendStream {
56
57
  return Math.max(this.opts.throttleMs ?? 500, MIN_INTERVAL_MS);
57
58
  }
58
59
 
59
- /** 追加增量文本;内部按节流窗口合并成帧,立即返回(后台发送) */
60
+ /** Append text; frames are merged by throttle window and sent in the background. */
60
61
  async append(delta: string): Promise<void> {
61
62
  if (this.doneSent || !delta) return;
62
63
  this.buffer += delta;
63
64
  const elapsed = Date.now() - this.lastFlushAt;
64
- if (this.flushing) return; // 在途 flush 的 trailing 逻辑会接手缓冲
65
+ if (this.flushing) return; // The in-flight flush trailing logic will pick up the buffer.
65
66
  if (elapsed >= this.throttleMs()) {
66
67
  await this.doFlush("generating");
67
68
  return;
@@ -74,7 +75,7 @@ export class AppendStream {
74
75
  }
75
76
  }
76
77
 
77
- /** 发送剩余增量并收尾(DONE 帧)。错误向上抛给调用方。 */
78
+ /** Flush remaining text and send DONE. Errors propagate to the caller. */
78
79
  async done(): Promise<void> {
79
80
  if (this.doneSent) return;
80
81
  if (this.flushTimer) {
@@ -85,11 +86,11 @@ export class AppendStream {
85
86
  await new Promise((r) => setTimeout(r, 20));
86
87
  }
87
88
  if (this.buffer) await this.doFlush("generating");
88
- await this.doFlush("done"); // DONE 帧 content_raw 为空(已实测接受)
89
+ await this.doFlush("done"); // DONE frames carry empty content_raw (verified).
89
90
  this.doneSent = true;
90
91
  }
91
92
 
92
- /** 仅停止后台定时器(不发送 DONE;用于会话关闭等异常路径) */
93
+ /** Stop background timers only; no DONE (for shutdown/error paths). */
93
94
  dispose(): void {
94
95
  if (this.flushTimer) {
95
96
  clearTimeout(this.flushTimer);
@@ -101,13 +102,13 @@ export class AppendStream {
101
102
  private async doFlush(state: "generating" | "done"): Promise<void> {
102
103
  if (this.flushing) return;
103
104
  const content = state === "done" ? "" : this.buffer;
104
- // DONE 帧允许空内容(表示生成结束),generating 无内容则无需发送
105
+ // DONE frames may be empty (generation finished); empty generating frames are skipped.
105
106
  if (!content && state === "generating") return;
106
107
  this.flushing = true;
107
108
  let failed = false;
108
109
  try {
109
110
  if (this.msgSeq === null) this.msgSeq = getNextMsgSeq(this.msgId);
110
- // input_mode 超出 SDK 类型定义(仅 replace),运行时值由平台语义决定
111
+ // input_mode is outside the SDK type (replace only); the platform defines its runtime meaning.
111
112
  const req = {
112
113
  input_mode: "append",
113
114
  input_state: state === "done" ? StreamInputState.DONE : StreamInputState.GENERATING,
@@ -128,7 +129,7 @@ export class AppendStream {
128
129
  throw err;
129
130
  } finally {
130
131
  this.flushing = false;
131
- // trailing:flush 期间又有新增量 → 排下一帧
132
+ // Trailing: new data arrived during flush; schedule the next frame.
132
133
  if (!failed && state === "generating" && this.buffer && !this.doneSent && !this.flushTimer) {
133
134
  this.flushTimer = setTimeout(() => {
134
135
  this.flushTimer = null;