@chen_hu_hu/pi-qq 1.6.0 → 1.6.2

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.
Files changed (36) hide show
  1. package/CHANGELOG.md +36 -4
  2. package/README-zh.md +21 -44
  3. package/README.md +29 -52
  4. package/doc/archive/{delivery-v1.md → delivery.1.0.0.md} +1 -1
  5. package/doc/archive/{delivery-v2.md → delivery.1.2.0.md} +1 -1
  6. package/doc/archive/{delivery-v3.md → delivery.1.3.0.md} +1 -1
  7. package/doc/archive/{delivery-v4.md → delivery.1.4.0.md} +1 -1
  8. package/doc/archive/{delivery-v5.md → delivery.1.5.0.md} +2 -2
  9. package/doc/archive/{delivery-v6.md → delivery.1.6.0.md} +3 -3
  10. package/doc/archive/delivery.1.6.1.md +150 -0
  11. package/doc/archive/delivery.1.6.2.md +196 -0
  12. package/doc/todo.md +2 -2
  13. package/index.ts +30 -32
  14. package/package.json +1 -1
  15. package/src/attachments/attachment-download.ts +2 -1
  16. package/src/attachments/file-attachments.ts +4 -5
  17. package/src/infra/file-logger.ts +6 -6
  18. package/src/infra/i18n.ts +4 -198
  19. package/src/infra/log-message-keys.ts +66 -0
  20. package/src/infra/power-status.ts +1 -11
  21. package/src/infra/reply-type.ts +1 -1
  22. package/src/infra/settings.ts +0 -6
  23. package/src/qq/inbound-attachments.ts +2 -2
  24. package/src/qq/inbound-command.ts +8 -7
  25. package/src/qq/media-tool.ts +36 -60
  26. package/src/qq/qq-bot.ts +1 -1
  27. package/src/qq/qq-diagnostics.ts +1 -1
  28. package/src/qq/qq-message-handler.ts +7 -6
  29. package/src/qq/status-report.ts +1 -13
  30. package/src/quota/reply-quota.ts +2 -2
  31. package/src/relay/bubble-writer.ts +84 -38
  32. package/src/relay/reply-policy.ts +0 -13
  33. package/src/relay/run-stream-relay.ts +129 -203
  34. package/src/relay/run-timeline.ts +127 -0
  35. package/src/relay/stream-block-format.ts +1 -1
  36. package/src/relay/stream-session.ts +25 -8
package/CHANGELOG.md CHANGED
@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.6.2] - 2026-11-11
11
+
12
+ ### Changed
13
+
14
+ - While a task is running in `replyType: "full"`, `/last` now pushes the current thinking, tools, and text snapshot to the new message immediately instead of waiting for assistant text. If the stream was dead, the repush opens a new stream and resumes later output. An empty snapshot now replies with a notice instead of staying silent.
15
+ - Log files are now always written in English; the `language` setting only affects UI notifications and replies.
16
+ - Consolidated the 1.6.2 code review and repair notes into `doc/archive/delivery.1.6.2.md`; removed the temporary `doc/repair.md`.
17
+
18
+ ### Removed
19
+
20
+ - Removed `replyType: "last"`; the only modes are now `full` and `simple`. Existing `"last"` values fall back to `full` with a validation warning.
21
+
22
+ ### Fixed
23
+
24
+ - Stream rate-limit retries now advance `index` and recognize QQ `ApiError` HTTP/business codes.
25
+ - A `40054005` duplicate-`msgseq` error now opens a new stream with a fresh sequence and replays the buffered content instead of repeatedly resuming the failed stream.
26
+ - Empty attachment responses are rejected consistently.
27
+
28
+ ## [1.6.1] - 2026-11-11
29
+
30
+ ### Changed
31
+
32
+ - Settings are loaded when the extension starts and re-read on every inbound QQ message from the bound user, so edits to `pi-qq.json` take effect on the next message without restarting pi or logging in again. Config errors are reported once per distinct text.
33
+
34
+ ### Removed
35
+
36
+ - Removed the `thinkingRelay` setting. `replyType: "full"` now always relays thinking, while `simple` and `last` never do. Existing `thinkingRelay` keys are ignored.
37
+
10
38
  ## [1.6.0] - 2026-11-09
