@chen_hu_hu/pi-qq 1.2.2 → 1.3.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/README-zh.md +48 -24
- package/README.md +40 -16
- package/doc/delivery-v1-zh.md +160 -0
- package/doc/delivery-v1.md +160 -0
- package/doc/delivery-v2-zh.md +100 -0
- package/doc/delivery-v2.md +98 -0
- package/doc/delivery-v3-zh.md +187 -0
- package/doc/delivery-v3.md +187 -0
- package/index.ts +71 -66
- package/package.json +8 -2
- package/src/{download.ts → attachments/attachment-download.ts} +2 -5
- package/src/{files.ts → attachments/file-attachments.ts} +4 -15
- package/src/{images.ts → attachments/image-attachments.ts} +3 -10
- package/src/{voice.ts → attachments/voice-transcript.ts} +1 -7
- package/src/{format.ts → infra/display-format.ts} +0 -2
- package/src/{logger.ts → infra/file-logger.ts} +6 -28
- package/src/infra/settings.ts +49 -0
- package/src/{bot.ts → qq/qq-bot.ts} +4 -29
- package/src/{inbound.ts → qq/qq-message-handler.ts} +10 -23
- package/src/{login.ts → qq/qr-login.ts} +20 -16
- package/src/{outbound.ts → qq/reply-sender.ts} +3 -34
- package/src/qrcode-terminal.d.ts +0 -2
- package/src/{budget-status.ts → quota/reply-quota-report.ts} +2 -3
- package/src/{reply-budget.ts → quota/reply-quota.ts} +0 -21
- package/src/relay/run-stream-relay.ts +586 -0
- package/src/relay/stream-block-format.ts +114 -0
- package/src/{append-stream.ts → relay/stream-session.ts} +46 -29
- package/doc/features-v1.md +0 -239
- package/doc/features-v2.md +0 -210
- package/doc/plan-v1.md +0 -190
- package/doc/plan-v2.md +0 -332
- package/src/config.ts +0 -82
- package/src/run-feedback.ts +0 -410
package/doc/plan-v1.md
DELETED
|
@@ -1,190 +0,0 @@
|
|
|
1
|
-
# pi-qq — plan-v1.md
|
|
2
|
-
|
|
3
|
-
> 执行计划。功能范围与决策见 [features-v1.md](./features-v1.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 | 扫码登录(唯一登录方式) |
|
|
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 只读设置(不含凭据)
|
|
32
|
-
├── login.ts # F1:仅扫码登录(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 # 人类可读字节/ token 数格式化
|
|
39
|
-
├── outbound.ts # F4:markdown→纯文本转换、流式(openStream)/降级(sendText)、分块
|
|
40
|
-
├── reply-budget.ts # §3:被动回复预算(msgId 5min 窗口、4条/h、降级主动发送)
|
|
41
|
-
└── budget-status.ts # /qq-test-budget 纯格式化(普通/流式/估算剩余)
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
职责边界:`index.ts` 只做装配与订阅,不含业务逻辑;每个模块可独立测试;模块间只经 `index.ts` 传递的共享状态对象(bot 实例、当前 target/msgId、配置)通信。
|
|
45
|
-
|
|
46
|
-
## 2. pi 事件与 SDK 接线总表
|
|
47
|
-
|
|
48
|
-
| 方向 | 信号 | 处理 |
|
|
49
|
-
| ------- | ------------------------------------ | --------------------------------------------------------------------------------------------------- |
|
|
50
|
-
| QQ → pi | `bot.on("message")`(kind=c2c) | 白名单 → QQ 命令(`/new` `/stop` `/compact` `/status` `/help`)→ 文本+图片 → `pi.sendUserMessage()` |
|
|
51
|
-
| pi → QQ | `message_update`(assistant) | 流式:`openStream().update(转换后全文)`,节流 ≥300ms |
|
|
52
|
-
| pi → QQ | `message_end`(assistant) | `stream.complete()`;无流上下文时 `sendText`;`stopReason==="error"` 回错误摘要 |
|
|
53
|
-
| 状态 | `session_start` / `session_shutdown` | 有内存登录态则启动 bot / 幂等停止 |
|
|
54
|
-
| 收尾 | `agent_end` | 封口最后一个流式气泡(DONE);不再发送用量摘要 |
|
|
55
|
-
|
|
56
|
-
## 3. 里程碑
|
|
57
|
-
|
|
58
|
-
### M1 — 登录接入与连接(F1 + bot.ts + config.ts)
|
|
59
|
-
|
|
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`。
|
|
62
|
-
3. `login.ts` + `index.ts`:
|
|
63
|
-
- `session_start`:进程内存有登录态则启动;否则提示 `/qq-login`。
|
|
64
|
-
- `/qq-login`:`startQrConnect`(`displayQrCodeToConsole: false`),`onQrDisplayed` 在 TUI 弹窗画二维码(`qrcode-terminal`),`onSuccess` 把凭据与 openid 存入内存并启动。
|
|
65
|
-
- `/qq-status`(内存登录/连接/绑定用户)、`/qq-logout`(清内存凭据)。
|
|
66
|
-
|
|
67
|
-
**验收**:扫码后 `/qq-status` 在线;pi 进程重启后需重新扫码;`4914/4915` 致命关闭码给出明确提示。
|
|
68
|
-
|
|
69
|
-
### M2 — 单人聊天与完整回复(F2 文本 + F4 非流式 + reply-budget.ts)
|
|
70
|
-
|
|
71
|
-
1. `inbound.ts`:C2C 白名单过滤、QQ 命令拦截(`/stop`→`ctx.abort()`、`/new`→扩展命令 `qq-new`→`ctx.newSession()`、`/status` 汇总、`/help`)、文本 → `sendUserMessage`;忙碌时 `deliverAs` 排队。
|
|
72
|
-
2. `outbound.ts` 非流式路径:markdown→纯文本转换函数(独立、可单测:强调/标题/列表/链接/表格退化)+ `TEXT_CHUNK_LIMIT` 分块。
|
|
73
|
-
3. `reply-budget.ts`:按 `msgId` 记录被动回复次数与 5min 窗口;超限降级主动发送并提示。
|
|
74
|
-
|
|
75
|
-
**验收**:QQ 发"你好"→ QQ 收到 pi 回复(纯文本、无 markdown 记号残留);连续对话额度不炸;非绑定用户发消息无任何反应。
|
|
76
|
-
|
|
77
|
-
### M2.5 — 长任务反馈包(F7,已拍板)
|
|
78
|
-
|
|
79
|
-
背景:实际场景 `user_input → thinking+tools(10~60 分钟)→ assistant message`,结果只在末尾出现一次。
|
|
80
|
-
|
|
81
|
-
1. `src/run-feedback.ts`:run 级状态机 —— QQ 触发标记(pending)、工具名×次数计数(`tool_execution_end`)、流会话(`openStream` 惰性开启:首次心跳或首次文本时尝试,失败标 dead)、typing keepalive 定时器(50s)、节流心跳定时器(默认 10min)、消息心跳保险丝(每 run ≤3)、`agent_end` 收尾(complete/cancel/清 timer)。
|
|
82
|
-
2. 载体优先级:流式心跳(一条消息持续刷新,0 额度)→ 消息心跳(≤3 条)→ 静默;结果文本在流存活时直接续写同一条流,`message_end` 被流接管时跳过 sendReply(避免双发)。
|
|
83
|
-
3. `inbound.ts`:不发送开始确认(节省被动额度),仅 `markQQTrigger`。
|
|
84
|
-
4. `index.ts`:接线 `agent_start` / `agent_end` / `tool_execution_end` / `message_update`。
|
|
85
|
-
5. `config.ts`:`heartbeatMinutes`(默认 10)、`heartbeatMaxMessages`(默认 3)。
|
|
86
|
-
|
|
87
|
-
**验收**:QQ 发任务 → 不发送确认 → 10s 内收到首个汇总帧 → typing 持续 → 心跳按期到达(流或消息)→ 结果回传不双发。
|
|
88
|
-
|
|
89
|
-
### M3 — 用量摘要(已取消)
|
|
90
|
-
|
|
91
|
-
用量摘要已按用户要求移除:
|
|
92
|
-
|
|
93
|
-
- 不再在 `agent_end` 汇总或发送 token/缓存/成本/上下文摘要。
|
|
94
|
-
- 上下文占比通过 QQ 侧 `/status` 或 pi 终端 `/qq-status` 查看。
|
|
95
|
-
- `src/usage.ts`、`usageRelay` 配置和对应单测已删除。
|
|
96
|
-
- 收益:每轮少一条 QQ 消息,降低被动额度消耗。
|
|
97
|
-
|
|
98
|
-
### M4 — 图片与打磨(F3 + markdownSupport 透传)
|
|
99
|
-
|
|
100
|
-
1. [x] F3 图片/文件:图片转 `ImageContent`;非图片附件保存到当前工作空间的 `.pi/pi-qq/YYYY-MM-DD/<msgId>/`,提示词中追加绝对路径、大小与原始文件名;`fileMaxSize` 默认 50MB。
|
|
101
|
-
2. [x] `markdownSupport: true`:`QQBot` 构造时已传入该开关,SDK 的 `sendText` 自动使用 msg_type=2;调用方保留原始 Markdown 即可,无需额外 `sendMarkdown`。
|
|
102
|
-
3. [x] QQ 侧 `/new`:inbound 调用隐藏扩展命令 `qq-new`,命令 handler 使用 `ctx.newSession()`;非 idle 时提示先 `/stop`。
|
|
103
|
-
|
|
104
|
-
**验收**:QQ 发图后 pi 能描述图片内容;QQ 发文件后保存到本机并在提示词中关联路径;额度全程不超限。
|
|
105
|
-
|
|
106
|
-
## 4. 验证策略
|
|
107
|
-
|
|
108
|
-
- **静态**:`npx tsc --noEmit`(tsconfig 仅类型检查)。
|
|
109
|
-
- **单测**(vitest,纯函数优先):markdown→纯文本转换、分块、reply-budget 状态机、config 读写合并。SDK 与 pi 事件层不做单测,靠 M1–M4 验收手动覆盖。
|
|
110
|
-
- **手动验收**:每个里程碑按上表验收项在真实 QQ 环境跑一遍;`baseUrl` 可指向 mock 验证协议路径(SDK 测试有先例)。
|
|
111
|
-
|
|
112
|
-
## 5. 风险与预案
|
|
113
|
-
|
|
114
|
-
| 风险 | 影响 | 预案 |
|
|
115
|
-
| ------------------------------------- | ------------- | ------------------------------------------------------- |
|
|
116
|
-
| 流式消息对非 C2C/过期 `msgId` 抛错 | 流式路径崩溃 | `openStream` 前置校验,失败即降级 `sendText`(M4 已含) |
|
|
117
|
-
| 被动额度耗尽(长 run 多回复) | 消息发不出去 | reply-budget 统一发牌,超限降级主动+提示;摘要固定合并 |
|
|
118
|
-
| markdown 转换漏判 | QQ 端残留记号 | 转换函数单测覆盖常见结构;允许透传开关兜底 |
|
|
119
|
-
| connector 混淆代码异常 / 扫码接口变更 | 无法登录 | 重试扫码;升级 connector;保留日志排查 |
|
|
120
|
-
| pi 事件在非 TUI 模式无 UI | 扩展报错 | 所有 `ctx.ui` 调用前判 `ctx.hasUI`/`ctx.mode` |
|
|
121
|
-
|
|
122
|
-
## 6. Todo-List(随进度勾选)
|
|
123
|
-
|
|
124
|
-
### 准备
|
|
125
|
-
|
|
126
|
-
- [x] 依赖安装:`@tencent-connect/qqbot-nodejs` + `@tencent-connect/qqbot-connector` + `qrcode-terminal`(用户已执行)
|
|
127
|
-
- [x] pi / SDK / connector API 签名核对(types.d.ts + 本地源码)
|
|
128
|
-
- [x] `package.json` 完善(`type: module`、description;发布时移除 private)
|
|
129
|
-
- [x] `tsconfig.json`(`moduleResolution: bundler`;`paths` 借用 pi 发行目录类型 + `typeRoots` 借用其 @types/node,typecheck 走 `npx typescript`,无需安装 devDeps)
|
|
130
|
-
|
|
131
|
-
### M1 — 登录接入与连接
|
|
132
|
-
|
|
133
|
-
- [x] `src/config.ts`:`~/.pi/agent/pi-qq.json` 只读设置(不含凭据)
|
|
134
|
-
- [x] `src/bot.ts`:`createBot/start/stop`、中间件装配(messageFilter/accessPolicy/concurrencyGuard)、连接状态跟踪、致命关闭码上报
|
|
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` 如未触发可在后续观察)
|
|
138
|
-
|
|
139
|
-
### M2 — 单人聊天与完整回复(非流式)
|
|
140
|
-
|
|
141
|
-
- [x] `src/inbound.ts`:白名单 → QQ 命令拦截(`/new` `/stop` `/compact` `/status` `/help`)→ 文本 `sendUserMessage` + `deliverAs` 排队
|
|
142
|
-
- [x] `src/outbound.ts`:markdown→纯文本转换(独立可单测)+ `TEXT_CHUNK_LIMIT` 分块
|
|
143
|
-
- [x] `src/reply-budget.ts`:被动回复预算(5min 窗口 / 4条每小时)+ 降级主动发送
|
|
144
|
-
- [x] `message_end`(assistant)非流式回传接线 + `stopReason==="error"` 错误摘要
|
|
145
|
-
- [x] 单测:markdown 转换 / 分块 / reply-budget(jiti + assert 脚本 `test/run.ts`,30 项断言;config 12 项在 M1 已验)
|
|
146
|
-
- [x] 验收:QQ 发消息→收到纯文本回复;非绑定用户无反应;额度不超限(用户实测通过)
|
|
147
|
-
|
|
148
|
-
### M2.5 — 长任务反馈包
|
|
149
|
-
|
|
150
|
-
- [x] `src/run-feedback.ts`:run 级状态机(QQ 触发标记、工具计数、流会话惰性开启、typing/心跳定时器、消息心跳保险丝)+ `formatHeartbeat`
|
|
151
|
-
- [x] `config.ts`:`heartbeatMinutes` / `heartbeatMaxMessages`
|
|
152
|
-
- [x] `inbound.ts`:`markQQTrigger`(不发送开始确认,2026-10-29 调整)
|
|
153
|
-
- [x] `index.ts`:`agent_start`/`agent_end`/`tool_execution_end`/`message_update` 接线;`message_end` 流接管判定
|
|
154
|
-
- [x] 单测:`formatHeartbeat`(test/run.ts 共 33 项断言)
|
|
155
|
-
- [x] 验收:QQ 发任务 → 不发送确认 → 10s 内收到汇总帧 → typing 持续 → 心跳按期 → 结果回传不双发(用户实测通过)
|
|
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 模式。
|
|
158
|
-
- 复验(2026-10-28):append 两帧 + DONE 全部渲染 ✓,流式链路打通。后续任务:心跳/结果追加需开启 `streamRelay: true`。
|
|
159
|
-
- 时间线升级(用户构想):流式气泡改为**回合活动时间线**——💭 思考中…(惰性标记,不回传内容)/ 🔧 工具名(tool_execution_start)/ 智能体消息原文(流式增量)依次追加,心跳与 DONE 照旧;帧失败自动降级消息路径并补发未发结果。
|
|
160
|
-
- 汇总帧重构(用户构想):逐事件追加改为**固定 3s 窗口汇总帧**——思考状态行 + 工具计数行(`[n] 🔧 name`)+ 消息文本增量,按设计稿分组排版;流式帧按 markdown 渲染(实测),故流内传原始文本。用户实测反馈:长思考/长工具期间静默——已加行组帧时间戳 + 空窗口 60s 活性行 + flush 队列串行化(防限流重试与定时器交错)。追加 debug 开关(SDK 日志转终端 + 文本帧时间戳)用于定位用户报告的「超时」现象。
|
|
161
|
-
- 回合独立气泡(用户反馈:内容全压一条气泡太挤):切分规则改为**每条带文本的 assistant 消息一个气泡**(首版按 message_start 切分产生大量迷你气泡——该模型每轮工具调用都发独立小消息,且 onToolStart 立即行与汇总帧双份报告)。文本驱动边界:新文本 + 当前气泡已含文本 → 封口开新泡;工具并入当前气泡。
|
|
162
|
-
- 二轮实测(2026-10-28,jsonl 事件时间线 vs 气泡时间戳):3s 汇总节奏准确(事件→帧延迟 0~3s)、无重复、91s 静默区活性行准时(60s 阈值)、markdown 渲染正常。M2.5 全部验收通过。首轮长任务实测三问题:① flushWindow 丢失 resultSentLen 推进导致累计文本重复重发(已修,帧内推进基准);② 心跳/汇总行补回 💭/🔧 图标;③ 帧节奏实为 3s,观感问题由①导致。
|
|
163
|
-
- 三轮实测(2026-10-29,用户 QQ 截图 + 会话日志):最终回复被追加 3 份,且最后一个气泡一直停留在“生成中”。根因是 `f806065` 重构丢失两处关键逻辑:① 成功追加文本后未推进 `resultSentLen`,每 3s 汇总帧重发全文;② `sealBubble` 在 `flushWindow` 前捕获旧 `cur`,切泡后新气泡收不到 DONE。修复:追加成功即推进基准;气泡边界仅在上一条文本消息定稿后触发(同消息的流式增量不再切泡);`sealBubble` 在 flush 后重读 `cur`;错误路径先封口再走消息链路。新增重复/单气泡/双气泡/错误 DONE 回归断言。
|
|
164
|
-
- 四轮实测(2026-10-29,`log/pi.jsonl` + `log/qq.png`):首条中间文本(工具活动之后的 assistant 消息)被并入活动气泡,未独立成泡。根因:切泡条件要求旧气泡已含文本,而首条文本之前只有思考/工具行组。修复:文本消息首个增量到达时,只要当前气泡已有内容就封口(含仅行组);工具计数行格式改为 `[n] 🔧 name`(心跳同步),新增活动气泡→文本气泡回归断言。
|
|
165
|
-
- 五轮调整(2026-10-29,用户要求):删除 t=0 的"✅ 已收到"开始确认(含忙碌合并提示),节省被动额度;汇总帧默认间隔 3000ms → 10000ms,工具调用每 10s 汇总一次(`streamFlushMs` 仍可配置)。
|
|
166
|
-
- 六轮调整(2026-10-29,用户 QQ 截图):中间文本消息与工具汇总混在同一气泡(如“已写入…”后紧跟 read 行)。改为**文本/活动严格分泡**:每条 assistant 文本独占纯文本气泡,思考/工具行组进活动气泡,文本前后的工具均另起活动气泡;新增“活动→文本→活动→文本→活动→最终文本”六气泡交错回归断言。
|
|
167
|
-
- 七轮自检(2026-10-29,`log/pi.png` + `log/qq.png`):当时的用量摘要与 pi Session Info 一致(该摘要后来已移除)。发现无文本 assistant 消息不走 `onAssistantFinal`,逐消息思考标记未重置,导致下一条消息的 thinking 行被吞(截图中 read 前缺 thinking)。修复:`message_end` 对无文本 assistant 也调用 `onAssistantFinal("")`,冲刷行组并重置逐消息状态;新增“无文本消息不吞后续行组”回归断言。
|
|
168
|
-
- 八轮调整(2026-10-29,重跑截图):read 与下一条消息的 thinking 落入同一 10s 窗口时,旧逻辑固定“thinking 优先”,显示顺序与真实事件相反(应 read → thinking → bash)。修复:窗口行组改为 `winLines` 事件序列,按事件到达顺序输出;连续同名工具合并计数;新增严格顺序回归断言。
|
|
169
|
-
|
|
170
|
-
### M3 — 用量摘要(已取消)
|
|
171
|
-
|
|
172
|
-
- [x] 按用户要求移除每轮用量摘要;上下文占比改用 `/status` / `/qq-status`
|
|
173
|
-
- [x] 删除 `src/usage.ts`、`usageRelay` 配置及对应测试
|
|
174
|
-
- 当前全量:8 个测试文件 / 77 个测试通过。
|
|
175
|
-
|
|
176
|
-
### M4 — 图片与打磨
|
|
177
|
-
|
|
178
|
-
- [x] F3 图片/文件:图片注入;文件落盘 + 提示词路径关联 + `fileMaxSize`
|
|
179
|
-
- [x] 流式接线(M2.5 已完成,`AppendStream` + 文本/活动分泡)
|
|
180
|
-
- [x] `/compact` 命令、typing 指示(C2C)
|
|
181
|
-
- [x] `markdownSupport: true`:SDK `sendText` 自动 msg_type=2(无需新增 sendMarkdown 路径)
|
|
182
|
-
- [x] QQ 侧 `/new` 支持(`qq-new` 扩展命令 → `ctx.newSession()`)
|
|
183
|
-
- [x] `/qq-test-budget` 诊断命令(普通被动剩余 / 流式气泡数 / 估算剩余 / 最近 msgId 新鲜度)
|
|
184
|
-
- [x] 单元测试迁移到 vitest(`test/*.test.ts`,8 个文件 / 77 个测试;`npm test`)
|
|
185
|
-
- [x] 多气泡流式额度实测(2026-10-29:当时包含 1 条摘要;摘要后来已移除,仅作历史记录)
|
|
186
|
-
- [x] `debug` 抓超时日志:AppendStream 限流重试/最终失败 + run start/end 日志
|
|
187
|
-
- [x] 验收:QQ 发图后 pi 能描述图片内容;全程额度不超限(2026-10-29 实测通过)
|
|
188
|
-
- [x] 文件传输实机验收(2026-10-29 用户实测通过:QQ 发 zip/pdf 等文件,保存到工作空间 `.pi/pi-qq/` 并在提示词中关联路径)
|
|
189
|
-
- 2026-10-29:图片+文字、纯图片(均被模型正确识别)、非图片附件拒绝(zip 提示“Attachment failed”)、多气泡+摘要额度诊断已实测通过。
|
|
190
|
-
- 无视觉模型场景按用户决定不验证(代码仍保留 `ctx.model.input` 检查)。
|
package/doc/plan-v2.md
DELETED
|
@@ -1,332 +0,0 @@
|
|
|
1
|
-
# pi-qq — plan-v2.md
|
|
2
|
-
|
|
3
|
-
> 执行计划。功能范围见 [features-v2.md](./features-v2.md);本文只回答:改哪些文件、按什么顺序做、每步怎么验收。
|
|
4
|
-
> V2 范围:F8 语音自动转写、F9 轻量日志基础设施、F10 文件消息等待指令、F11 文件存储与去重。不引入新依赖。
|
|
5
|
-
|
|
6
|
-
## 0. 前置与范围
|
|
7
|
-
|
|
8
|
-
- 无新增 npm 依赖;日志使用 Node 标准库自研。
|
|
9
|
-
- 基线:当前 v1 代码,`npm test` 77 个测试通过。
|
|
10
|
-
- 不实现:本地 Whisper、外部 STT、保存原始语音、语音命令解析。
|
|
11
|
-
- 语音只处理 `content_type === "voice"`;不扩展其他媒体类型。
|
|
12
|
-
- 日志默认 `silent`;需要排查时手动改为 `info` / `debug`。
|
|
13
|
-
|
|
14
|
-
## 1. 目录与模块
|
|
15
|
-
|
|
16
|
-
```text
|
|
17
|
-
pi-qq/
|
|
18
|
-
├── src/
|
|
19
|
-
│ ├── logger.ts # 新增:级别过滤、JSONL、按天单文件、SDK logger 适配
|
|
20
|
-
│ ├── voice.ts # 新增:语音附件判断、ASR 文本提取
|
|
21
|
-
│ ├── config.ts # 修改:logLevel、旧 debug 迁移
|
|
22
|
-
│ ├── inbound.ts # 修改:语音分支 + 日志分级 + pending + session uploads
|
|
23
|
-
│ ├── files.ts # 修改:session uploads、SHA-256 去重、索引维护
|
|
24
|
-
│ ├── bot.ts # 修改:接入 logger,移除 debug 选项
|
|
25
|
-
│ ├── index.ts # 修改:配置 logger,移除 getDebug,日志分级
|
|
26
|
-
│ ├── outbound.ts # 修改:发送日志分级
|
|
27
|
-
│ └── run-feedback.ts # 修改:移除 debug 时间戳,改用 logger
|
|
28
|
-
├── test/
|
|
29
|
-
│ ├── logger.test.ts # 新增
|
|
30
|
-
│ ├── voice.test.ts # 新增
|
|
31
|
-
│ ├── config.test.ts # 新增或扩展现有设置测试
|
|
32
|
-
│ ├── inbound.test.ts # 修改
|
|
33
|
-
│ ├── bot.test.ts # 新增:message handler 串行回归
|
|
34
|
-
│ └── run-feedback.test.ts # 修改
|
|
35
|
-
├── README.md # 修改:logLevel、日志路径、语音说明
|
|
36
|
-
└── doc/features-v2.md # 已存在,按实现结果校正
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## 2. 执行步骤
|
|
40
|
-
|
|
41
|
-
### M5a-1 — 实现 logger
|
|
42
|
-
|
|
43
|
-
**改动**
|
|
44
|
-
|
|
45
|
-
1. 新增 `src/logger.ts`:
|
|
46
|
-
- `LogLevel = "silent" | "error" | "warn" | "info" | "debug"`。
|
|
47
|
-
- `configureLogger(level, dir?)`、`getLogLevel()`。
|
|
48
|
-
- `log.error/warn/info/debug(scope, message, data?)`。
|
|
49
|
-
- `sdkLogger`:适配 SDK 的 `(message, meta?)` 接口,统一写入同一个 logger。
|
|
50
|
-
- `previewForLog(value, maxChars)`:截断工具参数/结果。
|
|
51
|
-
- 级别过滤:只输出当前级别及以上;`silent` 不写。
|
|
52
|
-
- 输出一行 JSON:`time`、`level`、`scope`、`msg` + 结构化字段。
|
|
53
|
-
- 文件路径:`<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。
|
|
54
|
-
- `PI_QQ_LOG_DIR` 可覆盖目录,供测试使用。
|
|
55
|
-
- 每次写入时重新计算日期;跨天自动换文件。
|
|
56
|
-
- 日志写入失败静默忽略,不影响消息处理。
|
|
57
|
-
2. 不新增 `debug-log.ts`;不保留临时调试文件。
|
|
58
|
-
|
|
59
|
-
**验证**
|
|
60
|
-
|
|
61
|
-
- 单测覆盖:级别过滤、日期文件名、`previewForLog`、写入失败不抛错。
|
|
62
|
-
- `logLevel: "silent"` 不产生文件。
|
|
63
|
-
- `logLevel: "debug"` 能写入一行合法 JSON。
|
|
64
|
-
- `src/logger.ts` 不依赖第三方包。
|
|
65
|
-
|
|
66
|
-
### M5a-2 — 配置与接线
|
|
67
|
-
|
|
68
|
-
**改动**
|
|
69
|
-
|
|
70
|
-
1. `src/config.ts`:
|
|
71
|
-
- 新增 `logLevel?: LogLevel`,默认 `silent`。
|
|
72
|
-
- 保留 `debug?: boolean` 仅用于旧配置迁移:`debug: true` → `logLevel: "debug"`,其他情况默认 `silent`。
|
|
73
|
-
- `ResolvedSettings` 移除 `debug`。
|
|
74
|
-
2. `src/index.ts`:
|
|
75
|
-
- 在 `session_start` / `startWithCredentials` 读取设置并 `configureLogger(settings.logLevel)`。
|
|
76
|
-
- 日志目录使用当前工作区 `ctx.cwd`;未配置时 logger 回退到 `process.cwd()`。
|
|
77
|
-
- 移除 `getDebug` 依赖和 `settings.debug` 传递。
|
|
78
|
-
3. `src/bot.ts`:
|
|
79
|
-
- `StartBotOptions` 移除 `debug`。
|
|
80
|
-
- `new QQBot({ logger: sdkLogger })`。
|
|
81
|
-
- 连接状态用 info;连接失败/异常用 error;入站 raw 用 debug。
|
|
82
|
-
4. `src/inbound.ts` / `src/outbound.ts`:
|
|
83
|
-
- 详细事件用 debug。
|
|
84
|
-
- 入站/出站摘要用 info。
|
|
85
|
-
- 附件失败、ASR 为空、发送降级用 warn。
|
|
86
|
-
- 发送失败、handler 异常用 error。
|
|
87
|
-
5. `src/run-feedback.ts`:
|
|
88
|
-
- 移除 `getDebug` 和 QQ 气泡时间戳。
|
|
89
|
-
- 内部诊断改用 `log.debug` / `log.warn`。
|
|
90
|
-
|
|
91
|
-
**验证**
|
|
92
|
-
|
|
93
|
-
- `getSettings({}).logLevel === "silent"`。
|
|
94
|
-
- `getSettings({ debug: true }).logLevel === "debug"`。
|
|
95
|
-
- `getSettings({ logLevel: "info" }).logLevel === "info"`。
|
|
96
|
-
- 非法 `logLevel` 回退到 `silent`。
|
|
97
|
-
- 代码中除迁移读取外不再引用 `debug` 配置。
|
|
98
|
-
- `npm run typecheck` 通过。
|
|
99
|
-
|
|
100
|
-
### M5a-3 — 日志行为验收
|
|
101
|
-
|
|
102
|
-
**验证**
|
|
103
|
-
|
|
104
|
-
1. `logLevel: "silent"`:发送 QQ 消息后,`<cwd>/.pi/pi-qq/logs/` 不新增日志。
|
|
105
|
-
2. `logLevel: "info"`:日志只含元数据,不含消息正文、prompt、工具参数。
|
|
106
|
-
3. `logLevel: "debug"`:日志包含 raw 事件、附件、prompt、工具参数/结果、消息正文。
|
|
107
|
-
4. 日期跨天:用注入时间或临时目录测试文件名从 `pi-qq-YYYY-MM-DD.log` 切换。
|
|
108
|
-
5. 目录不可写:消息仍正常处理,进程不崩溃。
|
|
109
|
-
|
|
110
|
-
### M5b-1 — 实现语音模块
|
|
111
|
-
|
|
112
|
-
**改动**
|
|
113
|
-
|
|
114
|
-
1. 新增 `src/voice.ts`:
|
|
115
|
-
- `isVoiceAttachment(attachment)`:仅当 `content_type === "voice"` 返回 true。
|
|
116
|
-
- `resolveVoiceTranscript(attachments)`:
|
|
117
|
-
- 只读取语音附件。
|
|
118
|
-
- `asr_refer_text` 去首尾空白。
|
|
119
|
-
- 过滤空值;多个非空文本按附件顺序换行拼接。
|
|
120
|
-
- 无有效文本返回 `undefined`。
|
|
121
|
-
2. 不下载 `url` / `voice_wav_url`,不保存语音文件。
|
|
122
|
-
|
|
123
|
-
**验证**
|
|
124
|
-
|
|
125
|
-
- `content_type === "voice"` 识别为语音。
|
|
126
|
-
- 普通文件、图片不识别为语音。
|
|
127
|
-
- `asr_refer_text` 为 `"测试。"` 返回 `"测试。"`。
|
|
128
|
-
- 空字符串、纯空白、缺失返回 `undefined`。
|
|
129
|
-
- 多个语音附件按顺序合并。
|
|
130
|
-
|
|
131
|
-
### M5b-2 — 接入 inbound
|
|
132
|
-
|
|
133
|
-
**改动**
|
|
134
|
-
|
|
135
|
-
1. `src/inbound.ts` 在图片/文件分流前增加语音分支:
|
|
136
|
-
- 提取 ASR 文本。
|
|
137
|
-
- 有文本:`markQQTrigger()` → `pi.sendUserMessage(text, { deliverAs })`,然后返回。
|
|
138
|
-
- 无文本:回复 `Could not transcribe this voice message; please resend or type it.`,不触发 run,然后返回。
|
|
139
|
-
2. 语音分支不调用 `resolveInboundImages()`,不调用 `saveInboundFiles()`。
|
|
140
|
-
3. 语音与文字不组合,语音转写不参与 QQ 命令解析。
|
|
141
|
-
4. 更新 `test/inbound.test.ts`:
|
|
142
|
-
- 有 ASR:`sendUserMessage` 收到文本;`saveFiles` 未被调用;`markQQTrigger` 调用 1 次。
|
|
143
|
-
- 空 ASR:只回复提示;不发送 user message;不触发 run。
|
|
144
|
-
- 语音不产生文件保存调用。
|
|
145
|
-
- 文字、图片、文件现有用例不回归。
|
|
146
|
-
|
|
147
|
-
**验证**
|
|
148
|
-
|
|
149
|
-
- `npm test -- test/voice.test.ts test/inbound.test.ts` 通过。
|
|
150
|
-
- 语音消息不会出现在 `saveInboundFiles()` 的附件参数中。
|
|
151
|
-
- 空 ASR 不会启动 agent。
|
|
152
|
-
|
|
153
|
-
### M5b-3 — F10 文件消息等待指令
|
|
154
|
-
|
|
155
|
-
**改动**
|
|
156
|
-
|
|
157
|
-
1. `src/inbound.ts` 增加 pending 文件队列,仅处理非图片文件:
|
|
158
|
-
- 文件消息保存后入队,不回复,不调用 `sendUserMessage` / `markQQTrigger`。
|
|
159
|
-
- 下一条文字或语音 ASR 文本出队,合并后走现有 `formatFilePrompt()`。
|
|
160
|
-
- 消费后清空;`/new` 清空;其他命令不消费。
|
|
161
|
-
- 部分失败只入队成功文件;图片、普通文字、文件+文字行为不变。
|
|
162
|
-
2. 更新 `test/inbound.test.ts`:
|
|
163
|
-
- 文件-only:保存、不回复、不发送 user message、不触发 run。
|
|
164
|
-
- 文件后文字:一次 run,提示词包含路径和文字。
|
|
165
|
-
- 连续文件:多个路径合并。
|
|
166
|
-
- 文件后语音:ASR 文本参与合并。
|
|
167
|
-
- `/new` 清空 pending。
|
|
168
|
-
|
|
169
|
-
**验证**
|
|
170
|
-
|
|
171
|
-
- `npm test -- test/inbound.test.ts` 通过。
|
|
172
|
-
- 文件-only 不启动 agent;下一条指令只启动一次。
|
|
173
|
-
- 图片行为与 v1 一致。
|
|
174
|
-
|
|
175
|
-
### M5b-4 — F11 文件存储与去重
|
|
176
|
-
|
|
177
|
-
**改动**
|
|
178
|
-
|
|
179
|
-
1. `src/inbound.ts`:文件保存路径改为 `<cwd>/.pi/pi-qq/<sessionId>/uploads/`,sessionId 来自 `ctx.sessionManager.getSessionId()`。
|
|
180
|
-
2. `src/files.ts`:
|
|
181
|
-
- 增加 `.index.json` 读写:`{ "<fileName>": "<sha256>" }`。
|
|
182
|
-
- 文件名不重复:保存、计算 SHA-256、写索引、引用。
|
|
183
|
-
- 同名不同内容:保存为下一个可用后缀名,写索引、引用新文件。
|
|
184
|
-
- 同名同内容:不保存,复用已有路径。
|
|
185
|
-
- 登录/会话启动:只检查索引中的文件是否存在,删除失效项;不重算所有 hash。
|
|
186
|
-
- 保存/复用前再次检查目标文件存在性;索引缺失或损坏时按需计算已有文件 hash。
|
|
187
|
-
- `bot.ts` 的 message handler 必须 await `onMessage`,让 SDK concurrencyGuard 持有锁到文件保存完成。
|
|
188
|
-
3. 更新 `test/files.test.ts` / `test/inbound.test.ts`:
|
|
189
|
-
- 路径、索引格式、三类保存规则。
|
|
190
|
-
- 删除文件后的索引清理与惰性回退。
|
|
191
|
-
- pending 同名同内容不重复入队;不同文件名同内容保留两份。
|
|
192
|
-
|
|
193
|
-
**验证**
|
|
194
|
-
|
|
195
|
-
- `npm test -- test/files.test.ts test/inbound.test.ts` 通过。
|
|
196
|
-
- 登录/会话启动只做存在性检查,不读取文件内容。
|
|
197
|
-
- 同名同内容不新增文件;同名不同内容生成后缀文件。
|
|
198
|
-
|
|
199
|
-
### M5b-5 — 文档与清理
|
|
200
|
-
|
|
201
|
-
**改动**
|
|
202
|
-
|
|
203
|
-
1. `README.md`:
|
|
204
|
-
- 设置表移除 `debug`,新增 `logLevel`(默认 `silent`)。
|
|
205
|
-
- 说明日志路径 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。
|
|
206
|
-
- Usage 增加语音:直接使用 QQ ASR,不保存语音文件。
|
|
207
|
-
2. `doc/features-v2.md`:按最终实现校正配置、日志路径和验收项。
|
|
208
|
-
3. 确认 `log/` 下历史调试日志不进入提交;不新增代码向 `log/` 写入。
|
|
209
|
-
4. 检查全仓库不再有 `debug` 配置引用(迁移读取除外)。
|
|
210
|
-
|
|
211
|
-
**验证**
|
|
212
|
-
|
|
213
|
-
- README 的配置示例与实际 `getSettings` 一致。
|
|
214
|
-
- `rg "debug"` 只命中迁移代码、历史文档或无关的调试函数名。
|
|
215
|
-
- `npx prettier --check .` 通过。
|
|
216
|
-
|
|
217
|
-
## 3. Todo-List
|
|
218
|
-
|
|
219
|
-
### 准备
|
|
220
|
-
|
|
221
|
-
- [x] 阅读 `doc/features-v2.md`,确认范围仅为 F8/F9/F10/F11
|
|
222
|
-
- [x] 运行基线 `npm test`、`npm run typecheck`
|
|
223
|
-
- [x] 确认不新增 npm 依赖
|
|
224
|
-
|
|
225
|
-
### F9 — 日志基础设施
|
|
226
|
-
|
|
227
|
-
- [x] `src/logger.ts`:级别、过滤、JSONL、按天单文件
|
|
228
|
-
- [x] `src/logger.ts`:`PI_QQ_LOG_DIR` 覆盖、写入失败降级
|
|
229
|
-
- [x] `src/logger.ts`:`sdkLogger` 适配器
|
|
230
|
-
- [x] `src/config.ts`:`logLevel` 默认 `silent`,旧 `debug` 迁移
|
|
231
|
-
- [x] `src/index.ts`:`configureLogger`、移除 `getDebug`
|
|
232
|
-
- [x] `src/bot.ts`:接入 `sdkLogger`,移除 `debug` 选项
|
|
233
|
-
- [x] `src/inbound.ts` / `src/outbound.ts`:日志分级
|
|
234
|
-
- [x] `src/run-feedback.ts`:移除 debug 时间戳,改用 logger
|
|
235
|
-
- [x] `test/logger.test.ts`:级别、文件名、截断、写入失败
|
|
236
|
-
- [x] `test/config.test.ts`:默认值、显式级别、旧配置迁移
|
|
237
|
-
- [x] `test/run-feedback.test.ts`:移除 debug 时间戳用例
|
|
238
|
-
- [x] 验证 silent / info / debug 三档行为
|
|
239
|
-
|
|
240
|
-
### F8 — 语音自动转写
|
|
241
|
-
|
|
242
|
-
- [x] `src/voice.ts`:`isVoiceAttachment()`、`resolveVoiceTranscript()`
|
|
243
|
-
- [x] `test/voice.test.ts`:识别、trim、空值、多值合并
|
|
244
|
-
- [x] `src/inbound.ts`:语音分支前置
|
|
245
|
-
- [x] `src/inbound.ts`:有 ASR 发送文本,无 ASR 回复提示
|
|
246
|
-
- [x] `src/inbound.ts`:语音不下载、不保存、不走图片/文件
|
|
247
|
-
- [x] `test/inbound.test.ts`:有 ASR / 空 ASR / 不保存文件
|
|
248
|
-
- [x] 确认文字、图片、文件用例不回归
|
|
249
|
-
|
|
250
|
-
### F10 — 文件等待指令
|
|
251
|
-
|
|
252
|
-
- [x] `src/inbound.ts`:pending 文件队列
|
|
253
|
-
- [x] 文件-only:保存后不回复,不启动 run
|
|
254
|
-
- [x] 下一条文字/语音:合并 pending 文件后注入
|
|
255
|
-
- [x] `/new` 清空 pending
|
|
256
|
-
- [x] `test/inbound.test.ts`:pending 队列相关用例
|
|
257
|
-
- [x] 图片、文字、文件+文字行为不回归
|
|
258
|
-
- [x] QQ 实机文件等待指令验收
|
|
259
|
-
|
|
260
|
-
### F11 — 文件存储与去重
|
|
261
|
-
|
|
262
|
-
- [x] `inbound.ts`:session uploads 路径
|
|
263
|
-
- [x] `files.ts`:`.index.json` 读写
|
|
264
|
-
- [x] 文件名不重复:保存并索引
|
|
265
|
-
- [x] 同名不同内容:生成后缀文件
|
|
266
|
-
- [x] 同名同内容:复用已有文件
|
|
267
|
-
- [x] 登录/会话启动:清理不存在文件的索引项
|
|
268
|
-
- [x] 惰性检查:复用前确认文件仍存在
|
|
269
|
-
- [x] `test/files.test.ts` / `test/inbound.test.ts`:去重与索引用例
|
|
270
|
-
- [x] `bot.ts`:await message handler,确保文件保存串行
|
|
271
|
-
- [x] `test/bot.test.ts`:handler await 回归
|
|
272
|
-
- [x] QQ 实机文件去重验收(并发文件上传重测)
|
|
273
|
-
|
|
274
|
-
### 文档与收尾
|
|
275
|
-
|
|
276
|
-
- [x] `README.md`:`logLevel`、日志路径、语音说明、文件等待指令、文件去重
|
|
277
|
-
- [x] `doc/features-v2.md`:F8/F9/F10/F11 与实现保持一致
|
|
278
|
-
- [x] 清理临时调试说明
|
|
279
|
-
- [x] `npm test`
|
|
280
|
-
- [x] `npm run typecheck`
|
|
281
|
-
- [x] `npm run format:check`
|
|
282
|
-
- [x] QQ 实机语音验收
|
|
283
|
-
|
|
284
|
-
## 4. 整体验证标准
|
|
285
|
-
|
|
286
|
-
### 自动化
|
|
287
|
-
|
|
288
|
-
- `npm test` 全部通过;新增 `logger` / `voice` / `inbound` 用例。
|
|
289
|
-
- `npm run typecheck` 无错误。
|
|
290
|
-
- `npm run format:check` 通过。
|
|
291
|
-
- 全仓库无第三方日志依赖,`package.json` 依赖不变。
|
|
292
|
-
|
|
293
|
-
### 实机验收
|
|
294
|
-
|
|
295
|
-
1. QQ 发送语音“测试”:pi 直接收到 `"测试。"`,不是 `.amr` / `.silk` 路径。
|
|
296
|
-
2. 不出现 `ffmpeg`、`pilk`、`faster-whisper` 等工具调用。
|
|
297
|
-
3. 工作区 `.pi/pi-qq/` 下不新增该语音文件。
|
|
298
|
-
4. 发送无法识别的语音或模拟空 ASR:QQ 收到提示,pi 不启动 run。
|
|
299
|
-
5. `logLevel: "silent"`:不产生日志文件。
|
|
300
|
-
6. `logLevel: "debug"`:日志文件包含 `asr_refer_text` 和完整附件;`info` 不含正文。
|
|
301
|
-
7. 旧配置 `debug: true` 仍能开启 debug 日志。
|
|
302
|
-
8. 文字、图片、文件消息行为与 v1 一致。
|
|
303
|
-
9. 只发文件:不回复,不启动 run。
|
|
304
|
-
10. 文件后发文字/语音:只启动一次 run,提示词包含文件路径和指令。
|
|
305
|
-
11. 连续上传多个文件:下一条指令合并全部文件。
|
|
306
|
-
12. `/new` 后 pending 清空。
|
|
307
|
-
13. 文件保存到 `.pi/pi-qq/<sessionId>/uploads/`。
|
|
308
|
-
14. 文件名不重复:保存并引用。
|
|
309
|
-
15. 同名不同内容:生成 `name-1.ext` 并引用。
|
|
310
|
-
16. 同名同内容:不新增文件,复用已有路径。
|
|
311
|
-
17. 删除文件后登录/会话启动清理索引,且不重算所有 hash。
|
|
312
|
-
|
|
313
|
-
## 5. 风险与预案
|
|
314
|
-
|
|
315
|
-
| 风险 | 影响 | 预案 |
|
|
316
|
-
| ------------------------------ | --------------- | -------------------------------------------------- |
|
|
317
|
-
| ASR 为空或识别不准 | 语音无法转写 | 回复提示重发或打字;V2 不做语音回退 |
|
|
318
|
-
| 平台只返回 `voice` 的假定失效 | 语音分支不触发 | 以实测字段为准;若变化再扩展识别条件 |
|
|
319
|
-
| 日志目录不可写 | 无日志 | 捕获写入异常,消息处理继续 |
|
|
320
|
-
| 默认 `silent` 导致排查时无日志 | 诊断困难 | README 明确开启 `logLevel: "info"` / `"debug"` |
|
|
321
|
-
| 移除 debug 时间戳影响现有诊断 | QQ 气泡少时间戳 | 已确认日志级别不影响聊天展示;需要时后续加独立开关 |
|
|
322
|
-
|
|
323
|
-
## 6. 执行记录
|
|
324
|
-
|
|
325
|
-
- 2026-10-30:M5a / M5b 代码与单测完成;`npm test` 97 项通过,`npm run typecheck`、`npm run format:check` 通过。
|
|
326
|
-
- 2026-10-30:QQ 实机语音验收通过。两条语音均直接使用 `asr_refer_text` 进入 pi;未保存 `.amr`,未调用本地转写工具;`logLevel: "debug"` 日志包含 ASR 元数据与全文。
|
|
327
|
-
- 2026-10-30:F10 文件等待指令实现完成;`npm test` 101 项通过,`typecheck`、`format:check` 通过。
|
|
328
|
-
- 2026-10-30:QQ 实机文件等待指令验收通过。文件-only 无回复、无 run;后续文字指令正确合并 1 个和 2 个 pending 文件并读取。
|
|
329
|
-
- 2026-10-30:F11 文件存储与去重实现完成;`npm test` 109 项通过,`typecheck`、`format:check` 通过。
|
|
330
|
-
- 2026-10-30:实机测试发现两条文件消息并发时索引互相覆盖(`c.txt` 文件存在但索引缺失)。根因是 `bot.ts` 的 message handler 未 await `onMessage`,导致 `concurrencyGuard` 提前释放锁。已修复并新增 `test/bot.test.ts`。
|
|
331
|
-
- 2026-10-30:F11 实机重测通过。`c.txt` / `b.txt` 快速连续上传后索引同时保留两项;`a.txt` / `d.txt` 不同文件名同内容按规则保留两份;索引共 4 项。
|
|
332
|
-
- 2026-10-30:修复 QQ 登录后 pi 侧本地交互被回传 QQ 的问题。`RunFeedback.isQQRunActive()` 按 run 来源判断,`message_end` 仅回传 QQ 触发的 run;`npm test` 110 项通过。
|
package/src/config.ts
DELETED
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
import { readFileSync } from "node:fs";
|
|
2
|
-
import { homedir } from "node:os";
|
|
3
|
-
import { join } from "node:path";
|
|
4
|
-
import { normalizeLogLevel, type LogLevel } from "./logger";
|
|
5
|
-
|
|
6
|
-
/**
|
|
7
|
-
* ~/.pi/agent/pi-qq.json contains non-secret settings only.
|
|
8
|
-
*
|
|
9
|
-
* QQ credentials are intentionally never written to disk: QR login keeps them in
|
|
10
|
-
* process memory, so restarting pi requires scanning a new QR code.
|
|
11
|
-
*/
|
|
12
|
-
|
|
13
|
-
/** Runtime settings (features-v1.md §4). */
|
|
14
|
-
export interface PiQQSettings {
|
|
15
|
-
/** F4: stream assistant replies */
|
|
16
|
-
streamAssistant?: boolean;
|
|
17
|
-
/** F4: bot has QQ markdown permission; pass Markdown through when true */
|
|
18
|
-
markdownSupport?: boolean;
|
|
19
|
-
/** F2: how a busy agent handles new messages */
|
|
20
|
-
deliverAs?: "steer" | "followUp";
|
|
21
|
-
/** F3: QQ image download limit (bytes) */
|
|
22
|
-
imageMaxSize?: number;
|
|
23
|
-
/** F3: QQ file download limit (bytes), default 50MB */
|
|
24
|
-
fileMaxSize?: number;
|
|
25
|
-
/** F7: heartbeat interval in minutes, 0 disables */
|
|
26
|
-
heartbeatMinutes?: number;
|
|
27
|
-
/** F7: per-run message heartbeat limit */
|
|
28
|
-
heartbeatMaxMessages?: number;
|
|
29
|
-
/** F7: stream summary frame interval (ms, minimum 300) */
|
|
30
|
-
streamFlushMs?: number;
|
|
31
|
-
/** Log threshold: silent, error, warn, info, debug (default: silent) */
|
|
32
|
-
logLevel?: LogLevel;
|
|
33
|
-
/** @deprecated Use logLevel; kept only for config migration. */
|
|
34
|
-
debug?: boolean;
|
|
35
|
-
/** F7: append-mode stream relay switch */
|
|
36
|
-
streamRelay?: boolean;
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
/** Settings file schema (legacy credential keys are ignored). */
|
|
40
|
-
export type PiQQConfig = PiQQSettings;
|
|
41
|
-
|
|
42
|
-
/** QR login result; kept in memory only. */
|
|
43
|
-
export interface Credentials {
|
|
44
|
-
appId: string;
|
|
45
|
-
appSecret: string;
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
export const CONFIG_PATH = join(homedir(), ".pi", "agent", "pi-qq.json");
|
|
49
|
-
|
|
50
|
-
/** Read settings; missing file yields empty settings, malformed JSON returns an error. */
|
|
51
|
-
export function readConfig(): { config: PiQQConfig; error?: string } {
|
|
52
|
-
let raw: string;
|
|
53
|
-
try {
|
|
54
|
-
raw = readFileSync(CONFIG_PATH, "utf8");
|
|
55
|
-
} catch {
|
|
56
|
-
return { config: {} };
|
|
57
|
-
}
|
|
58
|
-
try {
|
|
59
|
-
return { config: JSON.parse(raw) as PiQQConfig };
|
|
60
|
-
} catch (e) {
|
|
61
|
-
return { config: {}, error: `Failed to parse config file (${CONFIG_PATH}): ${(e as Error).message}` };
|
|
62
|
-
}
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
export interface ResolvedSettings extends Required<Omit<PiQQSettings, "debug">> {}
|
|
66
|
-
|
|
67
|
-
/** Settings with defaults applied (features-v1.md §4). */
|
|
68
|
-
export function getSettings(config: PiQQConfig): ResolvedSettings {
|
|
69
|
-
const logLevel = normalizeLogLevel(config.logLevel ?? (config.debug ? "debug" : undefined));
|
|
70
|
-
return {
|
|
71
|
-
streamAssistant: config.streamAssistant ?? true,
|
|
72
|
-
markdownSupport: config.markdownSupport ?? false,
|
|
73
|
-
deliverAs: config.deliverAs ?? "steer",
|
|
74
|
-
imageMaxSize: config.imageMaxSize ?? 10 * 1024 * 1024,
|
|
75
|
-
fileMaxSize: config.fileMaxSize ?? 50 * 1024 * 1024,
|
|
76
|
-
heartbeatMinutes: config.heartbeatMinutes ?? 10,
|
|
77
|
-
heartbeatMaxMessages: config.heartbeatMaxMessages ?? 3,
|
|
78
|
-
streamFlushMs: config.streamFlushMs ?? 10_000,
|
|
79
|
-
logLevel,
|
|
80
|
-
streamRelay: config.streamRelay ?? true,
|
|
81
|
-
};
|
|
82
|
-
}
|