@dsh-plus/image-studio 0.1.6 → 0.1.7

package/src/params/catalog.ts

@@ -11,6 +11,9 @@ import type { ImageEndpoint } from '../provider/types.ts'
 /** 参数值类型（校验与前端控件形态的依据）。 */
 export type ParamKind = 'string' | 'integer' | 'enum' | 'boolean'
 
+/** 值域规则 id（目录声明、边界校验与前端提示共用同一实现）。 */
+export type ParamRuleId = 'image-size'
+
 /** 单个参数的目录条目。 */
 export interface ParamEntry {
   /** 请求体字段名（官方 API 参数名）。 */
@@ -23,6 +26,8 @@ export interface ParamEntry {
   min?: number
   /** integer 时的上界（含）。 */
   max?: number
+  /** 结构化值域规则（如尺寸的倍数/比例/像素约束）；无则仅按 kind 校验。 */
+  rules?: ParamRuleId
   /** 适用端点（new-array 是目录实现细节，不外泄）。 */
   applies: readonly ImageEndpoint[]
   /** 适用模型代际：current（GPT Image）| dall-e-3 | dall-e-2 | all。 */
@@ -56,20 +61,21 @@ const CATALOG_RAW: readonly ParamEntry[] = [
   {
     key: 'size',
     kind: 'string',
+    rules: 'image-size',
     applies: ['generation', 'edit'],
     generation: 'current',
     advanced: false,
     description:
-      '尺寸，如 1024x1024 / 1536x1024 / 1024x1536 / auto；宽高需为 16 的倍数、最大边 ≤3840、比例 ≤3:1（依模型限制）',
+      '尺寸：auto 或「宽x高」。推荐 1024x1024 / 1536x1024 / 1024x1536；自定义需宽高为 16 的倍数、长边 ≤3840、比例 ≤3:1、总像素 655360-8294400',
   },
   {
     key: 'quality',
     kind: 'enum',
-    values: ['auto', 'low', 'medium', 'high'],
+    values: ['auto', 'low', 'medium', 'high', 'xhigh', 'max'],
     applies: ['generation', 'edit'],
     generation: 'current',
     advanced: false,
-    description: '质量档位',
+    description: '质量档位（xhigh/max 为 image 2.5 新增高档位）',
   },
   {
     key: 'background',

package/src/params/size.ts

@@ -0,0 +1,98 @@
+/**
+ * 官方图像尺寸规则与预设尺寸（口径取 gpt-image 系列当前代文档）：
+ * - 快捷预设：auto + 三档推荐尺寸 + 常见宽屏/竖屏/2K/4K；
+ * - 自定义尺寸：宽高均为 16 的倍数、长边 ≤3840、比例 1:3~3:1、
+ *   总像素 655,360–8,294,400；
+ * - 自由输入始终保留：预设只是快捷入口，非白名单。
+ * 同一份规则同时服务宿主边界校验（params/spec）与浏览器半即时提示（参数表单）。
+ * 纯函数零依赖，浏览器半可安全引入。
+ * @module image-studio/params/size
+ */
+
+/** 自定义尺寸约束（数值即官方文档口径）。 */
+export interface SizeRule {
+  /** 宽高须为其整数倍。 */
+  multiple: number
+  /** 长边上限（px）。 */
+  maxEdge: number
+  /** 总像素下限/上限。 */
+  minPixels: number
+  maxPixels: number
+  /** 长边与短边的比例上限（3 即 3:1）。 */
+  maxAspect: number
+}
+
+/** GPT Image 代自定义尺寸规则。 */
+export const IMAGE_SIZE_RULE: SizeRule = Object.freeze({
+  multiple: 16,
+  maxEdge: 3840,
+  minPixels: 655_360,
+  maxPixels: 8_294_400,
+  maxAspect: 3,
+})
+
+/** 免校验取值：实际尺寸由模型按提示词决定。 */
+export const SIZE_AUTO = 'auto'
+
+/** 预设尺寸（快捷选择项，非合法值白名单）。 */
+export interface SizePreset {
+  value: string
+  /** 面向用户的说明（比例/用途）。 */
+  label: string
+}
+
+/** 预设尺寸表（顺序即展示序：常用在前；全部满足 16 倍数约束）。 */
+export const SIZE_PRESETS: readonly SizePreset[] = Object.freeze([
+  Object.freeze({ value: SIZE_AUTO, label: 'auto（由模型决定）' }),
+  Object.freeze({ value: '1024x1024', label: '1024×1024 方形 1:1' }),
+  Object.freeze({ value: '1536x1024', label: '1536×1024 横向 3:2' }),
+  Object.freeze({ value: '1024x1536', label: '1024×1536 纵向 2:3' }),
+  Object.freeze({ value: '2048x1152', label: '2048×1152 宽屏 16:9' }),
+  Object.freeze({ value: '1152x2048', label: '1152×2048 竖屏 9:16' }),
+  Object.freeze({ value: '3840x2160', label: '3840×2160 4K 16:9' }),
+  Object.freeze({ value: '2160x3840', label: '2160×3840 4K 9:16' }),
+])
+
+/** 校验结论：通过或一条面向用户的原因（中文，直接展示）。 */
+export type SizeCheck = { ok: true } | { ok: false; message: string }
+
+const OK: SizeCheck = { ok: true }
+
+/** 「宽x高」规范形态（小写 x、无空白；`auto` 原样）。 */
+export function normalizeImageSize(value: string): string {
+  const text = value.trim()
+  if (text === SIZE_AUTO) return SIZE_AUTO
+  return text.replace(/[×✕✖]/g, 'x').replace(/\s+/g, '').toLowerCase()
+}
+
+/** 规范化后的「宽x高」形态。 */
+const SIZE_PATTERN = /^(\d{2,5})x(\d{2,5})$/
+
+/**
+ * 校验一个尺寸取值（`auto` 或「宽x高」，容忍大小写/全角乘号/空白）。
+ * @param value - 用户输入或预设值（提交/保存前校验）。
+ * @param rule - 尺寸约束（缺省 GPT Image 代规则）。
+ */
+export function checkImageSize(value: string, rule: SizeRule = IMAGE_SIZE_RULE): SizeCheck {
+  const text = normalizeImageSize(value)
+  if (text === SIZE_AUTO) return OK
+  const match = SIZE_PATTERN.exec(text)
+  if (match === null) return fail('需为「宽x高」（如 1024x1024）或 auto')
+  const width = Number(match[1])
+  const height = Number(match[2])
+  if (width % rule.multiple !== 0 || height % rule.multiple !== 0) {
+    return fail(`宽高需为 ${rule.multiple} 的倍数（当前 ${width}x${height}）`)
+  }
+  const long = Math.max(width, height)
+  const short = Math.min(width, height)
+  if (long > rule.maxEdge) return fail(`长边不能超过 ${rule.maxEdge}px（当前 ${long}px）`)
+  if (long / short > rule.maxAspect) return fail(`宽高比不能超过 ${rule.maxAspect}:1`)
+  const pixels = width * height
+  if (pixels < rule.minPixels) return fail(`总像素不能少于 ${rule.minPixels}（当前 ${pixels}）`)
+  if (pixels > rule.maxPixels) return fail(`总像素不能超过 ${rule.maxPixels}（当前 ${pixels}）`)
+  return OK
+}
+
+function fail(message: string): SizeCheck {
+  return { ok: false, message }
+}

package/src/params/spec.ts

@@ -5,7 +5,8 @@
  * @module image-studio/params/spec
  */
 import type { ImageEndpoint } from '../provider/types.ts'
-import { paramEntryOf } from './catalog.ts'
+import { type ParamRuleId, paramEntryOf } from './catalog.ts'
+import { checkImageSize, normalizeImageSize } from './size.ts'
 
 /** 单参数的开关 + 自定义值。 */
 export interface ParamSpec {
@@ -36,7 +37,7 @@ export function validateParamValue(key: string, value: unknown): unknown {
       if (typeof value !== 'string' || value.length === 0) {
         throw new ParamValidationError(key, '必须是非空字符串')
       }
-      return value
+      return validateRule(entry.rules, key, value)
     case 'enum':
       if (typeof value !== 'string' || !entry.values?.includes(value)) {
         throw new ParamValidationError(key, `必须是 ${entry.values?.join(' | ') ?? '枚举值'} 之一`)
@@ -60,6 +61,20 @@ export function validateParamValue(key: string, value: unknown): unknown {
   }
 }
 
+/**
+ * 结构化值域规则分派（目录声明 → 校验实现单一入口）。
+ * 无规则的参数原样返回；规则拒绝时错误消息即为面向用户的原因。
+ */
+function validateRule(rule: ParamRuleId | undefined, key: string, value: string): string {
+  if (rule === 'image-size') {
+    const checked = checkImageSize(value)
+    if (!checked.ok) throw new ParamValidationError(key, checked.message)
+    // 规范化落库/出站：小写 x、无空白（上游按字面解析尺寸串）。
+    return normalizeImageSize(value)
+  }
+  return value
+}
+
 /**
  * 校验并归一化一份参数表：仅保留启用且适用于该端点的参数；
  * model 是请求基础（提供商预设承载），不计入协议参数表。

package/src/service.ts

@@ -1,9 +1,10 @@
 /**
  * image-studio 服务主体：
- * - settings installSection（三组预设 + 并发/超时/代理/画廊上限）；
+ * - settings installSection（三组预设 + 并发/超时/代理/画廊上限/上传保留时长）；
  * - TaskRunner 并发生图：提交即排队，成功自动入画廊（元数据 + 图片落盘）；
  * - 提供商预设按 id 即时 resolve credentials（不缓存）；
- * - 端点：generate/tasks/gallery/images/credentials/providers（api.ts 注册）。
+ * - 上传暂存区：本地文件上传的源图/遮罩，孤儿按 TTL 回收；
+ * - 端点：generate/tasks/gallery/images/uploads/credentials/providers（api.ts 注册）。
  * 红线：开发测试仅指向本地 mock，严禁真实调用产生费用。
  * @module image-studio/service
  */
@@ -20,7 +21,7 @@ import {
   SETTINGS_NS,
 } from './config.ts'
 import { credentialRefNameOf, isValidPresetId } from './credentials.ts'
-import type { GenerateRequest, TaskWire } from './dto.ts'
+import type { GenerateRequest, SourceRef, TaskWire } from './dto.ts'
 import { ImageStudioError } from './errors.ts'
 import type { GalleryItem } from './gallery/store.ts'
 import {
@@ -29,12 +30,22 @@ import {
   deleteGalleryItem as removeGalleryItem,
   saveGalleryItem,
 } from './gallery/store.ts'
+import { isImageId } from './images/id.ts'
+import { mimeOfExt } from './images/mime.ts'
+import { MAX_SOURCE_IMAGES } from './limits.ts'
 import type { ParamSpecMap } from './params/spec.ts'
 import { normalizeParamSpecs, validateParamSpecs } from './params/spec.ts'
 import { createProvider } from './provider/registry.ts'
 import type { ImageEndpoint, InputImage, ProviderTarget } from './provider/types.ts'
 import type { TaskRecord } from './task/runner.ts'
 import { TaskRunner } from './task/runner.ts'
+import type { UploadEntry } from './uploads/store.ts'
+import {
+  loadUploads,
+  pruneUploads,
+  readUploadBytes,
+  saveUpload as saveUploadEntry,
+} from './uploads/store.ts'
 
 interface SettingsLike {
   installSection(
@@ -74,6 +85,8 @@ export class ImageStudioService extends Service {
   private current: () => ImageStudioConfig
   private readonly runner: TaskRunner<TaskSnapshot>
   private readonly log: (message: string) => void
+  /** 进行中的孤儿回收（串行化：索引重写不能并发）。 */
+  private pruning: Promise<void> | null
   // settings 服务窄面（settingsCtx.inject 回调内落存）。declare：不参与类字段
   // 初始化 emit，保持实例运行期形状与既有产物一致（不因声明而多出 undefined 字段）。
   private declare settingsRef: SettingsLike | undefined
@@ -82,7 +95,10 @@ export class ImageStudioService extends Service {
     super(ctx, 'imageStudio')
     this.current = () => config
     this.log = (message) => ctx.logger('image-studio').warn(message)
+    this.pruning = null
     this.runner = new TaskRunner<TaskSnapshot>({ maxConcurrent: config.maxConcurrent })
+    // 启动回收一次：上次进程遗留的孤儿上传（未被画廊引用且超 TTL）。
+    this.schedulePrune()
     ctx.inject(['settings'], (settingsCtx) => {
       this.settingsRef = settingsCtx.settings as unknown as SettingsLike
       settingsCtx.settings.installSection(ctx, SETTINGS_NS, configSchemaRef, config, {
@@ -220,7 +236,7 @@ export class ImageStudioService extends Service {
 
   /**
    * 任务准备（边界校验集中地）：提供商预设/inline → target；
-   * 参数预设 + 覆盖 → 归一化参数表；sourceIds → 输入图字节。
+   * 参数预设 + 覆盖 → 归一化参数表；sources/mask 引用 → 输入图字节。
    */
   private async prepareTask(request: GenerateRequest): Promise<{
     target: ProviderTarget
@@ -231,6 +247,7 @@ export class ImageStudioService extends Service {
     mask: InputImage | null
     params: Record<string, unknown>
     sourceIds: string[]
+    sourceUploads: string[]
   }> {
     const target = await this.resolveTarget(request)
     const endpoint = request.endpoint
@@ -243,19 +260,57 @@ export class ImageStudioService extends Service {
     const params = await this.resolveParams(request, endpoint)
     const nValue = params.n
     const n = typeof nValue === 'number' ? nValue : 1
-    const sourceIds = request.sourceIds ?? []
-    const images = await this.loadSourceImages(sourceIds, endpoint)
-    const mask = request.maskId !== undefined ? await this.loadMask(request.maskId) : null
+    const refs = this.sourceRefsOf(request)
+    const maskRef = this.maskRefOf(request)
+    const sources = await this.loadSourceImages(refs, endpoint)
+    const mask = maskRef === null ? null : await this.loadMaskImage(maskRef)
     return {
       target,
       endpoint,
       prompt: request.prompt,
       n,
-      images,
+      images: sources.images,
       mask,
       params: stripHostParams(params),
-      sourceIds,
+      sourceIds: sources.galleryIds,
+      sourceUploads: sources.uploadIds,
+    }
+  }
+
+  /** 源图引用规范化（sources 优先；旧 sourceIds 等价于全部 gallery 引用）。 */
+  private sourceRefsOf(request: GenerateRequest): SourceRef[] {
+    if (request.sources !== undefined) {
+      if (!Array.isArray(request.sources)) {
+        throw new ImageStudioError('invalid-request', 'sources 必须是数组')
+      }
+      return request.sources.map((ref) => this.assertRef(ref))
+    }
+    const legacy = request.sourceIds ?? []
+    if (!Array.isArray(legacy)) {
+      throw new ImageStudioError('invalid-request', 'sourceIds 必须是数组')
+    }
+    return legacy.map((id) => this.assertRef({ kind: 'gallery', id }))
+  }
+
+  /** 遮罩引用规范化（mask 优先；旧 maskId 等价于 gallery 引用）。 */
+  private maskRefOf(request: GenerateRequest): SourceRef | null {
+    if (request.mask !== undefined) return this.assertRef(request.mask)
+    if (request.maskId === undefined) return null
+    return this.assertRef({ kind: 'gallery', id: request.maskId })
+  }
+
+  /** 引用形态校验（请求体来自浏览器，kind 封闭集合 + id uuid 形态）。 */
+  private assertRef(ref: SourceRef): SourceRef {
+    if (ref === null || typeof ref !== 'object') {
+      throw new ImageStudioError('invalid-request', '源图引用必须是 { kind, id }')
     }
+    if (ref.kind !== 'gallery' && ref.kind !== 'upload') {
+      throw new ImageStudioError('invalid-request', `未知源图类型：${String(ref.kind)}`)
+    }
+    if (!isImageId(ref.id)) {
+      throw new ImageStudioError('invalid-request', `非法源图标识：${String(ref.id)}`)
+    }
+    return { kind: ref.kind, id: ref.id }
   }
 
   /** 提供商预设 / inline → ProviderTarget（凭据即时 resolve）。 */
@@ -350,36 +405,58 @@ export class ImageStudioService extends Service {
     return this.providerPresets().find((item) => item.id === presetId)?.model ?? ''
   }
 
-  /** 源图字节加载（edit ≥1 张；单图上限 50MB 对齐官方）。 */
+  /**
+   * 源图字节加载（edit ≥1 张；单图上限 50MB 对齐官方）。
+   * 按引用来源分流读取，并把两类 id 分开回传（画廊衍生链 / 上传暂存区）。
+   */
   private async loadSourceImages(
-    sourceIds: string[],
+    refs: SourceRef[],
     endpoint: ImageEndpoint,
-  ): Promise<InputImage[]> {
-    if (endpoint === 'generation') return []
-    if (sourceIds.length === 0) {
-      throw new ImageStudioError('invalid-request', 'edit 端点必须提供至少一张源图（sourceIds）')
+  ): Promise<{ images: InputImage[]; galleryIds: string[]; uploadIds: string[] }> {
+    if (endpoint === 'generation') return { images: [], galleryIds: [], uploadIds: [] }
+    if (refs.length === 0) {
+      throw new ImageStudioError('invalid-request', 'edit 端点必须提供至少一张源图（sources）')
     }
-    if (sourceIds.length > 16) {
-      throw new ImageStudioError('invalid-request', '源图最多 16 张（官方 GPT Image 限制）')
+    if (refs.length > MAX_SOURCE_IMAGES) {
+      throw new ImageStudioError(
+        'invalid-request',
+        `源图最多 ${MAX_SOURCE_IMAGES} 张（官方 GPT Image 限制）`,
+      )
     }
     const images: InputImage[] = []
-    for (const imageId of sourceIds) {
-      images.push(await this.loadOneImage(imageId))
+    const galleryIds: string[] = []
+    const uploadIds: string[] = []
+    for (const ref of refs) {
+      images.push(await this.loadRefImage(ref))
+      if (ref.kind === 'gallery') galleryIds.push(ref.id)
+      else uploadIds.push(ref.id)
     }
-    return images
+    return { images, galleryIds, uploadIds }
   }
 
-  private async loadMask(maskId: string): Promise<InputImage> {
-    return this.loadOneImage(maskId)
+  /** 单个引用 → 输入图字节（两个 id 空间分别查，未知一律 unknown-source）。 */
+  private async loadRefImage(ref: SourceRef): Promise<InputImage> {
+    const found =
+      ref.kind === 'gallery' ? await this.imageBytes(ref.id) : await this.uploadBytes(ref.id)
+    if (found === null) {
+      throw new ImageStudioError('unknown-source', `源图不存在：${ref.kind}:${ref.id}`)
+    }
+    return { data: found.data, mime: mimeOfExt(found.ext) }
   }
 
-  private async loadOneImage(imageId: string): Promise<InputImage> {
-    try {
-      const { data, ext } = await readImageBytes(imageId)
-      return { data, mime: ext === 'jpg' ? 'image/jpeg' : `image/${ext}` }
-    } catch {
-      throw new ImageStudioError('unknown-source', `源图不存在：${imageId}`)
+  /**
+   * 遮罩加载：官方要求带透明通道的 PNG（其它格式上游必然拒绝），
+   * 在边界提前给出可读原因，避免白跑一次计费请求。
+   */
+  private async loadMaskImage(ref: SourceRef): Promise<InputImage> {
+    const image = await this.loadRefImage(ref)
+    if (image.mime !== 'image/png') {
+      throw new ImageStudioError(
+        'unsupported-media',
+        `遮罩必须是 PNG（当前 ${image.mime}）：请上传带透明区域的 PNG`,
+      )
     }
+    return image
   }
 
   /** 任务体：调协议适配器 → 成功入画廊。失败向上抛给 TaskRunner 记录。 */
@@ -415,6 +492,7 @@ export class ImageStudioService extends Service {
         prompt: snapshot.prompt,
         params: snapshot.params,
         sourceIds: snapshot.sourceIds,
+        sourceUploads: snapshot.sourceUploads,
       },
       images: result.images.map((image) => ({
         data: image.data,
@@ -422,6 +500,8 @@ export class ImageStudioService extends Service {
         revisedPrompt: image.revisedPrompt,
       })),
     })
+    // 入库后回收一次：本次引用的上传已被条目引用（保留），其余过期孤儿清理。
+    this.schedulePrune()
     return { galleryItemId: item.id }
   }
 
@@ -451,6 +531,55 @@ export class ImageStudioService extends Service {
     }
   }
 
+  // ---------- 上传暂存区 ----------
+
+  /** 保存上传原图（端点边界已完成 MIME 嗅探与限额）。 */
+  async saveUpload(input: { name: string; mime: string; data: Uint8Array }): Promise<UploadEntry> {
+    const entry = await saveUploadEntry(input)
+    this.schedulePrune()
+    return entry
+  }
+
+  /** 上传列表（索引序，最新在后；前端自行倒序展示）。 */
+  async listUploads(): Promise<UploadEntry[]> {
+    return loadUploads(this.log)
+  }
+
+  /** 读取上传图片字节（缩略图端点；未知 id 返回 null）。 */
+  async uploadBytes(uploadId: string): Promise<{ data: Uint8Array; ext: string } | null> {
+    try {
+      return await readUploadBytes(uploadId)
+    } catch {
+      return null
+    }
+  }
+
+  /** 触发一次孤儿回收（并发调用合并为一次，失败不影响主流程）。 */
+  private schedulePrune(): void {
+    if (this.pruning !== null) return
+    this.pruning = this.pruneOrphans()
+      .catch((error: unknown) => {
+        this.log(`上传回收失败（忽略）：${error instanceof Error ? error.message : String(error)}`)
+      })
+      .finally(() => {
+        this.pruning = null
+      })
+  }
+
+  /** 保留被画廊条目引用的上传；其余超过 TTL 的回收（暂存区不无界增长）。 */
+  private async pruneOrphans(): Promise<void> {
+    const keepIds = new Set<string>()
+    for (const item of await this.gallery()) {
+      for (const id of item.sourceUploads) keepIds.add(id)
+    }
+    const removed = await pruneUploads({
+      keepIds,
+      ttlMs: this.current().uploadTtlHours * 3_600_000,
+      log: this.log,
+    })
+    if (removed > 0) this.log(`回收孤儿上传 ${removed} 个`)
+  }
+
   dispose(): void {
     // 进行中任务随进程终止（AbortController 无需逐一 abort——进程退出即断）。
   }

package/src/uploads/store.ts

@@ -0,0 +1,168 @@
+/**
+ * 上传暂存区：图生图源图/遮罩的本地文件上传（blobs + JSONL 索引，原子写）。
+ * 与画廊分离——上传图片不属于任何画廊条目；生图成功后由条目的
+ * sourceUploads 引用（衍生链可见），未被任何条目引用且超过 TTL 的由
+ * pruneUploads 回收（见 docs/repo/插件存储规范.md）。
+ * 落点 $DSH_HOME/dsh-plus/image-studio/uploads/{index.jsonl, blobs/}
+ * @module image-studio/uploads/store
+ */
+
+import { randomUUID } from 'node:crypto'
+import { appendFile, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { pluginDataPath } from '@dsh-plus/shared'
+import { isImageId } from '../images/id.ts'
+import { extOfMime } from '../images/mime.ts'
+
+/** 上传记录元数据（wire 视图原样投影）。 */
+export interface UploadEntry {
+  id: string
+  createdAt: string
+  /** 原始文件名（仅作展示，不参与路径拼接）。 */
+  name: string
+  mime: string
+  ext: string
+  /** 字节数。 */
+  size: number
+}
+
+/** 存储层根路径（惰性解析：DSH_HOME 可能在模块加载后才被测试环境设置）。 */
+function uploadsRoot(): string {
+  return pluginDataPath('image-studio', 'uploads')
+}
+
+function indexFile(): string {
+  return join(uploadsRoot(), 'index.jsonl')
+}
+
+function blobsDir(): string {
+  return join(uploadsRoot(), 'blobs')
+}
+
+/** 上传 id 即文件名前缀：uuid 形态白名单，兼作路径穿越防线。 */
+function validateUploadId(id: string): string {
+  if (!isImageId(id)) throw new Error(`非法上传标识：${id}`)
+  return id
+}
+
+/** 图片文件绝对路径。 */
+function blobPathOf(id: string, ext: string): string {
+  validateUploadId(id)
+  if (!/^[a-z0-9]{2,4}$/.test(ext)) throw new Error(`非法上传扩展名：${ext}`)
+  return join(blobsDir(), `${id}.${ext}`)
+}
+
+async function ensureDirs(): Promise<void> {
+  await mkdir(blobsDir(), { recursive: true })
+}
+
+/** 解析 JSONL 全量索引（坏行跳过并告警；空文件返回空表）。 */
+export async function loadUploads(log: (message: string) => void): Promise<UploadEntry[]> {
+  let text: string
+  try {
+    text = await readFile(indexFile(), 'utf8')
+  } catch {
+    return []
+  }
+  const items: UploadEntry[] = []
+  for (const line of text.split('\n')) {
+    if (line.trim().length === 0) continue
+    try {
+      items.push(JSON.parse(line) as UploadEntry)
+    } catch {
+      log(`上传索引坏行跳过：${line.slice(0, 80)}`)
+    }
+  }
+  return items
+}
+
+/** 单条上传记录查询（未知 id 返回 null）。 */
+export async function findUpload(
+  id: string,
+  log: (message: string) => void,
+): Promise<UploadEntry | null> {
+  if (!isImageId(id)) return null
+  return (await loadUploads(log)).find((item) => item.id === id) ?? null
+}
+
+/** 落盘一张上传图片（临时文件 + rename；索引追加在字节落盘之后）。 */
+export async function saveUpload(input: {
+  name: string
+  mime: string
+  data: Uint8Array
+}): Promise<UploadEntry> {
+  await ensureDirs()
+  const id = randomUUID()
+  const ext = extOfMime(input.mime)
+  const target = blobPathOf(id, ext)
+  const tmp = `${target}.tmp-${process.pid}-${Date.now()}`
+  await writeFile(tmp, input.data)
+  await rename(tmp, target)
+  const entry: UploadEntry = {
+    id,
+    createdAt: new Date().toISOString(),
+    name: input.name,
+    mime: input.mime,
+    ext,
+    size: input.data.byteLength,
+  }
+  await appendFile(indexFile(), `${JSON.stringify(entry)}\n`, 'utf8')
+  return entry
+}
+
+/** 读取上传图片字节（未知 id 抛错由调用方映射 404）。 */
+export async function readUploadBytes(id: string): Promise<{ data: Uint8Array; ext: string }> {
+  const files = await readdir(blobsDir()).catch(() => [] as string[])
+  const hit = files.find((name) => name.startsWith(`${id}.`))
+  if (hit === undefined) throw new Error(`unknown-upload: ${id}`)
+  const ext = hit.slice(id.length + 1)
+  const data = await readFile(blobPathOf(id, ext))
+  return { data: new Uint8Array(data), ext }
+}
+
+/** 删除单条（字节 + 索引行）。 */
+async function removeUpload(entry: UploadEntry): Promise<void> {
+  await rm(blobPathOf(entry.id, entry.ext), { force: true })
+}
+
+/** 索引导出为 JSONL（重写式删除的公共收尾）。 */
+async function rewriteIndex(kept: UploadEntry[]): Promise<void> {
+  const tmp = `${indexFile()}.tmp-${process.pid}-${Date.now()}`
+  await writeFile(
+    tmp,
+    kept.map((item) => JSON.stringify(item)).join('\n') + (kept.length > 0 ? '\n' : ''),
+    'utf8',
+  )
+  await rename(tmp, indexFile())
+}
+
+/**
+ * 回收孤儿上传：未被 keepIds 引用且创建时间早于 ttlMs 的条目删除。
+ * @returns 删除条数。
+ */
+export async function pruneUploads(options: {
+  keepIds: ReadonlySet<string>
+  ttlMs: number
+  now?: number
+  log: (message: string) => void
+}): Promise<number> {
+  const { keepIds, ttlMs, log } = options
+  const now = options.now ?? Date.now()
+  const items = await loadUploads(log)
+  const kept: UploadEntry[] = []
+  let removed = 0
+  for (const item of items) {
+    const expired = now - Date.parse(item.createdAt) > ttlMs
+    if (!keepIds.has(item.id) && expired) {
+      await removeUpload(item).catch((error: unknown) => {
+        log(`上传回收失败（忽略）：${item.id} ${String(error)}`)
+      })
+      removed += 1
+      continue
+    }
+    kept.push(item)
+  }
+  if (removed > 0) await rewriteIndex(kept)
+  return removed
+}