@dsh-plus/image-studio 0.1.6 → 0.1.7

package/lib/index.js

@@ -47,7 +47,8 @@ const Config = z.object({
 	maxConcurrent: z.number().min(0).max(16).description("生图任务并发上限（0 = 不限）").default(3),
 	requestTimeoutMs: z.number().min(1e4).max(6e5).description("单请求超时（毫秒；生图长耗时，默认 5 分钟）").default(3e5),
 	proxy: z.string().description("上游请求代理（空 = 直连）").default(""),
-	galleryMaxItems: z.number().min(0).max(1e4).description("画廊保留上限（条，0 = 不清理；超限按最旧删除）").default(500)
+	galleryMaxItems: z.number().min(0).max(1e4).description("画廊保留上限（条，0 = 不清理；超限按最旧删除）").default(500),
+	uploadTtlHours: z.number().min(1).max(720).description("上传原图保留时长（小时；未被画廊条目引用的超期即回收）").default(24)
 });
 //#endregion
 //#region src/errors.ts
@@ -70,9 +71,87 @@ function statusOfCode(code) {
 		case "task-not-runnable": return 400;
 		case "credential-unavailable":
 		case "settings-unavailable": return 409;
+		case "unsupported-media": return 415;
+		case "upload-too-large": return 413;
 		default: return 500;
 	}
 }
