@chen_hu_hu/pi-qq 0.0.0-stage → 1.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CQ-Developer
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,102 @@
1
- # Temporary Holding Version
1
+ # pi-qq
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Connect [pi](https://github.com/earendil-works/pi) to a QQ private chat. Send text, images, or files from mobile QQ; pi works on your machine and sends the result back to QQ.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pi install npm:@chen_hu_hu/pi-qq
9
+ ```
10
+
11
+ For local development:
12
+
13
+ ```bash
14
+ pi --extension /path/to/pi-qq
15
+ ```
16
+
17
+ ## Login
18
+
19
+ 1. Start pi.
20
+ 2. Run `/qq-login`.
21
+ 3. Scan the QR code with mobile QQ.
22
+
23
+ Credentials are kept in process memory only. Restarting pi requires scanning again. `/qq-logout` clears the in-memory credentials immediately.
24
+
25
+ ## Usage
26
+
27
+ Send a QQ private message to the bot to start a task.
28
+
29
+ - **Text**: normal chat message.
30
+ - **Images**: sent to pi as vision input.
31
+ - **Files**: saved under the current workspace at `.pi/pi-qq/YYYY-MM-DD/<msgId>/`; the saved path, size, and original filename are added to the prompt.
32
+
33
+ Example file prompt seen by pi:
34
+
35
+ ```text
36
+ User sent the following file via QQ (saved locally; use read/bash or other tools to access it):
37
+ - /home/chen/project/myproj/.pi/pi-qq/2026-10-29/xxx/report.pdf (1.4MB, original name: report.pdf)
38
+
39
+ User message:
40
+ Summarize this file.
41
+ ```
42
+
43
+ ## Commands
44
+
45
+ Run these in the pi terminal:
46
+
47
+ | Command | Description |
48
+ | --- | --- |
49
+ | `/qq-login` | Log in with a QR code and bind the scanning QQ user |
50
+ | `/qq-status` | Show login, connection, model, context, and bound user |
51
+ | `/qq-logout` | Log out and clear in-memory credentials |
52
+ | `/qq-budget` | Show passive-reply budget and stream-bubble diagnostics |
53
+ | `/qq-md [text]` | Send a Markdown test message |
54
+ | `/qq-stream-test` | Run a streamed timeline diagnostic |
55
+ | `/qq-new` | Reset the current session (used by QQ `/new`) |
56
+
57
+ QQ-side commands:
58
+
59
+ | Command | Description |
60
+ | --- | --- |
61
+ | `/new` | Start a new pi session |
62
+ | `/stop` | Abort the current run |
63
+ | `/compact` | Compact the current context |
64
+ | `/status` | Show session and usage status |
65
+ | `/help` | Show command help |
66
+
67
+ ## Settings
68
+
69
+ Create `~/.pi/agent/pi-qq.json` to override defaults. This file contains settings only; credentials are never written to it.
70
+
71
+ ```json
72
+ {
73
+ "markdownSupport": false,
74
+ "streamFlushMs": 10000,
75
+ "debug": false
76
+ }
77
+ ```
78
+
79
+ | Key | Default | Description |
80
+ | --- | --- | --- |
81
+ | `streamAssistant` | `true` | Stream assistant replies |
82
+ | `markdownSupport` | `false` | Bot has QQ Markdown permission; pass Markdown through |
83
+ | `usageRelay` | `true` | Send the per-run usage summary |
84
+ | `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
85
+ | `imageMaxSize` | `10485760` | QQ image download limit in bytes (10MB) |
86
+ | `fileMaxSize` | `52428800` | QQ file download limit in bytes (50MB) |
87
+ | `heartbeatMinutes` | `10` | Long-task heartbeat interval; `0` disables |
88
+ | `heartbeatMaxMessages` | `3` | Per-run message heartbeat limit |
89
+ | `streamRelay` | `true` | Use append-mode stream bubbles |
90
+ | `streamFlushMs` | `10000` | Stream summary frame interval in ms (minimum 300) |
91
+ | `debug` | `false` | SDK and stream retry/timeout diagnostics |
92
+
93
+ ## Notes
94
+
95
+ - Only C2C (QQ private chat) is supported.
96
+ - Incoming images are passed to the model as vision input; the current model must support image input.
97
+ - Saved files are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
98
+ - QQ limits passive replies per inbound message. Use `/qq-budget` to inspect the local budget.
99
+
100
+ ## License
101
+
102
+ MIT
@@ -0,0 +1,261 @@
1
+ # pi-qq — features.md
2
+
3
+ > pi 扩展:通过 QQ 机器人把 pi 接入 QQ 单人私聊(C2C)。
4
+ > 手机 QQ 上发消息(含图片)→ pi 在机器上干活 → 完整回复(Markdown → 纯文本)+ token 用量与上下文占比回传到 QQ。
5
+
6
+ 技术栈:
7
+
8
+ | 依赖 | 用途 |
9
+ | --- | --- |
10
+ | `@tencent-connect/qqbot-nodejs` | QQ 开放平台协议层:WebSocket Gateway、C2C 消息收发、媒体上传、流式消息 |
11
+ | `@tencent-connect/qqbot-connector` | 扫码登录:展示二维码,扫码后换取 `appId / appSecret / userOpenid`(仅内存) |
12
+ | `@earendil-works/pi-coding-agent`(ExtensionAPI) | pi 扩展宿主:事件订阅、命令注册、消息注入、上下文用量 |
13
+
14
+ ---
15
+
16
+ ## 1. 总体架构
17
+
18
+ 扩展以**目录形式**加载进 pi(`index.ts` + `package.json`),在 pi 进程内运行 QQBot 客户端:
19
+
20
+ ```
21
+ 手机 QQ(单人用户)
22
+ │ C2C 私聊(WebSocket Gateway)
23
+ ▼
24
+ QQBot(@tencent-connect/qqbot-nodejs,扩展内持有)
25
+ │ bot.on("message") ▲ bot.sendText / openStream(纯文本)
26
+ ▼ │
27
+ pi-qq 扩展 ── pi.sendUserMessage(text+images) ─┴─ pi 事件:
28
+ (QQ → pi 注入) message_update / message_end /
29
+ agent_end / ctx.getContextUsage()
30
+ ```
31
+
32
+ - **QQ → pi**:入站 C2C 消息经白名单校验后,通过 `pi.sendUserMessage()` 注入 pi(文本 + 图片附件转 `ImageContent`)。
33
+ - **pi → QQ**:订阅 pi 生命周期事件,格式化后经 `bot.sendText / openStream` 回传(纯文本)。
34
+ - 生命周期:`session_start` 启动 bot、`session_shutdown` 幂等关闭;WebSocket 断线重连由 SDK 负责。
35
+
36
+ ## 2. 核心功能
37
+
38
+ ### F1 扫码登录(仅扫码)
39
+
40
+ **目标**:唯一登录方式是 `/qq-login` 扫码;凭据只保存在进程内存,绝不落盘。pi 进程退出后必须重新扫码。
41
+
42
+ **行为**
43
+
44
+ 1. 用户在 pi 中执行 `/qq-login`。
45
+ 2. 扩展停止现有连接,调用 `startQrConnect({ displayQrCodeToConsole: false, signal })`:
46
+ - `onQrDisplayed(url)`:TUI 用 `qrcode-terminal` 把 URL 画成 ASCII 二维码;非 TUI 输出 URL。
47
+ - `onQrExpired()`:提示二维码过期并自动刷新。
48
+ - `onSuccess([{ appId, appSecret, userOpenid }])`:获取凭据与扫码人 openid。
49
+ 3. 凭据写入进程内存(`globalThis` 登录状态),不写 `~/.pi/agent/pi-qq.json`。`userOpenid` 作为唯一绑定的 QQ 用户白名单。
50
+ 4. 立即构造 `QQBot` 并启动;未完成扫码前可取消(Esc / AbortSignal)。
51
+ 5. 同一 pi 进程内的 session reload / `/new` 会复用内存登录;pi 进程退出后内存清空,下次启动必须重新 `/qq-login`。
52
+ 6. `/qq-logout` 立即清除内存凭据并断开连接;之后可重新扫码。
53
+
54
+ **通用**
55
+
56
+ - `/qq-status`、`/qq-login`、`/qq-logout`、`/qq-budget`、`/qq-md`、`/qq-stream-test`、`/qq-new` 的命令说明与 pi 终端输出均为英文。
57
+ - `/qq-status` 显示登录状态(in memory)、连接状态、模型、上下文与绑定用户;AppID 仅显示前 4 位 + `****`。
58
+ - 配置文件 `~/.pi/agent/pi-qq.json` 只保存非敏感设置;旧的 `AppID` / `AppSecret` / `allowedOpenid` 键会被忽略,不再用于登录。
59
+ - 白名单只接受扫码绑定的 openid;未登录时入站消息直接忽略。
60
+
61
+ ### F2 单人聊天
62
+
63
+ **目标**:只有一个绑定的用户能与机器人对话,消息进入 pi 会话。
64
+
65
+ **行为**
66
+
67
+ - 仅接受 `kind === "c2c"` 的入站消息;发送者 openid 必须等于本次扫码绑定的内存白名单(复用 SDK `accessPolicy`,其他用户静默忽略)。入站消息的 `senderId` 即发送者的 openid。
68
+ - 普通文本 → `pi.sendUserMessage(text)`,触发正常 agent run。
69
+ - 图片消息的处理见 F3(QQ → pi)。
70
+ - agent 忙碌时收到新消息 → 按 `deliverAs`(默认 `steer`,可配置 `followUp`)排队。
71
+ - QQ 侧控制命令(在进入 pi 前拦截):
72
+ - `/new` 新会话、`/stop` 中止当前 run(`ctx.abort()`)、`/compact` 压缩上下文(`ctx.compact()`)、`/status` 会话与用量状态、`/help` 命令帮助。
73
+ - agent 工作期间向 QQ 发送 typing 提示(SDK `sendTyping`,C2C only)。
74
+
75
+ ### F3 发送图片与文件(QQ → pi)
76
+
77
+ **目标**:用户在 QQ 上把图片或文件发给 pi;图片作为视觉输入,文件保存到本机并在提示词中给出路径。
78
+
79
+ **图片行为**
80
+
81
+ - 数据源:入站 C2C 消息的 `attachments`(`content_type` / `url` / `filename` / `size`)。
82
+ - 扩展下载图片 → 校验类型(jpg / jpeg / png / webp / gif)与大小 → 转 `ImageContent`(base64 + mimeType)→ 与消息文本一起 `pi.sendUserMessage()`。
83
+ - 类型判断:`content_type` 优先(兼容 `image/jpg`),非图片类型时按文件名扩展名兜底;明确声明为不支持的 `image/*`(如 svg)直接拒绝。
84
+ - 下载约束:单张超时 15s;`imageMaxSize` 默认 10MB;先看附件元数据,再在流式读取时二次限制实际字节数。
85
+ - 一条消息多张图片时按原顺序处理;部分失败时成功的图片仍注入,并回一条失败清单。
86
+ - 全部失败且没有文字/文件 → 不注入 pi,只回失败提示;有文字或文件 → 仍注入并提示图片失败。
87
+ - 当前模型无视觉能力(`ctx.model.input` 不含 `image`)时,QQ 提示并跳过图片;文字/文件仍处理。
88
+ - 已确认:pi 不向 QQ 发送图片——LLM 只能输出纯文本,无图片生成场景。
89
+
90
+ **文件行为**
91
+
92
+ - 非图片附件(如 zip/pdf/doc)下载后保存到当前工作空间的 `.pi/pi-qq/YYYY-MM-DD/<msgId>/<安全文件名>`。
93
+ - 文件名去掉路径与非法字符;同名文件自动加 `-1`、`-2` 后缀;不会写出保存目录。
94
+ - 单文件超时 60s;`fileMaxSize` 默认 50MB;同样先看元数据,再在流式读取时二次限流。
95
+ - 一条消息多个文件按原顺序保存;部分失败时成功的文件仍保留并给出失败清单。
96
+ - 提示词中追加文件块,例如:
97
+ ```text
98
+ User sent the following file(s) via QQ (saved locally; use read/bash or other tools to access):
99
+ - /home/chen/project/myproj/.pi/pi-qq/2026-10-29/xxx/report.pdf (1.4MB, original name: report.pdf)
100
+
101
+ User message:
102
+ 帮我总结这个文件
103
+ ```
104
+ - 纯文件消息(无文字)也会触发 run,提示词只含文件块;文件内容不直接注入 LLM,由 pi 用工具按需读取。
105
+
106
+ ### F4 回传 assistant 消息
107
+
108
+ **目标**:pi 的回复实时出现在 QQ 聊天里。
109
+
110
+ **行为**
111
+
112
+ - 数据源:`message_end`(`message.role === "assistant"`)。回复通常为 **Markdown 格式**的总结/提问文本(已确认:LLM 编码完成后不在回复中写代码)。
113
+ - 内容处理:
114
+ - 始终剔除 `thinking` 块(已确认:不回传思考内容)。
115
+ - **Markdown 转换**:
116
+ - 默认(无 markdown 权限,`markdownSupport: false`):轻量转纯文本——去掉 `**` / `*` / `` ` `` 等强调与行内代码标记、标题转为文本行、列表项转 `•`、链接转 `文字(url)`、表格等复杂结构逐行退化;保持手机端可读性。
117
+ - 机器人有 markdown 权限(`markdownSupport: true`)→ 透传原始 Markdown 由 QQ 客户端渲染。QQBot 构造时已传入 `markdownSupport`,SDK 的 `sendText` 会自动使用 msg_type=2,无需额外 `sendMarkdown`。
118
+ - 超长文本按单条上限自动分块(SDK `TEXT_CHUNK_LIMIT = 5000`)。
119
+ - **流式模式**(默认开启,C2C 专属):
120
+ - `message_update` 期间用 `bot.openStream({ target })` 持续 `update(全文)`(对累积全文实时做同样的转换);`message_end` 时 `complete()`。
121
+ - 遵守 SDK 约束:节流 ≥300ms、必须基于 5 分钟内的入站消息(`msgId`)、传全文非增量。
122
+ - **非流式/降级**:`sendText` 一次性发送。
123
+ - `stopReason === "error"` 时回传错误摘要而非静默。
124
+
125
+ ### F5 回传 token 详情(输入 / 输出 / 缓存命中率)
126
+
127
+ **数据源**:本次 agent run 的 `event.messages` 中 assistant 与 toolResult 的 `usage`(`input`、`cacheRead`、`cacheWrite`、`output`)。
128
+
129
+ **行为**
130
+
131
+ - 每次 **QQ 触发且成功完成**的 agent run 结束(`agent_end`)发送一条严格三行摘要(本地终端 run、错误/中止的 run 不发,避免消耗主动额度或重试刷屏):
132
+
133
+ ```
134
+ 📊 用量摘要
135
+ • 输入:4.1k (99.9%)
136
+ • 输出:2.3k
137
+ • 上下文:0.4%
138
+ ```
139
+
140
+ - **输入** = 本次 run 累计总输入(`input + cacheRead + cacheWrite`)。
141
+ - **括号百分比** = 本次 run 累计缓存命中率(`cacheRead / 总输入`),保留一位小数;无缓存时显示 `0.0%`。
142
+ - **输出** = 本次 run 累计输出。
143
+ - 不展示成本、本轮、上下文绝对值;严格保持三行。
144
+ - 与 F6 合并为一条消息发送,避免刷屏。
145
+
146
+ ### F6 回传上下文窗口占比
147
+
148
+ **数据源**:`ctx.getContextUsage()` → `{ tokens, contextWindow, percent }`。
149
+
150
+ **行为**
151
+
152
+ - 与 F5 同条消息的第三行:`• 上下文:0.4%`。
153
+ - `tokens === null`(压缩后尚未产生新响应)时显示 `重建中`。
154
+ - `percent` 缺失时按 `tokens / contextWindow` 计算。
155
+ - 严格三行格式,不追加 `/compact` 文字提示(百分比已可见)。
156
+
157
+ ### F7 长任务反馈(10~60 分钟级任务)
158
+
159
+ **目标**:工具阶段长达数十分钟时保持"活着"的感知,且不烧穿消息额度。
160
+
161
+ **行为**:**assistant 文本消息与思考/工具汇总使用独立气泡**——每条文本消息独占一个纯文本气泡(同一消息的流式增量续写),思考/工具行组进入活动气泡;文本前后的工具执行均另起活动气泡;最终回复独立成文本气泡。`streamRelay` 默认开,实测可用;气泡内按 `streamFlushMs`(默认 10000ms,最小 300)固定频率发送窗口汇总帧(工具调用每 10s 汇总一次):
162
+
163
+ ```
164
+ [活动气泡] 💭 思考中...
165
+ [活动气泡] [3] 🔧 bash
166
+ [活动气泡] [2] 🔧 read
167
+
168
+ [文本气泡] 中间消息原文
169
+
170
+ [活动气泡] [1] 🔧 edit
171
+
172
+ [文本气泡] 最终回复原文(流式增量)
173
+ ```
174
+
175
+ - **汇总帧内容**(窗口增量,间隔 `streamFlushMs` 默认 10000ms;`agent_end` 补发剩余并收 DONE)。活动气泡帧:**行组帧首行带时间戳 `[HH:MM:SS]`**,行组**严格按事件实际发生顺序**输出:思考状态行(惰性)与工具计数行 `[n] 🔧 name` 按到达顺序交错;连续同名工具合并为一条计数,不改变相对顺序。文本气泡帧:原始 Markdown 增量(流式帧按 markdown 渲染),不加时间戳以免插断回答。工具总在 message_end 后执行,故文本消息与其后工具天然分入不同气泡。
176
+ - **排版规则**:活动气泡内行与行相邻不空行;文本气泡内续写直接拼接;文本与工具不再混排。
177
+ - **气泡边界**:文本消息的**首个增量**到达 → 封口当前活动气泡,开文本气泡;思考/工具行组到达 → 封口当前文本气泡,开或续活动气泡;同一消息的后续流式增量不切泡;最终回复独立成文本气泡。
178
+ - **事件映射**:`tool_execution_start` → 窗口计数;`message_update`(thinking/text)→ 窗口状态/快照;`message_end` → 文本定稿;`agent_end` → 补帧 + DONE。AppendStream 内部仍有 500ms 节流与限流退避作安全网。
179
+ - **额度提示**:每条文本消息、每段活动各占一条 msg_seq 消息;长回合任务的气泡数多于单气泡模式,需关注被动额度;若平台拒绝(帧失败),该回合自动降级消息路径,文本仍完整送达。
180
+ - **降级**:任何一帧失败即标 dead,已追加部分作废,未发出的结果文本自动转消息路径补发;`streamRelay: false` 时整条时间线关闭,assistant 消息走普通消息路径(M2 行为)。
181
+ - **typing 保鲜**:run 开始立即发送"正在输入",之后每 50s 续期(0 额度),`agent_end` 清理。
182
+ - **空窗口活性线**:窗口无增量且静默 ≥60s 时补一条 `[HH:MM:SS] ⏱ 已运行 X 分钟…`——长思考/单工具长执行期间每分钟一行,不再无推送(时间戳可用于核对节奏)。
183
+ - **心跳兜底**:流不可用时降级为普通消息心跳(每 run ≤3 条保险丝,带时间戳)。
184
+ - 不发送"已收到"开始确认(节省被动额度):QQ 触发的 run 在首个汇总帧前保持安静。
185
+ - 非 QQ 触发的 run(本地终端)不发心跳/时间线,但 assistant 消息仍照常回传(现状)。
186
+
187
+ ## 3. 平台限制与回传预算(关键约束)
188
+
189
+ QQ 开放平台的发送限制直接决定回传策略,必须统一管理:
190
+
191
+ | 限制 | 数值 | 应对 |
192
+ | --- | --- | --- |
193
+ | 被动回复额度 | 每条入站消息 5 分钟内有效,约 4 条/小时 | 扩展内维护回复预算(复用 SDK `ReplyLimiter` 思路);assistant 时间线按文本/活动分泡,用量摘要合并为 1 条 |
194
+ | 主动消息 | 无 `msgId` 发送受平台额度限制 | 被动额度耗尽时才降级为主动发送,且给出明确提示 |
195
+ | 流式消息 | 仅 C2C;节流 ≥300ms;基于 5 分钟内 `msgId` | 流式仅用于 assistant 文本;无关联 `msgId` 时自动降级 `sendText` |
196
+ | 文本长度 | 单条 ~5000 字符 | SDK 分块;超出部分按序发送 |
197
+ | markdown | 默认无权限(`markdownSupport: false`) | Markdown → 纯文本降级渲染 |
198
+
199
+ **合并规则**(默认):assistant 文本消息与活动时间线严格分泡(每条文本消息 1 条纯文本气泡,工具间隔另起活动气泡);token 详情 + 上下文占比在 `agent_end` 合并为 1 条"用量摘要"发送。气泡数随回合内文本消息数增长,需关注 `msgId` 的被动额度;若平台拒绝(帧失败),自动降级消息路径。工具调用过程本身不逐条回传。
200
+
201
+ ## 4. 配置
202
+
203
+ `~/.pi/agent/pi-qq.json`(只保存设置;不含凭据、不写入登录信息):
204
+
205
+ | 字段 | 默认 | 说明 |
206
+ | --- | --- | --- |
207
+ | `streamAssistant` | `true` | assistant 流式回传开关 |
208
+ | `markdownSupport` | `false` | 机器人是否有 markdown 权限;`true` 时回传透传 Markdown |
209
+ | `usageRelay` | `true` | 本次 run 的 token/缓存命中率/上下文占比摘要开关 |
210
+ | `deliverAs` | `"steer"` | 忙碌时新消息的处理方式 |
211
+ | `imageMaxSize` | `10MB` | QQ 图片下载上限 |
212
+ | `fileMaxSize` | `50MB` | QQ 文件下载上限 |
213
+ | `heartbeatMinutes` | `10`(0 关闭) | F7 节流心跳间隔 |
214
+ | `heartbeatMaxMessages` | `3` | F7 每 run 消息心跳上限(流式心跳不受限) |
215
+ | `streamRelay` | `true` | F7 流式载体开关(append 追加 + 节流合帧 + 限流退避,实测可用;失败自动降级消息路径) |
216
+ | `streamFlushMs` | `10000`(最小 300) | F7 流式汇总帧间隔(毫秒,默认每 10s 汇总工具调用) |
217
+ | `debug` | `false` | 诊断模式:SDK 日志转终端 + 流式限流重试/超时日志 + 文本增量帧时间戳 |
218
+
219
+ ## 5. 命令总表
220
+
221
+ | 位置 | 命令 | 行为 |
222
+ | --- | --- | --- |
223
+ | pi 侧 | `/qq-login` | 扫码登录并绑定(QR only) |
224
+ | pi 侧 | `/qq-status` | 登录态、连接状态、绑定用户 |
225
+ | pi 侧 | `/qq-budget` | 诊断:被动额度、流式气泡数、最近 msgId 新鲜度 |
226
+ | pi 侧 | `/qq-logout` | 清除内存凭据并断开 |
227
+ | pi 侧 | `/qq-new` | 重置当前会话(QQ `/new` 调用) |
228
+ | pi 侧 | `/qq-md [text]` | 诊断:发送 Markdown 消息,验证 C2C markdown 渲染能力 |
229
+ | pi 侧 | `/qq-stream-test` | 诊断:开流→三帧→complete,验证流式帧是否渲染 |
230
+ | QQ 侧 | `/new` `/stop` `/compact` `/status` `/help` | 会话控制(见 F2) |
231
+
232
+ ## 6. 可靠性与安全
233
+
234
+ - **生命周期**:`session_start` 仅在进程内存有登录态时启动;`session_shutdown` 幂等关闭。SDK 默认无限重连(退避 1s→60s),4914/4915 致命关闭码上报为不可恢复,提示重新 `/qq-login`。
235
+ - **回声与去重**:启用 SDK `messageFilter`(跳过 bot 回声)与 `concurrencyGuard`(同用户串行),避免流式与回复互相踩踏。
236
+ - **安全**:
237
+ - 凭据仅保存在进程内存、不落盘;日志与 `/qq-status` 脱敏;扩展以 pi 同等权限运行,白名单外的消息不进入 pi(不产生任何工具执行)。
238
+ - QQ 侧无 shell 类命令;一切工具执行都经由 pi 自身权限体系。
239
+
240
+ ## 7. 决策记录
241
+
242
+ | # | 问题 | 决策 |
243
+ | --- | --- | --- |
244
+ | 1 | TUI 二维码渲染 | 登录协议用 connector;展示用 `qrcode-terminal`(零依赖)在 `ctx.ui` 弹窗画码 |
245
+ | 2 | thinking 内容 | 不回传具体内容(始终剔除,无配置开关);F7 时间线中仅以"💭 思考中…"标记体现 |
246
+ | 3 | tool 消息 | **完全不回传**(从功能范围移除;只回传 assistant 消息 + token usage + 上下文占比) |
247
+ | 4 | 图片方向 | F3 为 QQ → pi(用户发图给 pi);pi 不向 QQ 发图片(LLM 仅输出纯文本) |
248
+ | 5 | 成本展示 | 不在 QQ 摘要中展示成本;摘要严格三行(输入/缓存命中率、输出、上下文) |
249
+ | 6 | 回复格式 | 回复通常为 Markdown 格式的总结/提问文本(不在回复中写代码);默认轻量转纯文本,有 markdown 权限可透传 |
250
+ | 7 | 登录方式 | 仅 `/qq-login` 扫码;凭据只存进程内存、不落盘;pi 进程退出后必须重新扫码 |
251
+ | 8 | 长任务反馈 | typing 保鲜 + 每 10s 汇总工具调用 + 节流心跳(默认 10 分钟/条,流式载体优先,每 run ≤3 条消息心跳保险丝)+ 机会性流式(平台拒绝即降级);不发送开始确认 |
252
+ | 9 | 流式可用性(实测三轮) | ① C2C markdown(msg_type=2,`sendMarkdown`)渲染正常;② SDK 内置流式 `input_mode="replace"` 被平台拒绝("已经提交的消息内容不可修改"),首帧可渲染、后续帧报错;③ 自实现 `AppendStream`(input_mode="append",增量追加 + DONE)实测通过;补齐节流合帧(500ms)与限流退避重试后**默认开启**,失败自动降级消息路径 |
253
+
254
+ ## 8. 里程碑
255
+
256
+ | 阶段 | 内容 | 验收 |
257
+ | --- | --- | --- |
258
+ | M1 | F1 扫码登录 + 内存凭据 + 连接启动 | 扫码后 `/qq-status` 在线;重启 pi 需重新扫码 |
259
+ | M2 | F2 单人聊天 + F4 assistant 回传(先非流式) | QQ 发消息得到 pi 回复 |
260
+ | M3 | F5/F6 用量摘要(本次 run 输入/缓存命中率/输出/上下文) | 严格三行摘要正确呈现 |
261
+ | M4 | F3 QQ 图片/文件消息 + markdownSupport + 打磨 | 图片可进入 pi 会话;文件保存并关联到提示词 |
package/doc/plan.md ADDED
@@ -0,0 +1,195 @@
1
+ # pi-qq — plan.md
2
+
3
+ > 执行计划。功能范围与决策见 [features.md](./features.md),本文只回答:装什么、建什么文件、按什么顺序做、每步怎么验收。
4
+
5
+ ## 0. 前置:依赖安装(需你手动执行)
6
+
7
+ 按约定不由我安装。在项目目录执行:
8
+
9
+ ```bash
10
+ cd /home/chen/project/pi-qq
11
+ npm init -y
12
+ npm i @tencent-connect/qqbot-nodejs @tencent-connect/qqbot-connector qrcode-terminal
13
+ ```
14
+
15
+ | 包 | 版本锚点 | 用途 |
16
+ | --- | --- | --- |
17
+ | `@tencent-connect/qqbot-nodejs` | ^1.0.5 | QQ 协议层(本地另有源码 `/home/chen/project/qqbot-nodejs` 可查阅) |
18
+ | `@tencent-connect/qqbot-connector` | ^1.2.0 | 扫码登录(唯一登录方式) |
19
+ | `qrcode-terminal` | ^0.12 | 二维码 ASCII 渲染(零依赖) |
20
+
21
+ 开发加载方式:`pi --extension /home/chen/project/pi-qq`(jiti 直接跑 TS,无需构建)。
22
+
23
+ ## 1. 目录结构与模块划分
24
+
25
+ ```
26
+ pi-qq/
27
+ ├── package.json
28
+ ├── tsconfig.json # 仅编辑器/typecheck 用,无构建
29
+ ├── index.ts # 扩展入口:registerCommand + pi.on 订阅 + 生命周期
30
+ └── src/
31
+ ├── config.ts # ~/.pi/agent/pi-qq.json 只读设置(不含凭据)
32
+ ├── login.ts # F1:仅扫码登录(connector + TUI 二维码弹窗;凭据只返回内存)
33
+ ├── bot.ts # QQBot 实例生命周期:start/stop、中间件装配、重连/致命关闭码上报
34
+ ├── inbound.ts # F2/F3:白名单 → QQ 命令拦截 → 图片/文件附件 → sendUserMessage
35
+ ├── images.ts # F3:图片类型/大小校验、15s 超时下载、ImageContent 组装
36
+ ├── files.ts # F3:文件下载落盘、安全文件名、提示词路径关联
37
+ ├── download.ts # 图片/文件共用:超时与流式大小限制下载
38
+ ├── format.ts # 人类可读字节格式化
39
+ ├── outbound.ts # F4:markdown→纯文本转换、流式(openStream)/降级(sendText)、分块
40
+ ├── reply-budget.ts # §3:被动回复预算(msgId 5min 窗口、4条/h、降级主动发送)
41
+ ├── budget-status.ts # /qq-budget 纯格式化(普通/流式/估算剩余)
42
+ └── usage.ts # F5/F6:本次 run 用量汇总(agent_end messages)、严格三行摘要
43
+ ```
44
+
45
+ 职责边界:`index.ts` 只做装配与订阅,不含业务逻辑;每个模块可独立测试;模块间只经 `index.ts` 传递的共享状态对象(bot 实例、当前 target/msgId、配置)通信。
46
+
47
+ ## 2. pi 事件与 SDK 接线总表
48
+
49
+ | 方向 | 信号 | 处理 |
50
+ | --- | --- | --- |
51
+ | QQ → pi | `bot.on("message")`(kind=c2c) | 白名单 → QQ 命令(`/new` `/stop` `/compact` `/status` `/help`)→ 文本+图片 → `pi.sendUserMessage()` |
52
+ | pi → QQ | `message_update`(assistant) | 流式:`openStream().update(转换后全文)`,节流 ≥300ms |
53
+ | pi → QQ | `message_end`(assistant) | `stream.complete()`;无流上下文时 `sendText`;`stopReason==="error"` 回错误摘要 |
54
+ | pi → QQ | `agent_end` | 用量摘要一条(F5 本次 run token/缓存命中率 + F6 上下文占比) |
55
+ | 状态 | `session_start` / `session_shutdown` | 有内存登录态则启动 bot / 幂等停止 |
56
+ | 汇总 | `agent_end` | 从 `event.messages` 汇总本次 run 的 assistant/toolResult usage |
57
+
58
+ ## 3. 里程碑
59
+
60
+ ### M1 — 登录接入与连接(F1 + bot.ts + config.ts)
61
+
62
+ 1. `package.json`、`tsconfig.json`、目录骨架;`config.ts`:只读 `~/.pi/agent/pi-qq.json` 设置,不读写凭据。
63
+ 2. `bot.ts`:`start/stop`、装配 `messageFilter`(回声过滤)+ `accessPolicy`(白名单)+ `concurrencyGuard`;`ready/disconnected/error` 上报到 `ctx.ui`。
64
+ 3. `login.ts` + `index.ts`:
65
+ - `session_start`:进程内存有登录态则启动;否则提示 `/qq-login`。
66
+ - `/qq-login`:`startQrConnect`(`displayQrCodeToConsole: false`),`onQrDisplayed` 在 TUI 弹窗画二维码(`qrcode-terminal`),`onSuccess` 把凭据与 openid 存入内存并启动。
67
+ - `/qq-status`(内存登录/连接/绑定用户)、`/qq-logout`(清内存凭据)。
68
+
69
+ **验收**:扫码后 `/qq-status` 在线;pi 进程重启后需重新扫码;`4914/4915` 致命关闭码给出明确提示。
70
+
71
+ ### M2 — 单人聊天与完整回复(F2 文本 + F4 非流式 + reply-budget.ts)
72
+
73
+ 1. `inbound.ts`:C2C 白名单过滤、QQ 命令拦截(`/stop`→`ctx.abort()`、`/new`→扩展命令 `qq-new`→`ctx.newSession()`、`/status` 汇总、`/help`)、文本 → `sendUserMessage`;忙碌时 `deliverAs` 排队。
74
+ 2. `outbound.ts` 非流式路径:markdown→纯文本转换函数(独立、可单测:强调/标题/列表/链接/表格退化)+ `TEXT_CHUNK_LIMIT` 分块。
75
+ 3. `reply-budget.ts`:按 `msgId` 记录被动回复次数与 5min 窗口;超限降级主动发送并提示。
76
+
77
+ **验收**:QQ 发"你好"→ QQ 收到 pi 回复(纯文本、无 markdown 记号残留);连续对话额度不炸;非绑定用户发消息无任何反应。
78
+
79
+ ### M2.5 — 长任务反馈包(F7,已拍板)
80
+
81
+ 背景:实际场景 `user_input → thinking+tools(10~60 分钟)→ assistant message`,结果只在末尾出现一次。
82
+
83
+ 1. `src/run-feedback.ts`:run 级状态机 —— QQ 触发标记(pending)、工具名×次数计数(`tool_execution_end`)、流会话(`openStream` 惰性开启:首次心跳或首次文本时尝试,失败标 dead)、typing keepalive 定时器(50s)、节流心跳定时器(默认 10min)、消息心跳保险丝(每 run ≤3)、`agent_end` 收尾(complete/cancel/清 timer)。
84
+ 2. 载体优先级:流式心跳(一条消息持续刷新,0 额度)→ 消息心跳(≤3 条)→ 静默;结果文本在流存活时直接续写同一条流,`message_end` 被流接管时跳过 sendReply(避免双发)。
85
+ 3. `inbound.ts`:不发送开始确认(节省被动额度),仅 `markQQTrigger`。
86
+ 4. `index.ts`:接线 `agent_start` / `agent_end` / `tool_execution_end` / `message_update`。
87
+ 5. `config.ts`:`heartbeatMinutes`(默认 10)、`heartbeatMaxMessages`(默认 3)。
88
+
89
+ **验收**:QQ 发任务 → 不发送确认 → 10s 内收到首个汇总帧 → typing 持续 → 心跳按期到达(流或消息)→ 结果回传不双发。
90
+
91
+ ### M3 — 用量摘要(F5 + F6)
92
+
93
+ 1. `usage.ts`:`agent_end` 从 `event.messages` 汇总本次 run 的 assistant + toolResult usage;上下文取 `ctx.getContextUsage()`(`tokens===null` 显示"重建中")。
94
+ 2. 严格三行格式:`📊 用量摘要` / `• 输入:4.1k (99.9%)` / `• 输出:2.3k` / `• 上下文:0.4%`;输入为总输入(含 cacheRead/cacheWrite),括号为缓存命中率。
95
+ 3. 仅 QQ 触发且成功完成的 run 发送;经 reply-budget 发送。
96
+
97
+ **验收**:每轮对话后 QQ 收到一条三行摘要,数字与本次 run 实际用量一致。
98
+
99
+ ### M4 — 图片与打磨(F3 + markdownSupport 透传)
100
+
101
+ 1. [x] F3 图片/文件:图片转 `ImageContent`;非图片附件保存到当前工作空间的 `.pi/pi-qq/YYYY-MM-DD/<msgId>/`,提示词中追加绝对路径、大小与原始文件名;`fileMaxSize` 默认 50MB。
102
+ 2. [x] `markdownSupport: true`:`QQBot` 构造时已传入该开关,SDK 的 `sendText` 自动使用 msg_type=2;调用方保留原始 Markdown 即可,无需额外 `sendMarkdown`。
103
+ 3. [x] QQ 侧 `/new`:inbound 调用隐藏扩展命令 `qq-new`,命令 handler 使用 `ctx.newSession()`;非 idle 时提示先 `/stop`。
104
+ 4. [ ] 长代码块转文件附件(backlog);多气泡 + 摘要额度实测已完成。
105
+
106
+ **验收**:QQ 发图后 pi 能描述图片内容;QQ 发文件后保存到本机并在提示词中关联路径;额度全程不超限。
107
+
108
+ ## 4. 验证策略
109
+
110
+ - **静态**:`npx tsc --noEmit`(tsconfig 仅类型检查)。
111
+ - **单测**(vitest,纯函数优先):markdown→纯文本转换、分块、reply-budget 状态机、config 读写合并。SDK 与 pi 事件层不做单测,靠 M1–M4 验收手动覆盖。
112
+ - **手动验收**:每个里程碑按上表验收项在真实 QQ 环境跑一遍;`baseUrl` 可指向 mock 验证协议路径(SDK 测试有先例)。
113
+
114
+ ## 5. 风险与预案
115
+
116
+ | 风险 | 影响 | 预案 |
117
+ | --- | --- | --- |
118
+ | 流式消息对非 C2C/过期 `msgId` 抛错 | 流式路径崩溃 | `openStream` 前置校验,失败即降级 `sendText`(M4 已含) |
119
+ | 被动额度耗尽(长 run 多回复) | 消息发不出去 | reply-budget 统一发牌,超限降级主动+提示;摘要固定合并 |
120
+ | markdown 转换漏判 | QQ 端残留记号 | 转换函数单测覆盖常见结构;允许透传开关兜底 |
121
+ | connector 混淆代码异常 / 扫码接口变更 | 无法登录 | 重试扫码;升级 connector;保留日志排查 |
122
+ | pi 事件在非 TUI 模式无 UI | 扩展报错 | 所有 `ctx.ui` 调用前判 `ctx.hasUI`/`ctx.mode` |
123
+
124
+ ## 6. Todo-List(随进度勾选)
125
+
126
+ ### 准备
127
+
128
+ - [x] 依赖安装:`@tencent-connect/qqbot-nodejs` + `@tencent-connect/qqbot-connector` + `qrcode-terminal`(用户已执行)
129
+ - [x] pi / SDK / connector API 签名核对(types.d.ts + 本地源码)
130
+ - [x] `package.json` 完善(`type: module`、description;发布时移除 private)
131
+ - [x] `tsconfig.json`(`moduleResolution: bundler`;`paths` 借用 pi 发行目录类型 + `typeRoots` 借用其 @types/node,typecheck 走 `npx typescript`,无需安装 devDeps)
132
+
133
+ ### M1 — 登录接入与连接
134
+
135
+ - [x] `src/config.ts`:`~/.pi/agent/pi-qq.json` 只读设置(不含凭据)
136
+ - [x] `src/bot.ts`:`createBot/start/stop`、中间件装配(messageFilter/accessPolicy/concurrencyGuard)、连接状态跟踪、致命关闭码上报
137
+ - [x] `src/login.ts`:仅扫码 `startQrConnect`(含二维码展示与取消;凭据返回内存)
138
+ - [x] `index.ts`:`/qq-login` `/qq-status` `/qq-logout` 命令 + 内存登录态 + `session_start` 接入 + `session_shutdown` 幂等停止
139
+ - [x] 验收:扫码在线 / pi 重启后重新扫码 / `4914` `4915` 明确提示(扫码路径已实测;`4914/4915` 如未触发可在后续观察)
140
+
141
+ ### M2 — 单人聊天与完整回复(非流式)
142
+
143
+ - [x] `src/inbound.ts`:白名单 → QQ 命令拦截(`/new` `/stop` `/compact` `/status` `/help`)→ 文本 `sendUserMessage` + `deliverAs` 排队
144
+ - [x] `src/outbound.ts`:markdown→纯文本转换(独立可单测)+ `TEXT_CHUNK_LIMIT` 分块
145
+ - [x] `src/reply-budget.ts`:被动回复预算(5min 窗口 / 4条每小时)+ 降级主动发送
146
+ - [x] `message_end`(assistant)非流式回传接线 + `stopReason==="error"` 错误摘要
147
+ - [x] 单测:markdown 转换 / 分块 / reply-budget(jiti + assert 脚本 `test/run.ts`,30 项断言;config 12 项在 M1 已验)
148
+ - [x] 验收:QQ 发消息→收到纯文本回复;非绑定用户无反应;额度不超限(用户实测通过)
149
+
150
+ ### M2.5 — 长任务反馈包
151
+
152
+ - [x] `src/run-feedback.ts`:run 级状态机(QQ 触发标记、工具计数、流会话惰性开启、typing/心跳定时器、消息心跳保险丝)+ `formatHeartbeat`
153
+ - [x] `config.ts`:`heartbeatMinutes` / `heartbeatMaxMessages`
154
+ - [x] `inbound.ts`:`markQQTrigger`(不发送开始确认,2026-10-29 调整)
155
+ - [x] `index.ts`:`agent_start`/`agent_end`/`tool_execution_end`/`message_update` 接线;`message_end` 流接管判定
156
+ - [x] 单测:`formatHeartbeat`(test/run.ts 共 33 项断言)
157
+ - [x] 验收:QQ 发任务 → 不发送确认 → 10s 内收到汇总帧 → typing 持续 → 心跳按期 → 结果回传不双发(用户实测通过)
158
+ - 首轮实测(2026-10-28):确认/typing 正常;SDK 内置流式 replace 语义被平台拒绝("已经提交的消息内容不可修改",首帧可渲染、第二帧报错);C2C markdown 渲染正常(`/qq-md` ✓)。
159
+ - 修复:自实现 `src/append-stream.ts`(input_mode="append",追加语义),RunFeedback 改为增量追加,`/qq-stream-test` 改测 append 模式。
160
+ - 复验(2026-10-28):append 两帧 + DONE 全部渲染 ✓,流式链路打通。后续任务:心跳/结果追加需开启 `streamRelay: true`。
161
+ - 时间线升级(用户构想):流式气泡改为**回合活动时间线**——💭 思考中…(惰性标记,不回传内容)/ 🔧 工具名(tool_execution_start)/ 智能体消息原文(流式增量)依次追加,心跳与 DONE 照旧;帧失败自动降级消息路径并补发未发结果。
162
+ - 汇总帧重构(用户构想):逐事件追加改为**固定 3s 窗口汇总帧**——思考状态行 + 工具计数行(`[n] 🔧 name`)+ 消息文本增量,按设计稿分组排版;流式帧按 markdown 渲染(实测),故流内传原始文本。用户实测反馈:长思考/长工具期间静默——已加行组帧时间戳 + 空窗口 60s 活性行 + flush 队列串行化(防限流重试与定时器交错)。追加 debug 开关(SDK 日志转终端 + 文本帧时间戳)用于定位用户报告的「超时」现象。
163
+ - 回合独立气泡(用户反馈:内容全压一条气泡太挤):切分规则改为**每条带文本的 assistant 消息一个气泡**(首版按 message_start 切分产生大量迷你气泡——该模型每轮工具调用都发独立小消息,且 onToolStart 立即行与汇总帧双份报告)。文本驱动边界:新文本 + 当前气泡已含文本 → 封口开新泡;工具并入当前气泡。
164
+ - 二轮实测(2026-10-28,jsonl 事件时间线 vs 气泡时间戳):3s 汇总节奏准确(事件→帧延迟 0~3s)、无重复、91s 静默区活性行准时(60s 阈值)、markdown 渲染正常。M2.5 全部验收通过。首轮长任务实测三问题:① flushWindow 丢失 resultSentLen 推进导致累计文本重复重发(已修,帧内推进基准);② 心跳/汇总行补回 💭/🔧 图标;③ 帧节奏实为 3s,观感问题由①导致。
165
+ - 三轮实测(2026-10-29,用户 QQ 截图 + 会话日志):最终回复被追加 3 份,且最后一个气泡一直停留在“生成中”。根因是 `f806065` 重构丢失两处关键逻辑:① 成功追加文本后未推进 `resultSentLen`,每 3s 汇总帧重发全文;② `sealBubble` 在 `flushWindow` 前捕获旧 `cur`,切泡后新气泡收不到 DONE。修复:追加成功即推进基准;气泡边界仅在上一条文本消息定稿后触发(同消息的流式增量不再切泡);`sealBubble` 在 flush 后重读 `cur`;错误路径先封口再走消息链路。新增重复/单气泡/双气泡/错误 DONE 回归断言。
166
+ - 四轮实测(2026-10-29,`log/pi.jsonl` + `log/qq.png`):首条中间文本(工具活动之后的 assistant 消息)被并入活动气泡,未独立成泡。根因:切泡条件要求旧气泡已含文本,而首条文本之前只有思考/工具行组。修复:文本消息首个增量到达时,只要当前气泡已有内容就封口(含仅行组);工具计数行格式改为 `[n] 🔧 name`(心跳同步),新增活动气泡→文本气泡回归断言。
167
+ - 五轮调整(2026-10-29,用户要求):删除 t=0 的"✅ 已收到"开始确认(含忙碌合并提示),节省被动额度;汇总帧默认间隔 3000ms → 10000ms,工具调用每 10s 汇总一次(`streamFlushMs` 仍可配置)。
168
+ - 六轮调整(2026-10-29,用户 QQ 截图):中间文本消息与工具汇总混在同一气泡(如“已写入…”后紧跟 read 行)。改为**文本/活动严格分泡**:每条 assistant 文本独占纯文本气泡,思考/工具行组进活动气泡,文本前后的工具均另起活动气泡;新增“活动→文本→活动→文本→活动→最终文本”六气泡交错回归断言。
169
+ - 七轮自检(2026-10-29,`log/pi.png` + `log/qq.png`):用量摘要与 pi Session Info 完全一致(输入 14.3k/缓存 92.8%、输出 1.1k、上下文 0.4%)。发现无文本 assistant 消息不走 `onAssistantFinal`,逐消息思考标记未重置,导致下一条消息的 thinking 行被吞(截图中 read 前缺 thinking)。修复:`message_end` 对无文本 assistant 也调用 `onAssistantFinal("")`,冲刷行组并重置逐消息状态;新增“无文本消息不吞后续行组”回归断言。
170
+ - 八轮调整(2026-10-29,重跑截图):read 与下一条消息的 thinking 落入同一 10s 窗口时,旧逻辑固定“thinking 优先”,显示顺序与真实事件相反(应 read → thinking → bash)。修复:窗口行组改为 `winLines` 事件序列,按事件到达顺序输出;连续同名工具合并计数;新增严格顺序回归断言。
171
+
172
+ ### M3 — 用量摘要
173
+
174
+ - [x] `src/usage.ts`:`agent_end` 从 `event.messages` 汇总本次 run(assistant + toolResult 嵌套 usage)
175
+ - [x] 严格三行摘要:输入(总输入)+ 缓存命中率、输出、上下文占比;`tokens===null` 显示重建中
176
+ - [x] 仅 QQ 触发且成功完成的 run 发送;经 reply-budget 发送
177
+ - [ ] 验收(待 QQ 实测):摘要数字与本次 run 实际用量一致
178
+ - 2026-10-29:单测覆盖严格三行/命中率/无缓存/重建中/上下文计算/本次 run 汇总/无文本消息行组/图片类型与大小校验/QQ /new 分发/预算快照/流式气泡计数/文件保存与提示词(vitest:8 个测试文件 / 81 个测试通过)。
179
+
180
+ ### M4 — 图片与打磨
181
+
182
+ - [x] F3 图片/文件:图片注入;文件落盘 + 提示词路径关联 + `fileMaxSize`
183
+ - [x] 流式接线(M2.5 已完成,`AppendStream` + 文本/活动分泡)
184
+ - [x] `/compact` 命令、typing 指示(C2C)
185
+ - [x] `markdownSupport: true`:SDK `sendText` 自动 msg_type=2(无需新增 sendMarkdown 路径)
186
+ - [x] QQ 侧 `/new` 支持(`qq-new` 扩展命令 → `ctx.newSession()`)
187
+ - [x] `/qq-budget` 诊断命令(普通被动剩余 / 流式气泡数 / 估算剩余 / 最近 msgId 新鲜度)
188
+ - [x] 单元测试迁移到 vitest(`test/*.test.ts`,8 个文件 / 81 个测试;`npm test`)
189
+ - [ ] 长代码块转文件附件(backlog,暂缓)
190
+ - [x] 多气泡 + 摘要下的被动额度实测(2026-10-29:`/qq-budget` 实测符合预期:4 个流式气泡 + 1 条摘要,普通剩余 3 / 估算剩余 0 / 窗口有效)
191
+ - [x] `debug` 抓超时日志:AppendStream 限流重试/最终失败 + run start/end 日志
192
+ - [x] 验收:QQ 发图后 pi 能描述图片内容;全程额度不超限(2026-10-29 实测通过)
193
+ - [ ] 文件传输实机验收(QQ 发 zip/pdf 等,确认保存路径与提示词关联)
194
+ - 2026-10-29:图片+文字、纯图片(均被模型正确识别)、非图片附件拒绝(zip 提示“附件处理失败”)、多气泡+摘要额度诊断已实测通过。
195
+ - 无视觉模型场景按用户决定不验证(代码仍保留 `ctx.model.input` 检查)。