@chen_hu_hu/pi-qq 1.3.6 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,190 +0,0 @@
1
- # pi-qq delivery-v3
2
-
3
- > **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
4
- > 状态:v3 已实现并完成主链路真机验证;按块切泡、错误恢复、列表切分等最终细节仍需在目标 QQ 客户端做一次完整复验。
5
- > 说明:后续变更删除了图片专用链路,图片与文件共用保存/pending 流程。
6
- > 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md)、[delivery-v2-zh.md](./delivery-v2-zh.md)。
7
-
8
- ## 1. 交付范围
9
-
10
- v3 收敛长任务回传与配置:
11
-
12
- - F12:事件直推,思考、工具、文本按块回传;
13
- - F13:移除消息心跳;
14
- - F14:配置项收敛。
15
-
16
- ## 2. 输出模型
17
-
18
- ### 2.1 每个内容块一个气泡
19
-
20
- 按时间顺序:
21
-
22
- 1. 思考块;
23
- 2. 每个工具调用 + 结果;
24
- 3. 文本块;
25
- 4. 最终消息。
26
-
27
- 工具未完成时,后续思考/文本暂存,避免思考插入两个工具泡之间。并行工具按开始顺序逐个展示,结果通过 `toolCallId` 归属。
28
-
29
- ### 2.2 思考格式
30
-
31
- 每个思考泡首行:
32
-
33
- ```text
34
- **💭 思考**
35
- ```
36
-
37
- 正文为纯文本,不加 `>` 引用前缀,空行和换行原样保留。达到 12k 安全边界时主动切泡,新泡重复标题。
38
-
39
- 不使用引用块的原因:QQ 会把单行/空行引用块渲染为不支持的消息;纯文本 + 标题可稳定显示。
40
-
41
- ### 2.3 工具格式
42
-
43
- ````text
44
- **<图标> <工具名>**
45
-
46
- `参数`
47
-
48
- ```text
49
- 输出
50
- ````
51
-
52
- ````
53
-
54
- 失败结果首行:
55
-
56
- ```text
57
- ❌ ...
58
- ````
59
-
60
- 每个工具调用独立气泡;工具名、参数和结果不拆开。
61
-
62
- 固定图标映射:
63
-
64
- | 工具 | 图标 | 工具 | 图标 |
65
- | -------- | ---- | ---------- | ---- |
66
- | `bash` | 💻 | `read` | 📖 |
67
- | `write` | 📝 | `edit` | ✏️ |
68
- | `grep` | 🔎 | `search` | 🔍 |
69
- | `find` | 🗂️ | `ls` | 📁 |
70
- | `list` | 📋 | `web` | 🌐 |
71
- | `fetch` | 📡 | `delete` | 🗑️ |
72
- | `remove` | ❌ | `todo` | ✅ |
73
- | `test` | 🧪 | 未配置工具 | 🔧 |
74
-
75
- 图标硬编码在 `src/relay/stream-block-format.ts`,不增加配置项。
76
-
77
- ### 2.4 文本与普通消息
78
-
79
- assistant 文本按原文流式追加,不额外加标题。文本块和工具块之间通过气泡边界区分。
80
-
81
- ## 3. 切泡与流式传输
82
-
83
- - 每个 run 默认多泡,但每个泡只承载一个内容块。
84
- - 单块累计达到 `MAX_BUBBLE_CHARS = 12_000` 时,在安全边界切泡:
85
- - 块边界或行首;
86
- - 没有未闭合代码围栏;
87
- - 没有待续写检查点;
88
- - 没有进行中的工具。
89
- - 思考切泡优先保证列表/行结构,不在行中间强制截断。
90
- - 工具参数行与结果代码块始终在同一泡。
91
- - `AppendStream` 负责 300ms 平台下限、500ms 默认合帧、429/50002 退避和同泡续写。
92
- - `index` 每次发送尝试递增;失败帧的未确认缓冲用下一个 index 重发。
93
- - 超过 5 分钟或平台拒绝时,最终文本通过普通消息路径补发。
94
-
95
- ## 4. 中断与错误恢复
96
-
97
- ### 4.1 `/stop`
98
-
99
- `/stop` 的流程:
100
-
101
- 1. 取消错误恢复目标;
102
- 2. abort agent;
103
- 3. 等待 `agent_end` 完成当前流、工具结果和 DONE;
104
- 4. 回复 `Abort requested.`。
105
-
106
- 因此已启动的工具结果不会因为 `/stop` 丢失,也不会在 Abort requested 之后继续冒出排队工具泡。
107
-
108
- ### 4.2 模型错误恢复
109
-
110
- - 模型错误结束时保留原 QQ 目标 60 秒。
111
- - pi 自动恢复/重试产生的新 run 会沿用同一 `msgId` 继续推送。
112
- - 没有输出的空重试不会消耗恢复目标;下一次重试仍可继续。
113
- - 新 QQ 消息或 `/stop` 取消恢复。
114
- - 恢复目标内的本地 run 也可能被回传,这是为了延续 pi 自动恢复行为的明确取舍。
115
-
116
- ## 5. 配置
117
-
118
- `~/.pi/agent/pi-qq.json` 只保存设置,不保存凭据。
119
-
120
- | 配置 | 默认 | 说明 |
121
- | --------------- | ---------- | ---------------------------------------- |
122
- | `thinkingRelay` | `true` | 是否回传纯文本思考块 |
123
- | `deliverAs` | `"steer"` | 忙碌时新消息排队方式 |
124
- | `imageMaxSize` | 10MB | 图片下载上限 |
125
- | `fileMaxSize` | 50MB | 文件下载上限 |
126
- | `logLevel` | `"silent"` | 日志阈值 |
127
- | `debug` | 仅迁移读取 | `debug: true` 映射为 `logLevel: "debug"` |
128
-
129
- 已删除配置:`streamRelay`、`streamFlushMs`、`streamAssistant`、`markdownSupport`、`heartbeatMinutes`、`heartbeatMaxMessages`。旧键静默忽略,不写回。
130
-
131
- ## 6. 模块分布与边界
132
-
133
- 当前代码按职责分层:
134
-
135
- <!-- prettier-ignore -->
136
- | 模块 | 职责 |
137
- | ---------------------------- | -------------------------------------------- |
138
- | `index.ts` | 扩展装配、pi 事件订阅、登录/会话命令 |
139
- | `src/qq/qq-diagnostics.ts` | 终端协议诊断(`/qq-test-*`) |
140
- | `src/qq/qq-message-handler.ts` | QQ 入站路由、命令、附件、注入 pi |
141
- | `src/qq/reply-sender.ts` | Markdown 转纯文本、分块、消息发送 |
142
- | `src/relay/run-stream-relay.ts` | 内容块编排、气泡生命周期、工具队列、错误恢复 |
143
- | `src/relay/stream-block-format.ts` | 思考标题、工具图标、参数/结果纯格式化 |
144
- | `src/relay/stream-session.ts` | 流式帧、节流、重试、续写检查点 |
145
- | `src/quota/reply-quota.ts` | 被动回复预算与 `msgId` 窗口 |
146
- | `src/quota/reply-quota-report.ts` | 预算诊断文本 |
147
- | `src/infra/settings.ts` | 配置读取与旧键迁移 |
148
- | `src/qq/qq-bot.ts` | QQBot/Gateway 生命周期和中间件 |
149
- | `src/qq/qr-login.ts` | 扫码登录 |
150
- | `src/attachments/file-attachments.ts` | 文件保存、索引、去重、pending |
151
- | `src/attachments/image-attachments.ts` | 图片校验与视觉输入 |
152
- | `src/attachments/attachment-download.ts` | 图片/文件通用限流下载 |
153
- | `src/attachments/voice-transcript.ts` | QQ ASR 文本提取 |
154
- | `src/infra/file-logger.ts` | 结构化文件日志 |
155
- | `src/infra/display-format.ts` | 字节/token 通用格式化 |
156
-
157
- 边界原则:
158
-
159
- - `index.ts` 不承载回传状态机;
160
- - `stream-block-format.ts` 只做纯格式化,不依赖流对象;
161
- - `run-stream-relay.ts` 只做编排,不直接拼 Markdown 细节;
162
- - `stream-session.ts` 不感知内容块语义;
163
- - `qq-message-handler.ts` 不实现下载、存储或预算;
164
- - 所有配置通过 `settings.ts`,不散落在业务模块;
165
- - 每个模块都有独立测试或可从入口注入依赖。
166
-
167
- ## 7. 验证
168
-
169
- - v3 交付时单元测试:**135 passed**(14 个测试文件)。
170
- - TypeScript、ESLint 和 Prettier 检查通过。
171
- - 真机已验证:
172
- - C2C 登录、文本、图片、文件;
173
- - 思考/工具/文本按块展示;
174
- - 工具行与结果同泡;
175
- - 12k 切泡与标题重复;
176
- - `/stop` 收尾、模型错误后的自动恢复。
177
- - 仍需最终复验:
178
- - 目标客户端上的长列表切分;
179
- - 极端长代码围栏;
180
- - 错误恢复目标 TTL 接近边界的情况;
181
- - 并行工具较多时的消息额度。
182
-
183
- ## 8. 风险与限制
184
-
185
- - 每个内容块一泡会增加消息数;长任务需关注被动额度。
186
- - 12k 切泡依赖状态,极端单行/未闭合围栏仍可能落到平台自动切分。
187
- - 工具图标是硬编码 Emoji,不同 QQ 客户端字体可能略有差异。
188
- - 恢复目标是 60 秒 TTL;超过窗口后不再自动续传。
189
- - 仅支持 C2C 私聊;登录凭据只在进程内存。
190
- - 最终文本在流式失败时走普通消息路径,可能重复已显示的部分,优先保证完整。