11
39
 
12
40
  ### Added
@@ -17,7 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
17
45
  ### Changed
18
46
 
19
47
  - In `last` mode, `/last` during a running task now replies that the task is still running instead of repushing partial output.
20
- - Consolidated the v6 design and delivery record into `doc/archive/delivery-v6.md`; removed the working document.
48
+ - Consolidated the v6 design and delivery record into `doc/archive/delivery.1.6.0.md`; removed the working document.
21
49
 
22
50
  ### Fixed
23
51
 
@@ -39,7 +67,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
39
67
 
40
68
  ### Changed
41
69
 
42
- - Consolidated the v5 research, feature, and implementation plan into `doc/archive/delivery-v5.md`; removed the three working documents.
70
+ - Consolidated the v5 research, feature, and implementation plan into `doc/archive/delivery.1.5.0.md`; removed the three working documents.
43
71
 
44
72
  ### Fixed
45
73
 
@@ -71,7 +99,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
71
99
  ### Changed
72
100
 
73
101
  - 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`).
74
- - Consolidated the v4 design and investigation records into `doc/archive/delivery-v4.md` and `doc/archive/delivery-v4-zh.md`.
102
+ - Consolidated the v4 design and investigation records into `doc/archive/delivery.1.4.0.md` and `doc/archive/delivery-v4-zh.md`.
75
103
 
76
104
  ## [1.3.6] - 2026-11-04
77
105
 
@@ -151,7 +179,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
151
179
  - Added thinking labels, per-tool icons, model-error recovery, and idle-safe session handling.
152
180
  - Reorganized modules by bounded context and updated settings and delivery documentation.
153
181
 
154
- [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.5.0...HEAD
182
+ [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.6.2...HEAD
183
+ [1.6.2]: https://github.com/CQ-Developer/pi-qq/compare/v1.6.1...v1.6.2
184
+ [1.6.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.6.0...v1.6.1
185
+ [1.6.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.5.1...v1.6.0
186
+ [1.5.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.5.0...v1.5.1
155
187
  [1.5.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.2...v1.5.0
156
188
  [1.4.2]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.1...v1.4.2
157
189
  [1.4.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.0...v1.4.1
package/README-zh.md CHANGED
@@ -35,7 +35,7 @@ pi --extension /path/to/pi-qq
35
35
  给机器人发送 QQ 私聊消息即可开始任务。
36
36
 
37
37
  - **文字**:普通聊天消息。
38
- - **语音**:直接使用 QQ 内置 ASR 文本;音频不会下载或保存。如果 ASR 没有返回文本,机器人会提示你重发或改用文字。
38
+ - **语音**:QQ 内置 ASR 转写文本(`asr_refer_text`)会作为普通用户文本交给 pi;音频不会下载或保存,也不会使用外部语音识别服务。如果 ASR 没有返回文本,机器人会提示你重发或改用文字。通常语音和文字是两条独立的 QQ 消息,需要时按顺序发送。
39
39
  - **图片和文件**:保存到 `.pi/pi-qq/<sessionId>/uploads/`。如果消息中没有指令,pi 会等待你的下一条文字或语音消息。
40
40
 
41
41
  QQ 客户端对混合消息的支持不同。手机 QQ 通常一次只发一种类型,桌面版 QQ 可以发送“文字 + 图片”。当客户端把文字/语音和附件放在同一条消息里时,pi-qq 会把它们合并到同一个提示词中处理。
@@ -50,6 +50,7 @@ QQ 客户端对混合消息的支持不同。手机 QQ 通常一次只发一种
50
50
  - 图片通过 pi 的 `read` 工具查看,因此当前模型必须支持图片输入才能看到内容。
51
51
  - `/new` 会清空等待指令的附件。
52
52
  - 附件按当前 pi 会话隔离。相同文件名且内容相同会复用已有文件;相同文件名但内容不同会保存为 `name-1.ext`;不同文件名但内容相同会分别保存。
53
+ - 如有需要,请把 `.pi/` 加入你自己的项目 `.gitignore`。
53
54
 
54
55
  pi 看到的提示词示例:
55
56
 
@@ -74,25 +75,16 @@ Summarize this file.
74
75
  - 每条媒体消息消耗一次被动回复;超过限制后自动降级为主动消息。
75
76
  - 工具气泡与其它工具一致:`## 📤 qq_send_media`。