+//#endregion
+//#region src/images/mime.ts
+/**
+* 图片 MIME 单一事实源：扩展名互转 + 魔数嗅探。
+* 上传边界只认官方 images 端点接受的位图格式（png/jpeg/webp/gif），
+* 不信任客户端声明的 content-type（防伪装文件落盘）。
+* 纯函数零依赖，宿主两半均可安全引入。
+* @module image-studio/images/mime
+*/
+/** 魔数嗅探窗口（最长特征序列 + 偏移）。 */
+const SNIFF_BYTES = 16;
+/** 落盘扩展名 ← MIME（白名单外一律按 png 处理）。 */
+function extOfMime(mime) {
+	switch (mime) {
+		case "image/jpeg": return "jpg";
+		case "image/webp": return "webp";
+		case "image/gif": return "gif";
+		default: return "png";
+	}
+}
+/** MIME ← 落盘扩展名（读取回程；与 extOfMime 互逆）。 */
+function mimeOfExt(ext) {
+	switch (ext) {
+		case "jpg":
+		case "jpeg": return "image/jpeg";
+		case "webp": return "image/webp";
+		case "gif": return "image/gif";
+		default: return "image/png";
+	}
+}
+/** 前若干字节是否以 prefix 开头。 */
+function startsWith(bytes, prefix, offset = 0) {
+	if (bytes.length < offset + prefix.length) return false;
+	return prefix.every((value, index) => bytes[offset + index] === value);
+}
+/** ASCII 特征序列 → 字节数组（'RIFF' / 'WEBP' 等容器标记）。 */
+function ascii(text) {
+	return [...text].map((char) => char.charCodeAt(0));
+}
+/**
+* 魔数嗅探图片类型；非白名单格式返回 null。
+* @param bytes - 文件字节（只需前 16 字节即可判定）。
+*/
+function detectImageMime(bytes) {
+	const head = bytes.subarray(0, SNIFF_BYTES);
+	if (startsWith(head, [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	])) return "image/png";
+	if (startsWith(head, [
+		255,
+		216,
+		255
+	])) return "image/jpeg";
+	if (startsWith(head, ascii("GIF87a")) || startsWith(head, ascii("GIF89a"))) return "image/gif";
+	if (startsWith(head, ascii("RIFF")) && startsWith(head, ascii("WEBP"), 8)) return "image/webp";
+	return null;
+}
+//#endregion
+//#region src/limits.ts
+/**
+* 跨半共享的数量/体积上限（单一事实源）。
+* 宿主边界校验与浏览器半控件共用，避免两处各写一个数字而漂移。
+* 纯常量零依赖，浏览器半可安全引入。
+* @module image-studio/limits
+*/
+/** 单次 edits 请求的源图上限（官方 GPT Image 限制）。 */
+const MAX_SOURCE_IMAGES = 16;
+/** 单张上传原图体积上限（50MB，对齐官方 images 端点与仓库上传约定）。 */
+const UPLOAD_MAX_BYTES = 52428800;
 /** 只读目录（冻结防运行期篡改）。 */
 const PARAM_CATALOG = Object.freeze([
 	{
@@ -96,10 +175,11 @@ const PARAM_CATALOG = Object.freeze([
 	{
 		key: "size",
 		kind: "string",
+		rules: "image-size",
 		applies: ["generation", "edit"],
 		generation: "current",
 		advanced: false,
-		description: "尺寸，如 1024x1024 / 1536x1024 / 1024x1536 / auto；宽高需为 16 的倍数、最大边 ≤3840、比例 ≤3:1（依模型限制）"
+		description: "尺寸：auto 或「宽x高」。推荐 1024x1024 / 1536x1024 / 1024x1536；自定义需宽高为 16 的倍数、长边 ≤3840、比例 ≤3:1、总像素 655360-8294400"
 	},
 	{
 		key: "quality",
@@ -108,12 +188,14 @@ const PARAM_CATALOG = Object.freeze([
 			"auto",
 			"low",
 			"medium",
-			"high"
+			"high",
+			"xhigh",
+			"max"
 		],
 		applies: ["generation", "edit"],
 		generation: "current",
 		advanced: false,
-		description: "质量档位"
+		description: "质量档位（xhigh/max 为 image 2.5 新增高档位）"
 	},
 	{
 		key: "background",
@@ -223,6 +305,90 @@ function paramKeysFor(endpoint) {
 	return PARAM_CATALOG.filter((entry) => entry.applies.includes(endpoint)).map((entry) => entry.key);
 }
 //#endregion
+//#region src/params/size.ts
+/** GPT Image 代自定义尺寸规则。 */
+const IMAGE_SIZE_RULE = Object.freeze({
+	multiple: 16,
+	maxEdge: 3840,
+	minPixels: 655360,
+	maxPixels: 8294400,
+	maxAspect: 3
+});
+/** 免校验取值：实际尺寸由模型按提示词决定。 */
+const SIZE_AUTO = "auto";
+/** 预设尺寸表（顺序即展示序：常用在前；全部满足 16 倍数约束）。 */
+const SIZE_PRESETS = 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"
+	})
+]);
+const OK = { ok: true };
+/** 「宽x高」规范形态（小写 x、无空白；`auto` 原样）。 */
+function normalizeImageSize(value) {
+	const text = value.trim();
+	if (text === "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 代规则）。
+*/
+function checkImageSize(value, rule = IMAGE_SIZE_RULE) {
+	const text = normalizeImageSize(value);
+	if (text === "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) {
+	return {
+		ok: false,
+		message
+	};
+}
+//#endregion
 //#region src/params/spec.ts
 /** 归一化失败原因（边界校验用，端点转 invalid-request）。 */
 var ParamValidationError = class extends Error {
@@ -240,7 +406,7 @@ function validateParamValue(key, value) {
 	switch (entry.kind) {
 		case "string":
 			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(" | ") ?? "枚举值"} 之一`);
 			return value;
@@ -255,6 +421,18 @@ function validateParamValue(key, value) {
 	}
 }
 /**
+* 结构化值域规则分派（目录声明 → 校验实现单一入口）。
+* 无规则的参数原样返回；规则拒绝时错误消息即为面向用户的原因。
+*/
+function validateRule(rule, key, value) {
+	if (rule === "image-size") {
+		const checked = checkImageSize(value);
+		if (!checked.ok) throw new ParamValidationError(key, checked.message);
+		return normalizeImageSize(value);
+	}
+	return value;
+}
+/**
 * 校验并归一化一份参数表：仅保留启用且适用于该端点的参数；
 * model 是请求基础（提供商预设承载），不计入协议参数表。
 * 任何禁用/未知/越界项直接抛 ParamValidationError（边界 fail-loud）。
@@ -559,6 +737,8 @@ function createProvider(id) {
 //#endregion
 //#region src/api.ts
 const ROUTE_PREFIX = "/dsh-plus/image-studio";
+/** 上传文件名长度上限（仅展示用途，超长截断）。 */
+const UPLOAD_NAME_MAX = 200;
 function sendJson(res, status, body) {
 	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
 	res.end(JSON.stringify(body));
@@ -571,6 +751,27 @@ function readBody(req) {
 		req.on("error", reject);
 	});
 }
+/**
+* 读取二进制请求体（上传通道）：超限即中止并抛 upload-too-large。
+* 限额内的字节在内存中聚合（魔数嗅探需完整头部判定，单文件 ≤50MB；
+* 超限后不再累积，内存占用有界）。导出供单测用小限额直接驱动。
+*/
+function readBinaryBody(req, maxBytes = UPLOAD_MAX_BYTES) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > maxBytes) {
+				reject(new ImageStudioError("upload-too-large", `文件超过 ${maxBytes} 字节上限`));
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => resolve(Buffer.concat(chunks)));
+		req.on("error", reject);
+	});
+}
 /** 统一错误结算：ImageStudioError/ParamValidationError 按码映射，其余 500。 */
 function sendError(res, error) {
 	if (error instanceof ImageStudioError) {
@@ -592,6 +793,12 @@ function sendError(res, error) {
 		message: error instanceof Error ? error.message : String(error)
 	});
 }
+/** 上传文件名（query 参数，仅展示用）：去控制字符并截断。 */
+function uploadNameOf(url) {
+	const raw = (url.searchParams.get("name") ?? "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+	if (raw === "") return "upload";
+	return raw.slice(0, UPLOAD_NAME_MAX);
+}
 function buildHandlers(service) {
 	return {
 		async generate(_req, res, rest) {
@@ -666,13 +873,50 @@ function buildHandlers(service) {
 				sendJson(res, 404, { error: "not-found" });
 				return;
 			}
-			const mime = bytes.ext === "jpg" ? "image/jpeg" : `image/${bytes.ext}`;
+			const mime = mimeOfExt(bytes.ext);
 			res.writeHead(200, {
 				"content-type": mime,
 				"cache-control": "private, max-age=3600"
 			});
 			res.end(Buffer.from(bytes.data));
 		},
+		async uploads(req, res, rest, url) {
+			const uploadId = rest.replace(/\/$/, "");
+			if (method(req) === "POST") {
+				if (uploadId !== "") throw new ImageStudioError("invalid-request", "未知路径");
+				const data = new Uint8Array(await readBinaryBody(req));
+				const mime = detectImageMime(data);
+				if (mime === null) throw new ImageStudioError("unsupported-media", "只支持 PNG/JPEG/WebP/GIF 图片");
+				sendJson(res, 201, await service.saveUpload({
+					name: uploadNameOf(url),
+					mime,
+					data
+				}));
+				return;
+			}
+			if (method(req) !== "GET") {
+				sendJson(res, 405, { error: "GET or POST only" });
+				return;
+			}
+			if (uploadId === "") {
+				const items = await service.listUploads();
+				sendJson(res, 200, {
+					items,
+					total: items.length
+				});
+				return;
+			}
+			const bytes = await service.uploadBytes(uploadId);
+			if (bytes === null) {
+				sendJson(res, 404, { error: "not-found" });
+				return;
+			}
+			res.writeHead(200, {
+				"content-type": mimeOfExt(bytes.ext),
+				"cache-control": "private, max-age=3600"
+			});
+			res.end(Buffer.from(bytes.data));
+		},
 		async credentials(_req, res, rest) {
 			const refName = rest.replace(/\/$/, "");
 			if (refName.length === 0) {
@@ -736,7 +980,8 @@ function registerImageStudioApi(ctx, service) {
 		kind: "prefix",
 		path: ROUTE_PREFIX,
 		handler: (req, res) => {
-			const [head, ...tail] = new URL(req.url ?? "/", "http://localhost").pathname.slice(22).replace(/^\//, "").split("/");
+			const url = new URL(req.url ?? "/", "http://localhost");
+			const [head, ...tail] = url.pathname.slice(22).replace(/^\//, "").split("/");
 			const rest = tail.join("/");
 			(async () => {
 				if (head === void 0 || head === "") {
@@ -748,7 +993,7 @@ function registerImageStudioApi(ctx, service) {
 					sendJson(res, 404, { error: `unknown endpoint: ${head}` });
 					return;
 				}
-				await handler(req, res, rest);
+				await handler(req, res, rest, url);
 			})().catch((error) => sendError(res, error));
 		}
 	});
@@ -773,6 +1018,18 @@ function credentialRefNameOf(presetId) {
 	return `${REF_PREFIX}${presetId.replaceAll("-", "_").toUpperCase()}`;
 }
 //#endregion
+//#region src/images/id.ts
+/**
+* 图片标识形态（uuid）：画廊 imageId 与上传 uploadId 共用同一约束。
+* 既是路由参数白名单，也是路径拼接的穿越防线（单一事实源）。
+* @module image-studio/images/id
+*/
+const IMAGE_ID_RE = /^[a-f0-9-]{36}$/;
+/** 是否为合法图片标识（未知类型一律 false）。 */
+function isImageId(value) {
+	return typeof value === "string" && IMAGE_ID_RE.test(value);
+}
+//#endregion
 //#region src/gallery/store.ts
 /**
 * 画廊存储：元数据 JSONL（追加）+ 图片落盘（原子写）。
@@ -787,29 +1044,29 @@ function credentialRefNameOf(presetId) {
 function galleryRoot() {
 	return pluginDataPath("image-studio", "gallery");
 }
-function indexFile() {
+function indexFile$1() {
 	return join(galleryRoot(), "index.jsonl");
 }
 function imagesDir() {
 	return join(galleryRoot(), "images");
 }
-/** 图片扩展名由 MIME 推导（仅白名单格式）。 */
-function extOfMime(mime) {
-	switch (mime) {
-		case "image/jpeg": return "jpg";
-		case "image/webp": return "webp";
-		default: return "png";
-	}
-}
 /** 确保目录存在。 */
-async function ensureDirs() {
+async function ensureDirs$1() {
 	await mkdir(imagesDir(), { recursive: true });
 }
+/** 旧条目补齐新增字段（sourceUploads 为后加字段，历史 JSONL 里不存在）。 */
+function normalizeItem(item) {
+	return {
+		...item,
+		sourceIds: item.sourceIds ?? [],
+		sourceUploads: item.sourceUploads ?? []
+	};
+}
 /** 解析 JSONL 全量元数据（坏行跳过并告警；空文件返回空表）。 */
 async function loadGallery(log) {
 	let text;
 	try {
-		text = await readFile(indexFile(), "utf8");
+		text = await readFile(indexFile$1(), "utf8");
 	} catch {
 		return [];
 	}
@@ -817,7 +1074,7 @@ async function loadGallery(log) {
 	for (const line of text.split("\n")) {
 		if (line.trim().length === 0) continue;
 		try {
-			items.push(JSON.parse(line));
+			items.push(normalizeItem(JSON.parse(line)));
 		} catch {
 			log(`画廊元数据坏行跳过：${line.slice(0, 80)}`);
 		}
@@ -826,12 +1083,12 @@ async function loadGallery(log) {
 }
 /** 追加一条元数据（JSONL 原子性：单行小写入）。 */
 async function appendIndex(item) {
-	await ensureDirs();
-	await appendFile(indexFile(), `${JSON.stringify(item)}\n`, "utf8");
+	await ensureDirs$1();
+	await appendFile(indexFile$1(), `${JSON.stringify(item)}\n`, "utf8");
 }
 /** 图片文件绝对路径。 */
 function imagePathOf(imageId, ext) {
-	if (!/^[a-f0-9-]{36}$/.test(imageId) || !/^[a-z0-9]{2,4}$/.test(ext)) throw new Error(`非法画廊图片标识：${imageId}.${ext}`);
+	if (!isImageId(imageId) || !/^[a-z0-9]{2,4}$/.test(ext)) throw new Error(`非法画廊图片标识：${imageId}.${ext}`);
 	return join(imagesDir(), `${imageId}.${ext}`);
 }
 /** 读取图片字节（未知 id 抛错由调用方映射 404）。 */
@@ -847,7 +1104,7 @@ async function readImageBytes(imageId) {
 }
 /** 画廊新条目：落图片字节 + 追加元数据（一个事务语义，图片先落）。 */
 async function saveGalleryItem(input) {
-	await ensureDirs();
+	await ensureDirs$1();
 	const imageIds = [];
 	for (const image of input.images) {
 		const imageId = randomUUID();
@@ -877,9 +1134,9 @@ async function deleteGalleryItem(itemId) {
 		for (const name of files) if (name.startsWith(`${imageId}.`)) await rm(join(imagesDir(), name), { force: true });
 	}
 	const kept = items.filter((item) => item.id !== itemId);
-	const tmp = `${indexFile()}.tmp-${process.pid}-${Date.now()}`;
+	const tmp = `${indexFile$1()}.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());
+	await rename(tmp, indexFile$1());
 	return true;
 }
 //#endregion
@@ -1022,6 +1279,124 @@ function defaultIdCounter() {
 	};
 }
 //#endregion
+//#region src/uploads/store.ts
+/**
+* 上传暂存区：图生图源图/遮罩的本地文件上传（blobs + JSONL 索引，原子写）。
+* 与画廊分离——上传图片不属于任何画廊条目；生图成功后由条目的
+* sourceUploads 引用（衍生链可见），未被任何条目引用且超过 TTL 的由
+* pruneUploads 回收（见 docs/repo/插件存储规范.md）。
+* 落点 $DSH_HOME/dsh-plus/image-studio/uploads/{index.jsonl, blobs/}
+* @module image-studio/uploads/store
+*/
+/** 存储层根路径（惰性解析：DSH_HOME 可能在模块加载后才被测试环境设置）。 */
+function uploadsRoot() {
+	return pluginDataPath("image-studio", "uploads");
+}
+function indexFile() {
+	return join(uploadsRoot(), "index.jsonl");
+}
+function blobsDir() {
+	return join(uploadsRoot(), "blobs");
+}
+/** 上传 id 即文件名前缀：uuid 形态白名单，兼作路径穿越防线。 */
+function validateUploadId(id) {
+	if (!isImageId(id)) throw new Error(`非法上传标识：${id}`);
+	return id;
+}
+/** 图片文件绝对路径。 */
+function blobPathOf(id, ext) {
+	validateUploadId(id);
+	if (!/^[a-z0-9]{2,4}$/.test(ext)) throw new Error(`非法上传扩展名：${ext}`);
+	return join(blobsDir(), `${id}.${ext}`);
+}
+async function ensureDirs() {
+	await mkdir(blobsDir(), { recursive: true });
+}
+/** 解析 JSONL 全量索引（坏行跳过并告警；空文件返回空表）。 */
+async function loadUploads(log) {
+	let text;
+	try {
+		text = await readFile(indexFile(), "utf8");
+	} catch {
+		return [];
+	}
+	const items = [];
+	for (const line of text.split("\n")) {
+		if (line.trim().length === 0) continue;
+		try {
+			items.push(JSON.parse(line));
+		} catch {
+			log(`上传索引坏行跳过：${line.slice(0, 80)}`);
+		}
+	}
+	return items;
+}
+/** 落盘一张上传图片（临时文件 + rename；索引追加在字节落盘之后）。 */
+async function saveUpload(input) {
+	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 = {
+		id,
+		createdAt: (/* @__PURE__ */ 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）。 */
+async function readUploadBytes(id) {
+	const hit = (await readdir(blobsDir()).catch(() => [])).find((name) => name.startsWith(`${id}.`));
+	if (hit === void 0) 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) {
+	await rm(blobPathOf(entry.id, entry.ext), { force: true });
+}
+/** 索引导出为 JSONL（重写式删除的公共收尾）。 */
+async function rewriteIndex(kept) {
+	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 删除条数。
+*/
+async function pruneUploads(options) {
+	const { keepIds, ttlMs, log } = options;
+	const now = options.now ?? Date.now();
+	const items = await loadUploads(log);
+	const kept = [];
+	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) => {
+				log(`上传回收失败（忽略）：${item.id} ${String(error)}`);
+			});
+			removed += 1;
+			continue;
+		}
+		kept.push(item);
+	}
+	if (removed > 0) await rewriteIndex(kept);
+	return removed;
+}
+//#endregion
 //#region src/service.ts
 /** 静态 schema 引用（installSection 用；避免循环 import config → service）。 */
 var ImageStudioService = class extends Service {
@@ -1029,11 +1404,15 @@ var ImageStudioService = class extends Service {
 	current;
 	runner;
 	log;
+	/** 进行中的孤儿回收（串行化：索引重写不能并发）。 */
+	pruning;
 	constructor(ctx, config) {
 		super(ctx, "imageStudio");
 		this.current = () => config;
 		this.log = (message) => ctx.logger("image-studio").warn(message);
+		this.pruning = null;
 		this.runner = new TaskRunner({ maxConcurrent: config.maxConcurrent });
+		this.schedulePrune();
 		ctx.inject(["settings"], (settingsCtx) => {
 			this.settingsRef = settingsCtx.settings;
 			settingsCtx.settings.installSection(ctx, SETTINGS_NS, Config, config, {
@@ -1139,7 +1518,7 @@ var ImageStudioService = class extends Service {
 	}
 	/**
 	* 任务准备（边界校验集中地）：提供商预设/inline → target；
-	* 参数预设 + 覆盖 → 归一化参数表；sourceIds → 输入图字节。
+	* 参数预设 + 覆盖 → 归一化参数表；sources/mask 引用 → 输入图字节。
 	*/
 	async prepareTask(request) {
 		const target = await this.resolveTarget(request);
@@ -1149,18 +1528,52 @@ var ImageStudioService = class 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 !== void 0 ? 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 引用）。 */
+	sourceRefsOf(request) {
+		if (request.sources !== void 0) {
+			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 引用）。 */
+	maskRefOf(request) {
+		if (request.mask !== void 0) return this.assertRef(request.mask);
+		if (request.maskId === void 0) return null;
+		return this.assertRef({
+			kind: "gallery",
+			id: request.maskId
+		});
+	}
+	/** 引用形态校验（请求体来自浏览器，kind 封闭集合 + id uuid 形态）。 */
+	assertRef(ref) {
+		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）。 */
@@ -1232,28 +1645,49 @@ var ImageStudioService = class extends Service {
 		if (presetId === void 0) return "";
 		return this.providerPresets().find((item) => item.id === presetId)?.model ?? "";
 	}
-	/** 源图字节加载（edit ≥1 张；单图上限 50MB 对齐官方）。 */
-	async loadSourceImages(sourceIds, endpoint) {
-		if (endpoint === "generation") return [];
-		if (sourceIds.length === 0) throw new ImageStudioError("invalid-request", "edit 端点必须提供至少一张源图（sourceIds）");
-		if (sourceIds.length > 16) throw new ImageStudioError("invalid-request", "源图最多 16 张（官方 GPT Image 限制）");
+	/**
+	* 源图字节加载（edit ≥1 张；单图上限 50MB 对齐官方）。
+	* 按引用来源分流读取，并把两类 id 分开回传（画廊衍生链 / 上传暂存区）。
+	*/
+	async loadSourceImages(refs, endpoint) {
+		if (endpoint === "generation") return {
+			images: [],
+			galleryIds: [],
+			uploadIds: []
+		};
+		if (refs.length === 0) throw new ImageStudioError("invalid-request", "edit 端点必须提供至少一张源图（sources）");
+		if (refs.length > 16) throw new ImageStudioError("invalid-request", `源图最多 16 张（官方 GPT Image 限制）`);
 		const images = [];
-		for (const imageId of sourceIds) images.push(await this.loadOneImage(imageId));
-		return images;
+		const galleryIds = [];
+		const uploadIds = [];
+		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,
+			galleryIds,
+			uploadIds
+		};
 	}
-	async loadMask(maskId) {
-		return this.loadOneImage(maskId);
+	/** 单个引用 → 输入图字节（两个 id 空间分别查，未知一律 unknown-source）。 */
+	async loadRefImage(ref) {
+		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)
+		};
 	}
-	async loadOneImage(imageId) {
-		try {
-			const { data, ext } = await readImageBytes(imageId);
-			return {
-				data,
-				mime: ext === "jpg" ? "image/jpeg" : `image/${ext}`
-			};
-		} catch {
-			throw new ImageStudioError("unknown-source", `源图不存在：${imageId}`);
-		}
+	/**
+	* 遮罩加载：官方要求带透明通道的 PNG（其它格式上游必然拒绝），
+	* 在边界提前给出可读原因，避免白跑一次计费请求。
+	*/
+	async loadMaskImage(ref) {
+		const image = await this.loadRefImage(ref);
+		if (image.mime !== "image/png") throw new ImageStudioError("unsupported-media", `遮罩必须是 PNG（当前 ${image.mime}）：请上传带透明区域的 PNG`);
+		return image;
 	}
 	/** 任务体：调协议适配器 → 成功入画廊。失败向上抛给 TaskRunner 记录。 */
 	async executeTask(snapshot, signal) {
@@ -1268,7 +1702,7 @@ var ImageStudioService = class extends Service {
 			mask: snapshot.mask,
 			params: snapshot.params
 		}, signal);
-		return { galleryItemId: (await saveGalleryItem({
+		const item = await saveGalleryItem({
 			item: {
 				providerPresetId: this.presetIdOf(snapshot),
 				protocol: snapshot.target.protocol,
@@ -1276,14 +1710,17 @@ var ImageStudioService = class extends Service {
 				model: snapshot.target.model,
 				prompt: snapshot.prompt,
 				params: snapshot.params,
-				sourceIds: snapshot.sourceIds
+				sourceIds: snapshot.sourceIds,
+				sourceUploads: snapshot.sourceUploads
 			},
 			images: result.images.map((image) => ({
 				data: image.data,
 				mime: image.mime,
 				revisedPrompt: image.revisedPrompt
 			}))
-		})).id };
+		});
+		this.schedulePrune();
+		return { galleryItemId: item.id };
 	}
 	/** 提交时上下文里的预设 id（executeTask 无原请求，经 target 旁路携带）。 */
 	presetIdOf(snapshot) {
@@ -1305,6 +1742,44 @@ var ImageStudioService = class extends Service {
 			return null;
 		}
 	}
+	/** 保存上传原图（端点边界已完成 MIME 嗅探与限额）。 */
+	async saveUpload(input) {
+		const entry = await saveUpload(input);
+		this.schedulePrune();
+		return entry;
+	}
+	/** 上传列表（索引序，最新在后；前端自行倒序展示）。 */
+	async listUploads() {
+		return loadUploads(this.log);
+	}
+	/** 读取上传图片字节（缩略图端点；未知 id 返回 null）。 */
+	async uploadBytes(uploadId) {
+		try {
+			return await readUploadBytes(uploadId);
+		} catch {
+			return null;
+		}
+	}
+	/** 触发一次孤儿回收（并发调用合并为一次，失败不影响主流程）。 */
+	schedulePrune() {
+		if (this.pruning !== null) return;
+		this.pruning = this.pruneOrphans().catch((error) => {
+			this.log(`上传回收失败（忽略）：${error instanceof Error ? error.message : String(error)}`);
+		}).finally(() => {
+			this.pruning = null;
+		});
+	}
+	/** 保留被画廊条目引用的上传；其余超过 TTL 的回收（暂存区不无界增长）。 */
+	async pruneOrphans() {
+		const keepIds = /* @__PURE__ */ new Set();
+		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 * 36e5,
+			log: this.log
+		});
+		if (removed > 0) this.log(`回收孤儿上传 ${removed} 个`);
+	}
 	dispose() {}
 };
 /** 剔除 host 承载参数（model 不进协议参数表——openai-images 请求体单独拼）。 */
@@ -1320,4 +1795,4 @@ function apply(ctx, config) {
 	ctx.plugin(ImageStudioService, config);
 }
 //#endregion
-export { Config, ImageStudioError, ImageStudioService, PARAM_CATALOG, ParamValidationError, apply, credentialRefNameOf, inject, isValidPresetId, name, normalizeParamSpecs, paramEntryOf, paramKeysFor, validateParamSpecs };
+export { Config, IMAGE_SIZE_RULE, ImageStudioError, ImageStudioService, MAX_SOURCE_IMAGES, PARAM_CATALOG, ParamValidationError, SIZE_PRESETS, UPLOAD_MAX_BYTES, apply, checkImageSize, credentialRefNameOf, detectImageMime, extOfMime, inject, isImageId, isValidPresetId, mimeOfExt, name, normalizeParamSpecs, paramEntryOf, paramKeysFor, statusOfCode, validateParamSpecs };