@chen_hu_hu/pi-qq 1.0.2 → 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 +16 -7
- package/doc/features-v1.md +1 -1
- package/doc/features-v2.md +97 -0
- package/doc/plan-v1.md +1 -1
- package/doc/plan-v2.md +245 -0
- package/index.ts +54 -5
- package/package.json +1 -1
- package/src/append-stream.ts +1 -1
- package/src/bot.ts +43 -5
- package/src/config.ts +7 -3
- package/src/download.ts +8 -8
- package/src/files.ts +4 -4
- package/src/images.ts +19 -7
- package/src/inbound.ts +96 -19
- package/src/logger.ts +180 -0
- package/src/outbound.ts +20 -3
- package/src/run-feedback.ts +24 -36
- package/src/voice.ts +25 -0
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# pi-qq
|
|
2
2
|
|
|
3
|
-
Connect [pi](https://github.com/earendil-works/pi) to a QQ private chat. Send text, images, or files from mobile QQ; pi works on your machine and sends the result back to QQ.
|
|
3
|
+
Connect [pi](https://github.com/earendil-works/pi) to a QQ private chat. Send text, voice, images, or files from mobile QQ; pi works on your machine and sends the result back to QQ.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -27,6 +27,7 @@ Credentials are kept in process memory only. Restarting pi requires scanning aga
|
|
|
27
27
|
Send a QQ private message to the bot to start a task.
|
|
28
28
|
|
|
29
29
|
- **Text**: normal chat message.
|
|
30
|
+
- **Voice**: QQ built-in ASR text is sent to pi directly; the audio is not downloaded or saved. If ASR returns no text, the bot asks you to resend or type it.
|
|
30
31
|
- **Images**: sent to pi as vision input.
|
|
31
32
|
- **Files**: saved under the current workspace at `.pi/pi-qq/YYYY-MM-DD/<msgId>/`; the saved path, size, and original filename are added to the prompt.
|
|
32
33
|
|
|
@@ -40,6 +41,16 @@ User message:
|
|
|
40
41
|
Summarize this file.
|
|
41
42
|
```
|
|
42
43
|
|
|
44
|
+
### Voice messages
|
|
45
|
+
|
|
46
|
+
Voice messages use QQ's built-in ASR (`asr_refer_text`). The transcript is sent to pi as normal user text; pi never receives the audio file.
|
|
47
|
+
|
|
48
|
+
- The voice attachment is not downloaded or saved as `.amr` / `.silk`.
|
|
49
|
+
- No local or external speech-to-text service is used.
|
|
50
|
+
- If QQ ASR returns no text, the bot replies `Could not transcribe this voice message; please resend or type it.` and does not start a pi run.
|
|
51
|
+
- Voice and text are separate QQ messages; send them one after another when needed.
|
|
52
|
+
- To inspect the raw ASR result, set `logLevel` to `debug`; the log includes `asr_refer_text` and attachment metadata.
|
|
53
|
+
|
|
43
54
|
## Commands
|
|
44
55
|
|
|
45
56
|
Run these in the pi terminal:
|
|
@@ -72,7 +83,7 @@ Create `~/.pi/agent/pi-qq.json` to override defaults. This file contains setting
|
|
|
72
83
|
{
|
|
73
84
|
"markdownSupport": false,
|
|
74
85
|
"streamFlushMs": 10000,
|
|
75
|
-
"
|
|
86
|
+
"logLevel": "silent"
|
|
76
87
|
}
|
|
77
88
|
```
|
|
78
89
|
|
|
@@ -87,7 +98,9 @@ Create `~/.pi/agent/pi-qq.json` to override defaults. This file contains setting
|
|
|
87
98
|
| `heartbeatMaxMessages` | `3` | Per-run message heartbeat limit |
|
|
88
99
|
| `streamRelay` | `true` | Use append-mode stream bubbles |
|
|
89
100
|
| `streamFlushMs` | `10000` | Stream summary frame interval in ms (minimum 300) |
|
|
90
|
-
| `
|
|
101
|
+
| `logLevel` | `"silent"` | Log threshold: `silent`, `error`, `warn`, `info`, or `debug` |
|
|
102
|
+
|
|
103
|
+
When enabled, logs are written to `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`. `PI_QQ_LOG_DIR` overrides the directory. `info` records metadata only; `debug` records full events, attachments, prompts, and tool payloads. Legacy `debug: true` maps to `logLevel: "debug"`.
|
|
91
104
|
|
|
92
105
|
## Notes
|
|
93
106
|
|
|
@@ -95,7 +108,3 @@ Create `~/.pi/agent/pi-qq.json` to override defaults. This file contains setting
|
|
|
95
108
|
- Incoming images are passed to the model as vision input; the current model must support image input.
|
|
96
109
|
- Saved files are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
|
|
97
110
|
- QQ limits passive replies per inbound message. Use `/qq-test-budget` to inspect the local budget.
|
|
98
|
-
|
|
99
|
-
## License
|
|
100
|
-
|
|
101
|
-
MIT
|
package/doc/features-v1.md
CHANGED
|
@@ -157,7 +157,7 @@ pi-qq 扩展 ── pi.sendUserMessage(text+images) ─┴─ pi 事件:
|
|
|
157
157
|
- **额度提示**:每条文本消息、每段活动各占一条 msg_seq 消息;长回合任务的气泡数多于单气泡模式,需关注被动额度;若平台拒绝(帧失败),该回合自动降级消息路径,文本仍完整送达。
|
|
158
158
|
- **降级**:任何一帧失败即标 dead,已追加部分作废,未发出的结果文本自动转消息路径补发;`streamRelay: false` 时整条时间线关闭,assistant 消息走普通消息路径(M2 行为)。
|
|
159
159
|
- **typing 保鲜**:run 开始立即发送"正在输入",之后每 50s 续期(0 额度),`agent_end` 清理。
|
|
160
|
-
- **空窗口活性线**:窗口无增量且静默 ≥60s 时补一条 `⏱
|
|
160
|
+
- **空窗口活性线**:窗口无增量且静默 ≥60s 时补一条 `⏱ Running for X minutes…`——长思考/单工具长执行期间每分钟一行,不再无推送(debug 模式带时间戳)。
|
|
161
161
|
- **心跳兜底**:流不可用时降级为普通消息心跳(每 run ≤3 条保险丝;debug 模式带时间戳)。
|
|
162
162
|
- 不发送"已收到"开始确认(节省被动额度):QQ 触发的 run 在首个汇总帧前保持安静。
|
|
163
163
|
- 非 QQ 触发的 run(本地终端)不发心跳/时间线,但 assistant 消息仍照常回传(现状)。
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# pi-qq — features-v2.md
|
|
2
|
+
|
|
3
|
+
> V2 增量:F8 语音自动转写、F9 轻量日志基础设施。
|
|
4
|
+
> 基线见 [features-v1.md](./features-v1.md);本文只描述新增/变更内容。
|
|
5
|
+
|
|
6
|
+
## 1. 背景与结论
|
|
7
|
+
|
|
8
|
+
- 当前语音附件被当作普通文件保存,pi 只能本地解码 SILK 并转写;慢且可能误识别。
|
|
9
|
+
- 实测确认 C2C 语音消息的 `attachments[]` 包含 `asr_refer_text`(示例:`"测试。"`),`content` 为空;SDK 1.0.5 已透传该字段。
|
|
10
|
+
- 结论:直接使用 QQ 内置 ASR;不下载语音附件,不接本地或外部 STT。
|
|
11
|
+
|
|
12
|
+
## 2. F8 语音消息自动转写
|
|
13
|
+
|
|
14
|
+
### 触发与识别
|
|
15
|
+
|
|
16
|
+
- 仅 C2C、白名单用户。
|
|
17
|
+
- `content_type === "voice"` 视为语音消息。
|
|
18
|
+
- 读取并 trim `asr_refer_text`。
|
|
19
|
+
|
|
20
|
+
### 行为
|
|
21
|
+
|
|
22
|
+
| 情况 | 处理 |
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| 有 ASR 文本 | `markQQTrigger()` → `pi.sendUserMessage(text, { deliverAs })` |
|
|
25
|
+
| ASR 为空 | 回复 `Could not transcribe this voice message; please resend or type it.`,不触发 run |
|
|
26
|
+
| 语音消息 | 不下载 `url` / `voice_wav_url`,不保存文件,不走图片/文件分支 |
|
|
27
|
+
|
|
28
|
+
- 语音和文字是两条独立消息,不做同条组合。
|
|
29
|
+
- 转写文本不参与 QQ 命令解析,作为普通用户消息交给 pi。
|
|
30
|
+
- 正常一条语音消息只有一个语音附件;多值时按顺序换行拼接,仅作防御。
|
|
31
|
+
|
|
32
|
+
### 不实现
|
|
33
|
+
|
|
34
|
+
- 本地 Whisper 或外部 STT 回退
|
|
35
|
+
- 保存原始语音
|
|
36
|
+
|
|
37
|
+
### 代码边界
|
|
38
|
+
|
|
39
|
+
- 新增 `src/voice.ts`:`isVoiceAttachment()`、`resolveVoiceTranscript()`。
|
|
40
|
+
- `src/inbound.ts`:在图片/文件分流前增加语音分支,处理完直接返回。
|
|
41
|
+
|
|
42
|
+
### 验收
|
|
43
|
+
|
|
44
|
+
- 发语音后 pi 直接收到文本,不出现 `.amr` / `.silk` 路径。
|
|
45
|
+
- 无 `ffmpeg`、`pilk`、`faster-whisper` 等调用,工作区不新增语音文件。
|
|
46
|
+
- 空 ASR 只回提示,不启动 agent。
|
|
47
|
+
- 文字、图片、文件行为不变。
|
|
48
|
+
|
|
49
|
+
## 3. F9 日志基础设施
|
|
50
|
+
|
|
51
|
+
### 实现
|
|
52
|
+
|
|
53
|
+
- 自研轻量 logger,不引入第三方框架。
|
|
54
|
+
- 单文件按天:`<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;可用 `PI_QQ_LOG_DIR` 覆盖。
|
|
55
|
+
- 每条一行 JSON:`time`、`level`、`scope`、`msg` + 结构化字段。
|
|
56
|
+
- 日志写入失败不得影响 QQ 消息处理。
|
|
57
|
+
- SDK 日志接入同一 logger。
|
|
58
|
+
|
|
59
|
+
### 配置
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"logLevel": "silent"
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
| 级别 | 输出 |
|
|
68
|
+
| --- | --- |
|
|
69
|
+
| `silent` | 不写日志(默认) |
|
|
70
|
+
| `error` | error |
|
|
71
|
+
| `warn` | warn + error |
|
|
72
|
+
| `info` | info + warn + error |
|
|
73
|
+
| `debug` | 全部,含 raw 事件、附件、prompt、工具参数/结果、正文 |
|
|
74
|
+
|
|
75
|
+
- 配置键使用 `logLevel`,不使用 `log_level`。
|
|
76
|
+
- 移除 `debug` 配置;旧 `debug: true` 迁移为 `logLevel: "debug"`,其他情况默认 `silent`。
|
|
77
|
+
- 移除 `debug` 控制的 QQ 气泡时间戳;日志级别不影响聊天展示。
|
|
78
|
+
- `info` 只记元数据(如 `hasAsr`、`asrLength`);`debug` 才记录 `asr_refer_text` 全文和完整附件。
|
|
79
|
+
|
|
80
|
+
### 验收
|
|
81
|
+
|
|
82
|
+
- 各级别过滤正确;默认 `silent` 不产生日志。
|
|
83
|
+
- `logLevel: "debug"` 能看到语音原始附件和 ASR 文本;`info` 看不到正文。
|
|
84
|
+
- 旧 `debug` 配置可迁移。
|
|
85
|
+
- 日志路径、日期滚动、写入失败降级正常。
|
|
86
|
+
|
|
87
|
+
## 4. 配置变更
|
|
88
|
+
|
|
89
|
+
| 配置 | 变更 |
|
|
90
|
+
| --- | --- |
|
|
91
|
+
| `logLevel` | 新增;默认 `silent` |
|
|
92
|
+
| `debug` | 移除;仅保留迁移读取 |
|
|
93
|
+
|
|
94
|
+
## 5. 限制
|
|
95
|
+
|
|
96
|
+
- `asr_refer_text` 可能为空或识别不准确;V2 只提示用户重发或改用文字,不做回退。
|
|
97
|
+
- `debug` 日志可能包含消息正文和 URL token,仅在排查时本地开启。
|
package/doc/plan-v1.md
CHANGED
|
@@ -186,5 +186,5 @@ pi-qq/
|
|
|
186
186
|
- [x] `debug` 抓超时日志:AppendStream 限流重试/最终失败 + run start/end 日志
|
|
187
187
|
- [x] 验收:QQ 发图后 pi 能描述图片内容;全程额度不超限(2026-10-29 实测通过)
|
|
188
188
|
- [x] 文件传输实机验收(2026-10-29 用户实测通过:QQ 发 zip/pdf 等文件,保存到工作空间 `.pi/pi-qq/` 并在提示词中关联路径)
|
|
189
|
-
- 2026-10-29:图片+文字、纯图片(均被模型正确识别)、非图片附件拒绝(zip
|
|
189
|
+
- 2026-10-29:图片+文字、纯图片(均被模型正确识别)、非图片附件拒绝(zip 提示“Attachment failed”)、多气泡+摘要额度诊断已实测通过。
|
|
190
190
|
- 无视觉模型场景按用户决定不验证(代码仍保留 `ctx.model.input` 检查)。
|
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";
|
|
@@ -9,6 +10,7 @@ import { RunFeedback } from "./src/run-feedback";
|
|
|
9
10
|
import { AppendStream } from "./src/append-stream";
|
|
10
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 ?? "",
|
|
@@ -91,6 +92,15 @@ export default function (pi: ExtensionAPI) {
|
|
|
91
92
|
|
|
92
93
|
const startWithCredentials = (ctx: ExtensionContext, creds: Credentials, allowedOpenid: string) => {
|
|
93
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
|
+
});
|
|
94
104
|
running?.stop();
|
|
95
105
|
stateDetail = undefined;
|
|
96
106
|
sessionCtx = ctx;
|
|
@@ -98,7 +108,6 @@ export default function (pi: ExtensionAPI) {
|
|
|
98
108
|
credentials: creds,
|
|
99
109
|
allowedOpenid,
|
|
100
110
|
markdownSupport: settings.markdownSupport,
|
|
101
|
-
debug: settings.debug,
|
|
102
111
|
onMessage: createInboundHandler({
|
|
103
112
|
pi,
|
|
104
113
|
ctx,
|
|
@@ -135,10 +144,20 @@ export default function (pi: ExtensionAPI) {
|
|
|
135
144
|
// —— Lifecycle ——
|
|
136
145
|
|
|
137
146
|
pi.on("session_start", (_event, ctx) => {
|
|
138
|
-
const { error } = readConfig();
|
|
147
|
+
const { config, error } = readConfig();
|
|
148
|
+
const settings = getSettings(config);
|
|
149
|
+
configureLogger(settings.logLevel, join(ctx.cwd, ".pi", "pi-qq", "logs"));
|
|
139
150
|
if (error) ctx.ui.notify(`pi-qq ${error}`, "error");
|
|
140
151
|
|
|
141
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
|
+
});
|
|
142
161
|
if (login) {
|
|
143
162
|
startWithCredentials(ctx, login.credentials, login.allowedOpenid);
|
|
144
163
|
} else if (ctx.hasUI) {
|
|
@@ -147,6 +166,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
147
166
|
});
|
|
148
167
|
|
|
149
168
|
pi.on("session_shutdown", () => {
|
|
169
|
+
log.info("session", "shutting down");
|
|
150
170
|
stopIfRunning();
|
|
151
171
|
sessionCtx = undefined;
|
|
152
172
|
runFeedback.dispose();
|
|
@@ -155,18 +175,31 @@ export default function (pi: ExtensionAPI) {
|
|
|
155
175
|
// F7 run feedback: agent lifecycle / tool counts / text streaming.
|
|
156
176
|
|
|
157
177
|
pi.on("agent_start", () => {
|
|
178
|
+
log.info("agent", "run started");
|
|
158
179
|
runFeedback.onAgentStart();
|
|
159
180
|
});
|
|
160
181
|
|
|
161
182
|
pi.on("agent_end", () => {
|
|
183
|
+
log.info("agent", "run ended");
|
|
162
184
|
void runFeedback.onAgentEnd();
|
|
163
185
|
});
|
|
164
186
|
|
|
165
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
|
+
});
|
|
166
193
|
void runFeedback.onToolStart(event.toolName);
|
|
167
194
|
});
|
|
168
195
|
|
|
169
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
|
+
});
|
|
170
203
|
runFeedback.onToolEnd(event.toolName, event.isError);
|
|
171
204
|
});
|
|
172
205
|
|
|
@@ -190,13 +223,24 @@ export default function (pi: ExtensionAPI) {
|
|
|
190
223
|
const msg = event.message;
|
|
191
224
|
if (msg.role !== "assistant" || !running) return;
|
|
192
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
|
+
|
|
193
237
|
const { config } = readConfig();
|
|
194
238
|
const settings = getSettings(config);
|
|
195
239
|
const isError = msg.stopReason === "error";
|
|
196
240
|
|
|
197
241
|
let text: string;
|
|
198
242
|
if (isError) {
|
|
199
|
-
text = `⚠️
|
|
243
|
+
text = `⚠️ Model error: ${msg.errorMessage ?? "unknown error"}`;
|
|
200
244
|
} else {
|
|
201
245
|
text = msg.content
|
|
202
246
|
.filter((b) => b.type === "text")
|
|
@@ -205,6 +249,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
205
249
|
.trim();
|
|
206
250
|
}
|
|
207
251
|
if (!text) {
|
|
252
|
+
log.debug("pi", "assistant message has no text", { isError });
|
|
208
253
|
// Textless assistant messages also end the feedback turn: reset thinking state
|
|
209
254
|
// and flush pending thinking rows so the next message does not swallow them.
|
|
210
255
|
await runFeedback.onAssistantFinal("", isError);
|
|
@@ -212,16 +257,20 @@ export default function (pi: ExtensionAPI) {
|
|
|
212
257
|
}
|
|
213
258
|
|
|
214
259
|
// F7 stream takeover: stream frames render Markdown; send raw text so lengths match.
|
|
215
|
-
|
|
260
|
+
const streamTookOver = await runFeedback.onAssistantFinal(text, isError);
|
|
261
|
+
log.debug("pi", "stream takeover decision", { streamTookOver, isError, textPreview: previewForLog(text) });
|
|
262
|
+
if (streamTookOver) return;
|
|
216
263
|
|
|
217
264
|
const payload = settings.markdownSupport ? text : markdownToPlain(text);
|
|
218
265
|
|
|
219
266
|
const bound = getLoginState()?.allowedOpenid;
|
|
220
267
|
if (!bound) {
|
|
268
|
+
log.warn("pi", "no bound user; reply skipped");
|
|
221
269
|
ctx.ui.notify("pi-qq: no bound QQ user; skipping reply.", "warning");
|
|
222
270
|
return;
|
|
223
271
|
}
|
|
224
272
|
|
|
273
|
+
log.info("pi", "sending reply", { textLength: text.length, payloadLength: payload.length });
|
|
225
274
|
void sendReply(running.bot, payload, {
|
|
226
275
|
budget,
|
|
227
276
|
boundOpenid: bound,
|
package/package.json
CHANGED
package/src/append-stream.ts
CHANGED
|
@@ -31,7 +31,7 @@ export interface AppendStreamOptions {
|
|
|
31
31
|
retryBaseMs?: number;
|
|
32
32
|
/** Background throttle flush failure (stream is no longer trusted). */
|
|
33
33
|
onError?: (err: Error) => void;
|
|
34
|
-
/** Diagnostic log
|
|
34
|
+
/** Diagnostic log via the shared logger: rate-limit retries/final failures. */
|
|
35
35
|
onDebug?: (message: string) => void;
|
|
36
36
|
}
|
|
37
37
|
|