76
77
 
77
- ### 语音消息
78
-
79
- 语音消息使用 QQ 内置 ASR(`asr_refer_text`)。转写文本会作为普通用户文本交给 pi;pi 不会收到音频文件。
80
-
81
- - 语音附件不会下载或保存为 `.amr` / `.silk`。
82
- - 不使用本地或外部语音识别服务。
83
- - 如果 QQ ASR 没有返回文本,机器人会回复 `Could not transcribe this voice message; please resend or type it.`,并且不会启动 pi。
84
- - 语音和文字是两条独立的 QQ 消息;需要时按顺序发送。
85
- - 如果客户端允许语音消息同时携带文件或图片,它们会与转写文本一起处理。
86
-
87
- 将 `logLevel` 设为 `debug` 时,日志会包含原始 `asr_refer_text` 和附件元数据。
88
-
89
78
  ### 回复格式
90
79
 
91
- - **思考**:独立气泡,纯文本,首行 `## 💭 思考`。长思考可能续到新气泡,并重复标题。
80
+ `replyType: "full"` 模式下,QQ 会收到这些块类型:
81
+
82
+ - **思考**:独立气泡,纯文本,首行是本地化的 `## 💭 <标签>`(`Thinking` 或 `思考`)。长思考可能续到新气泡,并重复标题。
92
83
  - **工具**:每次调用独立气泡,首行 `## <图标> <工具名>`;`bash` 命令使用 `bash` 代码块,其他参数使用行内代码;结果按工具/文件类型使用 `text`、`markdown`、`python`、`json` 等代码块。
93
84
  - **普通消息**:原文,不加标题。
94
85
  - **工具图标**:💻 bash、📖 read、📝 write、✏️ edit、🔎 grep、🔍 search、🗂️ find、📁 ls、📋 list、🌐 web、📡 fetch、🗑️ delete、❌ remove、✅ todo、🧪 test;未配置工具使用 🔧。
95
- - **错误恢复**:模型错误后 60 秒内自动恢复的 run 会继续推送到原 QQ 会话;`/stop` 会等待当前工具和流收尾后再回复。
86
+
87
+ 模型错误后 60 秒内自动恢复的 run 会继续推送到原 QQ 会话;`/stop` 会等待当前工具和流收尾后再回复。
96
88
 
97
89
  ## 命令
98
90
 
@@ -113,7 +105,7 @@ QQ 侧命令:
113
105
  | `/stop` | 中止当前运行 |
114
106
  | `/compact` | 压缩当前上下文 |
115
107
  | `/status` | 显示会话和上下文状态 |
116
- | `/last` | 以流式推送最近完成的回复,或重新推送当前输出 |
108
+ | `/last` | 运行中重推当前输出;空闲时重推最近完成的回复 |
117
109
  | `/help` | 显示命令帮助 |
118
110
 
119
111
  ### 诊断
@@ -126,15 +118,12 @@ QQ 侧命令:
126
118
  | `/qq-test-md [text]` | 发送 Markdown 测试消息 |
127
119
  | `/qq-test-stream` | 运行流式时间线诊断(`resume` 验证续写) |
128
120
 
129
- 将 `logLevel` 设为 `debug` 时,只有在登录后由 QQ 消息触发的 run 期间才会写入 agent/message/tool 日志;本地 run、登录流程和空闲时段不写日志。`scope: "media"` 记录媒体工具在这些 run 中的关键步骤,QQ relay 日志也只在 QQ 触发的 run 中出现。
130
-
131
121
  ## 设置
132
122
 
133
123
  创建 `~/.pi/agent/pi-qq.json` 覆盖默认值。该文件只保存设置;凭据不会写入其中。
134
124
 
135
125
  ```json
136
126
  {
137
- "thinkingRelay": true,
138
127
  "replyType": "full",
139
128
  "deliverAs": "steer",
140
129
  "fileMaxSize": 52428800,
@@ -143,16 +132,15 @@ QQ 侧命令:
143
132
  }
144
133
  ```
145
134
 
