@chen_hu_hu/pi-qq 1.1.0 → 1.2.2

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/doc/plan-v2.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # pi-qq — plan-v2.md
2
2
 
3
3
  > 执行计划。功能范围见 [features-v2.md](./features-v2.md);本文只回答:改哪些文件、按什么顺序做、每步怎么验收。
4
- > V2 范围:F8 语音自动转写、F9 轻量日志基础设施。不引入新依赖。
4
+ > V2 范围:F8 语音自动转写、F9 轻量日志基础设施、F10 文件消息等待指令、F11 文件存储与去重。不引入新依赖。
5
5
 
6
6
  ## 0. 前置与范围
7
7
 
@@ -19,7 +19,8 @@ pi-qq/
19
19
  │ ├── logger.ts # 新增:级别过滤、JSONL、按天单文件、SDK logger 适配
20
20
  │ ├── voice.ts # 新增:语音附件判断、ASR 文本提取
21
21
  │ ├── config.ts # 修改:logLevel、旧 debug 迁移
22
- │ ├── inbound.ts # 修改:语音分支 + 日志分级
22
+ │ ├── inbound.ts # 修改:语音分支 + 日志分级 + pending + session uploads
23
+ │ ├── files.ts # 修改:session uploads、SHA-256 去重、索引维护
23
24
  │ ├── bot.ts # 修改:接入 logger,移除 debug 选项
24
25
  │ ├── index.ts # 修改:配置 logger,移除 getDebug,日志分级
25
26
  │ ├── outbound.ts # 修改:发送日志分级
@@ -29,6 +30,7 @@ pi-qq/
29
30
  │ ├── voice.test.ts # 新增
30
31
  │ ├── config.test.ts # 新增或扩展现有设置测试
31
32
  │ ├── inbound.test.ts # 修改
33
+ │ ├── bot.test.ts # 新增:message handler 串行回归
32
34
  │ └── run-feedback.test.ts # 修改
33
35
  ├── README.md # 修改:logLevel、日志路径、语音说明
34
36
  └── doc/features-v2.md # 已存在,按实现结果校正
@@ -148,7 +150,53 @@ pi-qq/
148
150
  - 语音消息不会出现在 `saveInboundFiles()` 的附件参数中。
149
151
  - 空 ASR 不会启动 agent。
150
152
 
151
- ### M5b-3 — 文档与清理
153
+ ### M5b-3 — F10 文件消息等待指令
154
+
155
+ **改动**
156
+
157
+ 1. `src/inbound.ts` 增加 pending 文件队列,仅处理非图片文件:
158
+ - 文件消息保存后入队,不回复,不调用 `sendUserMessage` / `markQQTrigger`。
159
+ - 下一条文字或语音 ASR 文本出队,合并后走现有 `formatFilePrompt()`。
160
+ - 消费后清空;`/new` 清空;其他命令不消费。
161
+ - 部分失败只入队成功文件;图片、普通文字、文件+文字行为不变。
162
+ 2. 更新 `test/inbound.test.ts`:
163
+ - 文件-only:保存、不回复、不发送 user message、不触发 run。
164
+ - 文件后文字:一次 run,提示词包含路径和文字。
165
+ - 连续文件:多个路径合并。
166
+ - 文件后语音:ASR 文本参与合并。
167
+ - `/new` 清空 pending。
168
+
169
+ **验证**
170
+
171
+ - `npm test -- test/inbound.test.ts` 通过。
172
+ - 文件-only 不启动 agent;下一条指令只启动一次。
173
+ - 图片行为与 v1 一致。
174
+
175
+ ### M5b-4 — F11 文件存储与去重
176
+
177
+ **改动**
178
+
179
+ 1. `src/inbound.ts`:文件保存路径改为 `<cwd>/.pi/pi-qq/<sessionId>/uploads/`,sessionId 来自 `ctx.sessionManager.getSessionId()`。
180
+ 2. `src/files.ts`:
181
+ - 增加 `.index.json` 读写:`{ "<fileName>": "<sha256>" }`。
182
+ - 文件名不重复:保存、计算 SHA-256、写索引、引用。
183
+ - 同名不同内容:保存为下一个可用后缀名,写索引、引用新文件。
184
+ - 同名同内容:不保存,复用已有路径。
185
+ - 登录/会话启动:只检查索引中的文件是否存在,删除失效项;不重算所有 hash。
186
+ - 保存/复用前再次检查目标文件存在性;索引缺失或损坏时按需计算已有文件 hash。
187
+ - `bot.ts` 的 message handler 必须 await `onMessage`,让 SDK concurrencyGuard 持有锁到文件保存完成。
188
+ 3. 更新 `test/files.test.ts` / `test/inbound.test.ts`:
189
+ - 路径、索引格式、三类保存规则。
190
+ - 删除文件后的索引清理与惰性回退。
191
+ - pending 同名同内容不重复入队;不同文件名同内容保留两份。
192
+
193
+ **验证**
194
+
195
+ - `npm test -- test/files.test.ts test/inbound.test.ts` 通过。
196
+ - 登录/会话启动只做存在性检查,不读取文件内容。
197
+ - 同名同内容不新增文件;同名不同内容生成后缀文件。
198
+
199
+ ### M5b-5 — 文档与清理
152
200
 
