@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 CHANGED
@@ -2,7 +2,13 @@
2
2
 
3
3
  [English](./README.md) | 简体中文
4
4
 
5
- 将 [pi](https://github.com/earendil-works/pi) 接入 QQ 私聊。在手机 QQ 上发送文字、语音、图片或文件,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
- - **图片**:作为视觉输入交给 pi。
34
- - **文件**:保存到当前工作区的 `.pi/pi-qq/<sessionId>/uploads/`,并等待你的下一条指令。
39
+ - **图片和文件**:保存到 `.pi/pi-qq/<sessionId>/uploads/`。如果消息中没有指令,pi 会等待你的下一条文字或语音消息。
35
40
 
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` 会等待当前工具和流收尾后再回复。
41
+ QQ 客户端对混合消息的支持不同。手机 QQ 通常一次只发一种类型,桌面版 QQ 可以发送“文字 + 图片”。当客户端把文字/语音和附件放在同一条消息里时,pi-qq 会把它们合并到同一个提示词中处理。
43
42
 
44
- ### 文件
43
+ ### 附件
45
44
 
46
- **只发送文件不会启动 pi。** 文件会先保存,pi 等待下一条文字或语音指令后再处理。
45
+ **只发送附件不会启动 pi。** 文件和图片会先保存,pi 等待下一条文字或语音指令后再处理。
47
46
 
48
- - 先上传一个或多个文件,再发送文字或语音说明要做什么。
49
- - 下一条文字/语音会作为指令;保存路径、文件大小和原始文件名会加入该提示词。
50
- - 指令到达前上传的多个文件会合并到同一个提示词中。
51
- - `/new` 会清空等待指令的文件。
52
- - 文件按当前 pi 会话隔离。相同文件名且内容相同会复用已有文件;相同文件名但内容不同会保存为 `name-1.ext`;不同文件名但内容相同会分别保存。
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
- User sent the following file via QQ (saved locally; use read/bash or other tools to access it):
58
- - /home/chen/project/myproj/.pi/pi-qq/<sessionId>/uploads/report.pdf (1.4MB, original name: report.pdf)
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
- - 要查看原始 ASR 结果,可将 `logLevel` 设为 `debug`;日志会包含 `asr_refer_text` 和附件元数据。
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` | 扫码登录并绑定扫码的 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` 调用) |
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
- | `imageMaxSize` | `10485760` | QQ 图片下载上限(字节,10MB) |
114
- | `fileMaxSize` | `52428800` | QQ 文件下载上限(字节,50MB) |
130
+ | `fileMaxSize` | `52428800` | QQ 附件下载上限(字节,50MB) |
115
131
  | `logLevel` | `"silent"` | 日志阈值:`silent`、`error`、`warn`、`info` 或 `debug` |
116
132
 
117
- 启用日志后,日志写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。可用 `PI_QQ_LOG_DIR` 覆盖目录。`info` 只记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。旧配置 `debug: true` 会映射为 `logLevel: "debug"`。
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
- 需要 Node.js 22.19 或更高版本(与 pi 的要求一致)。安装依赖后运行:
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
- `eslint.config.ts` 使用 Node.js 原生 TypeScript 剥离能力加载,不需要 `jiti`。
132
-
133
- ### 文件命名
147
+ 扩展入口是 `index.ts`。源码按职责分组:
134
148
 
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` 这类泛化名称,应体现领域和职责。
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;模型错误后的自动恢复 run 也会继续回传。无关的本地任务不推送 QQ。
145
- - 收到的图片会作为视觉输入传给模型;当前模型必须支持图片输入。
146
- - 保存的文件位于工作区 `.pi/` 下;如有需要,请把 `.pi/` 加入你自己的项目 `.gitignore`。
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 mobile QQ; pi works on your machine and sends the result back to QQ.
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 QQ private message to the bot to start a task.
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 directly; the audio is not downloaded or saved. If ASR returns no text, the bot asks you to resend or type it.
33
- - **Images**: sent to pi as vision input.
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
- ### 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.
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
- ### Files
43
+ ### Attachments
45
44
 
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.
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
- - Upload one or more files, then send a text or voice message describing what to do.
49
- - The next text/voice message is used as the instruction; the saved path(s), size, and original filename are added to that prompt.
50
- - Multiple files uploaded before the instruction are combined into one prompt.
51
- - `/new` clears files waiting for an instruction.
52
- - Uploads are scoped to the current pi session. If you upload the same filename with identical content, pi reuses the existing file; the same filename with different content is saved as `name-1.ext`; different filenames with identical content are kept as separate files.
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 file prompt seen by pi:
54
+ Example prompt seen by pi:
55
55
 
56
56
  ```text
57
- User sent the following file via QQ (saved locally; use read/bash or other tools to access it):
58
- - /home/chen/project/myproj/.pi/pi-qq/<sessionId>/uploads/report.pdf (1.4MB, original name: report.pdf)
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
- - To inspect the raw ASR result, set `logLevel` to `debug`; the log includes `asr_refer_text` and attachment metadata.
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 | Description |
79
- | -------------------- | ------------------------------------------------------- |
80
- | `/qq-login` | Log in with a QR code and bind the scanning QQ user |
81
- | `/qq-status` | Show login, connection, model, context, and bound user |
82
- | `/qq-logout` | Log out and clear in-memory credentials |
83
- | `/qq-test-budget` | Show passive-reply budget and stream-bubble diagnostics |
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. This file contains settings only; credentials are never written to it.
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
- | `imageMaxSize` | `10485760` | QQ image download limit in bytes (10MB) |
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
- 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"`.
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
- ## Development
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
- Node.js 22.19 or newer is required, matching pi. Install dependencies and run:
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
- `eslint.config.ts` is loaded through Node.js native TypeScript stripping; `jiti` is not required.
132
-
133
- ### File naming
147
+ The extension entrypoint is `index.ts`. Source modules are grouped by responsibility:
134
148
 
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.
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, as are automatic retry runs after model errors. Unrelated tasks started directly in pi stay local.
145
- - Incoming images are passed to the model as vision input; the current model must support image input.
146
- - Saved files are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
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
@@ -1,7 +1,7 @@
1
1
  # pi-qq delivery-v1
2
2
 
3
- > 状态:v1 已交付,作为后续版本基线。
4
- > 后续版本见 [delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
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 条 / 5 分钟窗口 | `ReplyBudget` 记录 `msgId` 配额,超限降级主动发送 |
104
- | 流式消息仅 C2C,节流 ≥300ms | `AppendStream` 负责合帧和退避 |
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
 
@@ -1,7 +1,7 @@
1
1
  # pi-qq delivery-v1
2
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).
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 5-minute window | `ReplyBudget` records `msgId` quota and falls back to proactive sends |
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 |
@@ -1,7 +1,7 @@
1
1
  # pi-qq delivery-v2
2
2
 
3
- > 状态:v2 已交付。
4
- > 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md);后续版本:[delivery-v3-zh.md](./delivery-v3-zh.md)。
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. 配置
@@ -1,7 +1,7 @@
1
1
  # pi-qq delivery-v2
2
2
 
3
- > Status: v2 delivered.
4
- > Previous: [delivery-v1.md](./delivery-v1.md); next: [delivery-v3.md](./delivery-v3.md).
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 records path, size, hash, and original filename; stale entries are pruned on startup.
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
@@ -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
- - 单元测试:**135 passed**(14 个测试文件)。
168
+ - v3 交付时单元测试:**135 passed**(14 个测试文件)。
167
169
  - TypeScript、ESLint 和 Prettier 检查通过。
168
170
  - 真机已验证:
169
171
  - C2C 登录、文本、图片、文件;
@@ -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, command/diagnostic registration |
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;