@dsh-plus/image-studio 0.1.6 → 0.1.8

package/lib/index.d.ts

@@ -9,6 +9,7 @@ declare const Config: z<Schemastery.ObjectS<{
   requestTimeoutMs: z<number, number>;
   proxy: z<string, string>;
   galleryMaxItems: z<number, number>;
+  uploadTtlHours: z<number, number>;
 }>, Schemastery.ObjectT<{
   promptPresets: z<unknown[], any[]>;
   paramPresets: z<unknown[], any[]>;
@@ -17,6 +18,7 @@ declare const Config: z<Schemastery.ObjectS<{
   requestTimeoutMs: z<number, number>;
   proxy: z<string, string>;
   galleryMaxItems: z<number, number>;
+  uploadTtlHours: z<number, number>;
 }>>;
 type ImageStudioConfig = Schemastery.TypeT<typeof Config>;
 /** 提示词预设（解析后视图）。 */
@@ -70,8 +72,10 @@ interface GalleryItem {
   imageIds: string[];
   /** 每张图的 revised_prompt（与 imageIds 对齐，可为 null）。 */
   revisedPrompts: Array<string | null>;
-  /** 图生图源图（本画廊内的 imageId）；文生图为空。 */
+  /** 图生图源图中的画廊图片（本画廊 imageId）；文生图为空。 */
   sourceIds: string[];
+  /** 图生图源图中的本地文件上传（uploads 暂存区 id）；上传被回收即失效。 */
+  sourceUploads: string[];
 }
 //#endregion
 //#region src/task/runner.d.ts
@@ -84,7 +88,36 @@ interface GalleryItem {
 /** 任务状态。 */
 type TaskState = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
 //#endregion
+//#region src/uploads/store.d.ts
+/**
+ * 上传暂存区：图生图源图/遮罩的本地文件上传（blobs + JSONL 索引，原子写）。
+ * 与画廊分离——上传图片不属于任何画廊条目；生图成功后由条目的
+ * sourceUploads 引用（衍生链可见），未被任何条目引用且超过 TTL 的由
+ * pruneUploads 回收（见 docs/repo/插件存储规范.md）。
+ * 落点 $DSH_HOME/dsh-plus/image-studio/uploads/{index.jsonl, blobs/}
+ * @module image-studio/uploads/store
+ */
+/** 上传记录元数据（wire 视图原样投影）。 */
+interface UploadEntry {
+  id: string;
+  createdAt: string;
+  /** 原始文件名（仅作展示，不参与路径拼接）。 */
+  name: string;
+  mime: string;
+  ext: string;
+  /** 字节数。 */
+  size: number;
+}
+//#endregion
 //#region src/dto.d.ts
+/**
+ * 源图引用：画廊已落盘图片（gallery）或本地文件上传的暂存图片（upload）。
+ * 两个 id 空间互不重叠，故引用必须显式带 kind（同一字符串在两边含义不同）。
+ */
+interface SourceRef {
+  kind: 'gallery' | 'upload';
+  id: string;
+}
 /** 任务提交请求体。 */
 interface GenerateRequest {
   /** 提供商预设 id 与 inline 二选一（都传时 inline 优先）。 */
@@ -104,9 +137,13 @@ interface GenerateRequest {
     enabled: boolean;
     value?: unknown;
   }>;
-  /** 图生图源图（本画廊 imageId；edit 必填 ≥1）。 */
+  /** 图生图源图（edit 必填 ≥1，≤16；画廊图片与本地文件上传混用）。 */
+  sources?: SourceRef[];
+  /** 可选遮罩（官方要求 PNG；与源图同一引用形态）。 */
+  mask?: SourceRef;
+  /** @deprecated 旧客户端兼容：等价于 kind='gallery' 的 sources。 */
   sourceIds?: string[];
-  /** 可选 PNG mask（本画廊 imageId）。 */
+  /** @deprecated 旧客户端兼容：等价于 kind='gallery' 的 mask。 */
   maskId?: string;
 }
 /** 任务记录 wire 视图。 */
@@ -165,6 +202,8 @@ declare class ImageStudioService extends Service {
   private current;
   private readonly runner;
   private readonly log;
+  /** 进行中的孤儿回收（串行化：索引重写不能并发）。 */
+  private pruning;
   private settingsRef;
   constructor(ctx: Context, config: ImageStudioConfig);
   /** 配置热更：并发上限即时生效（进行中任务不受影响）。 */
@@ -200,9 +239,15 @@ declare class ImageStudioService extends Service {
   private toTaskWire;
   /**
    * 任务准备（边界校验集中地）：提供商预设/inline → target；
-   * 参数预设 + 覆盖 → 归一化参数表；sourceIds → 输入图字节。
+   * 参数预设 + 覆盖 → 归一化参数表；sources/mask 引用 → 输入图字节。
    */
   private prepareTask;
+  /** 源图引用规范化（sources 优先；旧 sourceIds 等价于全部 gallery 引用）。 */
+  private sourceRefsOf;
+  /** 遮罩引用规范化（mask 优先；旧 maskId 等价于 gallery 引用）。 */
+  private maskRefOf;
+  /** 引用形态校验（请求体来自浏览器，kind 封闭集合 + id uuid 形态）。 */
+  private assertRef;
   /** 提供商预设 / inline → ProviderTarget（凭据即时 resolve）。 */
   private resolveTarget;
   /** 凭据解析（每次操作即时 resolve，不缓存）。 */
@@ -212,10 +257,18 @@ declare class ImageStudioService extends Service {
   /** 模型优先级：inline > 提供商预设（参数表中的 model 仅为展示，不参与）。 */
   private modelOf;
   private providerModelOf;
-  /** 源图字节加载（edit ≥1 张；单图上限 50MB 对齐官方）。 */
+  /**
+   * 源图字节加载（edit ≥1 张；单图上限 50MB 对齐官方）。
+   * 按引用来源分流读取，并把两类 id 分开回传（画廊衍生链 / 上传暂存区）。
+   */
   private loadSourceImages;
-  private loadMask;
-  private loadOneImage;
+  /** 单个引用 → 输入图字节（两个 id 空间分别查，未知一律 unknown-source）。 */
+  private loadRefImage;
+  /**
+   * 遮罩加载：官方要求带透明通道的 PNG（其它格式上游必然拒绝），
+   * 在边界提前给出可读原因，避免白跑一次计费请求。
+   */
+  private loadMaskImage;
   /** 任务体：调协议适配器 → 成功入画廊。失败向上抛给 TaskRunner 记录。 */
   private executeTask;
   /** 提交时上下文里的预设 id（executeTask 无原请求，经 target 旁路携带）。 */
@@ -229,6 +282,23 @@ declare class ImageStudioService extends Service {
     data: Uint8Array;
     ext: string;
   } | null>;
+  /** 保存上传原图（端点边界已完成 MIME 嗅探与限额）。 */
+  saveUpload(input: {
+    name: string;
+    mime: string;
+    data: Uint8Array;
+  }): Promise<UploadEntry>;
+  /** 上传列表（索引序，最新在后；前端自行倒序展示）。 */
+  listUploads(): Promise<UploadEntry[]>;
+  /** 读取上传图片字节（缩略图端点；未知 id 返回 null）。 */
+  uploadBytes(uploadId: string): Promise<{
+    data: Uint8Array;
+    ext: string;
+  } | null>;
+  /** 触发一次孤儿回收（并发调用合并为一次，失败不影响主流程）。 */
+  private schedulePrune;
+  /** 保留被画廊条目引用的上传；其余超过 TTL 的回收（暂存区不无界增长）。 */
+  private pruneOrphans;
   dispose(): void;
 }
 //#endregion
@@ -250,16 +320,59 @@ declare function credentialRefNameOf(presetId: string): string;
  * @module image-studio/errors
  */
 /** 全部错误码（封闭集合，新增协议/端点行为时按需扩充）。 */
-declare const ERROR_CODES: readonly ["unknown-protocol", "unknown-endpoint", "invalid-request", "unknown-source", "unknown-task", "task-not-runnable", "credential-unavailable", "settings-unavailable", "provider-error"];
+declare const ERROR_CODES: readonly ["unknown-protocol", "unknown-endpoint", "invalid-request", "unknown-source", "unknown-task", "task-not-runnable", "credential-unavailable", "settings-unavailable", "unsupported-media", "upload-too-large", "provider-error"];
 type ErrorCode = (typeof ERROR_CODES)[number];
 declare class ImageStudioError extends Error {
   readonly code: ErrorCode;
   constructor(code: ErrorCode, message?: string);
 }
+/** 按错误码映射 HTTP 状态（端点边界统一使用）。 */
+declare function statusOfCode(code: string): number;
+//#endregion
+//#region src/images/id.d.ts
+/**
+ * 图片标识形态（uuid）：画廊 imageId 与上传 uploadId 共用同一约束。
+ * 既是路由参数白名单，也是路径拼接的穿越防线（单一事实源）。
+ * @module image-studio/images/id
+ */
+/** 是否为合法图片标识（未知类型一律 false）。 */
+declare function isImageId(value: unknown): value is string;
+//#endregion
+//#region src/images/mime.d.ts
+/**
+ * 图片 MIME 单一事实源：扩展名互转 + 魔数嗅探。
+ * 上传边界只认官方 images 端点接受的位图格式（png/jpeg/webp/gif），
+ * 不信任客户端声明的 content-type（防伪装文件落盘）。
+ * 纯函数零依赖，宿主两半均可安全引入。
+ * @module image-studio/images/mime
+ */
+/** 落盘扩展名 ← MIME（白名单外一律按 png 处理）。 */
+declare function extOfMime(mime: string): string;
+/** MIME ← 落盘扩展名（读取回程；与 extOfMime 互逆）。 */
+declare function mimeOfExt(ext: string): string;
+/**
+ * 魔数嗅探图片类型；非白名单格式返回 null。
+ * @param bytes - 文件字节（只需前 16 字节即可判定）。
+ */
+declare function detectImageMime(bytes: Uint8Array): string | null;
+//#endregion
+//#region src/limits.d.ts
+/**
+ * 跨半共享的数量/体积上限（单一事实源）。
+ * 宿主边界校验与浏览器半控件共用，避免两处各写一个数字而漂移。
+ * 纯常量零依赖，浏览器半可安全引入。
+ * @module image-studio/limits
+ */
+/** 单次 edits 请求的源图上限（官方 GPT Image 限制）。 */
+declare const MAX_SOURCE_IMAGES = 16;
+/** 单张上传原图体积上限（50MB，对齐官方 images 端点与仓库上传约定）。 */
+declare const UPLOAD_MAX_BYTES: number;
 //#endregion
 //#region src/params/catalog.d.ts
 /** 参数值类型（校验与前端控件形态的依据）。 */
 type ParamKind = 'string' | 'integer' | 'enum' | 'boolean';
+/** 值域规则 id（目录声明、边界校验与前端提示共用同一实现）。 */
+type ParamRuleId = 'image-size';
 /** 单个参数的目录条目。 */
 interface ParamEntry {
   /** 请求体字段名（官方 API 参数名）。 */
@@ -272,6 +385,8 @@ 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。 */
@@ -288,6 +403,53 @@ declare function paramEntryOf(key: string): ParamEntry | null;
 /** 某端点下可用的参数键集合（含 advanced）。 */
 declare function paramKeysFor(endpoint: ImageEndpoint): readonly string[];
 //#endregion
+//#region src/params/size.d.ts
+/**
+ * 官方图像尺寸规则与预设尺寸（口径取 gpt-image 系列当前代文档）：
+ * - 快捷预设：auto + 三档推荐尺寸 + 常见宽屏/竖屏/2K/4K；
+ * - 自定义尺寸：宽高均为 16 的倍数、长边 ≤3840、比例 1:3~3:1、
+ *   总像素 655,360–8,294,400；
+ * - 自由输入始终保留：预设只是快捷入口，非白名单。
+ * 同一份规则同时服务宿主边界校验（params/spec）与浏览器半即时提示（参数表单）。
+ * 纯函数零依赖，浏览器半可安全引入。
+ * @module image-studio/params/size
+ */
+/** 自定义尺寸约束（数值即官方文档口径）。 */
+interface SizeRule {
+  /** 宽高须为其整数倍。 */
+  multiple: number;
+  /** 长边上限（px）。 */
+  maxEdge: number;
+  /** 总像素下限/上限。 */
+  minPixels: number;
+  maxPixels: number;
+  /** 长边与短边的比例上限（3 即 3:1）。 */
+  maxAspect: number;
+}
+/** GPT Image 代自定义尺寸规则。 */
+declare const IMAGE_SIZE_RULE: SizeRule;
+/** 预设尺寸（快捷选择项，非合法值白名单）。 */
+interface SizePreset {
+  value: string;
+  /** 面向用户的说明（比例/用途）。 */
+  label: string;
+}
+/** 预设尺寸表（顺序即展示序：常用在前；全部满足 16 倍数约束）。 */
+declare const SIZE_PRESETS: readonly SizePreset[];
+/** 校验结论：通过或一条面向用户的原因（中文，直接展示）。 */
+type SizeCheck = {
+  ok: true;
+} | {
+  ok: false;
+  message: string;
+};
+/**
+ * 校验一个尺寸取值（`auto` 或「宽x高」，容忍大小写/全角乘号/空白）。
+ * @param value - 用户输入或预设值（提交/保存前校验）。
+ * @param rule - 尺寸约束（缺省 GPT Image 代规则）。
+ */
+declare function checkImageSize(value: string, rule?: SizeRule): SizeCheck;
+//#endregion
 //#region src/params/spec.d.ts
 /** 单参数的开关 + 自定义值。 */
 interface ParamSpec {
@@ -320,4 +482,4 @@ declare module '@deepseek-ai/cordis' {
 }
 declare function apply(ctx: Context, config: ImageStudioConfig): void;
 //#endregion
-export { Config, type CredentialStatusWire, type ErrorCode, type GalleryItem, type GalleryListWire, type GenerateRequest, ImageStudioError, ImageStudioService, PARAM_CATALOG, type ParamEntry, type ParamSpec, type ParamSpecMap, ParamValidationError, type PresetsWire, type ProvidersWire, type TaskWire, apply, credentialRefNameOf, inject, isValidPresetId, name, normalizeParamSpecs, paramEntryOf, paramKeysFor, validateParamSpecs };
+export { Config, type CredentialStatusWire, type ErrorCode, type GalleryItem, type GalleryListWire, type GenerateRequest, IMAGE_SIZE_RULE, ImageStudioError, ImageStudioService, MAX_SOURCE_IMAGES, PARAM_CATALOG, type ParamEntry, type ParamSpec, type ParamSpecMap, ParamValidationError, type PresetsWire, type ProvidersWire, SIZE_PRESETS, type SourceRef, type TaskWire, UPLOAD_MAX_BYTES, type UploadEntry, apply, checkImageSize, credentialRefNameOf, detectImageMime, extOfMime, inject, isImageId, isValidPresetId, mimeOfExt, name, normalizeParamSpecs, paramEntryOf, paramKeysFor, statusOfCode, validateParamSpecs };