@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
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,26 +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
|
-
|
|
41
|
+
QQ 客户端对混合消息的支持不同。手机 QQ 通常一次只发一种类型,桌面版 QQ 可以发送“文字 + 图片”。当客户端把文字/语音和附件放在同一条消息里时,pi-qq 会把它们合并到同一个提示词中处理。
|
|
37
42
|
|
|
38
|
-
|
|
43
|
+
### 附件
|
|
39
44
|
|
|
40
|
-
|
|
41
|
-
- 下一条文字/语音会作为指令;保存路径、文件大小和原始文件名会加入该提示词。
|
|
42
|
-
- 指令到达前上传的多个文件会合并到同一个提示词中。
|
|
43
|
-
- `/new` 会清空等待指令的文件。
|
|
44
|
-
- 文件按当前 pi 会话隔离。相同文件名且内容相同会复用已有文件;相同文件名但内容不同会保存为 `name-1.ext`;不同文件名但内容相同会分别保存。
|
|
45
|
+
**只发送附件不会启动 pi。** 文件和图片会先保存,pi 等待下一条文字或语音指令后再处理。
|
|
45
46
|
|
|
46
|
-
|
|
47
|
+
- 先上传一个或多个文件或图片,再发送文字或语音说明要做什么。
|
|
48
|
+
- 下一条指令会包含保存后的附件路径。
|
|
49
|
+
- 指令到达前上传的多个附件会合并到同一个提示词中。
|
|
50
|
+
- 图片通过 pi 的 `read` 工具查看,因此当前模型必须支持图片输入才能看到内容。
|
|
51
|
+
- `/new` 会清空等待指令的附件。
|
|
52
|
+
- 附件按当前 pi 会话隔离。相同文件名且内容相同会复用已有文件;相同文件名但内容不同会保存为 `name-1.ext`;不同文件名但内容相同会分别保存。
|
|
53
|
+
|
|
54
|
+
pi 看到的提示词示例:
|
|
47
55
|
|
|
48
56
|
```text
|
|
49
|
-
|
|
50
|
-
-
|
|
57
|
+
# Attachments:
|
|
58
|
+
- .pi/pi-qq/<sessionId>/uploads/report.pdf
|
|
51
59
|
|
|
52
|
-
User message:
|
|
60
|
+
# User message:
|
|
53
61
|
Summarize this file.
|
|
54
62
|
```
|
|
55
63
|
|
|
@@ -61,21 +69,28 @@ Summarize this file.
|
|
|
61
69
|
- 不使用本地或外部语音识别服务。
|
|
62
70
|
- 如果 QQ ASR 没有返回文本,机器人会回复 `Could not transcribe this voice message; please resend or type it.`,并且不会启动 pi。
|
|
63
71
|
- 语音和文字是两条独立的 QQ 消息;需要时按顺序发送。
|
|
64
|
-
-
|
|
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` 会等待当前工具和流收尾后再回复。
|
|
65
83
|
|
|
66
84
|
## 命令
|
|
67
85
|
|
|
68
86
|
在 pi 终端执行:
|
|
69
87
|
|
|
70
|
-
| 命令
|
|
71
|
-
|
|
|
72
|
-
| `/qq-login`
|
|
73
|
-
| `/qq-status`
|
|
74
|
-
| `/qq-logout`
|
|
75
|
-
| `/qq-
|
|
76
|
-
| `/qq-test-md [text]` | 发送 Markdown 测试消息 |
|
|
77
|
-
| `/qq-test-stream` | 运行流式时间线诊断 |
|
|
78
|
-
| `/qq-new` | 重置当前会话(由 QQ 侧 `/new` 调用) |
|
|
88
|
+
| 命令 | 说明 |
|
|
89
|
+
| ------------ | -------------------------------------- |
|
|
90
|
+
| `/qq-login` | 扫码登录并绑定扫码的 QQ 用户 |
|
|
91
|
+
| `/qq-status` | 显示登录、连接、模型、上下文和绑定用户 |
|
|
92
|
+
| `/qq-logout` | 退出登录并清除内存中的凭据 |
|
|
93
|
+
| `/qq-new` | 重置当前会话(由 QQ 侧 `/new` 调用) |
|
|
79
94
|
|
|
80
95
|
QQ 侧命令:
|
|
81
96
|
|
|
@@ -87,36 +102,39 @@ QQ 侧命令:
|
|
|
87
102
|
| `/status` | 显示会话和上下文状态 |
|
|
88
103
|
| `/help` | 显示命令帮助 |
|
|
89
104
|
|
|
105
|
+
### 诊断
|
|
106
|
+
|
|
107
|
+
以下终端命令用于排查问题:
|
|
108
|
+
|
|
109
|
+
| 命令 | 说明 |
|
|
110
|
+
| -------------------- | --------------------------------------- |
|
|
111
|
+
| `/qq-test-budget` | 显示被动回复额度和流式气泡诊断信息 |
|
|
112
|
+
| `/qq-test-md [text]` | 发送 Markdown 测试消息 |
|
|
113
|
+
| `/qq-test-stream` | 运行流式时间线诊断(`resume` 验证续写) |
|
|
114
|
+
|
|
90
115
|
## 设置
|
|
91
116
|
|
|
92
117
|
创建 `~/.pi/agent/pi-qq.json` 覆盖默认值。该文件只保存设置;凭据不会写入其中。
|
|
93
118
|
|
|
94
119
|
```json
|
|
95
120
|
{
|
|
96
|
-
"
|
|
97
|
-
"streamFlushMs": 10000,
|
|
121
|
+
"thinkingRelay": true,
|
|
98
122
|
"logLevel": "silent"
|
|
99
123
|
}
|
|
100
124
|
```
|
|
101
125
|
|
|
102
|
-
| 配置项
|
|
103
|
-
|
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
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` |
|
|
114
|
-
|
|
115
|
-
启用日志后,日志写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。可用 `PI_QQ_LOG_DIR` 覆盖目录。`info` 只记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。旧配置 `debug: true` 会映射为 `logLevel: "debug"`。
|
|
126
|
+
| 配置项 | 默认值 | 说明 |
|
|
127
|
+
| --------------- | ---------- | ------------------------------------------------------ |
|
|
128
|
+
| `thinkingRelay` | `true` | 以 `💭 思考` 标题的纯文本回传思考;`false` 时隐藏 |
|
|
129
|
+
| `deliverAs` | `"steer"` | 忙碌时新消息的排队方式:`steer` 或 `followUp` |
|
|
130
|
+
| `fileMaxSize` | `52428800` | QQ 附件下载上限(字节,50MB) |
|
|
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` 记录完整事件、附件、提示词和工具参数/结果。
|
|
136
|
+
|
|
137
|
+
## 开发
|
|
120
138
|
|
|
121
139
|
```bash
|
|
122
140
|
npm ci
|
|
@@ -126,12 +144,24 @@ npm test
|
|
|
126
144
|
npm run format:check
|
|
127
145
|
```
|
|
128
146
|
|
|
129
|
-
`
|
|
147
|
+
扩展入口是 `index.ts`。源码按职责分组:
|
|
148
|
+
|
|
149
|
+
| 目录 | 职责 |
|
|
150
|
+
| ------------------ | ------------------------------------- |
|
|
151
|
+
| `src/qq/` | QQ bot 生命周期、登录、入站处理和回复 |
|
|
152
|
+
| `src/relay/` | 思考/工具/文本的流式回传 |
|
|
153
|
+
| `src/attachments/` | 附件下载、存储和语音转写 |
|
|
154
|
+
| `src/quota/` | 被动回复额度 |
|
|
155
|
+
| `src/infra/` | 配置、日志和显示格式化 |
|
|
130
156
|
|
|
131
157
|
## 说明
|
|
132
158
|
|
|
133
159
|
- 仅支持 C2C(QQ 私聊)。
|
|
134
|
-
-
|
|
135
|
-
-
|
|
136
|
-
-
|
|
160
|
+
- QQ 入站消息触发的任务会回传 QQ;直接在 pi 中启动的无关任务不会推送。
|
|
161
|
+
- 图片会保存为文件,并通过 pi 的 `read` 工具查看;当前模型必须支持图片输入才能看到内容。
|
|
162
|
+
- 保存的附件位于工作区 `.pi/` 下;如有需要,请把 `.pi/` 加入你自己的项目 `.gitignore`。
|
|
137
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,30 +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
|
-
|
|
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.
|
|
40
|
+
|
|
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.
|
|
35
42
|
|
|
36
|
-
###
|
|
43
|
+
### Attachments
|
|
37
44
|
|
|
38
|
-
|
|
45
|
+
An attachment-only message does **not** start pi. Files and images are saved, and pi waits for the next text or voice instruction.
|
|
39
46
|
|
|
40
|
-
-
|
|
41
|
-
- The next
|
|
42
|
-
- Multiple
|
|
43
|
-
-
|
|
44
|
-
-
|
|
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.
|
|
45
53
|
|
|
46
|
-
Example
|
|
54
|
+
Example prompt seen by pi:
|
|
47
55
|
|
|
48
56
|
```text
|
|
49
|
-
|
|
50
|
-
-
|
|
57
|
+
# Attachments:
|
|
58
|
+
- .pi/pi-qq/<sessionId>/uploads/report.pdf
|
|
51
59
|
|
|
52
|
-
User message:
|
|
60
|
+
# User message:
|
|
53
61
|
Summarize this file.
|
|
54
62
|
```
|
|
55
63
|
|
|
@@ -61,21 +69,28 @@ Voice messages use QQ's built-in ASR (`asr_refer_text`). The transcript is sent
|
|
|
61
69
|
- No local or external speech-to-text service is used.
|
|
62
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.
|
|
63
71
|
- Voice and text are separate QQ messages; send them one after another when needed.
|
|
64
|
-
-
|
|
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.
|
|
65
83
|
|
|
66
84
|
## Commands
|
|
67
85
|
|
|
68
86
|
Run these in the pi terminal:
|
|
69
87
|
|
|
70
|
-
| Command
|
|
71
|
-
|
|
|
72
|
-
| `/qq-login`
|
|
73
|
-
| `/qq-status`
|
|
74
|
-
| `/qq-logout`
|
|
75
|
-
| `/qq-
|
|
76
|
-
| `/qq-test-md [text]` | Send a Markdown test message |
|
|
77
|
-
| `/qq-test-stream` | Run a streamed timeline diagnostic |
|
|
78
|
-
| `/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`) |
|
|
79
94
|
|
|
80
95
|
QQ-side commands:
|
|
81
96
|
|
|
@@ -87,36 +102,39 @@ QQ-side commands:
|
|
|
87
102
|
| `/status` | Show session and context status |
|
|
88
103
|
| `/help` | Show command help |
|
|
89
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
|
+
|
|
90
115
|
## Settings
|
|
91
116
|
|
|
92
|
-
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.
|
|
93
118
|
|
|
94
119
|
```json
|
|
95
120
|
{
|
|
96
|
-
"
|
|
97
|
-
"streamFlushMs": 10000,
|
|
121
|
+
"thinkingRelay": true,
|
|
98
122
|
"logLevel": "silent"
|
|
99
123
|
}
|
|
100
124
|
```
|
|
101
125
|
|
|
102
|
-
| Key
|
|
103
|
-
|
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
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` |
|
|
114
|
-
|
|
115
|
-
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"`.
|
|
126
|
+
| Key | Default | Description |
|
|
127
|
+
| --------------- | ---------- | ------------------------------------------------------------ |
|
|
128
|
+
| `thinkingRelay` | `true` | Relay thinking as plain text with a `💭 思考` header |
|
|
129
|
+
| `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
|
|
130
|
+
| `fileMaxSize` | `52428800` | QQ attachment download limit in bytes (50MB) |
|
|
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.
|
|
136
|
+
|
|
137
|
+
## Development
|
|
120
138
|
|
|
121
139
|
```bash
|
|
122
140
|
npm ci
|
|
@@ -126,12 +144,24 @@ npm test
|
|
|
126
144
|
npm run format:check
|
|
127
145
|
```
|
|
128
146
|
|
|
129
|
-
|
|
147
|
+
The extension entrypoint is `index.ts`. Source modules are grouped by responsibility:
|
|
148
|
+
|
|
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 |
|
|
130
156
|
|
|
131
157
|
## Notes
|
|
132
158
|
|
|
133
159
|
- Only C2C (QQ private chat) is supported.
|
|
134
|
-
-
|
|
135
|
-
-
|
|
136
|
-
- 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.
|
|
137
163
|
- QQ limits passive replies per inbound message. Use `/qq-test-budget` to inspect the local budget.
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
|
|
167
|
+
MIT
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# pi-qq delivery-v1
|
|
2
|
+
|
|
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
|
+
|
|
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>/`;v2+ 使用按会话隔离的 `.pi/pi-qq/<sessionId>/uploads/`。提示词附带绝对路径、大小和原始文件名。
|
|
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 条 / 小时(SDK limiter) | `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 取代,不应作为当前行为参考。
|