@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.
@@ -1,6 +1,6 @@
1
- # pi-qq — plan.md
1
+ # pi-qq — plan-v1.md
2
2
 
3
- > 执行计划。功能范围与决策见 [features.md](./features.md),本文只回答:装什么、建什么文件、按什么顺序做、每步怎么验收。
3
+ > 执行计划。功能范围与决策见 [features-v1.md](./features-v1.md),本文只回答:装什么、建什么文件、按什么顺序做、每步怎么验收。
4
4
 
5
5
  ## 0. 前置:依赖安装(需你手动执行)
6
6
 
@@ -15,7 +15,7 @@ npm i @tencent-connect/qqbot-nodejs @tencent-connect/qqbot-connector qrcode-term
15
15
  | 包 | 版本锚点 | 用途 |
16
16
  | --- | --- | --- |
17
17
  | `@tencent-connect/qqbot-nodejs` | ^1.0.5 | QQ 协议层(本地另有源码 `/home/chen/project/qqbot-nodejs` 可查阅) |
18
- | `@tencent-connect/qqbot-connector` | ^1.2.0 | 扫码登录(方式 B) |
18
+ | `@tencent-connect/qqbot-connector` | ^1.2.0 | 扫码登录(唯一登录方式) |
19
19
  | `qrcode-terminal` | ^0.12 | 二维码 ASCII 渲染(零依赖) |
20
20
 
21
21
  开发加载方式:`pi --extension /home/chen/project/pi-qq`(jiti 直接跑 TS,无需构建)。
@@ -28,18 +28,17 @@ pi-qq/
28
28
  ├── tsconfig.json # 仅编辑器/typecheck 用,无构建
29
29
  ├── index.ts # 扩展入口:registerCommand + pi.on 订阅 + 生命周期
30
30
  └── src/
31
- ├── config.ts # ~/.pi/agent/pi-qq.json 读写(0600、schema 兼容大小写、字段合并)
32
- ├── login.ts # F1:方式 A 直连判定 / 方式 B 扫码(connector + TUI 二维码弹窗)
31
+ ├── config.ts # ~/.pi/agent/pi-qq.json 只读设置(不含凭据)
32
+ ├── login.ts # F1:仅扫码登录(connector + TUI 二维码弹窗;凭据只返回内存)
33
33
  ├── bot.ts # QQBot 实例生命周期:start/stop、中间件装配、重连/致命关闭码上报
34
34
  ├── inbound.ts # F2/F3:白名单 → QQ 命令拦截 → 图片/文件附件 → sendUserMessage
35
35
  ├── images.ts # F3:图片类型/大小校验、15s 超时下载、ImageContent 组装
36
36
  ├── files.ts # F3:文件下载落盘、安全文件名、提示词路径关联
37
37
  ├── download.ts # 图片/文件共用:超时与流式大小限制下载
38
- ├── format.ts # 人类可读字节格式化
38
+ ├── format.ts # 人类可读字节/ token 数格式化
39
39
  ├── outbound.ts # F4:markdown→纯文本转换、流式(openStream)/降级(sendText)、分块
40
40
  ├── reply-budget.ts # §3:被动回复预算(msgId 5min 窗口、4条/h、降级主动发送)
