@chen_hu_hu/pi-qq 1.3.2 → 1.3.3
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 +8 -1
- package/README-zh.md +8 -7
- package/README.md +8 -7
- package/doc/bugfix-v4.md +698 -0
- package/index.ts +2 -0
- package/package.json +1 -1
- package/src/qq/inbound-command.ts +25 -0
- package/src/qq/qq-message-handler.ts +24 -2
- package/src/qq/reply-sender.ts +23 -0
- package/src/relay/bubble-writer.ts +31 -0
- package/src/relay/run-stream-relay.ts +42 -5
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [1.3.3] - 2026-11-04
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- QQ `/last` command: push the last completed assistant message as a new stream bubble, or restart the current output while a run is active.
|
|
15
|
+
|
|
10
16
|
## [1.3.2] - 2026-11-04
|
|
11
17
|
|
|
12
18
|
### Added
|
|
@@ -55,7 +61,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
55
61
|
- Added thinking labels, per-tool icons, model-error recovery, and idle-safe session handling.
|
|
56
62
|
- Reorganized modules by bounded context and updated settings and delivery documentation.
|
|
57
63
|
|
|
58
|
-
[Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.
|
|
64
|
+
[Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.3...HEAD
|
|
65
|
+
[1.3.3]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.2...v1.3.3
|
|
59
66
|
[1.3.2]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.1...v1.3.2
|
|
60
67
|
[1.3.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.0...v1.3.1
|
|
61
68
|
[1.3.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.2.3...v1.3.0
|
package/README-zh.md
CHANGED
|
@@ -94,13 +94,14 @@ Summarize this file.
|
|
|
94
94
|
|
|
95
95
|
QQ 侧命令:
|
|
96
96
|
|
|
97
|
-
| 命令 | 说明
|
|
98
|
-
| ---------- |
|
|
99
|
-
| `/new` | 开始新的 pi 会话
|
|
100
|
-
| `/stop` | 中止当前运行
|
|
101
|
-
| `/compact` | 压缩当前上下文
|
|
102
|
-
| `/status` | 显示会话和上下文状态
|
|
103
|
-
| `/
|
|
97
|
+
| 命令 | 说明 |
|
|
98
|
+
| ---------- | -------------------------------------------- |
|
|
99
|
+
| `/new` | 开始新的 pi 会话 |
|
|
100
|
+
| `/stop` | 中止当前运行 |
|
|
101
|
+
| `/compact` | 压缩当前上下文 |
|
|
102
|
+
| `/status` | 显示会话和上下文状态 |
|
|
103
|
+
| `/last` | 以流式推送最近完成的回复,或重新推送当前输出 |
|
|
104
|
+
| `/help` | 显示命令帮助 |
|
|
104
105
|
|
|
105
106
|
### 诊断
|
|
106
107
|
|
package/README.md
CHANGED
|
@@ -94,13 +94,14 @@ Run these in the pi terminal:
|
|
|
94
94
|
|
|
95
95
|
QQ-side commands:
|
|
96
96
|
|
|
97
|
-
| Command | Description
|
|
98
|
-
| ---------- |
|
|
99
|
-
| `/new` | Start a new pi session
|
|
100
|
-
| `/stop` | Abort the current run
|
|
101
|
-
| `/compact` | Compact the current context
|
|
102
|
-
| `/status` | Show session and context status
|
|
103
|
-
| `/
|
|
97
|
+
| Command | Description |
|
|
98
|
+
| ---------- | ------------------------------------------------------------------------ |
|
|
99
|
+
| `/new` | Start a new pi session |
|
|
100
|
+
| `/stop` | Abort the current run |
|
|
101
|
+
| `/compact` | Compact the current context |
|
|
102
|
+
| `/status` | Show session and context status |
|
|
103
|
+
| `/last` | Push the last completed reply as a stream, or restart the current output |
|
|
104
|
+
| `/help` | Show command help |
|
|
104
105
|
|
|
105
106
|
### Diagnostics
|
|
106
107
|
|
package/doc/bugfix-v4.md
ADDED
|
@@ -0,0 +1,698 @@
|
|
|
1
|
+
# pi-qq v4 问题调研:手机 QQ 长期后台后收不到消息
|
|
2
|
+
|
|
3
|
+
> 状态:调研记录;已实现 QQ `/last` 命令,其余修复待定
|
|
4
|
+
> 日期:2026-11-04
|
|
5
|
+
> 涉及版本:pi-qq 1.3.2,`@tencent-connect/qqbot-nodejs` 1.0.5
|
|
6
|
+
> 范围:QQ C2C 私聊
|
|
7
|
+
|
|
8
|
+
## 1. 问题描述
|
|
9
|
+
|
|
10
|
+
用户反馈:
|
|
11
|
+
|
|
12
|
+
1. 手机 QQ 长时间挂在后台;
|
|
13
|
+
2. 电脑上的 pi 一直正常运行;
|
|
14
|
+
3. 电脑没有休眠,也没有切换网络;
|
|
15
|
+
4. **短时间后台/息屏后立即打开,一切正常**;
|
|
16
|
+
5. **长时间不打开 QQ 后,再次打开收不到任何机器人消息**;
|
|
17
|
+
6. 此时无法判断任务是在运行、已经完成,还是已经失败。
|
|
18
|
+
|
|
19
|
+
关键对比是第 4、5 条:短时间后台正常,长时间后台失败。这说明问题与**手机端 QQ 进程/连接在后台存活的时间**高度相关,而不是电脑侧 pi 是否运行。
|
|
20
|
+
|
|
21
|
+
需要区分两个不同的链路:
|
|
22
|
+
|
|
23
|
+
- **入站**:手机发出的 `C2C_MESSAGE_CREATE` 是否到达 pi;
|
|
24
|
+
- **出站**:pi 生成的回复是否到达手机 QQ,并在聊天记录中可见。
|
|
25
|
+
|
|
26
|
+
当前没有拿到事故时间段的 `pi-qq-*.log`。本文的结论来自代码路径、QQ 官方文档、局部复现和用户描述,仍需现场日志确认。
|
|
27
|
+
|
|
28
|
+
### 1.1 当前状态
|
|
29
|
+
|
|
30
|
+
- pi-qq 当前版本为 `1.3.2`;已实现 QQ `/last` 命令,其余修复待定。
|
|
31
|
+
- 用户环境为:手机 QQ 长时间后台,电脑上的 pi 持续运行,电脑未休眠、未切换网络。
|
|
32
|
+
- 现象具有明显的**时间阈值**:短时间后台正常,长时间后台后失败。
|
|
33
|
+
- 当前工作区没有找到事故时段的 `pi-qq-*.log`;`~/.pi/agent/pi-qq.json` 虽为 `logLevel: debug`,但无法确认事故进程的 cwd。
|
|
34
|
+
- 已基本排除入站和手机客户端同步;后续确认 TUI 持续有新事件,剩余关键是“iPhone 后台离线期间的平台保存/补发”还是“relay/stream 停止推送”。
|
|
35
|
+
|
|
36
|
+
### 1.2 追加确认(2026-11-04)
|
|
37
|
+
|
|
38
|
+
用户进一步确认:
|
|
39
|
+
|
|
40
|
+
1. 长时间后台后重新打开 QQ,发一条新消息,**电脑 pi 的 TUI 能收到**;
|
|
41
|
+
2. 长时间后台期间好友发来的普通 QQ 消息,重开后**能正常显示**;
|
|
42
|
+
3. 用户认为 `/qq-test-md` 和 `/qq-test-stream` 也能看到,因此暂不做该项测试。
|
|
43
|
+
|
|
44
|
+
由此可以基本排除:
|
|
45
|
+
|
|
46
|
+
- 入站 WebSocket 整体失效(新消息能到 pi);
|
|
47
|
+
- 手机 QQ 客户端的会话同步整体失效(好友消息能显示)。
|
|
48
|
+
|
|
49
|
+
问题范围缩小为:**任务在手机离线期间产生的机器人输出没有出现在手机上**,或者**任务本身在后台期间没有继续产生输出**(后续 1.4 已确认 TUI 一直有新事件,排除 agent 静默)。
|
|
50
|
+
|
|
51
|
+
需要区分“重开后触发测试能看到”和“手机后台期间发送、任务结束后再重开能看到”。前者只能证明实时链路正常,不能证明离线期间的消息被保存;第 3 条目前仍是假设,建议至少做一次“后台期间触发、结束前不打开手机”的对照。
|
|
52
|
+
|
|
53
|
+
### 1.3 再次确认(2026-11-04)
|
|
54
|
+
|
|
55
|
+
用户补充:
|
|
56
|
+
|
|
57
|
+
1. 失败发生时,电脑 TUI 里的 **agent 仍在运行**;
|
|
58
|
+
2. 重新打开 QQ 后发送新消息,**机器人会在 QQ 上回复**。
|
|
59
|
+
|
|
60
|
+
这意味着:
|
|
61
|
+
|
|
62
|
+
- 入站链路正常;
|
|
63
|
+
- 实时出站链路正常;
|
|
64
|
+
- 任务没有结束,因此问题不是“任务结束后的最终输出丢失”;
|
|
65
|
+
- 后续又确认 TUI 一直有新事件,因此 agent 并非静默;剩余可能是手机端离线期间消息未送达/未补发,或 relay/stream 停止推送;
|
|
66
|
+
- 无论哪种情况,用户都缺少“任务仍在运行/执行到哪一步”的反馈。
|
|
67
|
+
|
|
68
|
+
### 1.4 环境与现象确认(2026-11-04)
|
|
69
|
+
|
|
70
|
+
用户补充:
|
|
71
|
+
|
|
72
|
+
1. 手机是 **iPhone**;
|
|
73
|
+
2. 失败时 **TUI 一直有新事件**,可以确定有内容在持续输出;
|
|
74
|
+
3. 没有固定的工具或步骤,发生过很多次;
|
|
75
|
+
4. 只要手机 QQ 长时间挂后台就会断;
|
|
76
|
+
5. 用户没有查看日志,以上是根据现象描述;怀疑是 iPhone 把 QQ 的网络杀掉了。
|
|
77
|
+
|
|
78
|
+
这些信息基本排除了“agent 静默”:TUI 有新事件,说明 agent 仍在产出,`RunFeedback` 应该有内容要发。最符合的解释变成:
|
|
79
|
+
|
|
80
|
+
- iPhone 长时间后台后挂起/断开了 QQ 的网络;
|
|
81
|
+
- 期间 pi-qq 仍在发送,但手机没有收到;
|
|
82
|
+
- 重开后 QQ 能同步好友普通消息,但机器人消息没有补发;
|
|
83
|
+
- 新消息能到达 pi 并得到回复,说明实时链路恢复后是正常的。
|
|
84
|
+
|
|
85
|
+
仍需日志确认失败期间 `stream`/`outbound` 是否显示发送成功;如果日志显示流式失败或熔断,则还要并行排查 relay。
|
|
86
|
+
|
|
87
|
+
## 2. 结论摘要
|
|
88
|
+
|
|
89
|
+
| 优先级 | 可能原因 | 置信度 | 与现象的匹配度 |
|
|
90
|
+
| ------ | ------------------------------------------------------------------- | ------ | ------------------------------------------------------ |
|
|
91
|
+
| P0 | iPhone 长时间后台后挂起 QQ 网络,期间机器人输出未送达手机,也未补发 | 高 | 短后台正常、长后台失败;好友消息能同步、机器人消息不能 |
|
|
92
|
+
| P0 | 没有“下次入站补发”机制:用户回来后无法获知离线期间的任务输出/状态 | 高 | 用户无法判断执行到哪一步 |
|
|
93
|
+
| P1 | 后台期间只有流式输出,没有普通文本终态,离线客户端无内容可恢复 | 中 | 与机器人消息缺失、好友普通消息正常相符 |
|
|
94
|
+
| P1 | Relay/stream 在长任务中停止推送(60 分钟 `msg_id` 失效或熔断) | 中 | TUI 有新事件但手机无消息时需要排查 |
|
|
95
|
+
| P1 | C2C 被动回复窗口被写成 5 分钟,超过后走主动消息;主动消息可被关闭 | 高 | 长任务结果或兜底文本丢失 |
|
|
96
|
+
| P2 | 入站 WebSocket 静默失效(新消息已能到达,已排除) | 低 | 与“新消息能收到”不符 |
|
|
97
|
+
| P2 | 长离线不补发事件,且没有启用 `sessionPersistence` | 低 | 更符合进程重启或长时间断线 |
|
|
98
|
+
|
|
99
|
+
**结合最新确认**:失败时 TUI 持续有新事件,说明 agent 没有静默、relay 应该有内容要发;重开后新消息有 QQ 回复,说明实时出站正常。最符合现象的组合是:
|
|
100
|
+
|
|
101
|
+
1. iPhone 在长时间后台后挂起 QQ 的网络;
|
|
102
|
+
2. 这期间 pi 仍在产生输出并发送,但手机没有收到;
|
|
103
|
+
3. 重开后 QQ 能同步好友的普通消息,但机器人消息/流式消息没有补发;
|
|
104
|
+
4. pi-qq 也没有在用户下一次入站时补发这段时间的状态或输出。
|
|
105
|
+
|
|
106
|
+
下一步最关键的是确认失败期间日志中的 `stream`/`outbound` 是否显示发送成功,以及好友普通消息与机器人消息的同步差异。
|
|
107
|
+
|
|
108
|
+
## 3. 当前实现
|
|
109
|
+
|
|
110
|
+
### 3.1 入站链路
|
|
111
|
+
|
|
112
|
+
1. SDK 通过 WebSocket 接收 `C2C_MESSAGE_CREATE`,调用 `bot.on("message")`。
|
|
113
|
+
2. `src/qq/qq-message-handler.ts` 做 C2C、allowlist、回复预算和内容解析。
|
|
114
|
+
3. `deps.pi.sendUserMessage(...)` 把内容送入 pi agent。
|
|
115
|
+
4. `src/relay/run-stream-relay.ts` 负责把 agent 事件转成 QQ 输出。
|
|
116
|
+
|
|
117
|
+
`src/qq/qq-bot.ts` 的连接状态只由三个事件驱动:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
bot.on("ready", () => report("connected"));
|
|
121
|
+
bot.on("resumed", () => report("connected"));
|
|
122
|
+
bot.on("disconnected", ({ willReconnect }) => report(willReconnect ? "reconnecting" : "stopped"));
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
没有心跳 ACK 年龄、最后入站时间或主动健康检查。
|
|
126
|
+
|
|
127
|
+
### 3.2 出站链路
|
|
128
|
+
|
|
129
|
+
QQ 任务输出默认走 `/v2/users/{openid}/stream_messages`:
|
|
130
|
+
|
|
131
|
+
- `src/relay/bubble-writer.ts` 负责切泡、追加和 `DONE`;
|
|
132
|
+
- `src/relay/stream-session.ts` 负责流式帧的重试、节流和断点续写;
|
|
133
|
+
- `src/relay/run-stream-relay.ts:197` 用 `ok && hasPushed` 判断流式是否已经接管输出;
|
|
134
|
+
- `index.ts:243-247` 一旦 `streamTookOver === true`,就**不再发送普通文本消息**。
|
|
135
|
+
|
|
136
|
+
关键假设是:流式帧 HTTP 成功就代表用户最终能看到内容。代码没有客户端投递确认,也没有在流式成功后补发普通文本。
|
|
137
|
+
|
|
138
|
+
### 3.3 状态显示
|
|
139
|
+
|
|
140
|
+
`index.ts:70` 的连接状态来自缓存的 `lastState`:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
`Connection: ${lastState}${stateDetail ? ` (${stateDetail})` : ""}`;
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
当前没有展示:
|
|
147
|
+
|
|
148
|
+
- 最后一次收到 QQ 入站消息的时间;
|
|
149
|
+
- 最后一次成功/失败出站的时间;
|
|
150
|
+
- 当前是否有 QQ agent run;
|
|
151
|
+
- 当前流式气泡状态;
|
|
152
|
+
- 心跳 ACK 年龄。
|
|
153
|
+
|
|
154
|
+
因此即使入站或出站已经失效,终端仍可能显示 `connected`。
|
|
155
|
+
|
|
156
|
+
### 3.4 短后台与长后台的差异
|
|
157
|
+
|
|
158
|
+
“短时间后台正常、长时间后台失败”把问题的主要变量指向手机端:
|
|
159
|
+
|
|
160
|
+
- **短时间后台**:QQ 进程仍在运行,或操作系统尚未冻结它;QQ 与服务器的连接仍在,机器人消息可以正常推送和显示。
|
|
161
|
+
- **长时间后台**:手机系统可能冻结或杀死 QQ 进程,QQ 进入离线状态;此时机器人发送的消息不会到达手机。重开后新消息仍能正常到达 pi(已确认)。
|
|
162
|
+
- 重新打开 QQ 后,客户端会重新连接并同步会话,但**离线期间由机器人产生的消息是否被保存/补发,取决于 QQ 平台和消息类型**。
|
|
163
|
+
- 普通聊天消息、机器人普通文本、机器人流式消息可能有不同的保存/补发策略。
|
|
164
|
+
|
|
165
|
+
电脑侧的 pi 一直在运行,只能证明“发送方正常”,不能证明“接收方在线”。HTTP 请求成功也不等于手机客户端最终展示了内容。
|
|
166
|
+
|
|
167
|
+
## 4. 已确认的代码与官方规则差异
|
|
168
|
+
|
|
169
|
+
### 4.1 C2C 被动回复窗口:代码 5 分钟,官方 60 分钟
|
|
170
|
+
|
|
171
|
+
官方规则([消息收发概述](https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/overview.html)):
|
|
172
|
+
|
|
173
|
+
- 单聊被动消息有效期:**60 分钟**;
|
|
174
|
+
- 每条消息最多回复 **4 次**;
|
|
175
|
+
- 主动消息可以被用户在 QQ 客户端关闭「允许主动发送」,关闭后主动消息发送失败。
|
|
176
|
+
|
|
177
|
+
当前代码:
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
// src/quota/reply-quota.ts:34
|
|
181
|
+
this.freshMs = opts?.freshMs ?? 5 * 60_000;
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
SDK 自带的 `ReplyLimiter` 默认 TTL 是 1 小时,与官方规则一致;pi-qq 额外设置的 5 分钟窗口是错误的。
|
|
185
|
+
|
|
186
|
+
影响范围需要精确区分:
|
|
187
|
+
|
|
188
|
+
- 流式消息始终携带原始 `msg_id`,不经过 `ReplyBudget.acquire()`,所以在 60 分钟内仍可能作为被动消息发送;
|
|
189
|
+
- 流式失败后的兜底文本、命令回复、附件失败提示会走 `sendReply`,超过 5 分钟后变成主动消息;
|
|
190
|
+
- 如果用户关闭了主动消息,这些内容会丢失,且只写本地日志。
|
|
191
|
+
|
|
192
|
+
### 4.2 流式消息没有普通文本兜底
|
|
193
|
+
|
|
194
|
+
`src/relay/bubble-writer.ts:207`:
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
this.pushedAny = true;
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
只要流式 HTTP 请求成功,就认为已经“推送过”。`run-stream-relay.ts:197` 返回成功后,`index.ts:247` 直接 `return`,不会再走 `sendReply`。
|
|
201
|
+
|
|
202
|
+
如果手机 QQ 在后台/离线期间没有收到流式帧,而 QQ 又没有为离线客户端保存或重放这些流式消息,那么重开手机后可能看不到任何内容;电脑侧却会记录发送成功。
|
|
203
|
+
|
|
204
|
+
官方流式消息文档没有承诺“接收方离线时保存/补发”,当前实现也没有做这个兜底。
|
|
205
|
+
|
|
206
|
+
### 4.3 `DONE` 帧内容为空
|
|
207
|
+
|
|
208
|
+
官方流式消息示例的最后一片:
|
|
209
|
+
|
|
210
|
+
```json
|
|
211
|
+
{
|
|
212
|
+
"input_mode": "replace",
|
|
213
|
+
"input_state": 10,
|
|
214
|
+
"index": 2,
|
|
215
|
+
"content_raw": "正在生成回答,请稍候。目前已完成全部内容,以下是最终结果。",
|
|
216
|
+
"msg_id": "...",
|
|
217
|
+
"stream_msg_id": "...",
|
|
218
|
+
"msg_seq": 1
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
当前 `src/relay/stream-session.ts:121-123`:
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
const content = state === "done" ? "" : this.buffer;
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
即 `input_state=10` 的 `DONE` 帧发送空内容。虽然前面的 `generating` 帧已经发送过正文,但如果接收方离线、只看到最终状态,或 QQ 只保留 `DONE` 帧的内容,就可能表现为最终消息为空。
|
|
229
|
+
|
|
230
|
+
这一点需要和官方接口行为一起验证。
|
|
231
|
+
|
|
232
|
+
### 4.4 `event_id` 与 `msg_id` 同时发送
|
|
233
|
+
|
|
234
|
+
官方文档说明 `event_id` 和 `msg_id` 二选一:
|
|
235
|
+
|
|
236
|
+
- `event_id`:被动回复事件 ID;
|
|
237
|
+
- `msg_id`:被动回复消息 ID。
|
|
238
|
+
|
|
239
|
+
当前 `src/relay/stream-session.ts` 对 C2C 消息同时设置了:
|
|
240
|
+
|
|
241
|
+
```ts
|
|
242
|
+
event_id: this.msgId,
|
|
243
|
+
msg_id: this.msgId,
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
这是不符合接口约定的用法。虽然目前大多数情况下能发送成功,但可能导致平台按不同路径校验被动有效期或去重,需要纳入验证。
|
|
247
|
+
|
|
248
|
+
### 4.5 没有启用 session persistence
|
|
249
|
+
|
|
250
|
+
`src/qq/qq-bot.ts:33` 创建 `QQBot` 时没有传入 `sessionPersistence`。如果 pi 进程重启,无法 RESUME 之前的网关会话;长时间断线后,QQ 也只会对短时间重连补发遗漏事件([事件订阅与通知](https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html))。
|
|
251
|
+
|
|
252
|
+
这与“电脑一直运行、没有重启”的本问题不是首要原因,但会影响进程重启场景。
|
|
253
|
+
|
|
254
|
+
## 5. 复现与证据
|
|
255
|
+
|
|
256
|
+
### 5.1 心跳 ACK 没有超时检测
|
|
257
|
+
|
|
258
|
+
本地用假网关复现:服务端发送 `HELLO` 和 `READY`,之后只接收心跳、不回 `HEARTBEAT_ACK`。700ms 后结果:
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
{ "identifies": 1, "heartbeats": 13, "readies": 1, "disconnects": 0, "errors": 0, "serverCloses": 0 }
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
结论:客户端发了 13 次心跳、没有收到 ACK,但仍然保持连接,没有触发断线或重连。
|
|
265
|
+
|
|
266
|
+
相关代码:
|
|
267
|
+
|
|
268
|
+
- `node_modules/@tencent-connect/qqbot-nodejs/dist/protocol/gateway/gateway-connection.js:267`:`HEARTBEAT_ACK` 直接 `break`;
|
|
269
|
+
- 同文件 `:347-351`:心跳只检查 `ws.readyState === WebSocket.OPEN`。
|
|
270
|
+
|
|
271
|
+
这个缺陷在电脑休眠、网络切换时最容易触发;本次用户明确说电脑没有休眠/切网,所以优先级下降,但不能完全排除 NAT/网关侧静默失效。
|
|
272
|
+
|
|
273
|
+
### 5.2 没有事故日志
|
|
274
|
+
|
|
275
|
+
当前配置 `~/.pi/agent/pi-qq.json` 是:
|
|
276
|
+
|
|
277
|
+
```json
|
|
278
|
+
{ "logLevel": "debug" }
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
但在当前工作区及常见目录下没有找到 `pi-qq-*.log`。可能原因:
|
|
282
|
+
|
|
283
|
+
- 事故发生在其他 cwd;
|
|
284
|
+
- 日志被清理;
|
|
285
|
+
- 当时的 bot 尚未启动或运行在其他进程。
|
|
286
|
+
|
|
287
|
+
需要下一次复现时保留 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。
|
|
288
|
+
|
|
289
|
+
## 6. 可能原因
|
|
290
|
+
|
|
291
|
+
### P0:iPhone 后台挂起 QQ 网络,期间输出未送达/未补发
|
|
292
|
+
|
|
293
|
+
用户确认:
|
|
294
|
+
|
|
295
|
+
- iPhone;
|
|
296
|
+
- 失败时 TUI 一直有新事件,说明 agent 并非静默;
|
|
297
|
+
- 长后台后新消息能到 pi,且机器人有回复;
|
|
298
|
+
- 好友普通消息能在重开后同步。
|
|
299
|
+
|
|
300
|
+
最符合的解释:
|
|
301
|
+
|
|
302
|
+
1. iPhone 在长时间后台后挂起或断开 QQ 的网络;
|
|
303
|
+
2. 期间 pi 仍在正常产生并发送输出,但手机没有收到;
|
|
304
|
+
3. 重开后 QQ 恢复了实时连接,所以新消息有回复;
|
|
305
|
+
4. 但离线期间的机器人消息没有被 QQ 保存/补发,好友普通消息则可以同步;
|
|
306
|
+
5. 用户看到旧任务“完全没有消息”。
|
|
307
|
+
|
|
308
|
+
需要日志确认:失败期间 `stream`/`outbound` 是否显示发送成功。如果发送成功,问题在平台侧离线保存;如果流式失败/熔断,则同时存在 relay 问题。
|
|
309
|
+
|
|
310
|
+
### P0:没有“下次入站补发”机制
|
|
311
|
+
|
|
312
|
+
即使手机离线是外部原因,pi-qq 也没有在用户回来时补发状态或输出:
|
|
313
|
+
|
|
314
|
+
- 没有记录离线期间的任务进度/输出摘要;
|
|
315
|
+
- 下一次入站时不会先回报“上次任务仍在运行/已完成”;
|
|
316
|
+
- 用户只能看到新消息的回复,无法知道旧任务执行到哪一步。
|
|
317
|
+
|
|
318
|
+
这是当前最直接可改进的点,而且不依赖 QQ 是否保存离线机器人消息。
|
|
319
|
+
|
|
320
|
+
### P1:relay/stream 在长任务中停止推送
|
|
321
|
+
|
|
322
|
+
如果 TUI 在后台期间仍有新事件,但 QQ 没有对应消息,则要怀疑 relay/stream:
|
|
323
|
+
|
|
324
|
+
- 流式消息在 60 分钟 `msg_id` 有效期后失效,后续帧全部失败;
|
|
325
|
+
- `AppendStream` 熔断后 `streamDead = true`,中间内容不再推送;
|
|
326
|
+
- 只有最终 `message_end` 的兜底文本可能补发,而长任务可能迟迟不结束;
|
|
327
|
+
- 新消息的回复可能走了另一条 fallback 路径,所以看起来“有回复”,但旧任务的输出仍然丢失。
|
|
328
|
+
|
|
329
|
+
需要结合 `stream` 日志和 TUI 事件时间判断。
|
|
330
|
+
|
|
331
|
+
### P1:流式没有普通文本终态兜底
|
|
332
|
+
|
|
333
|
+
如果任务最终在手机离线期间结束:
|
|
334
|
+
|
|
335
|
+
1. 最终输出通过 `/stream_messages` 发出;
|
|
336
|
+
2. 手机离线,未收到最后几帧;
|
|
337
|
+
3. `streamTookOver === true`,pi-qq 不再发送普通文本;
|
|
338
|
+
4. 重开后可能只剩空记录。
|
|
339
|
+
|
|
340
|
+
即使当前失败时 agent 仍在运行,这个问题也会在任务结束时出现,因此仍需要处理。
|
|
341
|
+
|
|
342
|
+
### P1:5 分钟窗口导致兜底文本变成主动消息
|
|
343
|
+
|
|
344
|
+
仅影响“超过 5 分钟没有新入站消息”时的回复。如果用户重开后发了新消息,预算会重置;但如果用户只是等待之前任务的结果,或者流式失败后走兜底文本,就会被这个窗口影响。
|
|
345
|
+
|
|
346
|
+
### P2:入站 WebSocket 静默失效(已排除)
|
|
347
|
+
|
|
348
|
+
用户已确认长时间后台后新消息能到达 pi,且机器人有回复,因此入站和实时出站均已排除。保留此项仅因为当前没有心跳 ACK 超时检测,未来仍可能在电脑休眠/网络切换时发生。
|
|
349
|
+
|
|
350
|
+
### P2:长时间断线不补发
|
|
351
|
+
|
|
352
|
+
QQ 只保证短时间重连的 RESUME 补发;长时间离线或会话失效后,漏掉的 `C2C_MESSAGE_CREATE` 不会补发。如果 pi 进程重启过,也没有 `sessionPersistence` 可恢复。
|
|
353
|
+
|
|
354
|
+
### P3:手机 QQ 客户端设置
|
|
355
|
+
|
|
356
|
+
- 机器人会话被收纳/静音;
|
|
357
|
+
- 聊天窗口出现“灵魂不在线”提示;
|
|
358
|
+
- 用户关闭了「允许主动发送」;
|
|
359
|
+
- 手机系统限制 QQ 后台网络。
|
|
360
|
+
|
|
361
|
+
这些需要手机端现场确认。
|
|
362
|
+
|
|
363
|
+
## 7. 待确认的现场信息
|
|
364
|
+
|
|
365
|
+
复现时请记录:
|
|
366
|
+
|
|
367
|
+
1. **后台时长阈值**
|
|
368
|
+
- 短时间后台(例如 1 分钟、5 分钟)是否正常;
|
|
369
|
+
- 从多久开始失败(10 分钟、30 分钟、1 小时);
|
|
370
|
+
- 息屏与切到其它 app 是否有区别。
|
|
371
|
+
2. **重开后是否发送了新消息**
|
|
372
|
+
- 新消息是否出现在电脑 pi 的 TUI;
|
|
373
|
+
- 是否产生 `inbound message` 日志;
|
|
374
|
+
- 机器人是否对这条新消息产生了 QQ 回复(而不只是 pi 收到)。
|
|
375
|
+
3. **聊天记录中是否有机器人历史输出**
|
|
376
|
+
- 完全没有;
|
|
377
|
+
- 只有部分气泡;
|
|
378
|
+
- 有完整内容但时间不对。
|
|
379
|
+
4. **对照普通好友消息**
|
|
380
|
+
- 长时间后台期间,好友发来的普通消息在重开后是否出现;
|
|
381
|
+
- 如果普通消息能同步、机器人消息不能,问题更偏向机器人消息的保存/补发,而不是手机网络。
|
|
382
|
+
5. **QQ 聊天窗口是否有提示**
|
|
383
|
+
- “灵魂不在线”;
|
|
384
|
+
- “机器人暂时无法回复”;
|
|
385
|
+
- 消息被折叠/收纳。
|
|
386
|
+
6. **任务进度(关键)**
|
|
387
|
+
- 失败时 TUI 的 agent 是运行中还是 idle(当前已确认是运行中);
|
|
388
|
+
- 后台期间 TUI 是否仍出现新的 tool/assistant 事件;
|
|
389
|
+
- 最后一条事件的时间和内容;
|
|
390
|
+
- 当前工具名、已运行时长;
|
|
391
|
+
- 是否长时间停在同一个工具/同一行;
|
|
392
|
+
- `/qq-status` 和 `/qq-test-budget` 的输出。
|
|
393
|
+
7. **日志**
|
|
394
|
+
- 最后一条 `gateway READY/RESUMED`;
|
|
395
|
+
- 最后一条 `Dispatch event: t=C2C_MESSAGE_CREATE`;
|
|
396
|
+
- `sent to pi`;
|
|
397
|
+
- `stream` 相关日志;
|
|
398
|
+
- `outbound` 相关日志和错误;
|
|
399
|
+
- 最后一条 `agent_start` / `agent_end` / `tool` 事件。
|
|
400
|
+
8. **iPhone 设置**
|
|
401
|
+
- 低电量模式是否开启;
|
|
402
|
+
- QQ 的后台 App 刷新/后台网络权限;
|
|
403
|
+
- 通知权限和机器人会话是否被收纳;
|
|
404
|
+
- 长后台后是否出现“灵魂不在线”。
|
|
405
|
+
|
|
406
|
+
## 8. 建议的验证实验
|
|
407
|
+
|
|
408
|
+
### 实验 0:短后台 / 长后台对照
|
|
409
|
+
|
|
410
|
+
固定使用同一种消息类型(先只用 `/qq-test-md`),分别让手机后台:
|
|
411
|
+
|
|
412
|
+
- 1 分钟;
|
|
413
|
+
- 10 分钟;
|
|
414
|
+
- 30 分钟;
|
|
415
|
+
- 1 小时。
|
|
416
|
+
|
|
417
|
+
每次重新打开 QQ 后记录是否能看到消息。目标是找到从“正常”变成“收不到”的时间阈值,并确认息屏、切换 app、系统清理后台是否有差异。
|
|
418
|
+
|
|
419
|
+
### 实验 A:确认入站是否正常
|
|
420
|
+
|
|
421
|
+
1. 手机 QQ 后台放置足以复现问题的时间;
|
|
422
|
+
2. 重新打开,发送一条纯文本 `ping`;
|
|
423
|
+
3. 观察电脑 TUI 是否出现这条消息,以及日志是否有 `inbound message`。
|
|
424
|
+
|
|
425
|
+
结果:
|
|
426
|
+
|
|
427
|
+
- TUI 没有:入站链路问题;
|
|
428
|
+
- TUI 有、但手机没有回复:出站或 agent 问题。
|
|
429
|
+
|
|
430
|
+
### 实验 B:普通文本 vs 流式消息
|
|
431
|
+
|
|
432
|
+
在手机保持后台时,从电脑 TUI 依次触发:
|
|
433
|
+
|
|
434
|
+
```text
|
|
435
|
+
/qq-test-md bg-md-test
|
|
436
|
+
/qq-test-stream
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
同时在后台期间让一位好友发一条普通 QQ 消息作为对照。记录时间,然后重新打开手机 QQ,比较:
|
|
440
|
+
|
|
441
|
+
- 好友普通消息是否出现;
|
|
442
|
+
- `/qq-test-md` 的普通 Markdown 消息是否出现;
|
|
443
|
+
- `/qq-test-stream` 的流式气泡是否出现;
|
|
444
|
+
- 是否只有第一个气泡或空内容。
|
|
445
|
+
|
|
446
|
+
结果:
|
|
447
|
+
|
|
448
|
+
- 好友消息出现、机器人消息不出现:问题偏向机器人消息的离线保存/补发;
|
|
449
|
+
- 普通文本出现、流式不出现:高度怀疑流式消息离线不可见/未落盘;
|
|
450
|
+
- 两者都不出现:更偏向连接、主动消息或客户端问题;
|
|
451
|
+
- 两者都出现:原始问题不在出站,需要回到入站/任务状态排查。
|
|
452
|
+
|
|
453
|
+
### 实验 C:主动消息窗口
|
|
454
|
+
|
|
455
|
+
1. 从手机发一条消息,确保最后一次入站在 6 分钟前;
|
|
456
|
+
2. 不发送新消息,直接从 TUI 触发 `/qq-test-md active-window-test`;
|
|
457
|
+
3. 检查手机 QQ 是否收到,以及日志是否显示 proactive。
|
|
458
|
+
|
|
459
|
+
同时检查 QQ 机器人资料卡的「允许主动发送」开关。
|
|
460
|
+
|
|
461
|
+
### 实验 D:长任务流式结束
|
|
462
|
+
|
|
463
|
+
运行一个持续超过 5 分钟但少于 60 分钟的任务,手机保持后台,任务结束后重开,检查:
|
|
464
|
+
|
|
465
|
+
- 是否看到完整流式结果;
|
|
466
|
+
- 是否只有部分气泡;
|
|
467
|
+
- 日志中 `DONE` 是否成功、`stream` 是否报错。
|
|
468
|
+
|
|
469
|
+
### 实验 E:后台期间任务完成(关键)
|
|
470
|
+
|
|
471
|
+
这是最贴近原始现象的实验:
|
|
472
|
+
|
|
473
|
+
1. 手机在前台,从 QQ 发一条会执行约 2-3 分钟的任务;
|
|
474
|
+
2. 看到任务开始输出后,把手机 QQ 切到后台;
|
|
475
|
+
3. 在电脑 TUI 等待 `agent_end` / 任务完成,期间不打开手机;
|
|
476
|
+
4. 任务完成后,再打开手机 QQ,检查聊天记录。
|
|
477
|
+
|
|
478
|
+
对照组:同样任务,手机保持前台直到完成。
|
|
479
|
+
|
|
480
|
+
结果:
|
|
481
|
+
|
|
482
|
+
- 前台完成能看到、后台完成看不到:问题在任务结束时的最终输出/流式落盘;
|
|
483
|
+
- 后台完成也能看到:需要检查任务是否真的在后台期间结束,或是否存在特定的流式错误/主动消息限制;
|
|
484
|
+
- 两边都看不到:问题不在“后台”本身,回到 agent 执行或通用出站。
|
|
485
|
+
|
|
486
|
+
### 实验 F:长静默阶段对照(辅助)
|
|
487
|
+
|
|
488
|
+
用户已确认失败时 TUI 一直有新事件,因此本实验降为辅助,仅用于验证“没有事件时是否也没有消息”。
|
|
489
|
+
|
|
490
|
+
1. 在 QQ 发一个会执行长时间、期间没有输出的工具任务(例如一个运行 5-10 分钟的 `bash` 命令);
|
|
491
|
+
2. 看到工具开始气泡后,把手机 QQ 切到后台;
|
|
492
|
+
3. 在电脑 TUI 观察工具是否仍在运行,记录最后事件时间;
|
|
493
|
+
4. 在工具未结束时重新打开手机 QQ,检查是否有新消息;
|
|
494
|
+
5. 再发一条新消息,确认机器人是否回复,以及回复是否与旧任务进度有关。
|
|
495
|
+
|
|
496
|
+
结果:
|
|
497
|
+
|
|
498
|
+
- TUI 没有新事件、QQ 也没有新消息:说明“运行中但静默”是正常行为,核心问题是缺少进度反馈;
|
|
499
|
+
- TUI 有新事件、QQ 没有:问题在 relay/stream;
|
|
500
|
+
- 新消息能回复、旧任务没有输出:进一步说明实时出站正常,旧任务只是没有可推送事件。
|
|
501
|
+
|
|
502
|
+
## 9. 解决方案
|
|
503
|
+
|
|
504
|
+
### 9.0 下次入站补发离线期间的状态/输出(推荐)
|
|
505
|
+
|
|
506
|
+
不依赖 QQ 是否保存离线机器人消息,改用“下一次入站”这条已经确认可用的通道:
|
|
507
|
+
|
|
508
|
+
- 记录最近一次/多次 QQ 任务的开始时间、状态、最后事件时间、当前工具和输出摘要;
|
|
509
|
+
- 下一次入站时,如果距上次入站超过阈值(例如 2 分钟)且期间有输出,先回复一条摘要,例如“你离开期间任务仍在运行/已完成;当前工具 bash,已运行 12 分钟;最近输出:……”;
|
|
510
|
+
- 提供 `/last` 命令:运行中重新推送当前输出;空闲时用流式推送最近一次完成 run 的最终文本;不缓存完整历史;
|
|
511
|
+
- 摘要要限制长度,并标记“离线期间可能未送达”,避免与用户已看到的内容重复;
|
|
512
|
+
- 这是最可靠的“回来后知道执行到哪一步”的方案。
|
|
513
|
+
|
|
514
|
+
### 9.1 修复被动回复窗口(低风险,优先)
|
|
515
|
+
|
|
516
|
+
将 `src/quota/reply-quota.ts` 的默认窗口从 5 分钟改为 60 分钟,直接使用 SDK `ReplyLimiter` 的 TTL 或与官方规则一致:
|
|
517
|
+
|
|
518
|
+
```ts
|
|
519
|
+
this.freshMs = opts?.freshMs ?? 60 * 60_000;
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
同步更新:
|
|
523
|
+
|
|
524
|
+
- `test/quota/reply-quota.test.ts` 的 5 分钟断言;
|
|
525
|
+
- `/qq-test-budget` 的 `msgId window` 诊断;
|
|
526
|
+
- README 中的被动回复说明(如有)。
|
|
527
|
+
|
|
528
|
+
### 9.2 增加流式结束后的持久化兜底(需要产品决策)
|
|
529
|
+
|
|
530
|
+
可选方案:
|
|
531
|
+
|
|
532
|
+
1. **始终补发最终普通文本**:流式成功后,再发送一次完整最终文本或摘要。
|
|
533
|
+
优点:离线用户一定能看到一份持久内容;缺点:在线用户会看到重复内容。
|
|
534
|
+
2. **可配置补发**:新增 `streamFinalText` 配置,默认关闭或开启由用户决定。
|
|
535
|
+
3. **长任务补发**:只对超过某个时长或流式帧数超过阈值的任务补发普通文本。
|
|
536
|
+
4. **使用 `DONE` 帧携带完整内容**:验证 `input_state=10` 时发送完整 `content_raw` 是否能让离线客户端恢复内容。这是最接近协议示例的修复,但需要实测。
|
|
537
|
+
5. **下一次入站时补发状态/摘要**:记录每个任务的状态和最终结果;当检测到距上次入站超过阈值(例如 10 分钟)时,在下一次入站回复前先发送“上次任务已完成/仍在运行”的摘要。这样即使手机在任务运行期间离线,用户重新发消息后也能知道执行结果。
|
|
538
|
+
|
|
539
|
+
建议先做实验 B,再决定是否采用“始终补发”。
|
|
540
|
+
|
|
541
|
+
### 9.3 修正流式请求字段
|
|
542
|
+
|
|
543
|
+
- 验证 `DONE` 帧是否应携带完整内容;
|
|
544
|
+
- 验证 `event_id` 与 `msg_id` 同时发送是否被平台接受;
|
|
545
|
+
- 按官方约定,C2C 消息回复只使用 `msg_id`,不发送伪造的 `event_id`。
|
|
546
|
+
|
|
547
|
+
### 9.4 出站失败可恢复
|
|
548
|
+
|
|
549
|
+
当前 `src/qq/reply-sender.ts` 在被动发送失败后只尝试一次主动发送;主动失败后仅写日志。建议:
|
|
550
|
+
|
|
551
|
+
- 增加待发送队列,保存失败内容;
|
|
552
|
+
- 在下一次入站消息到来时,以被动消息补发;
|
|
553
|
+
- 或者提示用户“有一条回复发送失败,请重试”;
|
|
554
|
+
- 日志中记录明确的失败原因,供 `/qq-status` 展示。
|
|
555
|
+
|
|
556
|
+
### 9.5 增强状态面板
|
|
557
|
+
|
|
558
|
+
在 `getStatusLines` 中增加:
|
|
559
|
+
|
|
560
|
+
- `Last inbound`: 最后一条 QQ 消息时间;
|
|
561
|
+
- `Last outbound`: 最后一条发送结果(成功/失败/主动降级);
|
|
562
|
+
- `Last task`: 最后一次 QQ 任务的状态(运行中/完成/失败)和结果摘要;
|
|
563
|
+
- `QQ run`: `runFeedback.isQQRunActive()`;
|
|
564
|
+
- `Stream`: 当前是否有活跃气泡、是否已熔断;
|
|
565
|
+
- `Gateway`: 最后 `ready/resumed/disconnected` 时间;
|
|
566
|
+
- 如能扩展 SDK,增加心跳 ACK 年龄。
|
|
567
|
+
|
|
568
|
+
终端 `/qq-status` 和 QQ `/status` 共用这些字段。这样即使手机收不到消息,用户也能从电脑端判断执行状态。
|
|
569
|
+
|
|
570
|
+
### 9.6 运行中进度反馈(当前最直接的改进)
|
|
571
|
+
|
|
572
|
+
当前失败场景是“agent 仍在运行,但没有可推送事件”。可以增加运行中的显式状态:
|
|
573
|
+
|
|
574
|
+
- `RunFeedback` 记录 `runStartedAt`、`lastEventAt`、`currentTool`、`currentStep`;
|
|
575
|
+
- 每次 tool/assistant 事件更新 `lastEventAt`;
|
|
576
|
+
- 定时检查:如果 run 仍活跃,且 `now - lastEventAt` 超过阈值(例如 5 分钟),发送一次状态消息,例如“⏳ 仍在执行:bash,已运行 12 分钟”;
|
|
577
|
+
- 下一次入站消息到达时,如果距上次入站/事件超过阈值,先回复“上次任务:运行中/已完成,当前工具…,已运行…”,再处理新消息;
|
|
578
|
+
- `/status` 和 `/qq-status` 展示同样的字段。
|
|
579
|
+
|
|
580
|
+
注意:
|
|
581
|
+
|
|
582
|
+
- 状态消息优先使用当前 `msg_id` 作为被动回复;超过 60 分钟后可能只能走主动消息;
|
|
583
|
+
- 应设置阈值并限制“每次静默期只发一次”,避免刷屏;
|
|
584
|
+
- 这是解决“无法判断执行状态”的直接手段,但不能修复真正的流式投递丢失。
|
|
585
|
+
|
|
586
|
+
### 9.7 SDK 心跳 ACK 超时(中期)
|
|
587
|
+
|
|
588
|
+
在 `qqbot-nodejs` 的 `GatewayConnection` 中:
|
|
589
|
+
|
|
590
|
+
- 记录 `lastHeartbeatAckAt`;
|
|
591
|
+
- 收到 `HEARTBEAT_ACK` 时更新;
|
|
592
|
+
- 心跳定时器检查 `now - lastHeartbeatAckAt > 2 * heartbeat_interval`;
|
|
593
|
+
- 超时后 `cleanup()` + `planReconnect()`,用 RESUME 恢复;
|
|
594
|
+
- 增加假网关测试:服务端停止 ACK 后必须触发重连。
|
|
595
|
+
|
|
596
|
+
这是入站链路的根本性加固,即使本次不是首要原因,也建议后续处理。
|
|
597
|
+
|
|
598
|
+
### 9.8 session persistence(可选)
|
|
599
|
+
|
|
600
|
+
为 `QQBot` 传入文件型 `sessionPersistence`,让 pi 进程重启后可以尝试 RESUME。注意:
|
|
601
|
+
|
|
602
|
+
- 长时间离线仍可能被平台判定 session 失效;
|
|
603
|
+
- 需要和 QR 登录/凭据生命周期一起设计;
|
|
604
|
+
- 不能解决手机离线期间消息不补发的问题。
|
|
605
|
+
|
|
606
|
+
## 10. 建议执行顺序
|
|
607
|
+
|
|
608
|
+
1. **先确认发送侧是否成功**:查失败期间 `stream`/`outbound` 日志,区分“消息已发送但手机离线未保存”和“relay/stream 停止推送”。
|
|
609
|
+
2. **实现下次入站补发 + 运行中进度反馈**:记录最近任务状态/输出摘要,用户回来发消息时先回报;这是当前最直接解决“无法判断执行状态”的改动,且不依赖 QQ 离线保存。
|
|
610
|
+
3. **修复 60 分钟窗口**:低风险、确定性高。
|
|
611
|
+
4. **决定是否补发最终普通文本**:流式结束后保留一份持久化终态;需要先验证 QQ 是否保存离线普通机器人消息。
|
|
612
|
+
5. **验证 `DONE` 内容与 `event_id` 字段**:需要真实 QQ 客户端配合。
|
|
613
|
+
6. **增强状态面板**:展示最后入站、最后出站、当前/最后一次任务状态。
|
|
614
|
+
7. **增加出站失败队列**:改善出站失败后的可恢复性。
|
|
615
|
+
8. **修 SDK 心跳 ACK 超时**:作为入站可靠性加固。
|
|
616
|
+
9. **评估 session persistence**:仅针对进程重启场景。
|
|
617
|
+
|
|
618
|
+
## 11. 参考
|
|
619
|
+
|
|
620
|
+
- QQ 机器人消息收发概述:https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/overview.html
|
|
621
|
+
- C2C 被动消息 60 分钟、4 次;
|
|
622
|
+
- 主动消息可被用户关闭。
|
|
623
|
+
- QQ 机器人流式发送单聊消息:https://bot.q.qq.com/wiki/develop/api-v2/autogen/api/v2_users_user_openid_stream_messages.post.html
|
|
624
|
+
- QQ 机器人事件订阅与通知:https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html
|
|
625
|
+
- 心跳 ACK;
|
|
626
|
+
- 短时间重连补发遗漏事件。
|
|
627
|
+
- QQ 机器人常见问题:https://bot.q.qq.com/wiki/bot_FAQ/
|
|
628
|
+
- “灵魂不在线”提示;
|
|
629
|
+
- 重启网关/重新连接建议。
|
|
630
|
+
- 本地 SDK:`node_modules/@tencent-connect/qqbot-nodejs/dist/protocol/gateway/gateway-connection.js`
|
|
631
|
+
- 本地源码仓库:`/home/chen/project/qqbot-nodejs`
|
|
632
|
+
|
|
633
|
+
## 12. 未决问题
|
|
634
|
+
|
|
635
|
+
1. QQ 是否会在接收方离线时保存并补发 `/stream_messages` 的最终内容?
|
|
636
|
+
2. 手机 QQ 长期后台后,是否仍保持与 QQ 服务器的长连接?
|
|
637
|
+
3. 用户关闭「允许主动发送」后,手机重开是否还能看到之前失败的主动消息?
|
|
638
|
+
4. `DONE` 帧空内容是否会导致离线客户端只看到空消息?
|
|
639
|
+
5. `event_id` 与 `msg_id` 同时发送是否会影响被动回复有效期或去重?
|
|
640
|
+
6. 失败期间的 `stream`/`outbound` 日志是发送成功、HTTP 失败,还是已经熔断?
|
|
641
|
+
7. 从“短后台正常”到“长后台失败”的时间阈值是多少?是否与 iPhone 的低电量模式/后台网络挂起策略有关?
|
|
642
|
+
8. 长时间后台期间,好友普通消息能同步,机器人普通文本和流式消息分别能否同步?
|
|
643
|
+
9. 离线期间产生的输出是否全部为流式消息?有没有普通文本终态?
|
|
644
|
+
10. 流式是否在 60 分钟 `msg_id` 有效期前就已经熔断?`stream` 日志最后一条是什么?
|
|
645
|
+
11. 下次入站摘要应包含哪些内容、阈值多少、是否需要 `/last` 查看完整输出?
|
|
646
|
+
|
|
647
|
+
这些问题的现场答案将决定最终修复范围。
|
|
648
|
+
|
|
649
|
+
## 13. 实现记录:`/last`
|
|
650
|
+
|
|
651
|
+
已实现第一版 QQ 侧 `/last` 命令,不缓存完整对话历史。
|
|
652
|
+
|
|
653
|
+
### 行为
|
|
654
|
+
|
|
655
|
+
只保留两种状态:
|
|
656
|
+
|
|
657
|
+
- **pi idle(已完成)**:用一个新的流式气泡推送最近一次完成 run 的最终 assistant 文本;
|
|
658
|
+
- **pi 运行中(未完成)**:重新绑定到 `/last` 消息的 `msg_id`,创建一个新的流式气泡,推送当前 run 的最新文本;后续 delta 继续写入这个新气泡。
|
|
659
|
+
|
|
660
|
+
边界情况:
|
|
661
|
+
|
|
662
|
+
- 运行中但还没有文本:不额外回复,等下一次可推送输出;
|
|
663
|
+
- idle 且没有完成的文本:回复 `No completed message yet.`;
|
|
664
|
+
- 重新推送只保证“当前文本 + 后续输出”,不保证补齐离线期间已经错过的所有历史气泡。
|
|
665
|
+
|
|
666
|
+
### 实现
|
|
667
|
+
|
|
668
|
+
- `src/relay/bubble-writer.ts`
|
|
669
|
+
- 新增 `restartText(text, target)`:关闭当前气泡(如仍有内容),切换到 `/last` 的 openid/msgId,重置流状态并创建新气泡,重新推送当前文本;流式已熔断时也会尝试恢复。
|
|
670
|
+
- `src/qq/reply-sender.ts`
|
|
671
|
+
- 新增 `sendStreamReply()`:用 `/last` 消息的 msgId 创建一个新的流式气泡并 DONE。
|
|
672
|
+
- `src/relay/run-stream-relay.ts`
|
|
673
|
+
- `RunState.currentText` 保存当前 run 的最新文本;
|
|
674
|
+
- `lastCompletedText` 保存最近一次完成 run 的最终文本;
|
|
675
|
+
- `getLastMessage()` 只返回最近完成文本;
|
|
676
|
+
- `repushCurrent(openid, msgId)` 在运行中重新绑定到 `/last` 消息并重新推送当前文本;不重写 `resultSentLen`,避免下一条 assistant 消息的开头被截掉;
|
|
677
|
+
- 流式已经熔断时仍更新 `currentText`,因此 `/last` 不依赖 stream 状态。
|
|
678
|
+
- `src/qq/inbound-command.ts`
|
|
679
|
+
- 用 `ctx.isIdle()` 分成两种状态;
|
|
680
|
+
- 运行中直接调用 `restartPush()`,不额外回复;
|
|
681
|
+
- idle 调用 `streamReply()` 推送最终文本,没有 streamReply 时回退到普通 reply。
|
|
682
|
+
- `src/qq/qq-message-handler.ts`
|
|
683
|
+
- 为 `/last` 提供基于当前消息的 `streamReply` 和 `repushCurrent`;stream 失败时回退到普通文本。
|
|
684
|
+
- `index.ts`
|
|
685
|
+
- 接入 `runFeedback.getLastMessage()` 和 `runFeedback.repushCurrent(openid, msgId)`。
|
|
686
|
+
- 测试:
|
|
687
|
+
- `test/relay/run-stream-relay.test.ts` 覆盖重新推送、最终文本和流式熔断;
|
|
688
|
+
- `test/qq/reply-sender.test.ts` 覆盖 `sendStreamReply` 的流式 DONE;
|
|
689
|
+
- `test/qq/qq-message-handler.test.ts` 覆盖两种状态和静默边界。
|
|
690
|
+
|
|
691
|
+
### 限制
|
|
692
|
+
|
|
693
|
+
- 只保留 assistant 文本,不包含 thinking/tool 历史;
|
|
694
|
+
- 已完成和未完成都走流式;已完成时使用当前 `/last` 消息的被动窗口,普通文本仅作为 stream 失败时的兜底;
|
|
695
|
+
- 重新推送的目标场景是“手机没有收到当前文本”;如果手机其实已经收到,再次执行 `/last` 会看到重复内容,这是手动恢复的预期结果,不属于本功能要解决的问题;
|
|
696
|
+
- 如果超过 60 分钟被动窗口或流式已经不可恢复,重新推送仍可能失败;
|
|
697
|
+
- 最近一次 run 如果没有文本,会保留上一条最新的 assistant 文本;
|
|
698
|
+
- 非 QQ 触发的本地 run 不在 `RunFeedback` 中,`/last` 可能只显示上一条 QQ 结果。
|
package/index.ts
CHANGED
|
@@ -114,6 +114,8 @@ export default function (pi: ExtensionAPI) {
|
|
|
114
114
|
getDeliverAs,
|
|
115
115
|
getFileMaxSize: () => activeSettings.fileMaxSize,
|
|
116
116
|
getStatusLines,
|
|
117
|
+
getLastMessage: () => runFeedback.getLastMessage(),
|
|
118
|
+
repushCurrent: (openid, msgId) => runFeedback.repushCurrent(openid, msgId),
|
|
117
119
|
onWarn: onWarn(ctx),
|
|
118
120
|
markQQTrigger: (openid, msgId) => runFeedback.markQQTrigger(openid, msgId),
|
|
119
121
|
waitForEnd: () => runFeedback.waitForEnd(),
|
package/package.json
CHANGED
|
@@ -15,14 +15,21 @@ export interface InboundCommandDeps {
|
|
|
15
15
|
pi: InboundPi;
|
|
16
16
|
ctx: InboundContext;
|
|
17
17
|
getStatusLines: () => string[];
|
|
18
|
+
getLastMessage?: () => string | undefined;
|
|
18
19
|
onStop?: () => void;
|
|
19
20
|
waitForEnd?: () => Promise<void>;
|
|
20
21
|
}
|
|
21
22
|
|
|
23
|
+
export interface InboundCommandExtras {
|
|
24
|
+
streamReply?: (text: string) => Promise<void>;
|
|
25
|
+
restartPush?: () => void;
|
|
26
|
+
}
|
|
27
|
+
|
|
22
28
|
export async function handleInboundCommand(
|
|
23
29
|
text: string,
|
|
24
30
|
reply: (t: string) => Promise<void>,
|
|
25
31
|
deps: InboundCommandDeps,
|
|
32
|
+
extras: InboundCommandExtras = {},
|
|
26
33
|
): Promise<void> {
|
|
27
34
|
const cmd = text.split(/\s+/)[0];
|
|
28
35
|
switch (cmd) {
|
|
@@ -33,6 +40,7 @@ export async function handleInboundCommand(
|
|
|
33
40
|
"• /stop — abort the current task",
|
|
34
41
|
"• /compact — compact the context",
|
|
35
42
|
"• /status — show status",
|
|
43
|
+
"• /last — push the last completed message or restart current output",
|
|
36
44
|
"• /new — reset the session",
|
|
37
45
|
"• /help — this help",
|
|
38
46
|
"Other text is sent to pi.",
|
|
@@ -60,6 +68,23 @@ export async function handleInboundCommand(
|
|
|
60
68
|
case "/status":
|
|
61
69
|
await reply(deps.getStatusLines().join("\n"));
|
|
62
70
|
break;
|
|
71
|
+
case "/last": {
|
|
72
|
+
if (!deps.ctx.isIdle()) {
|
|
73
|
+
extras.restartPush?.();
|
|
74
|
+
} else {
|
|
75
|
+
const text = deps.getLastMessage?.();
|
|
76
|
+
if (text) {
|
|
77
|
+
if (extras.streamReply) {
|
|
78
|
+
await extras.streamReply(text);
|
|
79
|
+
} else {
|
|
80
|
+
await reply(text);
|
|
81
|
+
}
|
|
82
|
+
} else {
|
|
83
|
+
await reply("No completed message yet.");
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
break;
|
|
87
|
+
}
|
|
63
88
|
case "/new":
|
|
64
89
|
if (!deps.ctx.isIdle()) {
|
|
65
90
|
await reply("Task is running; use /stop before resetting.");
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { QQBot, QQBotInboundMessage } from "@tencent-connect/qqbot-nodejs";
|
|
2
|
-
import { sendReply, type ReplyChannel } from "./reply-sender";
|
|
2
|
+
import { sendReply, sendStreamReply, type ReplyChannel } from "./reply-sender";
|
|
3
3
|
import type { ReplyBudget } from "../quota/reply-quota";
|
|
4
4
|
import { formatAttachmentFailures } from "../attachments/attachment-failure";
|
|
5
5
|
import {
|
|
@@ -18,6 +18,8 @@ export interface InboundDeps extends InboundCommandDeps {
|
|
|
18
18
|
getDeliverAs: () => "steer" | "followUp";
|
|
19
19
|
getFileMaxSize: () => number;
|
|
20
20
|
saveFiles?: typeof saveInboundFiles;
|
|
21
|
+
streamReply?: typeof sendStreamReply;
|
|
22
|
+
repushCurrent: (openid: string, msgId: string) => boolean;
|
|
21
23
|
onWarn: (msg: string) => void;
|
|
22
24
|
markQQTrigger: (openid: string, msgId: string) => void;
|
|
23
25
|
}
|
|
@@ -78,7 +80,27 @@ export function createInboundHandler(deps: InboundDeps) {
|
|
|
78
80
|
log.info("inbound", "cleared pending attachments for /new", { count: pending.count });
|
|
79
81
|
pending.clear();
|
|
80
82
|
}
|
|
81
|
-
await handleInboundCommand(contentText, reply, deps
|
|
83
|
+
await handleInboundCommand(contentText, reply, deps, {
|
|
84
|
+
streamReply: async (text) => {
|
|
85
|
+
try {
|
|
86
|
+
await (deps.streamReply ?? sendStreamReply)(
|
|
87
|
+
bot,
|
|
88
|
+
text,
|
|
89
|
+
{ openid: msg.senderId, msgId: msg.messageId },
|
|
90
|
+
deps.budget,
|
|
91
|
+
);
|
|
92
|
+
} catch (err) {
|
|
93
|
+
log.warn("inbound", "stream reply failed; falling back to text", {
|
|
94
|
+
messageId: msg.messageId,
|
|
95
|
+
err,
|
|
96
|
+
});
|
|
97
|
+
await reply(text);
|
|
98
|
+
}
|
|
99
|
+
},
|
|
100
|
+
restartPush: () => {
|
|
101
|
+
deps.repushCurrent(msg.senderId, msg.messageId);
|
|
102
|
+
},
|
|
103
|
+
});
|
|
82
104
|
return;
|
|
83
105
|
}
|
|
84
106
|
|
package/src/qq/reply-sender.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { QQBot } from "@tencent-connect/qqbot-nodejs";
|
|
2
2
|
import { ReplyBudget } from "../quota/reply-quota";
|
|
3
|
+
import { AppendStream } from "../relay/stream-session";
|
|
3
4
|
import { log } from "../infra/file-logger";
|
|
4
5
|
|
|
5
6
|
export const TEXT_CHUNK_LIMIT = 4500;
|
|
@@ -80,6 +81,28 @@ export interface ReplyChannel {
|
|
|
80
81
|
onWarn?: (msg: string) => void;
|
|
81
82
|
}
|
|
82
83
|
|
|
84
|
+
export interface StreamTarget {
|
|
85
|
+
openid: string;
|
|
86
|
+
msgId: string;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** Send a complete message as one new stream bubble. */
|
|
90
|
+
export async function sendStreamReply(
|
|
91
|
+
bot: QQBot,
|
|
92
|
+
text: string,
|
|
93
|
+
target: StreamTarget,
|
|
94
|
+
budget?: ReplyBudget,
|
|
95
|
+
): Promise<void> {
|
|
96
|
+
const stream = new AppendStream(bot.messageApi, bot.getCredentials(), target.openid, target.msgId);
|
|
97
|
+
budget?.noteStreamBubble(target.msgId);
|
|
98
|
+
try {
|
|
99
|
+
await stream.append(text);
|
|
100
|
+
await stream.done();
|
|
101
|
+
} finally {
|
|
102
|
+
stream.dispose();
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
83
106
|
export async function sendReply(bot: QQBot, text: string, ch: ReplyChannel): Promise<void> {
|
|
84
107
|
for (const chunk of chunkText(text)) {
|
|
85
108
|
const { mode, openid, msgId } = ch.budget.acquire();
|
|
@@ -93,6 +93,37 @@ export class BubbleWriter {
|
|
|
93
93
|
});
|
|
94
94
|
}
|
|
95
95
|
|
|
96
|
+
/**
|
|
97
|
+
* Start a fresh bubble and push the current text again, reviving a stream
|
|
98
|
+
* that died while the phone was offline. Later deltas continue in this bubble.
|
|
99
|
+
*/
|
|
100
|
+
restartText(text: string, target?: { openid: string; msgId: string }): void {
|
|
101
|
+
if (!text || this.disposed) return;
|
|
102
|
+
void this.enqueue(async () => {
|
|
103
|
+
if (this.disposed) return;
|
|
104
|
+
if (this.fenceOpen) await this.closeOpenFence();
|
|
105
|
+
if (this.cur) await this.rotateStream();
|
|
106
|
+
|
|
107
|
+
if (target) {
|
|
108
|
+
this.deps.openid = target.openid;
|
|
109
|
+
this.deps.msgId = target.msgId;
|
|
110
|
+
}
|
|
111
|
+
this.streamDead = false;
|
|
112
|
+
this.pendingResume = undefined;
|
|
113
|
+
this.resumeAttempts = 0;
|
|
114
|
+
this.lastKind = "none";
|
|
115
|
+
this.blockClosed = false;
|
|
116
|
+
this.toolOpen = false;
|
|
117
|
+
this.fenceOpen = false;
|
|
118
|
+
this.fenceLen = 0;
|
|
119
|
+
this.fenceQuoted = false;
|
|
120
|
+
this.lastChar = "";
|
|
121
|
+
this.thinkingAtLineStart = true;
|
|
122
|
+
this.bubbleChars = 0;
|
|
123
|
+
this.pushText(text);
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
|
|
96
127
|
async whenIdle(): Promise<void> {
|
|
97
128
|
await this.drainQueue();
|
|
98
129
|
}
|
|
@@ -25,6 +25,8 @@ interface RunState {
|
|
|
25
25
|
msgId?: string;
|
|
26
26
|
thinkingSentLen: number;
|
|
27
27
|
finalizedText: string;
|
|
28
|
+
/** Latest text of the current run, kept for the QQ /last command. */
|
|
29
|
+
currentText: string;
|
|
28
30
|
resultSentLen: number;
|
|
29
31
|
tools: ToolCall[];
|
|
30
32
|
activeTool?: string;
|
|
@@ -49,6 +51,7 @@ export class RunFeedback {
|
|
|
49
51
|
private pending: { openid: string; msgId: string; at: number } | null = null;
|
|
50
52
|
private recovery: { openid: string; msgId: string; at: number } | null = null;
|
|
51
53
|
private run: RunState | null = null;
|
|
54
|
+
private lastCompletedText: string | undefined;
|
|
52
55
|
private endPromise: Promise<void> = Promise.resolve();
|
|
53
56
|
private endResolve?: () => void;
|
|
54
57
|
|
|
@@ -73,6 +76,32 @@ export class RunFeedback {
|
|
|
73
76
|
return this.run ? this.endPromise : Promise.resolve();
|
|
74
77
|
}
|
|
75
78
|
|
|
79
|
+
/**
|
|
80
|
+
* The final assistant text of the most recently completed QQ run.
|
|
81
|
+
* No transcript is retained.
|
|
82
|
+
*/
|
|
83
|
+
getLastMessage(): string | undefined {
|
|
84
|
+
return this.lastCompletedText;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Restart the current run's push with its latest text. This revives a stream
|
|
89
|
+
* that may have died while the phone was offline; later deltas continue.
|
|
90
|
+
*/
|
|
91
|
+
repushCurrent(openid: string, msgId: string): boolean {
|
|
92
|
+
const run = this.run;
|
|
93
|
+
const text = run?.currentText;
|
|
94
|
+
if (!run || !text?.trim()) return false;
|
|
95
|
+
// Rebind to the /last message so the new stream has a fresh passive window.
|
|
96
|
+
run.openid = openid;
|
|
97
|
+
run.msgId = msgId;
|
|
98
|
+
// Push the current text in full. Do not rewrite resultSentLen: it belongs to
|
|
99
|
+
// the assistant message currently being diffed, and changing it could drop
|
|
100
|
+
// the beginning of the next message.
|
|
101
|
+
run.writer.restartText(text, { openid, msgId });
|
|
102
|
+
return true;
|
|
103
|
+
}
|
|
104
|
+
|
|
76
105
|
onAgentStart(): void {
|
|
77
106
|
this.endPromise = new Promise((resolve) => {
|
|
78
107
|
this.endResolve = resolve;
|
|
@@ -105,6 +134,7 @@ export class RunFeedback {
|
|
|
105
134
|
msgId: target.msgId,
|
|
106
135
|
thinkingSentLen: 0,
|
|
107
136
|
finalizedText: "",
|
|
137
|
+
currentText: "",
|
|
108
138
|
resultSentLen: 0,
|
|
109
139
|
tools: [],
|
|
110
140
|
deferredThinking: "",
|
|
@@ -143,21 +173,25 @@ export class RunFeedback {
|
|
|
143
173
|
|
|
144
174
|
onAssistantDelta(snapshotText: string, snapshotThinking: string): void {
|
|
145
175
|
const run = this.run;
|
|
146
|
-
if (!run
|
|
176
|
+
if (!run) return;
|
|
177
|
+
|
|
178
|
+
const full = [run.finalizedText, snapshotText].filter((part) => part.trim()).join("\n\n");
|
|
179
|
+
if (full.trim()) run.currentText = full;
|
|
180
|
+
|
|
181
|
+
if (run.writer.dead) return;
|
|
147
182
|
|
|
148
183
|
if (snapshotThinking.length > run.thinkingSentLen) {
|
|
149
|
-
const
|
|
184
|
+
const thinkingDelta = snapshotThinking.slice(run.thinkingSentLen);
|
|
150
185
|
run.thinkingSentLen = snapshotThinking.length;
|
|
151
186
|
if (this.deps.getThinkingRelay()) {
|
|
152
187
|
if (this.hasPendingTools(run)) {
|
|
153
|
-
run.deferredThinking +=
|
|
188
|
+
run.deferredThinking += thinkingDelta;
|
|
154
189
|
} else {
|
|
155
|
-
run.writer.pushThinking(
|
|
190
|
+
run.writer.pushThinking(thinkingDelta);
|
|
156
191
|
}
|
|
157
192
|
}
|
|
158
193
|
}
|
|
159
194
|
|
|
160
|
-
const full = [run.finalizedText, snapshotText].filter((part) => part.trim()).join("\n\n");
|
|
161
195
|
const delta = full.slice(run.resultSentLen);
|
|
162
196
|
if (!delta) return;
|
|
163
197
|
run.resultSentLen = full.length;
|
|
@@ -173,6 +207,7 @@ export class RunFeedback {
|
|
|
173
207
|
if (!run) return false;
|
|
174
208
|
|
|
175
209
|
run.finalizedText = [run.finalizedText, text].filter((part) => part.trim()).join("\n\n");
|
|
210
|
+
if (text.trim()) run.currentText = text;
|
|
176
211
|
const delta = run.finalizedText.slice(run.resultSentLen);
|
|
177
212
|
run.resultSentLen = run.finalizedText.length;
|
|
178
213
|
if (!isError && text && delta) {
|
|
@@ -207,6 +242,7 @@ export class RunFeedback {
|
|
|
207
242
|
if (!this.hasPendingTools(run)) this.flushDeferred(run);
|
|
208
243
|
await run.writer.whenIdle();
|
|
209
244
|
this.clearTimers();
|
|
245
|
+
if (run.currentText.trim()) this.lastCompletedText = run.currentText;
|
|
210
246
|
if (!run.hadError && run.writer.hasPushed) this.recovery = null;
|
|
211
247
|
this.run = null;
|
|
212
248
|
log.debug("run", "ended", {
|
|
@@ -230,6 +266,7 @@ export class RunFeedback {
|
|
|
230
266
|
this.run = null;
|
|
231
267
|
this.pending = null;
|
|
232
268
|
this.recovery = null;
|
|
269
|
+
this.lastCompletedText = undefined;
|
|
233
270
|
this.finishEnd();
|
|
234
271
|
}
|
|
235
272
|
|