@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.
- package/README-zh.md +76 -46
- package/README.md +79 -49
- 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 +189 -0
- package/doc/delivery-v3.md +189 -0
- package/index.ts +66 -156
- package/package.json +6 -3
- package/src/{download.ts → attachments/attachment-download.ts} +1 -4
- package/src/attachments/attachment-failure.ts +12 -0
- package/src/{files.ts → attachments/file-attachments.ts} +19 -33
- 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 -31
- package/src/infra/settings.ts +103 -0
- package/src/{bot.ts → qq/qq-bot.ts} +6 -31
- package/src/qq/qq-diagnostics.ts +129 -0
- package/src/{inbound.ts → qq/qq-message-handler.ts} +58 -94
- package/src/{login.ts → qq/qr-login.ts} +24 -17
- package/src/{outbound.ts → qq/reply-sender.ts} +7 -37
- 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 +576 -0
- package/src/relay/stream-block-format.ts +117 -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/images.ts +0 -149
- package/src/run-feedback.ts +0 -409
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# pi-qq delivery-v1
|
|
2
|
+
|
|
3
|
+
> Status: v1 delivered; this is a historical baseline for later versions.
|
|
4
|
+
> Current behavior is documented in [README](../README.md); 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>/`; v2+ uses the session-scoped `.pi/pi-qq/<sessionId>/uploads/`. 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 hour (SDK limiter) | `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
|
+
> 当前行为以 [README-zh.md](../README-zh.md) 为准;前序版本:[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` 级别会包含敏感工具参数和文件内容,只在排查问题时开启。
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# pi-qq delivery-v2
|
|
2
|
+
|
|
3
|
+
> Status: v2 delivered; this is a historical record.
|
|
4
|
+
> Current behavior is documented in [README](../README.md); previous: [delivery-v1.md](./delivery-v1.md); next: [delivery-v3.md](./delivery-v3.md).
|
|
5
|
+
|
|
6
|
+
## 1. Scope
|
|
7
|
+
|
|
8
|
+
v2 adds to v1's QQ chat, image, and file support:
|
|
9
|
+
|
|
10
|
+
- F8 voice-message transcription;
|
|
11
|
+
- F9 structured logging;
|
|
12
|
+
- F10 file-only messages waiting for the next instruction;
|
|
13
|
+
- F11 upload paths, index, and deduplication.
|
|
14
|
+
|
|
15
|
+
## 2. Features
|
|
16
|
+
|
|
17
|
+
### F8 Voice messages
|
|
18
|
+
|
|
19
|
+
- Use QQ built-in ASR (`asr_refer_text`); never download the audio.
|
|
20
|
+
- Send the transcript to pi as ordinary user text.
|
|
21
|
+
- If ASR returns no text, reply `Could not transcribe this voice message; please resend or type it.` and do not start a run.
|
|
22
|
+
- No local or external speech-to-text service is used.
|
|
23
|
+
- Raw ASR results and attachment metadata are only written at `debug` level.
|
|
24
|
+
|
|
25
|
+
### F9 Logging
|
|
26
|
+
|
|
27
|
+
- Write daily files to `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`.
|
|
28
|
+
- `PI_QQ_LOG_DIR` can override the directory.
|
|
29
|
+
- Thresholds: `silent`, `error`, `warn`, `info`, `debug`.
|
|
30
|
+
- `info` records metadata only; `debug` records full events, attachments, prompts, and tool payloads.
|
|
31
|
+
- Logs are JSONL; errors include name, message, and stack.
|
|
32
|
+
- Legacy `debug: true` maps to `logLevel: "debug"`.
|
|
33
|
+
|
|
34
|
+
### F10 File-only messages
|
|
35
|
+
|
|
36
|
+
- A file-only message does not start pi; the file is saved and becomes pending.
|
|
37
|
+
- The next text or voice instruction consumes pending files and includes paths, sizes, and original filenames in the prompt.
|
|
38
|
+
- Multiple files uploaded before an instruction are merged into one prompt.
|
|
39
|
+
- `/new` clears pending files.
|
|
40
|
+
- Pending files are scoped to the current pi session.
|
|
41
|
+
|
|
42
|
+
### F11 Upload storage and deduplication
|
|
43
|
+
|
|
44
|
+
- Saved under the current workspace at `.pi/pi-qq/<sessionId>/uploads/`.
|
|
45
|
+
- Same name and same content reuses the existing file.
|
|
46
|
+
- Same name and different content is saved as `name-1.ext`.
|
|
47
|
+
- Different names with identical content are saved separately.
|
|
48
|
+
- The index maps filenames to hashes only; paths and sizes come from the filesystem. Stale index entries are pruned on startup.
|
|
49
|
+
- Pending files are independent from the index; `/new` does not delete saved indexed files.
|
|
50
|
+
|
|
51
|
+
## 3. Settings
|
|
52
|
+
|
|
53
|
+
| Setting | Default | Description |
|
|
54
|
+
| --------------- | -------------- | --------------------------- |
|
|
55
|
+
| `thinkingRelay` | `true` | Relay thinking text |
|
|
56
|
+
| `deliverAs` | `"steer"` | Queue behavior while busy |
|
|
57
|
+
| `imageMaxSize` | 10MB | Image download limit |
|
|
58
|
+
| `fileMaxSize` | 50MB | File download limit |
|
|
59
|
+
| `logLevel` | `"silent"` | Log threshold |
|
|
60
|
+
| `debug` | migration only | Legacy log switch migration |
|
|
61
|
+
|
|
62
|
+
## 4. Modules and boundaries
|
|
63
|
+
|
|
64
|
+
<!-- prettier-ignore -->
|
|
65
|
+
| Module | Responsibility |
|
|
66
|
+
| ---------------------------- | ------------------------------------------------------------- |
|
|
67
|
+
| `src/qq/qq-message-handler.ts` | Unified voice/file/text inbound routing; command interception |
|
|
68
|
+
| `src/attachments/voice-transcript.ts` | ASR text extraction and availability |
|
|
69
|
+
| `src/attachments/file-attachments.ts` | File storage, hashes, index, pending-file prompt |
|
|
70
|
+
| `src/attachments/attachment-download.ts` | Shared download limits for images and files |
|
|
71
|
+
| `src/attachments/image-attachments.ts` | Image validation and vision input assembly |
|
|
72
|
+
| `src/infra/file-logger.ts` | Log levels, formatting, daily file output |
|
|
73
|
+
| `src/qq/reply-sender.ts` | Markdown conversion, chunking, sending |
|
|
74
|
+
| `src/quota/reply-quota.ts` | Passive reply quota |
|
|
75
|
+
|
|
76
|
+
Boundary rules:
|
|
77
|
+
|
|
78
|
+
- `qq-message-handler` only routes; it does not implement download or storage details.
|
|
79
|
+
- `voice-transcript` never touches the filesystem.
|
|
80
|
+
- `file-attachments` handles storage and indexing, not pi events.
|
|
81
|
+
- `file-logger` does not depend on business modules.
|
|
82
|
+
- All attachment downloads go through `attachment-download.ts` so timeouts and size limits do not diverge.
|
|
83
|
+
|
|
84
|
+
## 5. Verification
|
|
85
|
+
|
|
86
|
+
- Voice ASR text injection, empty-ASR prompting, and no audio persistence.
|
|
87
|
+
- File-only messages do not start a run; the next instruction consumes the files.
|
|
88
|
+
- Multiple pending files merge; `/new` clears pending files.
|
|
89
|
+
- Same-name/same-content reuse, same-name/different-content suffixing, and different-name/same-content separation.
|
|
90
|
+
- Log directory, levels, JSONL fields, and legacy `debug` migration.
|
|
91
|
+
- Automated tests and real QQ verification passed.
|
|
92
|
+
|
|
93
|
+
## 6. Known limitations
|
|
94
|
+
|
|
95
|
+
- Only QQ ASR is used; there is no local speech-recognition fallback.
|
|
96
|
+
- If ASR returns no text, the user must resend or type the message.
|
|
97
|
+
- Pending files are scoped to the current pi session.
|
|
98
|
+
- `debug` logs can contain sensitive tool payloads and file contents; enable only while troubleshooting.
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
# pi-qq delivery-v3
|
|
2
|
+
|
|
3
|
+
> 状态:v3 已实现并完成主链路真机验证;按块切泡、错误恢复、列表切分等最终细节仍需在目标 QQ 客户端做一次完整复验。
|
|
4
|
+
> 说明:后续变更删除了图片专用链路,图片与文件共用保存/pending 流程。当前行为见 [README-zh.md](../README-zh.md)。
|
|
5
|
+
> 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md)、[delivery-v2-zh.md](./delivery-v2-zh.md)。
|
|
6
|
+
|
|
7
|
+
## 1. 交付范围
|
|
8
|
+
|
|
9
|
+
v3 收敛长任务回传与配置:
|
|
10
|
+
|
|
11
|
+
- F12:事件直推,思考、工具、文本按块回传;
|
|
12
|
+
- F13:移除消息心跳;
|
|
13
|
+
- F14:配置项收敛。
|
|
14
|
+
|
|
15
|
+
## 2. 输出模型
|
|
16
|
+
|
|
17
|
+
### 2.1 每个内容块一个气泡
|
|
18
|
+
|
|
19
|
+
按时间顺序:
|
|
20
|
+
|
|
21
|
+
1. 思考块;
|
|
22
|
+
2. 每个工具调用 + 结果;
|
|
23
|
+
3. 文本块;
|
|
24
|
+
4. 最终消息。
|
|
25
|
+
|
|
26
|
+
工具未完成时,后续思考/文本暂存,避免思考插入两个工具泡之间。并行工具按开始顺序逐个展示,结果通过 `toolCallId` 归属。
|
|
27
|
+
|
|
28
|
+
### 2.2 思考格式
|
|
29
|
+
|
|
30
|
+
每个思考泡首行:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
**💭 思考**
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
正文为纯文本,不加 `>` 引用前缀,空行和换行原样保留。达到 12k 安全边界时主动切泡,新泡重复标题。
|
|
37
|
+
|
|
38
|
+
不使用引用块的原因:QQ 会把单行/空行引用块渲染为不支持的消息;纯文本 + 标题可稳定显示。
|
|
39
|
+
|
|
40
|
+
### 2.3 工具格式
|
|
41
|
+
|
|
42
|
+
````text
|
|
43
|
+
**<图标> <工具名>**
|
|
44
|
+
|
|
45
|
+
`参数`
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
输出
|
|
49
|
+
````
|
|
50
|
+
|
|
51
|
+
````
|
|
52
|
+
|
|
53
|
+
失败结果首行:
|
|
54
|
+
|
|
55
|
+
```text
|
|
56
|
+
❌ ...
|
|
57
|
+
````
|
|
58
|
+
|
|
59
|
+
每个工具调用独立气泡;工具名、参数和结果不拆开。
|
|
60
|
+
|
|
61
|
+
固定图标映射:
|
|
62
|
+
|
|
63
|
+
| 工具 | 图标 | 工具 | 图标 |
|
|
64
|
+
| -------- | ---- | ---------- | ---- |
|
|
65
|
+
| `bash` | 💻 | `read` | 📖 |
|
|
66
|
+
| `write` | 📝 | `edit` | ✏️ |
|
|
67
|
+
| `grep` | 🔎 | `search` | 🔍 |
|
|
68
|
+
| `find` | 🗂️ | `ls` | 📁 |
|
|
69
|
+
| `list` | 📋 | `web` | 🌐 |
|
|
70
|
+
| `fetch` | 📡 | `delete` | 🗑️ |
|
|
71
|
+
| `remove` | ❌ | `todo` | ✅ |
|
|
72
|
+
| `test` | 🧪 | 未配置工具 | 🔧 |
|
|
73
|
+
|
|
74
|
+
图标硬编码在 `src/relay/stream-block-format.ts`,不增加配置项。
|
|
75
|
+
|
|
76
|
+
### 2.4 文本与普通消息
|
|
77
|
+
|
|
78
|
+
assistant 文本按原文流式追加,不额外加标题。文本块和工具块之间通过气泡边界区分。
|
|
79
|
+
|
|
80
|
+
## 3. 切泡与流式传输
|
|
81
|
+
|
|
82
|
+
- 每个 run 默认多泡,但每个泡只承载一个内容块。
|
|
83
|
+
- 单块累计达到 `MAX_BUBBLE_CHARS = 12_000` 时,在安全边界切泡:
|
|
84
|
+
- 块边界或行首;
|
|
85
|
+
- 没有未闭合代码围栏;
|
|
86
|
+
- 没有待续写检查点;
|
|
87
|
+
- 没有进行中的工具。
|
|
88
|
+
- 思考切泡优先保证列表/行结构,不在行中间强制截断。
|
|
89
|
+
- 工具参数行与结果代码块始终在同一泡。
|
|
90
|
+
- `AppendStream` 负责 300ms 平台下限、500ms 默认合帧、429/50002 退避和同泡续写。
|
|
91
|
+
- `index` 每次发送尝试递增;失败帧的未确认缓冲用下一个 index 重发。
|
|
92
|
+
- 超过 5 分钟或平台拒绝时,最终文本通过普通消息路径补发。
|
|
93
|
+
|
|
94
|
+
## 4. 中断与错误恢复
|
|
95
|
+
|
|
96
|
+
### 4.1 `/stop`
|
|
97
|
+
|
|
98
|
+
`/stop` 的流程:
|
|
99
|
+
|
|
100
|
+
1. 取消错误恢复目标;
|
|
101
|
+
2. abort agent;
|
|
102
|
+
3. 等待 `agent_end` 完成当前流、工具结果和 DONE;
|
|
103
|
+
4. 回复 `Abort requested.`。
|
|
104
|
+
|
|
105
|
+
因此已启动的工具结果不会因为 `/stop` 丢失,也不会在 Abort requested 之后继续冒出排队工具泡。
|
|
106
|
+
|
|
107
|
+
### 4.2 模型错误恢复
|
|
108
|
+
|
|
109
|
+
- 模型错误结束时保留原 QQ 目标 60 秒。
|
|
110
|
+
- pi 自动恢复/重试产生的新 run 会沿用同一 `msgId` 继续推送。
|
|
111
|
+
- 没有输出的空重试不会消耗恢复目标;下一次重试仍可继续。
|
|
112
|
+
- 新 QQ 消息或 `/stop` 取消恢复。
|
|
113
|
+
- 恢复目标内的本地 run 也可能被回传,这是为了延续 pi 自动恢复行为的明确取舍。
|
|
114
|
+
|
|
115
|
+
## 5. 配置
|
|
116
|
+
|
|
117
|
+
`~/.pi/agent/pi-qq.json` 只保存设置,不保存凭据。
|
|
118
|
+
|
|
119
|
+
| 配置 | 默认 | 说明 |
|
|
120
|
+
| --------------- | ---------- | ---------------------------------------- |
|
|
121
|
+
| `thinkingRelay` | `true` | 是否回传纯文本思考块 |
|
|
122
|
+
| `deliverAs` | `"steer"` | 忙碌时新消息排队方式 |
|
|
123
|
+
| `imageMaxSize` | 10MB | 图片下载上限 |
|
|
124
|
+
| `fileMaxSize` | 50MB | 文件下载上限 |
|
|
125
|
+
| `logLevel` | `"silent"` | 日志阈值 |
|
|
126
|
+
| `debug` | 仅迁移读取 | `debug: true` 映射为 `logLevel: "debug"` |
|
|
127
|
+
|
|
128
|
+
已删除配置:`streamRelay`、`streamFlushMs`、`streamAssistant`、`markdownSupport`、`heartbeatMinutes`、`heartbeatMaxMessages`。旧键静默忽略,不写回。
|
|
129
|
+
|
|
130
|
+
## 6. 模块分布与边界
|
|
131
|
+
|
|
132
|
+
当前代码按职责分层:
|
|
133
|
+
|
|
134
|
+
<!-- prettier-ignore -->
|
|
135
|
+
| 模块 | 职责 |
|
|
136
|
+
| ---------------------------- | -------------------------------------------- |
|
|
137
|
+
| `index.ts` | 扩展装配、pi 事件订阅、登录/会话命令 |
|
|
138
|
+
| `src/qq/qq-diagnostics.ts` | 终端协议诊断(`/qq-test-*`) |
|
|
139
|
+
| `src/qq/qq-message-handler.ts` | QQ 入站路由、命令、附件、注入 pi |
|
|
140
|
+
| `src/qq/reply-sender.ts` | Markdown 转纯文本、分块、消息发送 |
|
|
141
|
+
| `src/relay/run-stream-relay.ts` | 内容块编排、气泡生命周期、工具队列、错误恢复 |
|
|
142
|
+
| `src/relay/stream-block-format.ts` | 思考标题、工具图标、参数/结果纯格式化 |
|
|
143
|
+
| `src/relay/stream-session.ts` | 流式帧、节流、重试、续写检查点 |
|
|
144
|
+
| `src/quota/reply-quota.ts` | 被动回复预算与 `msgId` 窗口 |
|
|
145
|
+
| `src/quota/reply-quota-report.ts` | 预算诊断文本 |
|
|
146
|
+
| `src/infra/settings.ts` | 配置读取与旧键迁移 |
|
|
147
|
+
| `src/qq/qq-bot.ts` | QQBot/Gateway 生命周期和中间件 |
|
|
148
|
+
| `src/qq/qr-login.ts` | 扫码登录 |
|
|
149
|
+
| `src/attachments/file-attachments.ts` | 文件保存、索引、去重、pending |
|
|
150
|
+
| `src/attachments/image-attachments.ts` | 图片校验与视觉输入 |
|
|
151
|
+
| `src/attachments/attachment-download.ts` | 图片/文件通用限流下载 |
|
|
152
|
+
| `src/attachments/voice-transcript.ts` | QQ ASR 文本提取 |
|
|
153
|
+
| `src/infra/file-logger.ts` | 结构化文件日志 |
|
|
154
|
+
| `src/infra/display-format.ts` | 字节/token 通用格式化 |
|
|
155
|
+
|
|
156
|
+
边界原则:
|
|
157
|
+
|
|
158
|
+
- `index.ts` 不承载回传状态机;
|
|
159
|
+
- `stream-block-format.ts` 只做纯格式化,不依赖流对象;
|
|
160
|
+
- `run-stream-relay.ts` 只做编排,不直接拼 Markdown 细节;
|
|
161
|
+
- `stream-session.ts` 不感知内容块语义;
|
|
162
|
+
- `qq-message-handler.ts` 不实现下载、存储或预算;
|
|
163
|
+
- 所有配置通过 `settings.ts`,不散落在业务模块;
|
|
164
|
+
- 每个模块都有独立测试或可从入口注入依赖。
|
|
165
|
+
|
|
166
|
+
## 7. 验证
|
|
167
|
+
|
|
168
|
+
- v3 交付时单元测试:**135 passed**(14 个测试文件)。
|
|
169
|
+
- TypeScript、ESLint 和 Prettier 检查通过。
|
|
170
|
+
- 真机已验证:
|
|
171
|
+
- C2C 登录、文本、图片、文件;
|
|
172
|
+
- 思考/工具/文本按块展示;
|
|
173
|
+
- 工具行与结果同泡;
|
|
174
|
+
- 12k 切泡与标题重复;
|
|
175
|
+
- `/stop` 收尾、模型错误后的自动恢复。
|
|
176
|
+
- 仍需最终复验:
|
|
177
|
+
- 目标客户端上的长列表切分;
|
|
178
|
+
- 极端长代码围栏;
|
|
179
|
+
- 错误恢复目标 TTL 接近边界的情况;
|
|
180
|
+
- 并行工具较多时的消息额度。
|
|
181
|
+
|
|
182
|
+
## 8. 风险与限制
|
|
183
|
+
|
|
184
|
+
- 每个内容块一泡会增加消息数;长任务需关注被动额度。
|
|
185
|
+
- 12k 切泡依赖状态,极端单行/未闭合围栏仍可能落到平台自动切分。
|
|
186
|
+
- 工具图标是硬编码 Emoji,不同 QQ 客户端字体可能略有差异。
|
|
187
|
+
- 恢复目标是 60 秒 TTL;超过窗口后不再自动续传。
|
|
188
|
+
- 仅支持 C2C 私聊;登录凭据只在进程内存。
|
|
189
|
+
- 最终文本在流式失败时走普通消息路径,可能重复已显示的部分,优先保证完整。
|