@chen_hu_hu/pi-qq 1.2.3 → 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.
Files changed (33) hide show
  1. package/README-zh.md +34 -24
  2. package/README.md +26 -16
  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 +187 -0
  8. package/doc/delivery-v3.md +187 -0
  9. package/index.ts +71 -66
  10. package/package.json +3 -3
  11. package/src/{download.ts → attachments/attachment-download.ts} +1 -4
  12. package/src/{files.ts → attachments/file-attachments.ts} +3 -14
  13. package/src/{images.ts → attachments/image-attachments.ts} +3 -10
  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 -28
  17. package/src/infra/settings.ts +49 -0
  18. package/src/{bot.ts → qq/qq-bot.ts} +4 -29
  19. package/src/{inbound.ts → qq/qq-message-handler.ts} +10 -23
  20. package/src/{login.ts → qq/qr-login.ts} +20 -16
  21. package/src/{outbound.ts → qq/reply-sender.ts} +3 -34
  22. package/src/qrcode-terminal.d.ts +0 -2
  23. package/src/{budget-status.ts → quota/reply-quota-report.ts} +2 -3
  24. package/src/{reply-budget.ts → quota/reply-quota.ts} +0 -21
  25. package/src/relay/run-stream-relay.ts +586 -0
  26. package/src/relay/stream-block-format.ts +114 -0
  27. package/src/{append-stream.ts → relay/stream-session.ts} +46 -29
  28. package/doc/features-v1.md +0 -239
  29. package/doc/features-v2.md +0 -210
  30. package/doc/plan-v1.md +0 -190
  31. package/doc/plan-v2.md +0 -332
  32. package/src/config.ts +0 -82
  33. package/src/run-feedback.ts +0 -409
package/README-zh.md CHANGED
@@ -33,6 +33,14 @@ pi --extension /path/to/pi-qq
33
33
  - **图片**:作为视觉输入交给 pi。
34
34
  - **文件**:保存到当前工作区的 `.pi/pi-qq/<sessionId>/uploads/`,并等待你的下一条指令。
35
35
 
36
+ ### QQ 输出格式
37
+
38
+ - **思考**:独立气泡,纯文本,首行 `**💭 思考**`;长思考在 12k 行边界续泡时会重复标题。
39
+ - **工具**:每次调用独立气泡,首行 `**<图标> <工具名>**`,空行,参数行内代码,空行,结果 `text` 代码块。
40
+ - **普通消息**:原文,不加标题。
41
+ - **工具图标**:💻 bash、📖 read、📝 write、✏️ edit、🔎 grep、🔍 search、🗂️ find、📁 ls、📋 list、🌐 web、📡 fetch、🗑️ delete、❌ remove、✅ todo、🧪 test;未配置工具使用 🔧。
42
+ - **错误恢复**:模型错误后 60 秒内自动恢复的 run 会继续推送到原 QQ 会话;`/stop` 会等待当前工具和流收尾后再回复。
43
+
36
44
  ### 文件
37
45
 
38
46
  **只发送文件不会启动 pi。** 文件会先保存,pi 等待下一条文字或语音指令后再处理。
@@ -67,15 +75,15 @@ Summarize this file.
67
75
 
68
76
  在 pi 终端执行:
69
77
 
70
- | 命令 | 说明 |
71
- | -------------------- | -------------------------------------- |
72
- | `/qq-login` | 扫码登录并绑定扫码的 QQ 用户 |
73
- | `/qq-status` | 显示登录、连接、模型、上下文和绑定用户 |
74
- | `/qq-logout` | 退出登录并清除内存中的凭据 |
75
- | `/qq-test-budget` | 显示被动回复额度和流式气泡诊断信息 |
76
- | `/qq-test-md [text]` | 发送 Markdown 测试消息 |
77
- | `/qq-test-stream` | 运行流式时间线诊断 |
78
- | `/qq-new` | 重置当前会话(由 QQ 侧 `/new` 调用) |
78
+ | 命令 | 说明 |
79
+ | -------------------- | --------------------------------------- |
80
+ | `/qq-login` | 扫码登录并绑定扫码的 QQ 用户 |
81
+ | `/qq-status` | 显示登录、连接、模型、上下文和绑定用户 |
82
+ | `/qq-logout` | 退出登录并清除内存中的凭据 |
83
+ | `/qq-test-budget` | 显示被动回复额度和流式气泡诊断信息 |
84
+ | `/qq-test-md [text]` | 发送 Markdown 测试消息 |
85
+ | `/qq-test-stream` | 运行流式时间线诊断(`resume` 验证续写) |
86
+ | `/qq-new` | 重置当前会话(由 QQ 侧 `/new` 调用) |
79
87
 
80
88
  QQ 侧命令:
81
89
 
@@ -93,24 +101,18 @@ QQ 侧命令:
93
101
 