153
201
  **改动**
154
202
 
@@ -170,7 +218,7 @@ pi-qq/
170
218
 
171
219
  ### 准备
172
220
 
173
- - [x] 阅读 `doc/features-v2.md`,确认范围仅为 F8/F9
221
+ - [x] 阅读 `doc/features-v2.md`,确认范围仅为 F8/F9/F10/F11
174
222
  - [x] 运行基线 `npm test`、`npm run typecheck`
175
223
  - [x] 确认不新增 npm 依赖
176
224
 
@@ -199,10 +247,34 @@ pi-qq/
199
247
  - [x] `test/inbound.test.ts`:有 ASR / 空 ASR / 不保存文件
200
248
  - [x] 确认文字、图片、文件用例不回归
201
249
 
250
+ ### F10 — 文件等待指令
251
+
252
+ - [x] `src/inbound.ts`:pending 文件队列
253
+ - [x] 文件-only:保存后不回复,不启动 run
254
+ - [x] 下一条文字/语音:合并 pending 文件后注入
255
+ - [x] `/new` 清空 pending
256
+ - [x] `test/inbound.test.ts`:pending 队列相关用例
257
+ - [x] 图片、文字、文件+文字行为不回归
258
+ - [x] QQ 实机文件等待指令验收
259
+
260
+ ### F11 — 文件存储与去重
261
+
262
+ - [x] `inbound.ts`:session uploads 路径
263
+ - [x] `files.ts`:`.index.json` 读写
264
+ - [x] 文件名不重复:保存并索引
265
+ - [x] 同名不同内容:生成后缀文件
266
+ - [x] 同名同内容:复用已有文件
267
+ - [x] 登录/会话启动:清理不存在文件的索引项
268
+ - [x] 惰性检查:复用前确认文件仍存在
269
+ - [x] `test/files.test.ts` / `test/inbound.test.ts`:去重与索引用例
270
+ - [x] `bot.ts`:await message handler,确保文件保存串行
271
+ - [x] `test/bot.test.ts`:handler await 回归
272
+ - [x] QQ 实机文件去重验收(并发文件上传重测)
273
+
202
274
  ### 文档与收尾
203
275
 
204
- - [x] `README.md`:`logLevel`、日志路径、语音说明
205
- - [x] `doc/features-v2.md`:与实现保持一致
276
+ - [x] `README.md`:`logLevel`、日志路径、语音说明、文件等待指令、文件去重
277
+ - [x] `doc/features-v2.md`:F8/F9/F10/F11 与实现保持一致
206
278
  - [x] 清理临时调试说明
207
279
  - [x] `npm test`
208
280
  - [x] `npm run typecheck`
@@ -228,18 +300,33 @@ pi-qq/
228
300
  6. `logLevel: "debug"`:日志文件包含 `asr_refer_text` 和完整附件;`info` 不含正文。
229
301
  7. 旧配置 `debug: true` 仍能开启 debug 日志。
230
302
  8. 文字、图片、文件消息行为与 v1 一致。
303
+ 9. 只发文件:不回复,不启动 run。
304
+ 10. 文件后发文字/语音:只启动一次 run,提示词包含文件路径和指令。
305
+ 11. 连续上传多个文件:下一条指令合并全部文件。
306
+ 12. `/new` 后 pending 清空。
307
+ 13. 文件保存到 `.pi/pi-qq/<sessionId>/uploads/`。
308
+ 14. 文件名不重复:保存并引用。
309
+ 15. 同名不同内容:生成 `name-1.ext` 并引用。
310
+ 16. 同名同内容:不新增文件,复用已有路径。
311
+ 17. 删除文件后登录/会话启动清理索引,且不重算所有 hash。
231
312
 
