@chen_hu_hu/pi-qq 1.4.0 → 1.4.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.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.4.1] - 2026-11-04
11
+
12
+ ### Changed
13
+
14
+ - Removed the archived Chinese delivery records from `doc/archive/` and dropped `doc/archive/README.md`.
15
+ - Removed code comments from the TypeScript sources, tests, configuration, and release workflow.
16
+
10
17
  ## [1.4.0] - 2026-11-04
11
18
 
12
19
  ### Added
@@ -96,7 +103,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
96
103
  - Added thinking labels, per-tool icons, model-error recovery, and idle-safe session handling.
97
104
  - Reorganized modules by bounded context and updated settings and delivery documentation.
98
105
 
99
- [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.0...HEAD
106
+ [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.1...HEAD
107
+ [1.4.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.4.0...v1.4.1
100
108
  [1.4.0]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.6...v1.4.0
101
109
  [1.3.6]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.5...v1.3.6
102
110
  [1.3.5]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.4...v1.3.5
package/doc/todo.md CHANGED
@@ -83,7 +83,7 @@
83
83
  > 状态:TODO,等待长期使用日志
84
84
  > 记录日期:2026-11-04
85
85
  > 相关版本:pi-qq 1.4.0
86
- > 详细调研:`doc/archive/delivery-v4-zh.md`
86
+ > 详细调研:`doc/archive/delivery-v4.md`
87
87
 
88
88
  ### 现象
89
89
 
@@ -177,7 +177,7 @@ QQ 侧的 `/last` 已可用于手动恢复:
177
177
 
178
178
  ### 下一步
179
179
 
180
- - 如果日志确认 `msg_id` 过期/被动次数超限:按 `doc/archive/delivery-v4-zh.md` 的“长耗时工具”建议实现错误分类和预算修复。
180
+ - 如果日志确认 `msg_id` 过期/被动次数超限:按 `doc/archive/delivery-v4.md` 的“Long-running tools”建议实现错误分类和预算修复。
181
181
  - 如果日志显示流一直存活但没有新帧:优先实现长工具心跳和 `tool_execution_update` 转发。
182
182
  - 如果事件循环 `driftMs` / `p99Ms` 很高:排查 e2e CPU、TUI 渲染和同步工具代码。
183
183
  - 如果 `/stop` 的 `wait done` 缺失或 `waitedMs` 很大:实现非阻塞 `/stop`。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chen_hu_hu/pi-qq",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "Connect pi to QQ private chats.",
5
5
  "license": "MIT",
6
6
  "author": "CQ-Developer",
@@ -44,8 +44,7 @@ export function uploadIndexPath(uploadDir: string): string {
44
44
  export function sanitizeFilename(filename: string | undefined, fallback: string): string {
45
45
  const raw = basename((filename ?? "").trim());
46
46
  const cleaned = raw
47
- // eslint-disable-next-line no-control-regex
48
- .replace(/[\u0000-\u001f\u007f<>:"|?*]/g, "_")
47
+ .replace(/[\p{Cc}<>:"|?*]/gu, "_")
49
48
  .replace(/^[.\s]+|[.\s]+$/g, "")
50
49
  .trim();
51
50
  if (!cleaned || cleaned === "." || cleaned === "..") return fallback;
@@ -35,7 +35,6 @@ export function isLogEnabled(level: Exclude<LogLevel, "silent">): boolean {
35
35
  return isLevelEnabled(activeLevel, level);
36
36
  }
37
37
 
38
- /** Resolve once every queued log record has been written (or dropped). */
39
38
  export async function flushLogs(): Promise<void> {
40
39
  await writeQueue;
41
40
  }
@@ -68,9 +68,7 @@ export function readLinuxBattery(root = "/sys/class/power_supply"): PowerStatus
68
68
  const rawStatus = readFileSync(join(dir, "status"), "utf8").trim().toLowerCase();
69
69
  const state = rawStatus === "charging" ? "charging" : rawStatus === "discharging" ? "discharging" : "ac";
70
70
  return { percent, state };
71
- } catch {
72
- // Try the next battery.
73
- }
71
+ } catch {}
74
72
  }
75
73
  return undefined;
76
74
  }
@@ -37,10 +37,6 @@ function isPositiveSize(value: unknown): value is number {
37
37
  return typeof value === "number" && Number.isFinite(value) && value > 0;
38
38
  }
39
39
 
40
- /**
41
- * Validate the on-disk shape before it reaches business code. Invalid fields
42
- * are dropped individually so one typo does not discard the whole config.
43
- */
44
40
  export function parseConfig(raw: unknown): ReadConfigResult {
45
41
  if (!isRecord(raw)) {
46
42
  return {
@@ -22,10 +22,6 @@ export type ResolvedInbound =
22
22
  voiceCount: number;
23
23
  };
24
24
 
25
- /**
26
- * Turn one inbound message into injectable content: prefer ASR for voice,
27
- * persist every non-voice attachment, and report per-file failures.
28
- */
29
25
  export async function resolveInboundContent(
30
26
  msg: QQBotInboundMessage,
31
27
  options: ResolveInboundOptions,
@@ -56,7 +52,6 @@ export async function resolveInboundContent(
56
52
  }
57
53
  }
58
54
 
59
- // Voice attachments are handled above; all other attachments are stored as files.
60
55
  const attachmentsToSave = attachments.filter((attachment) => !isVoiceAttachment(attachment));
61
56
  const failures: AttachmentFailure[] = [];
62
57
  let files: SavedFile[] = [];
@@ -78,7 +73,6 @@ export async function resolveInboundContent(
78
73
  return { status: "resolved", text, files, failures, voiceCount: voiceAttachments.length };
79
74
  }
80
75
 
81
- /** Attachments that arrived without an instruction, consumed by the next text or voice message. */
82
76
  export class PendingAttachments {
83
77
  private files: SavedFile[] = [];
84
78
 
@@ -2,7 +2,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
2
  import { log } from "../infra/file-logger";
3
3
  import { t } from "../infra/i18n";
4
4
 
5
- /** The slice of ExtensionContext used by QQ inbound handling. */
6
5
  export interface InboundContext {
7
6
  readonly cwd: string;
8
7
  isIdle(): boolean;
@@ -12,10 +12,6 @@ export interface QQDiagnosticsDeps {
12
12
  getBoundOpenid: () => string | undefined;
13
13
  }
14
14
 
15
- /**
16
- * Terminal-only protocol probes. Kept out of the entrypoint so index.ts stays
17
- * a composition root and does not construct stream frames directly.
18
- */
19
15
  export function registerQQDiagnostics(pi: ExtensionAPI, deps: QQDiagnosticsDeps): void {
20
16
  const diagTarget = () => {
21
17
  const last = deps.budget.lastTarget;
@@ -87,8 +87,6 @@ export async function runQrLogin(ctx: ExtensionContext): Promise<QrLoginResult |
87
87
  },
88
88
  handleInput(data: string): void {
89
89
  if (keybindings.matches(data, "tui.select.cancel") || data === "\x1b") {
90
- // Mark the login settled before aborting: the connector reports an
91
- // AbortError through onFailure, which must not look like a failure.
92
90
  finish();
93
91
  ac.abort();
94
92
  done();
@@ -87,7 +87,6 @@ export interface StreamTarget {
87
87
  msgId: string;
88
88
  }
89
89
 
90
- /** Send a complete message as one new stream bubble. */
91
90
  export async function sendStreamReply(
92
91
  bot: QQBot,
93
92
  text: string,
@@ -25,11 +25,6 @@ export interface BubbleWriterDeps {
25
25
  onWarn: (msg: string) => void;
26
26
  }
27
27
 
28
- /**
29
- * Owns one run's QQ stream: block layout, bubble rotation, fence tracking, and
30
- * stream recovery. Operations are serialized so callers can enqueue in event
31
- * order without waiting for network round-trips.
32
- */
33
28
  export class BubbleWriter {
34
29
  private cur: AppendStream | null = null;
35
30
  private pendingResume?: AppendStreamCheckpoint;
@@ -59,7 +54,6 @@ export class BubbleWriter {
59
54
  return this.streamDead;
60
55
  }
61
56
 
62
- /** Snapshot used by debug logs to explain stalls without changing relay behavior. */
63
57
  stats(now = Date.now()): {
64
58
  dead: boolean;
65
59
  disposed: boolean;
@@ -86,7 +80,6 @@ export class BubbleWriter {
86
80
  };
87
81
  }
88
82
 
89
- /** Mark the current block as complete so the next content starts a new bubble. */
90
83
  closeBlock(): void {
91
84
  this.blockClosed = true;
92
85
  }
@@ -146,7 +139,6 @@ export class BubbleWriter {
146
139
  this.push(`${prefix}${formatToolResult(result, isError, language)}`, prefix.length > 0, true);
147
140
  }
148
141
 
149
- /** Run `op` after all currently queued appends, unless the stream died first. */
150
142
  schedule(op: () => void): void {
151
143
  void this.enqueue(async () => {
152
144
  if (this.streamDead || this.disposed) return;
@@ -154,10 +146,6 @@ export class BubbleWriter {
154
146
  });
155
147
  }
156
148
 
157
- /**
158
- * Start a fresh bubble and push the current text again, reviving a stream
159
- * that died while the phone was offline. Later deltas continue in this bubble.
160
- */
161
149
  restartText(text: string, target?: { openid: string; msgId: string }): void {
162
150
  if (!text || this.disposed) return;
163
151
  void this.enqueue(async () => {
@@ -27,7 +27,6 @@ interface RunState {
27
27
  msgId?: string;
28
28
  thinkingSentLen: number;
29
29
  finalizedText: string;
30
- /** Latest text of the current run, kept for the QQ /last command. */
31
30
  currentText: string;
32
31
  resultSentLen: number;
33
32
  tools: ToolCall[];
@@ -43,11 +42,6 @@ const TYPING_INTERVAL_MS = 50_000;
43
42
  const PENDING_TTL_MS = 15_000;
44
43
  const RECOVERY_TTL_MS = 60_000;
45
44
 
46
- /**
47
- * Coordinates a QQ-triggered agent run: target selection, tool ordering,
48
- * deferred content, typing indicators, and run lifetime. Bubble layout and
49
- * stream I/O are delegated to BubbleWriter.
50
- */
51
45
  export class RunFeedback {
52
46
  private readonly deps: RunFeedbackDeps;
53
47
  private pending: { openid: string; msgId: string; at: number } | null = null;
@@ -78,18 +72,10 @@ export class RunFeedback {
78
72
  return this.run ? this.endPromise : Promise.resolve();
79
73
  }
80
74
 
81
- /**
82
- * The final assistant text of the most recently completed QQ run.
83
- * No transcript is retained.
84
- */
85
75
  getLastMessage(): string | undefined {
86
76
  return this.lastCompletedText;
87
77
  }
88
78
 
89
- /**
90
- * Restart the current run's push with its latest text. This revives a stream
91
- * that may have died while the phone was offline; later deltas continue.
92
- */
93
79
  repushCurrent(openid: string, msgId: string): boolean {
94
80
  const run = this.run;
95
81
  const text = run?.currentText;
@@ -108,12 +94,8 @@ export class RunFeedback {
108
94
  textLength: text.length,
109
95
  ...this.diagnostics(run),
110
96
  });
111
- // Rebind to the /last message so the new stream has a fresh passive window.
112
97
  run.openid = openid;
113
98
  run.msgId = msgId;
114
- // Push the current text in full. Do not rewrite resultSentLen: it belongs to
115
- // the assistant message currently being diffed, and changing it could drop
116
- // the beginning of the next message.
117
99
  run.writer.restartText(text, { openid, msgId });
118
100
  return true;
119
101
  }
@@ -465,7 +447,6 @@ export class RunFeedback {
465
447
  run.typingTimer = undefined;
466
448
  }
467
449
 
468
- /** Structured snapshot for debug logs; must not be called on hot paths. */
469
450
  private diagnostics(run: RunState): Record<string, unknown> {
470
451
  if (!isLogEnabled("debug")) return {};
471
452
  return {
@@ -86,10 +86,6 @@ export interface SkillRead {
86
86
  name: string;
87
87
  }
88
88
 
89
- /**
90
- * Detect a read of a SKILL.md file. pi renders this as "[skill]" in the TUI;
91
- * QQ should show a dedicated skill block instead of a generic read tool.
92
- */
93
89
  export function detectSkillRead(toolName: string, args: unknown): SkillRead | undefined {
94
90
  if (toolName !== "read" || !args || typeof args !== "object") return undefined;
95
91
  const record = args as Record<string, unknown>;
@@ -1,32 +0,0 @@
1
- # Archived delivery records
2
-
3
- These documents record how pi-qq was delivered at each milestone. They are
4
- historical snapshots, not current documentation.
5
-
6
- - They may reference modules, settings, or behaviors that have since been
7
- removed (for example the image-specific pipeline and `imageMaxSize`).
8
- - Do not update them to match current behavior; write current documentation in
9
- `README.md`, `README-zh.md`, and `CHANGELOG.md` instead.
10
- - File and line details in these records are intentionally frozen.
11
-
12
- ## Records
13
-
14
- - v4: [English](./delivery-v4.md) · [中文](./delivery-v4-zh.md)
15
- - v3: [English](./delivery-v3.md) · [中文](./delivery-v3-zh.md)
16
- - v2: [English](./delivery-v2.md) · [中文](./delivery-v2-zh.md)
17
- - v1: [English](./delivery-v1.md) · [中文](./delivery-v1-zh.md)
18
-
19
- # 归档交付记录
20
-
21
- 本目录保存 pi-qq 各里程碑的交付记录,仅作历史快照,不是当前文档。
22
-
23
- - 文中可能引用已删除的模块、配置或行为(例如图片专用链路和 `imageMaxSize`)。
24
- - 不要把这些文档更新为当前行为;现行说明请写入 `README.md`、`README-zh.md` 和 `CHANGELOG.md`。
25
- - 文件与行号等细节按当时状态保留。
26
-
27
- ## 记录
28
-
29
- - v4:[English](./delivery-v4.md) · [中文](./delivery-v4-zh.md)
30
- - v3:[English](./delivery-v3.md) · [中文](./delivery-v3-zh.md)
31
- - v2:[English](./delivery-v2.md) · [中文](./delivery-v2-zh.md)
32
- - v1:[English](./delivery-v1.md) · [中文](./delivery-v1-zh.md)
@@ -1,161 +0,0 @@
1
- # pi-qq delivery-v1
2
-
3
- > **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
4
- > 状态:v1 已交付,作为后续版本的历史基线。
5
- > 后续版本见 [delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
6
-
7
- ## 1. 交付范围
8
-
9
- v1 将 pi 接入 QQ 单人私聊(C2C):
10
-
11
- - 手机 QQ 发送文字、图片、文件;
12
- - pi 在用户电脑上执行任务;
13
- - assistant 文本回传到 QQ;
14
- - 登录、命令、回复预算和连接生命周期可管理。
15
-
16
- 技术栈:
17
-
18
- | 依赖 | 用途 |
19
- | ---------------------------------- | ------------------------------------------------ |
20
- | `@tencent-connect/qqbot-nodejs` | QQ 协议层:Gateway、C2C 消息、媒体上传、流式消息 |
21
- | `@tencent-connect/qqbot-connector` | 扫码登录,凭据只保存在进程内存 |
22
- | `@earendil-works/pi-coding-agent` | pi 扩展宿主、事件订阅、消息注入、上下文信息 |
23
-
24
- ## 2. 架构
25
-
26
- 扩展以目录形式加载,在 pi 进程内持有 QQBot:
27
-
28
- ```text
29
- 手机 QQ(C2C)
30
- │ WebSocket Gateway
31
- ▼
32
- QQBot
33
- │ message
34
- ▼
35
- pi-qq:白名单 → QQ 命令 → 文本/图片/文件
36
- │ pi.sendUserMessage()
37
- ▼
38
- pi 会话
39
- │ message_update / message_end / agent_end
40
- ▼
41
- pi-qq:格式化 → QQ 文本/流式消息
42
- ```
43
-
44
- - QQ → pi:白名单校验后注入文本和图片;文件保存在工作区。
45
- - pi → QQ:订阅 assistant 消息并回传;长任务使用独立的反馈时间线。
46
- - 生命周期:`session_start` 启动 bot,`session_shutdown` 幂等停止。
47
- - 断线重连由 SDK 负责;致命关闭码 4914/4915 给出明确错误。
48
-
49
- ## 3. 功能
50
-
51
- ### F1 扫码登录
52
-
53
- - 只支持 `/qq-login` 扫码登录。
54
- - 凭据只保存在进程内存,不写入配置文件;重启 pi 后重新扫码。
55
- - 成功后绑定扫码用户 openid,其他 C2C 用户静默忽略。
56
- - `/qq-logout` 清除凭据并断开连接。
57
- - `/qq-status` 显示登录、连接、模型、上下文和绑定用户;AppID 脱敏。
58
-
59
- ### F2 单人聊天
60
-
61
- - 只接受白名单用户的 C2C 消息。
62
- - 文本通过 `pi.sendUserMessage()` 注入 pi。
63
- - 忙碌时按 `deliverAs`(`steer` 或 `followUp`)排队。
64
- - QQ 侧命令:`/new`、`/stop`、`/compact`、`/status`、`/help`。
65
- - 运行期间发送 typing 指示。
66
-
67
- ### F3 图片和文件
68
-
69
- 图片:
70
-
71
- - 下载后校验类型和大小,转换为 pi 的 `ImageContent`。
72
- - 支持 jpg/jpeg/png/webp/gif;不支持的 `image/*` 明确拒绝。
73
- - 单张超时 15 秒,默认上限 10MB。
74
- - 部分图片失败时,成功图片仍注入,并回传失败清单。
75
- - 当前模型不支持视觉输入时提示并跳过图片。
76
-
77
- 文件:
78
-
79
- - 保存到 `.pi/pi-qq/YYYY-MM-DD/<msgId>/`;v2+ 使用按会话隔离的 `.pi/pi-qq/<sessionId>/uploads/`。提示词附带绝对路径、大小和原始文件名。
80
- - 单文件超时 60 秒,默认上限 50MB。
81
- - 文件名安全化;同名文件自动追加 `-1`、`-2`。
82
- - 文件内容不直接注入模型,由工具按需读取。
83
-
84
- ### F4 assistant 回传
85
-
86
- - 数据源是 assistant 的 `message_end`。
87
- - Markdown 转纯文本:去强调/标题/行内代码标记,列表转 `•`,链接转文字和 URL。
88
- - 长文本按 `TEXT_CHUNK_LIMIT` 分块发送。
89
- - 支持 C2C 流式追加;平台失败时降级为普通消息路径。
90
- - `stopReason === "error"` 时回传错误摘要。
91
-
92
- ### F5/F6 用量摘要
93
-
94
- 已取消。不再发送 token、缓存、成本和上下文明细;上下文通过 `/status` / `/qq-status` 查看。
95
-
96
- ### F7 长任务反馈
97
-
98
- v1 曾使用窗口汇总、工具计数和消息心跳维持长任务活性。该实现已在 v3 被 F12/F13 取代;v1 历史行为不代表当前版本。
99
-
100
- ## 4. 平台限制与预算
101
-
102
- | 限制 | 应对 |
103
- | ------------------------------------- | ------------------------------------------------- |
104
- | 被动回复约 4 条 / 小时(SDK limiter) | `ReplyBudget` 记录 `msgId` 配额,超限降级主动发送 |
105
- | 流式消息仅 C2C,节流 ≥300ms | `AppendStream` 负责合帧和退避 |
106
- | 单条文本约 5000 字符 | 自动分块 |
107
- | 流式消息依赖 5 分钟内的 `msgId` | 过期后降级为普通消息 |
108
-
109
- ## 5. 配置与命令
110
-
111
- `~/.pi/agent/pi-qq.json` 只保存设置,不保存凭据。
112
-
113
- | 配置 | 默认 | 说明 |
114
- | --------------- | ---------- | ---------------------------------------- |
115
- | `thinkingRelay` | `true` | 回传思考正文 |
116
- | `deliverAs` | `"steer"` | 忙碌时新消息的排队方式 |
117
- | `imageMaxSize` | 10MB | 图片下载上限 |
118
- | `fileMaxSize` | 50MB | 文件下载上限 |
119
- | `logLevel` | `"silent"` | 日志阈值 |
120
- | `debug` | 仅迁移读取 | `debug: true` 映射为 `logLevel: "debug"` |
121
-
122
- pi 侧命令:`/qq-login`、`/qq-status`、`/qq-logout`、`/qq-test-budget`、`/qq-test-md`、`/qq-test-stream`、`/qq-new`。
123
-
124
- QQ 侧命令:`/new`、`/stop`、`/compact`、`/status`、`/help`。
125
-
126
- ## 6. 模块与边界(v1 基线)
127
-
128
- <!-- prettier-ignore -->
129
- | 模块 | 职责 |
130
- | ---------------------------- | ------------------------------------ |
131
- | `index.ts` | 扩展装配、事件订阅、命令注册 |
132
- | `src/infra/settings.ts` | 只读配置与迁移 |
133
- | `src/qq/qr-login.ts` | 扫码登录 |
134
- | `src/qq/qq-bot.ts` | QQBot 生命周期、Gateway 状态、中间件 |
135
- | `src/qq/qq-message-handler.ts` | 入站路由、命令、附件处理、注入 pi |
136
- | `src/attachments/image-attachments.ts` | 图片校验与 `ImageContent` |
137
- | `src/attachments/file-attachments.ts` | 文件保存、索引、提示词关联 |
138
- | `src/attachments/attachment-download.ts` | 图片/文件通用限流下载 |
139
- | `src/qq/reply-sender.ts` | Markdown 转换、分块、发送 |
140
- | `src/quota/reply-quota.ts` | 被动回复预算 |
141
- | `src/quota/reply-quota-report.ts` | 预算诊断格式化 |
142
- | `src/infra/display-format.ts` | 字节与 token 格式化 |
143
- | `src/infra/file-logger.ts` | 文件日志 |
144
- | `src/relay/run-stream-relay.ts` | 长任务反馈状态机 |
145
- | `src/relay/stream-session.ts` | 流式追加、重试、续写检查点 |
146
-
147
- 边界原则:入口只做装配;协议、存储、格式化、预算分别放在独立模块;模块通过显式参数和 `RunFeedbackDeps` 之类的接口通信。
148
-
149
- ## 7. 验证
150
-
151
- - 扫码登录、`/qq-status`、`/qq-logout` 实测通过。
152
- - QQ 文本触发 pi,回复回传 QQ。
153
- - 图片作为视觉输入、文件保存和提示词路径关联实测通过。
154
- - 被动回复预算实测不超限;异常路径可降级主动发送。
155
-
156
- ## 8. 已知限制
157
-
158
- - 仅支持 C2C 私聊。
159
- - 登录凭据在进程内存,重启后必须重新扫码。
160
- - 不提供开始确认和用量摘要,减少被动消息。
161
- - 历史流式/心跳实现已由 v3 取代,不应作为当前行为参考。
@@ -1,101 +0,0 @@
1
- # pi-qq delivery-v2
2
-
3
- > **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
4
- > 状态:v2 已交付,本文为历史记录。
5
- > 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md);后续版本:[delivery-v3-zh.md](./delivery-v3-zh.md)。
6
-
7
- ## 1. 交付范围
8
-
9
- v2 在 v1 的 QQ 私聊、图片和文件能力上增加:
10
-
11
- - F8 语音消息自动转写;
12
- - F9 结构化日志基础设施;
13
- - F10 文件消息等待下一条指令;
14
- - F11 文件保存路径、索引和去重。
15
-
16
- ## 2. 功能
17
-
18
- ### F8 语音消息
19
-
20
- - 使用 QQ 内置 ASR(`asr_refer_text`),不下载音频。
21
- - 转写文本作为普通用户文本交给 pi。
22
- - ASR 无结果时回复 `Could not transcribe this voice message; please resend or type it.`,不启动 run。
23
- - 不依赖本地或外部语音识别服务。
24
- - 原始 ASR 结果和附件元数据只在 `debug` 日志中记录。
25
-
26
- ### F9 日志
27
-
28
- - 按天写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。
29
- - `PI_QQ_LOG_DIR` 可覆盖目录。
30
- - 阈值:`silent`、`error`、`warn`、`info`、`debug`。
31
- - `info` 只记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。
32
- - 日志 JSONL 化,错误对象带名称、消息和堆栈。
33
- - 旧配置 `debug: true` 映射为 `logLevel: "debug"`。
34
-
35
- ### F10 文件等待指令
36
-
37
- - 只发送文件不会启动 pi;文件先保存并进入 pending。
38
- - 下一条文字或语音指令会消费 pending 文件,并在提示词中附带路径、大小和原始文件名。
39
- - 指令前上传多个文件会合并到同一个提示词。
40
- - `/new` 清空 pending。
41
- - 文件按当前 pi 会话隔离。
42
-
43
- ### F11 文件存储与去重
44
-
45
- - 保存在当前工作区 `.pi/pi-qq/<sessionId>/uploads/`。
46
- - 同名同内容复用已有文件。
47
- - 同名不同内容保存为 `name-1.ext`。
48
- - 不同名同内容分别保存。
49
- - 索引只记录文件名到哈希的映射;路径和大小来自文件系统。启动时清理失效索引。
50
- - pending 文件与索引解耦,`/new` 不影响已保存的索引文件。
51
-
52
- ## 3. 配置
53
-
54
- v2 继续使用:
55
-
56
- | 配置 | 默认 | 说明 |
57
- | --------------- | ---------- | -------------------- |
58
- | `thinkingRelay` | `true` | 思考正文回传开关 |
59
- | `deliverAs` | `"steer"` | 忙碌时的消息排队方式 |
60
- | `imageMaxSize` | 10MB | 图片下载上限 |
61
- | `fileMaxSize` | 50MB | 文件下载上限 |
62
- | `logLevel` | `"silent"` | 日志阈值 |
63
- | `debug` | 仅迁移读取 | 旧日志开关迁移 |
64
-
65
- ## 4. 模块与边界
66
-
67
- <!-- prettier-ignore -->
68
- | 模块 | 职责 |
69
- | ---------------------------- | ------------------------------------ |
70
- | `src/qq/qq-message-handler.ts` | 语音/文件/文本统一入站路由;命令拦截 |
71
- | `src/attachments/voice-transcript.ts` | ASR 文本提取与可用性判断 |
72
- | `src/attachments/file-attachments.ts` | 文件保存、哈希、索引、pending 提示词 |
73
- | `src/attachments/attachment-download.ts` | 图片和文件共用下载约束 |
74
- | `src/attachments/image-attachments.ts` | 图片校验与视觉输入组装 |
75
- | `src/infra/file-logger.ts` | 日志级别、格式化、按天写入 |
76
- | `src/qq/reply-sender.ts` | Markdown 转换、分块、发送 |
77
- | `src/quota/reply-quota.ts` | 被动回复预算 |
78
-
79
- 边界原则:
80
-
81
- - `qq-message-handler` 只负责路由,不自行实现下载或存储细节;
82
- - `voice-transcript` 不接触文件系统;
83
- - `file-attachments` 负责保存和索引,不负责 pi 事件;
84
- - `file-logger` 不依赖业务模块;
85
- - 所有附件下载都经过 `attachment-download.ts`,避免超时和大小限制分叉。
86
-
87
- ## 5. 验证
88
-
89
- - 语音 ASR 文本注入、无文本提示、音频不落盘;
90
- - 纯文件消息不启动 run,下一条指令消费文件;
91
- - 多文件合并、`/new` 清空 pending;
92
- - 同名同内容复用、同名不同内容加后缀、不同名同内容独立保存;
93
- - 日志目录、级别、JSONL 字段和旧 `debug` 迁移;
94
- - 自动化和实机测试通过。
95
-
96
- ## 6. 已知限制
97
-
98
- - 仅使用 QQ ASR,不提供本地识别兜底。
99
- - ASR 不返回文本时只能重发或改文字。
100
- - 文件等待指令按当前 pi 会话隔离。
101
- - 日志的 `debug` 级别会包含敏感工具参数和文件内容,只在排查问题时开启。
@@ -1,190 +0,0 @@
1
- # pi-qq delivery-v3
2
-
3
- > **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
4
- > 状态:v3 已实现并完成主链路真机验证;按块切泡、错误恢复、列表切分等最终细节仍需在目标 QQ 客户端做一次完整复验。
5
- > 说明:后续变更删除了图片专用链路,图片与文件共用保存/pending 流程。
6
- > 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md)、[delivery-v2-zh.md](./delivery-v2-zh.md)。
7
-
8
- ## 1. 交付范围
9
-
10
- v3 收敛长任务回传与配置:
11
-
12
- - F12:事件直推,思考、工具、文本按块回传;
13
- - F13:移除消息心跳;
14
- - F14:配置项收敛。
15
-
16
- ## 2. 输出模型
17
-
18
- ### 2.1 每个内容块一个气泡
19
-
20
- 按时间顺序:
21
-
22
- 1. 思考块;
23
- 2. 每个工具调用 + 结果;
24
- 3. 文本块;
25
- 4. 最终消息。
26
-
27
- 工具未完成时,后续思考/文本暂存,避免思考插入两个工具泡之间。并行工具按开始顺序逐个展示,结果通过 `toolCallId` 归属。
28
-
29
- ### 2.2 思考格式
30
-
31
- 每个思考泡首行:
32
-
33
- ```text
34
- **💭 思考**
35
- ```
36
-
37
- 正文为纯文本,不加 `>` 引用前缀,空行和换行原样保留。达到 12k 安全边界时主动切泡,新泡重复标题。
38
-
39
- 不使用引用块的原因:QQ 会把单行/空行引用块渲染为不支持的消息;纯文本 + 标题可稳定显示。
40
-
41
- ### 2.3 工具格式
42
-
43
- ````text
44
- **<图标> <工具名>**
45
-
46
- `参数`
47
-
48
- ```text
49
- 输出
50
- ````
51
-
52
- ````
53
-
54
- 失败结果首行:
55
-
56
- ```text
57
- ❌ ...
58
- ````
59
-
60
- 每个工具调用独立气泡;工具名、参数和结果不拆开。
61
-
62
- 固定图标映射:
63
-
64
- | 工具 | 图标 | 工具 | 图标 |
65
- | -------- | ---- | ---------- | ---- |
66
- | `bash` | 💻 | `read` | 📖 |
67
- | `write` | 📝 | `edit` | ✏️ |
68
- | `grep` | 🔎 | `search` | 🔍 |
69
- | `find` | 🗂️ | `ls` | 📁 |
70
- | `list` | 📋 | `web` | 🌐 |
71
- | `fetch` | 📡 | `delete` | 🗑️ |
72
- | `remove` | ❌ | `todo` | ✅ |
73
- | `test` | 🧪 | 未配置工具 | 🔧 |
74
-
75
- 图标硬编码在 `src/relay/stream-block-format.ts`,不增加配置项。
76
-
77
- ### 2.4 文本与普通消息
78
-
79
- assistant 文本按原文流式追加,不额外加标题。文本块和工具块之间通过气泡边界区分。
80
-
81
- ## 3. 切泡与流式传输
82
-
83
- - 每个 run 默认多泡,但每个泡只承载一个内容块。
84
- - 单块累计达到 `MAX_BUBBLE_CHARS = 12_000` 时,在安全边界切泡:
85
- - 块边界或行首;
86
- - 没有未闭合代码围栏;
87
- - 没有待续写检查点;
88
- - 没有进行中的工具。
89
- - 思考切泡优先保证列表/行结构,不在行中间强制截断。
90
- - 工具参数行与结果代码块始终在同一泡。
91
- - `AppendStream` 负责 300ms 平台下限、500ms 默认合帧、429/50002 退避和同泡续写。
92
- - `index` 每次发送尝试递增;失败帧的未确认缓冲用下一个 index 重发。
93
- - 超过 5 分钟或平台拒绝时,最终文本通过普通消息路径补发。
94
-
95
- ## 4. 中断与错误恢复
96
-
97
- ### 4.1 `/stop`
98
-
99
- `/stop` 的流程:
100
-
101
- 1. 取消错误恢复目标;
102
- 2. abort agent;
103
- 3. 等待 `agent_end` 完成当前流、工具结果和 DONE;
104
- 4. 回复 `Abort requested.`。
105
-
106
- 因此已启动的工具结果不会因为 `/stop` 丢失,也不会在 Abort requested 之后继续冒出排队工具泡。
107
-
108
- ### 4.2 模型错误恢复
109
-
110
- - 模型错误结束时保留原 QQ 目标 60 秒。
111
- - pi 自动恢复/重试产生的新 run 会沿用同一 `msgId` 继续推送。
112
- - 没有输出的空重试不会消耗恢复目标;下一次重试仍可继续。
113
- - 新 QQ 消息或 `/stop` 取消恢复。
114
- - 恢复目标内的本地 run 也可能被回传,这是为了延续 pi 自动恢复行为的明确取舍。
115
-
116
- ## 5. 配置
117
-
118
- `~/.pi/agent/pi-qq.json` 只保存设置,不保存凭据。
119
-
120
- | 配置 | 默认 | 说明 |
121
- | --------------- | ---------- | ---------------------------------------- |
122
- | `thinkingRelay` | `true` | 是否回传纯文本思考块 |
123
- | `deliverAs` | `"steer"` | 忙碌时新消息排队方式 |
124
- | `imageMaxSize` | 10MB | 图片下载上限 |
125
- | `fileMaxSize` | 50MB | 文件下载上限 |
126
- | `logLevel` | `"silent"` | 日志阈值 |
127
- | `debug` | 仅迁移读取 | `debug: true` 映射为 `logLevel: "debug"` |
128
-
129
- 已删除配置:`streamRelay`、`streamFlushMs`、`streamAssistant`、`markdownSupport`、`heartbeatMinutes`、`heartbeatMaxMessages`。旧键静默忽略,不写回。
130
-
131
- ## 6. 模块分布与边界
132
-
133
- 当前代码按职责分层:
134
-
135
- <!-- prettier-ignore -->
136
- | 模块 | 职责 |
137
- | ---------------------------- | -------------------------------------------- |
138
- | `index.ts` | 扩展装配、pi 事件订阅、登录/会话命令 |
139
- | `src/qq/qq-diagnostics.ts` | 终端协议诊断(`/qq-test-*`) |
140
- | `src/qq/qq-message-handler.ts` | QQ 入站路由、命令、附件、注入 pi |
141
- | `src/qq/reply-sender.ts` | Markdown 转纯文本、分块、消息发送 |
142
- | `src/relay/run-stream-relay.ts` | 内容块编排、气泡生命周期、工具队列、错误恢复 |
143
- | `src/relay/stream-block-format.ts` | 思考标题、工具图标、参数/结果纯格式化 |
144
- | `src/relay/stream-session.ts` | 流式帧、节流、重试、续写检查点 |
145
- | `src/quota/reply-quota.ts` | 被动回复预算与 `msgId` 窗口 |
146
- | `src/quota/reply-quota-report.ts` | 预算诊断文本 |
147
- | `src/infra/settings.ts` | 配置读取与旧键迁移 |
148
- | `src/qq/qq-bot.ts` | QQBot/Gateway 生命周期和中间件 |
149
- | `src/qq/qr-login.ts` | 扫码登录 |
150
- | `src/attachments/file-attachments.ts` | 文件保存、索引、去重、pending |
151
- | `src/attachments/image-attachments.ts` | 图片校验与视觉输入 |
152
- | `src/attachments/attachment-download.ts` | 图片/文件通用限流下载 |
153
- | `src/attachments/voice-transcript.ts` | QQ ASR 文本提取 |
154
- | `src/infra/file-logger.ts` | 结构化文件日志 |
155
- | `src/infra/display-format.ts` | 字节/token 通用格式化 |
156
-
157
- 边界原则:
158
-
159
- - `index.ts` 不承载回传状态机;
160
- - `stream-block-format.ts` 只做纯格式化,不依赖流对象;
161
- - `run-stream-relay.ts` 只做编排,不直接拼 Markdown 细节;
162
- - `stream-session.ts` 不感知内容块语义;
163
- - `qq-message-handler.ts` 不实现下载、存储或预算;
164
- - 所有配置通过 `settings.ts`,不散落在业务模块;
165
- - 每个模块都有独立测试或可从入口注入依赖。
166
-
167
- ## 7. 验证
168
-
169
- - v3 交付时单元测试:**135 passed**(14 个测试文件)。
170
- - TypeScript、ESLint 和 Prettier 检查通过。
171
- - 真机已验证:
172
- - C2C 登录、文本、图片、文件;
173
- - 思考/工具/文本按块展示;
174
- - 工具行与结果同泡;
175
- - 12k 切泡与标题重复;
176
- - `/stop` 收尾、模型错误后的自动恢复。
177
- - 仍需最终复验:
178
- - 目标客户端上的长列表切分;
179
- - 极端长代码围栏;
180
- - 错误恢复目标 TTL 接近边界的情况;
181
- - 并行工具较多时的消息额度。
182
-
183
- ## 8. 风险与限制
184
-
185
- - 每个内容块一泡会增加消息数;长任务需关注被动额度。
186
- - 12k 切泡依赖状态,极端单行/未闭合围栏仍可能落到平台自动切分。
187
- - 工具图标是硬编码 Emoji,不同 QQ 客户端字体可能略有差异。
188
- - 恢复目标是 60 秒 TTL;超过窗口后不再自动续传。
189
- - 仅支持 C2C 私聊;登录凭据只在进程内存。
190
- - 最终文本在流式失败时走普通消息路径,可能重复已显示的部分,优先保证完整。
@@ -1,327 +0,0 @@
1
- # pi-qq delivery-v4
2
-
3
- > **归档记录。** 内容反映 v4 交付时的状态,可能引用后续已变化的行为;现行说明见 [README-zh.md](../../README-zh.md)。
4
- > 状态:v4 已交付;工具代码块已完成真实 QQ 验证;长耗时工具与离线投递仍是未决项。
5
- > 版本:1.4.0
6
- > 日期:2026-11-04
7
- > 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md)、[delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
8
- > 未完成事项:[doc/todo.md](../todo.md)。
9
-
10
- ## 1. 交付范围
11
-
12
- v4 是一次“输出质量 + 可观测性”交付,本记录合并了六份 v4 工作文档(名称为历史名称):
13
-
14
- - 工具启动可见性(`tool-return`);
15
- - Skill 执行展示(`send-skill`);
16
- - `/status`、中英文与电量(`enhance-status`);
17
- - QQ 手机后台收不到消息(`bugfix-v4`);
18
- - 长耗时工具导致无响应(`long-tool`);
19
- - 工具结果代码块类型(`block-type`)。
20
-
21
- 主要交付:
22
-
23
- 1. 新的工具气泡格式和代码块语言;
24
- 2. `SKILL.md` 读取使用独立 Skill 气泡;
25
- 3. QQ `/status` 与终端 `/qq-status` 统一展示执行状态、语言和电量;
26
- 4. QQ `/last` 作为手动恢复通道;
27
- 5. 长工具和流式失败的 debug 诊断日志。
28
-
29
- 本次不改变传输模型:仍然是 QQ C2C 私聊、被动回复和 `stream_messages` 流式输出。
30
-
31
- ## 2. 工具输出
32
-
33
- ### 2.1 气泡布局
34
-
35
- 每个内容块独立成泡。思考保持纯文本:
36
-
37
- ```text
38
- **💭 思考**
39
-
40
- 推理内容...
41
- ```
42
-
43
- 工具调用使用二级标题:
44
-
45
- ````markdown
46
- ## 💻 bash
47
-
48
- ```bash
49
- npm test
50
- ```
51
-
52
- ```text
53
- 12 passed
54
- ```
55
- ````
56
-
57
- 规则:
58
-
59
- - 工具标题为 `## <图标> <工具名>`;
60
- - `bash` 命令使用 `bash` 代码块,保留换行;
61
- - bash 命令完整展示,不再套用旧的 200 字符参数上限;
62
- - `read` / `write` / `edit` 的路径继续使用行内代码;
63
- - 其他工具的主参数继续使用行内代码;
64
- - 工具调用和结果始终在同一个气泡;
65
- - 不在工具调用和结果之间切泡。
66
-
67
- 结果代码块语言按工具和文件类型选择:
68
-
69
- | 来源 | 结果语言 |
70
- | --------------- | ----------------------------------- |
71
- | `bash` | `text` |
72
- | `write`、`edit` | `text` |
73
- | `read` | 按扩展名选择;未知扩展名回退 `text` |
74
- | 错误或空结果 | `text` |
75
- | 其他工具 | `text` |
76
-
77
- 常用映射包括:`md` → `markdown`、`json` → `json`、`yaml` → `yaml`、`ts` → `typescript`、`tsx` → `tsx`、`js` → `javascript`、`py` → `python`、`sh`/`bash`/`zsh` → `bash`、`html` → `html`、`css` → `css`、`sql` → `sql`、`rs` → `rust`、`go` → `go`、`diff`/`patch` → `diff`。
78
-
79
- 特殊文件名:
80
-
81
- - `Dockerfile` → `dockerfile`;
82
- - `Makefile` → `makefile`;
83
- - `CMakeLists.txt` → `cmake`;
84
- - `README` → `markdown`。
85
-
86
- 空结果和失败结果始终使用 `text`。结果正文仍限制为 600 字符 / 8 行;bash 命令本身不截断。
87
-
88
- 固定图标:
89
-
90
- | 工具 | 图标 | 工具 | 图标 |
91
- | -------- | ---- | -------- | ---- |
92
- | `bash` | 💻 | `read` | 📖 |
93
- | `write` | 📝 | `edit` | ✏️ |
94
- | `grep` | 🔎 | `search` | 🔍 |
95
- | `find` | 🗂️ | `ls` | 📁 |
96
- | `list` | 📋 | `web` | 🌐 |
97
- | `fetch` | 📡 | `delete` | 🗑️ |
98
- | `remove` | ❌ | `todo` | ✅ |
99
- | `test` | 🧪 | 其他 | 🔧 |
100
-
101
- ### 2.2 Skill 气泡
102
-
103
- 读取 `SKILL.md` 时显示:
104
-
105
- ```markdown
106
- ## 🧩 Skill
107
-
108
- `playwright-cli`
109
- ```
110
-
111
- - skill 名称取父目录名;
112
- - 支持 `path` 和 `file_path`;
113
- - 支持 Unix 和 Windows 路径分隔符;
114
- - 不转发 `SKILL.md` 内容;
115
- - 不显示普通 `📖 read` 工具行和结果;
116
- - 每次读取产生一个 Skill 气泡,不做去重;
117
- - QQ 不支持 `/skill:`,只识别模型自动读取。
118
-
119
- ### 2.3 气泡边界
120
-
121
- - 思考、工具、文本各自成块;
122
- - 一次 run 可能产生多个气泡,但工具调用和结果始终同泡;
123
- - `MAX_BUBBLE_CHARS = 12_000` 时在块边界或行首安全切泡;
124
- - 不在未闭合代码围栏、待续写检查点或进行中的工具内切泡;
125
- - 并行工具按开始顺序逐个展示,结果通过 `toolCallId` 归属;
126
- - 工具未完成时,后续思考和文本暂存,避免插入工具调用和结果之间。
127
-
128
- ## 3. 状态、语言与电量
129
-
130
- QQ `/status` 与终端 `/qq-status` 共用同一份格式化结果。
131
-
132
- 当前字段:
133
-
134
- | 字段 | 内容 |
135
- | ------- | ------------------------------------------------ |
136
- | 标题 | `🖥️ pi-qq 状态` |
137
- | 登录 | 扫码登录与掩码 AppID,或“未登录” |
138
- | 连接 | `已连接`、`重连中`、`已停止`、`启动中`、`已阻止` |
139
- | 执行 | `执行中(QQ)`、`执行中(本地)`、`已完成` |
140
- | 模型 | 当前模型名 |
141
- | 上下文 | tokens / window / percent |
142
- | QQ 用户 | 掩码后的绑定 openid |
143
- | 电量 | 百分比和充电/放电/AC;没有电池时隐藏 |
144
- | 设置 | `~/.pi/agent/pi-qq.json` |
145
-
146
- 执行状态以 `ctx.isIdle()` 为全局信号,并用 `runFeedback.isQQRunActive()` 区分 QQ 任务和本地任务。
147
-
148
- 电量支持:
149
-
150
- - Linux:`/sys/class/power_supply/BAT*`;
151
- - macOS:`pmset -g batt`;
152
- - Windows:PowerShell `Get-CimInstance Win32_Battery`;
153
- - 结果缓存 30 秒;
154
- - 读取失败静默隐藏 Battery 行;
155
- - 不新增 npm 依赖。
156
-
157
- 中英文:
158
-
159
- - 新增 `language` 配置,支持 `"zh-cn"` 和 `"en-us"`;
160
- - 默认 `"zh-cn"`;
161
- - 命令回复、状态、错误、流式占位符和 pi-qq 自有日志都走文案表;
162
- - 日志保留稳定字段,并新增 `msgKey`,便于与语言无关地过滤;
163
- - 第三方 SDK 的原始错误和日志保持原文;
164
- - 非法配置回退默认值并给出警告。
165
-
166
- `Bound user` 改名为 `QQ 用户`,并做 openid 掩码。
167
-
168
- ## 4. 工具启动可见性
169
-
170
- 调研结论:工具启动信息延迟主要来自流式合帧,不是工具执行本身。
171
-
172
- - `AppendStream` 默认 500ms 节流,平台下限 300ms;
173
- - 短工具的结果可能在 500ms 内进入同一个 buffer,导致工具名、参数和结果一起出现;
174
- - 长工具通常会在约 500ms 后先发出启动帧;
175
- - 并行工具受 `RunFeedback.activeTool` 串行输出限制,后启动的工具要等前一个工具结束。
176
-
177
- v4 没有实现原计划中的工具启动 `flushAfter`。不过新的代码块格式把 bash 参数从行内代码改成 fenced block,避免了长行内代码被 QQ 折叠成一个点的问题。
178
-
179
- 1.3.6 增加了 debug 时序日志:
180
-
181
- - 工具入队 / append start / append done;
182
- - stream buffer、flush timer 和 flush 结果;
183
- - 事件循环 `meanMs`、`maxMs`、`p99Ms`,后续又增加 `driftMs`。
184
-
185
- ## 5. 长耗时工具
186
-
187
- ### 5.1 失败链路
188
-
189
- 长工具可能导致 QQ 长时间无输出:
190
-
191
- 1. 工具运行期间没有新的 assistant 事件;
192
- 2. QQ 上只有工具启动气泡;
193
- 3. 长静默后,下一帧很容易触发 `msg_id` 过期或被动回复次数超限;
194
- 4. `BubbleWriter` 用同一个过期 `msg_id` / `stream_msg_id` 尝试 resume;
195
- 5. resume 次数耗尽后 `killStream()`,后续工具输出全部丢失;
196
- 6. writer 死亡时 `onToolEnd()` 直接返回,`activeTool` 和 deferred 文本卡住;
197
- 7. 最终 assistant 文本可能改走普通消息,超过 5 分钟后会降级为主动消息。
198
-
199
- 其他放大因素:
200
-
201
- - 每个思考/工具气泡都会新建一条流式回复,但 `ReplyBudget` 没有把流式气泡计入 4 次被动回复上限;
202
- - `/stop` 要等 `waitForEnd()` 才回复,可能占住 SDK 并发锁;
203
- - 不转发 `tool_execution_update`,没有进度帧;
204
- - 新 QQ 消息以 `steer` 排队,要等当前工具批次结束才处理。
205
-
206
- ### 5.2 已交付内容
207
-
208
- - 只加 debug 诊断,不修改行为;
209
- - QQ `/last` 作为手动恢复:
210
- - 运行中:`RunFeedback.repushCurrent()` 绑定到新的 `/last` 消息并重推当前文本;
211
- - 空闲时:`sendStreamReply()` 推送最近一次完成的 assistant 文本。
212
- - 1.3.6 及后续补充的诊断:
213
- - 工具 `durationMs`、`updateCount`、`updateSpanMs`、首次部分输出;
214
- - run 目标选择、工具 queued/started/finished/ignored、assistant final 决策、run cleanup;
215
- - writer `dead`、`hasPendingResume`、`resumeAttempts`、`lastFrameAgeMs`;
216
- - 流式帧 `httpStatus`、`bizCode`、`path`、`msgSeq`、`streamMsgId`、`bufferLength`;
217
- - `/stop` 等待时长;
218
- - 事件循环 `driftMs`。
219
-
220
- ### 5.3 未修复的协议风险
221
-
222
- v4 未修复:
223
-
224
- - 流式气泡未计入被动回复额度;
225
- - `DONE` 帧的 `content_raw` 为空;
226
- - stream 请求同时发送 `event_id` 和 `msg_id`,而协议约定二选一;
227
- - resume 复用已过期的标识;
228
- - 没有过期被动窗口的待发送队列;
229
- - 流式成功后没有普通文本终态兜底;
230
- - SDK 没有心跳 ACK 超时检测;
231
- - 没有启用 session persistence。
232
-
233
- ## 6. QQ 后台与离线投递
234
-
235
- 现象:iPhone QQ 长时间后台后重新打开,电脑上的 pi 仍在运行,但离线期间的机器人输出看不到;新入站消息仍能到达 pi,机器人也能回复新消息。
236
-
237
- 最可能的解释是手机端/平台离线投递问题:QQ 不会补发手机离线期间产生的流式机器人内容。由于没有事故日志,这一点尚未完全确认。
238
-
239
- v4 已交付:
240
-
241
- - `/last` 手动恢复;
242
- - 登录、连接、执行、模型、上下文和额度的状态/诊断可见性。
243
-
244
- v4 未交付:
245
-
246
- - 60 分钟被动窗口修正(代码仍按 5 分钟);
247
- - 流式结束后的持久化最终文本;
248
- - 下次入站时补发离线摘要;
249
- - SDK 心跳 ACK 超时;
250
- - session persistence;
251
- - 运行中自动把 writer 重绑到新入站消息。
252
-
253
- ## 7. 诊断
254
-
255
- 终端命令:
256
-
257
- - `/qq-test-budget`:被动预算和流式气泡计数;
258
- - `/qq-test-md [text]`:Markdown 渲染测试;
259
- - `/qq-test-stream`:流式时间线和 resume 测试。
260
-
261
- 日志:
262
-
263
- - 在 `~/.pi/agent/pi-qq.json` 设置 `logLevel: "debug"`;
264
- - 日志路径:`<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`;
265
- - 可用 `PI_QQ_LOG_DIR` 覆盖目录;
266
- - `info` 记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。
267
-
268
- ## 8. 模块与边界
269
-
270
- <!-- prettier-ignore -->
271
- | 模块 | 职责 |
272
- | ---- | ---- |
273
- | `index.ts` | 扩展装配、pi 事件、登录/会话命令、状态数据收集 |
274
- | `src/qq/` | QQ 生命周期、扫码登录、入站路由、回复、诊断、状态格式化 |
275
- | `src/relay/` | 思考/工具/文本回传、气泡布局、流式会话、工具结果格式化 |
276
- | `src/quota/` | 被动回复预算与诊断 |
277
- | `src/attachments/` | 文件下载、保存、pending、语音转写 |
278
- | `src/infra/` | 配置、i18n、日志、电量、显示格式化 |
279
-
280
- 边界原则:
281
-
282
- - 纯格式化放在 `stream-block-format.ts`;
283
- - relay 编排放在 `run-stream-relay.ts` / `bubble-writer.ts`;
284
- - 流式帧和重试放在 `stream-session.ts`;
285
- - QQ 入站解析和命令路由放在 `src/qq/`;
286
- - 所有配置通过 `settings.ts`;
287
- - 模块由入口注入依赖,保持独立可测。
288
-
289
- 图片与文件共用保存/pending 流程;v4 之前的图片专用链路和 `imageMaxSize` 已移除。
290
-
291
- ## 9. 验证
292
-
293
- - 单元测试:**172 passed**,18 个测试文件。
294
- - TypeScript、ESLint、Prettier 检查通过。
295
- - 2026-11-04 真实 QQ 工具代码块验证:
296
- - 测试目录:`/home/chen/project/pi-qq-test`;
297
- - 文件:`hello.py`、`Hello.java`、`hello.rs`、`hello.ts`;
298
- - 日志:`.pi/pi-qq/logs/pi-qq-2026-11-04.log`;
299
- - 观察到 `## 💻 bash` + bash 代码块、`## 📖 read` + rust/typescript 结果块、`## 📝 write` + 行内路径;
300
- - event-loop `driftMs` 为 0–1ms,`maxMs` 约 101ms。
301
- - 本次验收未单独执行 `/qq-test-stream`。
302
- - 仍建议在真实 QQ 上补一次 `/status` 和长任务/离线场景的手动验收。
303
-
304
- ## 10. 风险与限制
305
-
306
- - 长任务可能耗尽 4 次被动回复,因为流式气泡没有计入额度。
307
- - 超过 5 分钟会降级为主动消息;用户可能关闭主动消息。
308
- - resume 无法恢复已过期的 `msg_id` / `stream_msg_id`。
309
- - 长工具没有进度心跳,只有 `typing`。
310
- - 工具启动可能受 500ms 节流影响。
311
- - QQ 客户端对语言高亮的支持不一致。
312
- - 12k 切泡依赖状态;极端单行或未闭合围栏仍可能触发平台行为。
313
- - 仅支持 C2C 私聊;登录凭据只在进程内存。
314
- - debug 日志可能包含提示词、工具参数和结果。
315
-
316
- ## 11. 未完成事项
317
-
318
- - [doc/todo.md](../todo.md) 第 1 节:长运行 bash 参数/工具启动可见性。
319
- - [doc/todo.md](../todo.md) 第 2 节:长耗时工具导致 QQ 侧无输出。
320
- - 先修复流式气泡额度记账,再增加更多按块气泡。
321
- - 设计过期被动窗口和 pending 输出的处理方式。
322
- - 验证 `DONE` 内容以及 `event_id` / `msg_id` 用法。
323
- - 增加进度心跳或转发 `tool_execution_update`。
324
- - 增加 SDK 心跳 ACK 超时,评估 session persistence。
325
- - 决定是否需要进一步验收 `/status` 和 `/last`。
326
-
327
- 在拿到真实现场日志前,本文和诊断日志是 v4 的判断依据;不把未经证实的 relay 重写纳入 v4。