@chen_hu_hu/pi-qq 1.5.1 → 1.6.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 +33 -3
- package/README-zh.md +61 -29
- package/README.md +61 -29
- package/doc/archive/{delivery-v1.md → delivery.1.0.0.md} +1 -1
- package/doc/archive/{delivery-v2.md → delivery.1.2.0.md} +1 -1
- package/doc/archive/{delivery-v3.md → delivery.1.3.0.md} +1 -1
- package/doc/archive/{delivery-v4.md → delivery.1.4.0.md} +1 -1
- package/doc/archive/{delivery-v5.md → delivery.1.5.0.md} +2 -2
- package/doc/archive/delivery.1.6.0.md +263 -0
- package/doc/archive/delivery.1.6.1.md +150 -0
- package/doc/todo.md +66 -38
- package/index.ts +50 -16
- package/package.json +1 -1
- package/src/infra/i18n.ts +6 -2
- package/src/infra/reply-type.ts +9 -0
- package/src/infra/settings.ts +7 -6
- package/src/qq/inbound-command.ts +6 -0
- package/src/qq/qq-message-handler.ts +4 -0
- package/src/qq/status-report.ts +4 -0
- package/src/relay/bubble-writer.ts +47 -32
- package/src/relay/reply-policy.ts +37 -0
- package/src/relay/run-stream-relay.ts +89 -16
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
# pi-qq delivery-v6
|
|
2
|
+
|
|
3
|
+
> **Delivery record.** v6 adds the `replyType` setting to control how much of an agent run is pushed to QQ, and fixes the 12k bubble split that almost never fired. See [README](../../README.md) for current user-facing behavior.
|
|
4
|
+
> Version: 1.6.0
|
|
5
|
+
> Date: 2026-11-09
|
|
6
|
+
> Previous: [delivery.1.0.0.md](./delivery.1.0.0.md), [delivery.1.2.0.md](./delivery.1.2.0.md), [delivery.1.3.0.md](./delivery.1.3.0.md), [delivery.1.4.0.md](./delivery.1.4.0.md), [delivery.1.5.0.md](./delivery.1.5.0.md).
|
|
7
|
+
> Open work: [doc/todo.md](../todo.md).
|
|
8
|
+
|
|
9
|
+
## 1. Scope
|
|
10
|
+
|
|
11
|
+
Before v6, pi-qq pushed everything the agent produced into QQ: thinking blocks, tool start lines, tool results, skill blocks, and every assistant message. A 29-minute run produced 184 bubbles (see [doc/todo.md](../todo.md)), so the actual answer was buried in tool noise.
|
|
12
|
+
|
|
13
|
+
v6 gives that choice a name and a setting:
|
|
14
|
+
|
|
15
|
+
- a new `replyType` setting with three modes: `full` (current behaviour), `simple`, `last`;
|
|
16
|
+
- `full` stays the default, so upgrading changes nothing;
|
|
17
|
+
- `/last` during a running task no longer repushes partial output in `last` mode;
|
|
18
|
+
- `/qq-status` shows the effective mode;
|
|
19
|
+
- an unrelated existing defect is fixed: the 12k bubble split almost never fired.
|
|
20
|
+
|
|
21
|
+
In scope:
|
|
22
|
+
|
|
23
|
+
- `replyType` parsing, validation, and defaulting;
|
|
24
|
+
- per-mode relay behaviour in `RunFeedback`;
|
|
25
|
+
- `last` mode delivery at the end of a run, with plain-message fallback;
|
|
26
|
+
- the `/last` command change in `last` mode;
|
|
27
|
+
- the reply type in `/qq-status`;
|
|
28
|
+
- the 12k bubble split fix.
|
|
29
|
+
|
|
30
|
+
Out of scope:
|
|
31
|
+
|
|
32
|
+
- summarising, trimming, or rewriting model output;
|
|
33
|
+
- changing pi's agent behaviour, prompts, or tool set;
|
|
34
|
+
- per-command or per-session mode switching;
|
|
35
|
+
- changing `qq_send_media` behaviour (media files are still delivered in every mode);
|
|
36
|
+
- a "progress hint" while a `last` run is in flight.
|
|
37
|
+
|
|
38
|
+
## 2. Final decisions
|
|
39
|
+
|
|
40
|
+
| # | Question | Decision |
|
|
41
|
+
| --- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
42
|
+
| D1 | Should `last` send a progress hint while the task runs? | No. It contradicts "only the last message"; the typing indicator already covers the wait. A hint would be its own setting, not a mode. |
|
|
43
|
+
| D2 | Should `simple` offer a "merge adjacent assistant messages" switch? | No. One assistant message is one bubble; the boundary already comes from `closeBlock()`. |
|
|
44
|
+
| D3 | Should QQ commands switch the mode at runtime (e.g. `/mode last`)? | No. Two sources of truth would compete with `deliverAs` and the other settings. |
|
|
45
|
+
| D4 | How is Markdown handled for the `last` message? | Keep the existing split: the stream channel sends raw Markdown, the plain-message fallback runs `markdownToPlain()`. |
|
|
46
|
+
| D5 | Should `/qq-status` show the reply type? | Yes. One `💬 Reply type: <mode>` line, so the effective setting is verifiable. |
|
|
47
|
+
| D6 | What should `/last` do during a running task in `last` mode? | Do not repush. Reply with a localized notice (`commands.last.running`) instead: whatever is on screen cannot be the last message. |
|
|
48
|
+
| D7 | When is the setting read? | Per session. `activeSettings` is refreshed on `session_start` and `/qq-login`; the config file is never read on the hot path. |
|
|
49
|
+
| D8 | Should `last` still deliver after `/stop` aborts the run? | Yes. `agent_end` also fires on abort, and a conclusion the agent already reached should not be lost. |
|
|
50
|
+
|
|
51
|
+
## 3. The three modes
|
|
52
|
+
|
|
53
|
+
| Dimension | `full` | `simple` | `last` |
|
|
54
|
+
| -------------------------- | ----------------------------------- | ------------------------- | ---------------------------------- |
|
|
55
|
+
| Thinking blocks | per `thinkingRelay` | no | no |
|
|
56
|
+
| Tool start lines / results | yes | no | no |
|
|
57
|
+
| Assistant text | all, streamed live | all, streamed live | last one only |
|
|
58
|
+
| When the text reaches QQ | while generated | while generated | when the run ends |
|
|
59
|
+
| Bubbles per run | one per block switch (often dozens) | one per assistant message | 1 (or 1 plain message on fallback) |
|
|
60
|
+
| Model error message | immediately, as a plain message | same | same |
|
|
61
|
+
|
|
62
|
+
- `full` is the default and reproduces pi-qq 1.5.x exactly.
|
|
63
|
+
- `simple` streams every assistant message live, one QQ bubble per message. Text produced while a tool is still running is pushed immediately instead of being deferred until the tool batch ends (there is no tool bubble to keep it clear of).
|
|
64
|
+
- `last` sends nothing while the task runs. When the run ends, the last assistant message that has text is delivered as one bubble (stream first, plain message on failure).
|
|
65
|
+
- "Last" means the last assistant message **with text**. A trailing message that only carries a tool call falls back to the previous one with text.
|
|
66
|
+
- A model error is always delivered immediately as a plain message, in every mode, and never occupies the "last message" slot.
|
|
67
|
+
- Tool output is never relayed in `simple` or `last`, but files sent with `qq_send_media` still arrive.
|
|
68
|
+
|
|
69
|
+
Example run:
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
user : 帮我看下 README 里的安装步骤对不对
|
|
73
|
+
|
|
74
|
+
agent : thinking 用户问的是安装步骤,先读 README
|
|
75
|
+
tool read README.md
|
|
76
|
+
message 1 我先读一下 README。
|
|
77
|
+
tool bash grep -n install
|
|
78
|
+
message 2 README 里的安装步骤是 npm i -g pi。
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
| Mode | QQ bubbles |
|
|
82
|
+
| -------- | --------------------------------------------------------------------------------------------------------------- |
|
|
83
|
+
| `full` | ① 💭 thinking ② 📖 read + result ③ 我先读一下 README。 ④ 💻 bash + result ⑤ README 里的安装步骤是 npm i -g pi。 |
|
|
84
|
+
| `simple` | ① 我先读一下 README。 ② README 里的安装步骤是 npm i -g pi。 |
|
|
85
|
+
| `last` | ① README 里的安装步骤是 npm i -g pi。(sent when the run ends) |
|
|
86
|
+
|
|
87
|
+
## 4. Configuration
|
|
88
|
+
|
|
89
|
+
`~/.pi/agent/pi-qq.json`:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"replyType": "full"
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
| Key | Type | Default | Meaning |
|
|
98
|
+
| ----------- | ------------------------------ | -------- | ---------------------------- |
|
|
99
|
+
| `replyType` | `"full" \| "simple" \| "last"` | `"full"` | How much of a run reaches QQ |
|
|
100
|
+
|
|
101
|
+
- An invalid value is ignored and falls back to the default, with a warning at session start: `replyType must be "full", "simple", or "last"`.
|
|
102
|
+
- `thinkingRelay` only applies to `full`; in `simple` and `last` thinking is never relayed.
|
|
103
|
+
- `deliverAs` is unrelated: it controls how QQ messages enter pi, `replyType` controls how pi's output returns to QQ.
|
|
104
|
+
- The default stays `full`, so upgrading changes nothing and there is no migration step.
|
|
105
|
+
|
|
106
|
+
## 5. Implementation
|
|
107
|
+
|
|
108
|
+
### 5.1 Layers
|
|
109
|
+
|
|
110
|
+
| File | Change |
|
|
111
|
+
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
112
|
+
| `src/infra/reply-type.ts` (new) | `ReplyType`, `REPLY_TYPES`, `DEFAULT_REPLY_TYPE = "full"`, `isReplyType()` |
|
|
113
|
+
| `src/infra/settings.ts` | `PiQQSettings.replyType`, validation in `parseConfig()`, default in `getSettings()` |
|
|
114
|
+
| `src/infra/i18n.ts` | `settings.replyType`, `status.replyType`, `commands.last.running` |
|
|
115
|
+
| `src/relay/reply-policy.ts` (new) | `ReplyPolicy` + `policyFor(type)` |
|
|
116
|
+
| `src/relay/run-stream-relay.ts` | Policy lookup per event; `lastText` buffering; end-of-run delivery and fallback; `onFallbackReply` dep |
|
|
117
|
+
| `src/qq/inbound-command.ts` | `/last` replies with a notice in `last` mode while a task is running |
|
|
118
|
+
| `src/qq/qq-message-handler.ts` | `InboundDeps.getReplyType` |
|
|
119
|
+
| `src/qq/status-report.ts` | `💬 Reply type: <mode>` line |
|
|
120
|
+
| `index.ts` | `getReplyType` / `onFallbackReply` wiring, `replyType` in session and bot logs |
|
|
121
|
+
|
|
122
|
+
`src/relay/bubble-writer.ts` is mode-agnostic: the writer only puts text into bubbles, and every mode difference is absorbed by `RunFeedback`.
|
|
123
|
+
|
|
124
|
+
### 5.2 Policy
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
export interface ReplyPolicy {
|
|
128
|
+
relayThinking: boolean;
|
|
129
|
+
relayTools: boolean;
|
|
130
|
+
relayTextLive: boolean;
|
|
131
|
+
deferTextWhileToolsPending: boolean;
|
|
132
|
+
deliverLastAtEnd: boolean;
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
| Mode | relayThinking | relayTools | relayTextLive | deferTextWhileToolsPending | deliverLastAtEnd |
|
|
137
|
+
| -------- | ------------------------- | ---------- | ------------- | -------------------------- | ---------------- |
|
|
138
|
+
| `full` | yes (and `thinkingRelay`) | yes | yes | yes | no |
|
|
139
|
+
| `simple` | no | no | yes | no | no |
|
|
140
|
+
| `last` | no | no | no | no | yes |
|
|
141
|
+
|
|
142
|
+
### 5.3 `last` mode
|
|
143
|
+
|
|
144
|
+
State: `RunState.lastText` holds the latest assistant message that has text.
|
|
145
|
+
|
|
146
|
+
- `onAssistantDelta(snapshot, thinking)`: nothing is pushed; a non-empty snapshot updates `lastText`.
|
|
147
|
+
- `onAssistantFinal(text, isError)`: a non-empty, non-error text becomes `lastText` and the call returns `true`, which suppresses the plain-message fallback in `index.ts` (the message is delivered at the end of the run instead). An error returns `false`, so the error keeps going out immediately through `sendReply`.
|
|
148
|
+
- `onAgentEnd()`: `planLastDelivery()` delivers `lastText`:
|
|
149
|
+
1. if `budget.snapshot().fresh` is false (the inbound message is older than the passive window), skip the stream and use the plain message path directly;
|
|
150
|
+
2. otherwise push the text into the bubble, rotate, flush, and `DONE`;
|
|
151
|
+
3. if the stream fails, fall back to `onFallbackReply(text)`, which reuses `sendReply()` — passive first, proactive when the window expired, chunked at 4500 characters.
|
|
152
|
+
|
|
153
|
+
```text
|
|
154
|
+
QQ message ─▶ agent_start
|
|
155
|
+
├─ thinking / tools / intermediate assistant text ─▶ dropped (latest text buffered)
|
|
156
|
+
├─ message_end(last assistant message) ─▶ lastText = "..."
|
|
157
|
+
└─ agent_end
|
|
158
|
+
├─ budget stale? ──yes──▶ sendReply(plain message)
|
|
159
|
+
└─ no ─▶ writer.pushText(lastText) ─▶ flush
|
|
160
|
+
├─ ok ─▶ DONE
|
|
161
|
+
└─ fail ─▶ onFallbackReply(lastText) ─▶ sendReply(plain message)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### 5.4 Commands
|
|
165
|
+
|
|
166
|
+
| Command | Behaviour |
|
|
167
|
+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
168
|
+
| `/last` (busy) | `full` / `simple`: `repushCurrent()`, the current assistant text is pushed to the new `msg_id`. `last`: a localized notice, no repush. |
|
|
169
|
+
| `/last` (idle) | The last completed reply is re-pushed as a stream, in every mode. |
|
|
170
|
+
| `/stop` | Aborts the run; `agent_end` still fires, so `last` mode still delivers the buffered text. |
|
|
171
|
+
| `/status` | Session, context, and battery; unaffected by the mode. |
|
|
172
|
+
|
|
173
|
+
### 5.5 Debug logs
|
|
174
|
+
|
|
175
|
+
- `session started`, `starting bot`, and `run started` carry `replyType`.
|
|
176
|
+
- `last` mode adds `run / last buffered` (`textLength`, `isError`) and `run / last delivered` (`delivered`, `fallback`).
|
|
177
|
+
- The `last delivered` record must be written **before** the run state is cleared: the log gate only opens while a QQ run is active, so `onAgentEnd()` now nulls `this.run` after the final flush and guards it with `if (this.run === run)`.
|
|
178
|
+
|
|
179
|
+
## 6. The 12k bubble split fix
|
|
180
|
+
|
|
181
|
+
This defect is unrelated to `replyType`; it existed in `full` mode as well.
|
|
182
|
+
|
|
183
|
+
**Symptom**: a single assistant message longer than 12k characters was not split. One measured message of 12590 characters used a single `stream_msg_id` for all 28 frames.
|
|
184
|
+
|
|
185
|
+
**Cause**: the split condition was `(blockBoundary || this.lastChar === "\n")`.
|
|
186
|
+
|
|
187
|
+
- `blockBoundary` is only true on a block switch, so it is always false for a continuous text stream;
|
|
188
|
+
- `this.lastChar === "\n"` requires the **previously pushed chunk** to end with a newline. Chunks arrive at the provider's SSE granularity, which has nothing to do with content, so this is a lottery. The measured message had 14 newlines after the 12k mark (all with the code fence closed) and none of them coincided with a chunk boundary.
|
|
189
|
+
|
|
190
|
+
**Impact**: no error, no lost content, no dead stream — the platform splits on its own when its own limit is hit. The cost is that the split point is chosen by the platform (possibly mid-line) and that a platform-split continuation bubble does not repeat the `## 💭` heading, so the v3 intent ("split at the 12k boundary and repeat the header") was lost.
|
|
191
|
+
|
|
192
|
+
**Fix**: find the split point in the chunk that is being pushed:
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
private splitPoint(text: string, newBubble: boolean): number {
|
|
196
|
+
if (newBubble) return -1;
|
|
197
|
+
if (!this.cur) return -1;
|
|
198
|
+
if (this.pendingResume) return -1;
|
|
199
|
+
if (this.fenceOpen) return -1;
|
|
200
|
+
if (this.toolOpen) return -1;
|
|
201
|
+
if (this.bubbleChars < MAX_BUBBLE_CHARS) return -1;
|
|
202
|
+
return text.indexOf("\n");
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
When a split point exists, the chunk is appended in two parts with a bubble rotation in between: the old bubble ends with the newline, the new bubble starts at a line start, and a thinking block repeats its `## 💭` heading. When the chunk has no newline, nothing is split yet and the next chunk with a newline is used. The overshoot is the distance to the next newline in the stream — normally tens of characters. Pathological single-line content is left to the platform.
|
|
207
|
+
|
|
208
|
+
Unchanged constraints: never split inside an open code fence, never split while a tool block is open (tool header and result stay together), never split while a resume checkpoint is pending.
|
|
209
|
+
|
|
210
|
+
## 7. Verification
|
|
211
|
+
|
|
212
|
+
Automated:
|
|
213
|
+
|
|
214
|
+
- **224 tests passed** across 19 files (22 new: settings 5, relay 13, inbound command 2, status report 2, i18n 1).
|
|
215
|
+
- `npm run typecheck`, `npm run lint`, `npm run format:check`, and `npm pack --dry-run` passed.
|
|
216
|
+
|
|
217
|
+
Real QQ, log `~/project/mine/pi-qq-test/.pi/pi-qq/logs/pi-qq-2026-11-09.log`:
|
|
218
|
+
|
|
219
|
+
| Case | Result |
|
|
220
|
+
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
221
|
+
| `last`, 5 runs | Exactly one stream message per run, each containing only the final assistant text (284 / 899 / 1263 / 1147 / 232 characters) |
|
|
222
|
+
| `last`, long run | Typing indicator kept the chat alive every 50s for a 4.5-minute run |
|
|
223
|
+
| `last`, media tool | `qq_send_media` uploaded and sent the image (passive) even though the tool bubble was suppressed |
|
|
224
|
+
| `last`, log gap | The `last delivered` record was missing because the log gate closed first; fixed, with a regression test |
|
|
225
|
+
| `simple`, 26 runs | 39 frames in 3 bubbles; **0** frames contained a tool or thinking marker |
|
|
226
|
+
| `simple`, live streaming | A 12590-character message was streamed in 28 frames over ~27 seconds |
|
|
227
|
+
| `simple`, one bubble per message | Two assistant messages produced two bubbles |
|
|
228
|
+
| Provider rate limit | 25 runs ended with the model provider's `429` TPM limit; each error was delivered immediately as a plain message, proactive once the passive window had expired |
|
|
229
|
+
| 12k split | The 12590-character message stayed in one bubble (the defect above); fixed in this release |
|
|
230
|
+
|
|
231
|
+
Not covered by the acceptance run:
|
|
232
|
+
|
|
233
|
+
- a message long enough to cross the platform's own limit, so the platform-side auto split was not observed;
|
|
234
|
+
- `last` mode with a run longer than the passive window (the stale-target fallback path was only exercised in tests);
|
|
235
|
+
- the `simple` mode tool-output suppression was verified from the logs, not from the QQ client rendering.
|
|
236
|
+
|
|
237
|
+
## 8. Risks and limitations
|
|
238
|
+
|
|
239
|
+
| Risk | Impact | Handling |
|
|
240
|
+
| --------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
241
|
+
| The default stays `full`, so `simple` / `last` are opt-in | None for existing users | Documented in both READMEs and the CHANGELOG |
|
|
242
|
+
| `last` sends nothing while the run is in flight | A long task looks idle on the phone | The typing indicator keeps running; a progress hint is a possible follow-up |
|
|
243
|
+
| `last` delivers at the end, when the passive window may be gone | The final message becomes a proactive message | `budget.snapshot().fresh` pre-check plus a plain-message fallback |
|
|
244
|
+
| `simple` pushes text while a tool is still running | Different from "collect everything after the tools" | Documented; the mode is opt-in |
|
|
245
|
+
| `thinkingRelay` has no effect in `simple` / `last` | May confuse users | Both READMEs state it explicitly |
|
|
246
|
+
| `/last` during a run is unavailable in `last` mode | The manual rescue path for stuck runs is gone | The command answers with a localized notice; the run still delivers its last message |
|
|
247
|
+
| `onAssistantFinal` returns `true` in `last` mode | "Handled" now means "delivered later", not "already sent" | Documented in the design and in the code |
|
|
248
|
+
|
|
249
|
+
## 9. Open work
|
|
250
|
+
|
|
251
|
+
- [doc/todo.md](../todo.md) item 1: long-running bash argument visibility.
|
|
252
|
+
- [doc/todo.md](../todo.md) item 2: long-running tools leading to missing QQ output.
|
|
253
|
+
- `doc/todo.md` recommends using `/last` to recover a stuck run; in `last` mode that path is unavailable during the run, and the note should say so.
|
|
254
|
+
- Whether `last` needs a progress hint (D1) once real usage shows the waiting feels too long.
|
|
255
|
+
- Whether the platform's own bubble limit should be measured, so the 12k margin can be tuned.
|
|
256
|
+
|
|
257
|
+
## 10. References
|
|
258
|
+
|
|
259
|
+
- Design history: [delivery.1.5.0.md](./delivery.1.5.0.md).
|
|
260
|
+
- User-facing behavior: [README.md](../../README.md), [README-zh.md](../../README-zh.md).
|
|
261
|
+
- Earlier split design: [delivery.1.3.0.md](./delivery.1.3.0.md) §3 (12k split, repeated header).
|
|
262
|
+
- pi extension API: `pi/packages/coding-agent/docs/extensions.md` (`message_update`, `message_end`, `agent_end`).
|
|
263
|
+
- QQ SDK: `@tencent-connect/qqbot-nodejs` 1.0.5, `src/protocol/api/messages.ts` (`sendC2CStreamMessage`).
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# pi-qq delivery 1.6.1
|
|
2
|
+
|
|
3
|
+
> **Delivery record.** 1.6.1 reloads `pi-qq.json` before every inbound QQ message and removes the redundant `thinkingRelay` setting. See [README](../../README.md) for current user-facing behavior.
|
|
4
|
+
> Version: 1.6.1
|
|
5
|
+
> Date: 2026-11-11
|
|
6
|
+
> Previous: [delivery.1.6.0.md](./delivery.1.6.0.md).
|
|
7
|
+
> Open work: [doc/todo.md](../todo.md).
|
|
8
|
+
|
|
9
|
+
## 1. Scope
|
|
10
|
+
|
|
11
|
+
Before 1.6.1, `~/.pi/agent/pi-qq.json` was read when the extension loaded, on `session_start`, and on `/qq-login`. Editing the file while the bot was running required a restart or a new login.
|
|
12
|
+
|
|
13
|
+
1.6.1 changes the trigger points and removes one setting:
|
|
14
|
+
|
|
15
|
+
- reload configuration before handling every inbound QQ message from the bound user;
|
|
16
|
+
- keep one initialization read at extension load for static command descriptions and early i18n;
|
|
17
|
+
- remove the `session_start` and `/qq-login` reads;
|
|
18
|
+
- remove `thinkingRelay`; `replyType` becomes the only output-mode control.
|
|
19
|
+
|
|
20
|
+
In scope:
|
|
21
|
+
|
|
22
|
+
- a single `applyConfig()` path for reading and applying the file;
|
|
23
|
+
- per-message reload in `createInboundHandler()`;
|
|
24
|
+
- logger setup when the bot starts and on each reload;
|
|
25
|
+
- initial config errors reported at `session_start`;
|
|
26
|
+
- deduplication of repeated QQ-message config errors;
|
|
27
|
+
- removal of `thinkingRelay` from settings, relay code, i18n, tests, and READMEs.
|
|
28
|
+
|
|
29
|
+
Out of scope:
|
|
30
|
+
|
|
31
|
+
- file watching or reloading configuration without a new QQ message;
|
|
32
|
+
- restarting the QQ bot or re-running QR login on a config change;
|
|
33
|
+
- changing `replyType` modes or their relay policies;
|
|
34
|
+
- migrating local (non-QQ) runs to a new reload trigger.
|
|
35
|
+
|
|
36
|
+
## 2. Final decisions
|
|
37
|
+
|
|
38
|
+
| # | Question | Decision |
|
|
39
|
+
| --- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
40
|
+
| D1 | When is the config file read? | At extension load and before every inbound QQ message from the bound user. |
|
|
41
|
+
| D2 | Why keep the extension-load read? | Command descriptions and other static UI strings are registered before `session_start`, so `language` must be applied there. |
|
|
42
|
+
| D3 | Should `session_start` or `/qq-login` read the file again? | No. They reuse the latest initialized or reloaded values; `session_start` only reports the error captured at extension load. |
|
|
43
|
+
| D4 | Should a reload restart the bot? | No. It replaces in-memory settings, i18n, and logger configuration only. Credentials and the QQ connection stay intact. |
|
|
44
|
+
| D5 | What happens with an invalid file? | Valid fields are kept, invalid fields and parse failures fall back to defaults, and an error is reported. Identical QQ-message errors are reported once. |
|
|
45
|
+
| D6 | Should `thinkingRelay` stay? | No. `replyType: "full"` always relays thinking; `simple` and `last` never do. Existing `thinkingRelay` keys are ignored. |
|
|
46
|
+
|
|
47
|
+
## 3. Trigger points
|
|
48
|
+
|
|
49
|
+
| Event | Before 1.6.1 | 1.6.1 |
|
|
50
|
+
| ---------------------- | -------------------------- | --------------------------------------------------------------- |
|
|
51
|
+
| Extension load | Read | Read (initialization) |
|
|
52
|
+
| `session_start` | Read | No read; uses initialized values and reports the captured error |
|
|
53
|
+
| `/qq-login` | Read | No read; uses current values |
|
|
54
|
+
| Inbound QQ message | No read | Read and apply (reload) |
|
|
55
|
+
| When edits take effect | After restart or new login | On the next QQ message |
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
QQ message
|
|
59
|
+
-> qqbot filtering, access policy, concurrency guard
|
|
60
|
+
-> createInboundHandler
|
|
61
|
+
-> bound-user check
|
|
62
|
+
-> reloadSettings()
|
|
63
|
+
readConfig()
|
|
64
|
+
getSettings()
|
|
65
|
+
configureI18n()
|
|
66
|
+
configureLogger()
|
|
67
|
+
-> command or normal message handling
|
|
68
|
+
-> markQQTrigger() / sendUserMessage()
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The reload runs before attachment downloads, message injection, and replies, so the current message already uses the new `fileMaxSize`, `deliverAs`, `language`, `logLevel`, and `replyType`.
|
|
72
|
+
|
|
73
|
+
Local runs started directly in pi use the latest initialized or reloaded values. Pi reloads extensions for `new`, `resume`, and `fork`, so those flows run the initialization read again.
|
|
74
|
+
|
|
75
|
+
## 4. Settings
|
|
76
|
+
|
|
77
|
+
| Key | Effect after reload |
|
|
78
|
+
| ------------- | -------------------------------------------------------------------------- |
|
|
79
|
+
| `fileMaxSize` | Applied to attachments in the current inbound message |
|
|
80
|
+
| `deliverAs` | Applied when the current message is injected into pi |
|
|
81
|
+
| `language` | Applied to subsequent notifications, replies, and log text |
|
|
82
|
+
| `logLevel` | Applied to subsequent log writes; the QQ-run log gate is unchanged |
|
|
83
|
+
| `replyType` | Applied to subsequent relay decisions, including a run already in progress |
|
|
84
|
+
|
|
85
|
+
A run that is already executing without a new QQ message keeps the previous values.
|
|
86
|
+
|
|
87
|
+
### 4.1 Logging
|
|
88
|
+
|
|
89
|
+
- The extension-load read has no session `cwd`, so it does not configure logging.
|
|
90
|
+
- `startWithCredentials()` configures the log path and level from `activeSettings` when the bot starts.
|
|
91
|
+
- A QQ-message reload applies the latest `logLevel` immediately.
|
|
92
|
+
- Logs are still written only while a QQ-triggered run is active after login.
|
|
93
|
+
|
|
94
|
+
### 4.2 Invalid configuration
|
|
95
|
+
|
|
96
|
+
- Missing file: all defaults, no error.
|
|
97
|
+
- Invalid JSON root or parse failure: defaults, with an error.
|
|
98
|
+
- Invalid individual fields: valid fields are kept, invalid fields are ignored, with an error.
|
|
99
|
+
- The error captured at extension load is shown once at `session_start`.
|
|
100
|
+
- QQ-message reloads report new errors; identical error text is deduplicated until the config is fixed.
|
|
101
|
+
- `/qq-login` does not re-read the file, so it does not produce a new parse-error notification.
|
|
102
|
+
|
|
103
|
+
## 5. `thinkingRelay` removal
|
|
104
|
+
|
|
105
|
+
`thinkingRelay` was a sub-option of `replyType: "full"`. Removing it leaves `replyType` as the only output-mode control:
|
|
106
|
+
|
|
107
|
+
- `full` relays thinking as before.
|
|
108
|
+
- `simple` and `last` never relay thinking.
|
|
109
|
+
|
|
110
|
+
Existing `"thinkingRelay": false` entries are ignored; they no longer suppress thinking in `full` mode. Users who want no thinking must choose `simple` or `last`, which also disable tool output. A "tools but no thinking" combination would require a new `replyType` mode and is not part of 1.6.1.
|
|
111
|
+
|
|
112
|
+
## 6. Implementation
|
|
113
|
+
|
|
114
|
+
| File | Change |
|
|
115
|
+
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
116
|
+
| `index.ts` | Single `applyConfig()`; error deduplication; initial error captured for `session_start`; `startWithCredentials()` configures logging; removed `getThinkingRelay`; removed `session_start` and `/qq-login` reads |
|
|
117
|
+
| `src/qq/qq-message-handler.ts` | Added `InboundDeps.reloadSettings` and call it after the bound-user check |
|
|
118
|
+
| `src/infra/settings.ts` | Removed `thinkingRelay` parsing, validation, and defaulting |
|
|
119
|
+
| `src/relay/run-stream-relay.ts` | Thinking relay now depends only on the `replyType` policy |
|
|
120
|
+
| `src/infra/i18n.ts` | Removed the `settings.thinkingRelay` error text |
|
|
121
|
+
| `test/index.test.ts` | Per-message reload, changed `deliverAs`, initial error display, and error deduplication |
|
|
122
|
+
| `test/qq/qq-message-handler.test.ts` | Reload happens before settings are read |
|
|
123
|
+
| `test/infra/settings.test.ts` | Removed `thinkingRelay` expectations; legacy key is ignored |
|
|
124
|
+
| `test/relay/run-stream-relay.test.ts` | Removed the `thinkingRelay` harness option and test |
|
|
125
|
+
|
|
126
|
+
## 7. Verification
|
|
127
|
+
|
|
128
|
+
- **226 tests passed** across 19 files.
|
|
129
|
+
- `npm run typecheck`, `npm run lint`, `npm run format:check`, and `npm pack --dry-run` passed.
|
|
130
|
+
- The test suite covers:
|
|
131
|
+
- a config read before every handled QQ message;
|
|
132
|
+
- a `deliverAs` change between two messages taking effect on the second;
|
|
133
|
+
- `session_start` reporting the initialization error without another read;
|
|
134
|
+
- identical QQ-message config errors being reported once;
|
|
135
|
+
- the legacy `thinkingRelay` key being ignored.
|
|
136
|
+
|
|
137
|
+
## 8. Risks and limitations
|
|
138
|
+
|
|
139
|
+
| Risk | Impact | Handling |
|
|
140
|
+
| ----------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
141
|
+
| Configuration is not watched | An edit without a new QQ message is not applied to a running task | Reload is intentionally tied to the next QQ message |
|
|
142
|
+
| `/qq-login` and local status use startup values | A mid-session edit is not reflected there until the next QQ message | Accepted; QQ conversations use the fresh values |
|
|
143
|
+
| `thinkingRelay` removal | `"thinkingRelay": false` users now receive thinking in `full` mode | Documented in the CHANGELOG and READMEs; choose `simple` or `last` to suppress thinking |
|
|
144
|
+
| Config errors are deduplicated | Repeating the same invalid config does not pop a new warning | The error is shown once at load and once per distinct text during message reloads |
|
|
145
|
+
|
|
146
|
+
## 9. References
|
|
147
|
+
|
|
148
|
+
- User-facing behavior: [README.md](../../README.md), [README-zh.md](../../README-zh.md).
|
|
149
|
+
- Previous delivery: [delivery.1.6.0.md](./delivery.1.6.0.md).
|
|
150
|
+
- This record replaces the temporary configuration-timing note; that note was removed with the release.
|
package/doc/todo.md
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
# TODO
|
|
2
2
|
|
|
3
|
+
> 2026-11-06 更新:已基于 2026-11-05 / 2026-11-06 的真实使用记录完成首轮分析。TODO 1 的启动帧和参数传递已确认正常;TODO 2 仍未复现,等待真正的多分钟单命令日志。详见各条目的“日志验证结果”。
|
|
4
|
+
|
|
3
5
|
## 1. 长运行 bash 工具的参数延迟显示
|
|
4
6
|
|
|
5
|
-
>
|
|
6
|
-
> 记录日期:2026-11-04
|
|
7
|
-
>
|
|
7
|
+
> 状态:启动帧已验证正常;待确认 QQ 客户端渲染
|
|
8
|
+
> 记录日期:2026-11-04
|
|
9
|
+
> 分析日期:2026-11-06
|
|
10
|
+
> 相关版本:pi-qq 1.3.6(仅增加 debug 日志);本次日志来自 1.4.0 之后的版本
|
|
8
11
|
|
|
9
12
|
### 现象
|
|
10
13
|
|
|
@@ -16,11 +19,7 @@
|
|
|
16
19
|
- 500ms 定时器不依赖工具 Promise;长工具的启动帧曾在工具结束前通过 `stream_messages` 发出。
|
|
17
20
|
- pi 内置 bash 使用异步 `spawn`,正常情况下不会阻塞 Node 事件循环。
|
|
18
21
|
- 本地异步子进程可持续触发 500ms timer,说明“bash 子进程本身”不是必然的事件循环阻塞源。
|
|
19
|
-
-
|
|
20
|
-
- 启动帧是否真的发出;
|
|
21
|
-
- `content_raw` 是否包含命令;
|
|
22
|
-
- timer/队列/事件循环是否被延迟;
|
|
23
|
-
- QQ 是否把长行内代码折叠成了一个点。
|
|
22
|
+
- 2026-11-05 的真实使用记录已覆盖启动帧、`content_raw`、timer/队列和事件循环;但最长单条 bash 只有 94 秒的 docker build,仍没有“数分钟 e2e”样本。分析结果见下文。
|
|
24
23
|
|
|
25
24
|
### 已经添加的诊断日志
|
|
26
25
|
|
|
@@ -51,39 +50,45 @@
|
|
|
51
50
|
<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log
|
|
52
51
|
```
|
|
53
52
|
|
|
54
|
-
###
|
|
53
|
+
### 日志验证结果(2026-11-06)
|
|
55
54
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
2
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
55
|
+
基于 2026-11-05 / 2026-11-06 的真实使用记录(`logLevel: "debug"`)验证。11-05 有 4 个 QQ 触发的 run(约 8 / 21 / 29 / 23 分钟),共 529 个启动帧(483 个工具行 + 46 个 skill 块)。
|
|
56
|
+
|
|
57
|
+
**启动帧确实发出,且带完整参数:**
|
|
58
|
+
|
|
59
|
+
- 94.2 秒的 docker build:
|
|
60
|
+
- 11:49:38.449 `tool start`,`args` 包含完整 `command`;
|
|
61
|
+
- 11:49:39.032 发出 `POST .../stream_messages`,`content_raw` 以 `## 💻 bash` 开头,命令放在 `bash` fenced code block 中,完整内容为 `cd .../xuanji-mock && docker compose ... build 2>&1 | tail -6`;
|
|
62
|
+
- 11:49:39.643 收到 200 OK;
|
|
63
|
+
- 工具在 11:51:12.689 才结束,结果帧在 11:51:12.690 发出、11:51:13.323 收到 200。
|
|
64
|
+
- 529 个启动帧全部能在 `stream_messages` 请求体中找到:
|
|
65
|
+
`93 bash + 194 write + 150 read + 28 codemode + 18 edit + 46 skill = 529`。
|
|
66
|
+
- 最长的 bash 命令为 1108 字符;`content_raw` 为完整的 1134 字符(标题 + fence + 命令),没有被截断。
|
|
67
|
+
- `append start` 的 `waitedMs` 最大 1ms;`append done` 的 `totalMs` 中位数约 1.3s、最大 2.1s。延迟来自关旧气泡、开新流和网络往返,不是队列积压。
|
|
68
|
+
- 94s 工具的启动帧不是被 500ms 节流拖住的:日志为 `append: immediate`,`flush` 在 `stream open` 后立即开始。
|
|
69
|
+
- QQ run 期间 `event-loop` 的 `maxMs` 最大 258ms,`driftMs` 最大 82ms;没有数秒级阻塞。
|
|
70
|
+
|
|
71
|
+
**结论:** 在这些日志覆盖的场景中,TODO 1 中列出的四种可能——启动帧没发出、`content_raw` 没命令、queue/timer 延迟、事件循环饥饿——均不成立。pi-qq 侧在工具开始后约 1.2 秒内已经把带完整命令的启动帧交给 QQ API。
|
|
72
|
+
|
|
73
|
+
### 尚未验证
|
|
74
|
+
|
|
75
|
+
- QQ 客户端如何渲染这个 fenced code block。日志只能证明请求体里有完整命令,不能证明手机 QQ 一定把代码块展开显示。
|
|
76
|
+
- 如果手机 QQ 仍只显示“bash 和一个点”,优先检查 QQ 对带 `bash` 语言标记的 fenced block、长代码块或新气泡的折叠/渲染,而不是继续排查 relay。
|
|
72
77
|
|
|
73
78
|
### 下一步
|
|
74
79
|
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
- 修复后补测试,更新 `doc/todo.md` / `CHANGELOG.md`,再发布版本。
|
|
80
|
+
- 不需要给工具启动行增加 `flushAfter`;当前无队列/节流延迟证据。
|
|
81
|
+
- 做一次 QQ 渲染 A/B:同一命令分别用带 `bash` 语言标记的 fenced block、无语言标记的 fenced block、行内代码发送,确认是否只在某种格式下显示异常。
|
|
82
|
+
- 如果确认是 QQ 渲染问题,再考虑缩短命令摘要或改用普通文本/行内代码;如果确认正常,可直接关闭 TODO 1。
|
|
83
|
+
- 若最终需要改格式,补测试并更新 `CHANGELOG.md`,再发布版本。
|
|
80
84
|
|
|
81
85
|
## 2. 长耗时命令导致 QQ 侧无输出/失去响应
|
|
82
86
|
|
|
83
|
-
>
|
|
87
|
+
> 状态:仍未复现;等待多分钟单命令日志
|
|
84
88
|
> 记录日期:2026-11-04
|
|
89
|
+
> 分析日期:2026-11-06
|
|
85
90
|
> 相关版本:pi-qq 1.4.0
|
|
86
|
-
> 详细调研:`doc/archive/delivery
|
|
91
|
+
> 详细调研:`doc/archive/delivery.1.4.0.md`
|
|
87
92
|
|
|
88
93
|
### 现象
|
|
89
94
|
|
|
@@ -116,6 +121,7 @@ QQ 侧的 `/last` 已可用于手动恢复:
|
|
|
116
121
|
|
|
117
122
|
- 暂不实施 v4 归档中的错误分类、预算、心跳、自动重绑等行为修改。
|
|
118
123
|
- 只追加可验证的 debug 日志,等待长期使用日志后再决定修复范围。
|
|
124
|
+
- 2026-11-06 首轮日志未复现失败路径,继续维持“只加日志、不改行为”的决定;详见“日志验证结果”。
|
|
119
125
|
- 新增诊断日志在 `logLevel: "debug"` 时写入;`stream error` / `stream unavailable` 原本就是 `warn`,保留为错误记录,不改变行为。
|
|
120
126
|
|
|
121
127
|
### 已追加的诊断日志
|
|
@@ -141,7 +147,27 @@ QQ 侧的 `/last` 已可用于手动恢复:
|
|
|
141
147
|
- `scope: "inbound"`:`/stop` 记录 `wait start` / `wait done` 及 `waitedMs`。
|
|
142
148
|
- `scope: "event-loop"`:增加 `driftMs`,用于发现 timer 被事件循环延迟。
|
|
143
149
|
|
|
144
|
-
###
|
|
150
|
+
### 日志验证结果(2026-11-06)
|
|
151
|
+
|
|
152
|
+
基于 2026-11-05 / 2026-11-06 的真实使用记录验证。
|
|
153
|
+
|
|
154
|
+
**没有复现失败:**
|
|
155
|
+
|
|
156
|
+
- 最长的单条命令是 94.2 秒的 docker build;其余 e2e jest 命令为 4.2–6.8 秒。日志中没有“数分钟到数十分钟”的单条 bash。
|
|
157
|
+
- 94s 工具期间从启动帧到结果帧有 93.7 秒没有新流式帧,说明长工具确实没有进度帧;但结果帧在工具结束后 0.6 秒发出并收到 200,没有丢失。
|
|
158
|
+
- `stream error` / `stream unavailable` / `phase: "frame failed"`:0 条。
|
|
159
|
+
- TODO 点名的错误码 `304103`、`40034005`、`40034128`、`40034024`、`429`、`50002`:0 次。
|
|
160
|
+
- 529 个工具全部有 `queued → output started → result recorded → output finished`,没有 `ignored: stream dead`。
|
|
161
|
+
- 4 个 run 结束时均为 `dead=false`、`hasPendingResume=false`、`resumeAttempts=0`、`hasPendingTools=false`、`hadError=false`;2055 组 `AppendStream` 的 `flush start/done` 一一对应。
|
|
162
|
+
- 2026-11-05 有 4 个 QQ run:约 8 / 21 / 29 / 23 分钟;29 分钟的 run 结束时 `streamBubbles=184`、`streamBubblesTotal=502`,但 `budget.remaining=4`。这验证了“流式气泡没有计入 4 次被动回复上限”这个前提,但没有观察到因此失败;同一 `msg_id` 在数十分钟内仍能继续发流式帧。
|
|
163
|
+
- `/last` 有 3 次有效调用,全部在 run 已结束后:分别重发 1410、2320、1827 字符,均收到 200 + done。没有 `last repush`(运行中恢复)记录。日志中没有运行中收到的普通消息,也没有 `/stop`,所以 steer 阻塞和非阻塞 `/stop` 仍未验证。
|
|
164
|
+
- 2026-11-06 的 `event-loop maxMs=41,266,045.8` 样本与机器休眠/恢复一致,不是事件循环被阻塞 11 小时:它出现在 23:32:06.970,与 WebSocket 1006 关闭/重连同一时刻,下一次采样已回到 259ms。
|
|
165
|
+
|
|
166
|
+
**结论:** 这些日志不能验证“长命令后 QQ 无输出/失去响应”的失败路径,也不能据此实施错误分类、预算或自动重绑修复。它们只支持两个前提:长工具期间没有进度帧;流式气泡没有计入被动回复预算。真正的触发条件仍需一次单条命令运行数分钟(最好 >5 分钟,甚至 >1 小时)的日志。
|
|
167
|
+
|
|
168
|
+
### 复现时仍需采集/分析
|
|
169
|
+
|
|
170
|
+
本次日志没有出现这些错误,以下步骤保留给下次复现时使用。
|
|
145
171
|
|
|
146
172
|
1. 找到长命令的 `scope: "tool"` `start` / `end`:
|
|
147
173
|
- `durationMs` 是否与用户感知一致;
|
|
@@ -166,7 +192,7 @@ QQ 侧的 `/last` 已可用于手动恢复:
|
|
|
166
192
|
|
|
167
193
|
### 需要提供的信息
|
|
168
194
|
|
|
169
|
-
|
|
195
|
+
本次日志没有覆盖多分钟单命令、运行中收到的普通消息、`/stop` 和 `/qq-test-budget` 输出;复现时请按以下清单提供:
|
|
170
196
|
|
|
171
197
|
- `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;
|
|
172
198
|
- 长命令内容、开始时间和结束时间;
|
|
@@ -177,8 +203,10 @@ QQ 侧的 `/last` 已可用于手动恢复:
|
|
|
177
203
|
|
|
178
204
|
### 下一步
|
|
179
205
|
|
|
180
|
-
-
|
|
181
|
-
-
|
|
182
|
-
-
|
|
206
|
+
- 本次日志未复现失败;不要据此实施错误分类、预算或自动重绑修复。
|
|
207
|
+
- 继续等待一次真正的多分钟单命令日志(最好 >5 分钟,并覆盖 >1 小时的 `msg_id` 生命周期);复现时按上面的“复现时仍需采集/分析”执行。
|
|
208
|
+
- 如果目标只是改善长工具期间的体感:优先实现长工具心跳和 `tool_execution_update` 转发,这不依赖失败复现。
|
|
209
|
+
- 如果后续日志确认 `msg_id` 过期/被动次数超限:再按 `doc/archive/delivery.1.4.0.md` 的“Long-running tools”建议实现错误分类和预算修复。
|
|
183
210
|
- 如果 `/stop` 的 `wait done` 缺失或 `waitedMs` 很大:实现非阻塞 `/stop`。
|
|
184
|
-
-
|
|
211
|
+
- `/last` 目前作为手动兜底可用,保持现状,不急于自动重绑。
|
|
212
|
+
- 修复后补测试,更新 `doc/todo.md` / `CHANGELOG.md`,再发布版本。
|