@chen_hu_hu/pi-qq 1.2.3 → 1.3.1

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.
Files changed (35) hide show
  1. package/README-zh.md +76 -46
  2. package/README.md +79 -49
  3. package/doc/delivery-v1-zh.md +160 -0
  4. package/doc/delivery-v1.md +160 -0
  5. package/doc/delivery-v2-zh.md +100 -0
  6. package/doc/delivery-v2.md +98 -0
  7. package/doc/delivery-v3-zh.md +189 -0
  8. package/doc/delivery-v3.md +189 -0
  9. package/index.ts +66 -156
  10. package/package.json +6 -3
  11. package/src/{download.ts → attachments/attachment-download.ts} +1 -4
  12. package/src/attachments/attachment-failure.ts +12 -0
  13. package/src/{files.ts → attachments/file-attachments.ts} +19 -33
  14. package/src/{voice.ts → attachments/voice-transcript.ts} +1 -7
  15. package/src/{format.ts → infra/display-format.ts} +0 -2
  16. package/src/{logger.ts → infra/file-logger.ts} +6 -31
  17. package/src/infra/settings.ts +103 -0
  18. package/src/{bot.ts → qq/qq-bot.ts} +6 -31
  19. package/src/qq/qq-diagnostics.ts +129 -0
  20. package/src/{inbound.ts → qq/qq-message-handler.ts} +58 -94
  21. package/src/{login.ts → qq/qr-login.ts} +24 -17
  22. package/src/{outbound.ts → qq/reply-sender.ts} +7 -37
  23. package/src/qrcode-terminal.d.ts +0 -2
  24. package/src/{budget-status.ts → quota/reply-quota-report.ts} +2 -3
  25. package/src/{reply-budget.ts → quota/reply-quota.ts} +0 -21
  26. package/src/relay/run-stream-relay.ts +576 -0
  27. package/src/relay/stream-block-format.ts +117 -0
  28. package/src/{append-stream.ts → relay/stream-session.ts} +46 -29
  29. package/doc/features-v1.md +0 -239
  30. package/doc/features-v2.md +0 -210
  31. package/doc/plan-v1.md +0 -190
  32. package/doc/plan-v2.md +0 -332
  33. package/src/config.ts +0 -82
  34. package/src/images.ts +0 -149
  35. package/src/run-feedback.ts +0 -409
@@ -6,32 +6,22 @@ import type {
6
6
  StreamMessageRequest,
7
7
  } from "@tencent-connect/qqbot-nodejs/protocol";
8
8
 
9
- /**
10
- * Minimal append-mode (input_mode="append") stream sender.
11
- *
12
- * The SDK StreamSession hardcodes input_mode="replace"; in 2026-10 the platform
13
- * rejected it with "submitted message content cannot be modified". In append mode
14
- * each content_raw frame carries only the **new** text, matching the platform rule
15
- * that already-submitted content is immutable.
16
- *
17
- * Two built-in safeguards (aligned with SDK StreamSession best practices):
18
- * 1. Throttle: token increments are buffered and merged into frames per throttle
19
- * window (default 500ms, minimum 300ms) to avoid flooding the API.
20
- * 2. Rate-limit backoff: 429 / err_code 50002 retry exponentially (1s→2s→4s, max 3).
21
- */
22
-
23
9
  const MIN_INTERVAL_MS = 300;
24
10
  const RATE_LIMIT_BASE_MS = 1000;
25
11
  const MAX_RETRIES = 3;
26
12
 
13
+ export interface AppendStreamCheckpoint {
14
+ msgSeq: number;
15
+ index: number;
16
+ streamMsgId?: string;
17
+ buffer?: string;
18
+ }
19
+
27
20
  export interface AppendStreamOptions {
28
- /** Minimum interval between frames; increments are merged during the window. */
29
21
  throttleMs?: number;
30
- /** Rate-limit backoff base in ms (for tests). */
31
22
  retryBaseMs?: number;
32
- /** Background throttle flush failure (stream is no longer trusted). */
23
+ resume?: AppendStreamCheckpoint;
33
24
  onError?: (err: Error) => void;
34
- /** Diagnostic log via the shared logger: rate-limit retries/final failures. */
35
25
  onDebug?: (message: string) => void;
36
26
  }
37
27
 
