@dickpy/dsh-imagegen 1.5.0 → 1.5.2

package/lib/index.js

@@ -1,4 +1,5 @@
-import { SettingsConflictError, installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import * as settingsModule from "@deepseek-ai/dsh-settings";
+import { SettingsConflictError } from "@deepseek-ai/dsh-settings";
 import z from "schemastery";
 import { createHash, randomUUID } from "node:crypto";
 import { promises } from "node:fs";
@@ -7,6 +8,29 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/settings-compat.ts
+const compatModule = settingsModule;
+/** Brand namespaces where the installed settings package still exposes it. */
+function settingsNamespaceCompat(value) {
+	return compatModule.settingsNamespace?.(value) ?? value;
+}
+/**
+* Register an optional settings section across the rc.7 and alpha.2 APIs.
+* rc.7 exposes a module helper; alpha.2 moves the helper onto the provider.
+*/
+function installSettingsSectionCompat(ctx, ns, schema, entry, hooks) {
+	const legacyInstaller = compatModule.installSettingsSection;
+	if (legacyInstaller !== void 0) {
+		legacyInstaller(ctx, ns, schema, entry, hooks);
+		return;
+	}
+	ctx.inject(["settings"], (sctx) => {
+		const provider = sctx.get("settings");
+		if (provider.installSection === void 0) throw new TypeError("dsh-settings does not expose installSection");
+		provider.installSection(ctx, ns, schema, entry, hooks);
+	});
+}
+//#endregion
 //#region src/protocol.ts
 /**
 * Wire contract shared by the host and client halves of dsh-imagegen: the
@@ -16,7 +40,7 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 /** 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.5.0";
+const PLUGIN_VERSION = "1.5.2";
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 const SETTINGS_API = {
 	describe: "/api/dsh-imagegen/settings/describe",
@@ -82,16 +106,48 @@ const GALLERY_API = {
 	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.
+* Same-origin route family for the prompt-template libraries. The library is
+* multi-source: every request names a source id from {@link TEMPLATE_SOURCES},
+* each source keeps an independent snapshot/image cache host-side, and
+* reference images are proxied through the source-scoped `image` prefix route
+* (`…/image/<sourceId>/<file>`) 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",
+	sample: "/api/dsh-imagegen/templates/sample",
 	image: "/api/dsh-imagegen/templates/image"
 };
+/** Same-origin route family for the user's saved (favorited) templates. */
+const TEMPLATE_FAVORITES_API = {
+	list: "/api/dsh-imagegen/templates/favorites/list",
+	add: "/api/dsh-imagegen/templates/favorites/add",
+	remove: "/api/dsh-imagegen/templates/favorites/remove"
+};
+/**
+* The template-library source registry. Each entry is fully independent (own
+* upstream JSON, own image pool, own refresh state) and renders as its own
+* tab; adding a source later means appending an entry here plus a host-side
+* fetch definition in templates-store.ts and an optional bundled snapshot.
+*/
+const TEMPLATE_SOURCES = [{
+	id: "vibeui",
+	label: "精选案例库",
+	homepage: "https://vibeui.top/",
+	description: "awesome-gpt-image-2 精选提示词案例（vibeui.top 镜像）"
+}, {
+	id: "canghe",
+	label: "沧河案例库",
+	homepage: "https://gpt-image2.canghe.ai/",
+	description: "GPT-Image2 Prompt Gallery（gpt-image2.canghe.ai，定期更新）"
+}];
+/** Default source id when a request does not name one (legacy clients). */
+const DEFAULT_TEMPLATE_SOURCE_ID = TEMPLATE_SOURCES[0].id;
+/** True when the id names a registered template source. */
+function isTemplateSourceId(id) {
+	return TEMPLATE_SOURCES.some((source) => source.id === id);
+}
 //#endregion
 //#region src/model-catalog.ts
 const ENTRIES = {
@@ -1335,24 +1391,42 @@ async function readGalleryImage(file) {
 //#endregion
 //#region src/templates-store.ts
 /**
-* Prompt-template library store (awesome-gpt-image-2 mirror).
+* Prompt-template library store (multi-source).
+*
+* The library is a registry of independent sources (see TEMPLATE_SOURCES in
+* protocol.ts): each source has its own upstream JSON list, its own bundled
+* snapshot, its own refreshed runtime copy, and its own on-disk image pool.
+* Sources never mix — the overlay shows one tab per source and every request
+* names the source explicitly.
 *
-* 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
+* Each case list ships as a bundled snapshot (src/templates/<file>, inside the
+* npm package) so every library works offline out of the box; a successful
+* refresh (manual, or the periodic background sync) writes a runtime copy
+* under ~/.dsh/dsh-imagegen/templates/<sourceId>/ which then takes precedence.
+* Reference images are not bundled (hundreds of files, ≈100 MB per source) —
+* they are fetched from the source's mirror on demand, cached on disk under
+* ~/.dsh/dsh-imagegen/template-images/<sourceId>/, 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). */
+/** Source registry (host half): where each TEMPLATE_SOURCES entry loads from. */
+const SOURCE_DEFS = {
+	vibeui: {
+		listUrl: "https://vibeui.top/extra/awesome-gpt-image-2/data/cases.json",
+		imageBaseUrl: "https://vibeui.top/extra/awesome-gpt-image-2/data/images/",
+		bundledPath: fileURLToPath(new URL("../src/templates/cases.json", import.meta.url)),
+		legacySnapshotPath: "legacy",
+		legacyImageDir: "legacy"
+	},
+	canghe: {
+		listUrl: "https://gpt-image2.canghe.ai/cases.json",
+		imageBaseUrl: "https://gpt-image2.canghe.ai/images/",
+		bundledPath: fileURLToPath(new URL("../src/templates/canghe-cases.json", import.meta.url))
+	}
+};
+/** Category label map mirrored from the upstream sites' site.js (zh names). */
 const CATEGORY_ZH = {
 	"Architecture & Spaces": "建筑与空间",
 	"Brand & Logos": "品牌与标志",
@@ -1382,26 +1456,26 @@ const CATEGORY_ZH = {
 	"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));
+const DATA_DIR$1 = path.join(homedir(), ".dsh", "dsh-imagegen");
+const REFRESHED_DIR = path.join(DATA_DIR$1, "templates");
+const IMAGE_CACHE_ROOT = path.join(DATA_DIR$1, "template-images");
+/** Pre-1.6 single-source locations (vibeui fallbacks). */
+const LEGACY_SNAPSHOT_PATH = path.join(REFRESHED_DIR, "cases.json");
+const LEGACY_IMAGE_DIR = IMAGE_CACHE_ROOT;
 /** 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-source in-memory memo of the active list (avoid re-parsing per request). */
+const memos = /* @__PURE__ */ new Map();
 /** Per-file in-flight downloads, so a gallery scroll never double-fetches. */
 const inflightImages = /* @__PURE__ */ new Map();
+/** Resolve a registered source id to its fetch definition. */
+function sourceDefOf(sourceId) {
+	return SOURCE_DEFS[sourceId];
+}
 /** Validate + normalize one raw upstream case; undefined when unusable. */
 function normalizeCase(raw) {
 	if (raw === null || typeof raw !== "object") return void 0;
@@ -1459,50 +1533,61 @@ async function readSnapshotFile(file) {
 	}
 }
 /**
-* The active template list: the refreshed runtime copy wins, the bundled
-* snapshot is the always-available fallback. Memoized; a successful refresh
-* replaces the memo.
+* The active template list of one source: the refreshed runtime copy wins, the
+* bundled snapshot is the always-available fallback. Memoized per source; a
+* successful refresh replaces that source's memo.
 */
-async function listTemplates() {
+async function listTemplates(sourceId = DEFAULT_TEMPLATE_SOURCE_ID) {
+	const def = sourceDefOf(sourceId);
+	if (def === void 0) throw new Error(`未知的模板库来源：${sourceId}`);
+	const memo = memos.get(sourceId);
 	if (memo !== void 0) return memo;
-	const refreshed = await readSnapshotFile(REFRESHED_CASES_PATH);
+	const refreshed = await readSnapshotFile(path.join(REFRESHED_DIR, sourceId, "cases.json")) ?? (def.legacySnapshotPath !== void 0 ? await readSnapshotFile(LEGACY_SNAPSHOT_PATH) : void 0);
 	if (refreshed !== void 0) {
-		memo = {
+		const result = {
+			sourceId,
 			...refreshed,
 			total: refreshed.cases.length,
 			origin: "refreshed"
 		};
-		return memo;
+		memos.set(sourceId, result);
+		return result;
 	}
-	const bundled = await readSnapshotFile(BUNDLED_CASES_PATH);
+	const bundled = await readSnapshotFile(def.bundledPath);
 	if (bundled !== void 0) {
-		memo = {
+		const result = {
+			sourceId,
 			...bundled,
 			total: bundled.cases.length,
 			origin: "bundled"
 		};
-		return memo;
+		memos.set(sourceId, result);
+		return result;
 	}
-	memo = {
+	const result = {
+		sourceId,
 		cases: [],
 		total: 0,
 		origin: "bundled",
 		repository: "freestylefly/awesome-gpt-image-2",
 		fetchedAt: ""
 	};
-	return memo;
+	memos.set(sourceId, result);
+	return result;
 }
 /**
-* 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
+* Re-download one source's case list from its 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() {
+async function refreshTemplates(sourceId = DEFAULT_TEMPLATE_SOURCE_ID) {
+	const def = sourceDefOf(sourceId);
+	if (def === void 0) throw new Error(`未知的模板库来源：${sourceId}`);
 	let response;
 	try {
-		response = await fetch(SOURCE_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+		response = await fetch(def.listUrl, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
 	} catch (error) {
-		throw new Error(`无法连接模板库源站：${error instanceof Error ? error.message : String(error)}`);
+		throw new Error(`无法连接模板库源站（${sourceId}）：${error instanceof Error ? error.message : String(error)}`);
 	}
 	if (!response.ok) throw new Error(`模板库源站拒绝请求（HTTP ${response.status}）`);
 	let payload;
@@ -1516,27 +1601,89 @@ async function refreshTemplates() {
 	const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
 	const snapshot = {
 		repository: parsed.repository,
-		sourceUrl: SOURCE_URL,
+		sourceUrl: def.listUrl,
 		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}`;
+	const target = path.join(REFRESHED_DIR, sourceId, "cases.json");
+	await promises.mkdir(path.dirname(target), { recursive: true });
+	const tmp = `${target}.tmp-${process.pid}`;
 	await promises.writeFile(tmp, JSON.stringify(snapshot), "utf8");
-	await promises.rename(tmp, REFRESHED_CASES_PATH);
-	memo = {
+	await promises.rename(tmp, target);
+	const result = {
+		sourceId,
 		cases: parsed.cases,
 		total: parsed.cases.length,
 		origin: "refreshed",
 		repository: parsed.repository,
 		fetchedAt
 	};
+	memos.set(sourceId, result);
 	return {
+		sourceId,
 		total: parsed.cases.length,
 		fetchedAt
 	};
 }
+/** Fisher–Yates shuffle (returns a copy; never mutates the pool). */
+function shuffled(items) {
+	const out = [...items];
+	for (let i = out.length - 1; i > 0; i -= 1) {
+		const j = Math.floor(Math.random() * (i + 1));
+		const a = out[i];
+		out[i] = out[j];
+		out[j] = a;
+	}
+	return out;
+}
+/**
+* Draw up to `count` random cases across every source that has data,
+* round-robin between sources so one huge library cannot crowd out the
+* others, then shuffle the final pick. Reads memoized lists, so this never
+* touches the network — cheap enough for every shuffle click.
+*/
+async function sampleTemplates(count = 9) {
+	const size = Math.min(12, Math.max(1, Math.floor(count) || 9));
+	const pools = [];
+	for (const source of TEMPLATE_SOURCES) try {
+		const list = await listTemplates(source.id);
+		if (list.cases.length > 0) pools.push({
+			sourceId: source.id,
+			cases: shuffled(list.cases)
+		});
+	} catch {}
+	const picks = [];
+	for (let round = 0; picks.length < size && pools.some((pool) => pool.cases.length > 0); round += 1) {
+		const pool = pools[round % pools.length];
+		const picked = pool.cases.pop();
+		if (picked !== void 0) picks.push({
+			sourceId: pool.sourceId,
+			case: picked
+		});
+	}
+	return shuffled(picks);
+}
+/** Serially refresh every registered source; one failure never stops the rest. */
+async function syncAllTemplates() {
+	const reports = [];
+	for (const source of TEMPLATE_SOURCES) try {
+		const result = await refreshTemplates(source.id);
+		reports.push({
+			sourceId: source.id,
+			ok: true,
+			total: result.total
+		});
+	} catch (error) {
+		reports.push({
+			sourceId: source.id,
+			ok: false,
+			total: 0,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return reports;
+}
 /** MIME type for a cached reference-image file name. */
 function mimeOfFile(file) {
 	switch (path.extname(file).toLowerCase()) {
@@ -1547,11 +1694,11 @@ function mimeOfFile(file) {
 		default: return "image/png";
 	}
 }
-/** Download one reference image into the disk cache; undefined on failure. */
-async function fetchTemplateImage(file) {
+/** Download one reference image into the source's disk cache; undefined on failure. */
+async function fetchTemplateImage(def, file, cacheDir) {
 	let response;
 	try {
-		response = await fetch(`${IMAGE_BASE_URL}${encodeURIComponent(file)}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+		response = await fetch(`${def.imageBaseUrl}${encodeURIComponent(file)}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
 	} catch {
 		return;
 	}
@@ -1561,10 +1708,10 @@ async function fetchTemplateImage(file) {
 	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.mkdir(cacheDir, { recursive: true });
+		const tmp = path.join(cacheDir, `${file}.tmp-${process.pid}`);
 		await promises.writeFile(tmp, data);
-		await promises.rename(tmp, path.join(IMAGE_CACHE_DIR, file));
+		await promises.rename(tmp, path.join(cacheDir, file));
 	} catch {}
 	return {
 		data,
@@ -1572,33 +1719,143 @@ async function fetchTemplateImage(file) {
 	};
 }
 /**
-* 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
+* Read one reference image for a source's library. Cache hit → disk; miss →
+* fetch from that source's 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) {
+async function readTemplateImage(sourceId, file) {
+	const def = sourceDefOf(sourceId);
+	if (def === void 0) return void 0;
 	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);
+	if (!(await listTemplates(sourceId)).cases.some((entry) => entry.image === file)) return void 0;
+	const cacheDir = path.join(IMAGE_CACHE_ROOT, sourceId);
 	try {
 		return {
-			data: await promises.readFile(cached),
+			data: await promises.readFile(path.join(cacheDir, file)),
 			mime: mimeOfFile(file)
 		};
 	} catch {}
-	const inflight = inflightImages.get(file);
+	if (def.legacyImageDir !== void 0) try {
+		return {
+			data: await promises.readFile(path.join(LEGACY_IMAGE_DIR, file)),
+			mime: mimeOfFile(file)
+		};
+	} catch {}
+	const cacheKey = `${sourceId}/${file}`;
+	const inflight = inflightImages.get(cacheKey);
 	if (inflight !== void 0) return inflight;
-	const pending = fetchTemplateImage(file);
-	inflightImages.set(file, pending);
+	const pending = fetchTemplateImage(def, file, cacheDir);
+	inflightImages.set(cacheKey, pending);
 	try {
 		return await pending;
 	} finally {
-		inflightImages.delete(file);
+		inflightImages.delete(cacheKey);
 	}
 }
-/** Drop the in-memory list memo (tests). */
+/** Drop the in-memory list memos (tests). */
 function clearTemplateMemo() {
+	memos.clear();
+}
+//#endregion
+//#region src/template-favorites.ts
+/**
+* Favorites store for the prompt-template library.
+*
+* The user's starred templates persist host-side as full case snapshots under
+* ~/.dsh/dsh-imagegen/templates/favorites.json, keyed by
+* `${sourceId}:${caseId}` — the snapshot means a favorite stays usable even
+* after the upstream list drops or renumbers the case. Framework-free
+* (node:fs only) so the route layer and tests can drive it directly.
+*/
+const DATA_DIR = path.join(homedir(), ".dsh", "dsh-imagegen");
+const FAVORITES_PATH = path.join(DATA_DIR, "templates", "favorites.json");
+/** Refuse to grow the file without bound; the user curates this list. */
+const MAX_FAVORITES = 1e3;
+/** In-memory memo of the persisted list. */
+let memo;
+/** Build the stable key of one case within a source. */
+function templateFavoriteKey(sourceId, caseId) {
+	return `${sourceId}:${caseId}`;
+}
+/** Validate + normalize one raw stored favorite; undefined when unusable. */
+function normalizeFavorite(raw) {
+	if (raw === null || typeof raw !== "object") return void 0;
+	const record = raw;
+	if (typeof record.key !== "string" || typeof record.savedAt !== "string") return void 0;
+	const sourceId = typeof record.sourceId === "string" ? record.sourceId : "";
+	if (!isTemplateSourceId(sourceId)) return void 0;
+	if (record.key !== templateFavoriteKey(sourceId, Number(record.case && record.case.id))) return void 0;
+	const rawCase = record.case;
+	if (rawCase === null || typeof rawCase !== "object") return void 0;
+	const item = rawCase;
+	const id = Number(item.id);
+	const title = typeof item.title === "string" ? item.title : "";
+	const prompt = typeof item.prompt === "string" ? item.prompt : "";
+	if (!Number.isInteger(id) || title === "" || prompt === "") return void 0;
+	const snapshot = {
+		id,
+		title,
+		prompt,
+		category: typeof item.category === "string" ? item.category : "",
+		categoryZh: typeof item.categoryZh === "string" ? item.categoryZh : "",
+		styles: Array.isArray(item.styles) ? item.styles.map(String) : [],
+		scenes: Array.isArray(item.scenes) ? item.scenes.map(String) : [],
+		sourceLabel: typeof item.sourceLabel === "string" ? item.sourceLabel : "",
+		sourceUrl: typeof item.sourceUrl === "string" ? item.sourceUrl : "",
+		githubUrl: typeof item.githubUrl === "string" ? item.githubUrl : "",
+		image: typeof item.image === "string" ? item.image : "",
+		featured: item.featured === true
+	};
+	return {
+		key: record.key,
+		sourceId,
+		savedAt: record.savedAt,
+		case: snapshot
+	};
+}
+/** Read + parse the favorites file (memoized). */
+async function listTemplateFavorites() {
+	if (memo !== void 0) return memo;
+	try {
+		const parsed = JSON.parse(await promises.readFile(FAVORITES_PATH, "utf8"));
+		memo = Array.isArray(parsed) ? parsed.map(normalizeFavorite).filter((entry) => entry !== void 0) : [];
+	} catch {
+		memo = [];
+	}
+	return memo;
+}
+/** Persist the list atomically and update the memo. */
+async function writeFavorites(entries) {
+	memo = entries;
+	await promises.mkdir(path.dirname(FAVORITES_PATH), { recursive: true });
+	const tmp = `${FAVORITES_PATH}.tmp-${process.pid}`;
+	await promises.writeFile(tmp, JSON.stringify(entries, null, 2), "utf8");
+	await promises.rename(tmp, FAVORITES_PATH);
+}
+/** Star one template. Re-starring refreshes the snapshot and is idempotent. */
+async function addTemplateFavorite(sourceId, item) {
+	if (!isTemplateSourceId(sourceId)) throw new Error(`未知的模板库来源：${sourceId}`);
+	const key = templateFavoriteKey(sourceId, item.id);
+	const rest = (await listTemplateFavorites()).filter((entry) => entry.key !== key);
+	const next = [{
+		key,
+		sourceId,
+		savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		case: item
+	}, ...rest].slice(0, MAX_FAVORITES);
+	await writeFavorites(next);
+	return next;
+}
+/** Unstar one template by key; unknown keys are a no-op. */
+async function removeTemplateFavorite(key) {
+	const next = (await listTemplateFavorites()).filter((entry) => entry.key !== key);
+	if (next.length === memo?.length) return next;
+	await writeFavorites(next);
+	return next;
+}
+/** Drop the in-memory memo (tests). */
+function clearTemplateFavoritesMemo() {
 	memo = void 0;
 }
 //#endregion
@@ -1817,6 +2074,12 @@ async function readJsonBody(req, maxBytes = MAX_JSON_BODY_BYTES) {
 function messageOf(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+/** Validate the { source } body of a template-library request. */
+function templateSourceOf(body) {
+	const raw = body?.source;
+	if (raw === void 0 || raw === "") return DEFAULT_TEMPLATE_SOURCE_ID;
+	return typeof raw === "string" && isTemplateSourceId(raw) ? raw : void 0;
+}
 function parseGenerateRequest(body) {
 	const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
 	if (prompt === "") return void 0;
@@ -1987,8 +2250,14 @@ function makeRoutes(deps) {
 	const templates = deps.templates ?? {
 		list: listTemplates,
 		refresh: refreshTemplates,
+		sample: sampleTemplates,
 		readImage: readTemplateImage
 	};
+	const favorites = deps.favorites ?? {
+		list: listTemplateFavorites,
+		add: addTemplateFavorite,
+		remove: removeTemplateFavorite
+	};
 	const resolvePrompt = deps.resolvePrompt ?? (() => ({
 		apiUrl: "",
 		apiKey: "",
@@ -2312,7 +2581,7 @@ function makeRoutes(deps) {
 				}
 				const expectedRevision = typeof body.expectedRevision === "number" ? body.expectedRevision : void 0;
 				try {
-					await deps.settings.mutate(settingsNamespace(ns), body.ops, expectedRevision);
+					await deps.settings.mutate(ns, body.ops, expectedRevision);
 				} catch (error) {
 					writeJson(res, 200, failureOf(error));
 					return;
@@ -2822,10 +3091,20 @@ function makeRoutes(deps) {
 			path: TEMPLATES_API.list,
 			handler: async (req, res) => {
 				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const sourceId = templateSourceOf(body);
+				if (sourceId === void 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "templates-source-unknown",
+						message: `未知的模板库来源：${String(body?.source ?? "")}`
+					});
+					return;
+				}
 				try {
 					writeJson(res, 200, {
 						ok: true,
-						...await templates.list()
+						...await templates.list(sourceId)
 					});
 				} catch (error) {
 					writeJson(res, 200, {
@@ -2841,10 +3120,20 @@ function makeRoutes(deps) {
 			path: TEMPLATES_API.refresh,
 			handler: async (req, res) => {
 				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const sourceId = templateSourceOf(body);
+				if (sourceId === void 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "templates-source-unknown",
+						message: `未知的模板库来源：${String(body?.source ?? "")}`
+					});
+					return;
+				}
 				try {
 					writeJson(res, 200, {
 						ok: true,
-						...await templates.refresh()
+						...await templates.refresh(sourceId)
 					});
 				} catch (error) {
 					writeJson(res, 200, {
@@ -2855,6 +3144,28 @@ function makeRoutes(deps) {
 				}
 			}
 		},
+		{
+			kind: "exact",
+			path: TEMPLATES_API.sample,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const requested = Number(body?.count);
+				const count = Number.isFinite(requested) ? requested : 9;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						samples: await templates.sample(count)
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "templates-sample-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
 		{
 			kind: "prefix",
 			path: TEMPLATES_API.image,
@@ -2867,12 +3178,15 @@ function makeRoutes(deps) {
 					writeJson(res, 405, { error: `method not allowed: ${req.method}` });
 					return;
 				}
-				const file = imageFileFrom(req.url, TEMPLATES_API.image);
-				if (file === void 0) {
+				const raw = imageFileFrom(req.url, TEMPLATES_API.image);
+				const slash = raw?.indexOf("/") ?? -1;
+				const sourceId = slash > 0 ? raw.slice(0, slash) : "";
+				const file = slash > 0 ? raw.slice(slash + 1) : "";
+				if (sourceId === "" || !isTemplateSourceId(sourceId) || file === "") {
 					writeJson(res, 404, { error: "not found" });
 					return;
 				}
-				const found = await templates.readImage(file);
+				const found = await templates.readImage(sourceId, file);
 				if (found === void 0) {
 					writeJson(res, 404, { error: "not found" });
 					return;
@@ -2884,6 +3198,96 @@ function makeRoutes(deps) {
 				});
 				res.end(found.data);
 			}
+		},
+		{
+			kind: "exact",
+			path: TEMPLATE_FAVORITES_API.list,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						favorites: await favorites.list()
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "template-favorites-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: TEMPLATE_FAVORITES_API.add,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const sourceId = templateSourceOf(body);
+				const rawCase = body?.case;
+				if (sourceId === void 0 || rawCase === null || typeof rawCase !== "object") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "template-favorite-invalid",
+						message: "收藏请求缺少有效的来源或模板数据"
+					});
+					return;
+				}
+				const record = rawCase;
+				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 === "") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "template-favorite-invalid",
+						message: "收藏请求缺少有效的模板数据"
+					});
+					return;
+				}
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						favorites: await favorites.add(sourceId, rawCase)
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "template-favorites-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: TEMPLATE_FAVORITES_API.remove,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const key = typeof body?.key === "string" ? body.key : "";
+				if (key === "") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "template-favorite-invalid",
+						message: "取消收藏请求缺少模板标识"
+					});
+					return;
+				}
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						favorites: await favorites.remove(key)
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "template-favorites-failed",
+						message: messageOf(error)
+					});
+				}
+			}
 		}
 	];
 }
@@ -3446,7 +3850,7 @@ const inject = [
 	"commands"
 ];
 /** The branded settings namespace of this plugin (the card edits it). */
-const ImageGenSettingsNamespace = settingsNamespace(IMAGEGEN_SETTINGS_NAMESPACE);
+const ImageGenSettingsNamespace = settingsNamespaceCompat(IMAGEGEN_SETTINGS_NAMESPACE);
 const Config = z.object({
 	enabled: z.boolean().default(true),
 	announceToAgent: z.boolean().default(true),
@@ -3477,7 +3881,7 @@ const DEFAULT_ALLOW_AGENT_IMAGE_GENERATION = 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（每个渠道 = 一个 API 端点 + 各自的模型目录），支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok-imagine 模型按官方 JSON image_url 协议发送，nanobanana 系列按 aspect_ratio / image_size 参数协议发送；seedream 系列统一走 /images/generations，参考图以 JSON image 数组发送；智谱 `glm-image` 使用官方 `/api/paas/v4/images/generations`，当前仅支持文生图）。API 地址与密钥在 GUI 设置中按渠道配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。模型只能使用用户在各渠道配置目录中的模型；检测模型时会过滤聊天、Embedding 等非图片模型，但模型出现在 /models 中仍不等于其网关原生支持生图协议，遇到 Qwen、Gemini 等非 OpenAI 生图协议时应如实说明上游兼容性。可一键把满意的图片加入「画廊」。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条提示词案例，可搜索、筛选与复用。Agent 可直接调用 `generate_image` 提交文生图，也可用 `edit_image` 图生图；默认保持工具调用等待直到任务完成，完成图片显示在工具调用对应的左侧结果区域，模型收到状态和附件引用，不会额外伪造用户消息。用户也可以使用 `/edit_image <修改描述>`，命令会直接读取当前对话最近图片并调用插件图片模型，不经过对话模型的图片能力检查。若明确需要后台执行，可传 `wait_for_completion: false`，之后再用 `get_image_generation_task` 查询；不要反复轮询。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。";
+const IMAGEGEN_GUIDANCE = "本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：通过「渠道」对接 OpenAI 兼容图像生成 API（每个渠道 = 一个 API 端点 + 各自的模型目录），支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok-imagine 模型按官方 JSON image_url 协议发送，nanobanana 系列按 aspect_ratio / image_size 参数协议发送；seedream 系列统一走 /images/generations，参考图以 JSON image 数组发送；智谱 `glm-image` 使用官方 `/api/paas/v4/images/generations`，当前仅支持文生图）。API 地址与密钥在 GUI 设置中按渠道配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。模型只能使用用户在各渠道配置目录中的模型；检测模型时会过滤聊天、Embedding 等非图片模型，但模型出现在 /models 中仍不等于其网关原生支持生图协议，遇到 Qwen、Gemini 等非 OpenAI 生图协议时应如实说明上游兼容性。可一键把满意的图片加入「画廊」。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：多来源标签页（精选案例库 / 沧河案例库，后续可扩展），打包 awesome-gpt-image-2 的数百条提示词案例，可搜索、筛选、收藏（星标，宿主持久化）与复用；各来源列表独立刷新，宿主每 12 小时后台自动同步一次。Agent 可直接调用 `generate_image` 提交文生图，也可用 `edit_image` 图生图；默认保持工具调用等待直到任务完成，完成图片显示在工具调用对应的左侧结果区域，模型收到状态和附件引用，不会额外伪造用户消息。用户也可以使用 `/edit_image <修改描述>`，命令会直接读取当前对话最近图片并调用插件图片模型，不经过对话模型的图片能力检查。若明确需要后台执行，可传 `wait_for_completion: false`，之后再用 `get_image_generation_task` 查询；不要反复轮询。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问对应来源站点（vibeui.top / gpt-image2.canghe.ai）。用户提到「生图 / 绘画 / 生成图片 / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。";
 /** Append the live channel × model table so an Agent can honor user choices. */
 function guidanceFor(channels, defaultChannelId) {
 	if (channels.length === 0) return `${IMAGEGEN_GUIDANCE} 尚未配置任何渠道：请先在「设置 → 插件 → AI 生图」添加渠道并填写 API 地址与密钥。`;
@@ -3609,7 +4013,19 @@ function apply(ctx, config) {
 				pendingConversationImages,
 				runtime
 			}).map((route) => ctx.webServer.register(route));
+			const TEMPLATE_SYNC_INITIAL_DELAY_MS = 3e4;
+			const TEMPLATE_SYNC_INTERVAL_MS = 720 * 60 * 1e3;
+			let syncTimer;
+			const runSync = () => {
+				if (!resolve().enabled) return;
+				syncAllTemplates().catch(() => {});
+			};
+			const startTimer = setTimeout(runSync, TEMPLATE_SYNC_INITIAL_DELAY_MS);
+			syncTimer = setInterval(runSync, TEMPLATE_SYNC_INTERVAL_MS);
+			syncTimer.unref?.();
 			return () => {
+				clearTimeout(startTimer);
+				clearInterval(syncTimer);
 				for (const dispose of disposers) dispose();
 			};
 		}, "dsh-imagegen: routes");
@@ -3656,7 +4072,7 @@ function apply(ctx, config) {
 			text: guidanceFor(value.channels, value.defaultChannelId)
 		});
 	};
-	installSettingsSection(ctx, ImageGenSettingsNamespace, Config, config ?? {}, {
+	installSettingsSectionCompat(ctx, ImageGenSettingsNamespace, Config, config ?? {}, {
 		setSource: (source) => {
 			current = source;
 			sync();
@@ -3666,4 +4082,4 @@ function apply(ctx, config) {
 	sync();
 }
 //#endregion
-export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, ImageGenerationRuntime, appendGallery, apply, checkForUpdate, clearGallery, clearTemplateMemo, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, latestSessionImage, listGallery, listTemplates, makeRoutes, name, profileFromProcess, readGalleryImage, readTemplateImage, refreshTemplates, registerAgentImageTools, registerEditImageCommand, removeGallery, updateGalleryTags };
+export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, ImageGenerationRuntime, addTemplateFavorite, appendGallery, apply, checkForUpdate, clearGallery, clearTemplateFavoritesMemo, clearTemplateMemo, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, latestSessionImage, listGallery, listTemplateFavorites, listTemplates, makeRoutes, name, profileFromProcess, readGalleryImage, readTemplateImage, refreshTemplates, registerAgentImageTools, registerEditImageCommand, removeGallery, removeTemplateFavorite, sampleTemplates, syncAllTemplates, updateGalleryTags };