232
313
  ## 5. 风险与预案
233
314
 
234
- | 风险 | 影响 | 预案 |
235
- | --- | --- | --- |
236
- | ASR 为空或识别不准 | 语音无法转写 | 回复提示重发或打字;V2 不做语音回退 |
237
- | 平台只返回 `voice` 的假定失效 | 语音分支不触发 | 以实测字段为准;若变化再扩展识别条件 |
238
- | 日志目录不可写 | 无日志 | 捕获写入异常,消息处理继续 |
239
- | 默认 `silent` 导致排查时无日志 | 诊断困难 | README 明确开启 `logLevel: "info"` / `"debug"` |
240
- | 移除 debug 时间戳影响现有诊断 | QQ 气泡少时间戳 | 已确认日志级别不影响聊天展示;需要时后续加独立开关 |
315
+ | 风险 | 影响 | 预案 |
316
+ | ------------------------------ | --------------- | -------------------------------------------------- |
317
+ | ASR 为空或识别不准 | 语音无法转写 | 回复提示重发或打字;V2 不做语音回退 |
318
+ | 平台只返回 `voice` 的假定失效 | 语音分支不触发 | 以实测字段为准;若变化再扩展识别条件 |
319
+ | 日志目录不可写 | 无日志 | 捕获写入异常,消息处理继续 |
320
+ | 默认 `silent` 导致排查时无日志 | 诊断困难 | README 明确开启 `logLevel: "info"` / `"debug"` |
321
+ | 移除 debug 时间戳影响现有诊断 | QQ 气泡少时间戳 | 已确认日志级别不影响聊天展示;需要时后续加独立开关 |
241
322
 
242
323
  ## 6. 执行记录
243
324
 
244
325
  - 2026-10-30:M5a / M5b 代码与单测完成;`npm test` 97 项通过,`npm run typecheck`、`npm run format:check` 通过。
245
326
  - 2026-10-30:QQ 实机语音验收通过。两条语音均直接使用 `asr_refer_text` 进入 pi;未保存 `.amr`,未调用本地转写工具;`logLevel: "debug"` 日志包含 ASR 元数据与全文。
327
+ - 2026-10-30:F10 文件等待指令实现完成;`npm test` 101 项通过,`typecheck`、`format:check` 通过。
328
+ - 2026-10-30:QQ 实机文件等待指令验收通过。文件-only 无回复、无 run;后续文字指令正确合并 1 个和 2 个 pending 文件并读取。
329
+ - 2026-10-30:F11 文件存储与去重实现完成;`npm test` 109 项通过,`typecheck`、`format:check` 通过。
330
+ - 2026-10-30:实机测试发现两条文件消息并发时索引互相覆盖(`c.txt` 文件存在但索引缺失)。根因是 `bot.ts` 的 message handler 未 await `onMessage`,导致 `concurrencyGuard` 提前释放锁。已修复并新增 `test/bot.test.ts`。
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
@@ -11,6 +11,7 @@ import { AppendStream } from "./src/append-stream";
11
11
  import { formatTokenCount } from "./src/format";
12
12
  import { formatBudgetStatus } from "./src/budget-status";
13
13
  import { configureLogger, log, previewForLog } from "./src/logger";
14
+ import { pruneUploadIndex, sessionUploadDir } from "./src/files";
14
15
 
