@chen_hu_hu/pi-qq 1.2.0 → 1.2.3
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 +137 -0
- package/README.md +26 -3
- package/doc/features-v2.md +1 -0
- package/doc/plan-v2.md +1 -0
- package/index.ts +4 -1
- package/package.json +11 -2
- package/src/config.ts +1 -1
- package/src/download.ts +1 -1
- package/src/files.ts +2 -2
- package/src/run-feedback.ts +5 -1
package/README-zh.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# pi-qq
|
|
2
|
+
|
|
3
|
+
[English](./README.md) | 简体中文
|
|
4
|
+
|
|
5
|
+
将 [pi](https://github.com/earendil-works/pi) 接入 QQ 私聊。在手机 QQ 上发送文字、语音、图片或文件,pi 在你的电脑上工作,并把结果发回 QQ。
|
|
6
|
+
|
|
7
|
+
## 安装
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pi install npm:@chen_hu_hu/pi-qq
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
本地开发:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pi --extension /path/to/pi-qq
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## 登录
|
|
20
|
+
|
|
21
|
+
1. 启动 pi。
|
|
22
|
+
2. 执行 `/qq-login`。
|
|
23
|
+
3. 用手机 QQ 扫描二维码。
|
|
24
|
+
|
|
25
|
+
登录凭据只保存在进程内存中。重启 pi 后需要重新扫码。`/qq-logout` 会立即清除内存中的凭据。
|
|
26
|
+
|
|
27
|
+
## 使用
|
|
28
|
+
|
|
29
|
+
给机器人发送 QQ 私聊消息即可开始任务。
|
|
30
|
+
|
|
31
|
+
- **文字**:普通聊天消息。
|
|
32
|
+
- **语音**:直接使用 QQ 内置 ASR 文本;音频不会下载或保存。如果 ASR 没有返回文本,机器人会提示你重发或改用文字。
|
|
33
|
+
- **图片**:作为视觉输入交给 pi。
|
|
34
|
+
- **文件**:保存到当前工作区的 `.pi/pi-qq/<sessionId>/uploads/`,并等待你的下一条指令。
|
|
35
|
+
|
|
36
|
+
### 文件
|
|
37
|
+
|
|
38
|
+
**只发送文件不会启动 pi。** 文件会先保存,pi 等待下一条文字或语音指令后再处理。
|
|
39
|
+
|
|
40
|
+
- 先上传一个或多个文件,再发送文字或语音说明要做什么。
|
|
41
|
+
- 下一条文字/语音会作为指令;保存路径、文件大小和原始文件名会加入该提示词。
|
|
42
|
+
- 指令到达前上传的多个文件会合并到同一个提示词中。
|
|
43
|
+
- `/new` 会清空等待指令的文件。
|
|
44
|
+
- 文件按当前 pi 会话隔离。相同文件名且内容相同会复用已有文件;相同文件名但内容不同会保存为 `name-1.ext`;不同文件名但内容相同会分别保存。
|
|
45
|
+
|
|
46
|
+
pi 看到的文件提示词示例:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
User sent the following file via QQ (saved locally; use read/bash or other tools to access it):
|
|
50
|
+
- /home/chen/project/myproj/.pi/pi-qq/<sessionId>/uploads/report.pdf (1.4MB, original name: report.pdf)
|
|
51
|
+
|
|
52
|
+
User message:
|
|
53
|
+
Summarize this file.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### 语音消息
|
|
57
|
+
|
|
58
|
+
语音消息使用 QQ 内置 ASR(`asr_refer_text`)。转写文本会作为普通用户文本交给 pi;pi 不会收到音频文件。
|
|
59
|
+
|
|
60
|
+
- 语音附件不会下载或保存为 `.amr` / `.silk`。
|
|
61
|
+
- 不使用本地或外部语音识别服务。
|
|
62
|
+
- 如果 QQ ASR 没有返回文本,机器人会回复 `Could not transcribe this voice message; please resend or type it.`,并且不会启动 pi。
|
|
63
|
+
- 语音和文字是两条独立的 QQ 消息;需要时按顺序发送。
|
|
64
|
+
- 要查看原始 ASR 结果,可将 `logLevel` 设为 `debug`;日志会包含 `asr_refer_text` 和附件元数据。
|
|
65
|
+
|
|
66
|
+
## 命令
|
|
67
|
+
|
|
68
|
+
在 pi 终端执行:
|
|
69
|
+
|
|
70
|
+
| 命令 | 说明 |
|
|
71
|
+
| -------------------- | -------------------------------------- |
|
|
72
|
+
| `/qq-login` | 扫码登录并绑定扫码的 QQ 用户 |
|
|
73
|
+
| `/qq-status` | 显示登录、连接、模型、上下文和绑定用户 |
|
|
74
|
+
| `/qq-logout` | 退出登录并清除内存中的凭据 |
|
|
75
|
+
| `/qq-test-budget` | 显示被动回复额度和流式气泡诊断信息 |
|
|
76
|
+
| `/qq-test-md [text]` | 发送 Markdown 测试消息 |
|
|
77
|
+
| `/qq-test-stream` | 运行流式时间线诊断 |
|
|
78
|
+
| `/qq-new` | 重置当前会话(由 QQ 侧 `/new` 调用) |
|
|
79
|
+
|
|
80
|
+
QQ 侧命令:
|
|
81
|
+
|
|
82
|
+
| 命令 | 说明 |
|
|
83
|
+
| ---------- | -------------------- |
|
|
84
|
+
| `/new` | 开始新的 pi 会话 |
|
|
85
|
+
| `/stop` | 中止当前运行 |
|
|
86
|
+
| `/compact` | 压缩当前上下文 |
|
|
87
|
+
| `/status` | 显示会话和上下文状态 |
|
|
88
|
+
| `/help` | 显示命令帮助 |
|
|
89
|
+
|
|
90
|
+
## 设置
|
|
91
|
+
|
|
92
|
+
创建 `~/.pi/agent/pi-qq.json` 覆盖默认值。该文件只保存设置;凭据不会写入其中。
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"markdownSupport": false,
|
|
97
|
+
"streamFlushMs": 10000,
|
|
98
|
+
"logLevel": "silent"
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
| 配置项 | 默认值 | 说明 |
|
|
103
|
+
| ---------------------- | ---------- | ------------------------------------------------------ |
|
|
104
|
+
| `streamAssistant` | `true` | 流式回传 assistant 回复 |
|
|
105
|
+
| `markdownSupport` | `false` | 机器人有 QQ Markdown 权限;设为 `true` 时透传 Markdown |
|
|
106
|
+
| `deliverAs` | `"steer"` | 忙碌时新消息的排队方式:`steer` 或 `followUp` |
|
|
107
|
+
| `imageMaxSize` | `10485760` | QQ 图片下载上限(字节,10MB) |
|
|
108
|
+
| `fileMaxSize` | `52428800` | QQ 文件下载上限(字节,50MB) |
|
|
109
|
+
| `heartbeatMinutes` | `10` | 长任务心跳间隔;`0` 表示关闭 |
|
|
110
|
+
| `heartbeatMaxMessages` | `3` | 每次运行的消息心跳上限 |
|
|
111
|
+
| `streamRelay` | `true` | 使用 append 模式流式气泡 |
|
|
112
|
+
| `streamFlushMs` | `10000` | 流式汇总帧间隔(毫秒,最小 300) |
|
|
113
|
+
| `logLevel` | `"silent"` | 日志阈值:`silent`、`error`、`warn`、`info` 或 `debug` |
|
|
114
|
+
|
|
115
|
+
启用日志后,日志写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。可用 `PI_QQ_LOG_DIR` 覆盖目录。`info` 只记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。旧配置 `debug: true` 会映射为 `logLevel: "debug"`。
|
|
116
|
+
|
|
117
|
+
## 开发
|
|
118
|
+
|
|
119
|
+
需要 Node.js 22.19 或更高版本(与 pi 的要求一致)。安装依赖后运行:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npm ci
|
|
123
|
+
npm run lint
|
|
124
|
+
npm run typecheck
|
|
125
|
+
npm test
|
|
126
|
+
npm run format:check
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`eslint.config.ts` 使用 Node.js 原生 TypeScript 剥离能力加载,不需要 `jiti`。
|
|
130
|
+
|
|
131
|
+
## 说明
|
|
132
|
+
|
|
133
|
+
- 仅支持 C2C(QQ 私聊)。
|
|
134
|
+
- 只有 QQ 入站消息触发的任务才会回传 QQ;在 pi 侧直接发起的任务只在本地处理,不推送 QQ。
|
|
135
|
+
- 收到的图片会作为视觉输入传给模型;当前模型必须支持图片输入。
|
|
136
|
+
- 保存的文件位于工作区 `.pi/` 下;如有需要,请把 `.pi/` 加入你自己的项目 `.gitignore`。
|
|
137
|
+
- QQ 对每条入站消息的被动回复次数有限制。可用 `/qq-test-budget` 查看本地额度。
|
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# pi-qq
|
|
2
2
|
|
|
3
|
+
[English](./README.md) | [简体中文](./README-zh.md)
|
|
4
|
+
|
|
3
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.
|
|
4
6
|
|
|
5
7
|
## Install
|
|
@@ -29,11 +31,17 @@ Send a QQ private message to the bot to start a task.
|
|
|
29
31
|
- **Text**: normal chat message.
|
|
30
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.
|
|
31
33
|
- **Images**: sent to pi as vision input.
|
|
32
|
-
- **Files**: saved under the current workspace at `.pi/pi-qq/<sessionId>/uploads
|
|
34
|
+
- **Files**: saved under the current workspace at `.pi/pi-qq/<sessionId>/uploads/` and wait for your next instruction.
|
|
35
|
+
|
|
36
|
+
### Files
|
|
33
37
|
|
|
34
|
-
|
|
38
|
+
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.
|
|
35
39
|
|
|
36
|
-
|
|
40
|
+
- Upload one or more files, then send a text or voice message describing what to do.
|
|
41
|
+
- The next text/voice message is used as the instruction; the saved path(s), size, and original filename are added to that prompt.
|
|
42
|
+
- Multiple files uploaded before the instruction are combined into one prompt.
|
|
43
|
+
- `/new` clears files waiting for an instruction.
|
|
44
|
+
- 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.
|
|
37
45
|
|
|
38
46
|
Example file prompt seen by pi:
|
|
39
47
|
|
|
@@ -106,9 +114,24 @@ Create `~/.pi/agent/pi-qq.json` to override defaults. This file contains setting
|
|
|
106
114
|
|
|
107
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"`.
|
|
108
116
|
|
|
117
|
+
## Development
|
|
118
|
+
|
|
119
|
+
Node.js 22.19 or newer is required, matching pi. Install dependencies and run:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npm ci
|
|
123
|
+
npm run lint
|
|
124
|
+
npm run typecheck
|
|
125
|
+
npm test
|
|
126
|
+
npm run format:check
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`eslint.config.ts` is loaded through Node.js native TypeScript stripping; `jiti` is not required.
|
|
130
|
+
|
|
109
131
|
## Notes
|
|
110
132
|
|
|
111
133
|
- Only C2C (QQ private chat) is supported.
|
|
134
|
+
- Only runs triggered by inbound QQ messages are relayed to QQ. Tasks started directly in pi stay local.
|
|
112
135
|
- Incoming images are passed to the model as vision input; the current model must support image input.
|
|
113
136
|
- Saved files are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
|
|
114
137
|
- QQ limits passive replies per inbound message. Use `/qq-test-budget` to inspect the local budget.
|
package/doc/features-v2.md
CHANGED
package/doc/plan-v2.md
CHANGED
|
@@ -329,3 +329,4 @@ pi-qq/
|
|
|
329
329
|
- 2026-10-30:F11 文件存储与去重实现完成;`npm test` 109 项通过,`typecheck`、`format:check` 通过。
|
|
330
330
|
- 2026-10-30:实机测试发现两条文件消息并发时索引互相覆盖(`c.txt` 文件存在但索引缺失)。根因是 `bot.ts` 的 message handler 未 await `onMessage`,导致 `concurrencyGuard` 提前释放锁。已修复并新增 `test/bot.test.ts`。
|
|
331
331
|
- 2026-10-30:F11 实机重测通过。`c.txt` / `b.txt` 快速连续上传后索引同时保留两项;`a.txt` / `d.txt` 不同文件名同内容按规则保留两份;索引共 4 项。
|
|
332
|
+
- 2026-10-30:修复 QQ 登录后 pi 侧本地交互被回传 QQ 的问题。`RunFeedback.isQQRunActive()` 按 run 来源判断,`message_end` 仅回传 QQ 触发的 run;`npm test` 110 项通过。
|
package/index.ts
CHANGED
|
@@ -222,13 +222,15 @@ export default function (pi: ExtensionAPI) {
|
|
|
222
222
|
void runFeedback.onAssistantDelta(snapshot, thinking);
|
|
223
223
|
});
|
|
224
224
|
|
|
225
|
-
// pi → QQ: assistant message relay (
|
|
225
|
+
// pi → QQ: assistant message relay (QQ-triggered runs only).
|
|
226
226
|
|
|
227
227
|
pi.on("message_end", async (event, ctx) => {
|
|
228
228
|
const msg = event.message;
|
|
229
229
|
if (msg.role !== "assistant" || !running) return;
|
|
230
230
|
|
|
231
|
+
const fromQQ = runFeedback.isQQRunActive();
|
|
231
232
|
log.debug("pi", "assistant message ended", {
|
|
233
|
+
fromQQ,
|
|
232
234
|
stopReason: msg.stopReason,
|
|
233
235
|
contentTypes: msg.content.map((block) => block.type),
|
|
234
236
|
textPreview: previewForLog(
|
|
@@ -238,6 +240,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
238
240
|
.join("\n"),
|
|
239
241
|
),
|
|
240
242
|
});
|
|
243
|
+
if (!fromQQ) return;
|
|
241
244
|
|
|
242
245
|
const { config } = readConfig();
|
|
243
246
|
const settings = getSettings(config);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@chen_hu_hu/pi-qq",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.3",
|
|
4
4
|
"description": "Connect pi to QQ private chats.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "CQ-Developer",
|
|
@@ -35,10 +35,13 @@
|
|
|
35
35
|
"src",
|
|
36
36
|
"doc",
|
|
37
37
|
"README.md",
|
|
38
|
+
"README-zh.md",
|
|
38
39
|
"LICENSE"
|
|
39
40
|
],
|
|
40
41
|
"scripts": {
|
|
41
|
-
"typecheck": "
|
|
42
|
+
"typecheck": "tsc --noEmit",
|
|
43
|
+
"lint": "npx --node-options=\"--experimental-strip-types\" eslint --flag unstable_native_nodejs_ts_config .",
|
|
44
|
+
"lint:fix": "npx --node-options=\"--experimental-strip-types\" eslint --flag unstable_native_nodejs_ts_config . --fix",
|
|
42
45
|
"test": "vitest run",
|
|
43
46
|
"format": "prettier --write .",
|
|
44
47
|
"format:check": "prettier --check ."
|
|
@@ -57,7 +60,13 @@
|
|
|
57
60
|
}
|
|
58
61
|
},
|
|
59
62
|
"devDependencies": {
|
|
63
|
+
"@earendil-works/pi-coding-agent": "^1.4.0",
|
|
64
|
+
"@eslint/js": "^10.0.1",
|
|
65
|
+
"@types/node": "^22.20.5",
|
|
66
|
+
"eslint": "^10.14.0",
|
|
60
67
|
"prettier": "^3.9.10",
|
|
68
|
+
"typescript": "^5.9.3",
|
|
69
|
+
"typescript-eslint": "^8.72.1",
|
|
61
70
|
"vitest": "^5.0.5"
|
|
62
71
|
}
|
|
63
72
|
}
|
package/src/config.ts
CHANGED
|
@@ -62,7 +62,7 @@ export function readConfig(): { config: PiQQConfig; error?: string } {
|
|
|
62
62
|
}
|
|
63
63
|
}
|
|
64
64
|
|
|
65
|
-
export
|
|
65
|
+
export type ResolvedSettings = Required<Omit<PiQQSettings, "debug">>;
|
|
66
66
|
|
|
67
67
|
/** Settings with defaults applied (features-v1.md §4). */
|
|
68
68
|
export function getSettings(config: PiQQConfig): ResolvedSettings {
|
package/src/download.ts
CHANGED
|
@@ -79,7 +79,7 @@ export async function downloadLimited(opts: DownloadOptions): Promise<Buffer> {
|
|
|
79
79
|
return await readBodyLimited(response, limit, opts.kind);
|
|
80
80
|
} catch (err) {
|
|
81
81
|
if (controller.signal.aborted) {
|
|
82
|
-
throw new Error(`download timed out after ${opts.timeoutMs / 1000}s
|
|
82
|
+
throw new Error(`download timed out after ${opts.timeoutMs / 1000}s`, { cause: err });
|
|
83
83
|
}
|
|
84
84
|
throw err;
|
|
85
85
|
} finally {
|
package/src/files.ts
CHANGED
|
@@ -55,6 +55,8 @@ export function uploadIndexPath(uploadDir: string): string {
|
|
|
55
55
|
export function sanitizeFilename(filename: string | undefined, fallback: string): string {
|
|
56
56
|
const raw = basename((filename ?? "").trim());
|
|
57
57
|
const cleaned = raw
|
|
58
|
+
// Control characters are rejected intentionally when normalizing a filename.
|
|
59
|
+
// eslint-disable-next-line no-control-regex
|
|
58
60
|
.replace(/[\u0000-\u001f\u007f<>:"|?*]/g, "_")
|
|
59
61
|
.replace(/^[.\s]+|[.\s]+$/g, "")
|
|
60
62
|
.trim();
|
|
@@ -152,7 +154,6 @@ async function saveOrReuse(
|
|
|
152
154
|
// A stale index entry must not make a missing file look reusable.
|
|
153
155
|
if (index[filename]) {
|
|
154
156
|
delete index[filename];
|
|
155
|
-
changed = true;
|
|
156
157
|
}
|
|
157
158
|
await writeFile(target, body, { flag: "wx" });
|
|
158
159
|
index[filename] = hash;
|
|
@@ -187,7 +188,6 @@ async function saveOrReuse(
|
|
|
187
188
|
|
|
188
189
|
if (index[candidate]) {
|
|
189
190
|
delete index[candidate];
|
|
190
|
-
changed = true;
|
|
191
191
|
}
|
|
192
192
|
await writeFile(candidatePath, body, { flag: "wx" });
|
|
193
193
|
index[candidate] = hash;
|
package/src/run-feedback.ts
CHANGED
|
@@ -97,7 +97,6 @@ export function formatHeartbeat(elapsedMs: number, tools: Map<string, ToolStat2>
|
|
|
97
97
|
return `⏱ Running for ${elapsedText} · ${parts.join(" · ")}${suffix}`;
|
|
98
98
|
}
|
|
99
99
|
|
|
100
|
-
const STREAM_LIVENESS_MS = 60_000; // Add a liveness row after this much silence
|
|
101
100
|
const TYPING_INTERVAL_MS = 50_000; // Platform typing window ~60s; renew early
|
|
102
101
|
const PENDING_TTL_MS = 15_000; // QQ trigger TTL (older means a local run)
|
|
103
102
|
|
|
@@ -116,6 +115,11 @@ export class RunFeedback {
|
|
|
116
115
|
this.pending = { openid, msgId, at: Date.now() };
|
|
117
116
|
}
|
|
118
117
|
|
|
118
|
+
/** Whether a QQ-triggered run is active. Local pi runs have no RunFeedback state. */
|
|
119
|
+
isQQRunActive(): boolean {
|
|
120
|
+
return this.run !== null;
|
|
121
|
+
}
|
|
122
|
+
|
|
119
123
|
onAgentStart(): void {
|
|
120
124
|
const pending = this.pending;
|
|
121
125
|
this.pending = null;
|