146
- | 配置项 | 默认值 | 说明 |
147
- | --------------- | ---------- | ------------------------------------------------------ |
148
- | `thinkingRelay` | `true` | 以本地化的 `## 💭` 标题纯文本回传思考;`false` 时隐藏 |
149
- | `replyType` | `"full"` | 推送到 QQ 的内容粒度:`full`、`simple`、`last` |
150
- | `deliverAs` | `"steer"` | 忙碌时新消息的排队方式:`steer` 或 `followUp` |
151
- | `fileMaxSize` | `52428800` | QQ 附件下载上限(字节,50MB) |
152
- | `language` | `"zh-cn"` | UI 和日志语言:`zh-cn` 或 `en-us` |
153
- | `logLevel` | `"silent"` | 日志阈值:`silent`、`error`、`warn`、`info` 或 `debug` |
135
+ | 配置项 | 默认值 | 说明 |
136
+ | ------------- | ---------- | ------------------------------------------------------ |
137
+ | `replyType` | `"full"` | 推送到 QQ 的内容粒度:`full` 或 `simple` |
138
+ | `deliverAs` | `"steer"` | 忙碌时新消息的排队方式:`steer` 或 `followUp` |
139
+ | `fileMaxSize` | `52428800` | QQ 附件下载上限(字节,50MB) |
140
+ | `language` | `"zh-cn"` | UI 语言:`zh-cn` 或 `en-us`;日志始终为英文 |
141
+ | `logLevel` | `"silent"` | 日志阈值:`silent`、`error`、`warn`、`info` 或 `debug` |
154
142
 
155
- 配置在 pi 会话启动时读取;修改文件后请重启 pi。未知配置项会被忽略,无效值会回退到默认值并给出提示。
143
+ 配置在扩展加载时读取,并在每条来自已绑定用户的 QQ 消息处理前重新读取。修改后下一条消息即生效,无需重启 pi 或重新登录。未知配置项会被忽略,无效值会回退到默认值并给出提示。
156
144
 
157
145
  ### `replyType`
158
146
 
@@ -162,21 +150,12 @@ QQ 侧命令:
162
150
  | -------- | ------------------------------------------------------------- |
163
151
  | `full` | 思考块、工具调用、工具结果,以及每一条 assistant 消息(默认) |
164
152
  | `simple` | 只推 assistant 消息,每条一个气泡 |
165
- | `last` | 只推 run 中最后一条 assistant 消息,在 run 结束时送出 |
166
153
 
167
- - `full` 是默认值,保持 pi-qq 1.5.x 的行为,也是唯一会应用 `thinkingRelay` 的模式。
154
+ - `full` 是默认值,保持 pi-qq 1.5.x 的行为;该模式固定回传思考。
168
155
  - `simple` 会实时流出每一条 assistant 消息,一条消息一个气泡。
169
- - `last` 在任务运行期间不推送任何内容;运行期间执行 `/last` 会回复“任务仍在进行中”。
170
156
  - 无论哪种模式,模型错误消息都会立即以普通消息发出。
171
- - `simple` 与 `last` 不回传工具输出,但 `qq_send_media` 发送的文件仍然会送达。
172
-
173
- ### `thinkingRelay`
174
-
175
- 是否把模型的思考单独回传成一个气泡。
176
-
177
- - `true`(默认):以本地化的 `## 💭` 标题纯文本回传思考。
178
- - `false`:丢弃思考。
179
- - 只在 `replyType: "full"` 下生效;`simple` 与 `last` 不会回传思考。
157
+ - `simple` 不回传工具输出,但 `qq_send_media` 发送的文件仍然会送达。
158
+ - 任务运行中执行 `/last` 时,`full` 模式会推送当前思考、工具和文本快照;`simple` 模式只推送当前文本。
180
159
 
181
160
  ### `deliverAs`
182
161
 
@@ -191,14 +170,14 @@ QQ 侧命令:
191
170
 
192
171
  ### `language`
193
172
 
194
- UI 提示与日志的语言。
173
+ UI 提示与回复的语言。日志文件始终使用英文,不受该配置影响。
195
174
 
196
175
  - `zh-cn`(默认):简体中文。
197
176
  - `en-us`:英文。
198
177
 
199
178
  ### `logLevel`
200
179
 