15
16
  /**
16
17
  * pi-qq extension entry.
@@ -90,9 +91,14 @@ export default function (pi: ExtensionAPI) {
90
91
 
91
92
  // —— Login and connection ——
92
93
 
93
- const startWithCredentials = (ctx: ExtensionContext, creds: Credentials, allowedOpenid: string) => {
94
+ const startWithCredentials = async (ctx: ExtensionContext, creds: Credentials, allowedOpenid: string) => {
94
95
  const settings = getSettings(readConfig().config);
95
96
  configureLogger(settings.logLevel, join(ctx.cwd, ".pi", "pi-qq", "logs"));
97
+ running?.stop();
98
+ stateDetail = undefined;
99
+ sessionCtx = ctx;
100
+ const uploadDir = sessionUploadDir(ctx.cwd, ctx.sessionManager.getSessionId());
101
+ const uploadIndex = await pruneUploadIndex(uploadDir);
96
102
  log.info("session", "starting bot", {
97
103
  appId: creds.appId,
98
104
  allowedOpenid,
@@ -100,10 +106,9 @@ export default function (pi: ExtensionAPI) {
100
106
  model: ctx.model?.name ?? null,
101
107
  markdownSupport: settings.markdownSupport,
102
108
  logLevel: settings.logLevel,
109
+ uploadDir,
110
+ indexedFiles: Object.keys(uploadIndex).length,
103
111
  });
104
- running?.stop();
105
- stateDetail = undefined;
106
- sessionCtx = ctx;
107
112
  running = startBot({
108
113
  credentials: creds,
109
114
  allowedOpenid,
@@ -143,7 +148,7 @@ export default function (pi: ExtensionAPI) {
143
148
 
144
149
  // —— Lifecycle ——
145
150
 
146
- pi.on("session_start", (_event, ctx) => {
151
+ pi.on("session_start", async (_event, ctx) => {
147
152
  const { config, error } = readConfig();
148
153
  const settings = getSettings(config);
149
154
  configureLogger(settings.logLevel, join(ctx.cwd, ".pi", "pi-qq", "logs"));
@@ -159,7 +164,7 @@ export default function (pi: ExtensionAPI) {
159
164
  configError: error ?? null,
160
165
  });
161
166
  if (login) {
162
- startWithCredentials(ctx, login.credentials, login.allowedOpenid);
167
+ await startWithCredentials(ctx, login.credentials, login.allowedOpenid);
163
168
  } else if (ctx.hasUI) {
164
169
  ctx.ui.notify("pi-qq: run /qq-login to scan a QR code.", "warning");
165
170
  }
@@ -217,13 +222,15 @@ export default function (pi: ExtensionAPI) {
217
222
  void runFeedback.onAssistantDelta(snapshot, thinking);
218
223
  });
219
224
 
220
- // pi → QQ: assistant message relay (non-streaming path + F7 stream takeover).
225
+ // pi → QQ: assistant message relay (QQ-triggered runs only).
221
226
 
222
227
  pi.on("message_end", async (event, ctx) => {
223
228
  const msg = event.message;
224
229
  if (msg.role !== "assistant" || !running) return;
225
230
 
231
+ const fromQQ = runFeedback.isQQRunActive();
226
232
  log.debug("pi", "assistant message ended", {
233
+ fromQQ,
227
234
  stopReason: msg.stopReason,
228
235
  contentTypes: msg.content.map((block) => block.type),
229
236
  textPreview: previewForLog(
@@ -233,6 +240,7 @@ export default function (pi: ExtensionAPI) {
233
240
  .join("\n"),
234
241
  ),
235
242
  });
243
+ if (!fromQQ) return;
236
244
 
237
245
  const { config } = readConfig();
238
246
  const settings = getSettings(config);
@@ -297,7 +305,7 @@ export default function (pi: ExtensionAPI) {
297
305
 
298
306
  const credentials: Credentials = { appId: result.appId, appSecret: result.appSecret };
299
307
  setLoginState({ credentials, allowedOpenid: result.userOpenid });
300
- startWithCredentials(ctx, credentials, result.userOpenid);
308
+ await startWithCredentials(ctx, credentials, result.userOpenid);
301
309
  },
302
310
  });
303
311
 
@@ -320,7 +328,7 @@ export default function (pi: ExtensionAPI) {
320
328
  handler: async (_args, ctx) => {
321
329
  stopIfRunning();
322
330
  setLoginState(undefined);
323
- ctx.ui.notify("pi-qq logged out. Credentials cleared from memory; run /qq-login to scan again.", "info");
331
+ ctx.ui.notify("pi-qq logged out.", "info");
324
332
  },
325
333
  });
326
334
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chen_hu_hu/pi-qq",
3
- "version": "1.1.0",
3
+ "version": "1.2.2",
4
4
  "description": "Connect pi to QQ private chats.",
5
5
  "license": "MIT",
6
6
  "author": "CQ-Developer",
@@ -35,6 +35,7 @@
35
35
  "src",
36
36
  "doc",
37
37
  "README.md",
38
+ "README-zh.md",
38
39
  "LICENSE"
39
40
  ],
40
41
  "scripts": {
@@ -57,6 +58,8 @@
57
58
  }
58
59
  },
59
60
  "devDependencies": {
61
+ "@earendil-works/pi-coding-agent": "^1.4.0",
62
+ "@types/node": "^22.20.5",
60
63
  "prettier": "^3.9.10",
61
64
  "vitest": "^5.0.5"
62
65
  }
package/src/bot.ts CHANGED
@@ -83,7 +83,7 @@ export function startBot(opts: StartBotOptions): RunningBot {
83
83
  log.error("bot", "error event", { err });
84
84
  opts.onRecoverableError?.(err);
85
85
  });
86
- bot.on("message", (_ctx, msg) => {
86
+ bot.on("message", async (_ctx, msg) => {
87
87
  log.debug("bot", "inbound message", {
88
88
  kind: msg.kind,
89
89
  rawEventType: msg.rawEventType,
@@ -102,9 +102,11 @@ export function startBot(opts: StartBotOptions): RunningBot {
102
102
  msgElements: msg.msgElements,
103
103
  raw: msg.raw,
104
104
  });
105
- Promise.resolve(opts.onMessage?.(bot, msg)).catch((err: unknown) => {
105
+ try {
106
+ await opts.onMessage?.(bot, msg);
107
+ } catch (err) {
106
108
  log.error("bot", "message handler rejected", { err });
107
- });
109
+ }
108
110
  });
109
111
 
110
112
  let stopped = false;
package/src/files.ts CHANGED
@@ -1,11 +1,13 @@
1
- /** Save QQ non-image attachments in the workspace and reference them in the prompt. */
2
- import { mkdir, writeFile } from "node:fs/promises";
1
+ /** Save QQ non-image attachments in the workspace, with session-scoped deduplication. */
2
+ import { createHash } from "node:crypto";
3
+ import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
3
4
  import { basename, extname, join } from "node:path";