94
102
  ```json
95
103
  {
96
- "markdownSupport": false,
97
- "streamFlushMs": 10000,
104
+ "thinkingRelay": true,
98
105
  "logLevel": "silent"
99
106
  }
100
107
  ```
101
108
 
102
- | 配置项 | 默认值 | 说明 |
103
- | ---------------------- | ---------- | ------------------------------------------------------ |
104
- | `streamAssistant` | `true` | 流式回传 assistant 回复 |
105
- | `markdownSupport` | `false` | 机器人有 QQ Markdown 权限;设为 `true` 时透传 Markdown |
106
- | `deliverAs` | `"steer"` | 忙碌时新消息的排队方式:`steer` 或 `followUp` |
107
- | `imageMaxSize` | `10485760` | QQ 图片下载上限(字节,10MB) |
108
- | `fileMaxSize` | `52428800` | QQ 文件下载上限(字节,50MB) |
109
- | `heartbeatMinutes` | `10` | 长任务心跳间隔;`0` 表示关闭 |
110
- | `heartbeatMaxMessages` | `3` | 每次运行的消息心跳上限 |
111
- | `streamRelay` | `true` | 使用 append 模式流式气泡 |
112
- | `streamFlushMs` | `10000` | 流式汇总帧间隔(毫秒,最小 300) |
113
- | `logLevel` | `"silent"` | 日志阈值:`silent`、`error`、`warn`、`info` 或 `debug` |
109
+ | 配置项 | 默认值 | 说明 |
110
+ | --------------- | ---------- | ------------------------------------------------------ |
111
+ | `thinkingRelay` | `true` | 以 `💭 思考` 标题的纯文本回传思考;`false` 时隐藏 |
112
+ | `deliverAs` | `"steer"` | 忙碌时新消息的排队方式:`steer` 或 `followUp` |
113
+ | `imageMaxSize` | `10485760` | QQ 图片下载上限(字节,10MB) |
114
+ | `fileMaxSize` | `52428800` | QQ 文件下载上限(字节,50MB) |
115
+ | `logLevel` | `"silent"` | 日志阈值:`silent`、`error`、`warn`、`info` 或 `debug` |
114
116
 
115
117
  启用日志后,日志写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。可用 `PI_QQ_LOG_DIR` 覆盖目录。`info` 只记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。旧配置 `debug: true` 会映射为 `logLevel: "debug"`。
116
118
 
@@ -128,10 +130,18 @@ npm run format:check
128
130
 
129
131
  `eslint.config.ts` 使用 Node.js 原生 TypeScript 剥离能力加载,不需要 `jiti`。
130
132
 
133
+ ### 文件命名
134
+
135
+ - 源文件使用 `<领域>-<职责>.ts`,例如 `qq-bot.ts`、`qq-message-handler.ts`、`reply-sender.ts`、`reply-quota.ts`、`stream-session.ts`、`stream-block-format.ts`、`run-stream-relay.ts`、`file-attachments.ts`。
136
+ - 源目录按限界上下文分组:`src/qq/`、`src/relay/`、`src/attachments/`、`src/quota/`、`src/infra/`。
137
+ - 测试文件镜像源路径和文件名:`test/<group>/<source>.test.ts`,例如 `test/relay/run-stream-relay.test.ts`。
138
+ - 纯类型模块使用 `.d.ts` 后缀;`.d.ts` 表示 TypeScript declaration file,不包含运行时代码,例如 `qrcode-terminal.d.ts`。
139
+ - 避免 `inbound`、`outbound`、`format`、`util`、`helpers` 这类泛化名称,应体现领域和职责。
140
+
131
141
  ## 说明
132
142
 
133
143
  - 仅支持 C2C(QQ 私聊)。
134
- - 只有 QQ 入站消息触发的任务才会回传 QQ;在 pi 侧直接发起的任务只在本地处理,不推送 QQ。
144
+ - QQ 入站消息触发的任务会回传 QQ;模型错误后的自动恢复 run 也会继续回传。无关的本地任务不推送 QQ。
135
145
  - 收到的图片会作为视觉输入传给模型;当前模型必须支持图片输入。
136
146
  - 保存的文件位于工作区 `.pi/` 下;如有需要,请把 `.pi/` 加入你自己的项目 `.gitignore`。
137
147
  - QQ 对每条入站消息的被动回复次数有限制。可用 `/qq-test-budget` 查看本地额度。
package/README.md CHANGED
@@ -33,6 +33,14 @@ Send a QQ private message to the bot to start a task.
33
33
  - **Images**: sent to pi as vision input.
34
34
  - **Files**: saved under the current workspace at `.pi/pi-qq/<sessionId>/uploads/` and wait for your next instruction.
35
35
 
