@chen_hu_hu/pi-qq 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/README.md +134 -2
- package/doc/features.md +276 -0
- package/doc/plan.md +195 -0
- package/index.ts +403 -0
- package/package.json +61 -4
- package/src/append-stream.ts +165 -0
- package/src/bot.ts +99 -0
- package/src/budget-status.ts +32 -0
- package/src/config.ts +136 -0
- package/src/download.ts +88 -0
- package/src/files.ts +138 -0
- package/src/format.ts +6 -0
- package/src/images.ts +137 -0
- package/src/inbound.ts +164 -0
- package/src/login.ts +97 -0
- package/src/outbound.ts +135 -0
- package/src/qrcode-terminal.d.ts +5 -0
- package/src/reply-budget.ts +123 -0
- package/src/run-feedback.ts +422 -0
- package/src/usage.ts +93 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 CQ-Developer
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,135 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pi-qq
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> pi 扩展:通过 QQ 机器人把 [pi](https://github.com/earendil-works/pi) 接入 QQ 单人私聊(C2C)。
|
|
4
|
+
> 手机 QQ 上发消息(文字/图片/文件)→ pi 在机器上干活 → 完整回复(Markdown → 纯文本)+ 用量摘要回传到 QQ。
|
|
5
|
+
|
|
6
|
+
基于腾讯官方 SDK [`@tencent-connect/qqbot-nodejs`](https://www.npmjs.com/package/@tencent-connect/qqbot-nodejs) 与 [`@tencent-connect/qqbot-connector`](https://www.npmjs.com/package/@tencent-connect/qqbot-connector)。
|
|
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 市场安装(推荐)
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pi install npm:@chen_hu_hu/pi-qq
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
包内已声明 `pi-package` 关键字与 `pi.extensions`,发布后可在 [Pi package gallery](https://pi.dev/packages) 中搜索到。
|
|
29
|
+
|
|
30
|
+
### 本地开发
|
|
31
|
+
|
|
32
|
+
#### 1. 安装依赖
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm install
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
#### 2. 登录机器人(二选一)
|
|
39
|
+
|
|
40
|
+
**方式 A:配置直连(推荐)** — 写入 `~/.pi/agent/pi-qq.json` 后启动 pi 自动连接:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"AppID": "你的 AppID",
|
|
45
|
+
"AppSecret": "你的 AppSecret"
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
**方式 B:扫码登录** — pi 中执行 `/qq-login`,用手机 QQ 扫码,凭据自动写回同一文件,
|
|
50
|
+
扫码人的 openid 自动绑定为"单人"白名单。
|
|
51
|
+
|
|
52
|
+
#### 3. 本地加载扩展
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pi --extension /path/to/pi-qq
|
|
56
|
+
# 或放入用户扩展目录,所有会话自动加载:
|
|
57
|
+
ln -s /path/to/pi-qq ~/.pi/agent/extensions/pi-qq
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## 配置项
|
|
61
|
+
|
|
62
|
+
`~/.pi/agent/pi-qq.json`(手动配置或扫码写入,同一文件;除凭据外均可省略):
|
|
63
|
+
|
|
64
|
+
| 字段 | 默认 | 说明 |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| `AppID` / `AppSecret` | 无 | 机器人凭据(文件权限 `0600`);存在即免扫码直连(兼容小写 `appId`/`appSecret`) |
|
|
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` 会通过扩展命令重置会话) |
|
|
91
|
+
|
|
92
|
+
## 一个回合的消息形态
|
|
93
|
+
|
|
94
|
+
QQ 用户每个回合看到的消息(确认已移除;文本与工具汇总严格分泡,末尾附用量摘要):
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
[活动气泡:💭思考/[n]🔧工具计数] ← streamRelay 开启时,每 10s 汇总
|
|
98
|
+
[文本气泡:assistant 消息原文] ← 每条文本消息独立成泡
|
|
99
|
+
[活动气泡:后续工具汇总]
|
|
100
|
+
[文本气泡:最终回复原文]
|
|
101
|
+
📊 用量摘要
|
|
102
|
+
• 输入:4.1k (99.9%)
|
|
103
|
+
• 输出:2.3k
|
|
104
|
+
• 上下文:0.4%
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## 开发
|
|
108
|
+
|
|
109
|
+
```bash
|
|
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
|
+
```
|
|
116
|
+
|
|
117
|
+
单测位于 `test/*.test.ts`(vitest),`npm run typecheck` 同时检查测试代码。
|
|
118
|
+
|
|
119
|
+
模块划分与事件接线见 [doc/plan.md](./doc/plan.md);src/ 下每个模块单一职责:
|
|
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`(字节格式化)。
|
|
124
|
+
|
|
125
|
+
## 已知平台限制(实测)
|
|
126
|
+
|
|
127
|
+
- **流式必须用追加语义**:SDK 内置的 `input_mode="replace"` 被平台拒绝("已经提交的消息内容不可修改"),
|
|
128
|
+
本项目自实现 append 模式(增量追加 + DONE),见 `src/append-stream.ts`
|
|
129
|
+
- **被动回复额度**:每条入站消息约 4 条/小时、msgId 约 5 分钟内有效;超限自动降级主动发送
|
|
130
|
+
- **主动消息有严格配额**:长任务的心跳默认走流式(0 额度),消息心跳有保险丝(每 run ≤3 条)
|
|
131
|
+
- 流式帧内容类型固定为 markdown(`sendMarkdown` 同理);无 markdown 渲染能力的场景请关闭 `streamRelay`
|
|
132
|
+
|
|
133
|
+
## 许可
|
|
134
|
+
|
|
135
|
+
MIT
|
package/doc/features.md
ADDED
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
# pi-qq — features.md
|
|
2
|
+
|
|
3
|
+
> pi 扩展:通过 QQ 机器人把 pi 接入 QQ 单人私聊(C2C)。
|
|
4
|
+
> 手机 QQ 上发消息(含图片)→ pi 在机器上干活 → 完整回复(Markdown → 纯文本)+ token 用量与上下文占比回传到 QQ。
|
|
5
|
+
|
|
6
|
+
技术栈:
|
|
7
|
+
|
|
8
|
+
| 依赖 | 用途 |
|
|
9
|
+
| --- | --- |
|
|
10
|
+
| `@tencent-connect/qqbot-nodejs` | QQ 开放平台协议层:WebSocket Gateway、C2C 消息收发、媒体上传、流式消息 |
|
|
11
|
+
| `@tencent-connect/qqbot-connector` | 扫码登录(方式 B):展示二维码,扫码后换取 `appId / appSecret / userOpenid` |
|
|
12
|
+
| `@earendil-works/pi-coding-agent`(ExtensionAPI) | pi 扩展宿主:事件订阅、命令注册、消息注入、上下文用量 |
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. 总体架构
|
|
17
|
+
|
|
18
|
+
扩展以**目录形式**加载进 pi(`index.ts` + `package.json`),在 pi 进程内运行 QQBot 客户端:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
手机 QQ(单人用户)
|
|
22
|
+
│ C2C 私聊(WebSocket Gateway)
|
|
23
|
+
▼
|
|
24
|
+
QQBot(@tencent-connect/qqbot-nodejs,扩展内持有)
|
|
25
|
+
│ bot.on("message") ▲ bot.sendText / openStream(纯文本)
|
|
26
|
+
▼ │
|
|
27
|
+
pi-qq 扩展 ── pi.sendUserMessage(text+images) ─┴─ pi 事件:
|
|
28
|
+
(QQ → pi 注入) message_update / message_end /
|
|
29
|
+
agent_end / ctx.getContextUsage()
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- **QQ → pi**:入站 C2C 消息经白名单校验后,通过 `pi.sendUserMessage()` 注入 pi(文本 + 图片附件转 `ImageContent`)。
|
|
33
|
+
- **pi → QQ**:订阅 pi 生命周期事件,格式化后经 `bot.sendText / openStream` 回传(纯文本)。
|
|
34
|
+
- 生命周期:`session_start` 启动 bot、`session_shutdown` 幂等关闭;WebSocket 断线重连由 SDK 负责。
|
|
35
|
+
|
|
36
|
+
## 2. 核心功能
|
|
37
|
+
|
|
38
|
+
### F1 登录接入(配置直连 / 扫码)
|
|
39
|
+
|
|
40
|
+
**目标**:两种方式接入机器人,凭据统一存放在 `~/.pi/agent/pi-qq.json`(权限 `0600`)。
|
|
41
|
+
|
|
42
|
+
**方式 A:配置文件直连(免扫码)**
|
|
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:扫码登录**
|
|
58
|
+
|
|
59
|
+
1. 用户在 pi 中执行 `/qq-login`。
|
|
60
|
+
2. 扩展调用 `startQrConnect({ displayQrCodeToConsole: false, signal })`:
|
|
61
|
+
- `onQrDisplayed(url)`:TUI 模式下用 `qrcode-terminal`(零依赖)把 `url` 画成 ASCII 二维码嵌入 `ctx.ui` 弹窗;非 TUI 模式直接打印 URL。
|
|
62
|
+
- `onQrExpired()`:提示"二维码已过期,已自动刷新"。
|
|
63
|
+
- `onSuccess([{ appId, appSecret, userOpenid }])`:进入下一步。
|
|
64
|
+
3. 凭据按方式 A 的 schema 写回 `~/.pi/agent/pi-qq.json`,`userOpenid` 写入默认单人绑定。`userOpenid` 即**扫码人的 openid**:QQ 开放平台用户的机器人内唯一标识(非 QQ 号,平台不向机器人暴露真实 QQ 号);谁扫码绑定,谁就是允许对话的"单人",写入 `allowedOpenid` 作为白名单。
|
|
65
|
+
4. 立即构造 `QQBot` 并启动;未扫码完成前可随时取消(`stop()` / AbortSignal)。
|
|
66
|
+
|
|
67
|
+
**通用**
|
|
68
|
+
|
|
69
|
+
- `/qq-status` 显示登录方式、凭据来源、绑定用户、连接状态;`/qq-logout` 清除凭据并断开。
|
|
70
|
+
- `/qq-login` 始终可用:已直连时重新扫码换绑。
|
|
71
|
+
- 职责划分:connector 负责**登录协议**(生成绑定任务、轮询、解密凭据),二维码绘制只是展示层;M1 允许先用 connector 自带控制台打印(`displayQrCodeToConsole: true`)跑通,再优化 TUI 弹窗(直接 console 打印会破坏 pi TUI 渲染)。
|
|
72
|
+
- 凭据脱敏:日志与 `/qq-status` 中只显示 `AppID` 前几位。
|
|
73
|
+
|
|
74
|
+
### F2 单人聊天
|
|
75
|
+
|
|
76
|
+
**目标**:只有一个绑定的用户能与机器人对话,消息进入 pi 会话。
|
|
77
|
+
|
|
78
|
+
**行为**
|
|
79
|
+
|
|
80
|
+
- 仅接受 `kind === "c2c"` 的入站消息;发送者 openid 必须等于配置的 `allowedOpenid`(复用 SDK `accessPolicy` 白名单中间件,其他用户静默忽略)。入站消息的 `senderId` 即发送者的 openid。
|
|
81
|
+
- 普通文本 → `pi.sendUserMessage(text)`,触发正常 agent run。
|
|
82
|
+
- 图片消息的处理见 F3(QQ → pi)。
|
|
83
|
+
- agent 忙碌时收到新消息 → 按 `deliverAs`(默认 `steer`,可配置 `followUp`)排队。
|
|
84
|
+
- QQ 侧控制命令(在进入 pi 前拦截):
|
|
85
|
+
- `/new` 新会话、`/stop` 中止当前 run(`ctx.abort()`)、`/compact` 压缩上下文(`ctx.compact()`)、`/status` 会话与用量状态、`/help` 命令帮助。
|
|
86
|
+
- agent 工作期间向 QQ 发送 typing 提示(SDK `sendTyping`,C2C only)。
|
|
87
|
+
|
|
88
|
+
### F3 发送图片与文件(QQ → pi)
|
|
89
|
+
|
|
90
|
+
**目标**:用户在 QQ 上把图片或文件发给 pi;图片作为视觉输入,文件保存到本机并在提示词中给出路径。
|
|
91
|
+
|
|
92
|
+
**图片行为**
|
|
93
|
+
|
|
94
|
+
- 数据源:入站 C2C 消息的 `attachments`(`content_type` / `url` / `filename` / `size`)。
|
|
95
|
+
- 扩展下载图片 → 校验类型(jpg / jpeg / png / webp / gif)与大小 → 转 `ImageContent`(base64 + mimeType)→ 与消息文本一起 `pi.sendUserMessage()`。
|
|
96
|
+
- 类型判断:`content_type` 优先(兼容 `image/jpg`),非图片类型时按文件名扩展名兜底;明确声明为不支持的 `image/*`(如 svg)直接拒绝。
|
|
97
|
+
- 下载约束:单张超时 15s;`imageMaxSize` 默认 10MB;先看附件元数据,再在流式读取时二次限制实际字节数。
|
|
98
|
+
- 一条消息多张图片时按原顺序处理;部分失败时成功的图片仍注入,并回一条失败清单。
|
|
99
|
+
- 全部失败且没有文字/文件 → 不注入 pi,只回失败提示;有文字或文件 → 仍注入并提示图片失败。
|
|
100
|
+
- 当前模型无视觉能力(`ctx.model.input` 不含 `image`)时,QQ 提示并跳过图片;文字/文件仍处理。
|
|
101
|
+
- 已确认:pi 不向 QQ 发送图片——LLM 只能输出纯文本,无图片生成场景。
|
|
102
|
+
|
|
103
|
+
**文件行为**
|
|
104
|
+
|
|
105
|
+
- 非图片附件(如 zip/pdf/doc)下载后保存到当前工作空间的 `.pi/pi-qq/YYYY-MM-DD/<msgId>/<安全文件名>`。
|
|
106
|
+
- 文件名去掉路径与非法字符;同名文件自动加 `-1`、`-2` 后缀;不会写出保存目录。
|
|
107
|
+
- 单文件超时 60s;`fileMaxSize` 默认 50MB;同样先看元数据,再在流式读取时二次限流。
|
|
108
|
+
- 一条消息多个文件按原顺序保存;部分失败时成功的文件仍保留并给出失败清单。
|
|
109
|
+
- 提示词中追加文件块,例如:
|
|
110
|
+
```text
|
|
111
|
+
用户通过 QQ 发送了以下文件(已保存到本机,可用 read/bash 等工具访问):
|
|
112
|
+
- /home/chen/project/myproj/.pi/pi-qq/2026-10-29/xxx/report.pdf(1.4MB,原始名:report.pdf)
|
|
113
|
+
|
|
114
|
+
用户消息:
|
|
115
|
+
帮我总结这个文件
|
|
116
|
+
```
|
|
117
|
+
- 纯文件消息(无文字)也会触发 run,提示词只含文件块;文件内容不直接注入 LLM,由 pi 用工具按需读取。
|
|
118
|
+
|
|
119
|
+
### F4 回传 assistant 消息
|
|
120
|
+
|
|
121
|
+
**目标**:pi 的回复实时出现在 QQ 聊天里。
|
|
122
|
+
|
|
123
|
+
**行为**
|
|
124
|
+
|
|
125
|
+
- 数据源:`message_end`(`message.role === "assistant"`)。回复通常为 **Markdown 格式**的总结/提问文本(已确认:LLM 编码完成后不在回复中写代码)。
|
|
126
|
+
- 内容处理:
|
|
127
|
+
- 始终剔除 `thinking` 块(已确认:不回传思考内容)。
|
|
128
|
+
- **Markdown 转换**:
|
|
129
|
+
- 默认(无 markdown 权限,`markdownSupport: false`):轻量转纯文本——去掉 `**` / `*` / `` ` `` 等强调与行内代码标记、标题转为文本行、列表项转 `•`、链接转 `文字(url)`、表格等复杂结构逐行退化;保持手机端可读性。
|
|
130
|
+
- 机器人有 markdown 权限(`markdownSupport: true`)→ 透传原始 Markdown 由 QQ 客户端渲染。QQBot 构造时已传入 `markdownSupport`,SDK 的 `sendText` 会自动使用 msg_type=2,无需额外 `sendMarkdown`。
|
|
131
|
+
- 超长文本按单条上限自动分块(SDK `TEXT_CHUNK_LIMIT = 5000`)。
|
|
132
|
+
- **流式模式**(默认开启,C2C 专属):
|
|
133
|
+
- `message_update` 期间用 `bot.openStream({ target })` 持续 `update(全文)`(对累积全文实时做同样的转换);`message_end` 时 `complete()`。
|
|
134
|
+
- 遵守 SDK 约束:节流 ≥300ms、必须基于 5 分钟内的入站消息(`msgId`)、传全文非增量。
|
|
135
|
+
- **非流式/降级**:`sendText` 一次性发送。
|
|
136
|
+
- `stopReason === "error"` 时回传错误摘要而非静默。
|
|
137
|
+
|
|
138
|
+
### F5 回传 token 详情(输入 / 输出 / 缓存命中率)
|
|
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 合并为一条消息发送,避免刷屏。
|
|
158
|
+
|
|
159
|
+
### F6 回传上下文窗口占比
|
|
160
|
+
|
|
161
|
+
**数据源**:`ctx.getContextUsage()` → `{ tokens, contextWindow, percent }`。
|
|
162
|
+
|
|
163
|
+
**行为**
|
|
164
|
+
|
|
165
|
+
- 与 F5 同条消息的第三行:`• 上下文:0.4%`。
|
|
166
|
+
- `tokens === null`(压缩后尚未产生新响应)时显示 `重建中`。
|
|
167
|
+
- `percent` 缺失时按 `tokens / contextWindow` 计算。
|
|
168
|
+
- 严格三行格式,不追加 `/compact` 文字提示(百分比已可见)。
|
|
169
|
+
|
|
170
|
+
### F7 长任务反馈(10~60 分钟级任务)
|
|
171
|
+
|
|
172
|
+
**目标**:工具阶段长达数十分钟时保持"活着"的感知,且不烧穿消息额度。
|
|
173
|
+
|
|
174
|
+
**行为**:**assistant 文本消息与思考/工具汇总使用独立气泡**——每条文本消息独占一个纯文本气泡(同一消息的流式增量续写),思考/工具行组进入活动气泡;文本前后的工具执行均另起活动气泡;最终回复独立成文本气泡。`streamRelay` 默认开,实测可用;气泡内按 `streamFlushMs`(默认 10000ms,最小 300)固定频率发送窗口汇总帧(工具调用每 10s 汇总一次):
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
[活动气泡] 💭 思考中...
|
|
178
|
+
[活动气泡] [3] 🔧 bash
|
|
179
|
+
[活动气泡] [2] 🔧 read
|
|
180
|
+
|
|
181
|
+
[文本气泡] 中间消息原文
|
|
182
|
+
|
|
183
|
+
[活动气泡] [1] 🔧 edit
|
|
184
|
+
|
|
185
|
+
[文本气泡] 最终回复原文(流式增量)
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
- **汇总帧内容**(窗口增量,间隔 `streamFlushMs` 默认 10000ms;`agent_end` 补发剩余并收 DONE)。活动气泡帧:**行组帧首行带时间戳 `[HH:MM:SS]`**,行组**严格按事件实际发生顺序**输出:思考状态行(惰性)与工具计数行 `[n] 🔧 name` 按到达顺序交错;连续同名工具合并为一条计数,不改变相对顺序。文本气泡帧:原始 Markdown 增量(流式帧按 markdown 渲染),不加时间戳以免插断回答。工具总在 message_end 后执行,故文本消息与其后工具天然分入不同气泡。
|
|
189
|
+
- **排版规则**:活动气泡内行与行相邻不空行;文本气泡内续写直接拼接;文本与工具不再混排。
|
|
190
|
+
- **气泡边界**:文本消息的**首个增量**到达 → 封口当前活动气泡,开文本气泡;思考/工具行组到达 → 封口当前文本气泡,开或续活动气泡;同一消息的后续流式增量不切泡;最终回复独立成文本气泡。
|
|
191
|
+
- **事件映射**:`tool_execution_start` → 窗口计数;`message_update`(thinking/text)→ 窗口状态/快照;`message_end` → 文本定稿;`agent_end` → 补帧 + DONE。AppendStream 内部仍有 500ms 节流与限流退避作安全网。
|
|
192
|
+
- **额度提示**:每条文本消息、每段活动各占一条 msg_seq 消息;长回合任务的气泡数多于单气泡模式,需关注被动额度;若平台拒绝(帧失败),该回合自动降级消息路径,文本仍完整送达。
|
|
193
|
+
- **降级**:任何一帧失败即标 dead,已追加部分作废,未发出的结果文本自动转消息路径补发;`streamRelay: false` 时整条时间线关闭,assistant 消息走普通消息路径(M2 行为)。
|
|
194
|
+
- **typing 保鲜**:run 开始立即发送"正在输入",之后每 50s 续期(0 额度),`agent_end` 清理。
|
|
195
|
+
- **空窗口活性线**:窗口无增量且静默 ≥60s 时补一条 `[HH:MM:SS] ⏱ 已运行 X 分钟…`——长思考/单工具长执行期间每分钟一行,不再无推送(时间戳可用于核对节奏)。
|
|
196
|
+
- **心跳兜底**:流不可用时降级为普通消息心跳(每 run ≤3 条保险丝,带时间戳)。
|
|
197
|
+
- 不发送"已收到"开始确认(节省被动额度):QQ 触发的 run 在首个汇总帧前保持安静。
|
|
198
|
+
- 非 QQ 触发的 run(本地终端)不发心跳/时间线,但 assistant 消息仍照常回传(现状)。
|
|
199
|
+
|
|
200
|
+
## 3. 平台限制与回传预算(关键约束)
|
|
201
|
+
|
|
202
|
+
QQ 开放平台的发送限制直接决定回传策略,必须统一管理:
|
|
203
|
+
|
|
204
|
+
| 限制 | 数值 | 应对 |
|
|
205
|
+
| --- | --- | --- |
|
|
206
|
+
| 被动回复额度 | 每条入站消息 5 分钟内有效,约 4 条/小时 | 扩展内维护回复预算(复用 SDK `ReplyLimiter` 思路);assistant 时间线按文本/活动分泡,用量摘要合并为 1 条 |
|
|
207
|
+
| 主动消息 | 无 `msgId` 发送受平台额度限制 | 被动额度耗尽时才降级为主动发送,且给出明确提示 |
|
|
208
|
+
| 流式消息 | 仅 C2C;节流 ≥300ms;基于 5 分钟内 `msgId` | 流式仅用于 assistant 文本;无关联 `msgId` 时自动降级 `sendText` |
|
|
209
|
+
| 文本长度 | 单条 ~5000 字符 | SDK 分块;超出部分按序发送 |
|
|
210
|
+
| markdown | 默认无权限(`markdownSupport: false`) | Markdown → 纯文本降级渲染 |
|
|
211
|
+
|
|
212
|
+
**合并规则**(默认):assistant 文本消息与活动时间线严格分泡(每条文本消息 1 条纯文本气泡,工具间隔另起活动气泡);token 详情 + 上下文占比在 `agent_end` 合并为 1 条"用量摘要"发送。气泡数随回合内文本消息数增长,需关注 `msgId` 的被动额度;若平台拒绝(帧失败),自动降级消息路径。工具调用过程本身不逐条回传。
|
|
213
|
+
|
|
214
|
+
## 4. 配置
|
|
215
|
+
|
|
216
|
+
`~/.pi/agent/pi-qq.json`(手动配置或扫码登录写入,同一文件、同一 schema):
|
|
217
|
+
|
|
218
|
+
| 字段 | 默认 | 说明 |
|
|
219
|
+
| --- | --- | --- |
|
|
220
|
+
| `AppID` / `AppSecret` | 手动填写或扫码写入 | 机器人凭据(`0600` 保护);存在即免扫码直连(兼容小写 `appId` / `appSecret`) |
|
|
221
|
+
| `allowedOpenid` | 扫码自动写入;手动配置时可选(缺省首个私聊用户绑定) | 单人绑定的 openid |
|
|
222
|
+
| `streamAssistant` | `true` | assistant 流式回传开关 |
|
|
223
|
+
| `markdownSupport` | `false` | 机器人是否有 markdown 权限;`true` 时回传透传 Markdown |
|
|
224
|
+
| `usageRelay` | `true` | 本次 run 的 token/缓存命中率/上下文占比摘要开关 |
|
|
225
|
+
| `deliverAs` | `"steer"` | 忙碌时新消息的处理方式 |
|
|
226
|
+
| `imageMaxSize` | `10MB` | QQ 图片下载上限 |
|
|
227
|
+
| `fileMaxSize` | `50MB` | QQ 文件下载上限 |
|
|
228
|
+
| `heartbeatMinutes` | `10`(0 关闭) | F7 节流心跳间隔 |
|
|
229
|
+
| `heartbeatMaxMessages` | `3` | F7 每 run 消息心跳上限(流式心跳不受限) |
|
|
230
|
+
| `streamRelay` | `true` | F7 流式载体开关(append 追加 + 节流合帧 + 限流退避,实测可用;失败自动降级消息路径) |
|
|
231
|
+
| `streamFlushMs` | `10000`(最小 300) | F7 流式汇总帧间隔(毫秒,默认每 10s 汇总工具调用) |
|
|
232
|
+
| `debug` | `false` | 诊断模式:SDK 日志转终端 + 流式限流重试/超时日志 + 文本增量帧时间戳 |
|
|
233
|
+
|
|
234
|
+
## 5. 命令总表
|
|
235
|
+
|
|
236
|
+
| 位置 | 命令 | 行为 |
|
|
237
|
+
| --- | --- | --- |
|
|
238
|
+
| pi 侧 | `/qq-login` | 扫码登录并绑定 |
|
|
239
|
+
| pi 侧 | `/qq-status` | 登录态、连接状态、绑定用户 |
|
|
240
|
+
| pi 侧 | `/qq-budget` | 诊断:被动额度、流式气泡数、最近 msgId 新鲜度 |
|
|
241
|
+
| pi 侧 | `/qq-logout` | 清除凭据并断开 |
|
|
242
|
+
| pi 侧 | `/qq-send <text>` | 手动向绑定用户发一条测试消息 |
|
|
243
|
+
| pi 侧 | `/qq-md [text]` | 诊断:发送 Markdown 消息,验证 C2C markdown 渲染能力 |
|
|
244
|
+
| pi 侧 | `/qq-stream-test` | 诊断:开流→三帧→complete,验证流式帧是否渲染 |
|
|
245
|
+
| QQ 侧 | `/new` `/stop` `/compact` `/status` `/help` | 会话控制(见 F2) |
|
|
246
|
+
|
|
247
|
+
## 6. 可靠性与安全
|
|
248
|
+
|
|
249
|
+
- **生命周期**:`session_start` 启动、`session_shutdown` 幂等关闭;SDK 默认无限重连(退避 1s→60s),4914/4915 致命关闭码上报为不可恢复,提示重新 `/qq-login` 或检查凭据。
|
|
250
|
+
- **回声与去重**:启用 SDK `messageFilter`(跳过 bot 回声)与 `concurrencyGuard`(同用户串行),避免流式与回复互相踩踏。
|
|
251
|
+
- **安全**:
|
|
252
|
+
- 凭据文件 `0600`,日志脱敏;扩展以 pi 同等权限运行,白名单外的消息不进入 pi(不产生任何工具执行)。
|
|
253
|
+
- QQ 侧无 shell 类命令;一切工具执行都经由 pi 自身权限体系。
|
|
254
|
+
|
|
255
|
+
## 7. 决策记录
|
|
256
|
+
|
|
257
|
+
| # | 问题 | 决策 |
|
|
258
|
+
| --- | --- | --- |
|
|
259
|
+
| 1 | TUI 二维码渲染 | 登录协议用 connector;展示用 `qrcode-terminal`(零依赖)在 `ctx.ui` 弹窗画码 |
|
|
260
|
+
| 2 | thinking 内容 | 不回传具体内容(始终剔除,无配置开关);F7 时间线中仅以"💭 思考中…"标记体现 |
|
|
261
|
+
| 3 | tool 消息 | **完全不回传**(从功能范围移除;只回传 assistant 消息 + token usage + 上下文占比) |
|
|
262
|
+
| 4 | 图片方向 | F3 为 QQ → pi(用户发图给 pi);pi 不向 QQ 发图片(LLM 仅输出纯文本) |
|
|
263
|
+
| 5 | 成本展示 | 不在 QQ 摘要中展示成本;摘要严格三行(输入/缓存命中率、输出、上下文) |
|
|
264
|
+
| 6 | 回复格式 | 回复通常为 Markdown 格式的总结/提问文本(不在回复中写代码);默认轻量转纯文本,有 markdown 权限可透传 |
|
|
265
|
+
| 7 | 登录方式 | 双通道:`~/.pi/agent/pi-qq.json` 存在 `AppID`/`AppSecret` 即免扫码直连,否则扫码登录;凭据统一存该文件 |
|
|
266
|
+
| 8 | 长任务反馈 | typing 保鲜 + 每 10s 汇总工具调用 + 节流心跳(默认 10 分钟/条,流式载体优先,每 run ≤3 条消息心跳保险丝)+ 机会性流式(平台拒绝即降级);不发送开始确认 |
|
|
267
|
+
| 9 | 流式可用性(实测三轮) | ① C2C markdown(msg_type=2,`sendMarkdown`)渲染正常;② SDK 内置流式 `input_mode="replace"` 被平台拒绝("已经提交的消息内容不可修改"),首帧可渲染、后续帧报错;③ 自实现 `AppendStream`(input_mode="append",增量追加 + DONE)实测通过;补齐节流合帧(500ms)与限流退避重试后**默认开启**,失败自动降级消息路径 |
|
|
268
|
+
|
|
269
|
+
## 8. 里程碑
|
|
270
|
+
|
|
271
|
+
| 阶段 | 内容 | 验收 |
|
|
272
|
+
| --- | --- | --- |
|
|
273
|
+
| M1 | F1 登录接入(配置直连 + 扫码登录)+ 凭据持久化 + 连接启动 | 配置直连或扫码后 `/qq-status` 显示在线 |
|
|
274
|
+
| M2 | F2 单人聊天 + F4 assistant 回传(先非流式) | QQ 发消息得到 pi 回复 |
|
|
275
|
+
| M3 | F5/F6 用量摘要(本次 run 输入/缓存命中率/输出/上下文) | 严格三行摘要正确呈现 |
|
|
276
|
+
| M4 | F3 QQ 图片/文件消息 + markdownSupport + 打磨 | 图片可进入 pi 会话;文件保存并关联到提示词 |
|
package/doc/plan.md
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# pi-qq — plan.md
|
|
2
|
+
|
|
3
|
+
> 执行计划。功能范围与决策见 [features.md](./features.md),本文只回答:装什么、建什么文件、按什么顺序做、每步怎么验收。
|
|
4
|
+
|
|
5
|
+
## 0. 前置:依赖安装(需你手动执行)
|
|
6
|
+
|
|
7
|
+
按约定不由我安装。在项目目录执行:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
cd /home/chen/project/pi-qq
|
|
11
|
+
npm init -y
|
|
12
|
+
npm i @tencent-connect/qqbot-nodejs @tencent-connect/qqbot-connector qrcode-terminal
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
| 包 | 版本锚点 | 用途 |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| `@tencent-connect/qqbot-nodejs` | ^1.0.5 | QQ 协议层(本地另有源码 `/home/chen/project/qqbot-nodejs` 可查阅) |
|
|
18
|
+
| `@tencent-connect/qqbot-connector` | ^1.2.0 | 扫码登录(方式 B) |
|
|
19
|
+
| `qrcode-terminal` | ^0.12 | 二维码 ASCII 渲染(零依赖) |
|
|
20
|
+
|
|
21
|
+
开发加载方式:`pi --extension /home/chen/project/pi-qq`(jiti 直接跑 TS,无需构建)。
|
|
22
|
+
|
|
23
|
+
## 1. 目录结构与模块划分
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
pi-qq/
|
|
27
|
+
├── package.json
|
|
28
|
+
├── tsconfig.json # 仅编辑器/typecheck 用,无构建
|
|
29
|
+
├── index.ts # 扩展入口:registerCommand + pi.on 订阅 + 生命周期
|
|
30
|
+
└── src/
|
|
31
|
+
├── config.ts # ~/.pi/agent/pi-qq.json 读写(0600、schema 兼容大小写、字段合并)
|
|
32
|
+
├── login.ts # F1:方式 A 直连判定 / 方式 B 扫码(connector + TUI 二维码弹窗)
|
|
33
|
+
├── bot.ts # QQBot 实例生命周期:start/stop、中间件装配、重连/致命关闭码上报
|
|
34
|
+
├── inbound.ts # F2/F3:白名单 → QQ 命令拦截 → 图片/文件附件 → sendUserMessage
|
|
35
|
+
├── images.ts # F3:图片类型/大小校验、15s 超时下载、ImageContent 组装
|
|
36
|
+
├── files.ts # F3:文件下载落盘、安全文件名、提示词路径关联
|
|
37
|
+
├── download.ts # 图片/文件共用:超时与流式大小限制下载
|
|
38
|
+
├── format.ts # 人类可读字节格式化
|
|
39
|
+
├── outbound.ts # F4:markdown→纯文本转换、流式(openStream)/降级(sendText)、分块
|
|
40
|
+
├── reply-budget.ts # §3:被动回复预算(msgId 5min 窗口、4条/h、降级主动发送)
|
|
41
|
+
├── budget-status.ts # /qq-budget 纯格式化(普通/流式/估算剩余)
|
|
42
|
+
└── usage.ts # F5/F6:本次 run 用量汇总(agent_end messages)、严格三行摘要
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
职责边界:`index.ts` 只做装配与订阅,不含业务逻辑;每个模块可独立测试;模块间只经 `index.ts` 传递的共享状态对象(bot 实例、当前 target/msgId、配置)通信。
|
|
46
|
+
|
|
47
|
+
## 2. pi 事件与 SDK 接线总表
|
|
48
|
+
|
|
49
|
+
| 方向 | 信号 | 处理 |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| QQ → pi | `bot.on("message")`(kind=c2c) | 白名单 → QQ 命令(`/new` `/stop` `/compact` `/status` `/help`)→ 文本+图片 → `pi.sendUserMessage()` |
|
|
52
|
+
| pi → QQ | `message_update`(assistant) | 流式:`openStream().update(转换后全文)`,节流 ≥300ms |
|
|
53
|
+
| pi → QQ | `message_end`(assistant) | `stream.complete()`;无流上下文时 `sendText`;`stopReason==="error"` 回错误摘要 |
|
|
54
|
+
| pi → QQ | `agent_end` | 用量摘要一条(F5 本次 run token/缓存命中率 + F6 上下文占比) |
|
|
55
|
+
| 状态 | `session_start` / `session_shutdown` | 读配置启动 bot(A→B 判定)/ 幂等停止 |
|
|
56
|
+
| 汇总 | `agent_end` | 从 `event.messages` 汇总本次 run 的 assistant/toolResult usage |
|
|
57
|
+
|
|
58
|
+
## 3. 里程碑
|
|
59
|
+
|
|
60
|
+
### M1 — 登录接入与连接(F1 + bot.ts + config.ts)
|
|
61
|
+
|
|
62
|
+
1. `package.json`、`tsconfig.json`、目录骨架;`config.ts`:读取/写入 `~/.pi/agent/pi-qq.json`(`AppID`/`AppSecret` 大小写兼容、其余字段合并保留、0600)。
|
|
63
|
+
2. `bot.ts`:`createBot(credentials)`、`start/stop`、装配 `messageFilter`(回声过滤)+ `accessPolicy`(白名单)+ `concurrencyGuard`;`ready/disconnected/error` 上报到 `ctx.ui`。
|
|
64
|
+
3. `login.ts` + `index.ts`:
|
|
65
|
+
- `session_start`:配置有凭据 → 直连(方式 A);无凭据 → `ctx.ui.notify` 提示 `/qq-login`。
|
|
66
|
+
- `/qq-login`:`startQrConnect`(`displayQrCodeToConsole: false`),`onQrDisplayed` 在 TUI 弹窗画二维码(`qrcode-terminal`),`onSuccess` 写配置并启动。
|
|
67
|
+
- `/qq-status`(登录方式/来源/绑定用户/连接状态)、`/qq-logout`。
|
|
68
|
+
|
|
69
|
+
**验收**:手写配置文件启动后 `/qq-status` 显示在线;删掉凭据走扫码后同样在线;`4914/4915` 致命关闭码给出明确提示。
|
|
70
|
+
|
|
71
|
+
### M2 — 单人聊天与完整回复(F2 文本 + F4 非流式 + reply-budget.ts)
|
|
72
|
+
|
|
73
|
+
1. `inbound.ts`:C2C 白名单过滤、QQ 命令拦截(`/stop`→`ctx.abort()`、`/new`→扩展命令 `qq-new`→`ctx.newSession()`、`/status` 汇总、`/help`)、文本 → `sendUserMessage`;忙碌时 `deliverAs` 排队。
|
|
74
|
+
2. `outbound.ts` 非流式路径:markdown→纯文本转换函数(独立、可单测:强调/标题/列表/链接/表格退化)+ `TEXT_CHUNK_LIMIT` 分块。
|
|
75
|
+
3. `reply-budget.ts`:按 `msgId` 记录被动回复次数与 5min 窗口;超限降级主动发送并提示。
|
|
76
|
+
|
|
77
|
+
**验收**:QQ 发"你好"→ QQ 收到 pi 回复(纯文本、无 markdown 记号残留);连续对话额度不炸;非绑定用户发消息无任何反应。
|
|
78
|
+
|
|
79
|
+
### M2.5 — 长任务反馈包(F7,已拍板)
|
|
80
|
+
|
|
81
|
+
背景:实际场景 `user_input → thinking+tools(10~60 分钟)→ assistant message`,结果只在末尾出现一次。
|
|
82
|
+
|
|
83
|
+
1. `src/run-feedback.ts`:run 级状态机 —— QQ 触发标记(pending)、工具名×次数计数(`tool_execution_end`)、流会话(`openStream` 惰性开启:首次心跳或首次文本时尝试,失败标 dead)、typing keepalive 定时器(50s)、节流心跳定时器(默认 10min)、消息心跳保险丝(每 run ≤3)、`agent_end` 收尾(complete/cancel/清 timer)。
|
|
84
|
+
2. 载体优先级:流式心跳(一条消息持续刷新,0 额度)→ 消息心跳(≤3 条)→ 静默;结果文本在流存活时直接续写同一条流,`message_end` 被流接管时跳过 sendReply(避免双发)。
|
|
85
|
+
3. `inbound.ts`:不发送开始确认(节省被动额度),仅 `markQQTrigger`。
|
|
86
|
+
4. `index.ts`:接线 `agent_start` / `agent_end` / `tool_execution_end` / `message_update`。
|
|
87
|
+
5. `config.ts`:`heartbeatMinutes`(默认 10)、`heartbeatMaxMessages`(默认 3)。
|
|
88
|
+
|
|
89
|
+
**验收**:QQ 发任务 → 不发送确认 → 10s 内收到首个汇总帧 → typing 持续 → 心跳按期到达(流或消息)→ 结果回传不双发。
|
|
90
|
+
|
|
91
|
+
### M3 — 用量摘要(F5 + F6)
|
|
92
|
+
|
|
93
|
+
1. `usage.ts`:`agent_end` 从 `event.messages` 汇总本次 run 的 assistant + toolResult usage;上下文取 `ctx.getContextUsage()`(`tokens===null` 显示"重建中")。
|
|
94
|
+
2. 严格三行格式:`📊 用量摘要` / `• 输入:4.1k (99.9%)` / `• 输出:2.3k` / `• 上下文:0.4%`;输入为总输入(含 cacheRead/cacheWrite),括号为缓存命中率。
|
|
95
|
+
3. 仅 QQ 触发且成功完成的 run 发送;经 reply-budget 发送。
|
|
96
|
+
|
|
97
|
+
**验收**:每轮对话后 QQ 收到一条三行摘要,数字与本次 run 实际用量一致。
|
|
98
|
+
|
|
99
|
+
### M4 — 图片与打磨(F3 + markdownSupport 透传)
|
|
100
|
+
|
|
101
|
+
1. [x] F3 图片/文件:图片转 `ImageContent`;非图片附件保存到当前工作空间的 `.pi/pi-qq/YYYY-MM-DD/<msgId>/`,提示词中追加绝对路径、大小与原始文件名;`fileMaxSize` 默认 50MB。
|
|
102
|
+
2. [x] `markdownSupport: true`:`QQBot` 构造时已传入该开关,SDK 的 `sendText` 自动使用 msg_type=2;调用方保留原始 Markdown 即可,无需额外 `sendMarkdown`。
|
|
103
|
+
3. [x] QQ 侧 `/new`:inbound 调用隐藏扩展命令 `qq-new`,命令 handler 使用 `ctx.newSession()`;非 idle 时提示先 `/stop`。
|
|
104
|
+
4. [ ] 长代码块转文件附件(backlog);多气泡 + 摘要额度实测已完成。
|
|
105
|
+
|
|
106
|
+
**验收**:QQ 发图后 pi 能描述图片内容;QQ 发文件后保存到本机并在提示词中关联路径;额度全程不超限。
|
|
107
|
+
|
|
108
|
+
## 4. 验证策略
|
|
109
|
+
|
|
110
|
+
- **静态**:`npx tsc --noEmit`(tsconfig 仅类型检查)。
|
|
111
|
+
- **单测**(vitest,纯函数优先):markdown→纯文本转换、分块、reply-budget 状态机、config 读写合并。SDK 与 pi 事件层不做单测,靠 M1–M4 验收手动覆盖。
|
|
112
|
+
- **手动验收**:每个里程碑按上表验收项在真实 QQ 环境跑一遍;`baseUrl` 可指向 mock 验证协议路径(SDK 测试有先例)。
|
|
113
|
+
|
|
114
|
+
## 5. 风险与预案
|
|
115
|
+
|
|
116
|
+
| 风险 | 影响 | 预案 |
|
|
117
|
+
| --- | --- | --- |
|
|
118
|
+
| 流式消息对非 C2C/过期 `msgId` 抛错 | 流式路径崩溃 | `openStream` 前置校验,失败即降级 `sendText`(M4 已含) |
|
|
119
|
+
| 被动额度耗尽(长 run 多回复) | 消息发不出去 | reply-budget 统一发牌,超限降级主动+提示;摘要固定合并 |
|
|
120
|
+
| markdown 转换漏判 | QQ 端残留记号 | 转换函数单测覆盖常见结构;允许透传开关兜底 |
|
|
121
|
+
| connector 混淆代码异常 / 扫码接口变更 | 扫码不可用 | 方式 A 直连始终可用(不依赖 connector) |
|
|
122
|
+
| pi 事件在非 TUI 模式无 UI | 扩展报错 | 所有 `ctx.ui` 调用前判 `ctx.hasUI`/`ctx.mode` |
|
|
123
|
+
|
|
124
|
+
## 6. Todo-List(随进度勾选)
|
|
125
|
+
|
|
126
|
+
### 准备
|
|
127
|
+
|
|
128
|
+
- [x] 依赖安装:`@tencent-connect/qqbot-nodejs` + `@tencent-connect/qqbot-connector` + `qrcode-terminal`(用户已执行)
|
|
129
|
+
- [x] pi / SDK / connector API 签名核对(types.d.ts + 本地源码)
|
|
130
|
+
- [x] `package.json` 完善(`type: module`、private、description)
|
|
131
|
+
- [x] `tsconfig.json`(`moduleResolution: bundler`;`paths` 借用 pi 发行目录类型 + `typeRoots` 借用其 @types/node,typecheck 走 `npx typescript`,无需安装 devDeps)
|
|
132
|
+
|
|
133
|
+
### M1 — 登录接入与连接
|
|
134
|
+
|
|
135
|
+
- [x] `src/config.ts`:`~/.pi/agent/pi-qq.json` 读写(`AppID`/`AppSecret` 大小写兼容、字段合并保留、`0600`、credentials/allowedOpenid 存取)
|
|
136
|
+
- [x] `src/bot.ts`:`createBot/start/stop`、中间件装配(messageFilter/accessPolicy/concurrencyGuard)、连接状态跟踪、致命关闭码上报
|
|
137
|
+
- [x] `src/login.ts`:方式 A 直连判定 + 方式 B `startQrConnect`(含二维码展示与取消)
|
|
138
|
+
- [x] `index.ts`:`/qq-login` `/qq-status` `/qq-logout` 命令 + `session_start` 自动接入 + `session_shutdown` 幂等停止
|
|
139
|
+
- [x] 验收:配置直连在线 / 扫码在线 / `4914` `4915` 明确提示(用户实测通过;`4914/4915` 与扫码路径如未触发可在后续使用中观察)
|
|
140
|
+
|
|
141
|
+
### M2 — 单人聊天与完整回复(非流式)
|
|
142
|
+
|
|
143
|
+
- [x] `src/inbound.ts`:白名单 → QQ 命令拦截(`/new` `/stop` `/compact` `/status` `/help`)→ 文本 `sendUserMessage` + `deliverAs` 排队
|
|
144
|
+
- [x] `src/outbound.ts`:markdown→纯文本转换(独立可单测)+ `TEXT_CHUNK_LIMIT` 分块
|
|
145
|
+
- [x] `src/reply-budget.ts`:被动回复预算(5min 窗口 / 4条每小时)+ 降级主动发送
|
|
146
|
+
- [x] `message_end`(assistant)非流式回传接线 + `stopReason==="error"` 错误摘要
|
|
147
|
+
- [x] 单测:markdown 转换 / 分块 / reply-budget(jiti + assert 脚本 `test/run.ts`,30 项断言;config 12 项在 M1 已验)
|
|
148
|
+
- [x] 验收:QQ 发消息→收到纯文本回复;非绑定用户无反应;额度不超限(用户实测通过)
|
|
149
|
+
|
|
150
|
+
### M2.5 — 长任务反馈包
|
|
151
|
+
|
|
152
|
+
- [x] `src/run-feedback.ts`:run 级状态机(QQ 触发标记、工具计数、流会话惰性开启、typing/心跳定时器、消息心跳保险丝)+ `formatHeartbeat`
|
|
153
|
+
- [x] `config.ts`:`heartbeatMinutes` / `heartbeatMaxMessages`
|
|
154
|
+
- [x] `inbound.ts`:`markQQTrigger`(不发送开始确认,2026-10-29 调整)
|
|
155
|
+
- [x] `index.ts`:`agent_start`/`agent_end`/`tool_execution_end`/`message_update` 接线;`message_end` 流接管判定
|
|
156
|
+
- [x] 单测:`formatHeartbeat`(test/run.ts 共 33 项断言)
|
|
157
|
+
- [x] 验收:QQ 发任务 → 不发送确认 → 10s 内收到汇总帧 → typing 持续 → 心跳按期 → 结果回传不双发(用户实测通过)
|
|
158
|
+
- 首轮实测(2026-10-28):确认/typing 正常;SDK 内置流式 replace 语义被平台拒绝("已经提交的消息内容不可修改",首帧可渲染、第二帧报错);C2C markdown 渲染正常(`/qq-md` ✓)。
|
|
159
|
+
- 修复:自实现 `src/append-stream.ts`(input_mode="append",追加语义),RunFeedback 改为增量追加,`/qq-stream-test` 改测 append 模式。
|
|
160
|
+
- 复验(2026-10-28):append 两帧 + DONE 全部渲染 ✓,流式链路打通。后续任务:心跳/结果追加需开启 `streamRelay: true`。
|
|
161
|
+
- 时间线升级(用户构想):流式气泡改为**回合活动时间线**——💭 思考中…(惰性标记,不回传内容)/ 🔧 工具名(tool_execution_start)/ 智能体消息原文(流式增量)依次追加,心跳与 DONE 照旧;帧失败自动降级消息路径并补发未发结果。
|
|
162
|
+
- 汇总帧重构(用户构想):逐事件追加改为**固定 3s 窗口汇总帧**——思考状态行 + 工具计数行(`[n] 🔧 name`)+ 消息文本增量,按设计稿分组排版;流式帧按 markdown 渲染(实测),故流内传原始文本。用户实测反馈:长思考/长工具期间静默——已加行组帧时间戳 + 空窗口 60s 活性行 + flush 队列串行化(防限流重试与定时器交错)。追加 debug 开关(SDK 日志转终端 + 文本帧时间戳)用于定位用户报告的「超时」现象。
|
|
163
|
+
- 回合独立气泡(用户反馈:内容全压一条气泡太挤):切分规则改为**每条带文本的 assistant 消息一个气泡**(首版按 message_start 切分产生大量迷你气泡——该模型每轮工具调用都发独立小消息,且 onToolStart 立即行与汇总帧双份报告)。文本驱动边界:新文本 + 当前气泡已含文本 → 封口开新泡;工具并入当前气泡。
|
|
164
|
+
- 二轮实测(2026-10-28,jsonl 事件时间线 vs 气泡时间戳):3s 汇总节奏准确(事件→帧延迟 0~3s)、无重复、91s 静默区活性行准时(60s 阈值)、markdown 渲染正常。M2.5 全部验收通过。首轮长任务实测三问题:① flushWindow 丢失 resultSentLen 推进导致累计文本重复重发(已修,帧内推进基准);② 心跳/汇总行补回 💭/🔧 图标;③ 帧节奏实为 3s,观感问题由①导致。
|
|
165
|
+
- 三轮实测(2026-10-29,用户 QQ 截图 + 会话日志):最终回复被追加 3 份,且最后一个气泡一直停留在“生成中”。根因是 `f806065` 重构丢失两处关键逻辑:① 成功追加文本后未推进 `resultSentLen`,每 3s 汇总帧重发全文;② `sealBubble` 在 `flushWindow` 前捕获旧 `cur`,切泡后新气泡收不到 DONE。修复:追加成功即推进基准;气泡边界仅在上一条文本消息定稿后触发(同消息的流式增量不再切泡);`sealBubble` 在 flush 后重读 `cur`;错误路径先封口再走消息链路。新增重复/单气泡/双气泡/错误 DONE 回归断言。
|
|
166
|
+
- 四轮实测(2026-10-29,`log/pi.jsonl` + `log/qq.png`):首条中间文本(工具活动之后的 assistant 消息)被并入活动气泡,未独立成泡。根因:切泡条件要求旧气泡已含文本,而首条文本之前只有思考/工具行组。修复:文本消息首个增量到达时,只要当前气泡已有内容就封口(含仅行组);工具计数行格式改为 `[n] 🔧 name`(心跳同步),新增活动气泡→文本气泡回归断言。
|
|
167
|
+
- 五轮调整(2026-10-29,用户要求):删除 t=0 的"✅ 已收到"开始确认(含忙碌合并提示),节省被动额度;汇总帧默认间隔 3000ms → 10000ms,工具调用每 10s 汇总一次(`streamFlushMs` 仍可配置)。
|
|
168
|
+
- 六轮调整(2026-10-29,用户 QQ 截图):中间文本消息与工具汇总混在同一气泡(如“已写入…”后紧跟 read 行)。改为**文本/活动严格分泡**:每条 assistant 文本独占纯文本气泡,思考/工具行组进活动气泡,文本前后的工具均另起活动气泡;新增“活动→文本→活动→文本→活动→最终文本”六气泡交错回归断言。
|
|
169
|
+
- 七轮自检(2026-10-29,`log/pi.png` + `log/qq.png`):用量摘要与 pi Session Info 完全一致(输入 14.3k/缓存 92.8%、输出 1.1k、上下文 0.4%)。发现无文本 assistant 消息不走 `onAssistantFinal`,逐消息思考标记未重置,导致下一条消息的 thinking 行被吞(截图中 read 前缺 thinking)。修复:`message_end` 对无文本 assistant 也调用 `onAssistantFinal("")`,冲刷行组并重置逐消息状态;新增“无文本消息不吞后续行组”回归断言。
|
|
170
|
+
- 八轮调整(2026-10-29,重跑截图):read 与下一条消息的 thinking 落入同一 10s 窗口时,旧逻辑固定“thinking 优先”,显示顺序与真实事件相反(应 read → thinking → bash)。修复:窗口行组改为 `winLines` 事件序列,按事件到达顺序输出;连续同名工具合并计数;新增严格顺序回归断言。
|
|
171
|
+
|
|
172
|
+
### M3 — 用量摘要
|
|
173
|
+
|
|
174
|
+
- [x] `src/usage.ts`:`agent_end` 从 `event.messages` 汇总本次 run(assistant + toolResult 嵌套 usage)
|
|
175
|
+
- [x] 严格三行摘要:输入(总输入)+ 缓存命中率、输出、上下文占比;`tokens===null` 显示重建中
|
|
176
|
+
- [x] 仅 QQ 触发且成功完成的 run 发送;经 reply-budget 发送
|
|
177
|
+
- [ ] 验收(待 QQ 实测):摘要数字与本次 run 实际用量一致
|
|
178
|
+
- 2026-10-29:单测覆盖严格三行/命中率/无缓存/重建中/上下文计算/本次 run 汇总/无文本消息行组/图片类型与大小校验/QQ /new 分发/预算快照/流式气泡计数/文件保存与提示词(vitest:8 个测试文件 / 81 个测试通过)。
|
|
179
|
+
|
|
180
|
+
### M4 — 图片与打磨
|
|
181
|
+
|
|
182
|
+
- [x] F3 图片/文件:图片注入;文件落盘 + 提示词路径关联 + `fileMaxSize`
|
|
183
|
+
- [x] 流式接线(M2.5 已完成,`AppendStream` + 文本/活动分泡)
|
|
184
|
+
- [x] `/compact` 命令、typing 指示(C2C)
|
|
185
|
+
- [x] `markdownSupport: true`:SDK `sendText` 自动 msg_type=2(无需新增 sendMarkdown 路径)
|
|
186
|
+
- [x] QQ 侧 `/new` 支持(`qq-new` 扩展命令 → `ctx.newSession()`)
|
|
187
|
+
- [x] `/qq-budget` 诊断命令(普通被动剩余 / 流式气泡数 / 估算剩余 / 最近 msgId 新鲜度)
|
|
188
|
+
- [x] 单元测试迁移到 vitest(`test/*.test.ts`,8 个文件 / 81 个测试;`npm test`)
|
|
189
|
+
- [ ] 长代码块转文件附件(backlog,暂缓)
|
|
190
|
+
- [x] 多气泡 + 摘要下的被动额度实测(2026-10-29:`/qq-budget` 实测符合预期:4 个流式气泡 + 1 条摘要,普通剩余 3 / 估算剩余 0 / 窗口有效)
|
|
191
|
+
- [x] `debug` 抓超时日志:AppendStream 限流重试/最终失败 + run start/end 日志
|
|
192
|
+
- [x] 验收:QQ 发图后 pi 能描述图片内容;全程额度不超限(2026-10-29 实测通过)
|
|
193
|
+
- [ ] 文件传输实机验收(QQ 发 zip/pdf 等,确认保存路径与提示词关联)
|
|
194
|
+
- 2026-10-29:图片+文字、纯图片(均被模型正确识别)、非图片附件拒绝(zip 提示“附件处理失败”)、多气泡+摘要额度诊断已实测通过。
|
|
195
|
+
- 无视觉模型场景按用户决定不验证(代码仍保留 `ctx.model.input` 检查)。
|