@chen_hu_hu/pi-qq 1.3.6 → 1.4.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/CHANGELOG.md +21 -1
- package/README-zh.md +1 -1
- package/README.md +1 -1
- package/doc/archive/delivery-v4.md +327 -0
- package/doc/todo.md +107 -2
- package/index.ts +64 -0
- package/package.json +1 -1
- package/src/attachments/file-attachments.ts +1 -2
- package/src/infra/file-logger.ts +0 -1
- package/src/infra/power-status.ts +1 -3
- package/src/infra/settings.ts +0 -4
- package/src/qq/inbound-attachments.ts +0 -6
- package/src/qq/inbound-command.ts +7 -1
- package/src/qq/qq-diagnostics.ts +2 -6
- package/src/qq/qr-login.ts +0 -2
- package/src/qq/reply-sender.ts +5 -1
- package/src/relay/bubble-writer.ts +109 -32
- package/src/relay/run-stream-relay.ts +165 -30
- package/src/relay/stream-block-format.ts +139 -26
- package/src/relay/stream-session.ts +27 -4
- package/doc/archive/README.md +0 -18
- package/doc/archive/delivery-v1-zh.md +0 -161
- package/doc/archive/delivery-v2-zh.md +0 -101
- package/doc/archive/delivery-v3-zh.md +0 -190
- package/doc/bugfix-v4.md +0 -698
- package/doc/enhance-status.md +0 -427
- package/doc/send-skill.md +0 -257
- package/doc/tool-return.md +0 -378
|
@@ -6,7 +6,7 @@ export function thinkingHeader(): string {
|
|
|
6
6
|
const ARG_MAX_CHARS = 200;
|
|
7
7
|
const RESULT_MAX_CHARS = 600;
|
|
8
8
|
const RESULT_MAX_LINES = 8;
|
|
9
|
-
const ARG_KEYS = ["command", "path", "file_path", "filename", "pattern", "query", "url"];
|
|
9
|
+
const ARG_KEYS = ["command", "path", "file_path", "filename", "pattern", "query", "url"] as const;
|
|
10
10
|
const TOOL_ICONS: Record<string, string> = {
|
|
11
11
|
bash: "💻",
|
|
12
12
|
read: "📖",
|
|
@@ -51,24 +51,32 @@ function truncateText(text: string, maxChars: number, maxLines: number): string
|
|
|
51
51
|
return truncated ? `${out}…` : out;
|
|
52
52
|
}
|
|
53
53
|
|
|
54
|
-
function
|
|
55
|
-
|
|
56
|
-
if (typeof args === "
|
|
57
|
-
value = args;
|
|
58
|
-
} else if (args && typeof args === "object") {
|
|
54
|
+
function stringArg(args: unknown, keys: readonly string[]): string | undefined {
|
|
55
|
+
if (typeof args === "string") return args;
|
|
56
|
+
if (args && typeof args === "object") {
|
|
59
57
|
const record = args as Record<string, unknown>;
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
58
|
+
for (const key of keys) {
|
|
59
|
+
const candidate = record[key];
|
|
60
|
+
if (typeof candidate === "string" && candidate.length > 0) return candidate;
|
|
61
|
+
}
|
|
62
|
+
return undefined;
|
|
63
|
+
}
|
|
64
|
+
if (args !== undefined && args !== null) return String(args);
|
|
65
|
+
return undefined;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function rawPrimaryArg(args: unknown, keys: readonly string[] = ARG_KEYS): string | undefined {
|
|
69
|
+
return stringArg(args, keys);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function primaryArg(args: unknown): string {
|
|
73
|
+
let value = rawPrimaryArg(args);
|
|
74
|
+
if (!value && args && typeof args === "object") {
|
|
75
|
+
try {
|
|
76
|
+
value = JSON.stringify(args);
|
|
77
|
+
} catch {
|
|
78
|
+
value = String(args);
|
|
69
79
|
}
|
|
70
|
-
} else if (args !== undefined && args !== null) {
|
|
71
|
-
value = String(args);
|
|
72
80
|
}
|
|
73
81
|
const normalized = (value ?? "").replace(/\s+/g, " ").trim();
|
|
74
82
|
return normalized.length > ARG_MAX_CHARS ? `${normalized.slice(0, ARG_MAX_CHARS)}…` : normalized;
|
|
@@ -78,10 +86,6 @@ export interface SkillRead {
|
|
|
78
86
|
name: string;
|
|
79
87
|
}
|
|
80
88
|
|
|
81
|
-
/**
|
|
82
|
-
* Detect a read of a SKILL.md file. pi renders this as "[skill]" in the TUI;
|
|
83
|
-
* QQ should show a dedicated skill block instead of a generic read tool.
|
|
84
|
-
*/
|
|
85
89
|
export function detectSkillRead(toolName: string, args: unknown): SkillRead | undefined {
|
|
86
90
|
if (toolName !== "read" || !args || typeof args !== "object") return undefined;
|
|
87
91
|
const record = args as Record<string, unknown>;
|
|
@@ -99,9 +103,114 @@ export function formatSkillBlock(name: string): string {
|
|
|
99
103
|
}
|
|
100
104
|
|
|
101
105
|
export function formatToolLine(name: string, args: unknown): string {
|
|
106
|
+
const lowerName = name.toLowerCase();
|
|
107
|
+
const label = `${TOOL_ICONS[lowerName] ?? "🔧"} ${name}`;
|
|
108
|
+
const header = `## ${label}`;
|
|
109
|
+
|
|
110
|
+
if (lowerName === "bash") {
|
|
111
|
+
const command = rawPrimaryArg(args, ["command"]);
|
|
112
|
+
const formatted = command ? formatBashCommand(command) : "";
|
|
113
|
+
return formatted ? `${header}\n\n${formatted}` : header;
|
|
114
|
+
}
|
|
115
|
+
|
|
102
116
|
const primary = primaryArg(args);
|
|
103
|
-
|
|
104
|
-
|
|
117
|
+
return primary ? `${header}\n\n${inlineCode(primary)}` : header;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function formatBashCommand(command: string): string {
|
|
121
|
+
const normalized = command
|
|
122
|
+
.replace(/\r\n?/g, "\n")
|
|
123
|
+
.replace(/[ \t]+$/gm, "")
|
|
124
|
+
.trim();
|
|
125
|
+
if (!normalized) return "";
|
|
126
|
+
const fence = backtickFence(normalized, 3);
|
|
127
|
+
return `${fence}bash\n${normalized}\n${fence}`;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
const EXTENSION_LANGUAGES: Record<string, string> = {
|
|
131
|
+
md: "markdown",
|
|
132
|
+
markdown: "markdown",
|
|
133
|
+
mdx: "markdown",
|
|
134
|
+
html: "html",
|
|
135
|
+
htm: "html",
|
|
136
|
+
xml: "xml",
|
|
137
|
+
svg: "xml",
|
|
138
|
+
tex: "latex",
|
|
139
|
+
rst: "rst",
|
|
140
|
+
css: "css",
|
|
141
|
+
scss: "scss",
|
|
142
|
+
less: "less",
|
|
143
|
+
vue: "vue",
|
|
144
|
+
svelte: "svelte",
|
|
145
|
+
json: "json",
|
|
146
|
+
jsonc: "json",
|
|
147
|
+
json5: "json",
|
|
148
|
+
ipynb: "json",
|
|
149
|
+
yaml: "yaml",
|
|
150
|
+
yml: "yaml",
|
|
151
|
+
toml: "toml",
|
|
152
|
+
ini: "ini",
|
|
153
|
+
cfg: "ini",
|
|
154
|
+
conf: "ini",
|
|
155
|
+
sql: "sql",
|
|
156
|
+
graphql: "graphql",
|
|
157
|
+
gql: "graphql",
|
|
158
|
+
proto: "protobuf",
|
|
159
|
+
ts: "typescript",
|
|
160
|
+
mts: "typescript",
|
|
161
|
+
cts: "typescript",
|
|
162
|
+
tsx: "tsx",
|
|
163
|
+
js: "javascript",
|
|
164
|
+
mjs: "javascript",
|
|
165
|
+
cjs: "javascript",
|
|
166
|
+
jsx: "jsx",
|
|
167
|
+
py: "python",
|
|
168
|
+
pyw: "python",
|
|
169
|
+
sh: "bash",
|
|
170
|
+
bash: "bash",
|
|
171
|
+
zsh: "bash",
|
|
172
|
+
fish: "fish",
|
|
173
|
+
ps1: "powershell",
|
|
174
|
+
bat: "bat",
|
|
175
|
+
cmd: "bat",
|
|
176
|
+
go: "go",
|
|
177
|
+
rs: "rust",
|
|
178
|
+
java: "java",
|
|
179
|
+
kt: "kotlin",
|
|
180
|
+
kts: "kotlin",
|
|
181
|
+
c: "c",
|
|
182
|
+
h: "c",
|
|
183
|
+
cpp: "cpp",
|
|
184
|
+
cc: "cpp",
|
|
185
|
+
cxx: "cpp",
|
|
186
|
+
hpp: "cpp",
|
|
187
|
+
cs: "csharp",
|
|
188
|
+
rb: "ruby",
|
|
189
|
+
php: "php",
|
|
190
|
+
swift: "swift",
|
|
191
|
+
dart: "dart",
|
|
192
|
+
lua: "lua",
|
|
193
|
+
r: "r",
|
|
194
|
+
pl: "perl",
|
|
195
|
+
diff: "diff",
|
|
196
|
+
patch: "diff",
|
|
197
|
+
};
|
|
198
|
+
|
|
199
|
+
function languageForPath(filePath: string): string {
|
|
200
|
+
const base = filePath.trim().split(/[\\/]/).pop()?.toLowerCase() ?? "";
|
|
201
|
+
if (base === "dockerfile") return "dockerfile";
|
|
202
|
+
if (base === "makefile") return "makefile";
|
|
203
|
+
if (base === "cmakelists.txt") return "cmake";
|
|
204
|
+
if (base === "readme") return "markdown";
|
|
205
|
+
const ext = base.includes(".") ? base.slice(base.lastIndexOf(".") + 1) : "";
|
|
206
|
+
return EXTENSION_LANGUAGES[ext] ?? "text";
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
export function resultLanguage(toolName: string, args: unknown, isError: boolean): string {
|
|
210
|
+
if (isError) return "text";
|
|
211
|
+
if (toolName.toLowerCase() !== "read") return "text";
|
|
212
|
+
const path = rawPrimaryArg(args, ["path", "file_path"]);
|
|
213
|
+
return path ? languageForPath(path) : "text";
|
|
105
214
|
}
|
|
106
215
|
|
|
107
216
|
function resultText(result: unknown): string {
|
|
@@ -134,12 +243,16 @@ function resultText(result: unknown): string {
|
|
|
134
243
|
}
|
|
135
244
|
}
|
|
136
245
|
|
|
137
|
-
export function formatToolResult(result: unknown, isError: boolean): string {
|
|
246
|
+
export function formatToolResult(result: unknown, isError: boolean, language = "text"): string {
|
|
138
247
|
let text = resultText(result);
|
|
139
248
|
text = text.replace(/\r\n/g, "\n").replace(/\s+$/, "");
|
|
140
|
-
if (!text)
|
|
249
|
+
if (!text) {
|
|
250
|
+
text = t("stream.noOutput");
|
|
251
|
+
language = "text";
|
|
252
|
+
}
|
|
141
253
|
text = truncateText(text, RESULT_MAX_CHARS, RESULT_MAX_LINES);
|
|
142
254
|
if (isError) text = `❌ ${text}`;
|
|
255
|
+
language = isError || !/^[a-z0-9+#.-]+$/i.test(language) ? "text" : language;
|
|
143
256
|
const fence = backtickFence(text, 3);
|
|
144
|
-
return `${fence}
|
|
257
|
+
return `${fence}${language}\n${text}\n${fence}\n`;
|
|
145
258
|
}
|
|
@@ -18,12 +18,21 @@ export interface AppendStreamCheckpoint {
|
|
|
18
18
|
buffer?: string;
|
|
19
19
|
}
|
|
20
20
|
|
|
21
|
+
export interface AppendStreamFrameInfo {
|
|
22
|
+
index: number;
|
|
23
|
+
state: "generating" | "done";
|
|
24
|
+
msgSeq: number | null;
|
|
25
|
+
streamMsgId?: string;
|
|
26
|
+
bufferLength: number;
|
|
27
|
+
}
|
|
28
|
+
|
|
21
29
|
export interface AppendStreamOptions {
|
|
22
30
|
throttleMs?: number;
|
|
23
31
|
retryBaseMs?: number;
|
|
24
32
|
resume?: AppendStreamCheckpoint;
|
|
25
33
|
onError?: (err: Error) => void;
|
|
26
34
|
onDebug?: (message: string) => void;
|
|
35
|
+
onFrameError?: (err: unknown, info: AppendStreamFrameInfo) => void;
|
|
27
36
|
}
|
|
28
37
|
|
|
29
38
|
export class AppendStream {
|
|
@@ -131,7 +140,9 @@ export class AppendStream {
|
|
|
131
140
|
if (this.flushing) return;
|
|
132
141
|
const content = state === "done" ? "" : this.buffer;
|
|
133
142
|
if (!content && state === "generating") return;
|
|
134
|
-
this.opts.onDebug?.(
|
|
143
|
+
this.opts.onDebug?.(
|
|
144
|
+
`flush: start state=${state}, content=${content.length}, index=${this.index}, msgSeq=${this.msgSeq ?? "none"}, streamMsgId=${this.streamMsgId ?? "none"}`,
|
|
145
|
+
);
|
|
135
146
|
this.flushing = true;
|
|
136
147
|
let failed = false;
|
|
137
148
|
try {
|
|
@@ -148,11 +159,13 @@ export class AppendStream {
|
|
|
148
159
|
index,
|
|
149
160
|
...(this.streamMsgId ? { stream_msg_id: this.streamMsgId } : {}),
|
|
150
161
|
} as unknown as StreamMessageRequest;
|
|
151
|
-
const resp = await this.sendWithRetry(req);
|
|
162
|
+
const resp = await this.sendWithRetry(req, state);
|
|
152
163
|
if (resp?.id && !this.streamMsgId) this.streamMsgId = resp.id;
|
|
153
164
|
if (state === "generating") this.buffer = this.buffer.slice(content.length);
|
|
154
165
|
this.lastFlushAt = Date.now();
|
|
155
|
-
this.opts.onDebug?.(
|
|
166
|
+
this.opts.onDebug?.(
|
|
167
|
+
`flush: done state=${state}, remaining=${this.buffer.length}, streamMsgId=${this.streamMsgId ?? "none"}`,
|
|
168
|
+
);
|
|
156
169
|
} catch (err) {
|
|
157
170
|
failed = true;
|
|
158
171
|
throw err;
|
|
@@ -167,7 +180,10 @@ export class AppendStream {
|
|
|
167
180
|
}
|
|
168
181
|
}
|
|
169
182
|
|
|
170
|
-
private async sendWithRetry(
|
|
183
|
+
private async sendWithRetry(
|
|
184
|
+
req: StreamMessageRequest,
|
|
185
|
+
state: "generating" | "done",
|
|
186
|
+
): Promise<MessageResponse | undefined> {
|
|
171
187
|
const base = this.opts.retryBaseMs ?? RATE_LIMIT_BASE_MS;
|
|
172
188
|
for (let attempt = 0; ; attempt++) {
|
|
173
189
|
try {
|
|
@@ -175,6 +191,13 @@ export class AppendStream {
|
|
|
175
191
|
} catch (err) {
|
|
176
192
|
const reason = err instanceof Error ? err.message : String(err);
|
|
177
193
|
if (attempt >= MAX_RETRIES || !this.isRateLimitError(err)) {
|
|
194
|
+
this.opts.onFrameError?.(err, {
|
|
195
|
+
index: req.index,
|
|
196
|
+
state,
|
|
197
|
+
msgSeq: this.msgSeq,
|
|
198
|
+
...(this.streamMsgId ? { streamMsgId: this.streamMsgId } : {}),
|
|
199
|
+
bufferLength: this.buffer.length,
|
|
200
|
+
});
|
|
178
201
|
this.opts.onDebug?.(t("log.streamFrameFailed", { index: req.index, attempts: attempt + 1, reason }));
|
|
179
202
|
throw err;
|
|
180
203
|
}
|
package/doc/archive/README.md
DELETED
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
# Archived delivery records
|
|
2
|
-
|
|
3
|
-
These documents record how pi-qq was delivered at each milestone. They are
|
|
4
|
-
historical snapshots, not current documentation.
|
|
5
|
-
|
|
6
|
-
- They may reference modules, settings, or behaviors that have since been
|
|
7
|
-
removed (for example the image-specific pipeline and `imageMaxSize`).
|
|
8
|
-
- Do not update them to match current behavior; write current documentation in
|
|
9
|
-
`README.md`, `README-zh.md`, and `CHANGELOG.md` instead.
|
|
10
|
-
- File and line details in these records are intentionally frozen.
|
|
11
|
-
|
|
12
|
-
# 归档交付记录
|
|
13
|
-
|
|
14
|
-
本目录保存 pi-qq 各里程碑的交付记录,仅作历史快照,不是当前文档。
|
|
15
|
-
|
|
16
|
-
- 文中可能引用已删除的模块、配置或行为(例如图片专用链路和 `imageMaxSize`)。
|
|
17
|
-
- 不要把这些文档更新为当前行为;现行说明请写入 `README.md`、`README-zh.md` 和 `CHANGELOG.md`。
|
|
18
|
-
- 文件与行号等细节按当时状态保留。
|
|
@@ -1,161 +0,0 @@
|
|
|
1
|
-
# pi-qq delivery-v1
|
|
2
|
-
|
|
3
|
-
> **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
|
|
4
|
-
> 状态:v1 已交付,作为后续版本的历史基线。
|
|
5
|
-
> 后续版本见 [delivery-v2-zh.md](./delivery-v2-zh.md)、[delivery-v3-zh.md](./delivery-v3-zh.md)。
|
|
6
|
-
|
|
7
|
-
## 1. 交付范围
|
|
8
|
-
|
|
9
|
-
v1 将 pi 接入 QQ 单人私聊(C2C):
|
|
10
|
-
|
|
11
|
-
- 手机 QQ 发送文字、图片、文件;
|
|
12
|
-
- pi 在用户电脑上执行任务;
|
|
13
|
-
- assistant 文本回传到 QQ;
|
|
14
|
-
- 登录、命令、回复预算和连接生命周期可管理。
|
|
15
|
-
|
|
16
|
-
技术栈:
|
|
17
|
-
|
|
18
|
-
| 依赖 | 用途 |
|
|
19
|
-
| ---------------------------------- | ------------------------------------------------ |
|
|
20
|
-
| `@tencent-connect/qqbot-nodejs` | QQ 协议层:Gateway、C2C 消息、媒体上传、流式消息 |
|
|
21
|
-
| `@tencent-connect/qqbot-connector` | 扫码登录,凭据只保存在进程内存 |
|
|
22
|
-
| `@earendil-works/pi-coding-agent` | pi 扩展宿主、事件订阅、消息注入、上下文信息 |
|
|
23
|
-
|
|
24
|
-
## 2. 架构
|
|
25
|
-
|
|
26
|
-
扩展以目录形式加载,在 pi 进程内持有 QQBot:
|
|
27
|
-
|
|
28
|
-
```text
|
|
29
|
-
手机 QQ(C2C)
|
|
30
|
-
│ WebSocket Gateway
|
|
31
|
-
▼
|
|
32
|
-
QQBot
|
|
33
|
-
│ message
|
|
34
|
-
▼
|
|
35
|
-
pi-qq:白名单 → QQ 命令 → 文本/图片/文件
|
|
36
|
-
│ pi.sendUserMessage()
|
|
37
|
-
▼
|
|
38
|
-
pi 会话
|
|
39
|
-
│ message_update / message_end / agent_end
|
|
40
|
-
▼
|
|
41
|
-
pi-qq:格式化 → QQ 文本/流式消息
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
- QQ → pi:白名单校验后注入文本和图片;文件保存在工作区。
|
|
45
|
-
- pi → QQ:订阅 assistant 消息并回传;长任务使用独立的反馈时间线。
|
|
46
|
-
- 生命周期:`session_start` 启动 bot,`session_shutdown` 幂等停止。
|
|
47
|
-
- 断线重连由 SDK 负责;致命关闭码 4914/4915 给出明确错误。
|
|
48
|
-
|
|
49
|
-
## 3. 功能
|
|
50
|
-
|
|
51
|
-
### F1 扫码登录
|
|
52
|
-
|
|
53
|
-
- 只支持 `/qq-login` 扫码登录。
|
|
54
|
-
- 凭据只保存在进程内存,不写入配置文件;重启 pi 后重新扫码。
|
|
55
|
-
- 成功后绑定扫码用户 openid,其他 C2C 用户静默忽略。
|
|
56
|
-
- `/qq-logout` 清除凭据并断开连接。
|
|
57
|
-
- `/qq-status` 显示登录、连接、模型、上下文和绑定用户;AppID 脱敏。
|
|
58
|
-
|
|
59
|
-
### F2 单人聊天
|
|
60
|
-
|
|
61
|
-
- 只接受白名单用户的 C2C 消息。
|
|
62
|
-
- 文本通过 `pi.sendUserMessage()` 注入 pi。
|
|
63
|
-
- 忙碌时按 `deliverAs`(`steer` 或 `followUp`)排队。
|
|
64
|
-
- QQ 侧命令:`/new`、`/stop`、`/compact`、`/status`、`/help`。
|
|
65
|
-
- 运行期间发送 typing 指示。
|
|
66
|
-
|
|
67
|
-
### F3 图片和文件
|
|
68
|
-
|
|
69
|
-
图片:
|
|
70
|
-
|
|
71
|
-
- 下载后校验类型和大小,转换为 pi 的 `ImageContent`。
|
|
72
|
-
- 支持 jpg/jpeg/png/webp/gif;不支持的 `image/*` 明确拒绝。
|
|
73
|
-
- 单张超时 15 秒,默认上限 10MB。
|
|
74
|
-
- 部分图片失败时,成功图片仍注入,并回传失败清单。
|
|
75
|
-
- 当前模型不支持视觉输入时提示并跳过图片。
|
|
76
|
-
|
|
77
|
-
文件:
|
|
78
|
-
|
|
79
|
-
- 保存到 `.pi/pi-qq/YYYY-MM-DD/<msgId>/`;v2+ 使用按会话隔离的 `.pi/pi-qq/<sessionId>/uploads/`。提示词附带绝对路径、大小和原始文件名。
|
|
80
|
-
- 单文件超时 60 秒,默认上限 50MB。
|
|
81
|
-
- 文件名安全化;同名文件自动追加 `-1`、`-2`。
|
|
82
|
-
- 文件内容不直接注入模型,由工具按需读取。
|
|
83
|
-
|
|
84
|
-
### F4 assistant 回传
|
|
85
|
-
|
|
86
|
-
- 数据源是 assistant 的 `message_end`。
|
|
87
|
-
- Markdown 转纯文本:去强调/标题/行内代码标记,列表转 `•`,链接转文字和 URL。
|
|
88
|
-
- 长文本按 `TEXT_CHUNK_LIMIT` 分块发送。
|
|
89
|
-
- 支持 C2C 流式追加;平台失败时降级为普通消息路径。
|
|
90
|
-
- `stopReason === "error"` 时回传错误摘要。
|
|
91
|
-
|
|
92
|
-
### F5/F6 用量摘要
|
|
93
|
-
|
|
94
|
-
已取消。不再发送 token、缓存、成本和上下文明细;上下文通过 `/status` / `/qq-status` 查看。
|
|
95
|
-
|
|
96
|
-
### F7 长任务反馈
|
|
97
|
-
|
|
98
|
-
v1 曾使用窗口汇总、工具计数和消息心跳维持长任务活性。该实现已在 v3 被 F12/F13 取代;v1 历史行为不代表当前版本。
|
|
99
|
-
|
|
100
|
-
## 4. 平台限制与预算
|
|
101
|
-
|
|
102
|
-
| 限制 | 应对 |
|
|
103
|
-
| ------------------------------------- | ------------------------------------------------- |
|
|
104
|
-
| 被动回复约 4 条 / 小时(SDK limiter) | `ReplyBudget` 记录 `msgId` 配额,超限降级主动发送 |
|
|
105
|
-
| 流式消息仅 C2C,节流 ≥300ms | `AppendStream` 负责合帧和退避 |
|
|
106
|
-
| 单条文本约 5000 字符 | 自动分块 |
|
|
107
|
-
| 流式消息依赖 5 分钟内的 `msgId` | 过期后降级为普通消息 |
|
|
108
|
-
|
|
109
|
-
## 5. 配置与命令
|
|
110
|
-
|
|
111
|
-
`~/.pi/agent/pi-qq.json` 只保存设置,不保存凭据。
|
|
112
|
-
|
|
113
|
-
| 配置 | 默认 | 说明 |
|
|
114
|
-
| --------------- | ---------- | ---------------------------------------- |
|
|
115
|
-
| `thinkingRelay` | `true` | 回传思考正文 |
|
|
116
|
-
| `deliverAs` | `"steer"` | 忙碌时新消息的排队方式 |
|
|
117
|
-
| `imageMaxSize` | 10MB | 图片下载上限 |
|
|
118
|
-
| `fileMaxSize` | 50MB | 文件下载上限 |
|
|
119
|
-
| `logLevel` | `"silent"` | 日志阈值 |
|
|
120
|
-
| `debug` | 仅迁移读取 | `debug: true` 映射为 `logLevel: "debug"` |
|
|
121
|
-
|
|
122
|
-
pi 侧命令:`/qq-login`、`/qq-status`、`/qq-logout`、`/qq-test-budget`、`/qq-test-md`、`/qq-test-stream`、`/qq-new`。
|
|
123
|
-
|
|
124
|
-
QQ 侧命令:`/new`、`/stop`、`/compact`、`/status`、`/help`。
|
|
125
|
-
|
|
126
|
-
## 6. 模块与边界(v1 基线)
|
|
127
|
-
|
|
128
|
-
<!-- prettier-ignore -->
|
|
129
|
-
| 模块 | 职责 |
|
|
130
|
-
| ---------------------------- | ------------------------------------ |
|
|
131
|
-
| `index.ts` | 扩展装配、事件订阅、命令注册 |
|
|
132
|
-
| `src/infra/settings.ts` | 只读配置与迁移 |
|
|
133
|
-
| `src/qq/qr-login.ts` | 扫码登录 |
|
|
134
|
-
| `src/qq/qq-bot.ts` | QQBot 生命周期、Gateway 状态、中间件 |
|
|
135
|
-
| `src/qq/qq-message-handler.ts` | 入站路由、命令、附件处理、注入 pi |
|
|
136
|
-
| `src/attachments/image-attachments.ts` | 图片校验与 `ImageContent` |
|
|
137
|
-
| `src/attachments/file-attachments.ts` | 文件保存、索引、提示词关联 |
|
|
138
|
-
| `src/attachments/attachment-download.ts` | 图片/文件通用限流下载 |
|
|
139
|
-
| `src/qq/reply-sender.ts` | Markdown 转换、分块、发送 |
|
|
140
|
-
| `src/quota/reply-quota.ts` | 被动回复预算 |
|
|
141
|
-
| `src/quota/reply-quota-report.ts` | 预算诊断格式化 |
|
|
142
|
-
| `src/infra/display-format.ts` | 字节与 token 格式化 |
|
|
143
|
-
| `src/infra/file-logger.ts` | 文件日志 |
|
|
144
|
-
| `src/relay/run-stream-relay.ts` | 长任务反馈状态机 |
|
|
145
|
-
| `src/relay/stream-session.ts` | 流式追加、重试、续写检查点 |
|
|
146
|
-
|
|
147
|
-
边界原则:入口只做装配;协议、存储、格式化、预算分别放在独立模块;模块通过显式参数和 `RunFeedbackDeps` 之类的接口通信。
|
|
148
|
-
|
|
149
|
-
## 7. 验证
|
|
150
|
-
|
|
151
|
-
- 扫码登录、`/qq-status`、`/qq-logout` 实测通过。
|
|
152
|
-
- QQ 文本触发 pi,回复回传 QQ。
|
|
153
|
-
- 图片作为视觉输入、文件保存和提示词路径关联实测通过。
|
|
154
|
-
- 被动回复预算实测不超限;异常路径可降级主动发送。
|
|
155
|
-
|
|
156
|
-
## 8. 已知限制
|
|
157
|
-
|
|
158
|
-
- 仅支持 C2C 私聊。
|
|
159
|
-
- 登录凭据在进程内存,重启后必须重新扫码。
|
|
160
|
-
- 不提供开始确认和用量摘要,减少被动消息。
|
|
161
|
-
- 历史流式/心跳实现已由 v3 取代,不应作为当前行为参考。
|
|
@@ -1,101 +0,0 @@
|
|
|
1
|
-
# pi-qq delivery-v2
|
|
2
|
-
|
|
3
|
-
> **归档记录。** 内容反映当时的交付状态,可能引用已删除的模块或配置;当前行为见 [README-zh.md](../../README-zh.md)。
|
|
4
|
-
> 状态:v2 已交付,本文为历史记录。
|
|
5
|
-
> 前序版本:[delivery-v1-zh.md](./delivery-v1-zh.md);后续版本:[delivery-v3-zh.md](./delivery-v3-zh.md)。
|
|
6
|
-
|
|
7
|
-
## 1. 交付范围
|
|
8
|
-
|
|
9
|
-
v2 在 v1 的 QQ 私聊、图片和文件能力上增加:
|
|
10
|
-
|
|
11
|
-
- F8 语音消息自动转写;
|
|
12
|
-
- F9 结构化日志基础设施;
|
|
13
|
-
- F10 文件消息等待下一条指令;
|
|
14
|
-
- F11 文件保存路径、索引和去重。
|
|
15
|
-
|
|
16
|
-
## 2. 功能
|
|
17
|
-
|
|
18
|
-
### F8 语音消息
|
|
19
|
-
|
|
20
|
-
- 使用 QQ 内置 ASR(`asr_refer_text`),不下载音频。
|
|
21
|
-
- 转写文本作为普通用户文本交给 pi。
|
|
22
|
-
- ASR 无结果时回复 `Could not transcribe this voice message; please resend or type it.`,不启动 run。
|
|
23
|
-
- 不依赖本地或外部语音识别服务。
|
|
24
|
-
- 原始 ASR 结果和附件元数据只在 `debug` 日志中记录。
|
|
25
|
-
|
|
26
|
-
### F9 日志
|
|
27
|
-
|
|
28
|
-
- 按天写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`。
|
|
29
|
-
- `PI_QQ_LOG_DIR` 可覆盖目录。
|
|
30
|
-
- 阈值:`silent`、`error`、`warn`、`info`、`debug`。
|
|
31
|
-
- `info` 只记录元数据;`debug` 记录完整事件、附件、提示词和工具参数/结果。
|
|
32
|
-
- 日志 JSONL 化,错误对象带名称、消息和堆栈。
|
|
33
|
-
- 旧配置 `debug: true` 映射为 `logLevel: "debug"`。
|
|
34
|
-
|
|
35
|
-
### F10 文件等待指令
|
|
36
|
-
|
|
37
|
-
- 只发送文件不会启动 pi;文件先保存并进入 pending。
|
|
38
|
-
- 下一条文字或语音指令会消费 pending 文件,并在提示词中附带路径、大小和原始文件名。
|
|
39
|
-
- 指令前上传多个文件会合并到同一个提示词。
|
|
40
|
-
- `/new` 清空 pending。
|
|
41
|
-
- 文件按当前 pi 会话隔离。
|
|
42
|
-
|
|
43
|
-
### F11 文件存储与去重
|
|
44
|
-
|
|
45
|
-
- 保存在当前工作区 `.pi/pi-qq/<sessionId>/uploads/`。
|
|
46
|
-
- 同名同内容复用已有文件。
|
|
47
|
-
- 同名不同内容保存为 `name-1.ext`。
|
|
48
|
-
- 不同名同内容分别保存。
|
|
49
|
-
- 索引只记录文件名到哈希的映射;路径和大小来自文件系统。启动时清理失效索引。
|
|
50
|
-
- pending 文件与索引解耦,`/new` 不影响已保存的索引文件。
|
|
51
|
-
|
|
52
|
-
## 3. 配置
|
|
53
|
-
|
|
54
|
-
v2 继续使用:
|
|
55
|
-
|
|
56
|
-
| 配置 | 默认 | 说明 |
|
|
57
|
-
| --------------- | ---------- | -------------------- |
|
|
58
|
-
| `thinkingRelay` | `true` | 思考正文回传开关 |
|
|
59
|
-
| `deliverAs` | `"steer"` | 忙碌时的消息排队方式 |
|
|
60
|
-
| `imageMaxSize` | 10MB | 图片下载上限 |
|
|
61
|
-
| `fileMaxSize` | 50MB | 文件下载上限 |
|
|
62
|
-
| `logLevel` | `"silent"` | 日志阈值 |
|
|
63
|
-
| `debug` | 仅迁移读取 | 旧日志开关迁移 |
|
|
64
|
-
|
|
65
|
-
## 4. 模块与边界
|
|
66
|
-
|
|
67
|
-
<!-- prettier-ignore -->
|
|
68
|
-
| 模块 | 职责 |
|
|
69
|
-
| ---------------------------- | ------------------------------------ |
|
|
70
|
-
| `src/qq/qq-message-handler.ts` | 语音/文件/文本统一入站路由;命令拦截 |
|
|
71
|
-
| `src/attachments/voice-transcript.ts` | ASR 文本提取与可用性判断 |
|
|
72
|
-
| `src/attachments/file-attachments.ts` | 文件保存、哈希、索引、pending 提示词 |
|
|
73
|
-
| `src/attachments/attachment-download.ts` | 图片和文件共用下载约束 |
|
|
74
|
-
| `src/attachments/image-attachments.ts` | 图片校验与视觉输入组装 |
|
|
75
|
-
| `src/infra/file-logger.ts` | 日志级别、格式化、按天写入 |
|
|
76
|
-
| `src/qq/reply-sender.ts` | Markdown 转换、分块、发送 |
|
|
77
|
-
| `src/quota/reply-quota.ts` | 被动回复预算 |
|
|
78
|
-
|
|
79
|
-
边界原则:
|
|
80
|
-
|
|
81
|
-
- `qq-message-handler` 只负责路由,不自行实现下载或存储细节;
|
|
82
|
-
- `voice-transcript` 不接触文件系统;
|
|
83
|
-
- `file-attachments` 负责保存和索引,不负责 pi 事件;
|
|
84
|
-
- `file-logger` 不依赖业务模块;
|
|
85
|
-
- 所有附件下载都经过 `attachment-download.ts`,避免超时和大小限制分叉。
|
|
86
|
-
|
|
87
|
-
## 5. 验证
|
|
88
|
-
|
|
89
|
-
- 语音 ASR 文本注入、无文本提示、音频不落盘;
|
|
90
|
-
- 纯文件消息不启动 run,下一条指令消费文件;
|
|
91
|
-
- 多文件合并、`/new` 清空 pending;
|
|
92
|
-
- 同名同内容复用、同名不同内容加后缀、不同名同内容独立保存;
|
|
93
|
-
- 日志目录、级别、JSONL 字段和旧 `debug` 迁移;
|
|
94
|
-
- 自动化和实机测试通过。
|
|
95
|
-
|
|
96
|
-
## 6. 已知限制
|
|
97
|
-
|
|
98
|
-
- 仅使用 QQ ASR,不提供本地识别兜底。
|
|
99
|
-
- ASR 不返回文本时只能重发或改文字。
|
|
100
|
-
- 文件等待指令按当前 pi 会话隔离。
|
|
101
|
-
- 日志的 `debug` 级别会包含敏感工具参数和文件内容,只在排查问题时开启。
|