dsh-audiogen 0.4.19 → 0.4.22

package/lib/index.js

@@ -35,7 +35,12 @@ const MODEL_API = { discover: "/api/dsh-audiogen/models/discover" };
 /** Vendor voice management (browse/filter + delete) endpoints. */
 const VOICES_API = {
 	list: "/api/dsh-audiogen/voices/list",
-	delete: "/api/dsh-audiogen/voices/delete"
+	delete: "/api/dsh-audiogen/voices/delete",
+	recommend: "/api/dsh-audiogen/voices/recommend",
+	recommendHistory: {
+		list: "/api/dsh-audiogen/voices/recommend-history/list",
+		remove: "/api/dsh-audiogen/voices/recommend-history/remove"
+	}
 };
 /** Loopback-only audio file reader for panel/tool-result previews. */
 const AUDIO_API = { file: "/api/dsh-audiogen/audio" };
@@ -1054,7 +1059,7 @@ async function enhancePromptText(deps, prompt, mode, override) {
 	} finally {
 		clearTimeout(timer);
 	}
-	const result = stripFences(output.trim());
+	const result = stripFences$1(output.trim());
 	if (result === "") {
 		if (terminalFailure !== "") throw new AudioGenError(`增强失败：LLM 调用出错（${terminalFailure}）。请检查「设置 → 模型」的默认模型是否可用`, "enhance-llm-error");
 		throw new AudioGenError("模型未返回增强内容：请检查「设置 → 模型」的默认模型是否可用（或稍后重试）", "enhance-empty-result");
@@ -1062,7 +1067,7 @@ async function enhancePromptText(deps, prompt, mode, override) {
 	return result;
 }
 /** 去掉模型可能包裹的 ``` 代码围栏。 */
-function stripFences(value) {
+function stripFences$1(value) {
 	if (value === "") return value;
 	return value.replace(/^```[a-zA-Z]*\s*\n?/, "").replace(/\n?```\s*$/, "").trim();
 }
@@ -1074,6 +1079,40 @@ const SHARED_VOICE_SORT_OPTIONS = [
 	"oldest",
 	"newest"
 ];
+/**
+* ISO 639-1 -> matching substrings across the two vendor vocabularies:
+* ElevenLabs uses ISO codes ("en"), MiniMax system ids use language labels
+* ("Chinese (Mandarin)_..." / "Japanese_..."). The aliases make one dropdown
+* value match both. "zh" also covers Cantonese (Chinese (Cantonese)).
+*/
+const LANGUAGE_ALIASES = {
+	zh: [
+		"zh",
+		"chinese",
+		"mandarin",
+		"cantonese",
+		"yue"
+	],
+	en: ["en", "english"],
+	ja: ["ja", "japanese"],
+	ko: ["ko", "korean"],
+	es: ["es", "spanish"],
+	fr: ["fr", "french"],
+	de: ["de", "german"],
+	ru: ["ru", "russian"],
+	it: ["it", "italian"],
+	pt: ["pt", "portuguese"],
+	ar: ["ar", "arabic"],
+	hi: ["hi", "hindi"]
+};
+function languageMatches(language, locale, needle) {
+	const haystack = [language ?? "", locale ?? ""].join(" ").toLowerCase();
+	const value = needle.trim().toLowerCase();
+	if (value === "") return true;
+	if (haystack.includes(value)) return true;
+	for (const alias of LANGUAGE_ALIASES[value] ?? []) if (haystack.includes(alias)) return true;
+	return false;
+}
 const MINIMAX_LANGUAGE_PREFIXES = [
 	"Chinese (Mandarin)",
 	"Chinese (Cantonese)",
@@ -1105,7 +1144,7 @@ function baseUrl$1(url) {
 function languageFromMiniMaxId(voiceId) {
 	for (const prefix of MINIMAX_LANGUAGE_PREFIXES) if (voiceId.startsWith(`${prefix}_`)) return prefix;
 }
-function asStringList(value) {
+function asStringList$1(value) {
 	if (Array.isArray(value)) return value.map((item) => String(item)).filter((item) => item.trim() !== "");
 	if (typeof value === "string" && value.trim() !== "") return [value.trim()];
 	return [];
@@ -1130,7 +1169,7 @@ async function postJson$1(url, apiKey, body) {
 }
 function normalizeMiniMax(voice, source) {
 	const voiceId = String(voice.voice_id ?? "").trim();
-	const description = asStringList(voice.description).join("；") || void 0;
+	const description = asStringList$1(voice.description).join("；") || void 0;
 	const language = languageFromMiniMaxId(voiceId);
 	return {
 		provider: "minimax",
@@ -1171,10 +1210,14 @@ function normalizeElevenLabs(voice, source) {
 		return (typeof owned === "string" && owned.trim() !== "" ? owned : typeof direct === "string" && direct.trim() !== "" ? direct : void 0)?.trim() || void 0;
 	};
 	const description = pick("description");
+	const name = String(voice.name ?? voiceId).trim() || voiceId;
+	const keptLabels = {};
+	for (const [key, value] of Object.entries(labels ?? {})) if (typeof value === "string" && value.trim() !== "") keptLabels[key] = value;
+	const descriptive = pick("descriptive");
 	return {
 		provider: "elevenlabs",
 		voice_id: voiceId,
-		name: String(voice.name ?? voiceId).trim() || voiceId,
+		name,
 		source,
 		...pick("language") === void 0 ? {} : { language: pick("language") },
 		...pick("locale") === void 0 ? {} : { locale: pick("locale") },
@@ -1183,6 +1226,8 @@ function normalizeElevenLabs(voice, source) {
 		...pick("age") === void 0 ? {} : { age: pick("age") },
 		...pick("use_case") === void 0 ? {} : { use_case: pick("use_case") },
 		...pick("category") === void 0 ? {} : { category: pick("category") },
+		...Object.keys(keptLabels).length === 0 ? {} : { labels: keptLabels },
+		...descriptive === void 0 ? {} : { descriptive },
 		...description === void 0 ? {} : { description },
 		...typeof voice.preview_url === "string" && voice.preview_url.trim() !== "" ? { preview_url: voice.preview_url.trim() } : {},
 		deletable: source === "owned"
@@ -1285,6 +1330,32 @@ async function listVendorVoices(channel, options = {}) {
 		...result.note === void 0 ? {} : { note: result.note }
 	};
 }
+/**
+* listVendorVoices 的网关友好版本：聚合网关（new-api 等）通常只代理生成接口、
+* 不映射 /v1/voices 与 /v1/shared-voices，此时把「渠道配置的音色目录」
+* （channel.models 的 alias 列表）作为候选池，保证音色浏览/推荐/选角仍可用。
+* 返回条目的 source 为 `configured`（只读、无试听、无性别/年龄元数据）。
+*/
+async function listVendorVoicesWithFallback(channel, options = {}) {
+	try {
+		return await listVendorVoices(channel, options);
+	} catch (error) {
+		const entries = (channel.models ?? []).filter((model) => model.alias.trim() !== "").map((model) => ({
+			provider: channel.preset || "configured",
+			voice_id: model.alias,
+			name: model.alias,
+			source: "configured",
+			deletable: false
+		}));
+		if (entries.length === 0) throw error;
+		const reason = error instanceof Error ? error.message : String(error);
+		return {
+			vendor: channel.preset || "custom",
+			...applyFilter(entries, options),
+			note: `音色库接口不可用（${reason.slice(0, 160)}）。已回退为渠道配置的音色目录（${entries.length} 个）：只能按名称选择，无试听与语言/性别/年龄元数据；配一个官方 API 地址（如 https://api.elevenlabs.io）的渠道可获得完整音色库`
+		};
+	}
+}
 async function deleteVendorVoice(channel, voiceId) {
 	if (channel.apiUrl.trim() === "") throw new Error("渠道未配置 API 地址");
 	if (channel.apiKey.trim() === "") throw new Error("渠道未配置 API 密钥");
@@ -1354,9 +1425,7 @@ function applyFilter(entries, options) {
 	const count = cap(options);
 	const matched = entries.filter((entry) => {
 		if (source !== "" && entry.source !== source) return false;
-		if (language !== "") {
-			if (![entry.language ?? "", entry.locale ?? ""].join(" ").toLowerCase().includes(language)) return false;
-		}
+		if (language !== "" && !languageMatches(entry.language, entry.locale, language)) return false;
 		if (field(filters.accent) !== "" && field(entry.accent) !== field(filters.accent)) return false;
 		if (field(filters.gender) !== "" && field(entry.gender) !== field(filters.gender)) return false;
 		if (field(filters.age) !== "" && field(entry.age) !== field(filters.age)) return false;
@@ -1374,7 +1443,9 @@ function applyFilter(entries, options) {
 				entry.accent ?? "",
 				entry.use_case ?? "",
 				entry.gender ?? "",
-				entry.age ?? ""
+				entry.age ?? "",
+				entry.descriptive ?? "",
+				...Object.values(entry.labels ?? {})
 			].join(" ").toLowerCase();
 			for (const token of keyword.split(/\s+/)) if (token !== "" && !haystack.includes(token)) return false;
 		}
@@ -1387,6 +1458,252 @@ function applyFilter(entries, options) {
 	};
 }
 //#endregion
+//#region src/voice-recommend.ts
+/** 推荐记录上限（超出最旧淘汰，新记录永远插在最前）。 */
+const RECORD_LIMIT = 50;
+function recommendStorePath() {
+	return path.join(process.env.DSH_HOME ?? path.join(os.homedir(), ".dsh"), "dsh-audiogen", "voice-recommends.json");
+}
+async function loadRecommendStore() {
+	try {
+		const text = await readFile(recommendStorePath(), "utf-8");
+		const payload = JSON.parse(text);
+		if (typeof payload === "object" && payload !== null && Array.isArray(payload.entries)) return {
+			version: 1,
+			updatedAt: String(payload.updatedAt ?? ""),
+			entries: payload.entries
+		};
+	} catch {}
+	return {
+		version: 1,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		entries: []
+	};
+}
+/** 追加一条 AI 推荐记录（最好努力：失败不阻断推荐结果返回）。 */
+async function appendVoiceRecommendRecord(record) {
+	const stored = {
+		id: randomUUID(),
+		createdAt: Date.now(),
+		...record
+	};
+	try {
+		const store = await loadRecommendStore();
+		store.entries = [stored, ...store.entries.filter((entry) => entry.id !== stored.id)].slice(0, RECORD_LIMIT);
+		store.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const file = recommendStorePath();
+		await mkdir(path.dirname(file), { recursive: true });
+		await writeFile(file, JSON.stringify(store, null, 2) + "\n", "utf-8");
+	} catch {}
+	return stored;
+}
+/** 读取最近 N 条 AI 推荐记录（新→旧）。 */
+async function listVoiceRecommendRecords(limit = 20) {
+	return (await loadRecommendStore()).entries.slice(0, Math.max(1, Math.min(50, Math.floor(limit))));
+}
+/** 删除一条 AI 推荐记录（不存在的 id 幂等成功）。 */
+async function removeVoiceRecommendRecord(id) {
+	const store = await loadRecommendStore();
+	const next = store.entries.filter((entry) => entry.id !== id);
+	if (next.length === store.entries.length) return;
+	const file = recommendStorePath();
+	await mkdir(path.dirname(file), { recursive: true });
+	await writeFile(file, JSON.stringify({
+		...store,
+		entries: next,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	}, null, 2) + "\n", "utf-8");
+}
+/** 候选描述的截断长度（超出以 … 结尾）。 */
+const MAX_DESCRIPTION_CHARS$1 = 400;
+/** LLM 调用超时。 */
+const RECOMMEND_TIMEOUT_MS = 45e3;
+/** 输出 token 预算：默认模型多为推理模型，思考 token 计入输出，需留足预算。 */
+const RECOMMEND_MAX_TOKENS = 8192;
+/** 需求描述 + 候选池 → top-k 推荐（每条含 LLM 理由）。 */
+async function recommendVoices(deps, requirement, candidates, topK) {
+	const text = requirement.trim();
+	if (text === "") throw new AudioGenError("需求描述为空，无法推荐音色", "recommend-empty-requirement");
+	if (candidates.length === 0) throw new AudioGenError("候选音色池为空：请先确认渠道配置了音色库，或放宽筛选条件", "recommend-no-candidates");
+	const value = (deps.settings.describe({ redactSecrets: true }) ?? []).find((candidate) => String(candidate.ns) === "agent-default-model")?.value ?? {};
+	const provider = typeof value.provider === "string" && value.provider.trim() !== "" ? value.provider.trim() : "";
+	const model = typeof value.model === "string" && value.model.trim() !== "" ? value.model.trim() : "";
+	if (provider === "" || model === "") throw new AudioGenError("未找到 Agent 默认模型（agent-default-model）：请先在「设置 → 模型」中配置默认模型", "no-default-model");
+	const runtime = deps.llm?.();
+	if (runtime === void 0 || runtime.stream === void 0) throw new AudioGenError("宿主 LLM 服务不可用（ctx.llm 未注册）", "llm-unavailable");
+	const messages = buildRecommendMessages(text, candidates, topK);
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new DOMException("The operation timed out.", "TimeoutError")), RECOMMEND_TIMEOUT_MS);
+	timer.unref?.();
+	let output = "";
+	let terminalFailure = "";
+	try {
+		for await (const chunk of runtime.stream({
+			provider,
+			model,
+			messages: [{
+				role: "user",
+				content: [{
+					type: "text",
+					text: messages.user
+				}]
+			}],
+			system: messages.system,
+			temperature: .2,
+			maxTokens: RECOMMEND_MAX_TOKENS,
+			signal: controller.signal
+		})) {
+			const record = chunk;
+			if (record.type === "text-delta" && typeof record.text === "string") output += record.text;
+			else if (record.type === "block-end" && record.block !== void 0 && record.block.type === "text" && typeof record.block.text === "string") output += record.block.text;
+			else if (record.type === "finish" && record.reason !== void 0 && record.reason.kind !== "stop" && record.reason.kind !== void 0 && terminalFailure === "") {
+				const failure = record.reason.failure;
+				terminalFailure = typeof failure?.message === "string" && failure.message.trim() !== "" ? `${failure.message}${typeof failure.code === "string" ? `（${failure.code}）` : ""}` : `stream ${record.reason.kind}`;
+			}
+		}
+	} finally {
+		clearTimeout(timer);
+	}
+	const content = stripFences(output.trim());
+	if (content === "") {
+		if (terminalFailure !== "") throw new AudioGenError(`音色推荐失败：LLM 调用出错（${terminalFailure}）。请检查「设置 → 模型」的默认模型是否可用`, "recommend-llm-error");
+		throw new AudioGenError("模型未返回推荐内容：请检查「设置 → 模型」的默认模型是否可用（或稍后重试）", "recommend-empty-result");
+	}
+	const recommendations = parseVoiceRecommendations(content, candidates, topK);
+	if (recommendations.length === 0) throw new AudioGenError("模型返回的推荐未能匹配候选池：请重试，或先用语言/关键词等条件缩小候选范围", "recommend-parse-failed");
+	return recommendations;
+}
+/** 纯函数：解析 LLM 响应并把推荐校验为候选池成员；无效/编造 id 丢弃。
+*
+* 兼容三种返回形态（模型并不总守 JSON）：
+*  1. JSON {"recommendations": [{"voice_id"|"voice_name": "...", "reason": "..."}]}
+*  2. JSON 数组 [{"voice_id": "..."}, ...] 或单对象 {"voice_id": "..."}
+*  3. 纯文本：按行/逗号/空白切分后，在候选池中做完全匹配（id 或 name，忽略大小写）
+*/
+function parseVoiceRecommendations(content, candidates, topK) {
+	const limit = Math.max(1, Math.floor(Number.isFinite(topK) ? topK : 5));
+	const results = [];
+	const seen = /* @__PURE__ */ new Set();
+	const findCandidate = (raw) => {
+		const needle = String(raw).trim();
+		if (needle === "") return void 0;
+		const byId = candidates.find((candidate) => candidate.voice_id === needle);
+		if (byId !== void 0) return byId;
+		const byName = candidates.find((candidate) => candidate.name.toLowerCase() === needle.toLowerCase());
+		if (byName !== void 0) return byName;
+		const normalized = needle.toLowerCase().replace(/\s+/g, " ");
+		return candidates.find((candidate) => candidate.voice_id.toLowerCase() === normalized || candidate.name.toLowerCase().replace(/\s+/g, " ") === normalized);
+	};
+	const push = (candidate, reason) => {
+		if (candidate === void 0 || results.length >= limit) return;
+		if (seen.has(candidate.voice_id)) return;
+		seen.add(candidate.voice_id);
+		results.push({
+			...candidate,
+			reason
+		});
+	};
+	const data = loadJsonLoose(content);
+	const rawItems = data === null ? void 0 : Array.isArray(data) ? data : typeof data === "object" ? data.recommendations : void 0;
+	if (Array.isArray(rawItems)) for (const item of rawItems) {
+		if (results.length >= limit) break;
+		if (typeof item !== "object" || item === null || Array.isArray(item)) continue;
+		const record = item;
+		const raw = record.voice_id ?? record.voice_name ?? record.name ?? record.id;
+		const reason = typeof record.reason === "string" ? record.reason.trim() : "";
+		push(findCandidate(String(raw)), reason);
+	}
+	if (results.length < limit) {
+		const flat = content.replace(/```[a-zA-Z]*/g, " ");
+		const lower = flat.toLowerCase();
+		const found = candidates.filter((candidate) => {
+			if (candidate.voice_id.length >= 3 && lower.includes(candidate.voice_id.toLowerCase())) return true;
+			if (candidate.name.length >= 3 && lower.includes(candidate.name.toLowerCase())) return true;
+			return false;
+		}).sort((a, b) => {
+			const ai = lower.indexOf(a.voice_id.toLowerCase());
+			const aiAlt = lower.indexOf(a.name.toLowerCase());
+			const bi = lower.indexOf(b.voice_id.toLowerCase());
+			const biAlt = lower.indexOf(b.name.toLowerCase());
+			const posA = ai === -1 ? aiAlt : ai === -1 ? ai : ai;
+			const posB = bi === -1 ? biAlt : bi === -1 ? bi : bi;
+			return (posA === -1 ? Number.MAX_SAFE_INTEGER : posA) - (posB === -1 ? Number.MAX_SAFE_INTEGER : posB);
+		});
+		for (const candidate of found) {
+			if (results.length >= limit) break;
+			push(candidate, "");
+		}
+		if (results.length < limit) {
+			const tokens = flat.replace(/[{}[\],:;"'`\n，。！？、；：（）()【】《》]+/g, " ").split(/\s+/).map((token) => token.trim()).filter((token) => token !== "");
+			for (const token of tokens) {
+				if (results.length >= limit) break;
+				push(findCandidate(token), "");
+			}
+		}
+	}
+	return results;
+}
+/** 构造推荐提示：系统（选角专家）+ 用户（需求 + 压缩候选 JSON）。 */
+function buildRecommendMessages(requirement, candidates, topK) {
+	const semantic = (entry) => entry.language !== void 0 && entry.language !== "" || entry.gender !== void 0 && entry.gender !== "" || entry.age !== void 0 && entry.age !== "" || entry.accent !== void 0 && entry.accent !== "" || entry.description !== void 0 && entry.description !== "";
+	const shown = [...candidates].sort((a, b) => semantic(a) === semantic(b) ? 0 : semantic(a) ? -1 : 1).slice(0, 80);
+	const note = candidates.length > shown.length ? `（注意：共 ${candidates.length} 条候选，仅展示前 ${shown.length} 条，其余候选未展示，请只从展示列表中挑选，或先用筛选条件缩小候选集。）` : "";
+	const system = [
+		"你是资深配音选角专家。根据用户描述的需求，从候选音色列表中挑选最合适的音色。",
+		"要求：",
+		"1. 只从候选列表中选，voice_id 必须与候选完全一致，不得编造。如果候选只有音色名没有语义字段，请结合名字里的语言/性别/年龄线索判断（如 Male_Young_、Chinese (Mandarin)_ 前缀）。",
+		"2. 综合考虑语言、性别、年龄感、音色气质与需求的匹配度，以及配音用途（旁白/角色/广告/游戏等）。",
+		`3. 只输出一个 JSON 对象：{"recommendations": [{"voice_id": "候选中的精确 voice_id", "reason": "简短中文理由"}]}，最多 ${Math.max(1, Math.floor(topK))} 条，按推荐优先级排序；候选的 voice_id 与 voice_name 可能相同或不同，一律用 voice_id 字段。`,
+		"4. 同需求下避免推荐多个明显同质的音色；不要输出 JSON 以外的任何文字。"
+	].join("\n");
+	const compact = shown.map((entry) => ({
+		voice_id: entry.voice_id,
+		voice_name: entry.name,
+		provider: entry.provider,
+		source: entry.source,
+		language: entry.language ?? null,
+		locale: entry.locale ?? null,
+		accent: entry.accent ?? null,
+		gender: entry.gender ?? null,
+		age: entry.age ?? null,
+		category: entry.category ?? null,
+		use_case: entry.use_case ?? null,
+		descriptive: entry.descriptive ?? null,
+		labels: entry.labels ?? null,
+		description: truncate(entry.description, MAX_DESCRIPTION_CHARS$1),
+		has_preview: entry.preview_url !== void 0 && entry.preview_url !== ""
+	}));
+	return {
+		system,
+		user: `需求：${requirement}\n\n候选音色（共 ${shown.length} 条）：\n${JSON.stringify(compact, null, 1)}\n${note}`
+	};
+}
+function truncate(value, limit) {
+	if (value === void 0) return null;
+	return value.length <= limit ? value : `${value.slice(0, limit - 1)}…`;
+}
+/** 去掉模型可能包裹的 ``` 代码围栏。 */
+function stripFences(value) {
+	if (value === "") return value;
+	return value.replace(/^```[a-zA-Z]*\s*\n?/, "").replace(/\n?```\s*$/, "").trim();
+}
+/** 宽松 JSON 解析：整体失败时尝试提取第一个 { 到最后一个 }。 */
+function loadJsonLoose(content) {
+	const text = stripFences(content);
+	try {
+		return JSON.parse(text);
+	} catch {
+		const start = text.indexOf("{");
+		const end = text.lastIndexOf("}");
+		if (start === -1 || end <= start) return null;
+		try {
+			return JSON.parse(text.slice(start, end + 1));
+		} catch {
+			return null;
+		}
+	}
+}
+//#endregion
 //#region src/audio-presets.ts
 const AUDIO_PRESETS = [
 	{
@@ -2302,6 +2619,60 @@ async function mergeLibraryProvenance(given, files, channels) {
 		...given.params !== void 0 || params !== void 0 ? { params: given.params ?? params } : {}
 	};
 }
+/** 从请求体解析音色列表/推荐共用的筛选选项。 */
+function voiceListOptionsOf(body) {
+	const str = (key) => {
+		const value = body?.[key];
+		return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+	};
+	const filters = {
+		...str("search") === void 0 ? {} : { search: str("search") },
+		...str("use_case") === void 0 ? {} : { use_case: str("use_case") },
+		...str("accent") === void 0 ? {} : { accent: str("accent") },
+		...str("gender") === void 0 ? {} : { gender: str("gender") },
+		...str("age") === void 0 ? {} : { age: str("age") },
+		...str("locale") === void 0 ? {} : { locale: str("locale") },
+		...str("category") === void 0 ? {} : { category: str("category") },
+		...str("sort") === void 0 ? {} : { sort: str("sort") },
+		...body?.featured === true ? { featured: true } : {},
+		...body?.free_users_allowed === true ? { free_users_allowed: true } : {},
+		...body?.descriptive === true ? { descriptive: true } : {}
+	};
+	return {
+		...str("language") === void 0 ? {} : { language: str("language") },
+		...str("keyword") === void 0 ? {} : { keyword: str("keyword") },
+		...str("source") === void 0 ? {} : { source: str("source") },
+		...typeof body?.limit === "number" && Number.isFinite(body.limit) ? { limit: Math.floor(body.limit) } : {},
+		...Object.keys(filters).length === 0 ? {} : { serverFilters: filters }
+	};
+}
+/** 推荐记录的筛选条件快照（面板展示用，不含密钥）。 */
+function recommendFiltersOf(body) {
+	const str = (key) => {
+		const value = body?.[key];
+		return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+	};
+	const out = {};
+	for (const key of [
+		"language",
+		"keyword",
+		"source",
+		"search",
+		"use_case",
+		"accent",
+		"gender",
+		"age",
+		"locale",
+		"category",
+		"sort"
+	]) {
+		const value = str(key);
+		if (value !== void 0) out[key] = value;
+	}
+	if (body?.featured === true) out.featured = true;
+	if (body?.free_users_allowed === true) out.free_users_allowed = true;
+	return out;
+}
 /** Build every /api/dsh-audiogen route. */
 function makeRoutes(deps) {
 	const guard = (req, res, method) => {
@@ -2413,31 +2784,8 @@ function makeRoutes(deps) {
 					});
 					return;
 				}
-				const str = (key) => {
-					const value = body?.[key];
-					return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
-				};
-				const filters = {
-					...str("search") === void 0 ? {} : { search: str("search") },
-					...str("use_case") === void 0 ? {} : { use_case: str("use_case") },
-					...str("accent") === void 0 ? {} : { accent: str("accent") },
-					...str("gender") === void 0 ? {} : { gender: str("gender") },
-					...str("age") === void 0 ? {} : { age: str("age") },
-					...str("locale") === void 0 ? {} : { locale: str("locale") },
-					...str("category") === void 0 ? {} : { category: str("category") },
-					...str("sort") === void 0 ? {} : { sort: str("sort") },
-					...body?.featured === true ? { featured: true } : {},
-					...body?.free_users_allowed === true ? { free_users_allowed: true } : {},
-					...body?.descriptive === true ? { descriptive: true } : {}
-				};
 				try {
-					const result = await listVendorVoices(channel, {
-						...str("language") === void 0 ? {} : { language: str("language") },
-						...str("keyword") === void 0 ? {} : { keyword: str("keyword") },
-						...str("source") === void 0 ? {} : { source: str("source") },
-						...typeof body?.limit === "number" && Number.isFinite(body.limit) ? { limit: Math.floor(body.limit) } : {},
-						...Object.keys(filters).length === 0 ? {} : { serverFilters: filters }
-					});
+					const result = await listVendorVoicesWithFallback(channel, voiceListOptionsOf(body));
 					writeJson(res, 200, {
 						ok: true,
 						vendor: result.vendor,
@@ -2501,6 +2849,129 @@ function makeRoutes(deps) {
 				}
 			}
 		},
+		{
+			kind: "exact",
+			path: VOICES_API.recommend,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const requirement = typeof body?.requirement === "string" ? body.requirement.trim() : "";
+				if (requirement === "") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "recommend-requirement-required",
+						message: "需求描述（requirement）不能为空。"
+					});
+					return;
+				}
+				const channel = channelOf(deps.resolveChannels(), body?.channel);
+				if (channel === void 0) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "channel-not-configured",
+						message: "没有可用的音频渠道（需要已配置 API 地址与密钥），请先在设置中添加。"
+					});
+					return;
+				}
+				const rawTopK = body?.top_k;
+				const topK = typeof rawTopK === "number" && Number.isFinite(rawTopK) ? Math.max(1, Math.min(10, Math.floor(rawTopK))) : 5;
+				try {
+					const result = await listVendorVoicesWithFallback(channel, {
+						...voiceListOptionsOf(body),
+						limit: 500
+					});
+					const recommendations = await deps.recommend(requirement, result.voices, topK);
+					appendVoiceRecommendRecord({
+						channel: channel.name,
+						vendor: result.vendor,
+						requirement,
+						candidate_count: result.voices.length,
+						top_k: topK,
+						channel_id: channel.id,
+						filters: recommendFiltersOf(body),
+						recommendations: recommendations.map((item) => ({
+							voice_id: item.voice_id,
+							name: item.name,
+							source: item.source,
+							deletable: item.deletable,
+							...item.language === void 0 ? {} : { language: item.language },
+							...item.locale === void 0 ? {} : { locale: item.locale },
+							...item.accent === void 0 ? {} : { accent: item.accent },
+							...item.gender === void 0 ? {} : { gender: item.gender },
+							...item.age === void 0 ? {} : { age: item.age },
+							...item.use_case === void 0 ? {} : { use_case: item.use_case },
+							...item.category === void 0 ? {} : { category: item.category },
+							...item.labels === void 0 ? {} : { labels: item.labels },
+							...item.descriptive === void 0 ? {} : { descriptive: item.descriptive },
+							...item.description === void 0 ? {} : { description: item.description },
+							...item.preview_url === void 0 ? {} : { preview_url: item.preview_url },
+							reason: item.reason
+						}))
+					}).catch(() => {});
+					writeJson(res, 200, {
+						ok: true,
+						vendor: result.vendor,
+						channel: channel.name,
+						requirement,
+						candidate_count: result.voices.length,
+						top_k: topK,
+						recommendations,
+						recorded: true,
+						...result.note === void 0 ? {} : { note: result.note }
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "voice-recommend-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: VOICES_API.recommendHistory.list,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const rawLimit = (await readJsonBody(req))?.limit;
+				const entries = await listVoiceRecommendRecords(typeof rawLimit === "number" && Number.isFinite(rawLimit) ? Math.max(1, Math.min(50, Math.floor(rawLimit))) : 20);
+				writeJson(res, 200, {
+					ok: true,
+					count: entries.length,
+					entries
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: VOICES_API.recommendHistory.remove,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const id = typeof body?.id === "string" ? body.id.trim() : "";
+				if (id === "") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "record-id-required",
+						message: "record id 不能为空。"
+					});
+					return;
+				}
+				try {
+					await removeVoiceRecommendRecord(id);
+					writeJson(res, 200, {
+						ok: true,
+						removed: id
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "record-remove-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
 		{
 			kind: "exact",
 			path: SETTINGS_API.describe,
@@ -3018,6 +3489,456 @@ function makeRoutes(deps) {
 	];
 }
 //#endregion
+//#region src/voice-cast.ts
+/**
+* 角色音色选角（voice casting）：把「角色画像 → 候选音色 → 主音色 + 备用音色」
+* 流水线落到插件里，等价于 standalone 音频工作室里 MiniMax/ElevenLabs 的选角逻辑。
+*
+* 分工（重要）：
+*  - 本模块只做确定性的事：角色画像归一化、硬过滤（gender/age/use_case 严格，
+*    accent 可放松）、投票校验（voice_id 必须属于该角色候选池、备份补齐、
+*    lead/major 主音色不重复）、选定记录持久化。
+*  - 「选谁」的推理/全局权衡由 Agent（DeepSeek Harness 当前模型）完成：
+*    action=cast 拿到每个角色的候选列表后，Agent 在上下文中统一选角，
+*    再把结果交给 action=save_cast 校验落盘。这样既防幻觉（工具校验），
+*    又保留整组阵容的全局视野（Agent 推理）。
+*
+* 与 audio_studio_standalone 的对应关系：
+*  - 输入结构  = tts/tools/build_character_adapter_input.py 的角色画像（主字段一致）
+*  - 硬过滤    = elevenlabs/voice-selection/tools/elevenlabs_voice_selection.py
+*                _map_gender / _map_age_filter / _filter_candidates_with_fallback
+*  - 校验      = _validate_voice_selection_plan（成员校验 + 备份补齐 + 复用检查）
+*/
+const MAX_CANDIDATES_PER_CHARACTER = 60;
+const MAX_SAMPLE_LINES = 3;
+const MAX_DESCRIPTION_CHARS = 400;
+const BACKUP_LIMIT = 2;
+const LEAD_DIALOGUE_COUNT = 200;
+const MAJOR_DIALOGUE_COUNT = 50;
+/** 性状拆分：与 standalone 的 TRAIT_SPLIT_RE 一致。 */
+const TRAIT_SPLIT_RE = /[；;、,，/|]+/;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+	if (typeof value === "string") return value.trim();
+	if (typeof value === "number") return String(value);
+	return "";
+}
+function asStringList(value) {
+	if (Array.isArray(value)) return value.map((item) => asString(item)).filter((item) => item !== "");
+	const text = asString(value);
+	return text === "" ? [] : [text];
+}
+function splitTraits(value) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const raw of asStringList(value)) for (const part of raw.split(TRAIT_SPLIT_RE)) {
+		const item = part.trim();
+		if (item !== "" && !seen.has(item)) {
+			seen.add(item);
+			out.push(item);
+		}
+	}
+	return out;
+}
+function asNumber(value) {
+	const text = asString(value);
+	if (text === "") return void 0;
+	const parsed = Number(text);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+/** 从角色名生成稳定的 character_id（缺省时自动补，与上游 char_u<hex> 风格一致）。 */
+function slugifyCharacterId(characterName, fallback) {
+	let slug = "";
+	for (const char of characterName.toLowerCase()) if (/[a-z0-9]/.test(char)) slug += char;
+	else if (char === "-" || char === "_") slug += "_";
+	else if (char.trim() !== "") slug += `${slug.endsWith("_") || slug === "" ? "" : "_"}u${char.codePointAt(0).toString(16)}`;
+	slug = slug.split("_").filter((part) => part !== "").join("_") || fallback;
+	return `char_${slug}`;
+}
+function importanceTier(dialogueCount, explicit) {
+	if (explicit === "lead" || explicit === "major" || explicit === "supporting") return explicit;
+	if (dialogueCount >= LEAD_DIALOGUE_COUNT) return "lead";
+	if (dialogueCount >= MAJOR_DIALOGUE_COUNT) return "major";
+	return "supporting";
+}
+/** 接受 JSON 数组 / 单个对象 / {characters: [...]} / JSON 字符串 → 角色剖面。 */
+function parseCharacterProfiles(input) {
+	let value = input;
+	if (typeof value === "string") {
+		const text = value.trim();
+		if (text === "") throw new AudioGenError("characters 不能为空：请传入角色画像 JSON（数组或单个对象）或 JSON 字符串", "cast-characters-empty");
+		try {
+			value = JSON.parse(text);
+		} catch {
+			throw new AudioGenError("characters 无法解析为 JSON：请先把角色信息整理成类似 [{\"character_id\": \"char_xxx\", \"character_name\": \"名字\", \"gender\": \"女性\", \"age_stage\": \"少女\", \"voice_traits\": [\"清亮\"], \"personality_traits\": [\"活泼\"], \"appearance\": [\"…\"], \"dialogue_count\": 12}] 的结构再调用", "cast-characters-parse-failed");
+		}
+	}
+	let list;
+	if (Array.isArray(value)) list = value;
+	else if (isRecord(value)) {
+		const inner = value.characters ?? value.classified_characters;
+		if (Array.isArray(inner)) list = inner;
+		else list = [value];
+	} else throw new AudioGenError("characters 必须是 JSON 数组、单个对象或 JSON 字符串", "cast-characters-invalid");
+	const profiles = [];
+	const missingNames = [];
+	list.forEach((item, index) => {
+		if (!isRecord(item)) {
+			missingNames.push(`characters[${index}] 不是对象`);
+			return;
+		}
+		const characterName = asString(item.character_name) || asString(item.name);
+		if (characterName === "") {
+			missingNames.push(`characters[${index}] 缺少 character_name`);
+			return;
+		}
+		const characterId = asString(item.character_id) || slugifyCharacterId(characterName, `r${index}`);
+		const sampleLines = (Array.isArray(item.sample_lines) ? item.sample_lines : typeof item.sample_lines === "string" ? item.sample_lines.split(/\n+/).map((line) => ({
+			text: line.trim(),
+			emotion_hint: ""
+		})) : []).filter((entry) => typeof entry === "string" || isRecord(entry)).filter((entry) => {
+			return (typeof entry === "string" ? entry.trim() : asString(entry.text) || asString(entry.dialogue)) !== "";
+		}).slice(0, MAX_SAMPLE_LINES).map((entry) => {
+			const text = typeof entry === "string" ? entry.trim() : asString(entry.text) || asString(entry.dialogue);
+			const emotion = typeof entry === "string" ? "" : asString(entry.emotion_hint) || asString(entry.emotion);
+			return {
+				text,
+				...emotion === "" ? {} : { emotion_hint: emotion }
+			};
+		});
+		profiles.push({
+			character_id: characterId,
+			character_name: characterName,
+			gender: asString(item.gender) || void 0,
+			age_stage: asStringList(item.age_stage ?? item.age),
+			...asString(item.age_stage_source) === "" ? {} : { age_stage_source: asString(item.age_stage_source) },
+			voice_traits: splitTraits(item.voice_traits),
+			personality_traits: splitTraits(item.personality_traits),
+			appearance: asStringList(item.appearance),
+			sample_lines: sampleLines,
+			dialogue_count: asNumber(item.dialogue_count),
+			importance_tier: asString(item.importance_tier) || asString(item.tier) || void 0,
+			...asString(item.language) === "" ? {} : { language: asString(item.language) },
+			...asString(item.use_case) === "" ? {} : { use_case: asString(item.use_case) }
+		});
+	});
+	if (missingNames.length > 0) throw new AudioGenError(`characters 数据不完整：${missingNames.slice(0, 5).join("；")}（请为每个角色提供 character_name）`, "cast-character-missing-name");
+	if (profiles.length === 0) throw new AudioGenError("characters 为空：请传入至少一个角色画像", "cast-characters-empty");
+	return profiles;
+}
+/** 性别归一：女/female → female；男/male → male；其余 undefined（不过滤）。 */
+function mapGender(text) {
+	const value = (text ?? "").toLowerCase();
+	if (value === "") return void 0;
+	if (value.includes("女") || value.includes("female")) return "female";
+	if (value.includes("男") || value.includes("male")) return "male";
+}
+/** 年龄段归一：老/老年→old；中年→middle_aged；少年/少女/青年/成年→young。 */
+function mapAgeFilter(ageStages) {
+	const text = (ageStages ?? []).join(" ");
+	if (text.trim() === "") return [];
+	if (text.includes("老") || text.includes("老年")) return ["old"];
+	if (text.includes("中年") || text.includes("middle")) return ["middle_aged"];
+	if (text.includes("少年") || text.includes("少女") || text.includes("少男") || text.includes("儿童") || text.includes("幼年") || text.includes("teen") || text.includes("child") || text.includes("young")) return ["young"];
+	if (text.includes("青年") || text.includes("年轻") || text.includes("成年") || text.includes("youth") || text.includes("adult")) return ["young"];
+	return [];
+}
+/** 一个角色对候选池的硬过滤（gender/age/use_case 严格，accent 可放松）。 */
+function filterCandidatesWithFallback(pool, options) {
+	const gender = options.gender;
+	const ages = options.ages ?? [];
+	const accent = options.accent;
+	const useCase = options.use_case;
+	const language = options.language;
+	const matches = (voice, checkAccent) => {
+		if (gender !== void 0 && (voice.gender ?? "").toLowerCase() !== gender.toLowerCase()) return false;
+		if (ages.length > 0 && !ages.includes((voice.age ?? "").toLowerCase())) return false;
+		if (language !== void 0 && !languageMatchesEntry(voice, language)) return false;
+		if (useCase !== void 0 && useCase !== "" && (voice.use_case ?? "").toLowerCase() !== useCase.toLowerCase()) return false;
+		if (checkAccent && accent !== void 0 && accent !== "" && (voice.accent ?? "").toLowerCase() !== accent.toLowerCase()) return false;
+		return true;
+	};
+	const strict = pool.filter((voice) => matches(voice, true));
+	const applied = [];
+	if (gender !== void 0) applied.push(`gender=${gender}`);
+	if (ages.length > 0) applied.push(`age=${ages.join("/")}`);
+	if (useCase !== void 0 && useCase !== "") applied.push(`use_case=${useCase}`);
+	if (accent !== void 0 && accent !== "") applied.push("accent");
+	if (language !== void 0 && language !== "") applied.push(`language=${language}`);
+	const appliedText = applied.join("+") === "" ? "none" : applied.join("+");
+	if (strict.length > 0) return {
+		candidates: strict,
+		relaxedAccent: false,
+		notes: `candidate_filter=${appliedText}`
+	};
+	const relaxed = pool.filter((voice) => matches(voice, false));
+	if (relaxed.length > 0) return {
+		candidates: relaxed,
+		relaxedAccent: true,
+		notes: `candidate_filter=${appliedText}；accent 已放松`
+	};
+	return {
+		candidates: [],
+		relaxedAccent: false,
+		notes: "candidate_filter=empty；严格过滤后无候选（可放宽 use_case 或换渠道）"
+	};
+}
+function languageMatchesEntry(voice, needle) {
+	const haystack = [
+		voice.language ?? "",
+		voice.locale ?? "",
+		voice.name ?? ""
+	].join(" ").toLowerCase();
+	const value = needle.trim().toLowerCase();
+	if (value === "") return true;
+	if (haystack.includes(value)) return true;
+	for (const alias of {
+		zh: [
+			"zh",
+			"chinese",
+			"mandarin",
+			"cantonese"
+		],
+		en: ["en", "english"],
+		ja: ["ja", "japanese"],
+		ko: ["ko", "korean"],
+		es: ["es", "spanish"],
+		fr: ["fr", "french"],
+		de: ["de", "german"],
+		ru: ["ru", "russian"],
+		it: ["it", "italian"],
+		pt: ["pt", "portuguese"],
+		ar: ["ar", "arabic"],
+		hi: ["hi", "hindi"]
+	}[value] ?? []) if (haystack.includes(alias)) return true;
+	return false;
+}
+function toSlimVoice(voice) {
+	const trimmed = voice.description !== void 0 && voice.description.length > MAX_DESCRIPTION_CHARS ? `${voice.description.slice(0, MAX_DESCRIPTION_CHARS - 1)}…` : voice.description;
+	return {
+		voice_id: voice.voice_id,
+		name: voice.name,
+		source: voice.source,
+		deletable: voice.deletable,
+		...voice.language === void 0 ? {} : { language: voice.language },
+		...voice.locale === void 0 ? {} : { locale: voice.locale },
+		...voice.accent === void 0 ? {} : { accent: voice.accent },
+		...voice.gender === void 0 ? {} : { gender: voice.gender },
+		...voice.age === void 0 ? {} : { age: voice.age },
+		...voice.use_case === void 0 ? {} : { use_case: voice.use_case },
+		...voice.category === void 0 ? {} : { category: voice.category },
+		...voice.labels === void 0 ? {} : { labels: voice.labels },
+		...voice.descriptive === void 0 ? {} : { descriptive: voice.descriptive },
+		...trimmed === void 0 ? {} : { description: trimmed },
+		...voice.preview_url === void 0 ? {} : { preview_url: voice.preview_url }
+	};
+}
+async function fetchPool(channel, options) {
+	if (channel.apiUrl.trim() === "") throw new AudioGenError("渠道未配置 API 地址", "audio-api-not-configured");
+	if (channel.apiKey.trim() === "") throw new AudioGenError("渠道未配置 API 密钥", "audio-api-not-configured");
+	const useCase = options.use_case !== void 0 && options.use_case !== "" ? options.use_case : void 0;
+	const result = await listVendorVoicesWithFallback(channel, {
+		limit: 500,
+		...options.language !== void 0 && options.language !== "" ? { language: options.language } : {},
+		...useCase === void 0 ? {} : { serverFilters: { use_case: useCase } }
+	});
+	return {
+		vendor: result.vendor,
+		pool: result.voices,
+		...result.note === void 0 ? {} : { note: result.note }
+	};
+}
+/** action=cast：角色画像 → 每个角色的硬过滤候选列表（不选角色，不调 LLM）。 */
+async function prepareVoiceCast(channel, profiles, options = {}) {
+	const { vendor, pool, note } = await fetchPool(channel, options);
+	const fallbackPool = pool.some((entry) => entry.source === "configured");
+	const hasMetadata = vendor !== "minimax" && !fallbackPool;
+	const views = [];
+	for (const profile of profiles) {
+		const gender = hasMetadata ? mapGender(profile.gender) : void 0;
+		const ages = hasMetadata ? mapAgeFilter(profile.age_stage) : [];
+		const language = hasMetadata ? profile.language ?? options.language : void 0;
+		const useCase = hasMetadata ? profile.use_case ?? options.use_case : void 0;
+		const accent = hasMetadata ? options.accent : void 0;
+		const dialogueCount = profile.dialogue_count ?? 0;
+		const tier = importanceTier(dialogueCount, profile.importance_tier);
+		const filtered = filterCandidatesWithFallback(pool, {
+			...gender === void 0 ? {} : { gender },
+			...ages.length > 0 ? { ages } : {},
+			...accent === void 0 || accent === "" ? {} : { accent },
+			...useCase === void 0 || useCase === "" ? {} : { use_case: useCase },
+			...language === void 0 || language === "" ? {} : { language }
+		});
+		const candidates = filtered.candidates.slice(0, MAX_CANDIDATES_PER_CHARACTER);
+		const mapped = {
+			...gender === void 0 ? {} : { gender },
+			...ages.length > 0 ? { age: ages } : {},
+			...accent === void 0 || accent === "" ? {} : { accent },
+			...useCase === void 0 || useCase === "" ? {} : { use_case: useCase },
+			...language === void 0 || language === "" ? {} : { language },
+			notes: `age_stage=${(profile.age_stage ?? []).join("/") || "unknown"}; ${filtered.notes}${vendor === "minimax" ? "；MiniMax 音色无性别/年龄/用途元数据，实际仅按语言与名称/描述筛选" : ""}`
+		};
+		const slim = {
+			character_id: profile.character_id,
+			character_name: profile.character_name,
+			dialogue_count: dialogueCount,
+			importance_tier: tier
+		};
+		if (profile.gender !== void 0) slim.gender = profile.gender;
+		if ((profile.age_stage ?? []).length > 0) slim.age_stage = profile.age_stage;
+		if (profile.age_stage_source !== void 0) slim.age_stage_source = profile.age_stage_source;
+		if ((profile.voice_traits ?? []).length > 0) slim.voice_traits = profile.voice_traits;
+		if ((profile.personality_traits ?? []).length > 0) slim.personality_traits = profile.personality_traits;
+		if ((profile.appearance ?? []).length > 0) slim.appearance = profile.appearance;
+		if ((profile.sample_lines ?? []).length > 0) slim.sample_lines = profile.sample_lines;
+		if (profile.language !== void 0) slim.language = profile.language;
+		if (profile.use_case !== void 0) slim.use_case = profile.use_case;
+		views.push({
+			character: slim,
+			mapped_filters: mapped,
+			candidate_count: candidates.length,
+			candidate_voices: candidates.map(toSlimVoice),
+			...filtered.candidates.length > candidates.length ? { note: `candidates truncated: ${filtered.candidates.length} → ${candidates.length}` } : {}
+		});
+	}
+	return {
+		vendor,
+		channel: channel.name,
+		pool_size: pool.length,
+		use_case_filter: options.use_case ?? "",
+		accent_preference: options.accent ?? "",
+		character_count: profiles.length,
+		characters: views,
+		...note === void 0 ? {} : { note }
+	};
+}
+/** action=save_cast：Agent 选角结果 → 校验 + 补齐 + 落盘（选定记录）。 */
+async function saveVoiceCast(channel, profiles, selectionInputs, options = {}) {
+	const prepared = await prepareVoiceCast(channel, profiles, options);
+	new Map(prepared.characters.map((view) => [String(view.character.character_id), view]));
+	const inputByCharacter = /* @__PURE__ */ new Map();
+	for (const input of selectionInputs) {
+		if (input === null || typeof input !== "object") continue;
+		const characterId = asString(input.character_id);
+		if (characterId !== "") inputByCharacter.set(characterId, input);
+	}
+	const entries = [];
+	const issues = [];
+	const sawReuse = /* @__PURE__ */ new Map();
+	for (const view of prepared.characters) {
+		const characterId = String(view.character.character_id ?? "");
+		const characterName = String(view.character.character_name ?? characterId);
+		const candidates = view.candidate_voices;
+		const input = inputByCharacter.get(characterId);
+		const dialogueCount = asNumber(view.character.dialogue_count) ?? 0;
+		const tier = String(view.character.importance_tier ?? importanceTier(dialogueCount));
+		let primary = asString(input?.voice_id ?? "");
+		let status = "ok";
+		const recordIssues = [];
+		if (primary === "" || !candidates.some((voice) => voice.voice_id === primary)) {
+			const fallback = candidates[0]?.voice_id ?? "";
+			if (fallback !== "") {
+				recordIssues.push("voice_id_not_in_candidates; fallback=first_candidate");
+				primary = fallback;
+				status = "tool_fallback";
+			}
+		}
+		const requiredBackupCount = Math.min(BACKUP_LIMIT, Math.max(candidates.length - 1, 0));
+		const backups = [];
+		const rawBackups = Array.isArray(input?.backup_voice_ids) ? input.backup_voice_ids : [];
+		for (const raw of rawBackups) {
+			const id = asString(raw);
+			if (id === "" || id === primary || backups.includes(id)) continue;
+			if (!candidates.some((voice) => voice.voice_id === id)) continue;
+			backups.push(id);
+			if (backups.length >= requiredBackupCount) break;
+		}
+		if (backups.length < requiredBackupCount) {
+			for (const voice of candidates) {
+				if (backups.length >= requiredBackupCount) break;
+				if (voice.voice_id === primary || backups.includes(voice.voice_id)) continue;
+				backups.push(voice.voice_id);
+			}
+			if (status === "ok") status = "fixed";
+			recordIssues.push("backup_voice_ids_auto_filled");
+		}
+		const primaryVoice = candidates.find((voice) => voice.voice_id === primary);
+		const reason = asString(input?.reason ?? "");
+		const record = {
+			character_id: characterId,
+			character_name: asString(input?.character_name) || characterName,
+			voice_id: primary,
+			voice_name: primaryVoice?.name ?? "",
+			backup_voice_ids: backups,
+			reason: reason === "" ? status === "tool_fallback" ? "tool fallback: selected from filtered candidates" : "" : reason,
+			dialogue_count: dialogueCount,
+			importance_tier: tier,
+			selection_status: status,
+			issues: recordIssues,
+			selected_at: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		entries.push(record);
+		sawReuse.set(primary, [...sawReuse.get(primary) ?? [], {
+			character_id: characterId,
+			character_name: characterName,
+			tier
+		}]);
+	}
+	for (const [voiceId, users] of sawReuse) {
+		const important = users.filter((user) => user.tier === "lead" || user.tier === "major");
+		if (important.length > 1) for (const user of important) issues.push({
+			character_id: user.character_id,
+			character_name: user.character_name,
+			issue: "primary_voice_reused",
+			detail: `主音色 ${voiceId} 被 ${important.map((item) => item.character_name).join("、")} 复用；lead/major 角色应尽量使用不同主音色`
+		});
+	}
+	const storePath = await writeCastSelections(channel, entries);
+	return {
+		vendor: prepared.vendor,
+		channel: channel.name,
+		store_path: storePath,
+		count: entries.length,
+		entries,
+		issues
+	};
+}
+function castSelectionsPath() {
+	return path.join(process.env.DSH_HOME ?? path.join(os.homedir(), ".dsh"), "dsh-audiogen", "cast-selections.json");
+}
+async function loadCastSelections() {
+	try {
+		const text = await readFile(castSelectionsPath(), "utf-8");
+		const payload = JSON.parse(text);
+		if (typeof payload === "object" && payload !== null && typeof payload.channels === "object") return payload;
+	} catch {}
+	return {
+		version: 1,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		channels: {}
+	};
+}
+/** 按渠道合并选定记录（同 character_id 覆盖），写回本地 JSON。 */
+async function writeCastSelections(channel, records) {
+	const store = await loadCastSelections();
+	const bucket = store.channels[channel.id] ?? {
+		provider: channel.preset || "custom",
+		name: channel.name,
+		updatedAt: "",
+		entries: {}
+	};
+	for (const record of records) bucket.entries[record.character_id] = record;
+	bucket.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	store.channels[channel.id] = bucket;
+	store.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const file = castSelectionsPath();
+	await mkdir(path.dirname(file), { recursive: true });
+	await writeFile(file, JSON.stringify(store, null, 2) + "\n", "utf-8");
+	return file;
+}
+//#endregion
 //#region src/agent-audio-tools.ts
 const audioRefSchema = {
 	type: "object",
@@ -3708,28 +4629,79 @@ function registerAgentAudioTools(ctx, resolve) {
 			};
 		}
 	}));
-	/** 厂商音色管理：浏览/筛选 + 删除（仅自建）。删除不可逆，必须 confirm=true。 */
+	/** 单条音色条目 schema（voices / candidate_voices 共用）。 */
+	const voiceItemSchema = {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			voice_id: {
+				type: "string",
+				required: true
+			},
+			name: {
+				type: "string",
+				required: true
+			},
+			source: {
+				type: "string",
+				required: true
+			},
+			deletable: {
+				type: "boolean",
+				required: true
+			},
+			language: { type: "string" },
+			locale: { type: "string" },
+			accent: { type: "string" },
+			gender: { type: "string" },
+			age: { type: "string" },
+			use_case: { type: "string" },
+			category: { type: "string" },
+			descriptive: { type: "string" },
+			labels: {
+				type: "object",
+				additionalProperties: true
+			},
+			description: { type: "string" },
+			preview_url: { type: "string" }
+		}
+	};
+	/** 厂商音色管理：浏览/筛选 + 按需求描述推荐 + 删除（仅自建）+ 角色选角（cast）。删除不可逆，必须 confirm=true。 */
 	const managementDisposer = ctx.tools.register(defineTool({
 		name: "manage_audio_voices",
-		description: "Manage vendor voice libraries (MiniMax / ElevenLabs). action=list: browse available TTS voices of a channel — official/shared voices plus voices designed/cloned by the account; filtering supports the official /v1/shared-voices server-side filters (search/use_case/accent/gender/age/locale/category/sort/featured/free_users_allowed/descriptive) for the ElevenLabs shared library, plus local language/keyword/source filtering everywhere; returns voice_id/name/source/description/preview_url and whether each voice is deletable. action=delete: delete one OWNED voice (custom/owned only; official/shared/system voices are read-only and refused) — irreversible, so confirm must be true (pass the exact voice_id from action=list). Use the returned voice_id with generate_audio (mode=tts, voice=<voice_id>) to speak with the selected voice.",
+		description: "Manage vendor voice libraries (MiniMax / ElevenLabs). action=list: browse available TTS voices of a channel — official/shared voices plus voices designed/cloned by the account; filtering supports the official /v1/shared-voices server-side filters (search/use_case/accent/gender/age/locale/category/sort/featured/free_users_allowed/descriptive) for the ElevenLabs shared library, plus local language/keyword/source filtering everywhere; returns voice_id/name/source/description/preview_url and whether each voice is deletable. Channels whose gateway lacks the vendor voice-library endpoints (e.g. new-api relays) automatically fall back to the configured model-alias catalog as the candidate pool (source=configured, name only). action=recommend: let the agent default model pick the top-k voices for a natural-language requirement (e.g. \"17岁清亮甜美的少女音，适合活泼女主角，英式口音\") from the same candidate pool — pass requirement (required) and optional top_k (1-10, default 5); returns ranked voices with a short reason each; voice_ids are validated against the pool (hallucinated ids are dropped). action=cast: 角色音色选角第一步 — pass characters (角色画像 JSON 数组/对象/JSON 字符串：character_id, character_name, gender 男/女, age_stage 少年/青年/中年/老年, voice_traits, personality_traits, appearance, sample_lines, dialogue_count, language, use_case) plus optional language/use_case/accent; the tool applies deterministic hard filters per character (gender/age/use_case strict; accent is a preference and is relaxed only when the strict pool is empty) and returns each character’s mapped filters + filtered candidate_voices (primary + backup slots). Then select voices globally in-context (lead/major 角色主音色不要复用), and call action=save_cast with the same characters plus selections [{character_id, voice_id, character_name?, backup_voice_ids?, reason?}] to validate membership, auto-fill backups, flag primary reuse and persist the cast plan to ~/.dsh/dsh-audiogen/cast-selections.json. action=delete: delete one OWNED voice (custom/owned only; official/shared/system voices are read-only and refused) — irreversible, so confirm must be true (pass the exact voice_id from action=list). Use the returned voice_id with generate_audio (mode=tts, voice=<voice_id>) to speak with the selected voice.",
 		parameters: {
 			action: {
 				type: "string",
-				enum: ["list", "delete"],
+				enum: [
+					"list",
+					"recommend",
+					"delete",
+					"cast",
+					"save_cast"
+				],
 				required: true,
-				description: "list = browse/filter voices; delete = remove an owned voice."
+				description: "list = browse/filter voices; recommend = pick voices for a requirement with the agent default model; cast = prepare per-character filtered candidate pools (deterministic hard filters, no LLM); save_cast = validate + persist a cast plan made in-context; delete = remove an owned voice."
 			},
 			channel: {
 				type: "string",
 				description: "Channel name or id (e.g. the channel shown in settings). Defaults to the default channel; required when more than one channel is configured."
 			},
+			characters: {
+				type: "json",
+				description: "Required for cast/save_cast: 角色画像 — JSON array of profile objects, a single profile object, or a JSON string. Each profile: character_id (optional, auto-derived from character_name), character_name (required), gender (男/女 or male/female), age_stage (少年/青年/中年/老年…, string or array), age_stage_source (explicit/appearance_inferred/unknown), voice_traits, personality_traits, appearance (string or string[]), sample_lines ([{text, emotion_hint?}] or text), dialogue_count (number), language (en/zh/ja…), use_case. Convert free-text character descriptions into this structure before calling."
+			},
+			selections: {
+				type: "json",
+				description: "Required for save_cast: the cast plan made by you — JSON array of {character_id, voice_id, character_name?, backup_voice_ids?, reason?}. voice_id must come from the cast action’s candidate_voices; the tool validates membership, fills missing backups, flags lead/major primary reuse and persists to ~/.dsh/dsh-audiogen/cast-selections.json."
+			},
 			language: {
 				type: "string",
-				description: "Filter for list: language substring (ISO code like en/zh/ja, or a label like Chinese (Mandarin))."
+				description: "Filter for list/recommend: language substring (ISO code like en/zh/ja, or a label like Chinese (Mandarin)). For cast: pool language for the candidates (per-character language overrides it)."
 			},
 			keyword: {
 				type: "string",
-				description: "Filter for list: free text over voice name/description/accent/use_case."
+				description: "Filter for list/recommend: free text over voice name/description/accent/use_case."
 			},
 			source: {
 				type: "string",
@@ -3739,7 +4711,7 @@ function registerAgentAudioTools(ctx, resolve) {
 					"owned",
 					"shared"
 				],
-				description: "Filter for list: MiniMax system/custom; ElevenLabs owned (account) / shared (community)."
+				description: "Filter for list/recommend: MiniMax system/custom; ElevenLabs owned (account) / shared (community)."
 			},
 			search: {
 				type: "string",
@@ -3747,11 +4719,11 @@ function registerAgentAudioTools(ctx, resolve) {
 			},
 			use_case: {
 				type: "string",
-				description: "Official filter: use case, e.g. characters_animation / conversational / narration / gaming (ElevenLabs shared library)."
+				description: "Official filter: use case, e.g. characters_animation / conversational / narration / gaming (ElevenLabs shared library). For cast: hard filter per character (default characters_animation for ElevenLabs; pass \"\" to disable)."
 			},
 			accent: {
 				type: "string",
-				description: "Official filter: accent, e.g. british / american / australian."
+				description: "Official filter: accent, e.g. british / american / australian. For cast: accent is a preference (strict first, relaxed when the strict pool is empty)."
 			},
 			gender: {
 				type: "string",
@@ -3791,6 +4763,14 @@ function registerAgentAudioTools(ctx, resolve) {
 				type: "boolean",
 				description: "Official filter: voices with descriptions only (true only)."
 			},
+			requirement: {
+				type: "string",
+				description: "Required for recommend: the natural-language voice requirement, e.g. \"低沉磁性的中年男声，适合沉稳旁白\"."
+			},
+			top_k: {
+				type: "integer",
+				description: "Optional for recommend: how many voices to return (1-10, default 5)."
+			},
 			voice_id: {
 				type: "string",
 				description: "Required for delete: the exact voice_id from action=list."
@@ -3813,7 +4793,13 @@ function registerAgentAudioTools(ctx, resolve) {
 					kind: {
 						type: "string",
 						required: true,
-						enum: ["list", "delete"]
+						enum: [
+							"list",
+							"recommend",
+							"delete",
+							"cast",
+							"save_cast"
+						]
 					},
 					vendor: {
 						type: "string",
@@ -3825,7 +4811,13 @@ function registerAgentAudioTools(ctx, resolve) {
 					},
 					count: { type: "integer" },
 					truncated: { type: "boolean" },
+					requirement: { type: "string" },
+					candidate_count: { type: "integer" },
 					voices: {
+						type: "array",
+						items: voiceItemSchema
+					},
+					recommendations: {
 						type: "array",
 						items: {
 							type: "object",
@@ -3848,15 +4840,199 @@ function registerAgentAudioTools(ctx, resolve) {
 									required: true
 								},
 								language: { type: "string" },
+								locale: { type: "string" },
 								accent: { type: "string" },
 								gender: { type: "string" },
 								age: { type: "string" },
 								use_case: { type: "string" },
+								category: { type: "string" },
+								descriptive: { type: "string" },
+								labels: {
+									type: "object",
+									additionalProperties: true
+								},
 								description: { type: "string" },
-								preview_url: { type: "string" }
+								preview_url: { type: "string" },
+								reason: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					pool_size: { type: "integer" },
+					use_case_filter: { type: "string" },
+					accent_preference: { type: "string" },
+					character_count: { type: "integer" },
+					characters: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								character: {
+									type: "object",
+									additionalProperties: false,
+									properties: {
+										character_id: {
+											type: "string",
+											required: true
+										},
+										character_name: {
+											type: "string",
+											required: true
+										},
+										gender: { type: "string" },
+										age_stage: {
+											type: "array",
+											items: { type: "string" }
+										},
+										age_stage_source: { type: "string" },
+										voice_traits: {
+											type: "array",
+											items: { type: "string" }
+										},
+										personality_traits: {
+											type: "array",
+											items: { type: "string" }
+										},
+										appearance: {
+											type: "array",
+											items: { type: "string" }
+										},
+										sample_lines: {
+											type: "array",
+											items: {
+												type: "object",
+												additionalProperties: false,
+												properties: {
+													text: {
+														type: "string",
+														required: true
+													},
+													emotion_hint: { type: "string" }
+												}
+											}
+										},
+										dialogue_count: {
+											type: "integer",
+											required: true
+										},
+										importance_tier: {
+											type: "string",
+											required: true
+										},
+										language: { type: "string" },
+										use_case: { type: "string" }
+									}
+								},
+								mapped_filters: {
+									type: "object",
+									additionalProperties: false,
+									properties: {
+										gender: { type: "string" },
+										age: {
+											type: "array",
+											items: { type: "string" }
+										},
+										fallback_age: {
+											type: "array",
+											items: { type: "string" }
+										},
+										accent: { type: "string" },
+										use_case: { type: "string" },
+										language: { type: "string" },
+										notes: {
+											type: "string",
+											required: true
+										}
+									}
+								},
+								candidate_count: {
+									type: "integer",
+									required: true
+								},
+								candidate_voices: {
+									type: "array",
+									required: true,
+									items: voiceItemSchema
+								},
+								note: { type: "string" }
+							}
+						}
+					},
+					selections: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								character_id: {
+									type: "string",
+									required: true
+								},
+								character_name: {
+									type: "string",
+									required: true
+								},
+								voice_id: {
+									type: "string",
+									required: true
+								},
+								voice_name: {
+									type: "string",
+									required: true
+								},
+								backup_voice_ids: {
+									type: "array",
+									items: { type: "string" },
+									required: true
+								},
+								reason: {
+									type: "string",
+									required: true
+								},
+								dialogue_count: { type: "integer" },
+								importance_tier: { type: "string" },
+								selection_status: {
+									type: "string",
+									required: true
+								},
+								issues: {
+									type: "array",
+									items: { type: "string" },
+									required: true
+								},
+								selected_at: { type: "string" }
+							}
+						}
+					},
+					issues: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								character_id: {
+									type: "string",
+									required: true
+								},
+								character_name: {
+									type: "string",
+									required: true
+								},
+								issue: {
+									type: "string",
+									required: true
+								},
+								detail: {
+									type: "string",
+									required: true
+								}
 							}
 						}
 					},
+					store_path: { type: "string" },
 					voice_id: { type: "string" },
 					deleted: { type: "boolean" },
 					message: { type: "string" },
@@ -3874,7 +5050,46 @@ function registerAgentAudioTools(ctx, resolve) {
 			const config = resolve();
 			if (!config.enabled) throw new AudioGenError("AI audio is disabled. Open Settings > Plugins > AI Audio and enable it.", "plugin-disabled");
 			const channel = resolveVoiceManagementChannel(config, args.channel);
-			if ((args.action === "delete" ? "delete" : "list") === "list") {
+			const action = args.action === "delete" ? "delete" : args.action === "recommend" ? "recommend" : args.action === "cast" ? "cast" : args.action === "save_cast" ? "save_cast" : "list";
+			if (action === "cast" || action === "save_cast") {
+				const characters = parseCharacterProfiles(args.characters);
+				const defaultUseCase = isElevenLabs$1(channel) && typeof args.use_case !== "string" ? "characters_animation" : void 0;
+				const castOptions = {
+					...typeof args.use_case === "string" ? { use_case: args.use_case.trim() } : defaultUseCase === void 0 ? {} : { use_case: defaultUseCase },
+					...typeof args.language === "string" && args.language.trim() !== "" ? { language: args.language.trim() } : {},
+					...typeof args.accent === "string" && args.accent.trim() !== "" ? { accent: args.accent.trim() } : {}
+				};
+				if (action === "cast") {
+					const prepared = await prepareVoiceCast(channel, characters, castOptions);
+					return {
+						status: "ok",
+						kind: "cast",
+						vendor: prepared.vendor,
+						channel: prepared.channel,
+						pool_size: prepared.pool_size,
+						use_case_filter: prepared.use_case_filter,
+						accent_preference: prepared.accent_preference,
+						character_count: prepared.character_count,
+						characters: prepared.characters,
+						...prepared.note === void 0 ? {} : { note: prepared.note }
+					};
+				}
+				const rawSelections = args.selections;
+				const selectionInputs = Array.isArray(rawSelections) ? rawSelections : [];
+				if (selectionInputs.length === 0) throw new AudioGenError("save_cast requires selections — an array of {character_id, voice_id, character_name?, backup_voice_ids?, reason?} matching the cast result", "cast-selections-required");
+				const saved = await saveVoiceCast(channel, characters, selectionInputs, castOptions);
+				return {
+					status: "ok",
+					kind: "save_cast",
+					vendor: saved.vendor,
+					channel: saved.channel,
+					store_path: saved.store_path,
+					count: saved.count,
+					selections: saved.entries,
+					issues: saved.issues
+				};
+			}
+			if (action === "list" || action === "recommend") {
 				const source = typeof args.source === "string" && [
 					"system",
 					"custom",
@@ -3900,12 +5115,64 @@ function registerAgentAudioTools(ctx, resolve) {
 					...args.free_users_allowed === true ? { free_users_allowed: true } : {},
 					...args.descriptive === true ? { descriptive: true } : {}
 				};
-				const result = await listVendorVoices(channel, {
+				const result = await listVendorVoicesWithFallback(channel, {
 					...typeof args.language === "string" && args.language.trim() !== "" ? { language: args.language.trim() } : {},
 					...typeof args.keyword === "string" && args.keyword.trim() !== "" ? { keyword: args.keyword.trim() } : {},
 					...source === void 0 ? {} : { source },
-					...Object.keys(serverFilters).length === 0 ? {} : { serverFilters }
+					...Object.keys(serverFilters).length === 0 ? {} : { serverFilters },
+					...action === "recommend" ? { limit: 500 } : {}
 				});
+				if (action === "recommend") {
+					const requirement = typeof args.requirement === "string" ? args.requirement.trim() : "";
+					if (requirement === "") throw new AudioGenError("recommend requires requirement (a natural-language voice description).", "recommend-requirement-required");
+					const rawTopK = args.top_k;
+					const topK = typeof rawTopK === "number" && Number.isFinite(rawTopK) ? Math.max(1, Math.min(10, Math.floor(rawTopK))) : 5;
+					if (config.recommend === void 0) throw new AudioGenError("Voice recommendation is unavailable (LLM service not wired).", "recommend-unavailable");
+					const recommendations = await config.recommend(requirement, result.voices, topK);
+					appendVoiceRecommendRecord({
+						channel: channel.name,
+						vendor: result.vendor,
+						requirement,
+						candidate_count: result.voices.length,
+						top_k: topK,
+						channel_id: channel.id,
+						filters: {
+							...typeof args.language === "string" && args.language.trim() !== "" ? { language: args.language.trim() } : {},
+							...typeof args.keyword === "string" && args.keyword.trim() !== "" ? { keyword: args.keyword.trim() } : {},
+							...source === void 0 ? {} : { source },
+							...typeof args.use_case === "string" && args.use_case.trim() !== "" ? { use_case: args.use_case.trim() } : {},
+							...typeof args.accent === "string" && args.accent.trim() !== "" ? { accent: args.accent.trim() } : {}
+						},
+						recommendations: recommendations.map((item) => ({
+							voice_id: item.voice_id,
+							name: item.name,
+							source: item.source,
+							deletable: item.deletable,
+							...item.language === void 0 ? {} : { language: item.language },
+							...item.locale === void 0 ? {} : { locale: item.locale },
+							...item.accent === void 0 ? {} : { accent: item.accent },
+							...item.gender === void 0 ? {} : { gender: item.gender },
+							...item.age === void 0 ? {} : { age: item.age },
+							...item.use_case === void 0 ? {} : { use_case: item.use_case },
+							...item.category === void 0 ? {} : { category: item.category },
+							...item.labels === void 0 ? {} : { labels: item.labels },
+							...item.descriptive === void 0 ? {} : { descriptive: item.descriptive },
+							...item.description === void 0 ? {} : { description: item.description },
+							...item.preview_url === void 0 ? {} : { preview_url: item.preview_url },
+							reason: item.reason
+						}))
+					}).catch(() => {});
+					return {
+						status: "ok",
+						kind: "recommend",
+						vendor: result.vendor,
+						channel: channel.name,
+						requirement,
+						candidate_count: result.voices.length,
+						recommendations,
+						...result.note === void 0 ? {} : { note: result.note }
+					};
+				}
 				return {
 					status: "ok",
 					kind: "list",
@@ -3989,7 +5256,7 @@ const DEFAULT_ENABLED = true;
 const DEFAULT_ANNOUNCE = true;
 const DEFAULT_ALLOW_AGENT_AUDIO = true;
 const SECTION_ORDER = 160;
-const AUDIOGEN_GUIDANCE = "本机已安装 dsh-audiogen 插件（DSH AI 音频）：侧边栏「AI 音频」入口。能力：通过「渠道」对接多个音频生成厂商（OpenAI TTS、ElevenLabs、MiniMax、Stability Audio、自定义 OpenAI 兼容接口），支持 TTS 文本转语音、音乐生成和音效生成。API 地址与密钥在 GUI 设置中按渠道配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发。Agent 可直接调用 `generate_audio` 提交 TTS/音乐/音效任务，默认等待完成并返回同源音频 URL；可用 `manage_audio_voices` 浏览/筛选/删除厂商音色（MiniMax、ElevenLabs），再用选定音色的 voice_id 调用 `generate_audio` 生成。限制：生成消耗上游 API 额度；音频内容由上游模型生成；模型只能使用用户在各渠道配置目录中的模型。用户提到「音频 / 语音 / TTS / 配乐 / 音效 / AI 音频」时即指本插件，请据此协作。";
+const AUDIOGEN_GUIDANCE = "本机已安装 dsh-audiogen 插件（DSH AI 音频）：侧边栏「AI 音频」入口。能力：通过「渠道」对接多个音频生成厂商（OpenAI TTS、ElevenLabs、MiniMax、Stability Audio、自定义 OpenAI 兼容接口），支持 TTS 文本转语音、音乐生成和音效生成。API 地址与密钥在 GUI 设置中按渠道配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发。Agent 可直接调用 `generate_audio` 提交 TTS/音乐/音效任务，默认等待完成并返回同源音频 URL；可用 `manage_audio_voices` 浏览/筛选/删除厂商音色（MiniMax、ElevenLabs），也能用该工具的 action=recommend 按自然语言需求描述（如「清亮甜美的少女音」）让默认模型推荐 top-k 音色，再用选定音色的 voice_id 调用 `generate_audio` 生成。角色音色选角（小说/游戏配音 casting）：传角色画像（JSON 数组/对象，字段 character_id/character_name/gender/age_stage/voice_traits/personality_traits/appearance/sample_lines/dialogue_count/language；文本描述需先整理成该结构）调用 `manage_audio_voices` 的 action=cast，工具按性别/年龄/用途做确定性硬过滤（accent 为偏好、候选为空才放松）并返回每个角色的候选池，你在上下文中全局权衡主音色（lead/major 不复用）+ 备用音色后，用 action=save_cast 校验落盘（~/.dsh/dsh-audiogen/cast-selections.json），随后按选定 voice_id 生成 TTS；MiniMax 也可先用 `generate_audio(mode=voice_design)` 为角色创作专属音色再选角。限制：生成消耗上游 API 额度；音频内容由上游模型生成；模型只能使用用户在各渠道配置目录中的模型；音色管理仅 MiniMax 与 ElevenLabs 渠道支持。用户提到「音频 / 语音 / TTS / 配乐 / 音效 / AI 音频」时即指本插件，请据此协作。";
 function guidanceFor(channels, defaultChannelId) {
 	if (channels.length === 0) return `${AUDIOGEN_GUIDANCE} 尚未配置任何渠道：请先在「设置 → 插件 → AI 音频」添加渠道并填写 API 地址与密钥。`;
 	const table = channels.map((channel) => {
@@ -4106,6 +5373,14 @@ function apply(ctx, config) {
 			model
 		} : void 0;
 	};
+	const recommend = async (requirement, candidates, topK) => {
+		const seam = ctx.get("settings");
+		if (seam?.describe === void 0) throw new AudioGenError("设置服务不可用，无法推荐音色", "settings-unavailable");
+		return recommendVoices({
+			settings: seam,
+			llm: () => ctx.get("llm")
+		}, requirement, candidates, topK);
+	};
 	/** 读取「设置 → 模型」目录：各提供方 + 可广播的模型列表（增强模型下拉候选）。 */
 	const llmModelOptions = async () => {
 		const llm = ctx.get("llm");
@@ -4154,6 +5429,7 @@ function apply(ctx, config) {
 				autoSave: () => resolve().autoSaveToLibrary,
 				budget,
 				enhance,
+				recommend,
 				llmModelOptions
 			}).map((route) => ctx.webServer.register(route));
 			return () => {
@@ -4171,7 +5447,8 @@ function apply(ctx, config) {
 				defaultChannelId: value.defaultChannelId,
 				autoSaveToLibrary: value.autoSaveToLibrary,
 				budget,
-				enhance
+				enhance,
+				recommend
 			};
 		}), "dsh-audiogen: agent audio tools");
 	});