201
- 日志阈值。只有 QQ 触发的 run 处于活动状态时才会写记录,路径为 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;可用 `PI_QQ_LOG_DIR` 覆盖目录。
180
+ 日志阈值。只有登录后 QQ 触发的 run 处于活动状态时才会写记录,路径为 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;可用 `PI_QQ_LOG_DIR` 覆盖目录。`scope: "media"` 记录媒体工具在这些 run 中的步骤。
202
181
 
203
182
  - `silent`(默认):完全不写日志文件。
204
183
  - `error`:只记录失败。
@@ -230,8 +209,6 @@ npm run format:check
230
209
 
231
210
  - 仅支持 C2C(QQ 私聊)。
232
211
  - QQ 入站消息触发的任务会回传 QQ;直接在 pi 中启动的无关任务不会推送。
233
- - 图片会保存为文件,并通过 pi 的 `read` 工具查看;当前模型必须支持图片输入才能看到内容。
234
- - 保存的附件位于工作区 `.pi/` 下;如有需要,请把 `.pi/` 加入你自己的项目 `.gitignore`。
235
212
  - QQ 对每条入站消息的被动回复次数有限制。可用 `/qq-test-budget` 查看本地额度。
236
213
  - 读取 `SKILL.md` 时,QQ 显示 `## 🧩 技能` 和 skill 名称,不转发文件内容。
237
214
 
package/README.md CHANGED
@@ -35,7 +35,7 @@ Credentials are not written to `pi-qq.json`. Restarting pi requires scanning aga
35
35
  Send a private message to the bot to start a task.
36
36
 
37
37
  - **Text**: normal chat message.
38
- - **Voice**: QQ's built-in ASR text is sent to pi. The audio is not downloaded or saved. If ASR returns no text, the bot asks you to resend or type it.
38
+ - **Voice**: QQ's built-in ASR transcript (`asr_refer_text`) is sent to pi as normal user text. The audio is not downloaded or saved, and no external speech-to-text service is used. If ASR returns no text, the bot asks you to resend or type it. Voice and text are normally separate QQ messages; send them in sequence when needed.
39
39
  - **Images and files**: saved under `.pi/pi-qq/<sessionId>/uploads/`. If the message has no instruction, pi waits for your next text or voice message.
40
40
 
41
41
  QQ clients differ in mixed-message support. Mobile QQ usually sends one message type at a time; desktop QQ can send text with an image. When a client includes text or voice together with attachments, pi-qq processes them in the same prompt.
@@ -50,6 +50,7 @@ An attachment-only message does **not** start pi. Files and images are saved, an
50
50
  - Images are read through pi's `read` tool, so the current model must support image input to see them.
51
51
  - `/new` clears attachments waiting for an instruction.
52
52
  - Uploads are scoped to the current pi session. Same filename and identical content reuse the existing file; same filename with different content becomes `name-1.ext`; different filenames with identical content are kept separately.
53
+ - Add `.pi/` to your project `.gitignore` if needed.
53
54
 
54
55
  Example prompt seen by pi:
55
56
 
@@ -74,25 +75,16 @@ Ask pi explicitly, for example `send me the screenshot` or `把截图发给我`.
74
75
  - Each media message consumes one passive reply; after the limit, pi-qq falls back to a proactive message.
75
76
  - The tool bubble is the same as any other tool: `## 📤 qq_send_media`.
76
77
 
77
- ### Voice messages
78
-
79
- 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.
80
-
81
- - The voice attachment is not downloaded or saved as `.amr` / `.silk`.
82
- - No local or external speech-to-text service is used.
83
- - 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.
84
- - Voice and text are separate QQ messages; send them one after another when needed.
85
- - If a client sends files or images together with a voice message, they are processed with the transcript.
86
-
87
- Debug logs include the raw `asr_refer_text` and attachment metadata when `logLevel` is set to `debug`.
88
-
89
78
  ### Reply format
90
79
 
91
- - **Thinking**: its own bubble, plain text, starting with `## 💭 思考`. Long thinking may continue in a new bubble with the header repeated.
80
+ In `replyType: "full"` mode, QQ receives these block types:
81
+
82
+ - **Thinking**: its own bubble, plain text, starting with a localized `## 💭 <label>` heading (`Thinking` or `思考`). Long thinking may continue in a new bubble with the header repeated.
92
83
  - **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.
