@chen_hu_hu/pi-qq 1.3.6 → 1.4.1
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 +21 -1
- package/README-zh.md +1 -1
- package/README.md +1 -1
- package/doc/archive/delivery-v4.md +327 -0
- package/doc/todo.md +107 -2
- package/index.ts +64 -0
- package/package.json +1 -1
- package/src/attachments/file-attachments.ts +1 -2
- package/src/infra/file-logger.ts +0 -1
- package/src/infra/power-status.ts +1 -3
- package/src/infra/settings.ts +0 -4
- package/src/qq/inbound-attachments.ts +0 -6
- package/src/qq/inbound-command.ts +7 -1
- package/src/qq/qq-diagnostics.ts +2 -6
- package/src/qq/qr-login.ts +0 -2
- package/src/qq/reply-sender.ts +5 -1
- package/src/relay/bubble-writer.ts +109 -32
- package/src/relay/run-stream-relay.ts +165 -30
- package/src/relay/stream-block-format.ts +139 -26
- package/src/relay/stream-session.ts +27 -4
- package/doc/archive/README.md +0 -18
- package/doc/archive/delivery-v1-zh.md +0 -161
- package/doc/archive/delivery-v2-zh.md +0 -101
- package/doc/archive/delivery-v3-zh.md +0 -190
- package/doc/bugfix-v4.md +0 -698
- package/doc/enhance-status.md +0 -427
- package/doc/send-skill.md +0 -257
- package/doc/tool-return.md +0 -378
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [1.4.1] - 2026-11-04
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- Removed the archived Chinese delivery records from `doc/archive/` and dropped `doc/archive/README.md`.
|
|
15
|
+
- Removed code comments from the TypeScript sources, tests, configuration, and release workflow.
|
|
16
|
+
|
|
17
|
+
## [1.4.0] - 2026-11-04
|
|
18
|
+
|
|
19
|
+
### Added
|
|
20
|
+
|
|
21
|
+
- Debug diagnostics for long-running tools: tool duration/update summaries, stream frame error codes, writer state, `/last` repush, `/stop` wait time, and event-loop timer drift. Logging only; no runtime behavior change.
|
|
22
|
+
|
|
23
|
+
### Changed
|
|
24
|
+
|
|
25
|
+
- Tool bubbles now use `## <icon> <name>`, show `bash` commands in a `bash` code block without truncation, and choose result code-block languages from `read` file extensions (for example `markdown`, `python`, `json`).
|
|
26
|
+
- Consolidated the v4 design and investigation records into `doc/archive/delivery-v4.md` and `doc/archive/delivery-v4-zh.md`.
|
|
27
|
+
|
|
10
28
|
## [1.3.6] - 2026-11-04
|
|
11
29
|
|
|
12
30
|
### Added
|
|
@@ -85,7 +103,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
85
103
|
- Added thinking labels, per-tool icons, model-error recovery, and idle-safe session handling.
|
|
86
104
|
- Reorganized modules by bounded context and updated settings and delivery documentation.
|
|
87
105
|
|
|
88
|
-
[Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.
|
|
106
|
+
[Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.1...HEAD
|
|
107
|
+
[1.4.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.0...v1.4.1
|
|
108
|
+
[1.4.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.6...v1.4.0
|
|
89
109
|
[1.3.6]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.5...v1.3.6
|
|
90
110
|
[1.3.5]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.4...v1.3.5
|
|
91
111
|
[1.3.4]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.3...v1.3.4
|
package/README-zh.md
CHANGED
|
@@ -76,7 +76,7 @@ Summarize this file.
|
|
|
76
76
|
### 回复格式
|
|
77
77
|
|
|
78
78
|
- **思考**:独立气泡,纯文本,首行 `**💭 思考**`。长思考可能续到新气泡,并重复标题。
|
|
79
|
-
- **工具**:每次调用独立气泡,首行
|
|
79
|
+
- **工具**:每次调用独立气泡,首行 `## <图标> <工具名>`;`bash` 命令使用 `bash` 代码块,其他参数使用行内代码;结果按工具/文件类型使用 `text`、`markdown`、`python`、`json` 等代码块。
|
|
80
80
|
- **普通消息**:原文,不加标题。
|
|
81
81
|
- **工具图标**:💻 bash、📖 read、📝 write、✏️ edit、🔎 grep、🔍 search、🗂️ find、📁 ls、📋 list、🌐 web、📡 fetch、🗑️ delete、❌ remove、✅ todo、🧪 test;未配置工具使用 🔧。
|
|
82
82
|
- **错误恢复**:模型错误后 60 秒内自动恢复的 run 会继续推送到原 QQ 会话;`/stop` 会等待当前工具和流收尾后再回复。
|
package/README.md
CHANGED
|
@@ -76,7 +76,7 @@ Debug logs include the raw `asr_refer_text` and attachment metadata when `logLev
|
|
|
76
76
|
### Reply format
|
|
77
77
|
|
|
78
78
|
- **Thinking**: its own bubble, plain text, starting with `**💭 思考**`. Long thinking may continue in a new bubble with the header repeated.
|
|
79
|
-
- **Tools**: one bubble per call:
|
|
79
|
+
- **Tools**: one bubble per call: `## <icon> <name>`; `bash` commands use a `bash` code block, other arguments use inline code, and results use `text`, `markdown`, `python`, `json`, etc. depending on the tool and file type.
|
|
80
80
|
- **Regular messages**: raw text with no header.
|
|
81
81
|
- **Tool icons**: 💻 bash, 📖 read, 📝 write, ✏️ edit, 🔎 grep, 🔍 search, 🗂️ find, 📁 ls, 📋 list, 🌐 web, 📡 fetch, 🗑️ delete, ❌ remove, ✅ todo, 🧪 test; unconfigured tools use 🔧.
|
|
82
82
|
- **Error recovery**: after a model error, automatic retry runs within 60 seconds keep pushing to the original QQ chat. `/stop` waits for active tools and streams to finish before replying.
|
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
# pi-qq delivery-v4
|
|
2
|
+
|
|
3
|
+
> **Archived record.** Content reflects the v4 delivery snapshot and may reference behavior that has since changed. See [README](../../README.md) for current behavior.
|
|
4
|
+
> Status: v4 delivered. Tool block types were verified on real QQ; long-running tool handling and offline delivery remain open items.
|
|
5
|
+
> Version: 1.4.0
|
|
6
|
+
> Date: 2026-11-04
|
|
7
|
+
> Previous: [delivery-v1.md](./delivery-v1.md), [delivery-v2.md](./delivery-v2.md), [delivery-v3.md](./delivery-v3.md).
|
|
8
|
+
> Open work: [doc/todo.md](../todo.md).
|
|
9
|
+
|
|
10
|
+
## 1. Scope
|
|
11
|
+
|
|
12
|
+
v4 is an output-quality and observability release. This record consolidates six former v4 working documents (names are historical):
|
|
13
|
+
|
|
14
|
+
- tool start visibility (`tool-return`);
|
|
15
|
+
- skill display (`send-skill`);
|
|
16
|
+
- `/status`, language, and battery (`enhance-status`);
|
|
17
|
+
- QQ background delivery (`bugfix-v4`);
|
|
18
|
+
- long-running tools (`long-tool`);
|
|
19
|
+
- tool result code-block types (`block-type`).
|
|
20
|
+
|
|
21
|
+
The main changes are:
|
|
22
|
+
|
|
23
|
+
1. a new tool output format with typed code blocks;
|
|
24
|
+
2. a dedicated Skill block for `SKILL.md` reads;
|
|
25
|
+
3. `/status` and `/qq-status` with agent state, language, and battery;
|
|
26
|
+
4. QQ-side `/last` as a manual recovery path;
|
|
27
|
+
5. debug diagnostics for long tools and stream failures.
|
|
28
|
+
|
|
29
|
+
The release does not change the transport: pi-qq still uses QQ C2C private messages, passive replies, and `stream_messages` for long output.
|
|
30
|
+
|
|
31
|
+
## 2. Tool output
|
|
32
|
+
|
|
33
|
+
### 2.1 Layout
|
|
34
|
+
|
|
35
|
+
Each content block gets its own bubble. Thinking stays plain text:
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
**💭 思考**
|
|
39
|
+
|
|
40
|
+
reasoning...
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Tool calls use a second-level heading:
|
|
44
|
+
|
|
45
|
+
````markdown
|
|
46
|
+
## 💻 bash
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npm test
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
12 passed
|
|
54
|
+
```
|
|
55
|
+
````
|
|
56
|
+
|
|
57
|
+
Rules:
|
|
58
|
+
|
|
59
|
+
- the tool header is `## <icon> <name>`;
|
|
60
|
+
- `bash` commands use a `bash` code block and preserve newlines;
|
|
61
|
+
- commands are displayed in full, without the old 200-character argument limit;
|
|
62
|
+
- `read` / `write` / `edit` keep their path as inline code;
|
|
63
|
+
- other tools keep their primary argument as inline code;
|
|
64
|
+
- tool call and result stay in the same bubble;
|
|
65
|
+
- a tool bubble is never split between the call and its result.
|
|
66
|
+
|
|
67
|
+
Result code-block language is chosen by tool and, for `read`, by file extension:
|
|
68
|
+
|
|
69
|
+
| Source | Result language |
|
|
70
|
+
| --------------------- | ----------------------------------------------------- |
|
|
71
|
+
| `bash` | `text` |
|
|
72
|
+
| `write`, `edit` | `text` |
|
|
73
|
+
| `read` | language from extension; unknown falls back to `text` |
|
|
74
|
+
| error or empty result | `text` |
|
|
75
|
+
| other tools | `text` |
|
|
76
|
+
|
|
77
|
+
Common mappings include `md` → `markdown`, `json` → `json`, `yaml` → `yaml`, `ts` → `typescript`, `tsx` → `tsx`, `js` → `javascript`, `py` → `python`, `sh`/`bash`/`zsh` → `bash`, `html` → `html`, `css` → `css`, `sql` → `sql`, `rs` → `rust`, `go` → `go`, and `diff`/`patch` → `diff`.
|
|
78
|
+
|
|
79
|
+
Special file names:
|
|
80
|
+
|
|
81
|
+
- `Dockerfile` → `dockerfile`;
|
|
82
|
+
- `Makefile` → `makefile`;
|
|
83
|
+
- `CMakeLists.txt` → `cmake`;
|
|
84
|
+
- `README` → `markdown`.
|
|
85
|
+
|
|
86
|
+
Empty and failed results always use `text`. Result text is still capped at 600 characters / 8 lines; the bash command itself is not truncated.
|
|
87
|
+
|
|
88
|
+
Fixed tool icons:
|
|
89
|
+
|
|
90
|
+
| Tool | Icon | Tool | Icon |
|
|
91
|
+
| -------- | ---- | -------- | ---- |
|
|
92
|
+
| `bash` | 💻 | `read` | 📖 |
|
|
93
|
+
| `write` | 📝 | `edit` | ✏️ |
|
|
94
|
+
| `grep` | 🔎 | `search` | 🔍 |
|
|
95
|
+
| `find` | 🗂️ | `ls` | 📁 |
|
|
96
|
+
| `list` | 📋 | `web` | 🌐 |
|
|
97
|
+
| `fetch` | 📡 | `delete` | 🗑️ |
|
|
98
|
+
| `remove` | ❌ | `todo` | ✅ |
|
|
99
|
+
| `test` | 🧪 | other | 🔧 |
|
|
100
|
+
|
|
101
|
+
### 2.2 Skill block
|
|
102
|
+
|
|
103
|
+
A `read` of a `SKILL.md` file is rendered as:
|
|
104
|
+
|
|
105
|
+
```markdown
|
|
106
|
+
## 🧩 Skill
|
|
107
|
+
|
|
108
|
+
`playwright-cli`
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
- skill name is the parent directory;
|
|
112
|
+
- `path` and `file_path` are both supported;
|
|
113
|
+
- Unix and Windows separators are supported;
|
|
114
|
+
- the `SKILL.md` content is never forwarded;
|
|
115
|
+
- the generic `📖 read` line and its result are suppressed;
|
|
116
|
+
- each read produces one skill bubble; no de-duplication;
|
|
117
|
+
- QQ does not support `/skill:`; only model-initiated reads are detected.
|
|
118
|
+
|
|
119
|
+
### 2.3 Bubble boundaries
|
|
120
|
+
|
|
121
|
+
- Thinking, tools, and text are separate blocks.
|
|
122
|
+
- A run may produce many bubbles, but a tool call and result are always together.
|
|
123
|
+
- `MAX_BUBBLE_CHARS = 12_000` triggers a safe split at a block boundary or line start.
|
|
124
|
+
- Do not split inside an open code fence or while a resume checkpoint/tool is active.
|
|
125
|
+
- Parallel tools are shown one at a time in start order; results are correlated by `toolCallId`.
|
|
126
|
+
- Text and thinking that arrive while tools are pending are deferred so they cannot appear between a tool call and its result.
|
|
127
|
+
|
|
128
|
+
## 3. Status, language, and battery
|
|
129
|
+
|
|
130
|
+
QQ `/status` and terminal `/qq-status` share one formatter.
|
|
131
|
+
|
|
132
|
+
Current fields:
|
|
133
|
+
|
|
134
|
+
| Field | Content |
|
|
135
|
+
| ---------- | ------------------------------------------------------------- |
|
|
136
|
+
| title | `🖥️ pi-qq status` / `pi-qq 状态` |
|
|
137
|
+
| login | QR login and masked AppID, or `not logged in` |
|
|
138
|
+
| connection | `connected`, `reconnecting`, `stopped`, `starting`, `blocked` |
|
|
139
|
+
| agent | `running (QQ)`, `running (local)`, or `completed` |
|
|
140
|
+
| model | current model name |
|
|
141
|
+
| context | tokens / window / percent |
|
|
142
|
+
| QQ user | masked bound openid |
|
|
143
|
+
| battery | percent and charging/discharging/AC; omitted when no battery |
|
|
144
|
+
| settings | `~/.pi/agent/pi-qq.json` |
|
|
145
|
+
|
|
146
|
+
Agent state uses `ctx.isIdle()` as the global signal and `runFeedback.isQQRunActive()` to distinguish a QQ-triggered run from a local run.
|
|
147
|
+
|
|
148
|
+
Battery support:
|
|
149
|
+
|
|
150
|
+
- Linux: `/sys/class/power_supply/BAT*`;
|
|
151
|
+
- macOS: `pmset -g batt`;
|
|
152
|
+
- Windows: PowerShell `Get-CimInstance Win32_Battery`;
|
|
153
|
+
- 30-second cache;
|
|
154
|
+
- failures are silent and hide the battery line;
|
|
155
|
+
- no new npm dependency.
|
|
156
|
+
|
|
157
|
+
Language:
|
|
158
|
+
|
|
159
|
+
- new `language` setting: `"zh-cn"` or `"en-us"`;
|
|
160
|
+
- default is `"zh-cn"`;
|
|
161
|
+
- user-facing command replies, status text, errors, stream placeholders, and pi-qq log messages are localized;
|
|
162
|
+
- logs keep stable fields and add `msgKey` for language-independent filtering;
|
|
163
|
+
- SDK-originated errors and third-party log text remain unmodified;
|
|
164
|
+
- invalid values fall back to the default and produce a warning.
|
|
165
|
+
|
|
166
|
+
`QQ user` replaces the old `Bound user` label and masks the openid.
|
|
167
|
+
|
|
168
|
+
## 4. Tool start visibility
|
|
169
|
+
|
|
170
|
+
The investigation found that tool start information is delayed by the stream batching layer, not by the tool itself:
|
|
171
|
+
|
|
172
|
+
- `AppendStream` uses a 500ms throttle with a 300ms floor;
|
|
173
|
+
- a short tool call and its result can land in the same buffer and appear together;
|
|
174
|
+
- a long tool normally sends its start frame after about 500ms;
|
|
175
|
+
- parallel tools are serialized by `RunFeedback.activeTool`, so a later tool may wait for the current tool to finish.
|
|
176
|
+
|
|
177
|
+
The proposed `flushAfter` behavior was not implemented in v4. The block-type change still improves visibility because bash parameters are no longer a single inline-code line that QQ may collapse.
|
|
178
|
+
|
|
179
|
+
Version 1.3.6 added debug timing logs:
|
|
180
|
+
|
|
181
|
+
- tool enqueue / append start / append done;
|
|
182
|
+
- stream buffer, flush timer, and flush result;
|
|
183
|
+
- event-loop `meanMs`, `maxMs`, `p99Ms`, and later `driftMs`.
|
|
184
|
+
|
|
185
|
+
## 5. Long-running tools
|
|
186
|
+
|
|
187
|
+
### 5.1 Observed failure chain
|
|
188
|
+
|
|
189
|
+
A long tool can leave QQ silent because:
|
|
190
|
+
|
|
191
|
+
1. the run has no new assistant event while the tool runs;
|
|
192
|
+
2. the only tool frame is the start bubble;
|
|
193
|
+
3. a long gap makes the next stream frame likely to hit `msg_id` expiry or passive-reply limits;
|
|
194
|
+
4. `BubbleWriter` resumes with the same expired `msg_id` / `stream_msg_id`;
|
|
195
|
+
5. after resume attempts are exhausted, `killStream()` makes later tool output disappear;
|
|
196
|
+
6. `onToolEnd()` early-returns when the writer is dead, leaving `activeTool` and deferred text stuck;
|
|
197
|
+
7. only the final assistant text may fall back to a normal message, and that fallback becomes proactive after 5 minutes.
|
|
198
|
+
|
|
199
|
+
Additional contributing factors:
|
|
200
|
+
|
|
201
|
+
- each thinking/tool bubble is a new stream reply, but `ReplyBudget` does not count stream bubbles against the 4-reply limit;
|
|
202
|
+
- `/stop` waits for `waitForEnd()` before replying, which can hold the SDK concurrency guard;
|
|
203
|
+
- no `tool_execution_update` progress is forwarded;
|
|
204
|
+
- new QQ messages are queued as `steer` until the tool batch finishes.
|
|
205
|
+
|
|
206
|
+
### 5.2 What shipped
|
|
207
|
+
|
|
208
|
+
- debug diagnostics only; no behavior fix;
|
|
209
|
+
- QQ `/last` as the manual recovery path:
|
|
210
|
+
- while running: `RunFeedback.repushCurrent()` rebinds to the new `/last` message and pushes current text;
|
|
211
|
+
- when idle: `sendStreamReply()` pushes the latest completed assistant text.
|
|
212
|
+
- diagnostics added in 1.3.6 and the follow-up debug pass:
|
|
213
|
+
- tool `durationMs`, `updateCount`, `updateSpanMs`, first partial output;
|
|
214
|
+
- run target selection, tool queued/started/finished/ignored, assistant final decision, run cleanup;
|
|
215
|
+
- writer `dead`, `hasPendingResume`, `resumeAttempts`, `lastFrameAgeMs`;
|
|
216
|
+
- stream frame `httpStatus`, `bizCode`, `path`, `msgSeq`, `streamMsgId`, `bufferLength`;
|
|
217
|
+
- `/stop` wait duration;
|
|
218
|
+
- event-loop drift.
|
|
219
|
+
|
|
220
|
+
### 5.3 Known protocol risks
|
|
221
|
+
|
|
222
|
+
Not fixed in v4:
|
|
223
|
+
|
|
224
|
+
- stream bubble quota is not accounted;
|
|
225
|
+
- `DONE` frames currently have empty `content_raw`;
|
|
226
|
+
- stream requests send both `event_id` and `msg_id`, although the protocol says one of them;
|
|
227
|
+
- stream resume reuses expired identifiers;
|
|
228
|
+
- no pending-output queue for expired passive windows;
|
|
229
|
+
- no final ordinary-text fallback after a successful stream;
|
|
230
|
+
- SDK heartbeat ACK timeout is not implemented;
|
|
231
|
+
- session persistence is not enabled.
|
|
232
|
+
|
|
233
|
+
## 6. QQ background and offline delivery
|
|
234
|
+
|
|
235
|
+
The reported case was: iPhone QQ stays in the background for a long time, pi keeps running, and after reopening QQ no bot output from the offline period is visible. New inbound messages still reach pi, and the bot can reply to them.
|
|
236
|
+
|
|
237
|
+
The likely explanation is client-side/offline delivery: QQ does not replay the streamed bot content that was produced while the phone was offline. This was not fully confirmed because no incident log was available.
|
|
238
|
+
|
|
239
|
+
What v4 shipped:
|
|
240
|
+
|
|
241
|
+
- `/last` as a manual recovery path;
|
|
242
|
+
- status/diagnostic visibility for login, connection, agent, model, context, and budget.
|
|
243
|
+
|
|
244
|
+
What v4 did not ship:
|
|
245
|
+
|
|
246
|
+
- 60-minute passive-window correction (the code still uses 5 minutes);
|
|
247
|
+
- persistent final text after streaming;
|
|
248
|
+
- offline summary on the next inbound message;
|
|
249
|
+
- SDK heartbeat ACK timeout;
|
|
250
|
+
- session persistence;
|
|
251
|
+
- automatic rebind of an active run to a new inbound message.
|
|
252
|
+
|
|
253
|
+
## 7. Diagnostics
|
|
254
|
+
|
|
255
|
+
Terminal commands:
|
|
256
|
+
|
|
257
|
+
- `/qq-test-budget` — passive budget and stream bubble counters;
|
|
258
|
+
- `/qq-test-md [text]` — Markdown rendering test;
|
|
259
|
+
- `/qq-test-stream` — stream timeline and resume test.
|
|
260
|
+
|
|
261
|
+
Debug logging:
|
|
262
|
+
|
|
263
|
+
- enable `logLevel: "debug"` in `~/.pi/agent/pi-qq.json`;
|
|
264
|
+
- logs are written to `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;
|
|
265
|
+
- `PI_QQ_LOG_DIR` can override the directory;
|
|
266
|
+
- `info` records metadata; `debug` records full events, attachments, prompts, and tool arguments/results.
|
|
267
|
+
|
|
268
|
+
## 8. Modules and boundaries
|
|
269
|
+
|
|
270
|
+
<!-- prettier-ignore -->
|
|
271
|
+
| Module | Responsibility |
|
|
272
|
+
| ------ | -------------- |
|
|
273
|
+
| `index.ts` | Extension wiring, pi events, login/session commands, status collection |
|
|
274
|
+
| `src/qq/` | QQ lifecycle, QR login, inbound routing, replies, diagnostics, status formatter |
|
|
275
|
+
| `src/relay/` | Thinking/tool/text relay, bubble layout, stream sessions, tool result formatting |
|
|
276
|
+
| `src/quota/` | Passive reply budget and diagnostics |
|
|
277
|
+
| `src/attachments/` | File download, storage, pending files, voice transcript |
|
|
278
|
+
| `src/infra/` | Settings, i18n, logging, power status, display formatting |
|
|
279
|
+
|
|
280
|
+
Boundary rules:
|
|
281
|
+
|
|
282
|
+
- formatting is pure and lives in `stream-block-format.ts`;
|
|
283
|
+
- relay orchestration lives in `run-stream-relay.ts` / `bubble-writer.ts`;
|
|
284
|
+
- stream frames and retries live in `stream-session.ts`;
|
|
285
|
+
- inbound QQ parsing and command routing live under `src/qq/`;
|
|
286
|
+
- all configuration goes through `settings.ts`;
|
|
287
|
+
- modules receive dependencies from the entrypoint and remain independently testable.
|
|
288
|
+
|
|
289
|
+
Images use the same save/pending path as files; the earlier image-specific pipeline and `imageMaxSize` were removed before v4.
|
|
290
|
+
|
|
291
|
+
## 9. Verification
|
|
292
|
+
|
|
293
|
+
- Unit tests: **172 passed** across 18 test files.
|
|
294
|
+
- TypeScript, ESLint, and Prettier checks pass.
|
|
295
|
+
- Real QQ block-type verification on 2026-11-04:
|
|
296
|
+
- test directory: `/home/chen/project/pi-qq-test`;
|
|
297
|
+
- files: `hello.py`, `Hello.java`, `hello.rs`, `hello.ts`;
|
|
298
|
+
- log: `.pi/pi-qq/logs/pi-qq-2026-11-04.log`;
|
|
299
|
+
- observed `## 💻 bash` with a bash block, `## 📖 read` with rust/typescript result blocks, `## 📝 write` with an inline path;
|
|
300
|
+
- event-loop `driftMs` was 0–1ms and `maxMs` about 101ms.
|
|
301
|
+
- `/qq-test-stream` was not separately executed during this acceptance.
|
|
302
|
+
- A full manual pass of `/status` and long-running/offline scenarios is still recommended.
|
|
303
|
+
|
|
304
|
+
## 10. Risks and limitations
|
|
305
|
+
|
|
306
|
+
- Long tasks can exhaust the 4 passive replies because stream bubbles are not counted.
|
|
307
|
+
- A 5-minute-old message falls back to proactive delivery; users may disable active messages.
|
|
308
|
+
- Stream resume does not recover an expired `msg_id` / `stream_msg_id`.
|
|
309
|
+
- Long tools have no progress heartbeat; only `typing` is sent.
|
|
310
|
+
- Tool start may be delayed by the 500ms throttle.
|
|
311
|
+
- QQ Markdown support for language-specific highlighting varies by client.
|
|
312
|
+
- A 12k split is stateful; extreme single-line or unclosed-fence content may still hit platform behavior.
|
|
313
|
+
- C2C private chat only; credentials stay in process memory.
|
|
314
|
+
- Debug logs may contain prompts, tool arguments, and tool results.
|
|
315
|
+
|
|
316
|
+
## 11. Open items
|
|
317
|
+
|
|
318
|
+
- [doc/todo.md](../todo.md) item 1: long-running bash argument/tool-start visibility.
|
|
319
|
+
- [doc/todo.md](../todo.md) item 2: long-running tool leading to missing QQ output.
|
|
320
|
+
- Fix stream quota accounting before adding more per-block bubbles.
|
|
321
|
+
- Decide how to handle expired passive windows and pending output.
|
|
322
|
+
- Validate `DONE` content and the `event_id` / `msg_id` usage against the QQ API.
|
|
323
|
+
- Add a progress heartbeat or forward `tool_execution_update`.
|
|
324
|
+
- Add SDK heartbeat ACK timeout and consider session persistence.
|
|
325
|
+
- Decide whether `/status` and `/last` need further real-client acceptance.
|
|
326
|
+
|
|
327
|
+
Until the live logs confirm the failure mode, the investigation and diagnostics remain the source of truth; no speculative relay rewrite is included in v4.
|
package/doc/todo.md
CHANGED
|
@@ -74,6 +74,111 @@
|
|
|
74
74
|
|
|
75
75
|
- 收集长期使用日志后,确定是事件循环、队列、网络还是 QQ 渲染问题。
|
|
76
76
|
- 如果是队列/缓冲问题,考虑给工具启动行增加 `flushAfter`。
|
|
77
|
-
-
|
|
77
|
+
- 长命令参数已改为 bash fenced code block;如果仍显示异常,检查 QQ 对代码块的渲染并考虑缩短命令摘要。
|
|
78
78
|
- 如果是 e2e CPU 导致的事件循环饥饿,需要评估 TUI/tool output 的同步开销,或把 relay 移出主进程。
|
|
79
|
-
-
|
|
79
|
+
- 修复后补测试,更新 `doc/todo.md` / `CHANGELOG.md`,再发布版本。
|
|
80
|
+
|
|
81
|
+
## 2. 长耗时命令导致 QQ 侧无输出/失去响应
|
|
82
|
+
|
|
83
|
+
> 状态:TODO,等待长期使用日志
|
|
84
|
+
> 记录日期:2026-11-04
|
|
85
|
+
> 相关版本:pi-qq 1.4.0
|
|
86
|
+
> 详细调研:`doc/archive/delivery-v4.md`
|
|
87
|
+
|
|
88
|
+
### 现象
|
|
89
|
+
|
|
90
|
+
QQ 侧执行一个运行数分钟到数十分钟的 `bash` 命令后,可能只有最初的工具气泡,之后:
|
|
91
|
+
|
|
92
|
+
- 命令结束没有工具结果;
|
|
93
|
+
- 没有最终回答;
|
|
94
|
+
- 长命令期间发送普通消息,直到命令结束才有反应;
|
|
95
|
+
- 看起来像机器人“失去响应”,但电脑上的 pi TUI 仍在运行。
|
|
96
|
+
|
|
97
|
+
### 已知事实
|
|
98
|
+
|
|
99
|
+
- pi 的 bash 工具使用异步 `spawn`,长时间运行的普通命令本身不会阻塞 Node 事件循环。
|
|
100
|
+
- 长工具期间 pi-qq 不订阅 `tool_execution_update`,所以没有进度帧;只有 50 秒一次的 `typing`。
|
|
101
|
+
- 每个思考/工具气泡都会新建一条流式回复,但 `ReplyBudget` 只统计普通文本,没有把流式气泡计入 4 次被动回复上限。
|
|
102
|
+
- 长静默后的结果帧如果因 `msg_id` 过期或被动次数超限失败,`BubbleWriter` 会沿用同一个过期 `msg_id` / `stream_msg_id` resume,最终 `killStream()`;之后 `onToolStart()` / `onToolEnd()` 直接早退,后续工具输出丢失。
|
|
103
|
+
- 运行中收到的普通消息以 `steer` 进入当前 run,要等当前工具批次结束才处理。
|
|
104
|
+
- `/stop` 目前要等 `waitForEnd()` 才回复;如果工具不响应 abort 或流式请求在重试,会占住 SDK 的并发锁。
|
|
105
|
+
|
|
106
|
+
### 临时恢复手段
|
|
107
|
+
|
|
108
|
+
QQ 侧的 `/last` 已可用于手动恢复:
|
|
109
|
+
|
|
110
|
+
- **run 运行中**:`/last` 调用 `RunFeedback.repushCurrent()`,把当前输出重推到新消息的 `msg_id` 上,并让后续 delta 继续写入新气泡;
|
|
111
|
+
- **run 已结束**:`/last` 用流式重新推送最近一次完成的 assistant 文本。
|
|
112
|
+
|
|
113
|
+
因此本次不实现行为修复;`/last` 作为用户可用的手动恢复路径。
|
|
114
|
+
|
|
115
|
+
### 本次决策
|
|
116
|
+
|
|
117
|
+
- 暂不实施 v4 归档中的错误分类、预算、心跳、自动重绑等行为修改。
|
|
118
|
+
- 只追加可验证的 debug 日志,等待长期使用日志后再决定修复范围。
|
|
119
|
+
- 新增诊断日志在 `logLevel: "debug"` 时写入;`stream error` / `stream unavailable` 原本就是 `warn`,保留为错误记录,不改变行为。
|
|
120
|
+
|
|
121
|
+
### 已追加的诊断日志
|
|
122
|
+
|
|
123
|
+
- `scope: "tool"`:
|
|
124
|
+
- `start` / `end` 增加 `parentToolCallId`、`durationMs`;
|
|
125
|
+
- `end` 增加 `updateCount`、`updateSpanMs`、`firstPartial`;
|
|
126
|
+
- `update` 记录首次部分输出,之后每 50 次记录一次进度。
|
|
127
|
+
- `scope: "run"`:
|
|
128
|
+
- `run started`:`phase: "no qq target"`、`source: pending/recovery`、`targetAgeMs`;
|
|
129
|
+
- `tool start` / `tool end`:`phase: queued / output started / result recorded / output finished / ignored: stream dead / ignored: no active run`;
|
|
130
|
+
- `stream takeover decision`:`textLength`、`deltaLength`、`hadPendingTools`、`flushOk`、`hasPushed`、`streamTookOver`、`deferredTextLen`;
|
|
131
|
+
- `run ended`:`hasPendingTools`、`hasPushed`、`lastCompletedTextLength`;
|
|
132
|
+
- `stream timing`:`phase: last repush / last repush ignored`;
|
|
133
|
+
- 工具、最终消息和 cleanup 相关日志都带 `diagnostics`:`activeTool`、`tools`、`deferredTextLen`、`writer stats`、`budget`。
|
|
134
|
+
- `scope: "stream"`:
|
|
135
|
+
- `stream timing` 的 `stats` 包含 `dead`、`hasStream`、`hasPendingResume`、`resumeAttempts`、`bubbleChars`、`hasPushed`、`lastKind`、`toolOpen`、`lastFrameAgeMs`;
|
|
136
|
+
- `stream open` 记录是否 resume、checkpoint 的 `index` / `hasStreamMsgId` / `bufferLength`、`budget`;
|
|
137
|
+
- `stream error` 增加 `phase: "frame failed"`,记录 `httpStatus`、`bizCode`、`path`、`msgSeq`、`streamMsgId`、`bufferLength`;
|
|
138
|
+
- `stream unavailable` 记录 writer `stats` 和 `budget`;
|
|
139
|
+
- `sendStreamReply()`(idle `/last`)记录 `phase: "last reply stream"`、`msgId`、`textLength`。
|
|
140
|
+
- `AppendStream` 的 `flush start/done` 增加 `msgSeq` 和 `streamMsgId`(存在时)。
|
|
141
|
+
- `scope: "inbound"`:`/stop` 记录 `wait start` / `wait done` 及 `waitedMs`。
|
|
142
|
+
- `scope: "event-loop"`:增加 `driftMs`,用于发现 timer 被事件循环延迟。
|
|
143
|
+
|
|
144
|
+
### 下次日志分析步骤
|
|
145
|
+
|
|
146
|
+
1. 找到长命令的 `scope: "tool"` `start` / `end`:
|
|
147
|
+
- `durationMs` 是否与用户感知一致;
|
|
148
|
+
- `updateCount` 是否为 0,判断长命令期间是否完全没有部分输出。
|
|
149
|
+
2. 看 `scope: "stream"` 的 `stream timing`:
|
|
150
|
+
- `tool queued` 时间;
|
|
151
|
+
- `append start` 的 `waitedMs` / `lastFrameAgeMs`;
|
|
152
|
+
- `append done` 的 `totalMs`;
|
|
153
|
+
- 工具结束到结果帧之间隔了多久。
|
|
154
|
+
3. 看 `stream error` 的 `phase: "frame failed"`:
|
|
155
|
+
- `httpStatus` / `bizCode` 是否为 `304103`、`40034005`、`40034128`、`40034024`、`429`、`50002`;
|
|
156
|
+
- `streamMsgId` 是否存在,`bufferLength` 是否持续增长。
|
|
157
|
+
4. 看 `stream unavailable` 之后 `scope: "run"` 的:
|
|
158
|
+
- `tool start/end` 是否出现 `ignored: stream dead`;
|
|
159
|
+
- `stream takeover decision` 的 `flushOk` / `hasPushed` / `hadPendingTools`;
|
|
160
|
+
- `run ended` 的 `hasPendingTools`。
|
|
161
|
+
5. 如果用户使用了 `/last`,看 `phase: "last repush"` 或 `"last repush ignored"`,确认是否恢复、恢复后是否仍有输出。
|
|
162
|
+
6. 看 `scope: "event-loop"` 的 `maxMs` / `p99Ms` / `driftMs`:
|
|
163
|
+
- 如果达到数秒甚至更高,优先排查 CPU 饥饿;
|
|
164
|
+
- 如果正常,则更可能是 QQ 被动窗口/配额或 relay 状态问题。
|
|
165
|
+
7. 对照 `/qq-test-budget` 的 `remaining`、`streamBubbles`、`streamBubblesTotal`,确认是否早已超过 4 次。
|
|
166
|
+
|
|
167
|
+
### 需要提供的信息
|
|
168
|
+
|
|
169
|
+
复现后请提供:
|
|
170
|
+
|
|
171
|
+
- `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;
|
|
172
|
+
- 长命令内容、开始时间和结束时间;
|
|
173
|
+
- QQ 上最后一条可见消息及时间;
|
|
174
|
+
- 期间是否发送过 `/status`、`/stop`、普通文本、`/last`;
|
|
175
|
+
- `/qq-test-budget` 和 `/qq-status` 输出;
|
|
176
|
+
- 手机 QQ 是否在前台,是否允许主动消息。
|
|
177
|
+
|
|
178
|
+
### 下一步
|
|
179
|
+
|
|
180
|
+
- 如果日志确认 `msg_id` 过期/被动次数超限:按 `doc/archive/delivery-v4.md` 的“Long-running tools”建议实现错误分类和预算修复。
|
|
181
|
+
- 如果日志显示流一直存活但没有新帧:优先实现长工具心跳和 `tool_execution_update` 转发。
|
|
182
|
+
- 如果事件循环 `driftMs` / `p99Ms` 很高:排查 e2e CPU、TUI 渲染和同步工具代码。
|
|
183
|
+
- 如果 `/stop` 的 `wait done` 缺失或 `waitedMs` 很大:实现非阻塞 `/stop`。
|
|
184
|
+
- 如果 `/last` 已能稳定恢复,保持为手动兜底,不急于自动重绑。
|
package/index.ts
CHANGED
|
@@ -49,6 +49,20 @@ const runFeedback = new RunFeedback({
|
|
|
49
49
|
const eventLoopDelay = monitorEventLoopDelay({ resolution: 100 });
|
|
50
50
|
let eventLoopTimer: ReturnType<typeof setInterval> | undefined;
|
|
51
51
|
|
|
52
|
+
interface ToolUpdateStats {
|
|
53
|
+
count: number;
|
|
54
|
+
firstAt: number;
|
|
55
|
+
lastAt: number;
|
|
56
|
+
firstPartial: string;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const toolUpdateStats = new Map<string, ToolUpdateStats>();
|
|
60
|
+
const TOOL_UPDATE_LOG_EVERY = 50;
|
|
61
|
+
|
|
62
|
+
function clearToolUpdateStats(): void {
|
|
63
|
+
toolUpdateStats.clear();
|
|
64
|
+
}
|
|
65
|
+
|
|
52
66
|
function roundMs(value: number): number {
|
|
53
67
|
return Math.round((value / 1e6) * 10) / 10;
|
|
54
68
|
}
|
|
@@ -58,11 +72,16 @@ function startEventLoopMonitor(): void {
|
|
|
58
72
|
eventLoopDelay.disable();
|
|
59
73
|
eventLoopDelay.reset();
|
|
60
74
|
eventLoopDelay.enable();
|
|
75
|
+
let lastTickAt = Date.now();
|
|
61
76
|
eventLoopTimer = setInterval(() => {
|
|
77
|
+
const now = Date.now();
|
|
78
|
+
const driftMs = now - lastTickAt - 5_000;
|
|
79
|
+
lastTickAt = now;
|
|
62
80
|
log.debug("event-loop", "event loop delay", {
|
|
63
81
|
meanMs: roundMs(eventLoopDelay.mean),
|
|
64
82
|
maxMs: roundMs(eventLoopDelay.max),
|
|
65
83
|
p99Ms: roundMs(eventLoopDelay.percentile(99)),
|
|
84
|
+
driftMs,
|
|
66
85
|
});
|
|
67
86
|
eventLoopDelay.reset();
|
|
68
87
|
}, 5_000);
|
|
@@ -121,6 +140,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
121
140
|
stateDetail = undefined;
|
|
122
141
|
sessionCtx = undefined;
|
|
123
142
|
runFeedback.dispose();
|
|
143
|
+
clearToolUpdateStats();
|
|
124
144
|
stopEventLoopMonitor();
|
|
125
145
|
};
|
|
126
146
|
|
|
@@ -208,22 +228,66 @@ export default function (pi: ExtensionAPI) {
|
|
|
208
228
|
});
|
|
209
229
|
|
|
210
230
|
pi.on("tool_execution_start", (event) => {
|
|
231
|
+
toolUpdateStats.delete(event.toolCallId);
|
|
211
232
|
if (isLogEnabled("debug")) {
|
|
212
233
|
log.debug("tool", "start", {
|
|
213
234
|
toolName: event.toolName,
|
|
214
235
|
toolCallId: event.toolCallId,
|
|
236
|
+
parentToolCallId: event.parentToolCallId ?? null,
|
|
237
|
+
at: Date.now(),
|
|
215
238
|
args: previewForLog(event.args),
|
|
216
239
|
});
|
|
217
240
|
}
|
|
218
241
|
void runFeedback.onToolStart(event.toolName, event.args, event.toolCallId);
|
|
219
242
|
});
|
|
220
243
|
|
|
244
|
+
pi.on("tool_execution_update", (event) => {
|
|
245
|
+
if (!isLogEnabled("debug")) return;
|
|
246
|
+
const now = Date.now();
|
|
247
|
+
const existing = toolUpdateStats.get(event.toolCallId);
|
|
248
|
+
if (!existing) {
|
|
249
|
+
const first: ToolUpdateStats = {
|
|
250
|
+
count: 1,
|
|
251
|
+
firstAt: now,
|
|
252
|
+
lastAt: now,
|
|
253
|
+
firstPartial: previewForLog(event.partialResult, 300),
|
|
254
|
+
};
|
|
255
|
+
toolUpdateStats.set(event.toolCallId, first);
|
|
256
|
+
log.debug("tool", "update", {
|
|
257
|
+
phase: "first",
|
|
258
|
+
toolName: event.toolName,
|
|
259
|
+
toolCallId: event.toolCallId,
|
|
260
|
+
count: 1,
|
|
261
|
+
partial: first.firstPartial,
|
|
262
|
+
});
|
|
263
|
+
return;
|
|
264
|
+
}
|
|
265
|
+
existing.count += 1;
|
|
266
|
+
existing.lastAt = now;
|
|
267
|
+
if (existing.count % TOOL_UPDATE_LOG_EVERY === 0) {
|
|
268
|
+
log.debug("tool", "update", {
|
|
269
|
+
phase: "progress",
|
|
270
|
+
toolName: event.toolName,
|
|
271
|
+
toolCallId: event.toolCallId,
|
|
272
|
+
count: existing.count,
|
|
273
|
+
spanMs: existing.lastAt - existing.firstAt,
|
|
274
|
+
});
|
|
275
|
+
}
|
|
276
|
+
});
|
|
277
|
+
|
|
221
278
|
pi.on("tool_execution_end", (event) => {
|
|
279
|
+
const updates = toolUpdateStats.get(event.toolCallId);
|
|
280
|
+
toolUpdateStats.delete(event.toolCallId);
|
|
222
281
|
if (isLogEnabled("debug")) {
|
|
223
282
|
log.debug("tool", "end", {
|
|
224
283
|
toolName: event.toolName,
|
|
225
284
|
toolCallId: event.toolCallId,
|
|
285
|
+
parentToolCallId: event.parentToolCallId ?? null,
|
|
226
286
|
isError: event.isError,
|
|
287
|
+
durationMs: event.durationMs ?? null,
|
|
288
|
+
updateCount: updates?.count ?? 0,
|
|
289
|
+
updateSpanMs: updates ? updates.lastAt - updates.firstAt : null,
|
|
290
|
+
firstPartial: updates?.firstPartial ?? null,
|
|
227
291
|
result: previewForLog(event.result),
|
|
228
292
|
});
|
|
229
293
|
}
|
package/package.json
CHANGED
|
@@ -44,8 +44,7 @@ export function uploadIndexPath(uploadDir: string): string {
|
|
|
44
44
|
export function sanitizeFilename(filename: string | undefined, fallback: string): string {
|
|
45
45
|
const raw = basename((filename ?? "").trim());
|
|
46
46
|
const cleaned = raw
|
|
47
|
-
|
|
48
|
-
.replace(/[\u0000-\u001f\u007f<>:"|?*]/g, "_")
|
|
47
|
+
.replace(/[\p{Cc}<>:"|?*]/gu, "_")
|
|
49
48
|
.replace(/^[.\s]+|[.\s]+$/g, "")
|
|
50
49
|
.trim();
|
|
51
50
|
if (!cleaned || cleaned === "." || cleaned === "..") return fallback;
|
package/src/infra/file-logger.ts
CHANGED
|
@@ -35,7 +35,6 @@ export function isLogEnabled(level: Exclude<LogLevel, "silent">): boolean {
|
|
|
35
35
|
return isLevelEnabled(activeLevel, level);
|
|
36
36
|
}
|
|
37
37
|
|
|
38
|
-
/** Resolve once every queued log record has been written (or dropped). */
|
|
39
38
|
export async function flushLogs(): Promise<void> {
|
|
40
39
|
await writeQueue;
|
|
41
40
|
}
|
|
@@ -68,9 +68,7 @@ export function readLinuxBattery(root = "/sys/class/power_supply"): PowerStatus
|
|
|
68
68
|
const rawStatus = readFileSync(join(dir, "status"), "utf8").trim().toLowerCase();
|
|
69
69
|
const state = rawStatus === "charging" ? "charging" : rawStatus === "discharging" ? "discharging" : "ac";
|
|
70
70
|
return { percent, state };
|
|
71
|
-
} catch {
|
|
72
|
-
// Try the next battery.
|
|
73
|
-
}
|
|
71
|
+
} catch {}
|
|
74
72
|
}
|
|
75
73
|
return undefined;
|
|
76
74
|
}
|
package/src/infra/settings.ts
CHANGED
|
@@ -37,10 +37,6 @@ function isPositiveSize(value: unknown): value is number {
|
|
|
37
37
|
return typeof value === "number" && Number.isFinite(value) && value > 0;
|
|
38
38
|
}
|
|
39
39
|
|
|
40
|
-
/**
|
|
41
|
-
* Validate the on-disk shape before it reaches business code. Invalid fields
|
|
42
|
-
* are dropped individually so one typo does not discard the whole config.
|
|
43
|
-
*/
|
|
44
40
|
export function parseConfig(raw: unknown): ReadConfigResult {
|
|
45
41
|
if (!isRecord(raw)) {
|
|
46
42
|
return {
|