36
+ ### QQ output format
37
+
38
+ - **Thinking**: its own bubble, plain text, with `**💭 思考**` as the first line. When a long thought continues in a new bubble at a 12k line boundary, the header is repeated.
39
+ - **Tools**: one bubble per call: `**<icon> <name>**`, blank line, inline-code argument, blank line, then the result in a `text` code block.
40
+ - **Regular messages**: raw text with no header.
41
+ - **Tool icons**: 💻 bash, 📖 read, 📝 write, ✏️ edit, 🔎 grep, 🔍 search, 🗂️ find, 📁 ls, 📋 list, 🌐 web, 📡 fetch, 🗑️ delete, ❌ remove, ✅ todo, 🧪 test; unconfigured tools use 🔧.
42
+ - **Error recovery**: after a model error, automatic retry runs within 60 seconds keep pushing to the original QQ chat. `/stop` waits for active tools and streams to finish before replying.
43
+
36
44
  ### Files
37
45
 
38
46
  A file-only message does **not** start pi. The file is saved, and pi waits for your next text or voice instruction before processing it.
@@ -74,7 +82,7 @@ Run these in the pi terminal:
74
82
  | `/qq-logout` | Log out and clear in-memory credentials |
75
83
  | `/qq-test-budget` | Show passive-reply budget and stream-bubble diagnostics |
76
84
  | `/qq-test-md [text]` | Send a Markdown test message |
77
- | `/qq-test-stream` | Run a streamed timeline diagnostic |
85
+ | `/qq-test-stream` | Run a streamed timeline diagnostic (`resume` for probe) |
78
86
  | `/qq-new` | Reset the current session (used by QQ `/new`) |
79
87
 
80
88
  QQ-side commands:
@@ -93,24 +101,18 @@ Create `~/.pi/agent/pi-qq.json` to override defaults. This file contains setting
93
101
 
94
102
  ```json
95
103
  {
96
- "markdownSupport": false,
97
- "streamFlushMs": 10000,
104
+ "thinkingRelay": true,
98
105
  "logLevel": "silent"
99
106
  }
100
107
  ```
101
108
 
102
- | Key | Default | Description |
103
- | ---------------------- | ---------- | ------------------------------------------------------------ |
104
- | `streamAssistant` | `true` | Stream assistant replies |
105
- | `markdownSupport` | `false` | Bot has QQ Markdown permission; pass Markdown through |
106
- | `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
107
- | `imageMaxSize` | `10485760` | QQ image download limit in bytes (10MB) |
108
- | `fileMaxSize` | `52428800` | QQ file download limit in bytes (50MB) |
109
- | `heartbeatMinutes` | `10` | Long-task heartbeat interval; `0` disables |
110
- | `heartbeatMaxMessages` | `3` | Per-run message heartbeat limit |
111
- | `streamRelay` | `true` | Use append-mode stream bubbles |
112
- | `streamFlushMs` | `10000` | Stream summary frame interval in ms (minimum 300) |
113
- | `logLevel` | `"silent"` | Log threshold: `silent`, `error`, `warn`, `info`, or `debug` |
109
+ | Key | Default | Description |
110
+ | --------------- | ---------- | ------------------------------------------------------------ |
111
+ | `thinkingRelay` | `true` | Relay thinking as plain text with a `💭 思考` header |
112
+ | `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
113
+ | `imageMaxSize` | `10485760` | QQ image download limit in bytes (10MB) |
114
+ | `fileMaxSize` | `52428800` | QQ file download limit in bytes (50MB) |
115
+ | `logLevel` | `"silent"` | Log threshold: `silent`, `error`, `warn`, `info`, or `debug` |
114
116
 
115
117
  When enabled, logs are written to `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`. `PI_QQ_LOG_DIR` overrides the directory. `info` records metadata only; `debug` records full events, attachments, prompts, and tool payloads. Legacy `debug: true` maps to `logLevel: "debug"`.
116
118
 
@@ -128,10 +130,18 @@ npm run format:check
128
130
 
129
131
  `eslint.config.ts` is loaded through Node.js native TypeScript stripping; `jiti` is not required.
130
132
 
133
+ ### File naming
134
+
135
+ - Source files use `<domain>-<role>.ts`, for example `qq-bot.ts`, `qq-message-handler.ts`, `reply-sender.ts`, `reply-quota.ts`, `stream-session.ts`, `stream-block-format.ts`, `run-stream-relay.ts`, and `file-attachments.ts`.
136
+ - Source directories group bounded contexts: `src/qq/`, `src/relay/`, `src/attachments/`, `src/quota/`, and `src/infra/`.
137
+ - Test files mirror the source path and file name: `test/<group>/<source>.test.ts`, for example `test/relay/run-stream-relay.test.ts`.
138
+ - Type-only modules use the `.d.ts` suffix; `.d.ts` means TypeScript declaration file and contains no runtime code. Example: `qrcode-terminal.d.ts`.
139
+ - Avoid vague standalone names such as `inbound`, `outbound`, `format`, `util`, or `helpers`; encode the domain and responsibility instead.
140
+
131
141
  ## Notes
