@dickpy/dsh-imagegen 1.0.7 → 1.0.19

package/lib/index.js

@@ -1,20 +1,21 @@
 import { SettingsConflictError, installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "schemastery";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { promises } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 //#region src/protocol.ts
 /**
 * Wire contract shared by the host and client halves of dsh-imagegen: the
 * settings namespace, the route paths, and the generate payload/result shapes.
-* Pure types + constants — safe for the client bundle to inline.
+* Pure types + constants 鈥?safe for the client bundle to inline.
 */
 /** Settings namespace this plugin owns (host settings seam + bridge). */
 const IMAGEGEN_SETTINGS_NAMESPACE = "dsh-imagegen";
 /** Published package version shared by the host updater and the client UI. */
-const PLUGIN_VERSION = "1.0.7";
+const PLUGIN_VERSION = "1.0.19";
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 const SETTINGS_API = {
 	describe: "/api/dsh-imagegen/settings/describe",
@@ -40,6 +41,29 @@ const HISTORY_API = {
 	clear: "/api/dsh-imagegen/history/clear",
 	image: "/api/dsh-imagegen/history/image"
 };
+/**
+* Same-origin route family for the user-curated gallery (favorites). Entries
+* reuse the history wire shape and persist under ~/.dsh/dsh-imagegen/gallery/;
+* unlike history there is no size cap 鈥?the user adds images on purpose.
+*/
+const GALLERY_API = {
+	list: "/api/dsh-imagegen/gallery/list",
+	append: "/api/dsh-imagegen/gallery/append",
+	remove: "/api/dsh-imagegen/gallery/remove",
+	clear: "/api/dsh-imagegen/gallery/clear",
+	image: "/api/dsh-imagegen/gallery/image"
+};
+/**
+* Same-origin route family for the bundled prompt-template library
+* (awesome-gpt-image-2 mirror). The case list ships inside the package and is
+* served by the host; reference images are proxied through the `image` prefix
+* route and cached on disk so repeated views never hit the network again.
+*/
+const TEMPLATES_API = {
+	list: "/api/dsh-imagegen/templates/list",
+	refresh: "/api/dsh-imagegen/templates/refresh",
+	image: "/api/dsh-imagegen/templates/image"
+};
 //#endregion
 //#region src/engine.ts
 /** A generation failure with a user-presentable message. */
@@ -64,6 +88,28 @@ const DALLE3_SIZES = /* @__PURE__ */ new Set([
 	"1792x1024",
 	"1024x1792"
 ]);
+/** Whether the model is an xAI Grok Imagine model (grok-imagine-image,
+*  grok-imagine-image-2.0, …). Grok Imagine speaks JSON on both endpoints
+*  and exposes its own aspect-ratio / response-format knobs instead of the
+*  OpenAI size/quality/detail passthrough. */
+function isGrokImagine(model) {
+	return /^grok-imagine(?:-|$)/.test(model);
+}
+/** The panel's aspect ratios mapped to the closest OpenAI pixel size
+*  (gpt-image-2 / generic OpenAI-compatible endpoints). */
+const OPENAI_SIZE_BY_RATIO = {
+	"1:1": "1024x1024",
+	"3:4": "1024x1536",
+	"4:3": "1536x1024",
+	"9:16": "1024x1792",
+	"2:3": "1024x1536",
+	"3:2": "1536x1024",
+	"16:9": "1792x1024",
+	"21:9": "1792x1024"
+};
+/** Panel ratios that need renaming for a model's vocabulary. Grok documents
+*  20:9 as its ultra-wide ratio, so the panel's 21:9 label is sent as 20:9. */
+const GROK_ASPECT_ALIASES = { "21:9": "20:9" };
 /** Content-type extension hints for URL-fetched images. */
 function mimeOfExtension(path) {
 	const match = /\.([a-z0-9]+)$/i.exec(path);
@@ -102,14 +148,25 @@ function clampCount(n) {
 *  so the count is satisfied by parallel single-image requests instead. */
 function effectiveParams(request) {
 	const model = request.model.trim() === "" ? "gpt-image-2" : request.model.trim();
-	if (model === "dall-e-3") return {
+	if (model === "dall-e-3") {
+		const pixel = OPENAI_SIZE_BY_RATIO[request.size];
+		return {
+			model,
+			size: pixel !== void 0 && DALLE3_SIZES.has(pixel) ? pixel : "1024x1024"
+		};
+	}
+	if (isGrokImagine(model)) return {
 		model,
-		size: DALLE3_SIZES.has(request.size) ? request.size : "1024x1024"
+		...request.size !== "" && request.size !== "auto" ? { aspect_ratio: GROK_ASPECT_ALIASES[request.size] ?? request.size } : {},
+		...request.quality !== "" && request.quality !== "auto" ? { resolution: request.quality === "4k" ? "2k" : request.quality } : {},
+		response_format: "b64_json"
 	};
 	return {
 		model,
-		...request.size !== "" && request.size !== "auto" ? { size: request.size } : {},
-		...request.quality !== "" && request.quality !== "auto" ? { quality: request.quality } : {},
+		...request.size !== "" && request.size !== "auto" && OPENAI_SIZE_BY_RATIO[request.size] !== void 0 ? { size: OPENAI_SIZE_BY_RATIO[request.size] } : {},
+		...request.quality === "1k" ? { quality: "low" } : {},
+		...request.quality === "2k" ? { quality: "medium" } : {},
+		...request.quality === "4k" ? { quality: "high" } : {},
 		...request.detail !== "" ? { detail: request.detail } : {}
 	};
 }
@@ -174,14 +231,28 @@ async function requestOneImage(baseUrl, upstream, request, params) {
 			throw new ImageGenError("参考图片数据无法解码", "edit-image-invalid");
 		}
 		if (bytes.byteLength > MAX_EDIT_IMAGE_BYTES) throw new ImageGenError("参考图片超过 10MB 上限", "edit-image-too-large");
-		const form = new FormData();
-		form.append("image", new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf$1(parsed.mime)}`);
-		form.append("prompt", request.prompt);
-		form.append("model", params.model);
-		if (params.size !== void 0) form.append("size", params.size);
-		if (params.quality !== void 0) form.append("quality", params.quality);
-		if (params.detail !== void 0) form.append("detail", params.detail);
-		body = form;
+		if (isGrokImagine(params.model)) {
+			headers["content-type"] = "application/json";
+			body = JSON.stringify({
+				model: params.model,
+				prompt: request.prompt,
+				image: {
+					url: request.image,
+					type: "image_url"
+				},
+				...params.aspect_ratio !== void 0 ? { aspect_ratio: params.aspect_ratio } : {},
+				response_format: "b64_json"
+			});
+		} else {
+			const form = new FormData();
+			form.append("image", new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf$2(parsed.mime)}`);
+			form.append("prompt", request.prompt);
+			form.append("model", params.model);
+			if (params.size !== void 0) form.append("size", params.size);
+			if (params.quality !== void 0) form.append("quality", params.quality);
+			if (params.detail !== void 0) form.append("detail", params.detail);
+			body = form;
+		}
 	} else {
 		headers["content-type"] = "application/json";
 		body = JSON.stringify({
@@ -247,7 +318,7 @@ function upstreamMessage(payload, status) {
 	return `上游接口拒绝请求（HTTP ${status}）`;
 }
 /** File extension for a MIME type (multipart reference image). */
-function extensionOf$1(mime) {
+function extensionOf$2(mime) {
 	switch (mime.split(";")[0].trim()) {
 		case "image/jpeg": return "jpg";
 		case "image/webp": return "webp";
@@ -266,11 +337,193 @@ function extensionOf$1(mime) {
 *
 * Framework-free (node:fs only) so the route layer can drive it directly.
 */
+const HISTORY_DIR$1 = path.join(homedir(), ".dsh", "dsh-imagegen");
+const INDEX_PATH$1 = path.join(HISTORY_DIR$1, "index.json");
+const IMAGES_DIR$1 = path.join(HISTORY_DIR$1, "images");
+let pendingMutation$1 = Promise.resolve();
+function mutateHistory(operation) {
+	const next = pendingMutation$1.then(operation, operation);
+	pendingMutation$1 = next.then(() => void 0, () => void 0);
+	return next;
+}
+/** File extension for a MIME type (image file names). */
+function extensionOf$1(mime) {
+	switch (mime.split(";")[0].trim()) {
+		case "image/jpeg": return "jpg";
+		case "image/webp": return "webp";
+		case "image/gif": return "gif";
+		default: return "png";
+	}
+}
+/** MIME type for a stored image file name (image route responses). */
+function mimeOfFile$2(file) {
+	switch (path.extname(file).toLowerCase()) {
+		case ".jpg":
+		case ".jpeg": return "image/jpeg";
+		case ".webp": return "image/webp";
+		case ".gif": return "image/gif";
+		default: return "image/png";
+	}
+}
+/** Sanitize an entry id for use as a file-name prefix. */
+function safeId$1(id) {
+	const cleaned = id.replace(/[^a-zA-Z0-9-]/g, "-");
+	return cleaned === "" ? "entry" : cleaned;
+}
+/** Ensure the storage directories exist. */
+async function ensureDirs$1() {
+	await promises.mkdir(IMAGES_DIR$1, { recursive: true });
+}
+/** Read the index, tolerating a missing/corrupt file. */
+async function readIndex$1() {
+	try {
+		const raw = await promises.readFile(INDEX_PATH$1, "utf8");
+		const parsed = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object") return [];
+		const entries = parsed.entries;
+		if (!Array.isArray(entries)) return [];
+		return entries.filter(isStoredEntry$1);
+	} catch {
+		return [];
+	}
+}
+/** Persist the index. */
+async function writeIndex$1(entries) {
+	await ensureDirs$1();
+	const payload = { entries };
+	const tmp = `${INDEX_PATH$1}.tmp-${process.pid}`;
+	await promises.writeFile(tmp, JSON.stringify(payload), "utf8");
+	await promises.rename(tmp, INDEX_PATH$1);
+}
+/** Structural guard for a stored entry. */
+function isStoredEntry$1(value) {
+	if (value === null || typeof value !== "object") return false;
+	const entry = value;
+	return typeof entry.id === "string" && typeof entry.createdAt === "number" && (entry.mode === "text" || entry.mode === "edit") && typeof entry.prompt === "string" && Array.isArray(entry.images) && entry.images.every((image) => {
+		if (image === null || typeof image !== "object") return false;
+		const record = image;
+		return typeof record.file === "string" && typeof record.mime === "string";
+	});
+}
+/** Remove one entry's image files (best effort). */
+async function removeEntryFiles$1(entry) {
+	for (const image of entry.images) try {
+		await promises.rm(path.join(IMAGES_DIR$1, image.file), { force: true });
+	} catch {}
+}
+/** Project a stored entry onto the wire shape (image URLs). */
+function toWire$1(entry) {
+	return {
+		id: entry.id,
+		createdAt: entry.createdAt,
+		mode: entry.mode,
+		model: entry.model,
+		prompt: entry.prompt,
+		size: entry.size,
+		quality: entry.quality,
+		detail: entry.detail,
+		n: entry.n,
+		images: entry.images.map((image) => ({
+			url: `/api/dsh-imagegen/history/image/${image.file}`,
+			mime: image.mime,
+			...image.revisedPrompt === void 0 ? {} : { revisedPrompt: image.revisedPrompt }
+		})),
+		...entry.refName === void 0 ? {} : { refName: entry.refName }
+	};
+}
+/** List the persisted history, newest first, as wire entries. */
+async function listHistory() {
+	return (await readIndex$1()).map(toWire$1);
+}
+/** Append one generation, evicting the oldest beyond HISTORY_MAX. */
+async function appendHistory(input) {
+	return mutateHistory(async () => {
+		await ensureDirs$1();
+		const prefix = safeId$1(input.id);
+		const storedImages = [];
+		try {
+			for (let index = 0; index < input.images.length; index++) {
+				const image = input.images[index];
+				const file = `${prefix}-${index}.${extensionOf$1(image.mime)}`;
+				await promises.writeFile(path.join(IMAGES_DIR$1, file), Buffer.from(image.b64, "base64"));
+				storedImages.push({
+					file,
+					mime: image.mime,
+					...image.revisedPrompt === void 0 ? {} : { revisedPrompt: image.revisedPrompt }
+				});
+			}
+		} catch (error) {
+			await removeEntryFiles$1({ images: storedImages });
+			throw error;
+		}
+		const merged = [{
+			id: input.id,
+			createdAt: input.createdAt,
+			mode: input.mode,
+			model: input.model,
+			prompt: input.prompt,
+			size: input.size,
+			quality: input.quality,
+			detail: input.detail,
+			n: input.n,
+			images: storedImages,
+			...input.refName === void 0 ? {} : { refName: input.refName }
+		}, ...await readIndex$1()];
+		const kept = merged.slice(0, 50);
+		for (const dropped of merged.slice(50)) await removeEntryFiles$1(dropped);
+		await writeIndex$1(kept);
+		return kept.map(toWire$1);
+	});
+}
+/** Remove one entry (and its image files). */
+async function removeHistory(id) {
+	return mutateHistory(async () => {
+		const previous = await readIndex$1();
+		const target = previous.find((entry) => entry.id === id);
+		if (target !== void 0) await removeEntryFiles$1(target);
+		const kept = previous.filter((entry) => entry.id !== id);
+		await writeIndex$1(kept);
+		return kept.map(toWire$1);
+	});
+}
+/** Remove every entry (and all image files). */
+async function clearHistory() {
+	return mutateHistory(async () => {
+		const previous = await readIndex$1();
+		for (const entry of previous) await removeEntryFiles$1(entry);
+		await writeIndex$1([]);
+		return [];
+	});
+}
+/** Read one stored image file by its (validated) file name. */
+async function readHistoryImage(file) {
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9-]*-[0-9]+\.(png|jpg|jpeg|webp|gif)$/.test(file)) return void 0;
+	try {
+		return {
+			data: await promises.readFile(path.join(IMAGES_DIR$1, file)),
+			mime: mimeOfFile$2(file)
+		};
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/gallery-store.ts
+/**
+* Host-persisted gallery (user-curated favorites): mirrors the history store
+* (image files + an index.json under ~/.dsh/dsh-imagegen/gallery/) but with no
+* size cap — every entry is an explicit user choice. Appends are deduplicated
+* by image content so adding the same generated image twice is a no-op.
+*
+* Framework-free (node:fs + node:crypto only) so the route layer can drive it
+* directly.
+*/
 const HISTORY_DIR = path.join(homedir(), ".dsh", "dsh-imagegen");
-const INDEX_PATH = path.join(HISTORY_DIR, "index.json");
-const IMAGES_DIR = path.join(HISTORY_DIR, "images");
+const GALLERY_DIR = path.join(HISTORY_DIR, "gallery");
+const INDEX_PATH = path.join(GALLERY_DIR, "index.json");
+const IMAGES_DIR = path.join(GALLERY_DIR, "images");
 let pendingMutation = Promise.resolve();
-function mutateHistory(operation) {
+function mutateGallery(operation) {
 	const next = pendingMutation.then(operation, operation);
 	pendingMutation = next.then(() => void 0, () => void 0);
 	return next;
@@ -285,7 +538,7 @@ function extensionOf(mime) {
 	}
 }
 /** MIME type for a stored image file name (image route responses). */
-function mimeOfFile(file) {
+function mimeOfFile$1(file) {
 	switch (path.extname(file).toLowerCase()) {
 		case ".jpg":
 		case ".jpeg": return "image/jpeg";
@@ -299,6 +552,12 @@ function safeId(id) {
 	const cleaned = id.replace(/[^a-zA-Z0-9-]/g, "-");
 	return cleaned === "" ? "entry" : cleaned;
 }
+/** Short content fingerprint of the entry's first image. */
+function fingerprint(input) {
+	const first = input.images[0];
+	if (first === void 0) return void 0;
+	return createHash("sha1").update(first.b64).digest("hex");
+}
 /** Ensure the storage directories exist. */
 async function ensureDirs() {
 	await promises.mkdir(IMAGES_DIR, { recursive: true });
@@ -353,21 +612,31 @@ function toWire(entry) {
 		detail: entry.detail,
 		n: entry.n,
 		images: entry.images.map((image) => ({
-			url: `/api/dsh-imagegen/history/image/${image.file}`,
+			url: `/api/dsh-imagegen/gallery/image/${image.file}`,
 			mime: image.mime,
 			...image.revisedPrompt === void 0 ? {} : { revisedPrompt: image.revisedPrompt }
 		})),
 		...entry.refName === void 0 ? {} : { refName: entry.refName }
 	};
 }
-/** List the persisted history, newest first, as wire entries. */
-async function listHistory() {
+/** List the persisted gallery, newest first, as wire entries. */
+async function listGallery() {
 	return (await readIndex()).map(toWire);
 }
-/** Append one generation, evicting the oldest beyond HISTORY_MAX. */
-async function appendHistory(input) {
-	return mutateHistory(async () => {
+/** Append one image to the gallery. Deduplicates by first-image content —
+*  appending an image already in the gallery returns `added: false` with the
+*  list unchanged. No size cap: every entry is an explicit user choice. */
+async function appendGallery(input) {
+	return mutateGallery(async () => {
 		await ensureDirs();
+		const hash = fingerprint(input);
+		if (hash !== void 0) {
+			const existing = await readIndex();
+			if (existing.some((entry) => entry.hash === hash)) return {
+				entries: existing.map(toWire),
+				added: false
+			};
+		}
 		const prefix = safeId(input.id);
 		const storedImages = [];
 		try {
@@ -396,17 +665,19 @@ async function appendHistory(input) {
 			detail: input.detail,
 			n: input.n,
 			images: storedImages,
+			...hash === void 0 ? {} : { hash },
 			...input.refName === void 0 ? {} : { refName: input.refName }
 		}, ...await readIndex()];
-		const kept = merged.slice(0, 50);
-		for (const dropped of merged.slice(50)) await removeEntryFiles(dropped);
-		await writeIndex(kept);
-		return kept.map(toWire);
+		await writeIndex(merged);
+		return {
+			entries: merged.map(toWire),
+			added: true
+		};
 	});
 }
 /** Remove one entry (and its image files). */
-async function removeHistory(id) {
-	return mutateHistory(async () => {
+async function removeGallery(id) {
+	return mutateGallery(async () => {
 		const previous = await readIndex();
 		const target = previous.find((entry) => entry.id === id);
 		if (target !== void 0) await removeEntryFiles(target);
@@ -416,8 +687,8 @@ async function removeHistory(id) {
 	});
 }
 /** Remove every entry (and all image files). */
-async function clearHistory() {
-	return mutateHistory(async () => {
+async function clearGallery() {
+	return mutateGallery(async () => {
 		const previous = await readIndex();
 		for (const entry of previous) await removeEntryFiles(entry);
 		await writeIndex([]);
@@ -425,18 +696,287 @@ async function clearHistory() {
 	});
 }
 /** Read one stored image file by its (validated) file name. */
-async function readHistoryImage(file) {
+async function readGalleryImage(file) {
 	if (!/^[a-zA-Z0-9][a-zA-Z0-9-]*-[0-9]+\.(png|jpg|jpeg|webp|gif)$/.test(file)) return void 0;
 	try {
 		return {
 			data: await promises.readFile(path.join(IMAGES_DIR, file)),
-			mime: mimeOfFile(file)
+			mime: mimeOfFile$1(file)
 		};
 	} catch {
 		return;
 	}
 }
 //#endregion
+//#region src/templates-store.ts
+/**
+* Prompt-template library store (awesome-gpt-image-2 mirror).
+*
+* The case list ships as a bundled snapshot (src/templates/cases.json, inside
+* the npm package) so the library works offline out of the box; a successful
+* manual refresh writes a runtime copy under ~/.dsh/dsh-imagegen/templates/
+* which then takes precedence. Reference images are not bundled (441 files,
+* ≈100 MB) — they are fetched from the vibeui.top mirror on demand, cached on
+* disk under ~/.dsh/dsh-imagegen/template-images/, and served from there on
+* every later view.
+*
+* Framework-free (node:fs only) so the route layer and tests can drive it
+* directly.
+*/
+/** Upstream mirror the library refreshes from (vibeui.top static mirror). */
+const SOURCE_URL = "https://vibeui.top/extra/awesome-gpt-image-2/data/cases.json";
+/** Remote image directory (file names come from the case list). */
+const IMAGE_BASE_URL = "https://vibeui.top/extra/awesome-gpt-image-2/data/images/";
+/** Category label map mirrored from vibeui.top's site.js (zh display names). */
+const CATEGORY_ZH = {
+	"Architecture & Spaces": "建筑与空间",
+	"Brand & Logos": "品牌与标志",
+	"Characters & People": "人物与角色",
+	"Charts & Infographics": "图表与信息可视化",
+	"Documents & Publishing": "文档与出版物",
+	"History & Classical Themes": "历史与古风题材",
+	"Illustration & Art": "插画与艺术",
+	"Other Use Cases": "其他应用场景",
+	"Photography & Realism": "摄影与写实",
+	"Posters & Typography": "海报与排版",
+	"Products & E-commerce": "商品与电商",
+	"Scenes & Storytelling": "场景与叙事",
+	"UI & Interfaces": "UI 与界面",
+	"Portraits & Fashion": "人像与时尚",
+	"Celebrities & Sports": "名人与运动",
+	"Characters & IP": "角色与 IP",
+	"Food & Beverage": "美食与饮品",
+	"Brand & Icons": "品牌与图标",
+	"Social Media & Stickers": "社媒与表情包",
+	"Infographics & Diagrams": "信息图与图解",
+	"UI & App Screens": "UI 与应用界面",
+	"Architecture & Interiors": "建筑与室内",
+	"Cinematic & Storytelling": "影视与叙事",
+	"Illustration & Comics": "插画与漫画",
+	"Historical & Fantasy": "历史与幻想",
+	"Animals & Nature": "动物与自然",
+	"Other Creative Uses": "其他创意用途"
+};
+const DATA_DIR = path.join(homedir(), ".dsh", "dsh-imagegen");
+const REFRESHED_CASES_PATH = path.join(DATA_DIR, "templates", "cases.json");
+const IMAGE_CACHE_DIR = path.join(DATA_DIR, "template-images");
+/**
+* Bundled snapshot path. The host bundle emits to lib/index.js while this
+* source file lives at src/templates-store.ts — both exactly one level below
+* the package root — so `../src/templates/cases.json` resolves to the shipped
+* snapshot in development and in the installed package alike.
+*/
+const BUNDLED_CASES_PATH = fileURLToPath(new URL("../src/templates/cases.json", import.meta.url));
+/** Budget for one upstream fetch (list refresh or one image). */
+const FETCH_TIMEOUT_MS = 6e4;
+/** Refuse to cache implausibly large "images". */
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+/** Strict reference-image file names this store writes and serves. */
+const IMAGE_FILE_PATTERN = /^case\d+\.(jpg|jpeg|png|webp|gif)$/i;
+/** In-memory memo of the active list (avoid re-parsing on every request). */
+let memo;
+/** Per-file in-flight downloads, so a gallery scroll never double-fetches. */
+const inflightImages = /* @__PURE__ */ new Map();
+/** Validate + normalize one raw upstream case; undefined when unusable. */
+function normalizeCase(raw) {
+	if (raw === null || typeof raw !== "object") return void 0;
+	const record = raw;
+	const id = Number(record.id);
+	const title = typeof record.title === "string" ? record.title.trim() : "";
+	const prompt = typeof record.prompt === "string" ? record.prompt.trim() : "";
+	if (!Number.isInteger(id) || title === "" || prompt === "") return void 0;
+	const category = typeof record.category === "string" ? record.category : "";
+	const image = imageFileOf(typeof record.image === "string" ? record.image : "");
+	return {
+		id,
+		title,
+		prompt,
+		category,
+		categoryZh: CATEGORY_ZH[category] ?? category,
+		styles: Array.isArray(record.styles) ? record.styles.map(String) : [],
+		scenes: Array.isArray(record.scenes) ? record.scenes.map(String) : [],
+		sourceLabel: typeof record.sourceLabel === "string" ? record.sourceLabel : "",
+		sourceUrl: typeof record.sourceUrl === "string" ? record.sourceUrl : "",
+		githubUrl: typeof record.githubUrl === "string" ? record.githubUrl : "",
+		image,
+		featured: record.featured === true
+	};
+}
+/** Extract the bare file name from an upstream image path. */
+function imageFileOf(value) {
+	const name = value.replace(/^\/+/, "").split("/").pop() ?? "";
+	return IMAGE_FILE_PATTERN.test(name) ? name : "";
+}
+/** Parse a snapshot payload (bundled, refreshed cache, or fresh download). */
+function parseSnapshot(payload) {
+	if (payload === null || typeof payload !== "object") return void 0;
+	const snapshot = payload;
+	if (!Array.isArray(snapshot.cases)) return void 0;
+	const cases = [];
+	for (const raw of snapshot.cases) {
+		const normalized = normalizeCase(raw);
+		if (normalized !== void 0) cases.push(normalized);
+	}
+	if (cases.length === 0) return void 0;
+	cases.sort((a, b) => b.id - a.id);
+	return {
+		cases,
+		repository: typeof snapshot.repository === "string" && snapshot.repository !== "" ? snapshot.repository : "freestylefly/awesome-gpt-image-2",
+		fetchedAt: typeof snapshot.fetchedAt === "string" && snapshot.fetchedAt !== "" ? snapshot.fetchedAt : ""
+	};
+}
+/** Read + parse a snapshot file; undefined when missing/corrupt. */
+async function readSnapshotFile(file) {
+	try {
+		return parseSnapshot(JSON.parse(await promises.readFile(file, "utf8")));
+	} catch {
+		return;
+	}
+}
+/**
+* The active template list: the refreshed runtime copy wins, the bundled
+* snapshot is the always-available fallback. Memoized; a successful refresh
+* replaces the memo.
+*/
+async function listTemplates() {
+	if (memo !== void 0) return memo;
+	const refreshed = await readSnapshotFile(REFRESHED_CASES_PATH);
+	if (refreshed !== void 0) {
+		memo = {
+			...refreshed,
+			total: refreshed.cases.length,
+			origin: "refreshed"
+		};
+		return memo;
+	}
+	const bundled = await readSnapshotFile(BUNDLED_CASES_PATH);
+	if (bundled !== void 0) {
+		memo = {
+			...bundled,
+			total: bundled.cases.length,
+			origin: "bundled"
+		};
+		return memo;
+	}
+	memo = {
+		cases: [],
+		total: 0,
+		origin: "bundled",
+		repository: "freestylefly/awesome-gpt-image-2",
+		fetchedAt: ""
+	};
+	return memo;
+}
+/**
+* Re-download the case list from the upstream mirror and persist it as the
+* runtime copy. Throws with a user-presentable message on failure; the
+* previous list (refreshed or bundled) stays active.
+*/
+async function refreshTemplates() {
+	let response;
+	try {
+		response = await fetch(SOURCE_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+	} catch (error) {
+		throw new Error(`无法连接模板库源站：${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!response.ok) throw new Error(`模板库源站拒绝请求（HTTP ${response.status}）`);
+	let payload;
+	try {
+		payload = await response.json();
+	} catch {
+		throw new Error("模板库源站返回了非 JSON 响应");
+	}
+	const parsed = parseSnapshot(payload);
+	if (parsed === void 0) throw new Error("模板库源站数据格式无效");
+	const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const snapshot = {
+		repository: parsed.repository,
+		sourceUrl: SOURCE_URL,
+		fetchedAt,
+		totalCases: parsed.cases.length,
+		cases: parsed.cases
+	};
+	await promises.mkdir(path.dirname(REFRESHED_CASES_PATH), { recursive: true });
+	const tmp = `${REFRESHED_CASES_PATH}.tmp-${process.pid}`;
+	await promises.writeFile(tmp, JSON.stringify(snapshot), "utf8");
+	await promises.rename(tmp, REFRESHED_CASES_PATH);
+	memo = {
+		cases: parsed.cases,
+		total: parsed.cases.length,
+		origin: "refreshed",
+		repository: parsed.repository,
+		fetchedAt
+	};
+	return {
+		total: parsed.cases.length,
+		fetchedAt
+	};
+}
+/** MIME type for a cached reference-image file name. */
+function mimeOfFile(file) {
+	switch (path.extname(file).toLowerCase()) {
+		case ".jpg":
+		case ".jpeg": return "image/jpeg";
+		case ".webp": return "image/webp";
+		case ".gif": return "image/gif";
+		default: return "image/png";
+	}
+}
+/** Download one reference image into the disk cache; undefined on failure. */
+async function fetchTemplateImage(file) {
+	let response;
+	try {
+		response = await fetch(`${IMAGE_BASE_URL}${encodeURIComponent(file)}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+	} catch {
+		return;
+	}
+	if (!response.ok) return void 0;
+	if (Number(response.headers.get("content-length") ?? 0) > MAX_IMAGE_BYTES) return void 0;
+	const data = Buffer.from(await response.arrayBuffer());
+	if (data.byteLength === 0 || data.byteLength > MAX_IMAGE_BYTES) return void 0;
+	const mime = mimeOfFile(file);
+	try {
+		await promises.mkdir(IMAGE_CACHE_DIR, { recursive: true });
+		const tmp = path.join(IMAGE_CACHE_DIR, `${file}.tmp-${process.pid}`);
+		await promises.writeFile(tmp, data);
+		await promises.rename(tmp, path.join(IMAGE_CACHE_DIR, file));
+	} catch {}
+	return {
+		data,
+		mime
+	};
+}
+/**
+* Read one reference image for the template library. Cache hit → disk; miss →
+* fetch from the upstream mirror, cache, and serve. Only file names present in
+* the active case list are served, so the route can never act as an open
+* proxy. Undefined when the name is unknown or the fetch failed.
+*/
+async function readTemplateImage(file) {
+	if (!IMAGE_FILE_PATTERN.test(file) || file.includes("..")) return void 0;
+	if (!(await listTemplates()).cases.some((entry) => entry.image === file)) return void 0;
+	const cached = path.join(IMAGE_CACHE_DIR, file);
+	try {
+		return {
+			data: await promises.readFile(cached),
+			mime: mimeOfFile(file)
+		};
+	} catch {}
+	const inflight = inflightImages.get(file);
+	if (inflight !== void 0) return inflight;
+	const pending = fetchTemplateImage(file);
+	inflightImages.set(file, pending);
+	try {
+		return await pending;
+	} finally {
+		inflightImages.delete(file);
+	}
+}
+/** Drop the in-memory list memo (tests). */
+function clearTemplateMemo() {
+	memo = void 0;
+}
+//#endregion
 //#region src/updater.ts
 /** GitHub Release discovery and explicit, user-triggered plugin updates. */
 /** Keep this in sync with package.json for each published release. */
@@ -683,6 +1223,18 @@ function makeRoutes(deps) {
 		clear: clearHistory,
 		readImage: readHistoryImage
 	};
+	const gallery = deps.gallery ?? {
+		list: listGallery,
+		append: appendGallery,
+		remove: removeGallery,
+		clear: clearGallery,
+		readImage: readGalleryImage
+	};
+	const templates = deps.templates ?? {
+		list: listTemplates,
+		refresh: refreshTemplates,
+		readImage: readTemplateImage
+	};
 	const guard = (req, res, method) => {
 		if (!isLoopbackRequest(req)) {
 			writeJson(res, 403, { error: "forbidden: loopback-only" });
@@ -1028,6 +1580,213 @@ function makeRoutes(deps) {
 				});
 				res.end(found.data);
 			}
+		},
+		{
+			kind: "exact",
+			path: GALLERY_API.list,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						entries: await gallery.list()
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "gallery-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: GALLERY_API.append,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req, MAX_HISTORY_BODY_BYTES);
+				if (body === void 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "unreadable JSON body"
+					});
+					return;
+				}
+				const entry = parseHistoryEntryInput(body);
+				if (entry === void 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "malformed gallery entry"
+					});
+					return;
+				}
+				try {
+					const result = await gallery.append({
+						...entry,
+						id: randomUUID()
+					});
+					writeJson(res, 200, {
+						ok: true,
+						entries: result.entries,
+						added: result.added
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "gallery-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: GALLERY_API.remove,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const id = body !== void 0 && typeof body.id === "string" ? body.id : "";
+				if (id === "") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "gallery id is required"
+					});
+					return;
+				}
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						entries: await gallery.remove(id)
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "gallery-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: GALLERY_API.clear,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						entries: await gallery.clear()
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "gallery-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "prefix",
+			path: GALLERY_API.image,
+			handler: async (req, res) => {
+				if (!isLoopbackRequest(req)) {
+					writeJson(res, 403, { error: "forbidden: loopback-only" });
+					return;
+				}
+				if (req.method !== "GET") {
+					writeJson(res, 405, { error: `method not allowed: ${req.method}` });
+					return;
+				}
+				const file = imageFileFrom(req.url, GALLERY_API.image);
+				if (file === void 0) {
+					writeJson(res, 404, { error: "not found" });
+					return;
+				}
+				const found = await gallery.readImage(file);
+				if (found === void 0) {
+					writeJson(res, 404, { error: "not found" });
+					return;
+				}
+				res.writeHead(200, {
+					"content-type": found.mime,
+					"content-length": found.data.length,
+					"cache-control": "private, max-age=3600"
+				});
+				res.end(found.data);
+			}
+		},
+		{
+			kind: "exact",
+			path: TEMPLATES_API.list,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						...await templates.list()
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "templates-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: TEMPLATES_API.refresh,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						...await templates.refresh()
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "templates-refresh-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "prefix",
+			path: TEMPLATES_API.image,
+			handler: async (req, res) => {
+				if (!isLoopbackRequest(req)) {
+					writeJson(res, 403, { error: "forbidden: loopback-only" });
+					return;
+				}
+				if (req.method !== "GET") {
+					writeJson(res, 405, { error: `method not allowed: ${req.method}` });
+					return;
+				}
+				const file = imageFileFrom(req.url, TEMPLATES_API.image);
+				if (file === void 0) {
+					writeJson(res, 404, { error: "not found" });
+					return;
+				}
+				const found = await templates.readImage(file);
+				if (found === void 0) {
+					writeJson(res, 404, { error: "not found" });
+					return;
+				}
+				res.writeHead(200, {
+					"content-type": found.mime,
+					"content-length": found.data.length,
+					"cache-control": "private, max-age=86400"
+				});
+				res.end(found.data);
+			}
 		}
 	];
 }
@@ -1051,7 +1810,7 @@ const DEFAULT_ANNOUNCE = true;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 150;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const IMAGEGEN_GUIDANCE = "本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2），支持文生图（/images/generations）与图生图（/images/edits，上传参考图）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / 文生图 / 图生图」时即指本插件，请据此协作。";
+const IMAGEGEN_GUIDANCE = "本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2 / grok-imagine-image），支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok 模型按官方 JSON image_url 协议发送）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载；可一键把满意的图片加入「画廊」（工作台顶部 文生图 / 图生图 / 画廊 三个标签页，画廊在右侧展示，收藏持久化在本地 ~/.dsh/dsh-imagegen/gallery/）。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条 gpt-image-2 提示词案例（含中文标题、分类、参考图，可搜索/按分类筛选），参考图经宿主代理按需缓存到本地；用户可一键把模板提示词填入提示词框再生成。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / grok-imagine-image / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。";
 /**
 * Mount the settings section, routes, and announcement.
 * @param ctx - host plugin context carrying webServer/systemPrompt.
@@ -1110,4 +1869,4 @@ function apply(ctx, config) {
 	sync();
 }
 //#endregion
-export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, apply, checkForUpdate, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, makeRoutes, name, profileFromProcess };
+export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, appendGallery, apply, checkForUpdate, clearGallery, clearTemplateMemo, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, listGallery, listTemplates, makeRoutes, name, profileFromProcess, readGalleryImage, readTemplateImage, refreshTemplates, removeGallery };