@chen_hu_hu/pi-qq 1.3.0 → 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 +67 -47
- package/README.md +70 -50
- package/doc/delivery-v1-zh.md +9 -9
- package/doc/delivery-v1.md +4 -4
- package/doc/delivery-v2-zh.md +3 -3
- package/doc/delivery-v2.md +3 -3
- package/doc/delivery-v3-zh.md +4 -2
- package/doc/delivery-v3.md +4 -2
- package/index.ts +36 -131
- package/package.json +4 -1
- package/src/attachments/attachment-failure.ts +12 -0
- package/src/attachments/file-attachments.ts +16 -19
- package/src/infra/file-logger.ts +0 -3
- package/src/infra/settings.ts +62 -8
- package/src/qq/qq-bot.ts +2 -2
- package/src/qq/qq-diagnostics.ts +129 -0
- package/src/qq/qq-message-handler.ts +51 -74
- package/src/qq/qr-login.ts +4 -1
- package/src/qq/reply-sender.ts +5 -4
- package/src/relay/run-stream-relay.ts +8 -18
- package/src/relay/stream-block-format.ts +7 -4
- package/src/attachments/image-attachments.ts +0 -142
package/README-zh.md
CHANGED
|
@@ -2,7 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
[English](./README.md) | 简体中文
|
|
4
4
|
|
|
5
|
-
将 [pi](https://github.com/earendil-works/pi) 接入 QQ
|
|
5
|
+
将 [pi](https://github.com/earendil-works/pi) 接入 QQ 私聊。在 QQ 上发送文字、语音、图片或文件,pi 在你的电脑上工作,并把结果发回 QQ。
|
|
6
|
+
|
|
7
|
+
## 环境要求
|
|
8
|
+
|
|
9
|
+
- Node.js 22.19 或更高版本,与 pi 保持一致。
|
|
10
|
+
- 已启用 C2C 私聊能力的 QQ 机器人应用。
|
|
11
|
+
- 可用的 pi 环境。
|
|
6
12
|
|
|
7
13
|
## 安装
|
|
8
14
|
|
|
@@ -30,34 +36,28 @@ pi --extension /path/to/pi-qq
|
|
|
30
36
|
|
|
31
37
|
- **文字**:普通聊天消息。
|
|
32
38
|
- **语音**:直接使用 QQ 内置 ASR 文本;音频不会下载或保存。如果 ASR 没有返回文本,机器人会提示你重发或改用文字。
|
|
33
|
-
-
|
|
34
|
-
- **文件**:保存到当前工作区的 `.pi/pi-qq/<sessionId>/uploads/`,并等待你的下一条指令。
|
|
39
|
+
- **图片和文件**:保存到 `.pi/pi-qq/<sessionId>/uploads/`。如果消息中没有指令,pi 会等待你的下一条文字或语音消息。
|
|
35
40
|
|
|
36
|
-
|
|
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` 会等待当前工具和流收尾后再回复。
|
|
41
|
+
QQ 客户端对混合消息的支持不同。手机 QQ 通常一次只发一种类型,桌面版 QQ 可以发送“文字 + 图片”。当客户端把文字/语音和附件放在同一条消息里时,pi-qq 会把它们合并到同一个提示词中处理。
|
|
43
42
|
|
|
44
|
-
###
|
|
43
|
+
### 附件
|
|
45
44
|
|
|
46
|
-
|
|
45
|
+
**只发送附件不会启动 pi。** 文件和图片会先保存,pi 等待下一条文字或语音指令后再处理。
|
|
47
46
|
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
47
|
+
- 先上传一个或多个文件或图片,再发送文字或语音说明要做什么。
|
|
48
|
+
- 下一条指令会包含保存后的附件路径。
|
|
49
|
+
- 指令到达前上传的多个附件会合并到同一个提示词中。
|
|
50
|
+
- 图片通过 pi 的 `read` 工具查看,因此当前模型必须支持图片输入才能看到内容。
|
|
51
|
+
- `/new` 会清空等待指令的附件。
|
|
52
|
+
- 附件按当前 pi 会话隔离。相同文件名且内容相同会复用已有文件;相同文件名但内容不同会保存为 `name-1.ext`;不同文件名但内容相同会分别保存。
|
|
53
53
|
|
|
54
|
-
pi
|
|
54
|
+
pi 看到的提示词示例:
|
|
55
55
|
|
|
56
56
|
```text
|
|
57
|
-
|
|
58
|
-
-
|
|
57
|
+
# Attachments:
|
|
58
|
+
- .pi/pi-qq/<sessionId>/uploads/report.pdf
|
|
59
59
|
|
|
60
|
-
User message:
|
|
60
|
+
# User message:
|
|
61
61
|
Summarize this file.
|
|
62
62
|
```
|
|
63
63
|
|
|
@@ -69,21 +69,28 @@ Summarize this file.
|
|
|
69
69
|
- 不使用本地或外部语音识别服务。
|
|
70
70
|
- 如果 QQ ASR 没有返回文本,机器人会回复 `Could not transcribe this voice message; please resend or type it.`,并且不会启动 pi。
|
|
71
71
|
- 语音和文字是两条独立的 QQ 消息;需要时按顺序发送。
|
|
72
|
-
-
|
|
72
|
+
- 如果客户端允许语音消息同时携带文件或图片,它们会与转写文本一起处理。
|
|
73
|
+
|
|
74
|
+
将 `logLevel` 设为 `debug` 时,日志会包含原始 `asr_refer_text` 和附件元数据。
|
|
75
|
+
|
|
76
|
+
### 回复格式
|
|
77
|
+
|
|
78
|
+
- **思考**:独立气泡,纯文本,首行 `**💭 思考**`。长思考可能续到新气泡,并重复标题。
|
|
79
|
+
- **工具**:每次调用独立气泡,首行 `**<图标> <工具名>**`,空行,参数行内代码,空行,结果 `text` 代码块。
|
|
80
|
+
- **普通消息**:原文,不加标题。
|
|
81
|
+
- **工具图标**:💻 bash、📖 read、📝 write、✏️ edit、🔎 grep、🔍 search、🗂️ find、📁 ls、📋 list、🌐 web、📡 fetch、🗑️ delete、❌ remove、✅ todo、🧪 test;未配置工具使用 🔧。
|
|
82
|
+
- **错误恢复**:模型错误后 60 秒内自动恢复的 run 会继续推送到原 QQ 会话;`/stop` 会等待当前工具和流收尾后再回复。
|
|
73
83
|
|
|
74
84
|
## 命令
|
|
75
85
|
|
|
76
86
|
在 pi 终端执行:
|
|
77
87
|
|
|
78
|
-
| 命令
|
|
79
|
-
|
|
|
80
|
-
| `/qq-login`
|
|
81
|
-
| `/qq-status`
|
|
82
|
-
| `/qq-logout`
|
|
83
|
-
| `/qq-
|
|
84
|
-
| `/qq-test-md [text]` | 发送 Markdown 测试消息 |
|
|
85
|
-
| `/qq-test-stream` | 运行流式时间线诊断(`resume` 验证续写) |
|
|
86
|
-
| `/qq-new` | 重置当前会话(由 QQ 侧 `/new` 调用) |
|
|
88
|
+
| 命令 | 说明 |
|
|
89
|
+
| ------------ | -------------------------------------- |
|
|
90
|
+
| `/qq-login` | 扫码登录并绑定扫码的 QQ 用户 |
|
|
91
|
+
| `/qq-status` | 显示登录、连接、模型、上下文和绑定用户 |
|
|
92
|
+
| `/qq-logout` | 退出登录并清除内存中的凭据 |
|
|
93
|
+
| `/qq-new` | 重置当前会话(由 QQ 侧 `/new` 调用) |
|
|
87
94
|
|
|
88
95
|
QQ 侧命令:
|
|
89
96
|
|
|
@@ -95,6 +102,16 @@ QQ 侧命令:
|
|
|
95
102
|
| `/status` | 显示会话和上下文状态 |
|
|
96
103
|
| `/help` | 显示命令帮助 |
|
|
97
104
|
|
|
105
|
+
### 诊断
|
|
106
|
+
|
|
107
|
+
以下终端命令用于排查问题:
|
|
108
|
+
|
|
109
|
+
| 命令 | 说明 |
|
|
110
|
+
| -------------------- | --------------------------------------- |
|
|
111
|
+
| `/qq-test-budget` | 显示被动回复额度和流式气泡诊断信息 |
|
|
112
|
+
| `/qq-test-md [text]` | 发送 Markdown 测试消息 |
|
|
113
|
+
| `/qq-test-stream` | 运行流式时间线诊断(`resume` 验证续写) |
|
|
114
|
+
|
|
98
115
|
## 设置
|
|
99
116
|
|
|
100
117
|
创建 `~/.pi/agent/pi-qq.json` 覆盖默认值。该文件只保存设置;凭据不会写入其中。
|
|
@@ -110,15 +127,14 @@ QQ 侧命令:
|
|
|
110
127
|
| --------------- | ---------- | ------------------------------------------------------ |
|
|
111
128
|
| `thinkingRelay` | `true` | 以 `💭 思考` 标题的纯文本回传思考;`false` 时隐藏 |
|
|
112
129
|
| `deliverAs` | `"steer"` | 忙碌时新消息的排队方式:`steer` 或 `followUp` |
|
|
113
|
-
| `
|
|
114
|
-
| `fileMaxSize` | `52428800` | QQ 文件下载上限(字节,50MB) |
|
|
130
|
+
| `fileMaxSize` | `52428800` | QQ 附件下载上限(字节,50MB) |
|
|
115
131
|
| `logLevel` | `"silent"` | 日志阈值:`silent`、`error`、`warn`、`info` 或 `debug` |
|
|
116
132
|
|
|
117
|
-
|
|
133
|
+
配置在 pi 会话启动时读取;修改文件后请重启 pi。未知配置项会被忽略,无效值会回退到默认值并给出提示。
|
|
118
134
|
|
|
119
|
-
|
|
135
|
+
启用日志后,日志写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。可用 `PI_QQ_LOG_DIR` 覆盖目录。`info` 只记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。
|
|
120
136
|
|
|
121
|
-
|
|
137
|
+
## 开发
|
|
122
138
|
|
|
123
139
|
```bash
|
|
124
140
|
npm ci
|
|
@@ -128,20 +144,24 @@ npm test
|
|
|
128
144
|
npm run format:check
|
|
129
145
|
```
|
|
130
146
|
|
|
131
|
-
`
|
|
132
|
-
|
|
133
|
-
### 文件命名
|
|
147
|
+
扩展入口是 `index.ts`。源码按职责分组:
|
|
134
148
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
149
|
+
| 目录 | 职责 |
|
|
150
|
+
| ------------------ | ------------------------------------- |
|
|
151
|
+
| `src/qq/` | QQ bot 生命周期、登录、入站处理和回复 |
|
|
152
|
+
| `src/relay/` | 思考/工具/文本的流式回传 |
|
|
153
|
+
| `src/attachments/` | 附件下载、存储和语音转写 |
|
|
154
|
+
| `src/quota/` | 被动回复额度 |
|
|
155
|
+
| `src/infra/` | 配置、日志和显示格式化 |
|
|
140
156
|
|
|
141
157
|
## 说明
|
|
142
158
|
|
|
143
159
|
- 仅支持 C2C(QQ 私聊)。
|
|
144
|
-
- QQ 入站消息触发的任务会回传 QQ
|
|
145
|
-
-
|
|
146
|
-
-
|
|
160
|
+
- QQ 入站消息触发的任务会回传 QQ;直接在 pi 中启动的无关任务不会推送。
|
|
161
|
+
- 图片会保存为文件,并通过 pi 的 `read` 工具查看;当前模型必须支持图片输入才能看到内容。
|
|
162
|
+
- 保存的附件位于工作区 `.pi/` 下;如有需要,请把 `.pi/` 加入你自己的项目 `.gitignore`。
|
|
147
163
|
- QQ 对每条入站消息的被动回复次数有限制。可用 `/qq-test-budget` 查看本地额度。
|
|
164
|
+
|
|
165
|
+
## 许可证
|
|
166
|
+
|
|
167
|
+
MIT
|
package/README.md
CHANGED
|
@@ -2,7 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
[English](./README.md) | [简体中文](./README-zh.md)
|
|
4
4
|
|
|
5
|
-
Connect [pi](https://github.com/earendil-works/pi) to a QQ private chat. Send text, voice, images, or files from
|
|
5
|
+
Connect [pi](https://github.com/earendil-works/pi) to a QQ private chat. Send text, voice, images, or files from QQ; pi works on your machine and sends the result back.
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Node.js 22.19 or newer, matching pi.
|
|
10
|
+
- A QQ bot application with C2C private messaging enabled.
|
|
11
|
+
- A working pi installation.
|
|
6
12
|
|
|
7
13
|
## Install
|
|
8
14
|
|
|
@@ -26,38 +32,32 @@ Credentials are kept in process memory only. Restarting pi requires scanning aga
|
|
|
26
32
|
|
|
27
33
|
## Usage
|
|
28
34
|
|
|
29
|
-
Send a
|
|
35
|
+
Send a private message to the bot to start a task.
|
|
30
36
|
|
|
31
37
|
- **Text**: normal chat message.
|
|
32
|
-
- **Voice**: QQ built-in ASR text is sent to pi
|
|
33
|
-
- **Images**:
|
|
34
|
-
- **Files**: saved under the current workspace at `.pi/pi-qq/<sessionId>/uploads/` and wait for your next instruction.
|
|
38
|
+
- **Voice**: QQ's built-in ASR text is sent to pi. The audio is not downloaded or saved. If ASR returns no text, the bot asks you to resend or type it.
|
|
39
|
+
- **Images and files**: saved under `.pi/pi-qq/<sessionId>/uploads/`. If the message has no instruction, pi waits for your next text or voice message.
|
|
35
40
|
|
|
36
|
-
|
|
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.
|
|
41
|
+
QQ clients differ in mixed-message support. Mobile QQ usually sends one message type at a time; desktop QQ can send text with an image. When a client includes text or voice together with attachments, pi-qq processes them in the same prompt.
|
|
43
42
|
|
|
44
|
-
###
|
|
43
|
+
### Attachments
|
|
45
44
|
|
|
46
|
-
|
|
45
|
+
An attachment-only message does **not** start pi. Files and images are saved, and pi waits for the next text or voice instruction.
|
|
47
46
|
|
|
48
|
-
-
|
|
49
|
-
- The next
|
|
50
|
-
- Multiple
|
|
51
|
-
-
|
|
52
|
-
-
|
|
47
|
+
- Send one or more files or images, then send a text or voice message describing what to do.
|
|
48
|
+
- The next instruction includes the saved attachment paths.
|
|
49
|
+
- Multiple attachments uploaded before the instruction are combined into one prompt.
|
|
50
|
+
- Images are read through pi's `read` tool, so the current model must support image input to see them.
|
|
51
|
+
- `/new` clears attachments waiting for an instruction.
|
|
52
|
+
- Uploads are scoped to the current pi session. Same filename and identical content reuse the existing file; same filename with different content becomes `name-1.ext`; different filenames with identical content are kept separately.
|
|
53
53
|
|
|
54
|
-
Example
|
|
54
|
+
Example prompt seen by pi:
|
|
55
55
|
|
|
56
56
|
```text
|
|
57
|
-
|
|
58
|
-
-
|
|
57
|
+
# Attachments:
|
|
58
|
+
- .pi/pi-qq/<sessionId>/uploads/report.pdf
|
|
59
59
|
|
|
60
|
-
User message:
|
|
60
|
+
# User message:
|
|
61
61
|
Summarize this file.
|
|
62
62
|
```
|
|
63
63
|
|
|
@@ -69,21 +69,28 @@ Voice messages use QQ's built-in ASR (`asr_refer_text`). The transcript is sent
|
|
|
69
69
|
- No local or external speech-to-text service is used.
|
|
70
70
|
- If QQ ASR returns no text, the bot replies `Could not transcribe this voice message; please resend or type it.` and does not start a pi run.
|
|
71
71
|
- Voice and text are separate QQ messages; send them one after another when needed.
|
|
72
|
-
-
|
|
72
|
+
- If a client sends files or images together with a voice message, they are processed with the transcript.
|
|
73
|
+
|
|
74
|
+
Debug logs include the raw `asr_refer_text` and attachment metadata when `logLevel` is set to `debug`.
|
|
75
|
+
|
|
76
|
+
### Reply format
|
|
77
|
+
|
|
78
|
+
- **Thinking**: its own bubble, plain text, starting with `**💭 思考**`. Long thinking may continue in a new bubble with the header repeated.
|
|
79
|
+
- **Tools**: one bubble per call: `**<icon> <name>**`, blank line, inline-code argument, blank line, then the result in a `text` code block.
|
|
80
|
+
- **Regular messages**: raw text with no header.
|
|
81
|
+
- **Tool icons**: 💻 bash, 📖 read, 📝 write, ✏️ edit, 🔎 grep, 🔍 search, 🗂️ find, 📁 ls, 📋 list, 🌐 web, 📡 fetch, 🗑️ delete, ❌ remove, ✅ todo, 🧪 test; unconfigured tools use 🔧.
|
|
82
|
+
- **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.
|
|
73
83
|
|
|
74
84
|
## Commands
|
|
75
85
|
|
|
76
86
|
Run these in the pi terminal:
|
|
77
87
|
|
|
78
|
-
| Command
|
|
79
|
-
|
|
|
80
|
-
| `/qq-login`
|
|
81
|
-
| `/qq-status`
|
|
82
|
-
| `/qq-logout`
|
|
83
|
-
| `/qq-
|
|
84
|
-
| `/qq-test-md [text]` | Send a Markdown test message |
|
|
85
|
-
| `/qq-test-stream` | Run a streamed timeline diagnostic (`resume` for probe) |
|
|
86
|
-
| `/qq-new` | Reset the current session (used by QQ `/new`) |
|
|
88
|
+
| Command | Description |
|
|
89
|
+
| ------------ | ------------------------------------------------------ |
|
|
90
|
+
| `/qq-login` | Log in with a QR code and bind the scanning QQ user |
|
|
91
|
+
| `/qq-status` | Show login, connection, model, context, and bound user |
|
|
92
|
+
| `/qq-logout` | Log out and clear in-memory credentials |
|
|
93
|
+
| `/qq-new` | Reset the current session (used by QQ `/new`) |
|
|
87
94
|
|
|
88
95
|
QQ-side commands:
|
|
89
96
|
|
|
@@ -95,9 +102,19 @@ QQ-side commands:
|
|
|
95
102
|
| `/status` | Show session and context status |
|
|
96
103
|
| `/help` | Show command help |
|
|
97
104
|
|
|
105
|
+
### Diagnostics
|
|
106
|
+
|
|
107
|
+
These terminal commands are intended for troubleshooting:
|
|
108
|
+
|
|
109
|
+
| Command | Description |
|
|
110
|
+
| -------------------- | ------------------------------------------------------- |
|
|
111
|
+
| `/qq-test-budget` | Show passive-reply budget and stream-bubble diagnostics |
|
|
112
|
+
| `/qq-test-md [text]` | Send a Markdown test message |
|
|
113
|
+
| `/qq-test-stream` | Run a streamed timeline diagnostic (`resume` for probe) |
|
|
114
|
+
|
|
98
115
|
## Settings
|
|
99
116
|
|
|
100
|
-
Create `~/.pi/agent/pi-qq.json` to override defaults.
|
|
117
|
+
Create `~/.pi/agent/pi-qq.json` to override defaults. It stores settings only; credentials are never written to it.
|
|
101
118
|
|
|
102
119
|
```json
|
|
103
120
|
{
|
|
@@ -110,15 +127,14 @@ Create `~/.pi/agent/pi-qq.json` to override defaults. This file contains setting
|
|
|
110
127
|
| --------------- | ---------- | ------------------------------------------------------------ |
|
|
111
128
|
| `thinkingRelay` | `true` | Relay thinking as plain text with a `💭 思考` header |
|
|
112
129
|
| `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
|
|
113
|
-
| `
|
|
114
|
-
| `fileMaxSize` | `52428800` | QQ file download limit in bytes (50MB) |
|
|
130
|
+
| `fileMaxSize` | `52428800` | QQ attachment download limit in bytes (50MB) |
|
|
115
131
|
| `logLevel` | `"silent"` | Log threshold: `silent`, `error`, `warn`, `info`, or `debug` |
|
|
116
132
|
|
|
117
|
-
|
|
133
|
+
Settings are read when a pi session starts; restart pi after editing the file. Unknown keys are ignored, and invalid values fall back to defaults with a warning.
|
|
118
134
|
|
|
119
|
-
|
|
135
|
+
When logging is 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.
|
|
120
136
|
|
|
121
|
-
|
|
137
|
+
## Development
|
|
122
138
|
|
|
123
139
|
```bash
|
|
124
140
|
npm ci
|
|
@@ -128,20 +144,24 @@ npm test
|
|
|
128
144
|
npm run format:check
|
|
129
145
|
```
|
|
130
146
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
### File naming
|
|
147
|
+
The extension entrypoint is `index.ts`. Source modules are grouped by responsibility:
|
|
134
148
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
149
|
+
| Directory | Responsibility |
|
|
150
|
+
| ------------------ | --------------------------------------------------- |
|
|
151
|
+
| `src/qq/` | QQ bot lifecycle, login, inbound handling, replies |
|
|
152
|
+
| `src/relay/` | Streamed thinking/tool/text relay |
|
|
153
|
+
| `src/attachments/` | Attachment download, storage, and voice transcripts |
|
|
154
|
+
| `src/quota/` | Passive reply budget |
|
|
155
|
+
| `src/infra/` | Settings, logging, and display formatting |
|
|
140
156
|
|
|
141
157
|
## Notes
|
|
142
158
|
|
|
143
159
|
- Only C2C (QQ private chat) is supported.
|
|
144
|
-
- Runs triggered by inbound QQ messages are relayed to QQ
|
|
145
|
-
-
|
|
146
|
-
- Saved
|
|
160
|
+
- Runs triggered by inbound QQ messages are relayed to QQ. Unrelated tasks started directly in pi stay local.
|
|
161
|
+
- Images are saved as files and read through pi's `read` tool; the current model must support image input to see them.
|
|
162
|
+
- Saved attachments are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
|
|
147
163
|
- QQ limits passive replies per inbound message. Use `/qq-test-budget` to inspect the local budget.
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
|
|
167
|
+
MIT
|
package/doc/delivery-v1-zh.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# pi-qq delivery-v1
|
|
2
2
|
|
|
3
|
-
> 状态:v1
|
|
4
|
-
>
|
|
3
|
+
> 状态:v1 已交付,作为后续版本的历史基线。
|
|
4
|
+
> 当前行为以 [README-zh.md](../README-zh.md) 为准;后续版本见 [delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
|
|
5
5
|
|
|
6
6
|
## 1. 交付范围
|
|
7
7
|
|
|
@@ -75,7 +75,7 @@ pi-qq:格式化 → QQ 文本/流式消息
|
|
|
75
75
|
|
|
76
76
|
文件:
|
|
77
77
|
|
|
78
|
-
- 保存到 `.pi/pi-qq/YYYY-MM-DD/<msgId
|
|
78
|
+
- 保存到 `.pi/pi-qq/YYYY-MM-DD/<msgId>/`;v2+ 使用按会话隔离的 `.pi/pi-qq/<sessionId>/uploads/`。提示词附带绝对路径、大小和原始文件名。
|
|
79
79
|
- 单文件超时 60 秒,默认上限 50MB。
|
|
80
80
|
- 文件名安全化;同名文件自动追加 `-1`、`-2`。
|
|
81
81
|
- 文件内容不直接注入模型,由工具按需读取。
|
|
@@ -98,12 +98,12 @@ v1 曾使用窗口汇总、工具计数和消息心跳维持长任务活性。
|
|
|
98
98
|
|
|
99
99
|
## 4. 平台限制与预算
|
|
100
100
|
|
|
101
|
-
| 限制
|
|
102
|
-
|
|
|
103
|
-
| 被动回复约 4 条 /
|
|
104
|
-
| 流式消息仅 C2C,节流 ≥300ms
|
|
105
|
-
| 单条文本约 5000 字符
|
|
106
|
-
| 流式消息依赖 5 分钟内的 `msgId`
|
|
101
|
+
| 限制 | 应对 |
|
|
102
|
+
| ------------------------------------- | ------------------------------------------------- |
|
|
103
|
+
| 被动回复约 4 条 / 小时(SDK limiter) | `ReplyBudget` 记录 `msgId` 配额,超限降级主动发送 |
|
|
104
|
+
| 流式消息仅 C2C,节流 ≥300ms | `AppendStream` 负责合帧和退避 |
|
|
105
|
+
| 单条文本约 5000 字符 | 自动分块 |
|
|
106
|
+
| 流式消息依赖 5 分钟内的 `msgId` | 过期后降级为普通消息 |
|
|
107
107
|
|
|
108
108
|
## 5. 配置与命令
|
|
109
109
|
|
package/doc/delivery-v1.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# pi-qq delivery-v1
|
|
2
2
|
|
|
3
|
-
> Status: v1 delivered; this is
|
|
4
|
-
>
|
|
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
5
|
|
|
6
6
|
## 1. Scope
|
|
7
7
|
|
|
@@ -75,7 +75,7 @@ Images:
|
|
|
75
75
|
|
|
76
76
|
Files:
|
|
77
77
|
|
|
78
|
-
- Saved under `.pi/pi-qq/YYYY-MM-DD/<msgId>/`; the prompt includes the absolute path, size, and original filename.
|
|
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
79
|
- Per-file timeout: 60 seconds; default limit: 50MB.
|
|
80
80
|
- Filenames are sanitized; duplicates get `-1`, `-2` suffixes.
|
|
81
81
|
- File contents are not injected into the model; tools read them on demand.
|
|
@@ -100,7 +100,7 @@ v1 used window summaries, tool counts, and message heartbeats to keep long runs
|
|
|
100
100
|
|
|
101
101
|
| Limit | Mitigation |
|
|
102
102
|
| --------------------------------------------------- | --------------------------------------------------------------------- |
|
|
103
|
-
| About 4 passive replies per
|
|
103
|
+
| About 4 passive replies per hour (SDK limiter) | `ReplyBudget` records `msgId` quota and falls back to proactive sends |
|
|
104
104
|
| Stream messages are C2C-only; throttle ≥300ms | `AppendStream` handles batching and retries |
|
|
105
105
|
| About 5000 characters per text message | Automatic chunking |
|
|
106
106
|
| Stream messages need a `msgId` newer than 5 minutes | Fall back to normal messages after expiry |
|
package/doc/delivery-v2-zh.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# pi-qq delivery-v2
|
|
2
2
|
|
|
3
|
-
> 状态:v2
|
|
4
|
-
>
|
|
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
5
|
|
|
6
6
|
## 1. 交付范围
|
|
7
7
|
|
|
@@ -45,7 +45,7 @@ v2 在 v1 的 QQ 私聊、图片和文件能力上增加:
|
|
|
45
45
|
- 同名同内容复用已有文件。
|
|
46
46
|
- 同名不同内容保存为 `name-1.ext`。
|
|
47
47
|
- 不同名同内容分别保存。
|
|
48
|
-
-
|
|
48
|
+
- 索引只记录文件名到哈希的映射;路径和大小来自文件系统。启动时清理失效索引。
|
|
49
49
|
- pending 文件与索引解耦,`/new` 不影响已保存的索引文件。
|
|
50
50
|
|
|
51
51
|
## 3. 配置
|
package/doc/delivery-v2.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# pi-qq delivery-v2
|
|
2
2
|
|
|
3
|
-
> Status: v2 delivered.
|
|
4
|
-
>
|
|
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
5
|
|
|
6
6
|
## 1. Scope
|
|
7
7
|
|
|
@@ -45,7 +45,7 @@ v2 adds to v1's QQ chat, image, and file support:
|
|
|
45
45
|
- Same name and same content reuses the existing file.
|
|
46
46
|
- Same name and different content is saved as `name-1.ext`.
|
|
47
47
|
- Different names with identical content are saved separately.
|
|
48
|
-
- The index
|
|
48
|
+
- The index maps filenames to hashes only; paths and sizes come from the filesystem. Stale index entries are pruned on startup.
|
|
49
49
|
- Pending files are independent from the index; `/new` does not delete saved indexed files.
|
|
50
50
|
|
|
51
51
|
## 3. Settings
|
package/doc/delivery-v3-zh.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# pi-qq delivery-v3
|
|
2
2
|
|
|
3
3
|
> 状态:v3 已实现并完成主链路真机验证;按块切泡、错误恢复、列表切分等最终细节仍需在目标 QQ 客户端做一次完整复验。
|
|
4
|
+
> 说明:后续变更删除了图片专用链路,图片与文件共用保存/pending 流程。当前行为见 [README-zh.md](../README-zh.md)。
|
|
4
5
|
> 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md)、[delivery-v2-zh.md](./delivery-v2-zh.md)。
|
|
5
6
|
|
|
6
7
|
## 1. 交付范围
|
|
@@ -133,7 +134,8 @@ assistant 文本按原文流式追加,不额外加标题。文本块和工具
|
|
|
133
134
|
<!-- prettier-ignore -->
|
|
134
135
|
| 模块 | 职责 |
|
|
135
136
|
| ---------------------------- | -------------------------------------------- |
|
|
136
|
-
| `index.ts` | 扩展装配、pi
|
|
137
|
+
| `index.ts` | 扩展装配、pi 事件订阅、登录/会话命令 |
|
|
138
|
+
| `src/qq/qq-diagnostics.ts` | 终端协议诊断(`/qq-test-*`) |
|
|
137
139
|
| `src/qq/qq-message-handler.ts` | QQ 入站路由、命令、附件、注入 pi |
|
|
138
140
|
| `src/qq/reply-sender.ts` | Markdown 转纯文本、分块、消息发送 |
|
|
139
141
|
| `src/relay/run-stream-relay.ts` | 内容块编排、气泡生命周期、工具队列、错误恢复 |
|
|
@@ -163,7 +165,7 @@ assistant 文本按原文流式追加,不额外加标题。文本块和工具
|
|
|
163
165
|
|
|
164
166
|
## 7. 验证
|
|
165
167
|
|
|
166
|
-
-
|
|
168
|
+
- v3 交付时单元测试:**135 passed**(14 个测试文件)。
|
|
167
169
|
- TypeScript、ESLint 和 Prettier 检查通过。
|
|
168
170
|
- 真机已验证:
|
|
169
171
|
- C2C 登录、文本、图片、文件;
|
package/doc/delivery-v3.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# pi-qq delivery-v3
|
|
2
2
|
|
|
3
3
|
> Status: v3 implemented and the main path has been verified on real QQ. Final details such as long-list splitting and recovery edge cases still need one complete pass on the target client.
|
|
4
|
+
> Note: later changes removed the image-specific pipeline; images now use the same save/pending path as files. See [README](../README.md) for current behavior.
|
|
4
5
|
> Previous: [delivery-v1.md](./delivery-v1.md), [delivery-v2.md](./delivery-v2.md).
|
|
5
6
|
|
|
6
7
|
## 1. Scope
|
|
@@ -133,7 +134,8 @@ The code is layered by responsibility:
|
|
|
133
134
|
<!-- prettier-ignore -->
|
|
134
135
|
| Module | Responsibility |
|
|
135
136
|
| ---------------------------- | ------------------------------------------------------------------------- |
|
|
136
|
-
| `index.ts` | Extension wiring, pi event subscriptions,
|
|
137
|
+
| `index.ts` | Extension wiring, pi event subscriptions, login/session commands |
|
|
138
|
+
| `src/qq/qq-diagnostics.ts` | Terminal protocol diagnostics (`/qq-test-*`) |
|
|
137
139
|
| `src/qq/qq-message-handler.ts` | QQ inbound routing, commands, attachments, injection into pi |
|
|
138
140
|
| `src/qq/reply-sender.ts` | Markdown-to-text conversion, chunking, sending |
|
|
139
141
|
| `src/relay/run-stream-relay.ts` | Content-block orchestration, bubble lifecycle, tool queue, recovery |
|
|
@@ -163,7 +165,7 @@ Boundary rules:
|
|
|
163
165
|
|
|
164
166
|
## 7. Verification
|
|
165
167
|
|
|
166
|
-
- Unit tests: **135 passed** across 14 test files.
|
|
168
|
+
- Unit tests at v3 delivery: **135 passed** across 14 test files.
|
|
167
169
|
- TypeScript, ESLint, and Prettier checks pass.
|
|
168
170
|
- Verified on real QQ:
|
|
169
171
|
- C2C login, text, images, and files;
|