93
84
  - **Regular messages**: raw text with no header.
94
85
  - **Tool icons**: 💻 bash, 📖 read, 📝 write, ✏️ edit, 🔎 grep, 🔍 search, 🗂️ find, 📁 ls, 📋 list, 🌐 web, 📡 fetch, 🗑️ delete, ❌ remove, ✅ todo, 🧪 test; unconfigured tools use 🔧.
95
- - **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.
86
+
87
+ After a model error, automatic retries within 60 seconds keep pushing to the original QQ chat. `/stop` waits for active tools and streams to finish before replying.
96
88
 
97
89
  ## Commands
98
90
 
@@ -107,14 +99,14 @@ Run these in the pi terminal:
107
99
 
108
100
  QQ-side commands:
109
101
 
110
- | Command | Description |
111
- | ---------- | ------------------------------------------------------------------------ |
112
- | `/new` | Start a new pi session |
113
- | `/stop` | Abort the current run |
114
- | `/compact` | Compact the current context |
115
- | `/status` | Show session and context status |
116
- | `/last` | Push the last completed reply as a stream, or restart the current output |
117
- | `/help` | Show command help |
102
+ | Command | Description |
103
+ | ---------- | -------------------------------------------------------------------------- |
104
+ | `/new` | Start a new pi session |
105
+ | `/stop` | Abort the current run |
106
+ | `/compact` | Compact the current context |
107
+ | `/status` | Show session and context status |
108
+ | `/last` | Repush current output while running, or the last completed reply when idle |
109
+ | `/help` | Show command help |
118
110
 
119
111
  ### Diagnostics
120
112
 
@@ -126,15 +118,12 @@ These terminal commands are intended for troubleshooting:
126
118
  | `/qq-test-md [text]` | Send a Markdown test message |
127
119
  | `/qq-test-stream` | Run a streamed timeline diagnostic (`resume` for probe) |
128
120
 
129
- With `logLevel: "debug"`, logs are written only while a QQ-triggered run is active after login; local runs, login, and idle periods are not logged. `scope: "media"` covers media-tool steps during those runs, and QQ relay logs only appear for QQ-triggered runs.
130
-
131
121
  ## Settings
132
122
 
133
123
  Create `~/.pi/agent/pi-qq.json` to override defaults. It stores settings only; credentials are never written to it.
134
124
 
135
125
  ```json
136
126
  {
137
- "thinkingRelay": true,
138
127
  "replyType": "full",
139
128
  "deliverAs": "steer",
140
129
  "fileMaxSize": 52428800,
@@ -143,16 +132,15 @@ Create `~/.pi/agent/pi-qq.json` to override defaults. It stores settings only; c
143
132
  }
144
133
  ```
145
134
 
146
- | Key | Default | Description |
147
- | --------------- | ---------- | ------------------------------------------------------------ |
148
- | `thinkingRelay` | `true` | Relay thinking as plain text with a localized `## 💭` header |
149
- | `replyType` | `"full"` | How much of a run is pushed to QQ: `full`, `simple`, `last` |
150
- | `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
151
- | `fileMaxSize` | `52428800` | QQ attachment download limit in bytes (50MB) |
152
- | `language` | `"zh-cn"` | UI and log language: `zh-cn` or `en-us` |
153
- | `logLevel` | `"silent"` | Log threshold: `silent`, `error`, `warn`, `info`, or `debug` |
135
+ | Key | Default | Description |
136
+ | ------------- | ---------- | ------------------------------------------------------------- |
137
+ | `replyType` | `"full"` | How much of a run is pushed to QQ: `full` or `simple` |
138
+ | `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
139
+ | `fileMaxSize` | `52428800` | QQ attachment download limit in bytes (50MB) |
140
+ | `language` | `"zh-cn"` | UI language: `zh-cn` or `en-us`; log files are always English |
141
+ | `logLevel` | `"silent"` | Log threshold: `silent`, `error`, `warn`, `info`, or `debug` |
154
142
 
155
- Settings are read when a pi session starts; restart pi after editing the file. Unknown keys are ignored, and invalid values fall back to defaults with a warning.
143
+ Settings are loaded when the extension starts and re-read on every inbound QQ message from the bound user, so edits take effect on the next message without restarting pi or logging in again. Unknown keys are ignored, and invalid values fall back to defaults with a warning.
156
144
 