@@ -51,18 +41,48 @@ export class AppendStream {
51
41
  private readonly openid: string,
52
42
  private readonly msgId: string,
53
43
  private readonly opts: AppendStreamOptions = {},
54
- ) {}
44
+ ) {
45
+ const resume = this.opts.resume;
46
+ if (resume) {
47
+ this.msgSeq = resume.msgSeq;
48
+ this.index = resume.index;
49
+ this.streamMsgId = resume.streamMsgId;
50
+ this.buffer = resume.buffer ?? "";
51
+ }
52
+ }
53
+
54
+ checkpoint(): AppendStreamCheckpoint | null {
55
+ if (this.msgSeq === null) return null;
56
+ return {
57
+ msgSeq: this.msgSeq,
58
+ index: this.index,
59
+ streamMsgId: this.streamMsgId,
60
+ ...(this.buffer ? { buffer: this.buffer } : {}),
61
+ };
62
+ }
63
+
64
+ async flush(): Promise<void> {
65
+ if (this.doneSent) return;
66
+ if (this.flushTimer) {
67
+ clearTimeout(this.flushTimer);
68
+ this.flushTimer = null;
69
+ }
70
+ while (this.flushing) {
71
+ await new Promise((r) => setTimeout(r, 20));
72
+ }
73
+ if (this.doneSent) return;
74
+ if (this.buffer) await this.doFlush("generating");
75
+ }
55
76
 
56
77
  private throttleMs(): number {
57
78
  return Math.max(this.opts.throttleMs ?? 500, MIN_INTERVAL_MS);
58
79
  }
59
80
 