41
- ├── budget-status.ts # /qq-budget 纯格式化(普通/流式/估算剩余)
42
- └── usage.ts # F5/F6:本次 run 用量汇总(agent_end messages)、严格三行摘要
41
+ └── budget-status.ts # /qq-test-budget 纯格式化(普通/流式/估算剩余)
43
42
  ```
44
43
 
45
44
  职责边界:`index.ts` 只做装配与订阅,不含业务逻辑;每个模块可独立测试;模块间只经 `index.ts` 传递的共享状态对象(bot 实例、当前 target/msgId、配置)通信。
@@ -51,22 +50,21 @@ pi-qq/
51
50
  | QQ → pi | `bot.on("message")`(kind=c2c) | 白名单 → QQ 命令(`/new` `/stop` `/compact` `/status` `/help`)→ 文本+图片 → `pi.sendUserMessage()` |
52
51
  | pi → QQ | `message_update`(assistant) | 流式:`openStream().update(转换后全文)`,节流 ≥300ms |
53
52
  | 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 |
53
+ | 状态 | `session_start` / `session_shutdown` | 有内存登录态则启动 bot / 幂等停止 |
54
+ | 收尾 | `agent_end` | 封口最后一个流式气泡(DONE);不再发送用量摘要 |
57
55
 
58
56
  ## 3. 里程碑
59
57
 
60
58
  ### M1 — 登录接入与连接(F1 + bot.ts + config.ts)
61
59
 
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`。
60
+ 1. `package.json`、`tsconfig.json`、目录骨架;`config.ts`:只读 `~/.pi/agent/pi-qq.json` 设置,不读写凭据。
61
+ 2. `bot.ts`:`start/stop`、装配 `messageFilter`(回声过滤)+ `accessPolicy`(白名单)+ `concurrencyGuard`;`ready/disconnected/error` 上报到 `ctx.ui`。
64
62
  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`。
63
+ - `session_start`:进程内存有登录态则启动;否则提示 `/qq-login`。
64
+ - `/qq-login`:`startQrConnect`(`displayQrCodeToConsole: false`),`onQrDisplayed` 在 TUI 弹窗画二维码(`qrcode-terminal`),`onSuccess` 把凭据与 openid 存入内存并启动。
65
+ - `/qq-status`(内存登录/连接/绑定用户)、`/qq-logout`(清内存凭据)。
68
66
 
69
- **验收**:手写配置文件启动后 `/qq-status` 显示在线;删掉凭据走扫码后同样在线;`4914/4915` 致命关闭码给出明确提示。
67
+ **验收**:扫码后 `/qq-status` 在线;pi 进程重启后需重新扫码;`4914/4915` 致命关闭码给出明确提示。
70
68
 
71
69
  ### M2 — 单人聊天与完整回复(F2 文本 + F4 非流式 + reply-budget.ts)
72
70
 
@@ -88,20 +86,20 @@ pi-qq/
88
86
 
89
87
  **验收**:QQ 发任务 → 不发送确认 → 10s 内收到首个汇总帧 → typing 持续 → 心跳按期到达(流或消息)→ 结果回传不双发。
90
88
 
91
- ### M3 — 用量摘要(F5 + F6)
89
+ ### M3 — 用量摘要(已取消)
92
90
 
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 发送。
91
+ 用量摘要已按用户要求移除:
96
92
 
97
- **验收**:每轮对话后 QQ 收到一条三行摘要,数字与本次 run 实际用量一致。
93
+ - 不再在 `agent_end` 汇总或发送 token/缓存/成本/上下文摘要。
94
+ - 上下文占比通过 QQ 侧 `/status` 或 pi 终端 `/qq-status` 查看。
95
+ - `src/usage.ts`、`usageRelay` 配置和对应单测已删除。
96
+ - 收益:每轮少一条 QQ 消息,降低被动额度消耗。
98
97
 
99
98
  ### M4 — 图片与打磨(F3 + markdownSupport 透传)
100
99
 
101
100
  1. [x] F3 图片/文件:图片转 `ImageContent`;非图片附件保存到当前工作空间的 `.pi/pi-qq/YYYY-MM-DD/<msgId>/`,提示词中追加绝对路径、大小与原始文件名;`fileMaxSize` 默认 50MB。
102
101
  2. [x] `markdownSupport: true`:`QQBot` 构造时已传入该开关,SDK 的 `sendText` 自动使用 msg_type=2;调用方保留原始 Markdown 即可,无需额外 `sendMarkdown`。
103
102
  3. [x] QQ 侧 `/new`:inbound 调用隐藏扩展命令 `qq-new`,命令 handler 使用 `ctx.newSession()`;非 idle 时提示先 `/stop`。
104
- 4. [ ] 长代码块转文件附件(backlog);多气泡 + 摘要额度实测已完成。
105
103
 
106
104
  **验收**:QQ 发图后 pi 能描述图片内容;QQ 发文件后保存到本机并在提示词中关联路径;额度全程不超限。
107
105
 
@@ -118,7 +116,7 @@ pi-qq/
118
116
  | 流式消息对非 C2C/过期 `msgId` 抛错 | 流式路径崩溃 | `openStream` 前置校验,失败即降级 `sendText`(M4 已含) |
119
117
  | 被动额度耗尽(长 run 多回复) | 消息发不出去 | reply-budget 统一发牌,超限降级主动+提示;摘要固定合并 |
120
118
  | markdown 转换漏判 | QQ 端残留记号 | 转换函数单测覆盖常见结构;允许透传开关兜底 |
121
- | connector 混淆代码异常 / 扫码接口变更 | 扫码不可用 | 方式 A 直连始终可用(不依赖 connector) |
119
+ | connector 混淆代码异常 / 扫码接口变更 | 无法登录 | 重试扫码;升级 connector;保留日志排查 |
122
120
  | pi 事件在非 TUI 模式无 UI | 扩展报错 | 所有 `ctx.ui` 调用前判 `ctx.hasUI`/`ctx.mode` |
123
121
 
124
122
  ## 6. Todo-List(随进度勾选)
@@ -127,16 +125,16 @@ pi-qq/
127
125
 
128
126
  - [x] 依赖安装:`@tencent-connect/qqbot-nodejs` + `@tencent-connect/qqbot-connector` + `qrcode-terminal`(用户已执行)
129
127
  - [x] pi / SDK / connector API 签名核对(types.d.ts + 本地源码)
130
- - [x] `package.json` 完善(`type: module`、private、description)
128
+ - [x] `package.json` 完善(`type: module`、description;发布时移除 private)
131
129
  - [x] `tsconfig.json`(`moduleResolution: bundler`;`paths` 借用 pi 发行目录类型 + `typeRoots` 借用其 @types/node,typecheck 走 `npx typescript`,无需安装 devDeps)
132
130
 
133
131
  ### M1 — 登录接入与连接
134
132
 
135
- - [x] `src/config.ts`:`~/.pi/agent/pi-qq.json` 读写(`AppID`/`AppSecret` 大小写兼容、字段合并保留、`0600`、credentials/allowedOpenid 存取)
133
+ - [x] `src/config.ts`:`~/.pi/agent/pi-qq.json` 只读设置(不含凭据)
136
134
  - [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` 与扫码路径如未触发可在后续使用中观察)
