dsh-audiogen 0.3.5 → 0.4.1

package/lib/index.js

@@ -1,8 +1,10 @@
 import { SettingsConflictError, installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path, { dirname, join } from "node:path";
 import z from "schemastery";
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
+import { mkdir, readFile, rename, rmdir, unlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/protocol.ts
@@ -34,6 +36,21 @@ const HISTORY_API = {
 	clear: "/api/dsh-audiogen/history/clear",
 	audio: "/api/dsh-audiogen/history/audio"
 };
+/** Host-persisted resource-library routes. */
+const LIBRARY_API = {
+	list: "/api/dsh-audiogen/library/list",
+	save: "/api/dsh-audiogen/library/save",
+	update: "/api/dsh-audiogen/library/update",
+	remove: "/api/dsh-audiogen/library/remove",
+	audio: "/api/dsh-audiogen/library/audio"
+};
+/** All library types, for iteration and validation. */
+const LIBRARY_TYPES = [
+	"voice",
+	"music",
+	"sfx",
+	"tts"
+];
 //#endregion
 //#region src/audio-engine.ts
 /** An audio generation failure with a user-presentable message. */
@@ -79,7 +96,12 @@ function detectAudioMime(data) {
 }
 function mimeFromContentType(value) {
 	if (value === null || value === "") return void 0;
-	return value.split(";")[0].trim().toLowerCase();
+	const parts = value.split(";");
+	for (const part of parts.slice(1)) {
+		const match = /^\s*type=([^;\s]+)/i.exec(part);
+		if (match !== null) return match[1].trim().toLowerCase();
+	}
+	return parts[0].trim().toLowerCase();
 }
 function audioMime(data, contentType) {
 	return detectAudioMime(data) ?? mimeFromContentType(contentType) ?? "audio/mpeg";
@@ -591,30 +613,155 @@ async function minimax(channel, request, signal) {
 		throw new AudioGenError(`MiniMax 渠道「${channel.name}」网关未提供原生 TTS 接口：POST ${endpoint} 返回 HTTP 404（Invalid URL，网关未路由 /v1/t2a_v2）；已回退 OpenAI 兼容 ${minimaxApiBase(channel.apiUrl)}/audio/speech 仍失败：${detailText.slice(0, 300)}。请把渠道 API 地址配置为官方 https://api.minimaxi.com（配合 MiniMax 官方密钥），或确认网关已将 /v1/audio/speech 映射到 MiniMax 音色渠道。`, "audio-api-error");
 	}
 }
-async function stabilityAudio(channel, request, signal) {
-	const base = endpointBase(channel.apiUrl);
-	const endpoint = /\/generation(\?|$)/i.test(base) ? base : `${base}/generation`;
+/** Stability 内部信号：路由缺失（网关 404 Invalid URL），可切换另一协议重试。 */
+var StabilityRouteMissError = class extends Error {};
+/** 网关风格：apiUrl 形如 .../v1、.../v1/audio/speech 时优先 OpenAI 兼容 speech。 */
+function stabilityGatewayStyle(channel) {
+	const url = channel.apiUrl.trim().toLowerCase();
+	return /\/v1(\/|$|\?)/.test(url) || /\/audio\/speech(\?|$)/.test(url);
+}
+function isStabilityRouteMiss(status, detail) {
+	return status === 404 && /invalid url|invalid_request_error/i.test(detail);
+}
+/**
+* Stable Audio 官方 v2beta（multipart/form-data）。
+* - stable-audio-3        → POST {base}/stable-audio/text-to-audio    （202 异步 → GET /v2beta/audio/results/{id} 轮询）
+* - stable-audio-2 / 2.5  → POST {base}/stable-audio-2/text-to-audio  （200 同步返回音频/JSON base64）
+* - 不同模型参数不同：stable-audio-3 steps 4-8、duration ≤380；2 steps 30-100、cfg_scale 默认 7；
+*   2.5 steps 4-8、cfg_scale 默认 1；均支持 seed、output_format(hp3|wav)。
+*/
+async function stabilityNativeAudio(channel, request, signal) {
+	const rawBase = endpointBase(channel.apiUrl);
+	const model = (request.upstream ?? request.model) || "stable-audio-2.5";
+	const isV3 = /^stable-audio-3/i.test(model);
+	const isV2 = /^stable-audio-2(\.[05])?$/i.test(model) || /^stable-audio-2-/i.test(model);
+	const group = isV2 ? "stable-audio-2" : "stable-audio";
+	const base = /\/v2beta\/audio$/i.test(rawBase) ? rawBase : /\/v2beta$/i.test(rawBase) ? `${rawBase}/audio` : `${rawBase}/v2beta/audio`;
+	const endpoint = `${base}/${group}/text-to-audio`;
+	const form = new FormData();
+	form.set("prompt", request.prompt);
+	form.set("model", model);
+	if (request.duration !== void 0 && Number.isFinite(request.duration)) {
+		const maxDuration = isV3 ? 380 : 190;
+		form.set("duration", String(Math.min(maxDuration, Math.max(1, request.duration))));
+	}
+	if (request.seed !== void 0 && Number.isFinite(request.seed)) form.set("seed", String(Math.floor(Math.min(4294967294, Math.max(0, request.seed)))));
+	const format = request.format === "wav" ? "wav" : "mp3";
+	form.set("output_format", format);
+	if (request.steps !== void 0 && Number.isInteger(request.steps)) {
+		const minSteps = isV2 && !/2\.5/i.test(model) ? 30 : 4;
+		const maxSteps = isV2 && !/2\.5/i.test(model) ? 100 : 8;
+		form.set("steps", String(Math.min(maxSteps, Math.max(minSteps, request.steps))));
+	}
+	if (request.cfgScale !== void 0 && Number.isFinite(request.cfgScale)) form.set("cfg_scale", String(Math.min(25, Math.max(1, request.cfgScale))));
+	const response = await fetchWithTimeout(endpoint, {
+		method: "POST",
+		redirect: "error",
+		headers: {
+			authorization: `Bearer ${channel.apiKey.trim()}`,
+			accept: "application/json"
+		},
+		body: form,
+		signal
+	}, isV3 ? 6e4 : UPSTREAM_TIMEOUT_MS);
+	if (!response.ok) {
+		const detail = await response.text().catch(() => "");
+		if (isStabilityRouteMiss(response.status, detail)) throw new StabilityRouteMissError();
+		throw new AudioGenError(`Stable Audio API error (HTTP ${response.status})${detail === "" ? "" : `: ${detail.slice(0, 300)}`}`, "audio-api-error");
+	}
+	if (response.status === 202) {
+		const payload = await response.json().catch(() => ({}));
+		if (payload.id === void 0 || payload.id === "") throw new AudioGenError("Stable Audio accepted the job but returned no result id", "audio-empty-result");
+		const resultUrl = `${base.replace(/\/v2beta\/audio$/i, "")}/v2beta/audio/results/${encodeURIComponent(payload.id)}`;
+		const deadline = Date.now() + UPSTREAM_TIMEOUT_MS;
+		while (Date.now() < deadline) {
+			if (signal?.aborted === true) throw new AudioGenError("Stable Audio generation was aborted", "audio-aborted");
+			const polled = await fetchWithTimeout(resultUrl, {
+				method: "GET",
+				redirect: "error",
+				headers: {
+					authorization: `Bearer ${channel.apiKey.trim()}`,
+					accept: "application/json"
+				},
+				signal
+			}, 6e4);
+			if (polled.ok) return normalizeAudioResponse(polled, {
+				apiKey: channel.apiKey,
+				fallbackMime: "audio/mpeg"
+			});
+			if (polled.status === 404 || polled.status === 202) {
+				await new Promise((resolve) => setTimeout(resolve, 5e3));
+				continue;
+			}
+			const detail = await polled.text().catch(() => "");
+			throw new AudioGenError(`Stable Audio result API error (HTTP ${polled.status})${detail === "" ? "" : `: ${detail.slice(0, 300)}`}`, "audio-api-error");
+		}
+		throw new AudioGenError("Stable Audio generation timed out waiting for the result", "audio-timeout");
+	}
+	return normalizeAudioResponse(response, {
+		apiKey: channel.apiKey,
+		fallbackMime: "audio/mpeg"
+	});
+}
+/**
+* Stable Audio 经 OpenAI 兼容网关（如 New API 的 /v1/audio/speech）：
+* 模型名映射到 Stable 上游，JSON 体为 {model, input, output_format, duration,
+* seed, steps, cfg_scale} —— 与官方 v2beta 字段一一对应，网关负责转发。
+*/
+async function stabilityGatewayAudio(channel, request, signal) {
+	const rawBase = endpointBase(channel.apiUrl);
+	const model = (request.upstream ?? request.model) || "stable-audio-2.5";
+	const isV3 = /^stable-audio-3/i.test(model);
+	const isV2 = /^stable-audio-2(\.[05])?$/i.test(model) || /^stable-audio-2-/i.test(model);
+	const endpoint = /\/audio\/speech(\?|$)/i.test(rawBase) ? rawBase : `${rawBase}/audio/speech`;
+	const format = request.format === "wav" ? "wav" : "mp3";
 	const body = {
-		model: (request.upstream ?? request.model) || "stable-audio-2.0",
-		prompt: request.prompt,
-		...request.duration !== void 0 ? { duration: request.duration } : {},
-		...request.format !== void 0 ? { output_format: request.format } : {}
+		model,
+		input: request.prompt,
+		output_format: format,
+		...request.duration !== void 0 && Number.isFinite(request.duration) ? { duration: Math.min(isV3 ? 380 : 190, Math.max(1, request.duration)) } : {},
+		...request.seed !== void 0 && Number.isFinite(request.seed) ? { seed: Math.floor(Math.min(4294967294, Math.max(0, request.seed))) } : {},
+		...request.steps !== void 0 && Number.isInteger(request.steps) ? { steps: Math.min(isV2 && !/2\.5/i.test(model) ? 100 : 8, Math.max(isV2 && !/2\.5/i.test(model) ? 30 : 4, request.steps)) } : {},
+		...request.cfgScale !== void 0 && Number.isFinite(request.cfgScale) ? { cfg_scale: Math.min(25, Math.max(1, request.cfgScale)) } : {}
 	};
-	return normalizeAudioResponse(await fetchWithTimeout(endpoint, {
+	const response = await fetchWithTimeout(endpoint, {
 		method: "POST",
-		redirect: "error",
+		redirect: "follow",
 		headers: {
 			authorization: `Bearer ${channel.apiKey.trim()}`,
-			"content-type": "application/json",
-			accept: "application/json, audio/mpeg, audio/wav"
+			accept: "audio/*",
+			"content-type": "application/json"
 		},
 		body: JSON.stringify(body),
 		signal
-	}, UPSTREAM_TIMEOUT_MS), {
+	}, UPSTREAM_TIMEOUT_MS);
+	if (!response.ok) {
+		const detail = await response.text().catch(() => "");
+		if (isStabilityRouteMiss(response.status, detail)) throw new StabilityRouteMissError();
+		throw new AudioGenError(`Stable Audio gateway API error (HTTP ${response.status})${detail === "" ? "" : `: ${detail.slice(0, 300)}`}`, "audio-api-error");
+	}
+	return normalizeAudioResponse(response, {
 		apiKey: channel.apiKey,
 		fallbackMime: "audio/mpeg"
 	});
 }
+/**
+* 稳定性入口：优先官方 v2beta（api.stability.ai / v2beta 形态），
+* 网关形态（apiUrl 以 /v1 结尾或已含 /audio/speech）优先 OpenAI 兼容；
+* 一方返回 404 Invalid URL（未路由）时自动换另一方重试。
+*/
+async function stabilityAudio(channel, request, signal) {
+	const styles = stabilityGatewayStyle(channel) ? ["gateway", "native"] : ["native", "gateway"];
+	let lastError;
+	for (const style of styles) try {
+		if (style === "gateway") return await stabilityGatewayAudio(channel, request, signal);
+		return await stabilityNativeAudio(channel, request, signal);
+	} catch (error) {
+		if (!(error instanceof StabilityRouteMissError)) throw error;
+		lastError = error;
+	}
+	throw lastError ?? new AudioGenError("Stable Audio 渠道未配置或不可达", "audio-api-error");
+}
 async function genericAudio(channel, request, signal) {
 	const base = endpointBase(channel.apiUrl);
 	if (request.mode === "tts" && !/\/generate(\?|$)/i.test(base)) return openAITTS(channel, request, signal);
@@ -653,7 +800,7 @@ async function generateAudio(channel, request, signal) {
 	if (request.mode === "voice_design" && !isMiniMax$1(channel) && !isElevenLabs$1(channel)) throw new AudioGenError("音色设计当前仅支持 MiniMax（/v1/voice_design）与 ElevenLabs（/v1/text-to-voice/design）渠道", "voice-design-unsupported");
 	if (isElevenLabs$1(channel)) return elevenLabs(channel, request, signal);
 	if (isMiniMax$1(channel)) return minimax(channel, request, signal);
-	if (isStability$1(channel)) return stabilityAudio(channel, request, signal);
+	if (isStability$1(channel) || /^stable-audio-/i.test(((request.upstream ?? request.model) || "").trim())) return stabilityAudio(channel, request, signal);
 	if (isOpenAICompatible(channel, request.mode)) return openAITTS(channel, request, signal);
 	return genericAudio(channel, request, signal);
 }
@@ -788,16 +935,24 @@ const AUDIO_PRESETS = [
 		name: "Stability AI（stable-audio）",
 		apiUrl: "https://api.stability.ai/v2beta/audio",
 		site: "https://stability.ai/stable-audio",
-		hint: "Stability AI 音乐 / 音效生成（stable-audio 系列）",
-		models: [{
-			alias: "stable-audio-2.0",
-			id: "stable-audio-2.0",
-			category: "music"
-		}, {
-			alias: "stable-audio-1.0",
-			id: "stable-audio-1.0",
-			category: "music"
-		}]
+		hint: "Stability AI 文本到音频（TTS 描述 / 音乐 / 音效，stable-audio 系列；stable-audio-3 为异步任务）",
+		models: [
+			{
+				alias: "stable-audio-3",
+				id: "stable-audio-3",
+				category: "music"
+			},
+			{
+				alias: "stable-audio-2.5",
+				id: "stable-audio-2.5",
+				category: "music"
+			},
+			{
+				alias: "stable-audio-2",
+				id: "stable-audio-2",
+				category: "music"
+			}
+		]
 	}
 ];
 /** Look up one built-in provider by id. */
@@ -995,12 +1150,16 @@ function dedupe(models) {
 /**
 * Host-side persistence for generated audio and generation history.
 * Files live under ~/.dsh/dsh-audiogen/audio/; history is one JSON document.
+* The resource library lives under ~/.dsh/dsh-audiogen/library/ with one
+* index JSON plus files organized by type (voice/music/sfx/tts) and category.
 */
 function dshHome() {
 	return process.env.DSH_HOME ?? path.join(os.homedir(), ".dsh");
 }
 const AUDIO_DATA_DIR = path.join(dshHome(), "dsh-audiogen", "audio");
 const HISTORY_FILE = path.join(dshHome(), "dsh-audiogen", "history.json");
+const LIBRARY_DATA_DIR = path.join(dshHome(), "dsh-audiogen", "library");
+const LIBRARY_INDEX_FILE = path.join(LIBRARY_DATA_DIR, "index.json");
 async function ensureDir() {
 	await mkdir(AUDIO_DATA_DIR, { recursive: true });
 }
@@ -1083,7 +1242,8 @@ async function appendHistory(entry) {
 			...audio.voiceId === void 0 ? {} : { voiceId: audio.voiceId }
 		})),
 		...entry.channelId === void 0 ? {} : { channelId: entry.channelId },
-		...entry.channel === void 0 ? {} : { channel: entry.channel }
+		...entry.channel === void 0 ? {} : { channel: entry.channel },
+		...entry.params === void 0 ? {} : { params: entry.params }
 	}, ...list].slice(0, 50);
 	await writeHistory(next);
 	return next;
@@ -1100,6 +1260,205 @@ async function clearHistory() {
 	await writeHistory([]);
 	return [];
 }
+/** Library type dir names (whitelisted on the audio route too). */
+const LIBRARY_TYPE_DIRS = {
+	voice: "voice",
+	music: "music",
+	sfx: "sfx",
+	tts: "tts"
+};
+/** Sanitize one path segment (cid or voice key). Falls back to 'default'. */
+function sanitizeSegment(value) {
+	const cleaned = value.replace(/[^a-zA-Z0-9\u4e00-\u9fa5._-]+/g, "_").replace(/^[._-]+|[._-]+$/g, "").slice(0, 60);
+	return cleaned === "" ? "default" : cleaned;
+}
+/** Infer the category for a save when the client did not provide one. */
+function defaultLibraryCategory(type, meta) {
+	if (type === "voice") {
+		const probe = `${meta.voiceId ?? ""} ${meta.voice ?? ""}`.toLowerCase();
+		if (/female|女/.test(probe)) return "female";
+		if (/male|男/.test(probe)) return "male";
+		return "custom";
+	}
+	if (type === "tts") return sanitizeSegment(meta.voice ?? meta.voiceId ?? "default");
+}
+/** Default resource name from the prompt. */
+function defaultLibraryName(prompt) {
+	const flat = prompt.replace(/\s+/g, " ").trim();
+	return flat === "" ? "未命名音频" : flat.length > 40 ? `${flat.slice(0, 40)}…` : flat;
+}
+async function readLibraryIndex() {
+	try {
+		const text = await readFile(LIBRARY_INDEX_FILE, "utf8");
+		const parsed = JSON.parse(text);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter(isLibraryEntry);
+	} catch {
+		return [];
+	}
+}
+function isLibraryEntry(value) {
+	if (value === null || typeof value !== "object") return false;
+	const raw = value;
+	return typeof raw.id === "string" && typeof raw.name === "string" && (raw.type === "voice" || raw.type === "music" || raw.type === "sfx" || raw.type === "tts") && Array.isArray(raw.files) && typeof raw.createdAt === "number" && typeof raw.provenance === "object";
+}
+async function writeLibraryIndex(entries) {
+	await mkdir(LIBRARY_DATA_DIR, { recursive: true });
+	await writeFile(LIBRARY_INDEX_FILE, JSON.stringify(entries, null, 2));
+}
+/** Same-origin URL for a library-relative file path. */
+function libraryUrlOf(rel) {
+	return `${LIBRARY_API.audio}/${rel.split("/").map((segment) => encodeURIComponent(segment)).join("/")}`;
+}
+/** Merge-library-entry: copy one audio/ file into library/<type>/<category>/. */
+async function copyIntoLibrary(input, typeDir, category) {
+	const stored = await readAudioFile(input.file);
+	if (stored === void 0) throw new Error(`音频文件不存在：${input.file}（请重新生成后再入库）`);
+	const ext = path.extname(input.file).replace(".", "") || (stored.mime.split("/")[1]?.replace("mpeg", "mp3") ?? "bin");
+	const rel = `${typeDir}/${category}/${input.id}.${ext}`;
+	const target = path.join(LIBRARY_DATA_DIR, ...rel.split("/"));
+	await mkdir(path.dirname(target), { recursive: true });
+	await writeFile(target, stored.data);
+	return {
+		url: libraryUrlOf(rel),
+		rel,
+		mime: stored.mime,
+		bytes: stored.bytes,
+		...input.duration === void 0 ? {} : { duration: input.duration },
+		...input.voiceId === void 0 ? {} : { voiceId: input.voiceId }
+	};
+}
+/**
+* Save one curated library entry: copies the referenced audio files into
+* library/<type>/<category>/ (audio/ files stay untouched) and appends the
+* entry to the index.
+*/
+async function saveToLibrary(input) {
+	if (input.audioFiles.length === 0) throw new Error("没有可入库的音频文件");
+	const typeDir = LIBRARY_TYPE_DIRS[input.type];
+	const category = input.category !== void 0 && input.category.trim() !== "" ? sanitizeSegment(input.category.trim()) : defaultLibraryCategory(input.type, {
+		voice: input.provenance.voice,
+		voiceId: input.provenance.voiceId ?? input.audioFiles.find((file) => file.voiceId !== void 0)?.voiceId
+	}) ?? "default";
+	const files = await Promise.all(input.audioFiles.map((file) => copyIntoLibrary(file, typeDir, category)));
+	const rawName = (input.name ?? "").trim();
+	const entry = {
+		id: randomUUID(),
+		createdAt: Date.now(),
+		type: input.type,
+		category: category === "default" && input.type !== "voice" && input.type !== "tts" ? void 0 : category,
+		name: rawName === "" ? defaultLibraryName(input.provenance.prompt) : rawName,
+		tags: Array.isArray(input.tags) ? [...new Set(input.tags.map((tag) => tag.trim()).filter((tag) => tag !== ""))].slice(0, 20) : [],
+		...input.note !== void 0 && input.note.trim() !== "" ? { note: input.note.trim() } : {},
+		files,
+		provenance: input.provenance
+	};
+	const entries = await readLibraryIndex();
+	entries.unshift(entry);
+	await writeLibraryIndex(entries);
+	return entry;
+}
+/** Read library entries (newest first). */
+async function listLibrary() {
+	return [...await readLibraryIndex()].sort((a, b) => b.createdAt - a.createdAt);
+}
+/** Move one library-relative file to a new rel path (same volume rename, else copy). */
+async function moveLibraryFile(fromRel, toRel) {
+	const from = path.join(LIBRARY_DATA_DIR, ...fromRel.split("/"));
+	const to = path.join(LIBRARY_DATA_DIR, ...toRel.split("/"));
+	await mkdir(path.dirname(to), { recursive: true });
+	try {
+		await rename(from, to);
+	} catch {
+		await writeFile(to, await readFile(from));
+		await unlink(from);
+	}
+}
+/** Patch name/tags/note/type/category; moving type/category relocates files. */
+async function updateLibraryEntry(id, patch) {
+	const entries = await readLibraryIndex();
+	const index = entries.findIndex((entry) => entry.id === id);
+	if (index < 0) return void 0;
+	const entry = {
+		...entries[index],
+		files: [...entries[index].files]
+	};
+	if (patch.type !== void 0 && LIBRARY_TYPES_VALID.includes(patch.type)) entry.type = patch.type;
+	if (patch.name !== void 0) entry.name = patch.name.trim() === "" ? defaultLibraryName(entry.provenance.prompt) : patch.name.trim();
+	if (patch.tags !== void 0) entry.tags = [...new Set(patch.tags.map((tag) => tag.trim()).filter((tag) => tag !== ""))].slice(0, 20);
+	if (patch.note !== void 0) entry.note = patch.note.trim() === "" ? void 0 : patch.note.trim();
+	if (patch.category !== void 0 && patch.category.trim() !== "") {
+		const next = sanitizeSegment(patch.category.trim());
+		if (entry.type === "voice" || entry.type === "tts") entry.category = next;
+	}
+	const oldCat = entries[index].category ?? "default";
+	const newCat = entry.category ?? "default";
+	if (entries[index].type !== entry.type || oldCat !== newCat) {
+		const moved = [];
+		for (const file of entry.files) {
+			const fileName = file.rel.split("/").pop() ?? "";
+			const fromRel = `${LIBRARY_TYPE_DIRS[entries[index].type]}/${oldCat}/${fileName}`;
+			const toRel = `${LIBRARY_TYPE_DIRS[entry.type]}/${newCat}/${fileName}`;
+			if (fromRel !== toRel) await moveLibraryFile(fromRel, toRel);
+			moved.push({
+				...file,
+				rel: toRel,
+				url: libraryUrlOf(toRel)
+			});
+		}
+		entry.files = moved;
+	}
+	entries[index] = entry;
+	await writeLibraryIndex(entries);
+	return entry;
+}
+/** Remove entries and their audio files; best-effort prune empty dirs. */
+async function removeLibraryEntries(ids) {
+	const entries = await readLibraryIndex();
+	const doomed = new Set(ids);
+	const kept = entries.filter((entry) => !doomed.has(entry.id));
+	for (const entry of entries) {
+		if (!doomed.has(entry.id)) continue;
+		for (const file of entry.files) try {
+			await unlink(path.join(LIBRARY_DATA_DIR, ...file.rel.split("/")));
+		} catch {}
+	}
+	for (const entry of entries) {
+		if (!doomed.has(entry.id)) continue;
+		try {
+			await rmdir(path.dirname(path.join(LIBRARY_DATA_DIR, ...entry.files[0].rel.split("/"))), { recursive: false });
+		} catch {}
+	}
+	await writeLibraryIndex(kept);
+	return kept;
+}
+/** Read one library file by its rel path (whitelisted, traversal-safe). */
+async function readLibraryFile(rel) {
+	const segments = rel.split("/").filter((segment) => segment !== "");
+	if (segments.length < 2 || segments.length > 3) return void 0;
+	const [typeDir, category, fileName] = segments;
+	if (typeDir === void 0 || !Object.values(LIBRARY_TYPE_DIRS).includes(typeDir)) return void 0;
+	if (category === void 0 || sanitizeSegment(category) !== category || category.length > 60) return void 0;
+	if (fileName === void 0 || !/^[0-9a-f-]{36}\.[a-z0-9]{2,5}$/i.test(fileName)) return void 0;
+	const full = path.join(LIBRARY_DATA_DIR, typeDir, category, fileName);
+	if (!full.startsWith(path.join(LIBRARY_DATA_DIR, typeDir, category) + path.sep)) return void 0;
+	try {
+		const data = await readFile(full);
+		return {
+			data,
+			mime: mimeFromFile(fileName),
+			bytes: data.byteLength
+		};
+	} catch {
+		return;
+	}
+}
+const LIBRARY_TYPES_VALID = [
+	"voice",
+	"music",
+	"sfx",
+	"tts"
+];
 //#endregion
 //#region src/routes.ts
 const MAX_JSON_BODY_BYTES = 16 * 1024 * 1024;
@@ -1182,6 +1541,9 @@ function parseGenerateRequest(body) {
 		...typeof body.isInstrumental === "boolean" ? { isInstrumental: body.isInstrumental } : {},
 		...typeof body.loop === "boolean" ? { loop: body.loop } : {},
 		...num(body.promptInfluence) !== void 0 ? { promptInfluence: num(body.promptInfluence) } : {},
+		...num(body.seed) !== void 0 ? { seed: num(body.seed) } : {},
+		...num(body.steps) !== void 0 ? { steps: num(body.steps) } : {},
+		...num(body.cfgScale) !== void 0 ? { cfgScale: num(body.cfgScale) } : {},
 		...typeof body.format === "string" && body.format.trim() !== "" ? { format: body.format.trim() } : {},
 		...typeof body.channelId === "string" && body.channelId !== "" ? { channelId: body.channelId } : {},
 		...str(body.emotion) !== void 0 ? { emotion: str(body.emotion) } : {},
@@ -1198,7 +1560,8 @@ function parseGenerateRequest(body) {
 		...flag(body.aigcWatermark) !== void 0 ? { aigcWatermark: flag(body.aigcWatermark) } : {},
 		...str(body.languageBoost) !== void 0 ? { languageBoost: str(body.languageBoost) } : {},
 		...voiceModify !== void 0 ? { voiceModify } : {},
-		...timbreWeights !== void 0 && timbreWeights.length > 0 ? { timbreWeights } : {}
+		...timbreWeights !== void 0 && timbreWeights.length > 0 ? { timbreWeights } : {},
+		...flag(body.saveToLibrary) !== void 0 ? { saveToLibrary: flag(body.saveToLibrary) } : {}
 	};
 }
 function toView(descriptor) {
@@ -1295,6 +1658,60 @@ function resolveChannelRequest(request, view) {
 		}
 	};
 }
+/** Build the library type from a generation mode (voice_design → voice). */
+function libraryTypeOf$1(mode) {
+	if (mode === "voice_design") return "voice";
+	return mode;
+}
+/** Provenance snapshot straight from a resolved generate request. */
+function provenanceOf(request, apiUrl) {
+	return {
+		mode: request.mode,
+		prompt: request.prompt,
+		...request.channel === void 0 ? {} : { channel: request.channel },
+		...request.channelId === void 0 ? {} : { channelId: request.channelId },
+		...apiUrl === "" ? {} : { apiUrl },
+		...request.model === void 0 || request.model === "" ? {} : { model: request.model },
+		...request.upstream === void 0 || request.upstream === "" ? {} : { upstream: request.upstream },
+		...request.voice === void 0 ? {} : { voice: request.voice },
+		params: { ...request }
+	};
+}
+const strOf = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+const strListOf = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim()) : void 0;
+const parseModeOf = (value) => value === "music" ? "music" : value === "sfx" ? "sfx" : value === "voice_design" ? "voice_design" : "tts";
+const parseLibraryTypeOf = (value) => LIBRARY_TYPES.includes(value) ? value : void 0;
+/** File name (audio/ id.ext) from a same-origin audio url. */
+function historyFileIdOf(url) {
+	try {
+		return decodeURIComponent(new URL(url, "http://localhost").pathname.split("/").pop() ?? "");
+	} catch {
+		return "";
+	}
+}
+/**
+* Fill missing provenance fields from host-persisted history (which carries
+* the resolved request snapshot) and the channel catalog. Client-supplied
+* values win when present.
+*/
+async function mergeLibraryProvenance(given, files, channels) {
+	const wanted = new Set(files.map((file) => file.file));
+	const entry = (await listHistory()).find((candidate) => candidate.audio.some((audio) => wanted.has(historyFileIdOf(audio.url))));
+	const params = entry?.params !== void 0 && typeof entry.params === "object" ? entry.params : void 0;
+	const channel = channels.find((candidate) => candidate.id === (entry?.channelId ?? ""));
+	return {
+		mode: entry?.mode ?? given.mode,
+		prompt: given.prompt !== "" ? given.prompt : entry?.prompt ?? "",
+		...given.channel !== void 0 || entry?.channel !== void 0 ? { channel: given.channel ?? entry?.channel } : {},
+		...given.channelId !== void 0 || entry?.channelId !== void 0 ? { channelId: given.channelId ?? entry?.channelId } : {},
+		...(given.apiUrl ?? channel?.apiUrl ?? "") === "" ? {} : { apiUrl: given.apiUrl ?? channel?.apiUrl },
+		...given.model !== void 0 || entry?.model !== void 0 ? { model: given.model ?? entry?.model } : {},
+		...(given.upstream ?? (typeof params?.upstream === "string" ? params.upstream : void 0)) !== void 0 ? { upstream: given.upstream ?? (typeof params?.upstream === "string" ? params.upstream : void 0) } : {},
+		...given.voice !== void 0 || entry?.voice !== void 0 ? { voice: given.voice ?? entry?.voice } : {},
+		...given.voiceId !== void 0 || entry?.voiceId !== void 0 ? { voiceId: given.voiceId ?? entry?.voiceId } : {},
+		...given.params !== void 0 || params !== void 0 ? { params: given.params ?? params } : {}
+	};
+}
 /** Build every /api/dsh-audiogen route. */
 function makeRoutes(deps) {
 	const guard = (req, res, method) => {
@@ -1455,6 +1872,7 @@ function makeRoutes(deps) {
 						const saved = await saveAudioFile(output.data, output.mime, `generated-${index + 1}`);
 						generated.push({
 							id: saved.id,
+							file: saved.file,
 							b64: Buffer.from(output.data).toString("base64"),
 							mime: saved.mime,
 							bytes: saved.bytes,
@@ -1462,6 +1880,7 @@ function makeRoutes(deps) {
 							...output.voiceId === void 0 ? {} : { voiceId: output.voiceId }
 						});
 					}
+					const paramsSnapshot = { ...request };
 					let history;
 					try {
 						history = await appendHistory({
@@ -1476,7 +1895,8 @@ function makeRoutes(deps) {
 							...request.format === void 0 ? {} : { format: request.format },
 							audio: generated,
 							...request.channelId === void 0 ? {} : { channelId: request.channelId },
-							...request.channel === void 0 ? {} : { channel: request.channel }
+							...request.channel === void 0 ? {} : { channel: request.channel },
+							params: paramsSnapshot
 						});
 					} catch (error) {
 						writeJson(res, 200, {
@@ -1486,10 +1906,30 @@ function makeRoutes(deps) {
 						});
 						return;
 					}
+					const wantSave = request.saveToLibrary === true || deps.autoSave() && request.saveToLibrary !== false;
+					let resources;
+					if (wantSave) try {
+						const entry = await saveToLibrary({
+							audioFiles: generated.map((audio) => ({
+								id: audio.id,
+								file: audio.file,
+								mime: audio.mime,
+								...audio.voiceId === void 0 ? {} : { voiceId: audio.voiceId }
+							})),
+							type: libraryTypeOf$1(request.mode),
+							provenance: provenanceOf(request, channel.apiUrl)
+						});
+						resources = [{
+							id: entry.id,
+							name: entry.name,
+							type: entry.type
+						}];
+					} catch {}
 					writeJson(res, 200, {
 						ok: true,
 						outputs: generated,
-						history
+						history,
+						...resources === void 0 ? {} : { resources }
 					});
 				} catch (error) {
 					writeJson(res, 200, {
@@ -1530,6 +1970,185 @@ function makeRoutes(deps) {
 				res.end(stored.data);
 			}
 		},
+		{
+			kind: "exact",
+			path: LIBRARY_API.list,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				writeJson(res, 200, {
+					ok: true,
+					entries: await listLibrary()
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: LIBRARY_API.save,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const audioFiles = Array.isArray(body?.audioFiles) ? body.audioFiles.filter((item) => typeof item === "object" && item !== null).map((item) => ({
+					id: strOf(item.id) ?? "",
+					file: strOf(item.file) ?? "",
+					mime: strOf(item.mime) ?? "audio/mpeg",
+					...strOf(item.voiceId) !== void 0 ? { voiceId: strOf(item.voiceId) } : {},
+					...typeof item.duration === "number" && Number.isFinite(item.duration) ? { duration: item.duration } : {}
+				})).filter((item) => item.id !== "" && item.file !== "") : [];
+				if (audioFiles.length === 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "没有可入库的音频文件"
+					});
+					return;
+				}
+				const type = parseLibraryTypeOf(body?.type);
+				if (type === void 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "资源类型无效（voice/music/sfx/tts）"
+					});
+					return;
+				}
+				const rawProvenance = typeof body?.provenance === "object" && body.provenance !== null ? body.provenance : {};
+				const provenance = await mergeLibraryProvenance({
+					mode: parseModeOf(rawProvenance.mode),
+					prompt: typeof rawProvenance.prompt === "string" ? rawProvenance.prompt.trim() : "",
+					...strOf(rawProvenance.channel) !== void 0 ? { channel: strOf(rawProvenance.channel) } : {},
+					...strOf(rawProvenance.channelId) !== void 0 ? { channelId: strOf(rawProvenance.channelId) } : {},
+					...strOf(rawProvenance.apiUrl) !== void 0 ? { apiUrl: strOf(rawProvenance.apiUrl) } : {},
+					...strOf(rawProvenance.model) !== void 0 ? { model: strOf(rawProvenance.model) } : {},
+					...strOf(rawProvenance.upstream) !== void 0 ? { upstream: strOf(rawProvenance.upstream) } : {},
+					...strOf(rawProvenance.voice) !== void 0 ? { voice: strOf(rawProvenance.voice) } : {},
+					...strOf(rawProvenance.voiceId) !== void 0 ? { voiceId: strOf(rawProvenance.voiceId) } : {},
+					...typeof rawProvenance.params === "object" && rawProvenance.params !== null ? { params: rawProvenance.params } : {}
+				}, audioFiles, deps.resolveChannels().channels);
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						entry: await saveToLibrary({
+							audioFiles,
+							type,
+							...strOf(body?.category) !== void 0 ? { category: strOf(body?.category) } : {},
+							...strOf(body?.name) !== void 0 ? { name: strOf(body?.name) } : {},
+							...strListOf(body?.tags) !== void 0 ? { tags: strListOf(body?.tags) } : {},
+							...strOf(body?.note) !== void 0 ? { note: strOf(body?.note) } : {},
+							provenance
+						})
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "library-save-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: LIBRARY_API.update,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const id = strOf(body?.id);
+				if (id === void 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "缺少资源 id"
+					});
+					return;
+				}
+				try {
+					const entry = await updateLibraryEntry(id, {
+						...strOf(body?.name) !== void 0 ? { name: strOf(body?.name) } : {},
+						...strListOf(body?.tags) !== void 0 ? { tags: strListOf(body?.tags) } : {},
+						...typeof body?.note === "string" ? { note: body.note } : {},
+						...strOf(body?.category) !== void 0 ? { category: strOf(body?.category) } : {},
+						...parseLibraryTypeOf(body?.type) !== void 0 ? { type: parseLibraryTypeOf(body?.type) } : {}
+					});
+					if (entry === void 0) {
+						writeJson(res, 200, {
+							ok: false,
+							code: "not-found",
+							message: "资源不存在"
+						});
+						return;
+					}
+					writeJson(res, 200, {
+						ok: true,
+						entry
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "library-update-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: LIBRARY_API.remove,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const ids = strListOf(body?.ids) ?? [];
+				if (ids.length === 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "缺少资源 id"
+					});
+					return;
+				}
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						entries: await removeLibraryEntries(ids)
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "library-remove-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "prefix",
+			path: LIBRARY_API.audio,
+			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 rel = audioFileFrom(req.url, LIBRARY_API.audio);
+				if (rel === void 0) {
+					writeJson(res, 400, { error: "invalid library audio" });
+					return;
+				}
+				const stored = await readLibraryFile(rel);
+				if (stored === void 0) {
+					writeJson(res, 404, { error: "library audio not found" });
+					return;
+				}
+				res.writeHead(200, {
+					"content-type": stored.mime,
+					"content-length": stored.bytes,
+					"cache-control": "private, max-age=3600"
+				});
+				res.end(stored.data);
+			}
+		},
 		{
 			kind: "exact",
 			path: HISTORY_API.list,
@@ -1598,6 +2217,29 @@ function makeRoutes(deps) {
 }
 //#endregion
 //#region src/agent-audio-tools.ts
+const audioRefSchema = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		id: {
+			type: "string",
+			required: true
+		},
+		url: {
+			type: "string",
+			required: true
+		},
+		mime: {
+			type: "string",
+			required: true
+		},
+		bytes: {
+			type: "integer",
+			required: true
+		},
+		voiceId: { type: "string" }
+	}
+};
 const resultSchema = {
 	type: "object",
 	additionalProperties: false,
@@ -1627,27 +2269,32 @@ const resultSchema = {
 		audio: {
 			type: "array",
 			required: true,
+			items: audioRefSchema
+		},
+		resources: {
+			type: "array",
+			items: { type: "string" }
+		},
+		groups: {
+			type: "array",
 			items: {
 				type: "object",
 				additionalProperties: false,
 				properties: {
-					id: {
-						type: "string",
-						required: true
-					},
-					url: {
+					model: {
 						type: "string",
 						required: true
 					},
-					mime: {
-						type: "string",
-						required: true
+					audio: {
+						type: "array",
+						required: true,
+						items: audioRefSchema
 					},
-					bytes: {
-						type: "integer",
-						required: true
+					resources: {
+						type: "array",
+						items: { type: "string" }
 					},
-					voiceId: { type: "string" }
+					error: { type: "string" }
 				}
 			}
 		},
@@ -1681,9 +2328,15 @@ function ensureConfigured(config) {
 	if (!config.allowAgentAudioGeneration) throw new AudioGenError("Agent audio generation is disabled in Settings > Plugins > AI Audio.", "agent-generation-disabled");
 	if (!config.channels.some((channel) => channel.apiUrl.trim() !== "" && channel.apiKey.trim() !== "")) throw new AudioGenError("Audio API credentials are not configured. Open Settings > Plugins > AI Audio, add a channel and fill its API URL and API key.", "audio-api-not-configured");
 }
+/** Library type from the generation mode, with an explicit override. */
+function libraryTypeOf(mode, override) {
+	if (override === "voice" || override === "music" || override === "sfx" || override === "tts") return override;
+	if (mode === "voice_design") return "voice";
+	return mode;
+}
 /** Register the Agent audio tool. */
 function registerAgentAudioTools(ctx, resolve) {
-	return ctx.tools.register(defineTool({
+	const disposer = ctx.tools.register(defineTool({
 		name: "generate_audio",
 		description: "Generate audio with the configured audio provider. Supports text-to-speech, music generation, sound effects and voice design (MiniMax /v1/voice_design, ElevenLabs /v1/text-to-voice/design). The tool call waits for the upstream result and returns same-origin audio URLs; pass those URLs to the user for playback or download. If multiple models are configured, first ask the user which one to use or pass model explicitly.",
 		parameters: {
@@ -1706,6 +2359,16 @@ function registerAgentAudioTools(ctx, resolve) {
 				type: "string",
 				description: "One of the configured audio models/voices. Defaults to the first configured model."
 			},
+			models: {
+				type: "array",
+				items: { type: "string" },
+				description: "Optional: several configured model aliases to generate the SAME prompt with each one, sequentially, for comparison (e.g. [\"speech-2.8-hd\",\"speech-2.6-hd\"]). Cannot be combined with model; when present, models wins."
+			},
+			model_params: {
+				type: "object",
+				additionalProperties: true,
+				description: "Optional per-model parameter overrides used with \"models\" (automatic by default = all models share the global params). Keys are model aliases; values are partial param objects using the same param names (format, duration, voice, speed, emotion, vol, pitch, sample_rate, bitrate, lyrics, is_instrumental, loop, prompt_influence, seed, steps, cfg_scale, subtitle_enable, aigc_watermark, language_boost, pronunciation_tone, voice_modify, timbre_weights). Unset fields fall back to the global values."
+			},
 			voice: {
 				type: "string",
 				description: "Optional voice id/name for TTS providers. Required for MiniMax TTS (e.g. male-qn-qingse, female-shaonv); fetch the account voices in Settings > Plugins > AI Audio."
@@ -1738,6 +2401,18 @@ function registerAgentAudioTools(ctx, resolve) {
 				type: "number",
 				description: "Sound effect prompt influence 0-1 (ElevenLabs prompt_influence, default 0.3): higher follows the prompt more closely, lower is more variable."
 			},
+			seed: {
+				type: "integer",
+				description: "Stable Audio random seed 0-4294967294 (default 0 = random); same seed yields reproducible audio."
+			},
+			steps: {
+				type: "integer",
+				description: "Stable Audio sampling steps, model-dependent: stable-audio-2 30-100, stable-audio-2.5/3 4-8 (out-of-range auto-clamped)."
+			},
+			cfg_scale: {
+				type: "number",
+				description: "Stable Audio prompt adherence 1-25 (stable-audio-2 default 7, 2.5/3 default 1); higher follows the prompt more strictly."
+			},
 			format: {
 				type: "string",
 				description: "Output format such as mp3 or wav. MiniMax music supports mp3/wav/pcm."
@@ -1824,12 +2499,40 @@ function registerAgentAudioTools(ctx, resolve) {
 					type: "object",
 					additionalProperties: false,
 					properties: {
-						voice_id: { type: "string" },
-						weight: { type: "integer" }
-					},
-					required: ["voice_id", "weight"]
+						voice_id: {
+							type: "string",
+							required: true
+						},
+						weight: {
+							type: "integer",
+							required: true
+						}
+					}
 				},
 				description: "MiniMax TTS dual-voice blend weights (timbre_weights)."
+			},
+			save_to_library: {
+				type: "boolean",
+				description: "Save the generated audio into the local resource library after success. Also enabled globally by the \"auto save to library\" setting; pass false to skip a single run."
+			},
+			library_name: {
+				type: "string",
+				description: "Resource name in the library. Defaults to the prompt."
+			},
+			library_type: {
+				type: "string",
+				enum: [
+					"voice",
+					"music",
+					"sfx",
+					"tts"
+				],
+				description: "Resource type in the library. Defaults to the generation mode (voice_design → voice)."
+			},
+			library_tags: {
+				type: "array",
+				items: { type: "string" },
+				description: "Tags for the library resource."
 			}
 		},
 		output: {
@@ -1842,117 +2545,356 @@ function registerAgentAudioTools(ctx, resolve) {
 			const config = resolve();
 			ensureConfigured(config);
 			const mode = args.mode === "music" ? "music" : args.mode === "sfx" ? "sfx" : args.mode === "voice_design" ? "voice_design" : "tts";
-			const picked = mode === "voice_design" ? (() => {
-				const usable = config.channels.filter((channel) => channel.apiUrl.trim() !== "" && channel.apiKey.trim() !== "");
-				const target = usable.find((channel) => channel.id === config.defaultChannelId) ?? usable[0];
-				if (target === void 0) throw new AudioGenError("No usable audio channel is configured for voice design.", "no-channel-available");
+			/** 把生成参数（snake_case 入参或 model_params 片段）映射为请求字段。 */
+			const mapParams = (raw) => {
+				const voiceModify = typeof raw.voice_modify === "object" && raw.voice_modify !== null ? (() => {
+					const src = raw.voice_modify;
+					const out = {};
+					if (typeof src.pitch === "number") out.pitch = src.pitch;
+					if (typeof src.intensity === "number") out.intensity = src.intensity;
+					if (typeof src.timbre === "number") out.timbre = src.timbre;
+					if (typeof src.sound_effects === "string" && src.sound_effects.trim() !== "") out.soundEffects = src.sound_effects.trim();
+					return Object.keys(out).length > 0 ? out : void 0;
+				})() : void 0;
+				const timbreWeights = Array.isArray(raw.timbre_weights) ? raw.timbre_weights.filter((item) => typeof item === "object" && item !== null && typeof item.voice_id === "string" && typeof item.weight === "number").map((item) => ({
+					voiceId: item.voice_id.trim(),
+					weight: item.weight
+				})).filter((item) => item.voiceId !== "") : void 0;
+				const stringOrEmpty = (key) => {
+					const value = raw[key];
+					return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+				};
+				const finiteOrUndefined = (key) => {
+					const value = raw[key];
+					return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+				};
 				return {
-					channel: target,
-					alias: "",
-					upstream: ""
+					...stringOrEmpty("voice") !== void 0 ? { voice: stringOrEmpty("voice") } : {},
+					...stringOrEmpty("preview_text") !== void 0 ? { previewText: stringOrEmpty("preview_text") } : {},
+					...finiteOrUndefined("speed") !== void 0 ? { speed: finiteOrUndefined("speed") } : {},
+					...finiteOrUndefined("duration") !== void 0 ? { duration: finiteOrUndefined("duration") } : {},
+					...stringOrEmpty("lyrics") !== void 0 ? { lyrics: stringOrEmpty("lyrics") } : {},
+					...typeof raw.is_instrumental === "boolean" ? { isInstrumental: raw.is_instrumental } : {},
+					...typeof raw.loop === "boolean" ? { loop: raw.loop } : {},
+					...finiteOrUndefined("prompt_influence") !== void 0 ? { promptInfluence: finiteOrUndefined("prompt_influence") } : {},
+					...finiteOrUndefined("seed") !== void 0 ? { seed: finiteOrUndefined("seed") } : {},
+					...finiteOrUndefined("steps") !== void 0 ? { steps: finiteOrUndefined("steps") } : {},
+					...finiteOrUndefined("cfg_scale") !== void 0 ? { cfgScale: finiteOrUndefined("cfg_scale") } : {},
+					...stringOrEmpty("format") !== void 0 ? { format: stringOrEmpty("format") } : {},
+					...stringOrEmpty("emotion") !== void 0 ? { emotion: stringOrEmpty("emotion") } : {},
+					...finiteOrUndefined("vol") !== void 0 ? { vol: finiteOrUndefined("vol") } : {},
+					...finiteOrUndefined("pitch") !== void 0 ? { pitch: finiteOrUndefined("pitch") } : {},
+					...typeof raw.text_normalization === "boolean" ? { textNormalization: raw.text_normalization } : {},
+					...typeof raw.latex_read === "boolean" ? { latexRead: raw.latex_read } : {},
+					...Array.isArray(raw.pronunciation_tone) && raw.pronunciation_tone.length > 0 ? { pronunciationTone: raw.pronunciation_tone.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim()) } : {},
+					...finiteOrUndefined("sample_rate") !== void 0 ? { sampleRate: finiteOrUndefined("sample_rate") } : {},
+					...finiteOrUndefined("bitrate") !== void 0 ? { bitrate: finiteOrUndefined("bitrate") } : {},
+					...finiteOrUndefined("channel") !== void 0 ? { audioChannel: finiteOrUndefined("channel") } : {},
+					...typeof raw.force_cbr === "boolean" ? { forceCbr: raw.force_cbr } : {},
+					...typeof raw.subtitle_enable === "boolean" ? { subtitleEnable: raw.subtitle_enable } : {},
+					...typeof raw.aigc_watermark === "boolean" ? { aigcWatermark: raw.aigc_watermark } : {},
+					...stringOrEmpty("language_boost") !== void 0 ? { languageBoost: stringOrEmpty("language_boost") } : {},
+					...voiceModify !== void 0 ? { voiceModify } : {},
+					...timbreWeights !== void 0 && timbreWeights.length > 0 ? { timbreWeights } : {}
 				};
-			})() : resolveModel(config, args.model);
-			const voiceModify = typeof args.voice_modify === "object" && args.voice_modify !== null ? (() => {
-				const raw = args.voice_modify;
-				const out = {};
-				if (typeof raw.pitch === "number") out.pitch = raw.pitch;
-				if (typeof raw.intensity === "number") out.intensity = raw.intensity;
-				if (typeof raw.timbre === "number") out.timbre = raw.timbre;
-				if (typeof raw.sound_effects === "string" && raw.sound_effects.trim() !== "") out.soundEffects = raw.sound_effects.trim();
-				return Object.keys(out).length > 0 ? out : void 0;
-			})() : void 0;
-			const timbreWeights = Array.isArray(args.timbre_weights) ? args.timbre_weights.filter((item) => typeof item === "object" && item !== null && typeof item.voice_id === "string" && typeof item.weight === "number").map((item) => ({
-				voiceId: item.voice_id.trim(),
-				weight: item.weight
-			})).filter((item) => item.voiceId !== "") : void 0;
-			const request = {
-				mode,
-				model: picked.alias,
-				upstream: picked.upstream,
-				channelId: picked.channel.id,
-				channel: picked.channel.name,
-				prompt: args.prompt.trim(),
-				...typeof args.voice === "string" && args.voice.trim() !== "" ? { voice: args.voice.trim() } : {},
-				...typeof args.preview_text === "string" && args.preview_text.trim() !== "" ? { previewText: args.preview_text.trim() } : {},
-				...typeof args.speed === "number" ? { speed: args.speed } : {},
-				...typeof args.duration === "number" ? { duration: args.duration } : {},
-				...typeof args.lyrics === "string" && args.lyrics.trim() !== "" ? { lyrics: args.lyrics.trim() } : {},
-				...typeof args.is_instrumental === "boolean" ? { isInstrumental: args.is_instrumental } : {},
-				...typeof args.loop === "boolean" ? { loop: args.loop } : {},
-				...typeof args.prompt_influence === "number" && Number.isFinite(args.prompt_influence) ? { promptInfluence: args.prompt_influence } : {},
-				...typeof args.format === "string" && args.format.trim() !== "" ? { format: args.format.trim() } : {},
-				...typeof args.emotion === "string" && args.emotion.trim() !== "" ? { emotion: args.emotion.trim() } : {},
-				...typeof args.vol === "number" && Number.isFinite(args.vol) ? { vol: args.vol } : {},
-				...typeof args.pitch === "number" && Number.isFinite(args.pitch) ? { pitch: args.pitch } : {},
-				...typeof args.text_normalization === "boolean" ? { textNormalization: args.text_normalization } : {},
-				...typeof args.latex_read === "boolean" ? { latexRead: args.latex_read } : {},
-				...Array.isArray(args.pronunciation_tone) && args.pronunciation_tone.length > 0 ? { pronunciationTone: args.pronunciation_tone.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim()) } : {},
-				...typeof args.sample_rate === "number" && Number.isFinite(args.sample_rate) ? { sampleRate: args.sample_rate } : {},
-				...typeof args.bitrate === "number" && Number.isFinite(args.bitrate) ? { bitrate: args.bitrate } : {},
-				...typeof args.channel === "number" && Number.isFinite(args.channel) ? { audioChannel: args.channel } : {},
-				...typeof args.force_cbr === "boolean" ? { forceCbr: args.force_cbr } : {},
-				...typeof args.subtitle_enable === "boolean" ? { subtitleEnable: args.subtitle_enable } : {},
-				...typeof args.aigc_watermark === "boolean" ? { aigcWatermark: args.aigc_watermark } : {},
-				...typeof args.language_boost === "string" && args.language_boost.trim() !== "" ? { languageBoost: args.language_boost.trim() } : {},
-				...voiceModify !== void 0 ? { voiceModify } : {},
-				...timbreWeights !== void 0 && timbreWeights.length > 0 ? { timbreWeights } : {}
 			};
-			try {
-				const outputs = await generateAudio(picked.channel, request, exec.signal);
-				const audio = [];
-				for (const [index, output] of outputs.entries()) {
-					const saved = await saveAudioFile(output.data, output.mime, `generated-${index + 1}`);
-					audio.push({
-						id: saved.id,
-						url: `/api/dsh-audiogen/audio/${encodeURIComponent(saved.file)}`,
-						mime: saved.mime,
-						bytes: saved.bytes,
-						...output.voiceId === void 0 ? {} : { voiceId: output.voiceId }
-					});
+			const buildRequest = (picked) => {
+				const base = mapParams(args);
+				let override = {};
+				if (typeof args.model_params === "object" && args.model_params !== null) {
+					const perModel = args.model_params[picked.alias];
+					if (typeof perModel === "object" && perModel !== null) override = mapParams(perModel);
 				}
+				return {
+					mode,
+					model: picked.alias,
+					upstream: picked.upstream,
+					channelId: picked.channel.id,
+					channel: picked.channel.name,
+					prompt: typeof args.prompt === "string" ? args.prompt.trim() : "",
+					...base,
+					...override
+				};
+			};
+			/** 单模型执行：生成 + 保存文件 + 历史 + 可选资源库；错误收敛为分组结果。 */
+			const runOne = async (picked) => {
+				const request = buildRequest(picked);
 				try {
-					await appendHistory({
-						id: randomUUID(),
-						createdAt: Date.now(),
-						mode: request.mode,
-						model: picked.alias,
-						prompt: request.prompt,
-						...request.voice === void 0 ? {} : { voice: request.voice },
-						...request.speed === void 0 ? {} : { speed: request.speed },
-						...request.duration === void 0 ? {} : { duration: request.duration },
-						...request.format === void 0 ? {} : { format: request.format },
-						audio: outputs.map((output, index) => ({
-							id: audio[index].id,
-							b64: Buffer.from(output.data).toString("base64"),
-							mime: audio[index].mime,
-							bytes: audio[index].bytes,
-							url: audio[index].url,
+					const outputs = await generateAudio(picked.channel, request, exec.signal);
+					const audio = [];
+					const saved = [];
+					for (const [index, output] of outputs.entries()) {
+						const stored = await saveAudioFile(output.data, output.mime, `generated-${index + 1}`);
+						saved.push({
+							id: stored.id,
+							url: `/api/dsh-audiogen/audio/${encodeURIComponent(stored.file)}`,
+							file: stored.file,
+							mime: stored.mime,
+							bytes: stored.bytes,
 							...output.voiceId === void 0 ? {} : { voiceId: output.voiceId }
-						})),
-						channelId: picked.channel.id,
-						channel: picked.channel.name
-					});
-				} catch {}
+						});
+						audio.push({
+							id: stored.id,
+							url: `/api/dsh-audiogen/audio/${encodeURIComponent(stored.file)}`,
+							mime: stored.mime,
+							bytes: stored.bytes,
+							...output.voiceId === void 0 ? {} : { voiceId: output.voiceId }
+						});
+					}
+					try {
+						await appendHistory({
+							id: randomUUID(),
+							createdAt: Date.now(),
+							mode: request.mode,
+							model: picked.alias,
+							prompt: request.prompt,
+							...request.voice === void 0 ? {} : { voice: request.voice },
+							...request.speed === void 0 ? {} : { speed: request.speed },
+							...request.duration === void 0 ? {} : { duration: request.duration },
+							...request.format === void 0 ? {} : { format: request.format },
+							audio: outputs.map((output, index) => ({
+								id: saved[index].id,
+								file: saved[index].file,
+								b64: Buffer.from(output.data).toString("base64"),
+								mime: saved[index].mime,
+								bytes: saved[index].bytes,
+								url: saved[index].url,
+								...output.voiceId === void 0 ? {} : { voiceId: output.voiceId }
+							})),
+							channelId: picked.channel.id,
+							channel: picked.channel.name,
+							params: { ...request }
+						});
+					} catch {}
+					const wantSave = args.save_to_library === true || config.autoSaveToLibrary && args.save_to_library !== false;
+					let resources;
+					if (wantSave) try {
+						resources = [(await saveToLibrary({
+							audioFiles: saved.map((item) => ({
+								id: item.id,
+								file: item.file,
+								mime: item.mime,
+								...item.voiceId === void 0 ? {} : { voiceId: item.voiceId }
+							})),
+							type: libraryTypeOf(request.mode, args.library_type),
+							...typeof args.library_name === "string" && args.library_name.trim() !== "" ? { name: args.library_name.trim() } : {},
+							...Array.isArray(args.library_tags) ? { tags: args.library_tags.filter((tag) => typeof tag === "string" && tag.trim() !== "").map((tag) => tag.trim()) } : {},
+							provenance: {
+								mode: request.mode,
+								prompt: request.prompt,
+								channel: picked.channel.name,
+								channelId: picked.channel.id,
+								apiUrl: picked.channel.apiUrl,
+								model: picked.alias,
+								upstream: picked.upstream,
+								...request.voice === void 0 ? {} : { voice: request.voice },
+								params: { ...request }
+							}
+						})).id];
+					} catch {}
+					return {
+						model: picked.alias,
+						audio,
+						...resources === void 0 ? {} : { resources }
+					};
+				} catch (error) {
+					if (exec.signal?.aborted === true) throw error;
+					return {
+						model: picked.alias,
+						audio: [],
+						error: error instanceof Error ? error.message : String(error)
+					};
+				}
+			};
+			const requestedModels = Array.isArray(args.models) ? [...new Set(args.models.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim()))] : [];
+			if (requestedModels.length > 0 && mode !== "voice_design") {
+				const groups = [];
+				let succeeded = 0;
+				for (const alias of requestedModels) {
+					let picked;
+					try {
+						picked = resolveModel(config, alias);
+					} catch (error) {
+						groups.push({
+							model: alias,
+							audio: [],
+							error: error instanceof Error ? error.message : String(error)
+						});
+						continue;
+					}
+					const group = await runOne(picked);
+					groups.push(group);
+					if (group.error === void 0) succeeded++;
+				}
 				return {
-					status: "completed",
-					message: "Audio generation completed. The audio files can be played/downloaded from the returned URLs.",
-					mode: request.mode,
-					model: picked.alias,
-					audio
+					status: succeeded > 0 ? "completed" : "failed",
+					message: succeeded > 0 ? `Generated ${succeeded}/${groups.length} model(s) with the same prompt for comparison. The audio files can be played/downloaded from the returned URLs.` : "All model generations failed.",
+					mode,
+					model: groups[0]?.model ?? requestedModels[0],
+					audio: groups.flatMap((group) => group.audio),
+					groups,
+					...succeeded === 0 ? { error: groups.map((group) => `${group.model}: ${group.error ?? ""}`).filter((item) => !item.endsWith(": ")).join("；") } : {}
 				};
-			} catch (error) {
-				if (exec.signal?.aborted === true) throw error;
+			}
+			const one = await runOne(mode === "voice_design" ? (() => {
+				const usable = config.channels.filter((channel) => channel.apiUrl.trim() !== "" && channel.apiKey.trim() !== "");
+				const target = usable.find((channel) => channel.id === config.defaultChannelId) ?? usable[0];
+				if (target === void 0) throw new AudioGenError("No usable audio channel is configured for voice design.", "no-channel-available");
 				return {
-					status: "failed",
-					message: "Audio generation failed.",
-					mode: request.mode,
-					model: picked.alias,
-					audio: [],
-					error: error instanceof Error ? error.message : String(error)
+					channel: target,
+					alias: "",
+					upstream: ""
 				};
+			})() : resolveModel(config, args.model));
+			if (one.error !== void 0) return {
+				status: "failed",
+				message: "Audio generation failed.",
+				mode,
+				model: one.model,
+				audio: [],
+				error: one.error
+			};
+			return {
+				status: "completed",
+				message: "Audio generation completed. The audio files can be played/downloaded from the returned URLs.",
+				mode,
+				model: one.model,
+				audio: one.audio,
+				...one.resources === void 0 ? {} : { resources: one.resources }
+			};
+		}
+	}));
+	const searchDisposer = ctx.tools.register(defineTool({
+		name: "search_audio_library",
+		description: "Search curated audio resources in the local resource library (voice / music / sfx / tts). Returns matching resources with type, category, name, tags, full provenance (channel, model, voiceId, prompt) and same-origin audio URLs the user can play. Use it before generating to reuse an existing voice, music bed or sound effect instead of generating a new one.",
+		parameters: {
+			type: {
+				type: "string",
+				enum: [
+					"voice",
+					"music",
+					"sfx",
+					"tts"
+				],
+				description: "Filter by resource type."
+			},
+			category: {
+				type: "string",
+				description: "Filter by category (voice: male/female/custom; tts: the speaking voice key)."
+			},
+			keyword: {
+				type: "string",
+				description: "Search name, tags, prompt and model."
 			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					status: {
+						type: "string",
+						required: true,
+						enum: ["ok"]
+					},
+					count: {
+						type: "integer",
+						required: true
+					},
+					entries: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								id: {
+									type: "string",
+									required: true
+								},
+								name: {
+									type: "string",
+									required: true
+								},
+								type: {
+									type: "string",
+									required: true,
+									enum: [
+										"voice",
+										"music",
+										"sfx",
+										"tts"
+									]
+								},
+								category: { type: "string" },
+								tags: {
+									type: "array",
+									items: { type: "string" },
+									required: true
+								},
+								prompt: {
+									type: "string",
+									required: true
+								},
+								model: { type: "string" },
+								channel: { type: "string" },
+								voiceId: { type: "string" },
+								urls: {
+									type: "array",
+									items: { type: "string" },
+									required: true
+								}
+							}
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value)
+			}]
+		},
+		isConcurrencySafe: () => true,
+		async execute(args) {
+			const keyword = typeof args.keyword === "string" ? args.keyword.trim().toLowerCase() : "";
+			const wantedType = args.type === "voice" || args.type === "music" || args.type === "sfx" || args.type === "tts" ? args.type : void 0;
+			const wantedCategory = typeof args.category === "string" && args.category.trim() !== "" ? args.category.trim() : void 0;
+			const entries = (await listLibrary()).filter((entry) => {
+				if (wantedType !== void 0 && entry.type !== wantedType) return false;
+				if (wantedCategory !== void 0 && (entry.category ?? "") !== wantedCategory) return false;
+				if (keyword !== "") {
+					if (![
+						entry.name,
+						...entry.tags,
+						entry.provenance.prompt,
+						entry.provenance.model ?? "",
+						entry.provenance.channel ?? ""
+					].join(" ").toLowerCase().includes(keyword)) return false;
+				}
+				return true;
+			}).slice(0, 30).map((entry) => ({
+				id: entry.id,
+				name: entry.name,
+				type: entry.type,
+				...entry.category === void 0 ? {} : { category: entry.category },
+				tags: entry.tags,
+				prompt: entry.provenance.prompt,
+				...entry.provenance.model === void 0 ? {} : { model: entry.provenance.model },
+				...entry.provenance.channel === void 0 ? {} : { channel: entry.provenance.channel },
+				...entry.provenance.voiceId === void 0 ? {} : { voiceId: entry.provenance.voiceId },
+				urls: entry.files.map((file) => file.url)
+			}));
+			return {
+				status: "ok",
+				count: entries.length,
+				entries
+			};
 		}
 	}));
+	return () => {
+		disposer();
+		searchDisposer();
+	};
 }
 //#endregion
 //#region src/index.ts
@@ -1978,7 +2920,8 @@ const Config = z.object({
 	})).default([]),
 	channelSecrets: z.dict(z.string().role("secret")).default({}),
 	defaultChannelId: z.string().default(""),
-	defaultModel: z.string().default("")
+	defaultModel: z.string().default(""),
+	autoSaveToLibrary: z.boolean().default(false)
 });
 const DEFAULT_ENABLED = true;
 const DEFAULT_ANNOUNCE = true;
@@ -1996,6 +2939,29 @@ function guidanceFor(channels, defaultChannelId) {
 	}).join("；");
 	return `${AUDIOGEN_GUIDANCE} 当前渠道与模型：${table}。`;
 }
+/**
+* 把随包分发的技能（skills/<id>/SKILL.md，含 frontmatter）同步到 DSH 用户技能根
+* `~/.dsh/skills/<id>/SKILL.md` —— DSH web 会话的 skill-filesystem（standard 等
+* preset 行）会扫描用户根，使会话可直接触发这些技能。仅创建缺失文件，绝不覆盖
+* 用户已有内容；任何失败仅告警，不影响插件本身。
+*/
+function syncBundledSkills() {
+	try {
+		const sourceRoot = join(dirname(dirname(fileURLToPath(import.meta.url))), "skills");
+		if (existsSync(sourceRoot) !== true) return;
+		const targetRoot = join(process.env.DSH_HOME ?? join(process.env.HOME ?? "", ".dsh"), "skills");
+		for (const entry of readdirSync(sourceRoot, { withFileTypes: true })) {
+			if (entry.isDirectory() !== true) continue;
+			const sourceFile = join(sourceRoot, entry.name, "SKILL.md");
+			if (existsSync(sourceFile) !== true) continue;
+			const targetDir = join(targetRoot, entry.name);
+			const targetFile = join(targetDir, "SKILL.md");
+			if (existsSync(targetFile)) continue;
+			mkdirSync(targetDir, { recursive: true });
+			copyFileSync(sourceFile, targetFile);
+		}
+	} catch {}
+}
 function normalizeChannels(value) {
 	if (!Array.isArray(value)) return [];
 	const out = [];
@@ -2027,6 +2993,7 @@ function normalizeChannels(value) {
 	return out;
 }
 function apply(ctx, config) {
+	syncBundledSkills();
 	let current = () => config ?? {};
 	const resolve = () => {
 		const value = current() ?? {};
@@ -2046,7 +3013,8 @@ function apply(ctx, config) {
 				apiKey: typeof secrets[channel.id] === "string" ? secrets[channel.id] : ""
 			})),
 			defaultChannelId,
-			defaultModel: typeof value.defaultModel === "string" ? value.defaultModel.trim() : ""
+			defaultModel: typeof value.defaultModel === "string" ? value.defaultModel.trim() : "",
+			autoSaveToLibrary: value.autoSaveToLibrary === true
 		};
 	};
 	const channelsView = () => {
@@ -2061,7 +3029,8 @@ function apply(ctx, config) {
 		sctx.effect(() => {
 			const disposers = makeRoutes({
 				settings: seam,
-				resolveChannels: channelsView
+				resolveChannels: channelsView,
+				autoSave: () => resolve().autoSaveToLibrary
 			}).map((route) => ctx.webServer.register(route));
 			return () => {
 				for (const dispose of disposers) dispose();
@@ -2075,7 +3044,8 @@ function apply(ctx, config) {
 				enabled: value.enabled,
 				allowAgentAudioGeneration: value.allowAgentAudioGeneration,
 				channels: value.channels,
-				defaultChannelId: value.defaultChannelId
+				defaultChannelId: value.defaultChannelId,
+				autoSaveToLibrary: value.autoSaveToLibrary
 			};
 		}), "dsh-audiogen: agent audio tools");
 	});