@chen_hu_hu/pi-qq 1.3.5 → 1.4.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/CHANGELOG.md +20 -1
- package/README-zh.md +1 -1
- package/README.md +1 -1
- package/doc/archive/README.md +14 -0
- package/doc/archive/delivery-v4-zh.md +327 -0
- package/doc/archive/delivery-v4.md +327 -0
- package/doc/todo.md +184 -0
- package/index.ts +97 -0
- package/package.json +1 -1
- package/src/infra/i18n.ts +6 -0
- package/src/qq/inbound-command.ts +7 -0
- package/src/qq/qq-diagnostics.ts +2 -2
- package/src/qq/reply-sender.ts +5 -0
- package/src/relay/bubble-writer.ts +141 -12
- package/src/relay/run-stream-relay.ts +166 -12
- package/src/relay/stream-block-format.ts +139 -22
- package/src/relay/stream-session.ts +38 -5
- package/doc/bugfix-v4.md +0 -698
- package/doc/enhance-status.md +0 -427
- package/doc/send-skill.md +0 -257
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [1.4.0] - 2026-11-04
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Debug diagnostics for long-running tools: tool duration/update summaries, stream frame error codes, writer state, `/last` repush, `/stop` wait time, and event-loop timer drift. Logging only; no runtime behavior change.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
- 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`).
|
|
19
|
+
- Consolidated the v4 design and investigation records into `doc/archive/delivery-v4.md` and `doc/archive/delivery-v4-zh.md`.
|
|
20
|
+
|
|
21
|
+
## [1.3.6] - 2026-11-04
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- Debug timing logs for tool stream enqueue/append, stream buffer/flush timers, and event-loop delay. They are written only at `logLevel: "debug"` and do not change runtime behavior.
|
|
26
|
+
|
|
10
27
|
## [1.3.5] - 2026-11-04
|
|
11
28
|
|
|
12
29
|
### Added
|
|
@@ -79,7 +96,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
79
96
|
- Added thinking labels, per-tool icons, model-error recovery, and idle-safe session handling.
|
|
80
97
|
- Reorganized modules by bounded context and updated settings and delivery documentation.
|
|
81
98
|
|
|
82
|
-
[Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.
|
|
99
|
+
[Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.0...HEAD
|
|
100
|
+
[1.4.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.6...v1.4.0
|
|
101
|
+
[1.3.6]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.5...v1.3.6
|
|
83
102
|
[1.3.5]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.4...v1.3.5
|
|
84
103
|
[1.3.4]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.3...v1.3.4
|
|
85
104
|
[1.3.3]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.2...v1.3.3
|
package/README-zh.md
CHANGED
|
@@ -76,7 +76,7 @@ Summarize this file.
|
|
|
76
76
|
### 回复格式
|
|
77
77
|
|
|
78
78
|
- **思考**:独立气泡,纯文本,首行 `**💭 思考**`。长思考可能续到新气泡,并重复标题。
|
|
79
|
-
- **工具**:每次调用独立气泡,首行
|
|
79
|
+
- **工具**:每次调用独立气泡,首行 `## <图标> <工具名>`;`bash` 命令使用 `bash` 代码块,其他参数使用行内代码;结果按工具/文件类型使用 `text`、`markdown`、`python`、`json` 等代码块。
|
|
80
80
|
- **普通消息**:原文,不加标题。
|
|
81
81
|
- **工具图标**:💻 bash、📖 read、📝 write、✏️ edit、🔎 grep、🔍 search、🗂️ find、📁 ls、📋 list、🌐 web、📡 fetch、🗑️ delete、❌ remove、✅ todo、🧪 test;未配置工具使用 🔧。
|
|
82
82
|
- **错误恢复**:模型错误后 60 秒内自动恢复的 run 会继续推送到原 QQ 会话;`/stop` 会等待当前工具和流收尾后再回复。
|
package/README.md
CHANGED
|
@@ -76,7 +76,7 @@ Debug logs include the raw `asr_refer_text` and attachment metadata when `logLev
|
|
|
76
76
|
### Reply format
|
|
77
77
|
|
|
78
78
|
- **Thinking**: its own bubble, plain text, starting with `**💭 思考**`. Long thinking may continue in a new bubble with the header repeated.
|
|
79
|
-
- **Tools**: one bubble per call:
|
|
79
|
+
- **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.
|
|
80
80
|
- **Regular messages**: raw text with no header.
|
|
81
81
|
- **Tool icons**: 💻 bash, 📖 read, 📝 write, ✏️ edit, 🔎 grep, 🔍 search, 🗂️ find, 📁 ls, 📋 list, 🌐 web, 📡 fetch, 🗑️ delete, ❌ remove, ✅ todo, 🧪 test; unconfigured tools use 🔧.
|
|
82
82
|
- **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.
|
package/doc/archive/README.md
CHANGED
|
@@ -9,6 +9,13 @@ historical snapshots, not current documentation.
|
|
|
9
9
|
`README.md`, `README-zh.md`, and `CHANGELOG.md` instead.
|
|
10
10
|
- File and line details in these records are intentionally frozen.
|
|
11
11
|
|
|
12
|
+
## Records
|
|
13
|
+
|
|
14
|
+
- v4: [English](./delivery-v4.md) · [中文](./delivery-v4-zh.md)
|
|
15
|
+
- v3: [English](./delivery-v3.md) · [中文](./delivery-v3-zh.md)
|
|
16
|
+
- v2: [English](./delivery-v2.md) · [中文](./delivery-v2-zh.md)
|
|
17
|
+
- v1: [English](./delivery-v1.md) · [中文](./delivery-v1-zh.md)
|
|
18
|
+
|
|
12
19
|
# 归档交付记录
|
|
13
20
|
|
|
14
21
|
本目录保存 pi-qq 各里程碑的交付记录,仅作历史快照,不是当前文档。
|
|
@@ -16,3 +23,10 @@ historical snapshots, not current documentation.
|
|
|
16
23
|
- 文中可能引用已删除的模块、配置或行为(例如图片专用链路和 `imageMaxSize`)。
|
|
17
24
|
- 不要把这些文档更新为当前行为;现行说明请写入 `README.md`、`README-zh.md` 和 `CHANGELOG.md`。
|
|
18
25
|
- 文件与行号等细节按当时状态保留。
|
|
26
|
+
|
|
27
|
+
## 记录
|
|
28
|
+
|
|
29
|
+
- v4:[English](./delivery-v4.md) · [中文](./delivery-v4-zh.md)
|
|
30
|
+
- v3:[English](./delivery-v3.md) · [中文](./delivery-v3-zh.md)
|
|
31
|
+
- v2:[English](./delivery-v2.md) · [中文](./delivery-v2-zh.md)
|
|
32
|
+
- v1:[English](./delivery-v1.md) · [中文](./delivery-v1-zh.md)
|
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
# pi-qq delivery-v4
|
|
2
|
+
|
|
3
|
+
> **归档记录。** 内容反映 v4 交付时的状态,可能引用后续已变化的行为;现行说明见 [README-zh.md](../../README-zh.md)。
|
|
4
|
+
> 状态:v4 已交付;工具代码块已完成真实 QQ 验证;长耗时工具与离线投递仍是未决项。
|
|
5
|
+
> 版本:1.4.0
|
|
6
|
+
> 日期:2026-11-04
|
|
7
|
+
> 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md)、[delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
|
|
8
|
+
> 未完成事项:[doc/todo.md](../todo.md)。
|
|
9
|
+
|
|
10
|
+
## 1. 交付范围
|
|
11
|
+
|
|
12
|
+
v4 是一次“输出质量 + 可观测性”交付,本记录合并了六份 v4 工作文档(名称为历史名称):
|
|
13
|
+
|
|
14
|
+
- 工具启动可见性(`tool-return`);
|
|
15
|
+
- Skill 执行展示(`send-skill`);
|
|
16
|
+
- `/status`、中英文与电量(`enhance-status`);
|
|
17
|
+
- QQ 手机后台收不到消息(`bugfix-v4`);
|
|
18
|
+
- 长耗时工具导致无响应(`long-tool`);
|
|
19
|
+
- 工具结果代码块类型(`block-type`)。
|
|
20
|
+
|
|
21
|
+
主要交付:
|
|
22
|
+
|
|
23
|
+
1. 新的工具气泡格式和代码块语言;
|
|
24
|
+
2. `SKILL.md` 读取使用独立 Skill 气泡;
|
|
25
|
+
3. QQ `/status` 与终端 `/qq-status` 统一展示执行状态、语言和电量;
|
|
26
|
+
4. QQ `/last` 作为手动恢复通道;
|
|
27
|
+
5. 长工具和流式失败的 debug 诊断日志。
|
|
28
|
+
|
|
29
|
+
本次不改变传输模型:仍然是 QQ C2C 私聊、被动回复和 `stream_messages` 流式输出。
|
|
30
|
+
|
|
31
|
+
## 2. 工具输出
|
|
32
|
+
|
|
33
|
+
### 2.1 气泡布局
|
|
34
|
+
|
|
35
|
+
每个内容块独立成泡。思考保持纯文本:
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
**💭 思考**
|
|
39
|
+
|
|
40
|
+
推理内容...
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
工具调用使用二级标题:
|
|
44
|
+
|
|
45
|
+
````markdown
|
|
46
|
+
## 💻 bash
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npm test
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
12 passed
|
|
54
|
+
```
|
|
55
|
+
````
|
|
56
|
+
|
|
57
|
+
规则:
|
|
58
|
+
|
|
59
|
+
- 工具标题为 `## <图标> <工具名>`;
|
|
60
|
+
- `bash` 命令使用 `bash` 代码块,保留换行;
|
|
61
|
+
- bash 命令完整展示,不再套用旧的 200 字符参数上限;
|
|
62
|
+
- `read` / `write` / `edit` 的路径继续使用行内代码;
|
|
63
|
+
- 其他工具的主参数继续使用行内代码;
|
|
64
|
+
- 工具调用和结果始终在同一个气泡;
|
|
65
|
+
- 不在工具调用和结果之间切泡。
|
|
66
|
+
|
|
67
|
+
结果代码块语言按工具和文件类型选择:
|
|
68
|
+
|
|
69
|
+
| 来源 | 结果语言 |
|
|
70
|
+
| --------------- | ----------------------------------- |
|
|
71
|
+
| `bash` | `text` |
|
|
72
|
+
| `write`、`edit` | `text` |
|
|
73
|
+
| `read` | 按扩展名选择;未知扩展名回退 `text` |
|
|
74
|
+
| 错误或空结果 | `text` |
|
|
75
|
+
| 其他工具 | `text` |
|
|
76
|
+
|
|
77
|
+
常用映射包括:`md` → `markdown`、`json` → `json`、`yaml` → `yaml`、`ts` → `typescript`、`tsx` → `tsx`、`js` → `javascript`、`py` → `python`、`sh`/`bash`/`zsh` → `bash`、`html` → `html`、`css` → `css`、`sql` → `sql`、`rs` → `rust`、`go` → `go`、`diff`/`patch` → `diff`。
|
|
78
|
+
|
|
79
|
+
特殊文件名:
|
|
80
|
+
|
|
81
|
+
- `Dockerfile` → `dockerfile`;
|
|
82
|
+
- `Makefile` → `makefile`;
|
|
83
|
+
- `CMakeLists.txt` → `cmake`;
|
|
84
|
+
- `README` → `markdown`。
|
|
85
|
+
|
|
86
|
+
空结果和失败结果始终使用 `text`。结果正文仍限制为 600 字符 / 8 行;bash 命令本身不截断。
|
|
87
|
+
|
|
88
|
+
固定图标:
|
|
89
|
+
|
|
90
|
+
| 工具 | 图标 | 工具 | 图标 |
|
|
91
|
+
| -------- | ---- | -------- | ---- |
|
|
92
|
+
| `bash` | 💻 | `read` | 📖 |
|
|
93
|
+
| `write` | 📝 | `edit` | ✏️ |
|
|
94
|
+
| `grep` | 🔎 | `search` | 🔍 |
|
|
95
|
+
| `find` | 🗂️ | `ls` | 📁 |
|
|
96
|
+
| `list` | 📋 | `web` | 🌐 |
|
|
97
|
+
| `fetch` | 📡 | `delete` | 🗑️ |
|
|
98
|
+
| `remove` | ❌ | `todo` | ✅ |
|
|
99
|
+
| `test` | 🧪 | 其他 | 🔧 |
|
|
100
|
+
|
|
101
|
+
### 2.2 Skill 气泡
|
|
102
|
+
|
|
103
|
+
读取 `SKILL.md` 时显示:
|
|
104
|
+
|
|
105
|
+
```markdown
|
|
106
|
+
## 🧩 Skill
|
|
107
|
+
|
|
108
|
+
`playwright-cli`
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
- skill 名称取父目录名;
|
|
112
|
+
- 支持 `path` 和 `file_path`;
|
|
113
|
+
- 支持 Unix 和 Windows 路径分隔符;
|
|
114
|
+
- 不转发 `SKILL.md` 内容;
|
|
115
|
+
- 不显示普通 `📖 read` 工具行和结果;
|
|
116
|
+
- 每次读取产生一个 Skill 气泡,不做去重;
|
|
117
|
+
- QQ 不支持 `/skill:`,只识别模型自动读取。
|
|
118
|
+
|
|
119
|
+
### 2.3 气泡边界
|
|
120
|
+
|
|
121
|
+
- 思考、工具、文本各自成块;
|
|
122
|
+
- 一次 run 可能产生多个气泡,但工具调用和结果始终同泡;
|
|
123
|
+
- `MAX_BUBBLE_CHARS = 12_000` 时在块边界或行首安全切泡;
|
|
124
|
+
- 不在未闭合代码围栏、待续写检查点或进行中的工具内切泡;
|
|
125
|
+
- 并行工具按开始顺序逐个展示,结果通过 `toolCallId` 归属;
|
|
126
|
+
- 工具未完成时,后续思考和文本暂存,避免插入工具调用和结果之间。
|
|
127
|
+
|
|
128
|
+
## 3. 状态、语言与电量
|
|
129
|
+
|
|
130
|
+
QQ `/status` 与终端 `/qq-status` 共用同一份格式化结果。
|
|
131
|
+
|
|
132
|
+
当前字段:
|
|
133
|
+
|
|
134
|
+
| 字段 | 内容 |
|
|
135
|
+
| ------- | ------------------------------------------------ |
|
|
136
|
+
| 标题 | `🖥️ pi-qq 状态` |
|
|
137
|
+
| 登录 | 扫码登录与掩码 AppID,或“未登录” |
|
|
138
|
+
| 连接 | `已连接`、`重连中`、`已停止`、`启动中`、`已阻止` |
|
|
139
|
+
| 执行 | `执行中(QQ)`、`执行中(本地)`、`已完成` |
|
|
140
|
+
| 模型 | 当前模型名 |
|
|
141
|
+
| 上下文 | tokens / window / percent |
|
|
142
|
+
| QQ 用户 | 掩码后的绑定 openid |
|
|
143
|
+
| 电量 | 百分比和充电/放电/AC;没有电池时隐藏 |
|
|
144
|
+
| 设置 | `~/.pi/agent/pi-qq.json` |
|
|
145
|
+
|
|
146
|
+
执行状态以 `ctx.isIdle()` 为全局信号,并用 `runFeedback.isQQRunActive()` 区分 QQ 任务和本地任务。
|
|
147
|
+
|
|
148
|
+
电量支持:
|
|
149
|
+
|
|
150
|
+
- Linux:`/sys/class/power_supply/BAT*`;
|
|
151
|
+
- macOS:`pmset -g batt`;
|
|
152
|
+
- Windows:PowerShell `Get-CimInstance Win32_Battery`;
|
|
153
|
+
- 结果缓存 30 秒;
|
|
154
|
+
- 读取失败静默隐藏 Battery 行;
|
|
155
|
+
- 不新增 npm 依赖。
|
|
156
|
+
|
|
157
|
+
中英文:
|
|
158
|
+
|
|
159
|
+
- 新增 `language` 配置,支持 `"zh-cn"` 和 `"en-us"`;
|
|
160
|
+
- 默认 `"zh-cn"`;
|
|
161
|
+
- 命令回复、状态、错误、流式占位符和 pi-qq 自有日志都走文案表;
|
|
162
|
+
- 日志保留稳定字段,并新增 `msgKey`,便于与语言无关地过滤;
|
|
163
|
+
- 第三方 SDK 的原始错误和日志保持原文;
|
|
164
|
+
- 非法配置回退默认值并给出警告。
|
|
165
|
+
|
|
166
|
+
`Bound user` 改名为 `QQ 用户`,并做 openid 掩码。
|
|
167
|
+
|
|
168
|
+
## 4. 工具启动可见性
|
|
169
|
+
|
|
170
|
+
调研结论:工具启动信息延迟主要来自流式合帧,不是工具执行本身。
|
|
171
|
+
|
|
172
|
+
- `AppendStream` 默认 500ms 节流,平台下限 300ms;
|
|
173
|
+
- 短工具的结果可能在 500ms 内进入同一个 buffer,导致工具名、参数和结果一起出现;
|
|
174
|
+
- 长工具通常会在约 500ms 后先发出启动帧;
|
|
175
|
+
- 并行工具受 `RunFeedback.activeTool` 串行输出限制,后启动的工具要等前一个工具结束。
|
|
176
|
+
|
|
177
|
+
v4 没有实现原计划中的工具启动 `flushAfter`。不过新的代码块格式把 bash 参数从行内代码改成 fenced block,避免了长行内代码被 QQ 折叠成一个点的问题。
|
|
178
|
+
|
|
179
|
+
1.3.6 增加了 debug 时序日志:
|
|
180
|
+
|
|
181
|
+
- 工具入队 / append start / append done;
|
|
182
|
+
- stream buffer、flush timer 和 flush 结果;
|
|
183
|
+
- 事件循环 `meanMs`、`maxMs`、`p99Ms`,后续又增加 `driftMs`。
|
|
184
|
+
|
|
185
|
+
## 5. 长耗时工具
|
|
186
|
+
|
|
187
|
+
### 5.1 失败链路
|
|
188
|
+
|
|
189
|
+
长工具可能导致 QQ 长时间无输出:
|
|
190
|
+
|
|
191
|
+
1. 工具运行期间没有新的 assistant 事件;
|
|
192
|
+
2. QQ 上只有工具启动气泡;
|
|
193
|
+
3. 长静默后,下一帧很容易触发 `msg_id` 过期或被动回复次数超限;
|
|
194
|
+
4. `BubbleWriter` 用同一个过期 `msg_id` / `stream_msg_id` 尝试 resume;
|
|
195
|
+
5. resume 次数耗尽后 `killStream()`,后续工具输出全部丢失;
|
|
196
|
+
6. writer 死亡时 `onToolEnd()` 直接返回,`activeTool` 和 deferred 文本卡住;
|
|
197
|
+
7. 最终 assistant 文本可能改走普通消息,超过 5 分钟后会降级为主动消息。
|
|
198
|
+
|
|
199
|
+
其他放大因素:
|
|
200
|
+
|
|
201
|
+
- 每个思考/工具气泡都会新建一条流式回复,但 `ReplyBudget` 没有把流式气泡计入 4 次被动回复上限;
|
|
202
|
+
- `/stop` 要等 `waitForEnd()` 才回复,可能占住 SDK 并发锁;
|
|
203
|
+
- 不转发 `tool_execution_update`,没有进度帧;
|
|
204
|
+
- 新 QQ 消息以 `steer` 排队,要等当前工具批次结束才处理。
|
|
205
|
+
|
|
206
|
+
### 5.2 已交付内容
|
|
207
|
+
|
|
208
|
+
- 只加 debug 诊断,不修改行为;
|
|
209
|
+
- QQ `/last` 作为手动恢复:
|
|
210
|
+
- 运行中:`RunFeedback.repushCurrent()` 绑定到新的 `/last` 消息并重推当前文本;
|
|
211
|
+
- 空闲时:`sendStreamReply()` 推送最近一次完成的 assistant 文本。
|
|
212
|
+
- 1.3.6 及后续补充的诊断:
|
|
213
|
+
- 工具 `durationMs`、`updateCount`、`updateSpanMs`、首次部分输出;
|
|
214
|
+
- run 目标选择、工具 queued/started/finished/ignored、assistant final 决策、run cleanup;
|
|
215
|
+
- writer `dead`、`hasPendingResume`、`resumeAttempts`、`lastFrameAgeMs`;
|
|
216
|
+
- 流式帧 `httpStatus`、`bizCode`、`path`、`msgSeq`、`streamMsgId`、`bufferLength`;
|
|
217
|
+
- `/stop` 等待时长;
|
|
218
|
+
- 事件循环 `driftMs`。
|
|
219
|
+
|
|
220
|
+
### 5.3 未修复的协议风险
|
|
221
|
+
|
|
222
|
+
v4 未修复:
|
|
223
|
+
|
|
224
|
+
- 流式气泡未计入被动回复额度;
|
|
225
|
+
- `DONE` 帧的 `content_raw` 为空;
|
|
226
|
+
- stream 请求同时发送 `event_id` 和 `msg_id`,而协议约定二选一;
|
|
227
|
+
- resume 复用已过期的标识;
|
|
228
|
+
- 没有过期被动窗口的待发送队列;
|
|
229
|
+
- 流式成功后没有普通文本终态兜底;
|
|
230
|
+
- SDK 没有心跳 ACK 超时检测;
|
|
231
|
+
- 没有启用 session persistence。
|
|
232
|
+
|
|
233
|
+
## 6. QQ 后台与离线投递
|
|
234
|
+
|
|
235
|
+
现象:iPhone QQ 长时间后台后重新打开,电脑上的 pi 仍在运行,但离线期间的机器人输出看不到;新入站消息仍能到达 pi,机器人也能回复新消息。
|
|
236
|
+
|
|
237
|
+
最可能的解释是手机端/平台离线投递问题:QQ 不会补发手机离线期间产生的流式机器人内容。由于没有事故日志,这一点尚未完全确认。
|
|
238
|
+
|
|
239
|
+
v4 已交付:
|
|
240
|
+
|
|
241
|
+
- `/last` 手动恢复;
|
|
242
|
+
- 登录、连接、执行、模型、上下文和额度的状态/诊断可见性。
|
|
243
|
+
|
|
244
|
+
v4 未交付:
|
|
245
|
+
|
|
246
|
+
- 60 分钟被动窗口修正(代码仍按 5 分钟);
|
|
247
|
+
- 流式结束后的持久化最终文本;
|
|
248
|
+
- 下次入站时补发离线摘要;
|
|
249
|
+
- SDK 心跳 ACK 超时;
|
|
250
|
+
- session persistence;
|
|
251
|
+
- 运行中自动把 writer 重绑到新入站消息。
|
|
252
|
+
|
|
253
|
+
## 7. 诊断
|
|
254
|
+
|
|
255
|
+
终端命令:
|
|
256
|
+
|
|
257
|
+
- `/qq-test-budget`:被动预算和流式气泡计数;
|
|
258
|
+
- `/qq-test-md [text]`:Markdown 渲染测试;
|
|
259
|
+
- `/qq-test-stream`:流式时间线和 resume 测试。
|
|
260
|
+
|
|
261
|
+
日志:
|
|
262
|
+
|
|
263
|
+
- 在 `~/.pi/agent/pi-qq.json` 设置 `logLevel: "debug"`;
|
|
264
|
+
- 日志路径:`<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;
|
|
265
|
+
- 可用 `PI_QQ_LOG_DIR` 覆盖目录;
|
|
266
|
+
- `info` 记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。
|
|
267
|
+
|
|
268
|
+
## 8. 模块与边界
|
|
269
|
+
|
|
270
|
+
<!-- prettier-ignore -->
|
|
271
|
+
| 模块 | 职责 |
|
|
272
|
+
| ---- | ---- |
|
|
273
|
+
| `index.ts` | 扩展装配、pi 事件、登录/会话命令、状态数据收集 |
|
|
274
|
+
| `src/qq/` | QQ 生命周期、扫码登录、入站路由、回复、诊断、状态格式化 |
|
|
275
|
+
| `src/relay/` | 思考/工具/文本回传、气泡布局、流式会话、工具结果格式化 |
|
|
276
|
+
| `src/quota/` | 被动回复预算与诊断 |
|
|
277
|
+
| `src/attachments/` | 文件下载、保存、pending、语音转写 |
|
|
278
|
+
| `src/infra/` | 配置、i18n、日志、电量、显示格式化 |
|
|
279
|
+
|
|
280
|
+
边界原则:
|
|
281
|
+
|
|
282
|
+
- 纯格式化放在 `stream-block-format.ts`;
|
|
283
|
+
- relay 编排放在 `run-stream-relay.ts` / `bubble-writer.ts`;
|
|
284
|
+
- 流式帧和重试放在 `stream-session.ts`;
|
|
285
|
+
- QQ 入站解析和命令路由放在 `src/qq/`;
|
|
286
|
+
- 所有配置通过 `settings.ts`;
|
|
287
|
+
- 模块由入口注入依赖,保持独立可测。
|
|
288
|
+
|
|
289
|
+
图片与文件共用保存/pending 流程;v4 之前的图片专用链路和 `imageMaxSize` 已移除。
|
|
290
|
+
|
|
291
|
+
## 9. 验证
|
|
292
|
+
|
|
293
|
+
- 单元测试:**172 passed**,18 个测试文件。
|
|
294
|
+
- TypeScript、ESLint、Prettier 检查通过。
|
|
295
|
+
- 2026-11-04 真实 QQ 工具代码块验证:
|
|
296
|
+
- 测试目录:`/home/chen/project/pi-qq-test`;
|
|
297
|
+
- 文件:`hello.py`、`Hello.java`、`hello.rs`、`hello.ts`;
|
|
298
|
+
- 日志:`.pi/pi-qq/logs/pi-qq-2026-11-04.log`;
|
|
299
|
+
- 观察到 `## 💻 bash` + bash 代码块、`## 📖 read` + rust/typescript 结果块、`## 📝 write` + 行内路径;
|
|
300
|
+
- event-loop `driftMs` 为 0–1ms,`maxMs` 约 101ms。
|
|
301
|
+
- 本次验收未单独执行 `/qq-test-stream`。
|
|
302
|
+
- 仍建议在真实 QQ 上补一次 `/status` 和长任务/离线场景的手动验收。
|
|
303
|
+
|
|
304
|
+
## 10. 风险与限制
|
|
305
|
+
|
|
306
|
+
- 长任务可能耗尽 4 次被动回复,因为流式气泡没有计入额度。
|
|
307
|
+
- 超过 5 分钟会降级为主动消息;用户可能关闭主动消息。
|
|
308
|
+
- resume 无法恢复已过期的 `msg_id` / `stream_msg_id`。
|
|
309
|
+
- 长工具没有进度心跳,只有 `typing`。
|
|
310
|
+
- 工具启动可能受 500ms 节流影响。
|
|
311
|
+
- QQ 客户端对语言高亮的支持不一致。
|
|
312
|
+
- 12k 切泡依赖状态;极端单行或未闭合围栏仍可能触发平台行为。
|
|
313
|
+
- 仅支持 C2C 私聊;登录凭据只在进程内存。
|
|
314
|
+
- debug 日志可能包含提示词、工具参数和结果。
|
|
315
|
+
|
|
316
|
+
## 11. 未完成事项
|
|
317
|
+
|
|
318
|
+
- [doc/todo.md](../todo.md) 第 1 节:长运行 bash 参数/工具启动可见性。
|
|
319
|
+
- [doc/todo.md](../todo.md) 第 2 节:长耗时工具导致 QQ 侧无输出。
|
|
320
|
+
- 先修复流式气泡额度记账,再增加更多按块气泡。
|
|
321
|
+
- 设计过期被动窗口和 pending 输出的处理方式。
|
|
322
|
+
- 验证 `DONE` 内容以及 `event_id` / `msg_id` 用法。
|
|
323
|
+
- 增加进度心跳或转发 `tool_execution_update`。
|
|
324
|
+
- 增加 SDK 心跳 ACK 超时,评估 session persistence。
|
|
325
|
+
- 决定是否需要进一步验收 `/status` 和 `/last`。
|
|
326
|
+
|
|
327
|
+
在拿到真实现场日志前,本文和诊断日志是 v4 的判断依据;不把未经证实的 relay 重写纳入 v4。
|