@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/README.md +21 -13
- package/doc/{features.md → features-v1.md} +28 -50
- package/doc/features-v2.md +97 -0
- package/doc/{plan.md → plan-v1.md} +23 -28
- package/doc/plan-v2.md +245 -0
- package/index.ts +68 -59
- package/package.json +2 -2
- package/src/append-stream.ts +21 -20
- package/src/bot.ts +58 -20
- package/src/budget-status.ts +1 -1
- package/src/config.ts +9 -8
- package/src/download.ts +11 -11
- package/src/files.ts +10 -10
- package/src/format.ts +6 -1
- package/src/images.ts +25 -13
- package/src/inbound.ts +103 -26
- package/src/logger.ts +180 -0
- package/src/outbound.ts +42 -25
- package/src/qrcode-terminal.d.ts +1 -1
- package/src/reply-budget.ts +15 -15
- package/src/run-feedback.ts +85 -102
- package/src/voice.ts +25 -0
- package/src/usage.ts +0 -93
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
|
|
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
|
-
//
|
|
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", (
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
//
|
|
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 = `⚠️
|
|
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
|
-
|
|
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
|
|
255
|
-
|
|
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
|
|
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]
|
|
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]
|
|
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
package/src/append-stream.ts
CHANGED
|
@@ -7,16 +7,17 @@ import type {
|
|
|
7
7
|
} from "@tencent-connect/qqbot-nodejs/protocol";
|
|
8
8
|
|
|
9
9
|
/**
|
|
10
|
-
*
|
|
10
|
+
* Minimal append-mode (input_mode="append") stream sender.
|
|
11
11
|
*
|
|
12
|
-
* SDK
|
|
13
|
-
*
|
|
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
|
-
*
|
|
17
|
-
* 1.
|
|
18
|
-
*
|
|
19
|
-
* 2.
|
|
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
|
-
/**
|
|
30
|
+
/** Rate-limit backoff base in ms (for tests). */
|
|
30
31
|
retryBaseMs?: number;
|
|
31
|
-
/**
|
|
32
|
+
/** Background throttle flush failure (stream is no longer trusted). */
|
|
32
33
|
onError?: (err: Error) => void;
|
|
33
|
-
/**
|
|
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; //
|
|
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
|
-
/**
|
|
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
|
|
89
|
+
await this.doFlush("done"); // DONE frames carry empty content_raw (verified).
|
|
89
90
|
this.doneSent = true;
|
|
90
91
|
}
|
|
91
92
|
|
|
92
|
-
/**
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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;
|