157
145
  ### `replyType`
158
146
 
@@ -162,21 +150,12 @@ How much of an agent run is pushed to QQ.
162
150
  | -------- | -------------------------------------------------------------------------------- |
163
151
  | `full` | Thinking blocks, tool calls, tool results, and every assistant message (default) |
164
152
  | `simple` | Assistant messages only, one bubble each |
165
- | `last` | Only the last assistant message of the run, sent when the run ends |
166
153
 
167
- - `full` is the default and keeps the behaviour of pi-qq 1.5.x; it is the only mode where `thinkingRelay` applies.
154
+ - `full` is the default and keeps the behaviour of pi-qq 1.5.x; thinking is always relayed in this mode.
168
155
  - `simple` streams every assistant message live, one QQ bubble per message.
169
- - `last` sends nothing while the task is running; `/last` during a running task replies that the task is still running.
170
- - Model errors are always delivered immediately as a normal message, in every mode.
171
- - Tool output is not relayed in `simple` or `last`, but files sent with `qq_send_media` are still delivered.
172
-
173
- ### `thinkingRelay`
174
-
175
- Whether the model's thinking is relayed to QQ as its own bubble.
176
-
177
- - `true` (default): thinking is relayed as plain text under a localized `## 💭` heading.
178
- - `false`: thinking is dropped.
179
- - Only applies to `replyType: "full"`; `simple` and `last` never relay thinking.
156
+ - Model errors are always delivered immediately as a normal message, in either mode.
157
+ - Tool output is not relayed in `simple`, but files sent with `qq_send_media` are still delivered.
158
+ - While a task is running, `/last` pushes the current thinking/tools/text snapshot in `full` mode; in `simple` mode it pushes the current text.
180
159
 
181
160
  ### `deliverAs`
182
161
 
@@ -191,14 +170,14 @@ Maximum size of an inbound attachment, in bytes (default `52428800`, 50MB). Larg
191
170
 
192
171
  ### `language`
193
172
 
194
- Language of the UI notifications and the log messages.
173
+ Language of UI notifications and replies. Log files are always written in English, regardless of this setting.
195
174
 
196
175
  - `zh-cn` (default): Simplified Chinese.
197
176
  - `en-us`: English.
198
177
 
199
178
  ### `logLevel`
200
179
 
201
- Log threshold. Records are written only while a QQ-triggered run is active, to `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`; `PI_QQ_LOG_DIR` overrides the directory.
180
+ Log threshold. Records are written only while a QQ-triggered run is active after login, to `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`; `PI_QQ_LOG_DIR` overrides the directory. `scope: "media"` covers media-tool steps during those runs.
202
181
 
203
182
  - `silent` (default): no log file at all.
204
183
  - `error`: failures only.
@@ -230,8 +209,6 @@ The extension entrypoint is `index.ts`. Source modules are grouped by responsibi
230
209
 
231
210
  - Only C2C (QQ private chat) is supported.
232
211
  - Runs triggered by inbound QQ messages are relayed to QQ. Unrelated tasks started directly in pi stay local.
233
- - Images are saved as files and read through pi's `read` tool; the current model must support image input to see them.
234
- - Saved attachments are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
235
212
  - QQ limits passive replies per inbound message. Use `/qq-test-budget` to inspect the local budget.
236
213
  - Reading a `SKILL.md` is shown as a `## 🧩 Skill` block with the skill name; the file content is not forwarded to QQ.
237
214
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  > **Archived record.** Content reflects the delivery at that time and may reference removed modules or settings. See [README](../../README.md) for current behavior.
4
4
  > Status: v1 delivered; this is a historical baseline for later versions.
5
- > Later versions: [delivery-v2.md](./delivery-v2.md), [delivery-v3.md](./delivery-v3.md).
5
+ > Later versions: [delivery.1.2.0.md](./delivery.1.2.0.md), [delivery.1.3.0.md](./delivery.1.3.0.md).
6
6
 
7
7
  ## 1. Scope
8
8
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  > **Archived record.** Content reflects the delivery at that time and may reference removed modules or settings. See [README](../../README.md) for current behavior.
4
4
  > Status: v2 delivered; this is a historical record.