132
142
 
133
143
  - Only C2C (QQ private chat) is supported.
134
- - Only runs triggered by inbound QQ messages are relayed to QQ. Tasks started directly in pi stay local.
144
+ - Runs triggered by inbound QQ messages are relayed to QQ, as are automatic retry runs after model errors. Unrelated tasks started directly in pi stay local.
135
145
  - Incoming images are passed to the model as vision input; the current model must support image input.
136
146
  - Saved files are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
137
147
  - QQ limits passive replies per inbound message. Use `/qq-test-budget` to inspect the local budget.
@@ -0,0 +1,160 @@
1
+ # pi-qq delivery-v1
2
+
3
+ > 状态:v1 已交付,作为后续版本基线。
4
+ > 后续版本见 [delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
5
+
6
+ ## 1. 交付范围
7
+
8
+ v1 将 pi 接入 QQ 单人私聊(C2C):
9
+
10
+ - 手机 QQ 发送文字、图片、文件;
11
+ - pi 在用户电脑上执行任务;
12
+ - assistant 文本回传到 QQ;
13
+ - 登录、命令、回复预算和连接生命周期可管理。
14
+
15
+ 技术栈:
16
+
17
+ | 依赖 | 用途 |
18
+ | ---------------------------------- | ------------------------------------------------ |
19
+ | `@tencent-connect/qqbot-nodejs` | QQ 协议层:Gateway、C2C 消息、媒体上传、流式消息 |
20
+ | `@tencent-connect/qqbot-connector` | 扫码登录,凭据只保存在进程内存 |
21
+ | `@earendil-works/pi-coding-agent` | pi 扩展宿主、事件订阅、消息注入、上下文信息 |
22
+
23
+ ## 2. 架构
24
+
25
+ 扩展以目录形式加载,在 pi 进程内持有 QQBot:
26
+
27
+ ```text
28
+ 手机 QQ(C2C)
29
+ │ WebSocket Gateway
30
+ ▼
31
+ QQBot
32
+ │ message
33
+ ▼
34
+ pi-qq:白名单 → QQ 命令 → 文本/图片/文件
35
+ │ pi.sendUserMessage()
36
+ ▼
37
+ pi 会话
38
+ │ message_update / message_end / agent_end
39
+ ▼
40
+ pi-qq:格式化 → QQ 文本/流式消息
41
+ ```
42
+
43
+ - QQ → pi:白名单校验后注入文本和图片;文件保存在工作区。
44
+ - pi → QQ:订阅 assistant 消息并回传;长任务使用独立的反馈时间线。
45
+ - 生命周期:`session_start` 启动 bot,`session_shutdown` 幂等停止。
46
+ - 断线重连由 SDK 负责;致命关闭码 4914/4915 给出明确错误。
47
+
48
+ ## 3. 功能
49
+
50
+ ### F1 扫码登录
51
+
52
+ - 只支持 `/qq-login` 扫码登录。
53
+ - 凭据只保存在进程内存,不写入配置文件;重启 pi 后重新扫码。
54
+ - 成功后绑定扫码用户 openid,其他 C2C 用户静默忽略。
55
+ - `/qq-logout` 清除凭据并断开连接。
56
+ - `/qq-status` 显示登录、连接、模型、上下文和绑定用户;AppID 脱敏。
57
+
58
+ ### F2 单人聊天
59
+
60
+ - 只接受白名单用户的 C2C 消息。
61
+ - 文本通过 `pi.sendUserMessage()` 注入 pi。
62
+ - 忙碌时按 `deliverAs`(`steer` 或 `followUp`)排队。
63
+ - QQ 侧命令:`/new`、`/stop`、`/compact`、`/status`、`/help`。
64
+ - 运行期间发送 typing 指示。
65
+
66
+ ### F3 图片和文件
67
+
68
+ 图片:
69
+
70
+ - 下载后校验类型和大小,转换为 pi 的 `ImageContent`。
71
+ - 支持 jpg/jpeg/png/webp/gif;不支持的 `image/*` 明确拒绝。
72
+ - 单张超时 15 秒,默认上限 10MB。
73
+ - 部分图片失败时,成功图片仍注入,并回传失败清单。
74
+ - 当前模型不支持视觉输入时提示并跳过图片。
75
+
76
+ 文件:
77
+
78
+ - 保存到 `.pi/pi-qq/YYYY-MM-DD/<msgId>/`,提示词附带绝对路径、大小和原始文件名。
79
+ - 单文件超时 60 秒,默认上限 50MB。
80
+ - 文件名安全化;同名文件自动追加 `-1`、`-2`。
81
+ - 文件内容不直接注入模型,由工具按需读取。
82
+
83
+ ### F4 assistant 回传
84
+
85
+ - 数据源是 assistant 的 `message_end`。
86
+ - Markdown 转纯文本:去强调/标题/行内代码标记,列表转 `•`,链接转文字和 URL。
87
+ - 长文本按 `TEXT_CHUNK_LIMIT` 分块发送。
88
+ - 支持 C2C 流式追加;平台失败时降级为普通消息路径。
89
+ - `stopReason === "error"` 时回传错误摘要。
90
+
91
+ ### F5/F6 用量摘要
92
+
93
+ 已取消。不再发送 token、缓存、成本和上下文明细;上下文通过 `/status` / `/qq-status` 查看。
94
+
95
+ ### F7 长任务反馈
96
+
97
+ v1 曾使用窗口汇总、工具计数和消息心跳维持长任务活性。该实现已在 v3 被 F12/F13 取代;v1 历史行为不代表当前版本。
98
+
99
+ ## 4. 平台限制与预算
100
+
101
+ | 限制 | 应对 |
102
+ | ------------------------------- | ------------------------------------------------- |
103
+ | 被动回复约 4 条 / 5 分钟窗口 | `ReplyBudget` 记录 `msgId` 配额,超限降级主动发送 |
104
+ | 流式消息仅 C2C,节流 ≥300ms | `AppendStream` 负责合帧和退避 |
105
+ | 单条文本约 5000 字符 | 自动分块 |
106
+ | 流式消息依赖 5 分钟内的 `msgId` | 过期后降级为普通消息 |
107
+
108
+ ## 5. 配置与命令
109
+
110
+ `~/.pi/agent/pi-qq.json` 只保存设置,不保存凭据。
111
+
112
+ | 配置 | 默认 | 说明 |
113
+ | --------------- | ---------- | ---------------------------------------- |
114
+ | `thinkingRelay` | `true` | 回传思考正文 |
115
+ | `deliverAs` | `"steer"` | 忙碌时新消息的排队方式 |
116
+ | `imageMaxSize` | 10MB | 图片下载上限 |
117
+ | `fileMaxSize` | 50MB | 文件下载上限 |
118
+ | `logLevel` | `"silent"` | 日志阈值 |
119
+ | `debug` | 仅迁移读取 | `debug: true` 映射为 `logLevel: "debug"` |
120
+
121
+ pi 侧命令:`/qq-login`、`/qq-status`、`/qq-logout`、`/qq-test-budget`、`/qq-test-md`、`/qq-test-stream`、`/qq-new`。
122
+
123
+ QQ 侧命令:`/new`、`/stop`、`/compact`、`/status`、`/help`。
124
+
125
+ ## 6. 模块与边界(v1 基线)
126
+
127
+ <!-- prettier-ignore -->
128
+ | 模块 | 职责 |
129
+ | ---------------------------- | ------------------------------------ |
130
+ | `index.ts` | 扩展装配、事件订阅、命令注册 |
131
+ | `src/infra/settings.ts` | 只读配置与迁移 |
132
+ | `src/qq/qr-login.ts` | 扫码登录 |
133
+ | `src/qq/qq-bot.ts` | QQBot 生命周期、Gateway 状态、中间件 |
134
+ | `src/qq/qq-message-handler.ts` | 入站路由、命令、附件处理、注入 pi |
135
+ | `src/attachments/image-attachments.ts` | 图片校验与 `ImageContent` |
136
+ | `src/attachments/file-attachments.ts` | 文件保存、索引、提示词关联 |
137
+ | `src/attachments/attachment-download.ts` | 图片/文件通用限流下载 |
138
+ | `src/qq/reply-sender.ts` | Markdown 转换、分块、发送 |
139
+ | `src/quota/reply-quota.ts` | 被动回复预算 |
140
+ | `src/quota/reply-quota-report.ts` | 预算诊断格式化 |
141
+ | `src/infra/display-format.ts` | 字节与 token 格式化 |
142
+ | `src/infra/file-logger.ts` | 文件日志 |
143
+ | `src/relay/run-stream-relay.ts` | 长任务反馈状态机 |
144
+ | `src/relay/stream-session.ts` | 流式追加、重试、续写检查点 |
145
+
146
+ 边界原则:入口只做装配;协议、存储、格式化、预算分别放在独立模块;模块通过显式参数和 `RunFeedbackDeps` 之类的接口通信。
147
+
148
+ ## 7. 验证
149
+
150
+ - 扫码登录、`/qq-status`、`/qq-logout` 实测通过。
151
+ - QQ 文本触发 pi,回复回传 QQ。
152
+ - 图片作为视觉输入、文件保存和提示词路径关联实测通过。
153
+ - 被动回复预算实测不超限;异常路径可降级主动发送。
154
+
155
+ ## 8. 已知限制
156
+
157
+ - 仅支持 C2C 私聊。
158
+ - 登录凭据在进程内存,重启后必须重新扫码。
159
+ - 不提供开始确认和用量摘要,减少被动消息。
160
+ - 历史流式/心跳实现已由 v3 取代,不应作为当前行为参考。
@@ -0,0 +1,160 @@
1
+ # pi-qq delivery-v1
2
+
3
+ > Status: v1 delivered; this is the baseline for later versions.
4
+ > Later versions: [delivery-v2.md](./delivery-v2.md), [delivery-v3.md](./delivery-v3.md).
5
+
6
+ ## 1. Scope
7
+
8
+ v1 connects pi to a QQ private chat (C2C):
9
+
10
+ - send text, images, and files from mobile QQ;
11
+ - pi runs tasks on the user's machine;
12
+ - assistant text is relayed back to QQ;
13
+ - login, commands, reply quota, and connection lifecycle are managed.
14
+
15
+ Stack:
16
+
17
+ | Dependency | Purpose |
18
+ | ---------------------------------- | ----------------------------------------------------------------- |
19
+ | `@tencent-connect/qqbot-nodejs` | QQ protocol: Gateway, C2C messages, media upload, stream messages |
20
+ | `@tencent-connect/qqbot-connector` | QR login; credentials stay in process memory |
21
+ | `@earendil-works/pi-coding-agent` | pi extension host, events, message injection, context |
22
+
23
+ ## 2. Architecture
24
+
25
+ The extension is loaded as a directory and owns a QQBot inside the pi process:
26
+
27
+ ```text
28
+ mobile QQ (C2C)
29
+ │ WebSocket Gateway
30
+ ▼
31
+ QQBot
32
+ │ message
33
+ ▼
34
+ pi-qq: allowlist → QQ commands → text/images/files
35
+ │ pi.sendUserMessage()
36
+ ▼
37
+ pi session
38
+ │ message_update / message_end / agent_end
39
+ ▼
40
+ pi-qq: format → QQ text/stream message
41
+ ```
42
+
43
+ - QQ → pi: validate the allowlist, then inject text and images; files are saved in the workspace.
44
+ - pi → QQ: subscribe to assistant messages and relay them; long tasks use an independent feedback timeline.
45
+ - Lifecycle: `session_start` starts the bot; `session_shutdown` stops it idempotently.
46
+ - Reconnection is handled by the SDK; fatal close codes 4914/4915 produce explicit errors.
47
+
48
+ ## 3. Features
49
+
50
+ ### F1 QR login
51
+
52
+ - Login is only available through `/qq-login`.
53
+ - Credentials are kept in process memory, never in the config file; restarting pi requires scanning again.
54
+ - The scanning user's openid becomes the only allowed C2C peer.
55
+ - `/qq-logout` clears credentials and disconnects.
56
+ - `/qq-status` shows login, connection, model, context, and bound user; AppID is masked.
57
+
58
+ ### F2 Single-user chat
59
+
60
+ - Accept only allowlisted C2C messages.
61
+ - Inject text through `pi.sendUserMessage()`.
62
+ - Queue messages while the agent is busy according to `deliverAs` (`steer` or `followUp`).
63
+ - QQ-side commands: `/new`, `/stop`, `/compact`, `/status`, `/help`.
64
+ - Send typing indicators during a run.
65
+
66
+ ### F3 Images and files
67
+
68
+ Images:
69
+
70
+ - Download, validate type/size, and convert to pi's `ImageContent`.
71
+ - Supported: jpg/jpeg/png/webp/gif; unsupported `image/*` types are rejected.
72
+ - Per-image timeout: 15 seconds; default limit: 10MB.
73
+ - If some images fail, successful images are still injected and failures are reported.
74
+ - If the model has no vision support, notify the user and skip images.
75
+
76
+ Files:
77
+
78
+ - Saved under `.pi/pi-qq/YYYY-MM-DD/<msgId>/`; the prompt includes the absolute path, size, and original filename.
79
+ - Per-file timeout: 60 seconds; default limit: 50MB.
80
+ - Filenames are sanitized; duplicates get `-1`, `-2` suffixes.
81
+ - File contents are not injected into the model; tools read them on demand.
82
+
83
+ ### F4 Assistant relay
84
+
85
+ - Source: assistant `message_end`.
86
+ - Convert Markdown to plain text: strip emphasis/headings/inline-code markers, convert list bullets to `•`, and keep link text plus URL.
87
+ - Split long text by `TEXT_CHUNK_LIMIT`.
88
+ - Support C2C stream append; fall back to normal messages if the platform rejects the stream.
89
+ - On `stopReason === "error"`, relay an error summary.
90
+
91
+ ### F5/F6 Usage summary
92
+
93
+ Removed. Do not send token, cache, cost, or context details; use `/status` or `/qq-status` to inspect context usage.
94
+
95
+ ### F7 Long-task feedback
96
+
97
+ v1 used window summaries, tool counts, and message heartbeats to keep long runs visible. This was replaced by F12/F13 in v3; v1 behavior is historical, not current.
98
+
99
+ ## 4. Platform limits and quota
100
+
101
+ | Limit | Mitigation |
102
+ | --------------------------------------------------- | --------------------------------------------------------------------- |
103
+ | About 4 passive replies per 5-minute window | `ReplyBudget` records `msgId` quota and falls back to proactive sends |
104
+ | Stream messages are C2C-only; throttle ≥300ms | `AppendStream` handles batching and retries |
105
+ | About 5000 characters per text message | Automatic chunking |
106
+ | Stream messages need a `msgId` newer than 5 minutes | Fall back to normal messages after expiry |
107
+
108
+ ## 5. Settings and commands
109
+
110
+ `~/.pi/agent/pi-qq.json` stores settings only; credentials are never written there.
111
+
112
+ | Setting | Default | Description |
113
+ | --------------- | -------------- | ----------------------------------------- |
114
+ | `thinkingRelay` | `true` | Relay thinking text |
115
+ | `deliverAs` | `"steer"` | Queue behavior while busy |
116
+ | `imageMaxSize` | 10MB | Image download limit |
117
+ | `fileMaxSize` | 50MB | File download limit |
118
+ | `logLevel` | `"silent"` | Log threshold |
119
+ | `debug` | migration only | `debug: true` maps to `logLevel: "debug"` |
120
+
121
+ pi-side commands: `/qq-login`, `/qq-status`, `/qq-logout`, `/qq-test-budget`, `/qq-test-md`, `/qq-test-stream`, `/qq-new`.
122
+
123
+ QQ-side commands: `/new`, `/stop`, `/compact`, `/status`, `/help`.
124
+
125
+ ## 6. Modules and boundaries (v1 baseline)
126
+
127
+ <!-- prettier-ignore -->
128
+ | Module | Responsibility |
129
+ | ---------------------------- | ----------------------------------------------------------- |
130
+ | `index.ts` | Extension wiring, event subscriptions, command registration |
131
+ | `src/infra/settings.ts` | Read-only settings and migration |
132
+ | `src/qq/qr-login.ts` | QR login |
133
+ | `src/qq/qq-bot.ts` | QQBot lifecycle, Gateway state, middleware |
134
+ | `src/qq/qq-message-handler.ts` | Inbound routing, commands, attachments, injection into pi |
135
+ | `src/attachments/image-attachments.ts` | Image validation and `ImageContent` |
136
+ | `src/attachments/file-attachments.ts` | File storage, index, prompt attachment |
137
+ | `src/attachments/attachment-download.ts` | Shared limited download for images/files |
138
+ | `src/qq/reply-sender.ts` | Markdown conversion, chunking, sending |
139
+ | `src/quota/reply-quota.ts` | Passive reply quota |
140
+ | `src/quota/reply-quota-report.ts` | Quota diagnostics formatting |
141
+ | `src/infra/display-format.ts` | Byte and token formatting |
142
+ | `src/infra/file-logger.ts` | File logging |
143
+ | `src/relay/run-stream-relay.ts` | Long-task feedback state machine |
144
+ | `src/relay/stream-session.ts` | Stream append, retries, checkpoint resume |
145
+
146
+ Boundary rules: the entrypoint only wires modules; protocol, storage, formatting, and quota are separate; modules communicate through explicit parameters and interfaces such as `RunFeedbackDeps`.
147
+
148
+ ## 7. Verification
149
+
150
+ - QR login, `/qq-status`, and `/qq-logout` verified on real QQ.
151
+ - QQ text starts pi and the reply comes back.
152
+ - Images as vision input, file storage, and prompt path association verified.
153
+ - Passive reply quota stayed within limits; failure paths fell back to proactive sends.
154
+
155
+ ## 8. Known limitations
156
+
157
+ - C2C private chat only.
158
+ - Credentials live in process memory; restarting pi requires scanning again.
159
+ - No start acknowledgement or usage summary, reducing passive messages.
160
+ - Historical stream/heartbeat behavior was replaced by v3 and is not current behavior.
@@ -0,0 +1,100 @@
1
+ # pi-qq delivery-v2
2
+
3
+ > 状态:v2 已交付。
4
+ > 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md);后续版本:[delivery-v3-zh.md](./delivery-v3-zh.md)。
5
+
6
+ ## 1. 交付范围
7
+
8
+ v2 在 v1 的 QQ 私聊、图片和文件能力上增加:
9
+
10
+ - F8 语音消息自动转写;
11
+ - F9 结构化日志基础设施;
12
+ - F10 文件消息等待下一条指令;
13
+ - F11 文件保存路径、索引和去重。
14
+
15
+ ## 2. 功能
16
+
17
+ ### F8 语音消息
18
+
19
+ - 使用 QQ 内置 ASR(`asr_refer_text`),不下载音频。
20
+ - 转写文本作为普通用户文本交给 pi。
21
+ - ASR 无结果时回复 `Could not transcribe this voice message; please resend or type it.`,不启动 run。
22
+ - 不依赖本地或外部语音识别服务。
23
+ - 原始 ASR 结果和附件元数据只在 `debug` 日志中记录。
24
+
25
+ ### F9 日志
26
+
27
+ - 按天写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。
28
+ - `PI_QQ_LOG_DIR` 可覆盖目录。
29
+ - 阈值:`silent`、`error`、`warn`、`info`、`debug`。
30
+ - `info` 只记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。
31
+ - 日志 JSONL 化,错误对象带名称、消息和堆栈。
32
+ - 旧配置 `debug: true` 映射为 `logLevel: "debug"`。
33
+
34
+ ### F10 文件等待指令
35
+
36
+ - 只发送文件不会启动 pi;文件先保存并进入 pending。
37
+ - 下一条文字或语音指令会消费 pending 文件,并在提示词中附带路径、大小和原始文件名。
38
+ - 指令前上传多个文件会合并到同一个提示词。
39
+ - `/new` 清空 pending。
40
+ - 文件按当前 pi 会话隔离。
41
+
42
+ ### F11 文件存储与去重
43
+
44
+ - 保存在当前工作区 `.pi/pi-qq/<sessionId>/uploads/`。
45
+ - 同名同内容复用已有文件。
46
+ - 同名不同内容保存为 `name-1.ext`。
47
+ - 不同名同内容分别保存。
48
+ - 索引记录路径、大小、哈希和原始文件名;启动时清理失效索引。
49
+ - pending 文件与索引解耦,`/new` 不影响已保存的索引文件。
50
+
51
+ ## 3. 配置
52
+
53
+ v2 继续使用:
54
+
55
+ | 配置 | 默认 | 说明 |
56
+ | --------------- | ---------- | -------------------- |
57
+ | `thinkingRelay` | `true` | 思考正文回传开关 |
58
+ | `deliverAs` | `"steer"` | 忙碌时的消息排队方式 |
59
+ | `imageMaxSize` | 10MB | 图片下载上限 |
60
+ | `fileMaxSize` | 50MB | 文件下载上限 |
61
+ | `logLevel` | `"silent"` | 日志阈值 |
62
+ | `debug` | 仅迁移读取 | 旧日志开关迁移 |
63
+
64
+ ## 4. 模块与边界
65
+
66
+ <!-- prettier-ignore -->
67
+ | 模块 | 职责 |
68
+ | ---------------------------- | ------------------------------------ |
69
+ | `src/qq/qq-message-handler.ts` | 语音/文件/文本统一入站路由;命令拦截 |
70
+ | `src/attachments/voice-transcript.ts` | ASR 文本提取与可用性判断 |
71
+ | `src/attachments/file-attachments.ts` | 文件保存、哈希、索引、pending 提示词 |
72
+ | `src/attachments/attachment-download.ts` | 图片和文件共用下载约束 |
73
+ | `src/attachments/image-attachments.ts` | 图片校验与视觉输入组装 |
74
+ | `src/infra/file-logger.ts` | 日志级别、格式化、按天写入 |
75
+ | `src/qq/reply-sender.ts` | Markdown 转换、分块、发送 |
76
+ | `src/quota/reply-quota.ts` | 被动回复预算 |
77
+
78
+ 边界原则:
79
+
80
+ - `qq-message-handler` 只负责路由,不自行实现下载或存储细节;
81
+ - `voice-transcript` 不接触文件系统;
82
+ - `file-attachments` 负责保存和索引,不负责 pi 事件;
83
+ - `file-logger` 不依赖业务模块;
84
+ - 所有附件下载都经过 `attachment-download.ts`,避免超时和大小限制分叉。
85
+
86
+ ## 5. 验证
87
+
88
+ - 语音 ASR 文本注入、无文本提示、音频不落盘;
89
+ - 纯文件消息不启动 run,下一条指令消费文件;
90
+ - 多文件合并、`/new` 清空 pending;
91
+ - 同名同内容复用、同名不同内容加后缀、不同名同内容独立保存;
92
+ - 日志目录、级别、JSONL 字段和旧 `debug` 迁移;
93
+ - 自动化和实机测试通过。
94
+
95
+ ## 6. 已知限制
96
+
97
+ - 仅使用 QQ ASR,不提供本地识别兜底。
98
+ - ASR 不返回文本时只能重发或改文字。
99
+ - 文件等待指令按当前 pi 会话隔离。
100
+ - 日志的 `debug` 级别会包含敏感工具参数和文件内容,只在排查问题时开启。