@chen_hu_hu/pi-qq 1.2.2 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README-zh.md +48 -24
- package/README.md +40 -16
- package/doc/delivery-v1-zh.md +160 -0
- package/doc/delivery-v1.md +160 -0
- package/doc/delivery-v2-zh.md +100 -0
- package/doc/delivery-v2.md +98 -0
- package/doc/delivery-v3-zh.md +187 -0
- package/doc/delivery-v3.md +187 -0
- package/index.ts +71 -66
- package/package.json +8 -2
- package/src/{download.ts → attachments/attachment-download.ts} +2 -5
- package/src/{files.ts → attachments/file-attachments.ts} +4 -15
- package/src/{images.ts → attachments/image-attachments.ts} +3 -10
- package/src/{voice.ts → attachments/voice-transcript.ts} +1 -7
- package/src/{format.ts → infra/display-format.ts} +0 -2
- package/src/{logger.ts → infra/file-logger.ts} +6 -28
- package/src/infra/settings.ts +49 -0
- package/src/{bot.ts → qq/qq-bot.ts} +4 -29
- package/src/{inbound.ts → qq/qq-message-handler.ts} +10 -23
- package/src/{login.ts → qq/qr-login.ts} +20 -16
- package/src/{outbound.ts → qq/reply-sender.ts} +3 -34
- package/src/qrcode-terminal.d.ts +0 -2
- package/src/{budget-status.ts → quota/reply-quota-report.ts} +2 -3
- package/src/{reply-budget.ts → quota/reply-quota.ts} +0 -21
- package/src/relay/run-stream-relay.ts +586 -0
- package/src/relay/stream-block-format.ts +114 -0
- package/src/{append-stream.ts → relay/stream-session.ts} +46 -29
- package/doc/features-v1.md +0 -239
- package/doc/features-v2.md +0 -210
- package/doc/plan-v1.md +0 -190
- package/doc/plan-v2.md +0 -332
- package/src/config.ts +0 -82
- package/src/run-feedback.ts +0 -410
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# pi-qq delivery-v2
|
|
2
|
+
|
|
3
|
+
> Status: v2 delivered.
|
|
4
|
+
> Previous: [delivery-v1.md](./delivery-v1.md); next: [delivery-v3.md](./delivery-v3.md).
|
|
5
|
+
|
|
6
|
+
## 1. Scope
|
|
7
|
+
|
|
8
|
+
v2 adds to v1's QQ chat, image, and file support:
|
|
9
|
+
|
|
10
|
+
- F8 voice-message transcription;
|
|
11
|
+
- F9 structured logging;
|
|
12
|
+
- F10 file-only messages waiting for the next instruction;
|
|
13
|
+
- F11 upload paths, index, and deduplication.
|
|
14
|
+
|
|
15
|
+
## 2. Features
|
|
16
|
+
|
|
17
|
+
### F8 Voice messages
|
|
18
|
+
|
|
19
|
+
- Use QQ built-in ASR (`asr_refer_text`); never download the audio.
|
|
20
|
+
- Send the transcript to pi as ordinary user text.
|
|
21
|
+
- If ASR returns no text, reply `Could not transcribe this voice message; please resend or type it.` and do not start a run.
|
|
22
|
+
- No local or external speech-to-text service is used.
|
|
23
|
+
- Raw ASR results and attachment metadata are only written at `debug` level.
|
|
24
|
+
|
|
25
|
+
### F9 Logging
|
|
26
|
+
|
|
27
|
+
- Write daily files to `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`.
|
|
28
|
+
- `PI_QQ_LOG_DIR` can override the directory.
|
|
29
|
+
- Thresholds: `silent`, `error`, `warn`, `info`, `debug`.
|
|
30
|
+
- `info` records metadata only; `debug` records full events, attachments, prompts, and tool payloads.
|
|
31
|
+
- Logs are JSONL; errors include name, message, and stack.
|
|
32
|
+
- Legacy `debug: true` maps to `logLevel: "debug"`.
|
|
33
|
+
|
|
34
|
+
### F10 File-only messages
|
|
35
|
+
|
|
36
|
+
- A file-only message does not start pi; the file is saved and becomes pending.
|
|
37
|
+
- The next text or voice instruction consumes pending files and includes paths, sizes, and original filenames in the prompt.
|
|
38
|
+
- Multiple files uploaded before an instruction are merged into one prompt.
|
|
39
|
+
- `/new` clears pending files.
|
|
40
|
+
- Pending files are scoped to the current pi session.
|
|
41
|
+
|
|
42
|
+
### F11 Upload storage and deduplication
|
|
43
|
+
|
|
44
|
+
- Saved under the current workspace at `.pi/pi-qq/<sessionId>/uploads/`.
|
|
45
|
+
- Same name and same content reuses the existing file.
|
|
46
|
+
- Same name and different content is saved as `name-1.ext`.
|
|
47
|
+
- Different names with identical content are saved separately.
|
|
48
|
+
- The index records path, size, hash, and original filename; stale entries are pruned on startup.
|
|
49
|
+
- Pending files are independent from the index; `/new` does not delete saved indexed files.
|
|
50
|
+
|
|
51
|
+
## 3. Settings
|
|
52
|
+
|
|
53
|
+
| Setting | Default | Description |
|
|
54
|
+
| --------------- | -------------- | --------------------------- |
|
|
55
|
+
| `thinkingRelay` | `true` | Relay thinking text |
|
|
56
|
+
| `deliverAs` | `"steer"` | Queue behavior while busy |
|
|
57
|
+
| `imageMaxSize` | 10MB | Image download limit |
|
|
58
|
+
| `fileMaxSize` | 50MB | File download limit |
|
|
59
|
+
| `logLevel` | `"silent"` | Log threshold |
|
|
60
|
+
| `debug` | migration only | Legacy log switch migration |
|
|
61
|
+
|
|
62
|
+
## 4. Modules and boundaries
|
|
63
|
+
|
|
64
|
+
<!-- prettier-ignore -->
|
|
65
|
+
| Module | Responsibility |
|
|
66
|
+
| ---------------------------- | ------------------------------------------------------------- |
|
|
67
|
+
| `src/qq/qq-message-handler.ts` | Unified voice/file/text inbound routing; command interception |
|
|
68
|
+
| `src/attachments/voice-transcript.ts` | ASR text extraction and availability |
|
|
69
|
+
| `src/attachments/file-attachments.ts` | File storage, hashes, index, pending-file prompt |
|
|
70
|
+
| `src/attachments/attachment-download.ts` | Shared download limits for images and files |
|
|
71
|
+
| `src/attachments/image-attachments.ts` | Image validation and vision input assembly |
|
|
72
|
+
| `src/infra/file-logger.ts` | Log levels, formatting, daily file output |
|
|
73
|
+
| `src/qq/reply-sender.ts` | Markdown conversion, chunking, sending |
|
|
74
|
+
| `src/quota/reply-quota.ts` | Passive reply quota |
|
|
75
|
+
|
|
76
|
+
Boundary rules:
|
|
77
|
+
|
|
78
|
+
- `qq-message-handler` only routes; it does not implement download or storage details.
|
|
79
|
+
- `voice-transcript` never touches the filesystem.
|
|
80
|
+
- `file-attachments` handles storage and indexing, not pi events.
|
|
81
|
+
- `file-logger` does not depend on business modules.
|
|
82
|
+
- All attachment downloads go through `attachment-download.ts` so timeouts and size limits do not diverge.
|
|
83
|
+
|
|
84
|
+
## 5. Verification
|
|
85
|
+
|
|
86
|
+
- Voice ASR text injection, empty-ASR prompting, and no audio persistence.
|
|
87
|
+
- File-only messages do not start a run; the next instruction consumes the files.
|
|
88
|
+
- Multiple pending files merge; `/new` clears pending files.
|
|
89
|
+
- Same-name/same-content reuse, same-name/different-content suffixing, and different-name/same-content separation.
|
|
90
|
+
- Log directory, levels, JSONL fields, and legacy `debug` migration.
|
|
91
|
+
- Automated tests and real QQ verification passed.
|
|
92
|
+
|
|
93
|
+
## 6. Known limitations
|
|
94
|
+
|
|
95
|
+
- Only QQ ASR is used; there is no local speech-recognition fallback.
|
|
96
|
+
- If ASR returns no text, the user must resend or type the message.
|
|
97
|
+
- Pending files are scoped to the current pi session.
|
|
98
|
+
- `debug` logs can contain sensitive tool payloads and file contents; enable only while troubleshooting.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# pi-qq delivery-v3
|
|
2
|
+
|
|
3
|
+
> 状态:v3 已实现并完成主链路真机验证;按块切泡、错误恢复、列表切分等最终细节仍需在目标 QQ 客户端做一次完整复验。
|
|
4
|
+
> 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md)、[delivery-v2-zh.md](./delivery-v2-zh.md)。
|
|
5
|
+
|
|
6
|
+
## 1. 交付范围
|
|
7
|
+
|
|
8
|
+
v3 收敛长任务回传与配置:
|
|
9
|
+
|
|
10
|
+
- F12:事件直推,思考、工具、文本按块回传;
|
|
11
|
+
- F13:移除消息心跳;
|
|
12
|
+
- F14:配置项收敛。
|
|
13
|
+
|
|
14
|
+
## 2. 输出模型
|
|
15
|
+
|
|
16
|
+
### 2.1 每个内容块一个气泡
|
|
17
|
+
|
|
18
|
+
按时间顺序:
|
|
19
|
+
|
|
20
|
+
1. 思考块;
|
|
21
|
+
2. 每个工具调用 + 结果;
|
|
22
|
+
3. 文本块;
|
|
23
|
+
4. 最终消息。
|
|
24
|
+
|
|
25
|
+
工具未完成时,后续思考/文本暂存,避免思考插入两个工具泡之间。并行工具按开始顺序逐个展示,结果通过 `toolCallId` 归属。
|
|
26
|
+
|
|
27
|
+
### 2.2 思考格式
|
|
28
|
+
|
|
29
|
+
每个思考泡首行:
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
**💭 思考**
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
正文为纯文本,不加 `>` 引用前缀,空行和换行原样保留。达到 12k 安全边界时主动切泡,新泡重复标题。
|
|
36
|
+
|
|
37
|
+
不使用引用块的原因:QQ 会把单行/空行引用块渲染为不支持的消息;纯文本 + 标题可稳定显示。
|
|
38
|
+
|
|
39
|
+
### 2.3 工具格式
|
|
40
|
+
|
|
41
|
+
````text
|
|
42
|
+
**<图标> <工具名>**
|
|
43
|
+
|
|
44
|
+
`参数`
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
输出
|
|
48
|
+
````
|
|
49
|
+
|
|
50
|
+
````
|
|
51
|
+
|
|
52
|
+
失败结果首行:
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
❌ ...
|
|
56
|
+
````
|
|
57
|
+
|
|
58
|
+
每个工具调用独立气泡;工具名、参数和结果不拆开。
|
|
59
|
+
|
|
60
|
+
固定图标映射:
|
|
61
|
+
|
|
62
|
+
| 工具 | 图标 | 工具 | 图标 |
|
|
63
|
+
| -------- | ---- | ---------- | ---- |
|
|
64
|
+
| `bash` | 💻 | `read` | 📖 |
|
|
65
|
+
| `write` | 📝 | `edit` | ✏️ |
|
|
66
|
+
| `grep` | 🔎 | `search` | 🔍 |
|
|
67
|
+
| `find` | 🗂️ | `ls` | 📁 |
|
|
68
|
+
| `list` | 📋 | `web` | 🌐 |
|
|
69
|
+
| `fetch` | 📡 | `delete` | 🗑️ |
|
|
70
|
+
| `remove` | ❌ | `todo` | ✅ |
|
|
71
|
+
| `test` | 🧪 | 未配置工具 | 🔧 |
|
|
72
|
+
|
|
73
|
+
图标硬编码在 `src/relay/stream-block-format.ts`,不增加配置项。
|
|
74
|
+
|
|
75
|
+
### 2.4 文本与普通消息
|
|
76
|
+
|
|
77
|
+
assistant 文本按原文流式追加,不额外加标题。文本块和工具块之间通过气泡边界区分。
|
|
78
|
+
|
|
79
|
+
## 3. 切泡与流式传输
|
|
80
|
+
|
|
81
|
+
- 每个 run 默认多泡,但每个泡只承载一个内容块。
|
|
82
|
+
- 单块累计达到 `MAX_BUBBLE_CHARS = 12_000` 时,在安全边界切泡:
|
|
83
|
+
- 块边界或行首;
|
|
84
|
+
- 没有未闭合代码围栏;
|
|
85
|
+
- 没有待续写检查点;
|
|
86
|
+
- 没有进行中的工具。
|
|
87
|
+
- 思考切泡优先保证列表/行结构,不在行中间强制截断。
|
|
88
|
+
- 工具参数行与结果代码块始终在同一泡。
|
|
89
|
+
- `AppendStream` 负责 300ms 平台下限、500ms 默认合帧、429/50002 退避和同泡续写。
|
|
90
|
+
- `index` 每次发送尝试递增;失败帧的未确认缓冲用下一个 index 重发。
|
|
91
|
+
- 超过 5 分钟或平台拒绝时,最终文本通过普通消息路径补发。
|
|
92
|
+
|
|
93
|
+
## 4. 中断与错误恢复
|
|
94
|
+
|
|
95
|
+
### 4.1 `/stop`
|
|
96
|
+
|
|
97
|
+
`/stop` 的流程:
|
|
98
|
+
|
|
99
|
+
1. 取消错误恢复目标;
|
|
100
|
+
2. abort agent;
|
|
101
|
+
3. 等待 `agent_end` 完成当前流、工具结果和 DONE;
|
|
102
|
+
4. 回复 `Abort requested.`。
|
|
103
|
+
|
|
104
|
+
因此已启动的工具结果不会因为 `/stop` 丢失,也不会在 Abort requested 之后继续冒出排队工具泡。
|
|
105
|
+
|
|
106
|
+
### 4.2 模型错误恢复
|
|
107
|
+
|
|
108
|
+
- 模型错误结束时保留原 QQ 目标 60 秒。
|
|
109
|
+
- pi 自动恢复/重试产生的新 run 会沿用同一 `msgId` 继续推送。
|
|
110
|
+
- 没有输出的空重试不会消耗恢复目标;下一次重试仍可继续。
|
|
111
|
+
- 新 QQ 消息或 `/stop` 取消恢复。
|
|
112
|
+
- 恢复目标内的本地 run 也可能被回传,这是为了延续 pi 自动恢复行为的明确取舍。
|
|
113
|
+
|
|
114
|
+
## 5. 配置
|
|
115
|
+
|
|
116
|
+
`~/.pi/agent/pi-qq.json` 只保存设置,不保存凭据。
|
|
117
|
+
|
|
118
|
+
| 配置 | 默认 | 说明 |
|
|
119
|
+
| --------------- | ---------- | ---------------------------------------- |
|
|
120
|
+
| `thinkingRelay` | `true` | 是否回传纯文本思考块 |
|
|
121
|
+
| `deliverAs` | `"steer"` | 忙碌时新消息排队方式 |
|
|
122
|
+
| `imageMaxSize` | 10MB | 图片下载上限 |
|
|
123
|
+
| `fileMaxSize` | 50MB | 文件下载上限 |
|
|
124
|
+
| `logLevel` | `"silent"` | 日志阈值 |
|
|
125
|
+
| `debug` | 仅迁移读取 | `debug: true` 映射为 `logLevel: "debug"` |
|
|
126
|
+
|
|
127
|
+
已删除配置:`streamRelay`、`streamFlushMs`、`streamAssistant`、`markdownSupport`、`heartbeatMinutes`、`heartbeatMaxMessages`。旧键静默忽略,不写回。
|
|
128
|
+
|
|
129
|
+
## 6. 模块分布与边界
|
|
130
|
+
|
|
131
|
+
当前代码按职责分层:
|
|
132
|
+
|
|
133
|
+
<!-- prettier-ignore -->
|
|
134
|
+
| 模块 | 职责 |
|
|
135
|
+
| ---------------------------- | -------------------------------------------- |
|
|
136
|
+
| `index.ts` | 扩展装配、pi 事件订阅、命令和诊断接线 |
|
|
137
|
+
| `src/qq/qq-message-handler.ts` | QQ 入站路由、命令、附件、注入 pi |
|
|
138
|
+
| `src/qq/reply-sender.ts` | Markdown 转纯文本、分块、消息发送 |
|
|
139
|
+
| `src/relay/run-stream-relay.ts` | 内容块编排、气泡生命周期、工具队列、错误恢复 |
|
|
140
|
+
| `src/relay/stream-block-format.ts` | 思考标题、工具图标、参数/结果纯格式化 |
|
|
141
|
+
| `src/relay/stream-session.ts` | 流式帧、节流、重试、续写检查点 |
|
|
142
|
+
| `src/quota/reply-quota.ts` | 被动回复预算与 `msgId` 窗口 |
|
|
143
|
+
| `src/quota/reply-quota-report.ts` | 预算诊断文本 |
|
|
144
|
+
| `src/infra/settings.ts` | 配置读取与旧键迁移 |
|
|
145
|
+
| `src/qq/qq-bot.ts` | QQBot/Gateway 生命周期和中间件 |
|
|
146
|
+
| `src/qq/qr-login.ts` | 扫码登录 |
|
|
147
|
+
| `src/attachments/file-attachments.ts` | 文件保存、索引、去重、pending |
|
|
148
|
+
| `src/attachments/image-attachments.ts` | 图片校验与视觉输入 |
|
|
149
|
+
| `src/attachments/attachment-download.ts` | 图片/文件通用限流下载 |
|
|
150
|
+
| `src/attachments/voice-transcript.ts` | QQ ASR 文本提取 |
|
|
151
|
+
| `src/infra/file-logger.ts` | 结构化文件日志 |
|
|
152
|
+
| `src/infra/display-format.ts` | 字节/token 通用格式化 |
|
|
153
|
+
|
|
154
|
+
边界原则:
|
|
155
|
+
|
|
156
|
+
- `index.ts` 不承载回传状态机;
|
|
157
|
+
- `stream-block-format.ts` 只做纯格式化,不依赖流对象;
|
|
158
|
+
- `run-stream-relay.ts` 只做编排,不直接拼 Markdown 细节;
|
|
159
|
+
- `stream-session.ts` 不感知内容块语义;
|
|
160
|
+
- `qq-message-handler.ts` 不实现下载、存储或预算;
|
|
161
|
+
- 所有配置通过 `settings.ts`,不散落在业务模块;
|
|
162
|
+
- 每个模块都有独立测试或可从入口注入依赖。
|
|
163
|
+
|
|
164
|
+
## 7. 验证
|
|
165
|
+
|
|
166
|
+
- 单元测试:**135 passed**(14 个测试文件)。
|
|
167
|
+
- TypeScript、ESLint 和 Prettier 检查通过。
|
|
168
|
+
- 真机已验证:
|
|
169
|
+
- C2C 登录、文本、图片、文件;
|
|
170
|
+
- 思考/工具/文本按块展示;
|
|
171
|
+
- 工具行与结果同泡;
|
|
172
|
+
- 12k 切泡与标题重复;
|
|
173
|
+
- `/stop` 收尾、模型错误后的自动恢复。
|
|
174
|
+
- 仍需最终复验:
|
|
175
|
+
- 目标客户端上的长列表切分;
|
|
176
|
+
- 极端长代码围栏;
|
|
177
|
+
- 错误恢复目标 TTL 接近边界的情况;
|
|
178
|
+
- 并行工具较多时的消息额度。
|
|
179
|
+
|
|
180
|
+
## 8. 风险与限制
|
|
181
|
+
|
|
182
|
+
- 每个内容块一泡会增加消息数;长任务需关注被动额度。
|
|
183
|
+
- 12k 切泡依赖状态,极端单行/未闭合围栏仍可能落到平台自动切分。
|
|
184
|
+
- 工具图标是硬编码 Emoji,不同 QQ 客户端字体可能略有差异。
|
|
185
|
+
- 恢复目标是 60 秒 TTL;超过窗口后不再自动续传。
|
|
186
|
+
- 仅支持 C2C 私聊;登录凭据只在进程内存。
|
|
187
|
+
- 最终文本在流式失败时走普通消息路径,可能重复已显示的部分,优先保证完整。
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# pi-qq delivery-v3
|
|
2
|
+
|
|
3
|
+
> Status: v3 implemented and the main path has been verified on real QQ. Final details such as long-list splitting and recovery edge cases still need one complete pass on the target client.
|
|
4
|
+
> Previous: [delivery-v1.md](./delivery-v1.md), [delivery-v2.md](./delivery-v2.md).
|
|
5
|
+
|
|
6
|
+
## 1. Scope
|
|
7
|
+
|
|
8
|
+
v3 consolidates long-run relay and configuration:
|
|
9
|
+
|
|
10
|
+
- F12: event-driven relay of thinking, tools, and text by content block;
|
|
11
|
+
- F13: remove message heartbeats;
|
|
12
|
+
- F14: consolidate settings.
|
|
13
|
+
|
|
14
|
+
## 2. Output model
|
|
15
|
+
|
|
16
|
+
### 2.1 One bubble per content block
|
|
17
|
+
|
|
18
|
+
In chronological order:
|
|
19
|
+
|
|
20
|
+
1. thinking block;
|
|
21
|
+
2. each tool call + result;
|
|
22
|
+
3. text block;
|
|
23
|
+
4. final message.
|
|
24
|
+
|
|
25
|
+
While tools are pending, later thinking/text is deferred so it cannot appear between two tool bubbles. Parallel tools are shown one at a time in start order; results are correlated by `toolCallId`.
|
|
26
|
+
|
|
27
|
+
### 2.2 Thinking format
|
|
28
|
+
|
|
29
|
+
The first line of every thinking bubble:
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
**💭 思考**
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The body is plain text with no `>` quote prefix; blank lines and newlines are preserved. At the 12k safety boundary the relay starts a new bubble and repeats the header.
|
|
36
|
+
|
|
37
|
+
Blockquotes are not used because QQ renders single-line/blank-line quote blocks as unsupported messages; plain text plus a header renders reliably.
|
|
38
|
+
|
|
39
|
+
### 2.3 Tool format
|
|
40
|
+
|
|
41
|
+
````text
|
|
42
|
+
**<icon> <tool>**
|
|
43
|
+
|
|
44
|
+
`argument`
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
output
|
|
48
|
+
````
|
|
49
|
+
|
|
50
|
+
````
|
|
51
|
+
|
|
52
|
+
Failed results start with:
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
❌ ...
|
|
56
|
+
````
|
|
57
|
+
|
|
58
|
+
Each tool call gets its own bubble; the tool header, argument, and result are never split.
|
|
59
|
+
|
|
60
|
+
Fixed icon map:
|
|
61
|
+
|
|
62
|
+
| Tool | Icon | Tool | Icon |
|
|
63
|
+
| -------- | ---- | ------------ | ---- |
|
|
64
|
+
| `bash` | 💻 | `read` | 📖 |
|
|
65
|
+
| `write` | 📝 | `edit` | ✏️ |
|
|
66
|
+
| `grep` | 🔎 | `search` | 🔍 |
|
|
67
|
+
| `find` | 🗂️ | `ls` | 📁 |
|
|
68
|
+
| `list` | 📋 | `web` | 🌐 |
|
|
69
|
+
| `fetch` | 📡 | `delete` | 🗑️ |
|
|
70
|
+
| `remove` | ❌ | `todo` | ✅ |
|
|
71
|
+
| `test` | 🧪 | unconfigured | 🔧 |
|
|
72
|
+
|
|
73
|
+
Icons are hard-coded in `src/relay/stream-block-format.ts`; no setting is added.
|
|
74
|
+
|
|
75
|
+
### 2.4 Text and ordinary messages
|
|
76
|
+
|
|
77
|
+
Assistant text is appended as-is and has no extra header. Text and tool blocks are separated by bubble boundaries.
|
|
78
|
+
|
|
79
|
+
## 3. Bubble splitting and streaming
|
|
80
|
+
|
|
81
|
+
- A run normally produces multiple bubbles, but each bubble carries one content block.
|
|
82
|
+
- When one block reaches `MAX_BUBBLE_CHARS = 12_000`, split at a safe boundary:
|
|
83
|
+
- block boundary or line start;
|
|
84
|
+
- no open code fence;
|
|
85
|
+
- no pending resume checkpoint;
|
|
86
|
+
- no active tool.
|
|
87
|
+
- Thinking splits favor line/list structure and do not truncate mid-line.
|
|
88
|
+
- Tool header/argument and result always stay in the same bubble.
|
|
89
|
+
- `AppendStream` enforces the 300ms platform floor, 500ms default batching, 429/50002 backoff, and same-bubble resume.
|
|
90
|
+
- `index` advances after every send attempt; an unconfirmed failed frame is retried with the next index.
|
|
91
|
+
- After five minutes or a platform rejection, the final text falls back to the normal message path.
|
|
92
|
+
|
|
93
|
+
## 4. Abort and error recovery
|
|
94
|
+
|
|
95
|
+
### 4.1 `/stop`
|
|
96
|
+
|
|
97
|
+
The `/stop` flow:
|
|
98
|
+
|
|
99
|
+
1. cancel the recovery target;
|
|
100
|
+
2. abort the agent;
|
|
101
|
+
3. wait for `agent_end` to finish the current stream, tool results, and DONE;
|
|
102
|
+
4. reply `Abort requested.`
|
|
103
|
+
|
|
104
|
+
Started tool results are therefore not lost, and queued tool bubbles do not appear after the abort reply.
|
|
105
|
+
|
|
106
|
+
### 4.2 Model error recovery
|
|
107
|
+
|
|
108
|
+
- After a model error, keep the original QQ target for 60 seconds.
|
|
109
|
+
- New runs created by pi's automatic recovery/retry reuse the same `msgId`.
|
|
110
|
+
- An empty retry that produces no output does not consume the recovery target; the next retry can still attach.
|
|
111
|
+
- A new QQ message or `/stop` cancels recovery.
|
|
112
|
+
- A local run inside the recovery window can also be relayed. This is an explicit trade-off to preserve pi's automatic recovery.
|
|
113
|
+
|
|
114
|
+
## 5. Settings
|
|
115
|
+
|
|
116
|
+
`~/.pi/agent/pi-qq.json` stores settings only; credentials are never written there.
|
|
117
|
+
|
|
118
|
+
| Setting | Default | Description |
|
|
119
|
+
| --------------- | -------------- | ----------------------------------------- |
|
|
120
|
+
| `thinkingRelay` | `true` | Relay plain-text thinking blocks |
|
|
121
|
+
| `deliverAs` | `"steer"` | Queue behavior while busy |
|
|
122
|
+
| `imageMaxSize` | 10MB | Image download limit |
|
|
123
|
+
| `fileMaxSize` | 50MB | File download limit |
|
|
124
|
+
| `logLevel` | `"silent"` | Log threshold |
|
|
125
|
+
| `debug` | migration only | `debug: true` maps to `logLevel: "debug"` |
|
|
126
|
+
|
|
127
|
+
Removed settings: `streamRelay`, `streamFlushMs`, `streamAssistant`, `markdownSupport`, `heartbeatMinutes`, `heartbeatMaxMessages`. Old keys are ignored and not written back.
|
|
128
|
+
|
|
129
|
+
## 6. Modules and boundaries
|
|
130
|
+
|
|
131
|
+
The code is layered by responsibility:
|
|
132
|
+
|
|
133
|
+
<!-- prettier-ignore -->
|
|
134
|
+
| Module | Responsibility |
|
|
135
|
+
| ---------------------------- | ------------------------------------------------------------------------- |
|
|
136
|
+
| `index.ts` | Extension wiring, pi event subscriptions, command/diagnostic registration |
|
|
137
|
+
| `src/qq/qq-message-handler.ts` | QQ inbound routing, commands, attachments, injection into pi |
|
|
138
|
+
| `src/qq/reply-sender.ts` | Markdown-to-text conversion, chunking, sending |
|
|
139
|
+
| `src/relay/run-stream-relay.ts` | Content-block orchestration, bubble lifecycle, tool queue, recovery |
|
|
140
|
+
| `src/relay/stream-block-format.ts` | Thinking header, tool icons, argument/result formatting |
|
|
141
|
+
| `src/relay/stream-session.ts` | Stream frames, batching, retries, resume checkpoints |
|
|
142
|
+
| `src/quota/reply-quota.ts` | Passive reply quota and `msgId` window |
|
|
143
|
+
| `src/quota/reply-quota-report.ts` | Quota diagnostic text |
|
|
144
|
+
| `src/infra/settings.ts` | Settings reading and legacy-key migration |
|
|
145
|
+
| `src/qq/qq-bot.ts` | QQBot/Gateway lifecycle and middleware |
|
|
146
|
+
| `src/qq/qr-login.ts` | QR login |
|
|
147
|
+
| `src/attachments/file-attachments.ts` | File storage, index, deduplication, pending files |
|
|
148
|
+
| `src/attachments/image-attachments.ts` | Image validation and vision input |
|
|
149
|
+
| `src/attachments/attachment-download.ts` | Shared limited download for images/files |
|
|
150
|
+
| `src/attachments/voice-transcript.ts` | QQ ASR text extraction |
|
|
151
|
+
| `src/infra/file-logger.ts` | Structured file logging |
|
|
152
|
+
| `src/infra/display-format.ts` | Byte/token display formatting |
|
|
153
|
+
|
|
154
|
+
Boundary rules:
|
|
155
|
+
|
|
156
|
+
- `index.ts` does not own the relay state machine.
|
|
157
|
+
- `stream-block-format.ts` is pure formatting and does not depend on streams.
|
|
158
|
+
- `run-stream-relay.ts` orchestrates and does not build Markdown details.
|
|
159
|
+
- `stream-session.ts` does not know content-block semantics.
|
|
160
|
+
- `qq-message-handler.ts` does not implement download, storage, or quota.
|
|
161
|
+
- All configuration goes through `settings.ts`.
|
|
162
|
+
- Modules are independently testable or receive dependencies from the entrypoint.
|
|
163
|
+
|
|
164
|
+
## 7. Verification
|
|
165
|
+
|
|
166
|
+
- Unit tests: **135 passed** across 14 test files.
|
|
167
|
+
- TypeScript, ESLint, and Prettier checks pass.
|
|
168
|
+
- Verified on real QQ:
|
|
169
|
+
- C2C login, text, images, and files;
|
|
170
|
+
- thinking/tool/text rendered as separate blocks;
|
|
171
|
+
- tool header/result in the same bubble;
|
|
172
|
+
- 12k split with repeated header;
|
|
173
|
+
- `/stop` teardown and automatic recovery after model errors.
|
|
174
|
+
- Still worth a final pass:
|
|
175
|
+
- long list splitting on the target client;
|
|
176
|
+
- extremely long unclosed code fences;
|
|
177
|
+
- recovery near the TTL boundary;
|
|
178
|
+
- message quota with many parallel tools.
|
|
179
|
+
|
|
180
|
+
## 8. Risks and limitations
|
|
181
|
+
|
|
182
|
+
- One bubble per block increases message count; long runs need quota monitoring.
|
|
183
|
+
- 12k splitting is stateful; extreme single-line or unclosed-fence content may still fall back to platform splitting.
|
|
184
|
+
- Tool icons are hard-coded Emoji; rendering may vary by QQ client font.
|
|
185
|
+
- Recovery has a 60-second TTL; it stops after the window.
|
|
186
|
+
- C2C private chat only; credentials live in process memory.
|
|
187
|
+
- If streaming fails, the final text uses the normal message path and may duplicate already-visible content. Completeness is prioritized.
|