@chen_hu_hu/pi-qq 1.0.0 → 1.0.2
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.md +70 -104
- package/doc/{features.md → features-v1.md} +55 -92
- package/doc/{plan.md → plan-v1.md} +38 -43
- package/index.ts +111 -159
- package/package.json +2 -2
- package/src/append-stream.ts +21 -20
- package/src/bot.ts +23 -23
- package/src/budget-status.ts +9 -9
- package/src/config.ts +22 -80
- package/src/download.ts +3 -3
- package/src/files.ts +9 -9
- package/src/format.ts +6 -1
- package/src/images.ts +6 -6
- package/src/inbound.ts +12 -19
- package/src/login.ts +19 -20
- package/src/outbound.ts +22 -22
- package/src/qrcode-terminal.d.ts +1 -1
- package/src/reply-budget.ts +15 -15
- package/src/run-feedback.ts +70 -75
- package/src/usage.ts +0 -93
package/README.md
CHANGED
|
@@ -1,135 +1,101 @@
|
|
|
1
1
|
# pi-qq
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
> 手机 QQ 上发消息(文字/图片/文件)→ pi 在机器上干活 → 完整回复(Markdown → 纯文本)+ 用量摘要回传到 QQ。
|
|
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.
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
## 功能特性
|
|
9
|
-
|
|
10
|
-
- **扫码登录 / 配置直连**:`/qq-login` 扫码即用(自动换取凭据并绑定单人),或在配置文件写入 `AppID`/`AppSecret` 免扫码直连
|
|
11
|
-
- **单人聊天**:绑定用户私聊消息直接进入 pi 会话(含图片/文件),白名单外的消息完全隔离
|
|
12
|
-
- **完整回复**:assistant 消息实时回传(流式追加 / 降级分块),Markdown 转手机可读纯文本
|
|
13
|
-
- **长任务反馈**:"正在输入"保鲜 + 每 10s 汇总工具调用 + 节流心跳(`⏱ 已运行 25 分钟 · [86] 🔧 bash · [12] 🔧 read`),数十分钟级任务不再黑盒等待
|
|
14
|
-
- **用量摘要**:每次 QQ 任务后回传本次 run 的输入(含缓存命中率)、输出与上下文占比,严格三行
|
|
15
|
-
- **发送图片/文件**:QQ 端发图自动注入 pi;QQ 端发文件保存到当前工作空间 `.pi/pi-qq/`,并把路径写入提示词(图片默认 10MB、文件默认 50MB)
|
|
16
|
-
- **诊断命令**:`/qq-md`、`/qq-stream-test`、`/qq-budget` 快速验证平台能力与额度
|
|
17
|
-
|
|
18
|
-
架构与决策记录见 [doc/features.md](./doc/features.md),实施计划与验收见 [doc/plan.md](./doc/plan.md)。
|
|
19
|
-
|
|
20
|
-
## 快速开始
|
|
21
|
-
|
|
22
|
-
### 从 npm / Pi 市场安装(推荐)
|
|
5
|
+
## Install
|
|
23
6
|
|
|
24
7
|
```bash
|
|
25
8
|
pi install npm:@chen_hu_hu/pi-qq
|
|
26
9
|
```
|
|
27
10
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
### 本地开发
|
|
31
|
-
|
|
32
|
-
#### 1. 安装依赖
|
|
11
|
+
For local development:
|
|
33
12
|
|
|
34
13
|
```bash
|
|
35
|
-
|
|
14
|
+
pi --extension /path/to/pi-qq
|
|
36
15
|
```
|
|
37
16
|
|
|
38
|
-
|
|
17
|
+
## Login
|
|
39
18
|
|
|
40
|
-
|
|
19
|
+
1. Start pi.
|
|
20
|
+
2. Run `/qq-login`.
|
|
21
|
+
3. Scan the QR code with mobile QQ.
|
|
41
22
|
|
|
42
|
-
|
|
43
|
-
{
|
|
44
|
-
"AppID": "你的 AppID",
|
|
45
|
-
"AppSecret": "你的 AppSecret"
|
|
46
|
-
}
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
**方式 B:扫码登录** — pi 中执行 `/qq-login`,用手机 QQ 扫码,凭据自动写回同一文件,
|
|
50
|
-
扫码人的 openid 自动绑定为"单人"白名单。
|
|
23
|
+
Credentials are kept in process memory only. Restarting pi requires scanning again. `/qq-logout` clears the in-memory credentials immediately.
|
|
51
24
|
|
|
52
|
-
|
|
25
|
+
## Usage
|
|
53
26
|
|
|
54
|
-
|
|
55
|
-
pi --extension /path/to/pi-qq
|
|
56
|
-
# 或放入用户扩展目录,所有会话自动加载:
|
|
57
|
-
ln -s /path/to/pi-qq ~/.pi/agent/extensions/pi-qq
|
|
58
|
-
```
|
|
27
|
+
Send a QQ private message to the bot to start a task.
|
|
59
28
|
|
|
60
|
-
|
|
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.
|
|
61
32
|
|
|
62
|
-
|
|
33
|
+
Example file prompt seen by pi:
|
|
63
34
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
| `allowedOpenid` | 扫码自动写入 | 单人绑定的 openid;手动配置时缺省则首个私聊用户自动绑定 |
|
|
68
|
-
| `streamAssistant` | `true` | assistant 流式回传开关(关闭则整条回复完成后一次性发送) |
|
|
69
|
-
| `markdownSupport` | `false` | 机器人是否有 markdown 权限;`true` 时回传透传原始 Markdown |
|
|
70
|
-
| `usageRelay` | `true` | 本次 run 的输入/缓存命中率/输出/上下文摘要开关 |
|
|
71
|
-
| `deliverAs` | `"steer"` | agent 忙碌时新消息的处理方式:`steer` 并入当前任务 / `followUp` 排队 |
|
|
72
|
-
| `imageMaxSize` | `10485760` | QQ 图片下载上限(字节,默认 10MB) |
|
|
73
|
-
| `fileMaxSize` | `52428800` | QQ 文件下载上限(字节,默认 50MB) |
|
|
74
|
-
| `heartbeatMinutes` | `10` | 长任务心跳间隔(分钟),`0` 关闭 |
|
|
75
|
-
| `heartbeatMaxMessages` | `3` | 每 run 消息心跳上限(流式心跳不受限) |
|
|
76
|
-
| `streamRelay` | `true` | 流式载体(append 追加语义);关闭则心跳与结果全走普通消息 |
|
|
77
|
-
| `streamFlushMs` | `10000` | 流式汇总帧间隔(毫秒,最小 300;默认每 10s 汇总工具调用) |
|
|
78
|
-
| `debug` | `false` | 诊断模式:SDK 日志 + 流式限流重试/超时日志 + 文本帧时间戳 |
|
|
79
|
-
|
|
80
|
-
## 命令
|
|
81
|
-
|
|
82
|
-
| 位置 | 命令 | 行为 |
|
|
83
|
-
| --- | --- | --- |
|
|
84
|
-
| pi 侧 | `/qq-login` | 扫码登录/换绑 |
|
|
85
|
-
| pi 侧 | `/qq-status` | 登录态、连接状态、绑定用户 |
|
|
86
|
-
| pi 侧 | `/qq-budget` | 诊断:被动额度、流式气泡数、最近 msgId 新鲜度 |
|
|
87
|
-
| pi 侧 | `/qq-logout` | 清除凭据并断开 |
|
|
88
|
-
| pi 侧 | `/qq-md [text]` | 诊断:验证 C2C markdown 渲染能力 |
|
|
89
|
-
| pi 侧 | `/qq-stream-test` | 诊断:追加模式流式全链路验证 |
|
|
90
|
-
| QQ 侧 | `/new` `/stop` `/compact` `/status` `/help` | 会话控制(`/new` 会通过扩展命令重置会话) |
|
|
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)
|
|
91
38
|
|
|
92
|
-
|
|
39
|
+
User message:
|
|
40
|
+
Summarize this file.
|
|
41
|
+
```
|
|
93
42
|
|
|
94
|
-
|
|
43
|
+
## Commands
|
|
95
44
|
|
|
96
|
-
|
|
97
|
-
[活动气泡:💭思考/[n]🔧工具计数] ← streamRelay 开启时,每 10s 汇总
|
|
98
|
-
[文本气泡:assistant 消息原文] ← 每条文本消息独立成泡
|
|
99
|
-
[活动气泡:后续工具汇总]
|
|
100
|
-
[文本气泡:最终回复原文]
|
|
101
|
-
📊 用量摘要
|
|
102
|
-
• 输入:4.1k (99.9%)
|
|
103
|
-
• 输出:2.3k
|
|
104
|
-
• 上下文:0.4%
|
|
105
|
-
```
|
|
45
|
+
Run these in the pi terminal:
|
|
106
46
|
|
|
107
|
-
|
|
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-test-budget` | Show passive-reply budget and stream-bubble diagnostics |
|
|
53
|
+
| `/qq-test-md [text]` | Send a Markdown test message |
|
|
54
|
+
| `/qq-test-stream` | Run a streamed timeline diagnostic |
|
|
55
|
+
| `/qq-new` | Reset the current session (used by QQ `/new`) |
|
|
108
56
|
|
|
109
|
-
|
|
110
|
-
npm install # 安装依赖(prettier / vitest 为 devDependencies)
|
|
111
|
-
npm run typecheck # 类型检查
|
|
112
|
-
npm test # vitest(8 个测试文件 / 81 个测试)
|
|
113
|
-
npm run format # Prettier 格式化
|
|
114
|
-
npm run format:check # Prettier 校验
|
|
115
|
-
```
|
|
57
|
+
QQ-side commands:
|
|
116
58
|
|
|
117
|
-
|
|
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 context status |
|
|
65
|
+
| `/help` | Show command help |
|
|
118
66
|
|
|
119
|
-
|
|
120
|
-
`config`(配置读写)/ `login`(扫码)/ `bot`(生命周期)/ `inbound`(QQ→pi)/
|
|
121
|
-
`outbound`(pi→QQ 文本)/ `reply-budget`(被动回复额度)/ `budget-status`(`/qq-budget` 格式化)/ `run-feedback`(长任务反馈)/
|
|
122
|
-
`append-stream`(追加模式流式发送器)/ `usage`(token 累计与用量摘要)/ `images`(QQ 图片下载与校验)/
|
|
123
|
-
`files`(QQ 文件落盘与提示词路径)/ `download`(附件限流下载)/ `format`(字节格式化)。
|
|
67
|
+
## Settings
|
|
124
68
|
|
|
125
|
-
|
|
69
|
+
Create `~/.pi/agent/pi-qq.json` to override defaults. This file contains settings only; credentials are never written to it.
|
|
126
70
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"markdownSupport": false,
|
|
74
|
+
"streamFlushMs": 10000,
|
|
75
|
+
"debug": false
|
|
76
|
+
}
|
|
77
|
+
```
|
|
132
78
|
|
|
133
|
-
|
|
79
|
+
| Key | Default | Description |
|
|
80
|
+
| --- | --- | --- |
|
|
81
|
+
| `streamAssistant` | `true` | Stream assistant replies |
|
|
82
|
+
| `markdownSupport` | `false` | Bot has QQ Markdown permission; pass Markdown through |
|
|
83
|
+
| `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
|
|
84
|
+
| `imageMaxSize` | `10485760` | QQ image download limit in bytes (10MB) |
|
|
85
|
+
| `fileMaxSize` | `52428800` | QQ file download limit in bytes (50MB) |
|
|
86
|
+
| `heartbeatMinutes` | `10` | Long-task heartbeat interval; `0` disables |
|
|
87
|
+
| `heartbeatMaxMessages` | `3` | Per-run message heartbeat limit |
|
|
88
|
+
| `streamRelay` | `true` | Use append-mode stream bubbles |
|
|
89
|
+
| `streamFlushMs` | `10000` | Stream summary frame interval in ms (minimum 300) |
|
|
90
|
+
| `debug` | `false` | SDK and stream retry/timeout diagnostics |
|
|
91
|
+
|
|
92
|
+
## Notes
|
|
93
|
+
|
|
94
|
+
- Only C2C (QQ private chat) is supported.
|
|
95
|
+
- Incoming images are passed to the model as vision input; the current model must support image input.
|
|
96
|
+
- Saved files are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
|
|
97
|
+
- QQ limits passive replies per inbound message. Use `/qq-test-budget` to inspect the local budget.
|
|
98
|
+
|
|
99
|
+
## License
|
|
134
100
|
|
|
135
101
|
MIT
|
|
@@ -1,14 +1,14 @@
|
|
|
1
|
-
# pi-qq — features.md
|
|
1
|
+
# pi-qq — features-v1.md
|
|
2
2
|
|
|
3
3
|
> pi 扩展:通过 QQ 机器人把 pi 接入 QQ 单人私聊(C2C)。
|
|
4
|
-
> 手机 QQ
|
|
4
|
+
> 手机 QQ 上发消息(含图片/文件)→ pi 在机器上干活 → 完整回复(Markdown → 纯文本)回传到 QQ;上下文占比可通过 `/status` 查看。
|
|
5
5
|
|
|
6
6
|
技术栈:
|
|
7
7
|
|
|
8
8
|
| 依赖 | 用途 |
|
|
9
9
|
| --- | --- |
|
|
10
10
|
| `@tencent-connect/qqbot-nodejs` | QQ 开放平台协议层:WebSocket Gateway、C2C 消息收发、媒体上传、流式消息 |
|
|
11
|
-
| `@tencent-connect/qqbot-connector` |
|
|
11
|
+
| `@tencent-connect/qqbot-connector` | 扫码登录:展示二维码,扫码后换取 `appId / appSecret / userOpenid`(仅内存) |
|
|
12
12
|
| `@earendil-works/pi-coding-agent`(ExtensionAPI) | pi 扩展宿主:事件订阅、命令注册、消息注入、上下文用量 |
|
|
13
13
|
|
|
14
14
|
---
|
|
@@ -35,41 +35,28 @@ pi-qq 扩展 ── pi.sendUserMessage(text+images) ─┴─ pi 事件:
|
|
|
35
35
|
|
|
36
36
|
## 2. 核心功能
|
|
37
37
|
|
|
38
|
-
### F1
|
|
38
|
+
### F1 扫码登录(仅扫码)
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
**目标**:唯一登录方式是 `/qq-login` 扫码;凭据只保存在进程内存,绝不落盘。pi 进程退出后必须重新扫码。
|
|
41
41
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
用户预先在 `~/.pi/agent/pi-qq.json` 写入:
|
|
45
|
-
|
|
46
|
-
```json
|
|
47
|
-
{
|
|
48
|
-
"AppID": "...",
|
|
49
|
-
"AppSecret": "..."
|
|
50
|
-
}
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
- 规则(已确认):配置文件中存在有效凭据 → 启动时直接构造 `QQBot` 接入,**无需扫码**;否则进入扫码流程。
|
|
54
|
-
- 读取时兼容小写 `appId` / `appSecret`;文件中其余配置项(§4)可共存。
|
|
55
|
-
- 手动配置时若未填 `allowedOpenid`:第一个发来 C2C 私聊的用户自动绑定为单人用户(写入配置并在 pi 侧提示),也可手动预先填写。
|
|
56
|
-
|
|
57
|
-
**方式 B:扫码登录**
|
|
42
|
+
**行为**
|
|
58
43
|
|
|
59
44
|
1. 用户在 pi 中执行 `/qq-login`。
|
|
60
|
-
2.
|
|
61
|
-
- `onQrDisplayed(url)`:TUI
|
|
62
|
-
- `onQrExpired()
|
|
63
|
-
- `onSuccess([{ appId, appSecret, userOpenid }])
|
|
64
|
-
3.
|
|
65
|
-
4. 立即构造 `QQBot`
|
|
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` 立即清除内存凭据并断开连接;之后可重新扫码。
|
|
66
53
|
|
|
67
54
|
**通用**
|
|
68
55
|
|
|
69
|
-
- `/qq-status
|
|
70
|
-
- `/qq-
|
|
71
|
-
-
|
|
72
|
-
-
|
|
56
|
+
- `/qq-status`、`/qq-login`、`/qq-logout`、`/qq-test-budget`、`/qq-test-md`、`/qq-test-stream`、`/qq-new` 的命令说明与 pi 终端输出均为英文。
|
|
57
|
+
- `/qq-status` 显示登录状态(in memory)、连接状态、模型、上下文与绑定用户;AppID 仅显示前 4 位 + `****`。
|
|
58
|
+
- 配置文件 `~/.pi/agent/pi-qq.json` 只保存非敏感设置;旧的 `AppID` / `AppSecret` / `allowedOpenid` 键会被忽略,不再用于登录。
|
|
59
|
+
- 白名单只接受扫码绑定的 openid;未登录时入站消息直接忽略。
|
|
73
60
|
|
|
74
61
|
### F2 单人聊天
|
|
75
62
|
|
|
@@ -77,7 +64,7 @@ pi-qq 扩展 ── pi.sendUserMessage(text+images) ─┴─ pi 事件:
|
|
|
77
64
|
|
|
78
65
|
**行为**
|
|
79
66
|
|
|
80
|
-
- 仅接受 `kind === "c2c"` 的入站消息;发送者 openid
|
|
67
|
+
- 仅接受 `kind === "c2c"` 的入站消息;发送者 openid 必须等于本次扫码绑定的内存白名单(复用 SDK `accessPolicy`,其他用户静默忽略)。入站消息的 `senderId` 即发送者的 openid。
|
|
81
68
|
- 普通文本 → `pi.sendUserMessage(text)`,触发正常 agent run。
|
|
82
69
|
- 图片消息的处理见 F3(QQ → pi)。
|
|
83
70
|
- agent 忙碌时收到新消息 → 按 `deliverAs`(默认 `steer`,可配置 `followUp`)排队。
|
|
@@ -108,13 +95,14 @@ pi-qq 扩展 ── pi.sendUserMessage(text+images) ─┴─ pi 事件:
|
|
|
108
95
|
- 一条消息多个文件按原顺序保存;部分失败时成功的文件仍保留并给出失败清单。
|
|
109
96
|
- 提示词中追加文件块,例如:
|
|
110
97
|
```text
|
|
111
|
-
|
|
112
|
-
- /home/chen/project/myproj/.pi/pi-qq/2026-10-29/xxx/report.pdf
|
|
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)
|
|
113
100
|
|
|
114
|
-
|
|
101
|
+
User message:
|
|
115
102
|
帮我总结这个文件
|
|
116
103
|
```
|
|
117
104
|
- 纯文件消息(无文字)也会触发 run,提示词只含文件块;文件内容不直接注入 LLM,由 pi 用工具按需读取。
|
|
105
|
+
- **实测**:2026-10-29 用户已验证 QQ 发送文件后保存到工作空间 `.pi/pi-qq/`,提示词中的路径可正常关联。
|
|
118
106
|
|
|
119
107
|
### F4 回传 assistant 消息
|
|
120
108
|
|
|
@@ -135,37 +123,14 @@ pi-qq 扩展 ── pi.sendUserMessage(text+images) ─┴─ pi 事件:
|
|
|
135
123
|
- **非流式/降级**:`sendText` 一次性发送。
|
|
136
124
|
- `stopReason === "error"` 时回传错误摘要而非静默。
|
|
137
125
|
|
|
138
|
-
### F5
|
|
139
|
-
|
|
140
|
-
**数据源**:本次 agent run 的 `event.messages` 中 assistant 与 toolResult 的 `usage`(`input`、`cacheRead`、`cacheWrite`、`output`)。
|
|
141
|
-
|
|
142
|
-
**行为**
|
|
143
|
-
|
|
144
|
-
- 每次 **QQ 触发且成功完成**的 agent run 结束(`agent_end`)发送一条严格三行摘要(本地终端 run、错误/中止的 run 不发,避免消耗主动额度或重试刷屏):
|
|
145
|
-
|
|
146
|
-
```
|
|
147
|
-
📊 用量摘要
|
|
148
|
-
• 输入:4.1k (99.9%)
|
|
149
|
-
• 输出:2.3k
|
|
150
|
-
• 上下文:0.4%
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
- **输入** = 本次 run 累计总输入(`input + cacheRead + cacheWrite`)。
|
|
154
|
-
- **括号百分比** = 本次 run 累计缓存命中率(`cacheRead / 总输入`),保留一位小数;无缓存时显示 `0.0%`。
|
|
155
|
-
- **输出** = 本次 run 累计输出。
|
|
156
|
-
- 不展示成本、本轮、上下文绝对值;严格保持三行。
|
|
157
|
-
- 与 F6 合并为一条消息发送,避免刷屏。
|
|
126
|
+
### F5/F6 用量摘要(已移除)
|
|
158
127
|
|
|
159
|
-
|
|
128
|
+
每轮 QQ 对话后的 token 用量摘要已取消:
|
|
160
129
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
- 与 F5 同条消息的第三行:`• 上下文:0.4%`。
|
|
166
|
-
- `tokens === null`(压缩后尚未产生新响应)时显示 `重建中`。
|
|
167
|
-
- `percent` 缺失时按 `tokens / contextWindow` 计算。
|
|
168
|
-
- 严格三行格式,不追加 `/compact` 文字提示(百分比已可见)。
|
|
130
|
+
- 不再在 `agent_end` 发送 `📊 用量摘要`。
|
|
131
|
+
- 上下文占比通过 QQ 侧 `/status` 或 pi 终端 `/qq-status` 查看。
|
|
132
|
+
- 不展示 token、缓存命中率、成本;减少一条被动回复消息。
|
|
133
|
+
- `usageRelay` 配置项已移除(旧配置键会被忽略)。
|
|
169
134
|
|
|
170
135
|
### F7 长任务反馈(10~60 分钟级任务)
|
|
171
136
|
|
|
@@ -174,26 +139,26 @@ pi-qq 扩展 ── pi.sendUserMessage(text+images) ─┴─ pi 事件:
|
|
|
174
139
|
**行为**:**assistant 文本消息与思考/工具汇总使用独立气泡**——每条文本消息独占一个纯文本气泡(同一消息的流式增量续写),思考/工具行组进入活动气泡;文本前后的工具执行均另起活动气泡;最终回复独立成文本气泡。`streamRelay` 默认开,实测可用;气泡内按 `streamFlushMs`(默认 10000ms,最小 300)固定频率发送窗口汇总帧(工具调用每 10s 汇总一次):
|
|
175
140
|
|
|
176
141
|
```
|
|
177
|
-
[活动气泡] 💭
|
|
178
|
-
[活动气泡] [3]
|
|
179
|
-
[活动气泡] [2]
|
|
142
|
+
[活动气泡] [💭] Thinking...
|
|
143
|
+
[活动气泡] [🔧] [3] bash
|
|
144
|
+
[活动气泡] [🔧] [2] read
|
|
180
145
|
|
|
181
146
|
[文本气泡] 中间消息原文
|
|
182
147
|
|
|
183
|
-
[活动气泡] [1]
|
|
148
|
+
[活动气泡] [🔧] [1] edit
|
|
184
149
|
|
|
185
150
|
[文本气泡] 最终回复原文(流式增量)
|
|
186
151
|
```
|
|
187
152
|
|
|
188
|
-
- **汇总帧内容**(窗口增量,间隔 `streamFlushMs` 默认 10000ms;`agent_end` 补发剩余并收 DONE
|
|
153
|
+
- **汇总帧内容**(窗口增量,间隔 `streamFlushMs` 默认 10000ms;`agent_end` 补发剩余并收 DONE)。活动气泡帧:**debug 模式下行首带 `[HH:MM:SS]` 时间戳**,普通模式不带时间戳。行组**严格按事件实际发生顺序**输出:思考状态行 `[💭] Thinking...` 与工具计数行 `[🔧] [n] name` 按到达顺序交错;连续同名工具合并为一条计数,不改变相对顺序。文本气泡帧:原始 Markdown 增量(流式帧按 markdown 渲染),debug 模式才加时间戳以免插断回答。工具总在 message_end 后执行,故文本消息与其后工具天然分入不同气泡。
|
|
189
154
|
- **排版规则**:活动气泡内行与行相邻不空行;文本气泡内续写直接拼接;文本与工具不再混排。
|
|
190
155
|
- **气泡边界**:文本消息的**首个增量**到达 → 封口当前活动气泡,开文本气泡;思考/工具行组到达 → 封口当前文本气泡,开或续活动气泡;同一消息的后续流式增量不切泡;最终回复独立成文本气泡。
|
|
191
156
|
- **事件映射**:`tool_execution_start` → 窗口计数;`message_update`(thinking/text)→ 窗口状态/快照;`message_end` → 文本定稿;`agent_end` → 补帧 + DONE。AppendStream 内部仍有 500ms 节流与限流退避作安全网。
|
|
192
157
|
- **额度提示**:每条文本消息、每段活动各占一条 msg_seq 消息;长回合任务的气泡数多于单气泡模式,需关注被动额度;若平台拒绝(帧失败),该回合自动降级消息路径,文本仍完整送达。
|
|
193
158
|
- **降级**:任何一帧失败即标 dead,已追加部分作废,未发出的结果文本自动转消息路径补发;`streamRelay: false` 时整条时间线关闭,assistant 消息走普通消息路径(M2 行为)。
|
|
194
159
|
- **typing 保鲜**:run 开始立即发送"正在输入",之后每 50s 续期(0 额度),`agent_end` 清理。
|
|
195
|
-
- **空窗口活性线**:窗口无增量且静默 ≥60s 时补一条
|
|
196
|
-
- **心跳兜底**:流不可用时降级为普通消息心跳(每 run ≤3
|
|
160
|
+
- **空窗口活性线**:窗口无增量且静默 ≥60s 时补一条 `⏱ 已运行 X 分钟…`——长思考/单工具长执行期间每分钟一行,不再无推送(debug 模式带时间戳)。
|
|
161
|
+
- **心跳兜底**:流不可用时降级为普通消息心跳(每 run ≤3 条保险丝;debug 模式带时间戳)。
|
|
197
162
|
- 不发送"已收到"开始确认(节省被动额度):QQ 触发的 run 在首个汇总帧前保持安静。
|
|
198
163
|
- 非 QQ 触发的 run(本地终端)不发心跳/时间线,但 assistant 消息仍照常回传(现状)。
|
|
199
164
|
|
|
@@ -203,25 +168,22 @@ QQ 开放平台的发送限制直接决定回传策略,必须统一管理:
|
|
|
203
168
|
|
|
204
169
|
| 限制 | 数值 | 应对 |
|
|
205
170
|
| --- | --- | --- |
|
|
206
|
-
| 被动回复额度 | 每条入站消息 5 分钟内有效,约 4 条/小时 | 扩展内维护回复预算(复用 SDK `ReplyLimiter` 思路);assistant
|
|
171
|
+
| 被动回复额度 | 每条入站消息 5 分钟内有效,约 4 条/小时 | 扩展内维护回复预算(复用 SDK `ReplyLimiter` 思路);assistant 时间线按文本/活动分泡 |
|
|
207
172
|
| 主动消息 | 无 `msgId` 发送受平台额度限制 | 被动额度耗尽时才降级为主动发送,且给出明确提示 |
|
|
208
173
|
| 流式消息 | 仅 C2C;节流 ≥300ms;基于 5 分钟内 `msgId` | 流式仅用于 assistant 文本;无关联 `msgId` 时自动降级 `sendText` |
|
|
209
174
|
| 文本长度 | 单条 ~5000 字符 | SDK 分块;超出部分按序发送 |
|
|
210
175
|
| markdown | 默认无权限(`markdownSupport: false`) | Markdown → 纯文本降级渲染 |
|
|
211
176
|
|
|
212
|
-
**合并规则**(默认):assistant 文本消息与活动时间线严格分泡(每条文本消息 1
|
|
177
|
+
**合并规则**(默认):assistant 文本消息与活动时间线严格分泡(每条文本消息 1 条纯文本气泡,工具间隔另起活动气泡);不再发送用量摘要,上下文占比通过 `/status` 查询。气泡数随回合内文本消息数增长,需关注 `msgId` 的被动额度;若平台拒绝(帧失败),自动降级消息路径。工具调用过程本身不逐条回传。
|
|
213
178
|
|
|
214
179
|
## 4. 配置
|
|
215
180
|
|
|
216
|
-
`~/.pi/agent/pi-qq.json
|
|
181
|
+
`~/.pi/agent/pi-qq.json`(只保存设置;不含凭据、不写入登录信息):
|
|
217
182
|
|
|
218
183
|
| 字段 | 默认 | 说明 |
|
|
219
184
|
| --- | --- | --- |
|
|
220
|
-
| `AppID` / `AppSecret` | 手动填写或扫码写入 | 机器人凭据(`0600` 保护);存在即免扫码直连(兼容小写 `appId` / `appSecret`) |
|
|
221
|
-
| `allowedOpenid` | 扫码自动写入;手动配置时可选(缺省首个私聊用户绑定) | 单人绑定的 openid |
|
|
222
185
|
| `streamAssistant` | `true` | assistant 流式回传开关 |
|
|
223
186
|
| `markdownSupport` | `false` | 机器人是否有 markdown 权限;`true` 时回传透传 Markdown |
|
|
224
|
-
| `usageRelay` | `true` | 本次 run 的 token/缓存命中率/上下文占比摘要开关 |
|
|
225
187
|
| `deliverAs` | `"steer"` | 忙碌时新消息的处理方式 |
|
|
226
188
|
| `imageMaxSize` | `10MB` | QQ 图片下载上限 |
|
|
227
189
|
| `fileMaxSize` | `50MB` | QQ 文件下载上限 |
|
|
@@ -229,27 +191,27 @@ QQ 开放平台的发送限制直接决定回传策略,必须统一管理:
|
|
|
229
191
|
| `heartbeatMaxMessages` | `3` | F7 每 run 消息心跳上限(流式心跳不受限) |
|
|
230
192
|
| `streamRelay` | `true` | F7 流式载体开关(append 追加 + 节流合帧 + 限流退避,实测可用;失败自动降级消息路径) |
|
|
231
193
|
| `streamFlushMs` | `10000`(最小 300) | F7 流式汇总帧间隔(毫秒,默认每 10s 汇总工具调用) |
|
|
232
|
-
| `debug` | `false` | 诊断模式:SDK 日志转终端 +
|
|
194
|
+
| `debug` | `false` | 诊断模式:SDK 日志转终端 + 流式重试/超时日志 + 行组/文本帧时间戳 |
|
|
233
195
|
|
|
234
196
|
## 5. 命令总表
|
|
235
197
|
|
|
236
198
|
| 位置 | 命令 | 行为 |
|
|
237
199
|
| --- | --- | --- |
|
|
238
|
-
| pi 侧 | `/qq-login` |
|
|
200
|
+
| pi 侧 | `/qq-login` | 扫码登录并绑定(QR only) |
|
|
239
201
|
| pi 侧 | `/qq-status` | 登录态、连接状态、绑定用户 |
|
|
240
|
-
| pi 侧 | `/qq-budget` | 诊断:被动额度、流式气泡数、最近 msgId 新鲜度 |
|
|
241
|
-
| pi 侧 | `/qq-logout` |
|
|
242
|
-
| pi 侧 | `/qq-
|
|
243
|
-
| pi 侧 | `/qq-md [text]` | 诊断:发送 Markdown 消息,验证 C2C markdown 渲染能力 |
|
|
244
|
-
| pi 侧 | `/qq-stream
|
|
202
|
+
| pi 侧 | `/qq-test-budget` | 诊断:被动额度、流式气泡数、最近 msgId 新鲜度 |
|
|
203
|
+
| pi 侧 | `/qq-logout` | 清除内存凭据并断开 |
|
|
204
|
+
| pi 侧 | `/qq-new` | 重置当前会话(QQ `/new` 调用) |
|
|
205
|
+
| pi 侧 | `/qq-test-md [text]` | 诊断:发送 Markdown 消息,验证 C2C markdown 渲染能力 |
|
|
206
|
+
| pi 侧 | `/qq-test-stream` | 诊断:开流→三帧→complete,验证流式帧是否渲染 |
|
|
245
207
|
| QQ 侧 | `/new` `/stop` `/compact` `/status` `/help` | 会话控制(见 F2) |
|
|
246
208
|
|
|
247
209
|
## 6. 可靠性与安全
|
|
248
210
|
|
|
249
|
-
- **生命周期**:`session_start`
|
|
211
|
+
- **生命周期**:`session_start` 仅在进程内存有登录态时启动;`session_shutdown` 幂等关闭。SDK 默认无限重连(退避 1s→60s),4914/4915 致命关闭码上报为不可恢复,提示重新 `/qq-login`。
|
|
250
212
|
- **回声与去重**:启用 SDK `messageFilter`(跳过 bot 回声)与 `concurrencyGuard`(同用户串行),避免流式与回复互相踩踏。
|
|
251
213
|
- **安全**:
|
|
252
|
-
-
|
|
214
|
+
- 凭据仅保存在进程内存、不落盘;日志与 `/qq-status` 脱敏;扩展以 pi 同等权限运行,白名单外的消息不进入 pi(不产生任何工具执行)。
|
|
253
215
|
- QQ 侧无 shell 类命令;一切工具执行都经由 pi 自身权限体系。
|
|
254
216
|
|
|
255
217
|
## 7. 决策记录
|
|
@@ -257,12 +219,12 @@ QQ 开放平台的发送限制直接决定回传策略,必须统一管理:
|
|
|
257
219
|
| # | 问题 | 决策 |
|
|
258
220
|
| --- | --- | --- |
|
|
259
221
|
| 1 | TUI 二维码渲染 | 登录协议用 connector;展示用 `qrcode-terminal`(零依赖)在 `ctx.ui` 弹窗画码 |
|
|
260
|
-
| 2 | thinking 内容 | 不回传具体内容(始终剔除,无配置开关);F7 时间线中仅以
|
|
261
|
-
| 3 | tool 消息 |
|
|
222
|
+
| 2 | thinking 内容 | 不回传具体内容(始终剔除,无配置开关);F7 时间线中仅以 `[💭] Thinking...` 标记体现 |
|
|
223
|
+
| 3 | tool 消息 | **完全不回传**;只回传 assistant 消息,上下文占比通过 `/status` 查询 |
|
|
262
224
|
| 4 | 图片方向 | F3 为 QQ → pi(用户发图给 pi);pi 不向 QQ 发图片(LLM 仅输出纯文本) |
|
|
263
|
-
| 5 |
|
|
225
|
+
| 5 | 成本/用量摘要 | 已移除每轮用量摘要;不展示 token、缓存命中率、成本 |
|
|
264
226
|
| 6 | 回复格式 | 回复通常为 Markdown 格式的总结/提问文本(不在回复中写代码);默认轻量转纯文本,有 markdown 权限可透传 |
|
|
265
|
-
| 7 | 登录方式 |
|
|
227
|
+
| 7 | 登录方式 | 仅 `/qq-login` 扫码;凭据只存进程内存、不落盘;pi 进程退出后必须重新扫码 |
|
|
266
228
|
| 8 | 长任务反馈 | typing 保鲜 + 每 10s 汇总工具调用 + 节流心跳(默认 10 分钟/条,流式载体优先,每 run ≤3 条消息心跳保险丝)+ 机会性流式(平台拒绝即降级);不发送开始确认 |
|
|
267
229
|
| 9 | 流式可用性(实测三轮) | ① C2C markdown(msg_type=2,`sendMarkdown`)渲染正常;② SDK 内置流式 `input_mode="replace"` 被平台拒绝("已经提交的消息内容不可修改"),首帧可渲染、后续帧报错;③ 自实现 `AppendStream`(input_mode="append",增量追加 + DONE)实测通过;补齐节流合帧(500ms)与限流退避重试后**默认开启**,失败自动降级消息路径 |
|
|
268
230
|
|
|
@@ -270,7 +232,8 @@ QQ 开放平台的发送限制直接决定回传策略,必须统一管理:
|
|
|
270
232
|
|
|
271
233
|
| 阶段 | 内容 | 验收 |
|
|
272
234
|
| --- | --- | --- |
|
|
273
|
-
| M1 | F1
|
|
235
|
+
| M1 | F1 扫码登录 + 内存凭据 + 连接启动 | 扫码后 `/qq-status` 在线;重启 pi 需重新扫码 |
|
|
274
236
|
| M2 | F2 单人聊天 + F4 assistant 回传(先非流式) | QQ 发消息得到 pi 回复 |
|
|
275
|
-
| M3 | F5/F6 用量摘要(本次 run 输入/缓存命中率/输出/上下文) | 严格三行摘要正确呈现 |
|
|
276
237
|
| M4 | F3 QQ 图片/文件消息 + markdownSupport + 打磨 | 图片可进入 pi 会话;文件保存并关联到提示词 |
|
|
238
|
+
|
|
239
|
+
> 原 M3 用量摘要已取消(2026-10-29)。
|