4
5
  import { downloadLimited, type InboundAttachmentLike } from "./download";
5
6
  import { formatBytes } from "./format";
7
+ import { log } from "./logger";
6
8
 
7
9
  const DOWNLOAD_TIMEOUT_MS = 60_000;
8
- const DEFAULT_BASE_DIR = join(process.cwd(), ".pi", "pi-qq");
10
+ const UPLOAD_INDEX_FILENAME = ".index.json";
9
11
 
10
12
  export interface SavedFile {
11
13
  path: string;
@@ -18,13 +20,15 @@ export interface FileFailure {
18
20
  reason: string;
19
21
  }
20
22
 
23
+ /** fileName -> SHA-256. Paths are derived from uploadDir. */
24
+ export type UploadIndex = Record<string, string>;
25
+
21
26
  export interface SaveFilesOptions {
22
27
  maxSize: number;
23
- /** Test override; defaults to <cwd>/.pi/pi-qq. */
24
- baseDir?: string;
25
- /** Directory key for one message (usually msgId). */
26
- dirKey?: string;
27
- now?: Date;
28
+ /** `<cwd>/.pi/pi-qq/<sessionId>/uploads`. */
29
+ uploadDir: string;
30
+ /** Test/caller override; loaded from uploadDir when omitted. Mutated in place. */
31
+ index?: UploadIndex;
28
32
  fetchImpl?: typeof fetch;
29
33
  }
30
34
 
@@ -33,18 +37,18 @@ export interface SaveFilesResult {
33
37
  failures: FileFailure[];
34
38
  }
35
39
 
36
- function pad(n: number): string {
37
- return String(n).padStart(2, "0");
40
+ function safePathSegment(key: string): string {
41
+ const cleaned = key.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^[._]+|[._]+$/g, "");
42
+ return cleaned.slice(0, 64) || "session";
38
43
  }
39
44
 
40
- function dateStamp(now: Date): string {
41
- return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
45
+ /** Session-scoped upload directory; no date or msgId subdirectories. */
46
+ export function sessionUploadDir(cwd: string, sessionId: string): string {
47
+ return join(cwd, ".pi", "pi-qq", safePathSegment(sessionId), "uploads");
42
48
  }
43
49
 
44
- function withSuffix(filename: string, suffix: number): string {
45
- const ext = extname(filename);
46
- const stem = filename.slice(0, filename.length - ext.length);
47
- return `${stem}-${suffix}${ext}`;
50
+ export function uploadIndexPath(uploadDir: string): string {
51
+ return join(uploadDir, UPLOAD_INDEX_FILENAME);
48
52
  }
49
53
 
50
54
  /** Keep only a safe basename (no paths/control/Windows-invalid chars); truncate long stems. */
@@ -62,22 +66,134 @@ export function sanitizeFilename(filename: string | undefined, fallback: string)
62
66
  return `${stem.slice(0, maxStemLength)}${ext}`;
63
67
  }
64
68
 
65
- function safeDirKey(key: string): string {
66
- const cleaned = key.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^[._]+|[._]+$/g, "");
67
- return cleaned.slice(0, 64) || "msg";
69
+ function withSuffix(filename: string, suffix: number): string {
70
+ const ext = extname(filename);
71
+ const stem = filename.slice(0, filename.length - ext.length);
72
+ return `${stem}-${suffix}${ext}`;
68
73
  }
69
74
 
70
- async function writeUnique(dir: string, filename: string, body: Buffer): Promise<string> {
71
- for (let attempt = 0; attempt < 100; attempt++) {
72
- const candidate = attempt === 0 ? filename : withSuffix(filename, attempt);
73
- const path = join(dir, candidate);
74
- try {
75
- await writeFile(path, body, { flag: "wx" });
76
- return path;
77
- } catch (err) {
78
- if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
75
+ function isSafeIndexKey(filename: string): boolean {
76
+ return (
77
+ filename.length > 0 &&
78
+ filename !== "." &&
79
+ filename !== ".." &&
80
+ filename !== UPLOAD_INDEX_FILENAME &&
81
+ basename(filename) === filename
82
+ );
83
+ }
84
+
85
+ export function sha256Hex(body: Buffer): string {
86
+ return createHash("sha256").update(body).digest("hex");
87
+ }
88
+
89
+ async function isFile(path: string): Promise<boolean> {
90
+ try {
91
+ return (await stat(path)).isFile();
92
+ } catch {
93
+ return false;
94
+ }
95
+ }
96
+
97
+ export async function loadUploadIndex(uploadDir: string): Promise<UploadIndex> {
98
+ try {
99
+ const parsed = JSON.parse(await readFile(uploadIndexPath(uploadDir), "utf8")) as unknown;
100
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
101
+ const index: UploadIndex = {};
102
+ for (const [filename, hash] of Object.entries(parsed as Record<string, unknown>)) {
103
+ if (isSafeIndexKey(filename) && typeof hash === "string") index[filename] = hash;
79
104
  }
105
+ return index;
106
+ } catch {
107
+ return {};
108
+ }
109
+ }
110
+
111
+ async function persistUploadIndex(uploadDir: string, index: UploadIndex): Promise<void> {
112
+ const path = uploadIndexPath(uploadDir);
113
+ const tmp = `${path}.${process.pid}.tmp`;
114
+ try {
115
+ await mkdir(uploadDir, { recursive: true });
116
+ await writeFile(tmp, `${JSON.stringify(index, null, 2)}\n`, "utf8");
117
+ await rename(tmp, path);
118
+ } catch (err) {
119
+ log.warn("files", "failed to write upload index", { path, err });
80
120
  }
121
+ }
122
+
123
+ /** Load the index and drop entries whose files no longer exist. No content hashing. */
124
+ export async function pruneUploadIndex(uploadDir: string): Promise<UploadIndex> {
125
+ const index = await loadUploadIndex(uploadDir);
126
+ let changed = false;
127
+ for (const filename of Object.keys(index)) {
128
+ if (!(await isFile(join(uploadDir, filename)))) {
129
+ delete index[filename];
130
+ changed = true;
131
+ }
132
+ }
133
+ if (changed) await persistUploadIndex(uploadDir, index);
134
+ return index;
135
+ }
136
+
137
+ async function hashExistingFile(path: string): Promise<string> {
138
+ return sha256Hex(await readFile(path));
139
+ }
140
+
141
+ async function saveOrReuse(
142
+ uploadDir: string,
143
+ filename: string,
144
+ body: Buffer,
145
+ index: UploadIndex,
146
+ ): Promise<{ file: SavedFile; changed: boolean }> {
147
+ const hash = sha256Hex(body);
148
+ const target = join(uploadDir, filename);
149
+ let changed = false;
150
+
151
+ if (!(await isFile(target))) {
152
+ // A stale index entry must not make a missing file look reusable.
153
+ if (index[filename]) {
154
+ delete index[filename];
155
+ changed = true;
156
+ }
157
+ await writeFile(target, body, { flag: "wx" });
158
+ index[filename] = hash;
159
+ return { file: { path: target, originalName: filename, size: body.byteLength }, changed: true };
160
+ }
161
+
162
+ let existingHash = index[filename];
163
+ if (!existingHash) {
164
+ existingHash = await hashExistingFile(target);
165
+ index[filename] = existingHash;
166
+ changed = true;
167
+ }
168
+ if (existingHash === hash) {
169
+ return { file: { path: target, originalName: filename, size: body.byteLength }, changed };
170
+ }
171
+
172
+ for (let suffix = 1; suffix < 100; suffix++) {
173
+ const candidate = withSuffix(filename, suffix);
174
+ const candidatePath = join(uploadDir, candidate);
175
+ if (await isFile(candidatePath)) {
176
+ let candidateHash = index[candidate];
177
+ if (!candidateHash) {
178
+ candidateHash = await hashExistingFile(candidatePath);
179
+ index[candidate] = candidateHash;
180
+ changed = true;
181
+ }
182
+ if (candidateHash === hash) {
183
+ return { file: { path: candidatePath, originalName: candidate, size: body.byteLength }, changed };
184
+ }
185
+ continue;
186
+ }
187
+
188
+ if (index[candidate]) {
189
+ delete index[candidate];
190
+ changed = true;
191
+ }
192
+ await writeFile(candidatePath, body, { flag: "wx" });
193
+ index[candidate] = hash;
194
+ return { file: { path: candidatePath, originalName: candidate, size: body.byteLength }, changed: true };
195
+ }
196
+
81
197
  throw new Error("Could not allocate a unique filename");
82
198
  }
83
199
 
@@ -86,20 +202,25 @@ export async function saveInboundFiles(
86
202
  attachments: readonly InboundAttachmentLike[],
87
203
  options: SaveFilesOptions,
88
204
  ): Promise<SaveFilesResult> {
89
- const now = options.now ?? new Date();
90
- const baseDir = options.baseDir ?? DEFAULT_BASE_DIR;
91
- const dir = options.dirKey
92
- ? join(baseDir, dateStamp(now), safeDirKey(options.dirKey))
93
- : join(baseDir, dateStamp(now));
205
+ const uploadDir = options.uploadDir;
94
206
  const limit = Math.max(1, options.maxSize);
95
207
  const fetchImpl = options.fetchImpl ?? fetch;
96
-
208
+ const index = options.index ?? (await loadUploadIndex(uploadDir));
97
209
  const files: SavedFile[] = [];
98
210
  const failures: FileFailure[] = [];
99
- if (attachments.length > 0) await mkdir(dir, { recursive: true });
211
+ const seenPaths = new Set<string>();
212
+ let indexChanged = false;
213
+
214
+ if (attachments.length > 0) await mkdir(uploadDir, { recursive: true });
215
+
216
+ const addFile = (file: SavedFile) => {
217
+ if (seenPaths.has(file.path)) return;
218
+ seenPaths.add(file.path);
219
+ files.push(file);
220
+ };
100
221
 
101
- for (const [index, attachment] of attachments.entries()) {
102
- const fallback = `file-${index + 1}`;
222
+ for (const [position, attachment] of attachments.entries()) {
223
+ const fallback = `file-${position + 1}`;
103
224
  const filename = sanitizeFilename(attachment.filename, fallback);
104
225
  if (typeof attachment.size === "number" && attachment.size > limit) {
105
226
  failures.push({ filename, reason: `file too large (${formatBytes(attachment.size)} > ${formatBytes(limit)})` });
@@ -114,13 +235,15 @@ export async function saveInboundFiles(
114
235
  kind: "file",
115
236
  fetchImpl,
116
237
  });
117
- const path = await writeUnique(dir, filename, body);
118
- files.push({ path, originalName: filename, size: body.byteLength });
238
+ const result = await saveOrReuse(uploadDir, filename, body, index);
239
+ indexChanged ||= result.changed;
240
+ addFile(result.file);
119
241
  } catch (err) {
120
242
  failures.push({ filename, reason: err instanceof Error ? err.message : "Download failed" });
121
243
  }
122
244
  }
123
245
 
246
+ if (indexChanged) await persistUploadIndex(uploadDir, index);
124
247
  return { files, failures };
125
248
  }
126
249