60
- /** Append text; frames are merged by throttle window and sent in the background. */
61
81
  async append(delta: string): Promise<void> {
62
82
  if (this.doneSent || !delta) return;
63
83
  this.buffer += delta;
64
84
  const elapsed = Date.now() - this.lastFlushAt;
65
- if (this.flushing) return; // The in-flight flush trailing logic will pick up the buffer.
85
+ if (this.flushing) return;
66
86
  if (elapsed >= this.throttleMs()) {
67
87
  await this.doFlush("generating");
68
88
  return;
@@ -75,7 +95,6 @@ export class AppendStream {
75
95
  }
76
96
  }
77
97
 
78
- /** Flush remaining text and send DONE. Errors propagate to the caller. */
79
98
  async done(): Promise<void> {
80
99
  if (this.doneSent) return;
81
100
  if (this.flushTimer) {
@@ -85,12 +104,12 @@ export class AppendStream {
85
104
  while (this.flushing) {
86
105
  await new Promise((r) => setTimeout(r, 20));
87
106
  }
107
+ if (this.doneSent) return;
88
108
  if (this.buffer) await this.doFlush("generating");
89
- await this.doFlush("done"); // DONE frames carry empty content_raw (verified).
109
+ await this.doFlush("done");
90
110
  this.doneSent = true;
91
111
  }
92
112
 
93
- /** Stop background timers only; no DONE (for shutdown/error paths). */
94
113
  dispose(): void {
95
114
  if (this.flushTimer) {
96
115
  clearTimeout(this.flushTimer);
@@ -102,13 +121,12 @@ export class AppendStream {
102
121
  private async doFlush(state: "generating" | "done"): Promise<void> {
103
122
  if (this.flushing) return;
104
123
  const content = state === "done" ? "" : this.buffer;
105
- // DONE frames may be empty (generation finished); empty generating frames are skipped.
106
124
  if (!content && state === "generating") return;
107
125
  this.flushing = true;
108
126
  let failed = false;
109
127
  try {
110
128
  if (this.msgSeq === null) this.msgSeq = getNextMsgSeq(this.msgId);
111
- // input_mode is outside the SDK type (replace only); the platform defines its runtime meaning.
129
+ const index = this.index++;
112
130
  const req = {
113
131
  input_mode: "append",
114
132
  input_state: state === "done" ? StreamInputState.DONE : StreamInputState.GENERATING,
@@ -117,19 +135,18 @@ export class AppendStream {
117
135
  event_id: this.msgId,
118
136
  msg_id: this.msgId,
119
137
  msg_seq: this.msgSeq,
120
- index: this.index++,
138
+ index,
121
139
  ...(this.streamMsgId ? { stream_msg_id: this.streamMsgId } : {}),
122
140
  } as unknown as StreamMessageRequest;
123
141
  const resp = await this.sendWithRetry(req);
124
142
  if (resp?.id && !this.streamMsgId) this.streamMsgId = resp.id;
125
- if (state === "generating") this.buffer = "";
143
+ if (state === "generating") this.buffer = this.buffer.slice(content.length);
126
144
  this.lastFlushAt = Date.now();
127
145
  } catch (err) {
128
146
  failed = true;
129
147
  throw err;
130
148
  } finally {
131
149
  this.flushing = false;
132
- // Trailing: new data arrived during flush; schedule the next frame.
133
150
  if (!failed && state === "generating" && this.buffer && !this.doneSent && !this.flushTimer) {
134
151
  this.flushTimer = setTimeout(() => {
135
152
  this.flushTimer = null;
@@ -1,239 +0,0 @@
1
- # pi-qq — features-v1.md
2
-
3
- > pi 扩展:通过 QQ 机器人把 pi 接入 QQ 单人私聊(C2C)。
4
- > 手机 QQ 上发消息(含图片/文件)→ pi 在机器上干活 → 完整回复(Markdown → 纯文本)回传到 QQ;上下文占比可通过 `/status` 查看。
5
-
6
- 技术栈:
7
-
8
- | 依赖 | 用途 |
9
- | ------------------------------------------------- | --------------------------------------------------------------------------- |
10
- | `@tencent-connect/qqbot-nodejs` | QQ 开放平台协议层:WebSocket Gateway、C2C 消息收发、媒体上传、流式消息 |
11
- | `@tencent-connect/qqbot-connector` | 扫码登录:展示二维码,扫码后换取 `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
- **目标**:唯一登录方式是 `/qq-login` 扫码;凭据只保存在进程内存,绝不落盘。pi 进程退出后必须重新扫码。
41
-
42
- **行为**
43
-
44
- 1. 用户在 pi 中执行 `/qq-login`。
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` 立即清除内存凭据并断开连接;之后可重新扫码。
53
-
54
- **通用**
55
-
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;未登录时入站消息直接忽略。
60
-
61
- ### F2 单人聊天
62
-
63
- **目标**:只有一个绑定的用户能与机器人对话,消息进入 pi 会话。
64
-
65
- **行为**
66
-
67
- - 仅接受 `kind === "c2c"` 的入站消息;发送者 openid 必须等于本次扫码绑定的内存白名单(复用 SDK `accessPolicy`,其他用户静默忽略)。入站消息的 `senderId` 即发送者的 openid。
68
- - 普通文本 → `pi.sendUserMessage(text)`,触发正常 agent run。
69
- - 图片消息的处理见 F3(QQ → pi)。
70
- - agent 忙碌时收到新消息 → 按 `deliverAs`(默认 `steer`,可配置 `followUp`)排队。
71
- - QQ 侧控制命令(在进入 pi 前拦截):
72
- - `/new` 新会话、`/stop` 中止当前 run(`ctx.abort()`)、`/compact` 压缩上下文(`ctx.compact()`)、`/status` 会话与用量状态、`/help` 命令帮助。
73
- - agent 工作期间向 QQ 发送 typing 提示(SDK `sendTyping`,C2C only)。
74
-
75
- ### F3 发送图片与文件(QQ → pi)
76
-
77
- **目标**:用户在 QQ 上把图片或文件发给 pi;图片作为视觉输入,文件保存到本机并在提示词中给出路径。
78
-
79
- **图片行为**
80
-
81
- - 数据源:入站 C2C 消息的 `attachments`(`content_type` / `url` / `filename` / `size`)。
82
- - 扩展下载图片 → 校验类型(jpg / jpeg / png / webp / gif)与大小 → 转 `ImageContent`(base64 + mimeType)→ 与消息文本一起 `pi.sendUserMessage()`。
83
- - 类型判断:`content_type` 优先(兼容 `image/jpg`),非图片类型时按文件名扩展名兜底;明确声明为不支持的 `image/*`(如 svg)直接拒绝。
84
- - 下载约束:单张超时 15s;`imageMaxSize` 默认 10MB;先看附件元数据,再在流式读取时二次限制实际字节数。
85
- - 一条消息多张图片时按原顺序处理;部分失败时成功的图片仍注入,并回一条失败清单。
86
- - 全部失败且没有文字/文件 → 不注入 pi,只回失败提示;有文字或文件 → 仍注入并提示图片失败。
87
- - 当前模型无视觉能力(`ctx.model.input` 不含 `image`)时,QQ 提示并跳过图片;文字/文件仍处理。
88
- - 已确认:pi 不向 QQ 发送图片——LLM 只能输出纯文本,无图片生成场景。
89
-
90
- **文件行为**
91
-
92
- - 非图片附件(如 zip/pdf/doc)下载后保存到当前工作空间的 `.pi/pi-qq/YYYY-MM-DD/<msgId>/<安全文件名>`。
93
- - 文件名去掉路径与非法字符;同名文件自动加 `-1`、`-2` 后缀;不会写出保存目录。
94
- - 单文件超时 60s;`fileMaxSize` 默认 50MB;同样先看元数据,再在流式读取时二次限流。
95
- - 一条消息多个文件按原顺序保存;部分失败时成功的文件仍保留并给出失败清单。
96
- - 提示词中追加文件块,例如:
97
- ```text
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)
100
-
101
- User message:
102
- 帮我总结这个文件
103
- ```
104
- - 纯文件消息(无文字)也会触发 run,提示词只含文件块;文件内容不直接注入 LLM,由 pi 用工具按需读取。
105
- - **实测**:2026-10-29 用户已验证 QQ 发送文件后保存到工作空间 `.pi/pi-qq/`,提示词中的路径可正常关联。
106
-
107
- ### F4 回传 assistant 消息
108
-
109
- **目标**:pi 的回复实时出现在 QQ 聊天里。
110
-
111
- **行为**
112
-
113
- - 数据源:`message_end`(`message.role === "assistant"`)。回复通常为 **Markdown 格式**的总结/提问文本(已确认:LLM 编码完成后不在回复中写代码)。
114
- - 内容处理:
115
- - 始终剔除 `thinking` 块(已确认:不回传思考内容)。
116
- - **Markdown 转换**:
117
- - 默认(无 markdown 权限,`markdownSupport: false`):轻量转纯文本——去掉 `**` / `*` / `` ` `` 等强调与行内代码标记、标题转为文本行、列表项转 `•`、链接转 `文字(url)`、表格等复杂结构逐行退化;保持手机端可读性。
118
- - 机器人有 markdown 权限(`markdownSupport: true`)→ 透传原始 Markdown 由 QQ 客户端渲染。QQBot 构造时已传入 `markdownSupport`,SDK 的 `sendText` 会自动使用 msg_type=2,无需额外 `sendMarkdown`。
119
- - 超长文本按单条上限自动分块(SDK `TEXT_CHUNK_LIMIT = 5000`)。
120
- - **流式模式**(默认开启,C2C 专属):
121
- - `message_update` 期间用 `bot.openStream({ target })` 持续 `update(全文)`(对累积全文实时做同样的转换);`message_end` 时 `complete()`。
122
- - 遵守 SDK 约束:节流 ≥300ms、必须基于 5 分钟内的入站消息(`msgId`)、传全文非增量。
123
- - **非流式/降级**:`sendText` 一次性发送。
124
- - `stopReason === "error"` 时回传错误摘要而非静默。
125
-
126
- ### F5/F6 用量摘要(已移除)
127
-
128
- 每轮 QQ 对话后的 token 用量摘要已取消:
129
-
130
- - 不再在 `agent_end` 发送 `📊 用量摘要`。
131
- - 上下文占比通过 QQ 侧 `/status` 或 pi 终端 `/qq-status` 查看。
132
- - 不展示 token、缓存命中率、成本;减少一条被动回复消息。
133
- - `usageRelay` 配置项已移除(旧配置键会被忽略)。
134
-
135
- ### F7 长任务反馈(10~60 分钟级任务)
136
-
137
- **目标**:工具阶段长达数十分钟时保持"活着"的感知,且不烧穿消息额度。
138
-
139
- **行为**:**assistant 文本消息与思考/工具汇总使用独立气泡**——每条文本消息独占一个纯文本气泡(同一消息的流式增量续写),思考/工具行组进入活动气泡;文本前后的工具执行均另起活动气泡;最终回复独立成文本气泡。`streamRelay` 默认开,实测可用;气泡内按 `streamFlushMs`(默认 10000ms,最小 300)固定频率发送窗口汇总帧(工具调用每 10s 汇总一次):
140
-
141
- ```
142
- [活动气泡] [💭] Thinking...
143
- [活动气泡] [🔧] [3] bash
144
- [活动气泡] [🔧] [2] read
145
-
146
- [文本气泡] 中间消息原文
147
-
148
- [活动气泡] [🔧] [1] edit
149
-
150
- [文本气泡] 最终回复原文(流式增量)
151
- ```
152
-
153
- - **汇总帧内容**(窗口增量,间隔 `streamFlushMs` 默认 10000ms;`agent_end` 补发剩余并收 DONE)。活动气泡帧:**debug 模式下行首带 `[HH:MM:SS]` 时间戳**,普通模式不带时间戳。行组**严格按事件实际发生顺序**输出:思考状态行 `[💭] Thinking...` 与工具计数行 `[🔧] [n] name` 按到达顺序交错;连续同名工具合并为一条计数,不改变相对顺序。文本气泡帧:原始 Markdown 增量(流式帧按 markdown 渲染),debug 模式才加时间戳以免插断回答。工具总在 message_end 后执行,故文本消息与其后工具天然分入不同气泡。
154
- - **排版规则**:活动气泡内行与行相邻不空行;文本气泡内续写直接拼接;文本与工具不再混排。
155
- - **气泡边界**:文本消息的**首个增量**到达 → 封口当前活动气泡,开文本气泡;思考/工具行组到达 → 封口当前文本气泡,开或续活动气泡;同一消息的后续流式增量不切泡;最终回复独立成文本气泡。
156
- - **事件映射**:`tool_execution_start` → 窗口计数;`message_update`(thinking/text)→ 窗口状态/快照;`message_end` → 文本定稿;`agent_end` → 补帧 + DONE。AppendStream 内部仍有 500ms 节流与限流退避作安全网。
157
- - **额度提示**:每条文本消息、每段活动各占一条 msg_seq 消息;长回合任务的气泡数多于单气泡模式,需关注被动额度;若平台拒绝(帧失败),该回合自动降级消息路径,文本仍完整送达。
158
- - **降级**:任何一帧失败即标 dead,已追加部分作废,未发出的结果文本自动转消息路径补发;`streamRelay: false` 时整条时间线关闭,assistant 消息走普通消息路径(M2 行为)。
159
- - **typing 保鲜**:run 开始立即发送"正在输入",之后每 50s 续期(0 额度),`agent_end` 清理。
160
- - **空窗口活性线**:窗口无增量且静默 ≥60s 时补一条 `⏱ Running for X minutes…`——长思考/单工具长执行期间每分钟一行,不再无推送(debug 模式带时间戳)。
161
- - **心跳兜底**:流不可用时降级为普通消息心跳(每 run ≤3 条保险丝;debug 模式带时间戳)。
162
- - 不发送"已收到"开始确认(节省被动额度):QQ 触发的 run 在首个汇总帧前保持安静。
163
- - 非 QQ 触发的 run(本地终端)不发心跳/时间线,但 assistant 消息仍照常回传(现状)。
164
-
165
- ## 3. 平台限制与回传预算(关键约束)
166
-
167
- QQ 开放平台的发送限制直接决定回传策略,必须统一管理:
168
-
169
- | 限制 | 数值 | 应对 |
170
- | ------------ | ------------------------------------------ | ----------------------------------------------------------------------------------- |
171
- | 被动回复额度 | 每条入站消息 5 分钟内有效,约 4 条/小时 | 扩展内维护回复预算(复用 SDK `ReplyLimiter` 思路);assistant 时间线按文本/活动分泡 |
172
- | 主动消息 | 无 `msgId` 发送受平台额度限制 | 被动额度耗尽时才降级为主动发送,且给出明确提示 |
173
- | 流式消息 | 仅 C2C;节流 ≥300ms;基于 5 分钟内 `msgId` | 流式仅用于 assistant 文本;无关联 `msgId` 时自动降级 `sendText` |
174
- | 文本长度 | 单条 ~5000 字符 | SDK 分块;超出部分按序发送 |
175
- | markdown | 默认无权限(`markdownSupport: false`) | Markdown → 纯文本降级渲染 |
176
-
177
- **合并规则**(默认):assistant 文本消息与活动时间线严格分泡(每条文本消息 1 条纯文本气泡,工具间隔另起活动气泡);不再发送用量摘要,上下文占比通过 `/status` 查询。气泡数随回合内文本消息数增长,需关注 `msgId` 的被动额度;若平台拒绝(帧失败),自动降级消息路径。工具调用过程本身不逐条回传。
178
-
179
- ## 4. 配置
180
-
181
- `~/.pi/agent/pi-qq.json`(只保存设置;不含凭据、不写入登录信息):
182
-
183
- | 字段 | 默认 | 说明 |
184
- | ---------------------- | ------------------- | ------------------------------------------------------------------------------------ |
185
- | `streamAssistant` | `true` | assistant 流式回传开关 |
186
- | `markdownSupport` | `false` | 机器人是否有 markdown 权限;`true` 时回传透传 Markdown |
187
- | `deliverAs` | `"steer"` | 忙碌时新消息的处理方式 |
188
- | `imageMaxSize` | `10MB` | QQ 图片下载上限 |
189
- | `fileMaxSize` | `50MB` | QQ 文件下载上限 |
190
- | `heartbeatMinutes` | `10`(0 关闭) | F7 节流心跳间隔 |
191
- | `heartbeatMaxMessages` | `3` | F7 每 run 消息心跳上限(流式心跳不受限) |
192
- | `streamRelay` | `true` | F7 流式载体开关(append 追加 + 节流合帧 + 限流退避,实测可用;失败自动降级消息路径) |
193
- | `streamFlushMs` | `10000`(最小 300) | F7 流式汇总帧间隔(毫秒,默认每 10s 汇总工具调用) |
194
- | `debug` | `false` | 诊断模式:SDK 日志转终端 + 流式重试/超时日志 + 行组/文本帧时间戳 |
195
-
196
- ## 5. 命令总表
197
-
198
- | 位置 | 命令 | 行为 |
199
- | ----- | ------------------------------------------- | ---------------------------------------------------- |
200
- | pi 侧 | `/qq-login` | 扫码登录并绑定(QR only) |
201
- | pi 侧 | `/qq-status` | 登录态、连接状态、绑定用户 |
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,验证流式帧是否渲染 |
207
- | QQ 侧 | `/new` `/stop` `/compact` `/status` `/help` | 会话控制(见 F2) |
208
-
209
- ## 6. 可靠性与安全
210
-
211
- - **生命周期**:`session_start` 仅在进程内存有登录态时启动;`session_shutdown` 幂等关闭。SDK 默认无限重连(退避 1s→60s),4914/4915 致命关闭码上报为不可恢复,提示重新 `/qq-login`。
212
- - **回声与去重**:启用 SDK `messageFilter`(跳过 bot 回声)与 `concurrencyGuard`(同用户串行),避免流式与回复互相踩踏。
213
- - **安全**:
214
- - 凭据仅保存在进程内存、不落盘;日志与 `/qq-status` 脱敏;扩展以 pi 同等权限运行,白名单外的消息不进入 pi(不产生任何工具执行)。
215
- - QQ 侧无 shell 类命令;一切工具执行都经由 pi 自身权限体系。
216
-
217
- ## 7. 决策记录
218
-
219
- | # | 问题 | 决策 |
220
- | --- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
221
- | 1 | TUI 二维码渲染 | 登录协议用 connector;展示用 `qrcode-terminal`(零依赖)在 `ctx.ui` 弹窗画码 |
222
- | 2 | thinking 内容 | 不回传具体内容(始终剔除,无配置开关);F7 时间线中仅以 `[💭] Thinking...` 标记体现 |
223
- | 3 | tool 消息 | **完全不回传**;只回传 assistant 消息,上下文占比通过 `/status` 查询 |
224
- | 4 | 图片方向 | F3 为 QQ → pi(用户发图给 pi);pi 不向 QQ 发图片(LLM 仅输出纯文本) |
225
- | 5 | 成本/用量摘要 | 已移除每轮用量摘要;不展示 token、缓存命中率、成本 |
226
- | 6 | 回复格式 | 回复通常为 Markdown 格式的总结/提问文本(不在回复中写代码);默认轻量转纯文本,有 markdown 权限可透传 |
227
- | 7 | 登录方式 | 仅 `/qq-login` 扫码;凭据只存进程内存、不落盘;pi 进程退出后必须重新扫码 |
228
- | 8 | 长任务反馈 | typing 保鲜 + 每 10s 汇总工具调用 + 节流心跳(默认 10 分钟/条,流式载体优先,每 run ≤3 条消息心跳保险丝)+ 机会性流式(平台拒绝即降级);不发送开始确认 |
229
- | 9 | 流式可用性(实测三轮) | ① C2C markdown(msg_type=2,`sendMarkdown`)渲染正常;② SDK 内置流式 `input_mode="replace"` 被平台拒绝("已经提交的消息内容不可修改"),首帧可渲染、后续帧报错;③ 自实现 `AppendStream`(input_mode="append",增量追加 + DONE)实测通过;补齐节流合帧(500ms)与限流退避重试后**默认开启**,失败自动降级消息路径 |
230
-
231
- ## 8. 里程碑
232
-
233
- | 阶段 | 内容 | 验收 |
234
- | ---- | -------------------------------------------- | -------------------------------------------- |
235
- | M1 | F1 扫码登录 + 内存凭据 + 连接启动 | 扫码后 `/qq-status` 在线;重启 pi 需重新扫码 |
236
- | M2 | F2 单人聊天 + F4 assistant 回传(先非流式) | QQ 发消息得到 pi 回复 |
237
- | M4 | F3 QQ 图片/文件消息 + markdownSupport + 打磨 | 图片可进入 pi 会话;文件保存并关联到提示词 |
238
-
239
- > 原 M3 用量摘要已取消(2026-10-29)。
@@ -1,210 +0,0 @@
1
- # pi-qq — features-v2.md
2
-
3
- > V2 增量:F8 语音自动转写、F9 轻量日志基础设施、F10 文件消息等待指令、F11 文件存储与去重。
4
- > 基线见 [features-v1.md](./features-v1.md);本文只描述新增/变更内容。
5
-
6
- ## 1. 背景与结论
7
-
8
- - 当前语音附件被当作普通文件保存,pi 只能本地解码 SILK 并转写;慢且可能误识别。
9
- - 实测确认 C2C 语音消息的 `attachments[]` 包含 `asr_refer_text`(示例:`"测试。"`),`content` 为空;SDK 1.0.5 已透传该字段。
10
- - 结论:直接使用 QQ 内置 ASR;不下载语音附件,不接本地或外部 STT。
11
-
12
- ## 2. F8 语音消息自动转写
13
-
14
- ### 触发与识别
15
-
16
- - 仅 C2C、白名单用户。
17
- - `content_type === "voice"` 视为语音消息。
18
- - 读取并 trim `asr_refer_text`。
19
-
20
- ### 行为
21
-
22
- | 情况 | 处理 |
23
- | ----------- | ------------------------------------------------------------------------------------- |
24
- | 有 ASR 文本 | `markQQTrigger()` → `pi.sendUserMessage(text, { deliverAs })` |
25
- | ASR 为空 | 回复 `Could not transcribe this voice message; please resend or type it.`,不触发 run |
26
- | 语音消息 | 不下载 `url` / `voice_wav_url`,不保存文件,不走图片/文件分支 |
27
-
28
- - 语音和文字是两条独立消息,不做同条组合。
29
- - 转写文本不参与 QQ 命令解析,作为普通用户消息交给 pi。
30
- - 正常一条语音消息只有一个语音附件;多值时按顺序换行拼接,仅作防御。
31
-
32
- ### 不实现
33
-
34
- - 本地 Whisper 或外部 STT 回退
35
- - 保存原始语音
36
-
37
- ### 代码边界
38
-
39
- - 新增 `src/voice.ts`:`isVoiceAttachment()`、`resolveVoiceTranscript()`。
40
- - `src/inbound.ts`:在图片/文件分流前增加语音分支,处理完直接返回。
41
-
42
- ### 验收
43
-
44
- - 发语音后 pi 直接收到文本,不出现 `.amr` / `.silk` 路径。
45
- - 无 `ffmpeg`、`pilk`、`faster-whisper` 等调用,工作区不新增语音文件。
46
- - 空 ASR 只回提示,不启动 agent。
47
- - 文字、图片、文件行为不变。
48
-
49
- ## 3. F9 日志基础设施
50
-
51
- ### 实现
52
-
53
- - 自研轻量 logger,不引入第三方框架。
54
- - 单文件按天:`<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;可用 `PI_QQ_LOG_DIR` 覆盖。
55
- - 每条一行 JSON:`time`、`level`、`scope`、`msg` + 结构化字段。
56
- - 日志写入失败不得影响 QQ 消息处理。
57
- - SDK 日志接入同一 logger。
58
-
59
- ### 配置
60
-
61
- ```json
62
- {
63
- "logLevel": "silent"
64
- }
65
- ```
66
-
67
- | 级别 | 输出 |
68
- | -------- | ---------------------------------------------------- |
69
- | `silent` | 不写日志(默认) |
70
- | `error` | error |
71
- | `warn` | warn + error |
72
- | `info` | info + warn + error |
73
- | `debug` | 全部,含 raw 事件、附件、prompt、工具参数/结果、正文 |
74
-
75
- - 配置键使用 `logLevel`,不使用 `log_level`。
76
- - 移除 `debug` 配置;旧 `debug: true` 迁移为 `logLevel: "debug"`,其他情况默认 `silent`。
77
- - 移除 `debug` 控制的 QQ 气泡时间戳;日志级别不影响聊天展示。
78
- - `info` 只记元数据(如 `hasAsr`、`asrLength`);`debug` 才记录 `asr_refer_text` 全文和完整附件。
79
-
80
- ### 验收
81
-
82
- - 各级别过滤正确;默认 `silent` 不产生日志。
83
- - `logLevel: "debug"` 能看到语音原始附件和 ASR 文本;`info` 看不到正文。
84
- - 旧 `debug` 配置可迁移。
85
- - 日志路径、日期滚动、写入失败降级正常。
86
-
87
- ## 4. F10 文件消息等待指令
88
-
89
- ### 目标
90
-
91
- QQ 不能同时发送文字和文件。非图片文件上传后先保存,等待用户下一条文字或语音指令,避免立即触发 pi。
92
-
93
- ### 行为
94
-
95
- | 情况 | 处理 |
96
- | ------------ | ------------------------------------------------------------------------------------------------------------- |
97
- | 只发文件 | 保存到 F11 定义的 session uploads 目录;加入 pending 队列;不回复;不调用 `sendUserMessage` / `markQQTrigger` |
98
- | 连续上传文件 | 追加到同一 pending 队列;不回复 |
99
- | 下一条文字 | 合并 pending 文件与当前文件,`formatFilePrompt(files, text)` 后 `sendUserMessage`;清空 pending;触发 run |
100
- | 下一条语音 | 用 ASR 文本作为指令,合并 pending 文件;清空 pending |
101
- | `/new` | 清空 pending |
102
- | 其他 QQ 命令 | 不消费 pending,命令行为不变 |
103
- | 图片 | 保持 v1 行为;图片可以随文字发送,不进入 pending |
104
-
105
- - 部分文件保存失败:只把成功文件加入 pending,并回复失败清单。
106
- - 文件消息不回复确认,不触发 agent run。
107
- - pending 状态只保存在当前会话内存;pi 重启后丢失,已落盘文件仍保留。
108
- - pending 文件按保存顺序合并;消费后清空,不重复注入。
109
-
110
- ### 代码边界
111
-
112
- - `src/inbound.ts`:维护 pending 队列;文件消息先入队,下一条文字/语音指令出队并合并。
113
- - `/new` 命令清空 pending。
114
- - 图片路径不变。
115
-
116
- ### 验收
117
-
118
- - 只发文件:文件已保存,不回复,`sendUserMessage` / `markQQTrigger` 均未调用。
119
- - 文件后发文字:只触发一次 run,提示词包含文件路径和文字指令。
120
- - 连续两个文件后发文字:两个文件路径都在提示词中。
121
- - 文件后发语音:ASR 文本与文件一起注入。
122
- - `/new`:pending 被清空。
123
- - 文件保存失败:不进入 pending,仍回复失败信息。
124
- - 图片、普通文字、既有文件+文字行为不变。
125
-
126
- ## 5. F11 文件存储与去重
127
-
128
- ### 路径
129
-
130
- - 非图片文件保存到:
131
- ```text
132
- <cwd>/.pi/pi-qq/<sessionId>/uploads/
133
- ```
134
- - `sessionId` 来自 `ctx.sessionManager.getSessionId()`。
135
- - 不再使用日期目录或 `msgId` 子目录。
136
- - 文件名使用清理后的 basename;同名文件通过后缀区分。
137
-
138
- ### 索引
139
-
140
- 索引文件:
141
-
142
- ```text
143
- <cwd>/.pi/pi-qq/<sessionId>/uploads/.index.json
144
- ```
145
-
146
- 格式只记录文件名和内容摘要,不记录完整路径:
147
-
148
- ```json
149
- {
150
- "a.txt": "<sha256>",
151
- "a-1.txt": "<sha256>"
152
- }
153
- ```
154
-
155
- ### 保存规则
156
-
157
- | 情况 | 处理 |
158
- | -------------------- | ------------------------------------------------------------ |
159
- | 文件名不重复 | 保存文件;计算 SHA-256;写入索引;引用文件 |
160
- | 文件名重复,内容不同 | 保存为下一个可用文件名(如 `a-1.txt`);写入索引;引用新文件 |
161
- | 文件名重复,内容相同 | 不保存新文件;复用已有文件路径 |
162
-
163
- - 只有文件名重复时才比较内容摘要;文件名不重复时即使内容已存在于其他文件名下,也按规则保存新文件。
164
- - 文件名重复且内容不同时,从 `name-1.ext` 开始寻找可用文件名;如果该后缀文件已存在且内容相同,复用该后缀文件。
165
- - 文件名重复且内容相同,复用已有同名文件,不生成副本。
166
- - 图片、语音不进入该文件索引。
167
-
168
- ### 索引维护
169
-
170
- - QQ 登录 / 会话启动时加载索引:
171
- - 对每个 `fileName` 检查 `uploads/fileName` 是否存在。
172
- - 文件不存在则删除对应索引项。
173
- - 只做存在性检查,不读取文件内容,不重新计算 hash。
174
- - 索引有变化才原子写回。
175
- - 保存或复用文件前再次检查目标文件是否存在;不存在则删除索引项并按新文件处理。
176
- - 索引缺失或损坏时从空索引开始;遇到同名文件时再计算已有文件 hash 并补写索引。
177
- - 文件保存与索引更新按用户消息串行执行;当前消息处理完成前不处理下一条,避免并发覆盖索引。
178
- - 索引写入失败只记 warn,不影响文件保存和消息处理。
179
- - 不新增配置参数。
180
-
181
- ### 与 pending 的关系
182
-
183
- - 同名同内容重复上传:只返回一个 `SavedFile`,pending 不重复加入。
184
- - 不同文件名但内容相同:按规则保存两份,pending 保留两个路径。
185
-
186
- ### 验收
187
-
188
- - 文件保存到 `.pi/pi-qq/<sessionId>/uploads/`,不再出现日期 / `msgId` 目录。
189
- - 索引文件只包含文件名到 SHA-256 的映射。
190
- - 文件名不重复:保存并引用。
191
- - 同名不同内容:保存为 `name-1.ext` 并引用新文件。
192
- - 同名同内容:不新增文件,复用已有路径。
193
- - 登录 / 会话启动:删除指向不存在文件的索引项,且不重新计算所有文件 hash。
194
- - 索引缺失或损坏:同名文件仍能通过现有文件 hash 正确判断。
195
- - 索引写入失败不影响文件保存和消息处理。
196
-
197
- ## 6. 配置变更
198
-
199
- | 配置 | 变更 |
200
- | ---------- | -------------------- |
201
- | `logLevel` | 新增;默认 `silent` |
202
- | `debug` | 移除;仅保留迁移读取 |
203
-
204
- ## 7. 限制
205
-
206
- - `asr_refer_text` 可能为空或识别不准确;V2 只提示用户重发或改用文字,不做回退。
207
- - `debug` 日志可能包含消息正文和 URL token,仅在排查时本地开启。
208
- - 文件 pending 不跨 pi 重启;未消费的文件仍保留在 `.pi/pi-qq/<sessionId>/uploads/` 下。
209
- - 索引信任写入时的 hash;如果用户手动修改同名文件内容,登录时的存在性检查不会发现。
210
- - 回传按 run 来源判断:只有 QQ 入站消息触发的 run 回传 QQ;pi 侧直接发起的 run 不推送。