5
- > Previous: [delivery-v1.md](./delivery-v1.md); next: [delivery-v3.md](./delivery-v3.md).
5
+ > Previous: [delivery.1.0.0.md](./delivery.1.0.0.md); next: [delivery.1.3.0.md](./delivery.1.3.0.md).
6
6
 
7
7
  ## 1. Scope
8
8
 
@@ -3,7 +3,7 @@
3
3
  > **Archived record.** Content reflects the delivery at that time and may reference removed modules or settings. See [README](../../README.md) for current behavior.
4
4
  > Status: v3 implemented and the main path has been verified on real QQ.
5
5
  > Note: later changes removed the image-specific pipeline; images now use the same save/pending path as files.
6
- > Previous: [delivery-v1.md](./delivery-v1.md), [delivery-v2.md](./delivery-v2.md).
6
+ > Previous: [delivery.1.0.0.md](./delivery.1.0.0.md), [delivery.1.2.0.md](./delivery.1.2.0.md).
7
7
 
8
8
  ## 1. Scope
9
9
 
@@ -4,7 +4,7 @@
4
4
  > Status: v4 delivered. Tool block types were verified on real QQ; long-running tool handling and offline delivery remain open items.
5
5
  > Version: 1.4.0
6
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).
7
+ > 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).
8
8
  > Open work: [doc/todo.md](../todo.md).
9
9
 
10
10
  ## 1. Scope
@@ -3,7 +3,7 @@
3
3
  > **Delivery record.** v5 adds outbound media delivery and fixes debug log coverage for non-QQ runs. See [README](../../README.md) for current user-facing behavior.
4
4
  > Version: 1.5.0
5
5
  > Date: 2026-11-05
6
- > Previous: [delivery-v1.md](./delivery-v1.md), [delivery-v2.md](./delivery-v2.md), [delivery-v3.md](./delivery-v3.md), [delivery-v4.md](./delivery-v4.md).
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).
7
7
  > Supersedes: `doc/research.md`, `doc/feature.md`, and `doc/plan.md`; those working documents were consolidated into this record and removed.
8
8
  > Open work: [doc/todo.md](../todo.md).
9
9
 
@@ -211,7 +211,7 @@ The v5 acceptance log does not cover the two long-running bash scenarios; they r
211
211
 
212
212
  ## 12. References
213
213
 
214
- - Design history: [delivery-v4.md](./delivery-v4.md).
214
+ - Design history: [delivery.1.4.0.md](./delivery.1.4.0.md).
215
215
  - User-facing behavior: [README.md](../../README.md), [README-zh.md](../../README-zh.md).
216
216
  - QQ SDK: `@tencent-connect/qqbot-nodejs` 1.0.5, `src/QQBot.ts`, `src/protocol/api/media.ts`.
217
217
  - pi extension API: `pi/packages/coding-agent/docs/extensions.md`.
@@ -3,7 +3,7 @@
3
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
4
  > Version: 1.6.0
5
5
  > Date: 2026-11-09
6
- > Previous: [delivery-v1.md](./delivery-v1.md), [delivery-v2.md](./delivery-v2.md), [delivery-v3.md](./delivery-v3.md), [delivery-v4.md](./delivery-v4.md), [delivery-v5.md](./delivery-v5.md).
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
7
  > Open work: [doc/todo.md](../todo.md).
8
8
 
9
9
  ## 1. Scope
@@ -256,8 +256,8 @@ Not covered by the acceptance run:
256
256
 
257
257
  ## 10. References
258
258
 
259
- - Design history: [delivery-v5.md](./delivery-v5.md).
259
+ - Design history: [delivery.1.5.0.md](./delivery.1.5.0.md).
260
260
  - User-facing behavior: [README.md](../../README.md), [README-zh.md](../../README-zh.md).
261
- - Earlier split design: [delivery-v3.md](./delivery-v3.md) §3 (12k split, repeated header).
261
+ - Earlier split design: [delivery.1.3.0.md](./delivery.1.3.0.md) §3 (12k split, repeated header).
262
262
  - pi extension API: `pi/packages/coding-agent/docs/extensions.md` (`message_update`, `message_end`, `agent_end`).
263
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.