135
+ - [x] `src/login.ts`:仅扫码 `startQrConnect`(含二维码展示与取消;凭据返回内存)
136
+ - [x] `index.ts`:`/qq-login` `/qq-status` `/qq-logout` 命令 + 内存登录态 + `session_start` 接入 + `session_shutdown` 幂等停止
137
+ - [x] 验收:扫码在线 / pi 重启后重新扫码 / `4914` `4915` 明确提示(扫码路径已实测;`4914/4915` 如未触发可在后续观察)
140
138
 
141
139
  ### M2 — 单人聊天与完整回复(非流式)
142
140
 
@@ -155,8 +153,8 @@ pi-qq/
155
153
  - [x] `index.ts`:`agent_start`/`agent_end`/`tool_execution_end`/`message_update` 接线;`message_end` 流接管判定
156
154
  - [x] 单测:`formatHeartbeat`(test/run.ts 共 33 项断言)
157
155
  - [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 模式。
156
+ - 首轮实测(2026-10-28):确认/typing 正常;SDK 内置流式 replace 语义被平台拒绝("已经提交的消息内容不可修改",首帧可渲染、第二帧报错);C2C markdown 渲染正常(`/qq-test-md` ✓)。
157
+ - 修复:自实现 `src/append-stream.ts`(input_mode="append",追加语义),RunFeedback 改为增量追加,`/qq-test-stream` 改测 append 模式。
160
158
  - 复验(2026-10-28):append 两帧 + DONE 全部渲染 ✓,流式链路打通。后续任务:心跳/结果追加需开启 `streamRelay: true`。
161
159
  - 时间线升级(用户构想):流式气泡改为**回合活动时间线**——💭 思考中…(惰性标记,不回传内容)/ 🔧 工具名(tool_execution_start)/ 智能体消息原文(流式增量)依次追加,心跳与 DONE 照旧;帧失败自动降级消息路径并补发未发结果。
162
160
  - 汇总帧重构(用户构想):逐事件追加改为**固定 3s 窗口汇总帧**——思考状态行 + 工具计数行(`[n] 🔧 name`)+ 消息文本增量,按设计稿分组排版;流式帧按 markdown 渲染(实测),故流内传原始文本。用户实测反馈:长思考/长工具期间静默——已加行组帧时间戳 + 空窗口 60s 活性行 + flush 队列串行化(防限流重试与定时器交错)。追加 debug 开关(SDK 日志转终端 + 文本帧时间戳)用于定位用户报告的「超时」现象。
@@ -166,16 +164,14 @@ pi-qq/
166
164
  - 四轮实测(2026-10-29,`log/pi.jsonl` + `log/qq.png`):首条中间文本(工具活动之后的 assistant 消息)被并入活动气泡,未独立成泡。根因:切泡条件要求旧气泡已含文本,而首条文本之前只有思考/工具行组。修复:文本消息首个增量到达时,只要当前气泡已有内容就封口(含仅行组);工具计数行格式改为 `[n] 🔧 name`(心跳同步),新增活动气泡→文本气泡回归断言。
167
165
  - 五轮调整(2026-10-29,用户要求):删除 t=0 的"✅ 已收到"开始确认(含忙碌合并提示),节省被动额度;汇总帧默认间隔 3000ms → 10000ms,工具调用每 10s 汇总一次(`streamFlushMs` 仍可配置)。
168
166
  - 六轮调整(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("")`,冲刷行组并重置逐消息状态;新增“无文本消息不吞后续行组”回归断言。
167
+ - 七轮自检(2026-10-29,`log/pi.png` + `log/qq.png`):当时的用量摘要与 pi Session Info 一致(该摘要后来已移除)。发现无文本 assistant 消息不走 `onAssistantFinal`,逐消息思考标记未重置,导致下一条消息的 thinking 行被吞(截图中 read 前缺 thinking)。修复:`message_end` 对无文本 assistant 也调用 `onAssistantFinal("")`,冲刷行组并重置逐消息状态;新增“无文本消息不吞后续行组”回归断言。
170
168
  - 八轮调整(2026-10-29,重跑截图):read 与下一条消息的 thinking 落入同一 10s 窗口时,旧逻辑固定“thinking 优先”,显示顺序与真实事件相反(应 read → thinking → bash)。修复:窗口行组改为 `winLines` 事件序列,按事件到达顺序输出;连续同名工具合并计数;新增严格顺序回归断言。
171
169
 
172
- ### M3 — 用量摘要
170
+ ### M3 — 用量摘要(已取消)
173
171
 
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 个测试通过)。
172
+ - [x] 按用户要求移除每轮用量摘要;上下文占比改用 `/status` / `/qq-status`
173
+ - [x] 删除 `src/usage.ts`、`usageRelay` 配置及对应测试
174
+ - 当前全量:8 个测试文件 / 77 个测试通过。
179
175
 
180
176
  ### M4 — 图片与打磨
181
177
 
@@ -184,12 +180,11 @@ pi-qq/
184
180
  - [x] `/compact` 命令、typing 指示(C2C)
185
181
  - [x] `markdownSupport: true`:SDK `sendText` 自动 msg_type=2(无需新增 sendMarkdown 路径)
186
182
  - [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 / 窗口有效)
183
+ - [x] `/qq-test-budget` 诊断命令(普通被动剩余 / 流式气泡数 / 估算剩余 / 最近 msgId 新鲜度)
184
+ - [x] 单元测试迁移到 vitest(`test/*.test.ts`,8 个文件 / 77 个测试;`npm test`)
185
+ - [x] 多气泡流式额度实测(2026-10-29:当时包含 1 条摘要;摘要后来已移除,仅作历史记录)
191
186
  - [x] `debug` 抓超时日志:AppendStream 限流重试/最终失败 + run start/end 日志
192
187
  - [x] 验收:QQ 发图后 pi 能描述图片内容;全程额度不超限(2026-10-29 实测通过)
193
- - [ ] 文件传输实机验收(QQ 发 zip/pdf 等,确认保存路径与提示词关联)
188
+ - [x] 文件传输实机验收(2026-10-29 用户实测通过:QQ 发 zip/pdf 等文件,保存到工作空间 `.pi/pi-qq/` 并在提示词中关联路径)
194
189
  - 2026-10-29:图片+文字、纯图片(均被模型正确识别)、非图片附件拒绝(zip 提示“附件处理失败”)、多气泡+摘要额度诊断已实测通过。
195
190
  - 无视觉模型场景按用户决定不验证(代码仍保留 `ctx.model.input` 检查)。