dsh-audiogen 0.4.19 → 0.4.22

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-audiogen",
   "description": "AI audio generation plugin for the dsh web GUI: multi-vendor TTS/music/sound-effect channels (OpenAI-compatible, ElevenLabs, MiniMax, Stability AI and custom), per-channel model/voice catalogs, Agent tool and a sidebar AI 音频 panel.",
-  "version": "0.4.19",
+  "version": "0.4.22",
   "type": "module",
   "main": "lib/index.js",
   "exports": {

package/skills/voice-cast/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: dsh-audiogen-voice-cast
+description: 角色音色选角（casting）——把角色画像（JSON 或文本）交给 DSH AI 音频插件，manage_audio_voices 的 action=cast 做确定性硬过滤（性别/年龄/用途严格、accent 可放松）得到每个角色的候选音色池，Agent 在上下文中全局权衡主音色（lead/major 不复用）+ 备用音色，再用 action=save_cast 校验落盘并生成 TTS。当用户提到「为角色选音色 / 角色配音 / 给每个角色分配声音 / 选角 / 角色音色表 / 给小说或游戏角色挑声线」时触发。
+whenToUse: 用户有一批角色（小说/游戏/剧本），需要用 MiniMax 或 ElevenLabs 音色为每个角色分配主音色（可带备用音色），且输入可能是结构化 JSON 或自然语言文本；或想把选角结果保存下来再逐角色生成 TTS 时。
+---
+
+# 角色音色选角（dsh-audiogen voice cast）
+
+选角 = **角色画像 → 确定性硬过滤（工具）→ 全局权衡（Agent 推理）→ 校验落盘（工具）→ TTS 生成**。
+工具不做「选谁」的推理（那是本 Agent 的工作，保持整组阵容的全局视野）；工具只做可校验的过滤与防幻觉校验。
+
+## 第一步：整理输入（JSON 或文本都行，但工具只接受 JSON 结构）
+
+`manage_audio_voices` 的 `characters` 参数接受：JSON 数组 / 单个对象 / JSON 字符串。
+如果用户给的是自然语言文本（如「男主慕声，少年，声音低沉阴郁；女主慕瑶，青年，清冷……」），
+**先把它整理成下面的结构**再调用：
+
+```json
+{
+  "action": "cast",
+  "channel": "MiniMax",
+  "language": "zh",
+  "characters": [
+    {
+      "character_id": "char_musheng",
+      "character_name": "慕声",
+      "gender": "男性",
+      "age_stage": "少年",
+      "voice_traits": ["声音低沉轻柔", "冷淡"],
+      "personality_traits": ["阴郁", "狠厉", "占有欲强"],
+      "appearance": ["少年；高马尾；黑发微卷；身形单薄"],
+      "sample_lines": [{"text": "……", "emotion_hint": "冷淡"}],
+      "dialogue_count": 300
+    },
+    {
+      "character_id": "char_muyao",
+      "character_name": "慕瑶",
+      "gender": "女性",
+      "age_stage": "青年",
+      "voice_traits": ["清冽动听", "清冷"],
+      "personality_traits": ["清冷", "孤傲", "坚强"],
+      "dialogue_count": 120
+    }
+  ]
+}
+```
+
+字段说明：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `character_id` | 否 | 缺省按角色名自动生成（`char_<slug>`） |
+| `character_name` | 是 | 角色名（缺失会报 `cast-character-missing-name`） |
+| `gender` | 否 | 男/女、male/female（自动归一） |
+| `age_stage` | 否 | 少年/青年/中年/老年 或数组；可加 `age_stage_source`（explicit/appearance_inferred/unknown）表示年龄字段可信度 |
+| `voice_traits` / `personality_traits` / `appearance` | 否 | 字符串或数组，自动按 `；;、,，/|` 拆分去重 |
+| `sample_lines` | 否 | 样例台词（voice_design 的 preview_text 来源，最多 3 句） |
+| `dialogue_count` | 否 | 台词量：≥200 → lead，≥50 → major，其余 supporting（决定「主音色不复用」的约束） |
+| `language` / `use_case` | 否 | 语言（如 zh/en）与用途（如 characters_animation）；也可在工具顶层传 |
+
+## 第二步：action=cast 拿每角色的候选池（工具做确定性硬过滤）
+
+```json
+{
+  "action": "cast",
+  "channel": "ElevenLabs",
+  "language": "en",
+  "use_case": "characters_animation",
+  "accent": "british",
+  "characters": [……]
+}
+```
+
+返回每个角色的 `character`（含 `importance_tier`）、`mapped_filters`（映射后的过滤条件 + notes）与
+`candidate_voices`（每条含 voice_id/name/source/gender/age/accent/use_case/description/preview_url）。
+
+**过滤规则（与音频工作室项目一致）**：
+
+- `gender`：男→male / 女→female；映射出来后是**硬过滤**，绝不放松。
+- `age`：少年/少女/青年/成年→young；中年→middle_aged；老年→old；**硬过滤**。
+- `use_case`：**硬过滤**（ElevenLabs 默认 `characters_animation`；传 `""` 关闭）。
+- `accent`：**只是偏好**——严格候选为空时才放松（重新从全池过滤）。
+- MiniMax 系统/自建音色没有性别/年龄/用途元数据：候选池按语言（voice_id 前缀）本地过滤，
+  排名完全靠名称/描述，需要 Agent 结合声音描述判断。
+- 候选最多 60 条/角色，超限自动截断并在 `note` 标注。
+
+## 第三步：全局选角（Agent 推理，这是 LLM 的活）
+
+拿到每角色候选池后，在上下文里统一权衡（不要逐角色独立选）：
+
+1. 先看 `voice_traits`（声线质感），用 `personality_traits` 修正气质（清冷/温润/阴郁/活泼/胆怯/威严）。
+2. 用 `gender` + `age_stage` 排除明显不合的候选（注意 `age_stage_source`：explicit 时年龄是唯一依据，
+   appearance 里的年龄词只能作辅助）。
+3. 主音色要能承担长台词：清晰度、稳定音量、中性/紧张/温柔/愤怒都要可行；
+   很强"效果音"质感的只适合备用槽，除非那正是角色日常说话身份。
+4. **lead / major 角色主音色不得复用**；supporting 只有无替代候选时才可复用并在 reason 说明。
+5. 每个角色主音色 + 最多 2 个备用（`backup_voice_ids`）；`reason` 简短中文理由。
+
+## 第四步：action=save_cast 校验落盘
+
+```json
+{
+  "action": "save_cast",
+  "channel": "ElevenLabs",
+  "characters": [……同 cast……],
+  "selections": [
+    {"character_id": "char_musheng", "voice_id": "bjoUrk7s2fY9cu2u67KF", "backup_voice_ids": ["q1h5HGdnfVxp4TXTJRNN"], "reason": "低沉阴郁的少年音…"}
+  ]
+}
+```
+
+工具会：
+- 重新按相同规则算候选池，校验 `voice_id` 属于该角色候选（**编造/过期 id 会被兜底并标记 `tool_fallback`**）;
+- 自动补齐 `backup_voice_ids`（最多 2 个，不重复、不等于主音色）；
+- 检查 lead/major 主音色复用（`issues` 里给 `primary_voice_reused` 警告，需你下一轮修正后重存）；
+- 持久化到 `~/.dsh/dsh-audiogen/cast-selections.json`（按渠道 + character_id 覆盖保存）。
+
+返回 `selections`（含 `selection_status`/`issues`）与 `issues`；有 `primary_voice_reused` 时修一下再存。
+
+## 第五步：按选定音色生成 TTS
+
+```json
+{"mode": "tts", "channel": "ElevenLabs", "voice": "<voice_id>", "prompt": "对白文本"}
+```
+
+- MiniMax 的 `voice` 必须是官方 voice_id（如 `Chinese (Mandarin)_Gentleman` 或 `voice_xxx`）。
+- 若字符没有合适现成音色，先用 **voice_design 创作专属音色**（见 dsh-audiogen-voice-design 技能）：
+
+```json
+{"mode": "voice_design", "prompt": "一位清冷孤傲却带柔情的青年女声，音色清冽，气质疏离……", "preview_text": "从 sample_lines 里选一句，或写一句自然对白"}
+```
+
+  生成的 `voiceId` 可直接作为该角色的主音色 `voice_id` 写入 save_cast。
+
+## 常见错误
+
+- `cast-characters-parse-failed`：characters 不是合法 JSON → 先整理成数组/对象再调用。
+- `cast-character-missing-name`：某个角色缺 `character_name`。
+- `cast-selections-required`：save_cast 忘了传 `selections`。
+- `character_count=0` 或显示候选为空：检查语言/use_case 太严（use_case 传 `""` 再试），或渠道网关不支持音色库。
+- `channel-choice-required`：多渠道未指定 → 显式传 `channel`（如 "ElevenLabs"）。
+- 候选池只有 shared/system（只读）没关系：cast 只需要 voice_id，生成时照常可用。
+- 网关渠道无音色库端点时：cast 候选池会回退为该渠道配置的音色目录（`source=渠道模型`，无性别/年龄
+  元数据），此时硬过滤不适用，只能按名称/描述判断；需要完整候选池请配置官方 API 地址的渠道。
+
+## 与推荐的区别
+
+- `action=recommend`：一句需求文本（如「17岁清亮甜美少女音」）→ 插件 LLM 给 top-k，
+  适合**单个声线的快速推荐**（无角色结构）。
+- `action=cast` + `save_cast`：**整组角色** → 工具硬过滤 + Agent 全局选角 + 校验落盘，
+  适合**小说/游戏配音的正式选角**（JSON 或文本角色清单）。

package/skills/voice-management/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dsh-audiogen-voice-management
-description: 浏览/筛选/删除厂商音色库（MiniMax、ElevenLabs）并复用选定音色生成 TTS。当用户提到「音色管理 / 音色列表 / 查看有哪些音色 / 删除音色 / 筛选音色 / 用某个音色 TTS / 声音列表」时触发。与资源库（本地生成结果）无关，请勿混淆。
-whenToUse: 需要查看某个渠道（MiniMax / ElevenLabs）有哪些可用音色、按语言/关键词筛选音色、删除某个自建音色，或拿到音色 voice_id 后用它生成语音时。
+description: 浏览/筛选/删除厂商音色库（MiniMax、ElevenLabs）并按需求描述（prompt）推荐音色，复用选定音色生成 TTS。当用户提到「音色管理 / 音色列表 / 查看有哪些音色 / 删除音色 / 筛选音色 / 推荐音色 / 选个合适的音色 / 用某个音色 TTS / 声音列表」时触发。与资源库（本地生成结果）无关，请勿混淆。
+whenToUse: 需要查看某个渠道（MiniMax / ElevenLabs）有哪些可用音色、按语言/关键词筛选音色、按一段描述（如「清亮甜美的少女音」）让模型推荐音色、删除某个自建音色，或拿到音色 voice_id 后用它生成语音时。
 ---
 
 # 厂商音色管理（dsh-audiogen）
@@ -45,6 +45,19 @@ whenToUse: 需要查看某个渠道（MiniMax / ElevenLabs）有哪些可用音
 
 这些参数只对 ElevenLabs 共享库起作用（服务端筛选），自有音色与其他渠道按同名字段本地兜底；MiniMax 无服务端筛选端点，会在返回 `note` 中说明。
 
+## 按需求描述推荐音色（action=recommend）
+
+```json
+{"action": "recommend", "channel": "ElevenLabs", "language": "en", "requirement": "17岁清亮甜美的少女音，适合活泼女主角，英式口音", "top_k": 5}
+```
+
+- `requirement`（必填）：自然语言需求描述。模型按语言/性别/年龄感/气质/用途综合打分。
+- `top_k`：推荐条数（1-10，默认 5）。
+- 候选池 = 当前渠道 + 传入的筛选条件（language/keyword/source + 共享库服务端参数），默认拉宽到上限 500 条；结果中的 `voice_id` 均校验为候选池真实成员（模型编造的 id 会被丢弃）。
+- 返回 `recommendations`：每条含 `voice_id` / `name` / `source` / `deletable` / `preview_url` 等音色字段 + `reason`（中文推荐理由）。
+- 机制：复用 Agent 默认模型（「设置 → 模型」的 agent-default-model），**不新增 API key**；模型未配置时提示先设置默认模型。
+- 推荐后再 `generate_audio(mode="tts", voice="<voice_id>")` 闭环生成。
+
 ## 删除音色（action=delete）
 
 ```json
@@ -64,5 +77,27 @@ MiniMax TTS 的 `voice` 参数需要官方 voice_id；ElevenLabs 的 `voice` 参
 ## 常见错误
 
 - `channel-choice-required`：多个渠道未指定 → 先 `manage_audio_voices(list, channel=...)` 或询问用户。
+- `recommend-requirement-required`：推荐时缺 `requirement` → 补上自然语言描述。
+- `recommend-no-candidates`：候选池为空 → 确认渠道音色库可用，或放宽筛选。
+- `recommend-parse-failed`：模型返回的推荐未命中候选池 → 重试，或用语言/关键词先缩小候选集。
 - 删除被拒（`system`/`shared` 只读）：换个 `source=custom`/`owned` 的音色。
 - 拉取失败：渠道 API 地址/密钥错误，或网关不支持音色管理端点（Stability、自定义 OpenAI 兼容渠道无此能力，会明确提示不支持）。
+- 网关渠道（如 new-api 中转站）未映射 ElevenLabs 的 `/v1/voices`、`/v1/shared-voices`：列表与 AI 推荐会**自动回退**
+  为该渠道「配置的音色目录」（`source=渠道模型`，只有名称、无试听/语言/性别/年龄元数据），仍可推荐与生成；
+  需要完整音色库（试听、描述、性别年龄筛选）时请添加一个官方 API 地址（https://api.elevenlabs.io）的渠道。
+
+## 角色选角（多角色分配音色）
+
+上面是「一个需求 → 一个音色」。如果用户有一整组角色（小说/游戏配音）要为每个角色分配
+主音色（+备用音色），使用工具的 **action=cast / action=save_cast** 两个动作：
+
+1. `action=cast`：传 `characters`（角色画像 JSON 数组/对象，含 character_name/gender/age_stage/
+   voice_traits/personality_traits/appearance/sample_lines/dialogue_count），工具按性别/年龄/用途做
+   确定性硬过滤（accent 为偏好、候选为空才放松），返回每个角色的候选池。
+2. Agent 在上下文中全局选角（lead/major 角色主音色不要复用；每角色主音色 + 最多 2 个备用）。
+3. `action=save_cast`：传同样的 `characters` + `selections`，工具校验 voice_id 属于候选池、
+   补齐备份、标记复用警告并持久化到 `~/.dsh/dsh-audiogen/cast-selections.json`。
+4. 用选定 `voice_id` 调 `generate_audio` 生成 TTS；无合适音色时先用
+   `generate_audio(mode="voice_design")` 创作专属音色。
+
+完整流程、输入结构示例与约束见 **dsh-audiogen-voice-cast** 技能。

package/src/agent-audio-tools.ts

@@ -12,9 +12,19 @@ import { generateAudio, AudioGenError } from './audio-engine.ts'
 import type { GenerationBudget } from './audio-scheduler.ts'
 import { appendHistory, saveAudioFile, saveToLibrary, listLibrary } from './audio-store.ts'
 import {
-  listVendorVoices,
+  listVendorVoicesWithFallback,
   deleteVendorVoice,
+  isElevenLabs,
+  type VendorVoiceEntry,
 } from './voice-manager.ts'
+import type { VoiceRecommendation } from './voice-recommend.ts'
+import { appendVoiceRecommendRecord } from './voice-recommend.ts'
+import {
+  parseCharacterProfiles,
+  prepareVoiceCast,
+  saveVoiceCast,
+  type CastSelectionInput,
+} from './voice-cast.ts'
 import type { AudioMode, GenerateAudioRequest, LibraryType } from './protocol.ts'
 
 export interface AgentAudioToolConfig {
@@ -27,6 +37,8 @@ export interface AgentAudioToolConfig {
   budget?: GenerationBudget
   /** 提示词增强（复用 Agent 默认模型）；enhance_prompt=true 时在生成前调用。 */
   enhance?: (prompt: string, mode: AudioMode) => Promise<string>
+  /** 音色推荐（复用 Agent 默认模型）：需求描述 + 候选池 → top-k 推荐。 */
+  recommend?: (requirement: string, candidates: VendorVoiceEntry[], topK: number) => Promise<VoiceRecommendation[]>
 }
 
 interface AgentAudioRef {
@@ -553,19 +565,44 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
     },
   }))
 
-  /** 厂商音色管理：浏览/筛选 + 删除（仅自建）。删除不可逆，必须 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' },
+    },
+  } as const
+
+  /** 厂商音色管理：浏览/筛选 + 按需求描述推荐 + 删除（仅自建）+ 角色选角（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\u2019s 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'], required: true, description: 'list = browse/filter voices; delete = remove an owned voice.' },
+      action: { type: 'string', enum: ['list', 'recommend', 'delete', 'cast', 'save_cast'], required: true, 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.' },
-      language: { type: 'string', description: 'Filter for list: language substring (ISO code like en/zh/ja, or a label like Chinese (Mandarin)).' },
-      keyword: { type: 'string', description: 'Filter for list: free text over voice name/description/accent/use_case.' },
-      source: { type: 'string', enum: ['system', 'custom', 'owned', 'shared'], description: 'Filter for list: MiniMax system/custom; ElevenLabs owned (account) / shared (community).' },
+      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\u2019s 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/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/recommend: free text over voice name/description/accent/use_case.' },
+      source: { type: 'string', enum: ['system', 'custom', 'owned', 'shared'], description: 'Filter for list/recommend: MiniMax system/custom; ElevenLabs owned (account) / shared (community).' },
       search: { type: 'string', description: 'Official /v1/shared-voices filter: free-text search over the ElevenLabs shared voice library (ElevenLabs only; local fallback elsewhere).' },
-      use_case: { type: 'string', description: 'Official filter: use case, e.g. characters_animation / conversational / narration / gaming (ElevenLabs shared library).' },
-      accent: { type: 'string', description: 'Official filter: accent, e.g. british / american / australian.' },
+      use_case: { type: 'string', 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. For cast: accent is a preference (strict first, relaxed when the strict pool is empty).' },
       gender: { type: 'string', description: 'Official filter: male / female.' },
       age: { type: 'string', description: 'Official filter: age bracket, e.g. adult / young / middle_aged.' },
       locale: { type: 'string', description: 'Official filter: language locale, e.g. en-us / en-gb.' },
@@ -574,6 +611,8 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
       featured: { type: 'boolean', description: 'Official filter: featured shared voices only (true only).' },
       free_users_allowed: { type: 'boolean', description: 'Official filter: voices allowed for free users only (true only).' },
       descriptive: { 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.' },
       confirm: { type: 'boolean', description: 'Required for delete: must be true; deletion is irreversible.' },
     },
@@ -583,12 +622,18 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
         additionalProperties: false,
         properties: {
           status: { type: 'string', required: true, enum: ['ok'] },
-          kind: { type: 'string', required: true, enum: ['list', 'delete'] },
+          kind: { type: 'string', required: true, enum: ['list', 'recommend', 'delete', 'cast', 'save_cast'] },
           vendor: { type: 'string', required: true },
           channel: { type: 'string', required: true },
           count: { type: 'integer' },
           truncated: { type: 'boolean' },
+          requirement: { type: 'string' },
+          candidate_count: { type: 'integer' },
           voices: {
+            type: 'array',
+            items: voiceItemSchema,
+          },
+          recommendations: {
             type: 'array',
             items: {
               type: 'object',
@@ -599,15 +644,113 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
                 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' },
+                reason: { type: 'string', required: true },
+              },
+            },
+          },
+          // ---- cast / save_cast ----
+          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' },
@@ -624,8 +767,57 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
         throw new AudioGenError('AI audio is disabled. Open Settings > Plugins > AI Audio and enable it.', 'plugin-disabled')
       }
       const channel = resolveVoiceManagementChannel(config, args.channel)
-      const action = args.action === 'delete' ? 'delete' : 'list'
-      if (action === 'list') {
+      const action = args.action === 'delete' ? 'delete'
+        : args.action === 'recommend' ? 'recommend'
+          : args.action === 'cast' ? 'cast'
+            : args.action === 'save_cast' ? 'save_cast'
+              : 'list'
+      // ---- 角色选角：先过滤（cast），后校验落盘（save_cast）——LLM 推理在中间由 Agent 完成。 ----
+      if (action === 'cast' || action === 'save_cast') {
+        const characters = parseCharacterProfiles(args.characters)
+        // ElevenLabs 选角默认硬过滤用途 characters_animation（传 "" 可关闭）；accent 仅是偏好。
+        const defaultUseCase = isElevenLabs(channel) && typeof args.use_case !== 'string' ? 'characters_animation' : undefined
+        const castOptions = {
+          ...(typeof args.use_case === 'string' ? { use_case: args.use_case.trim() } : defaultUseCase === undefined ? {} : { 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' as const,
+            kind: 'cast' as const,
+            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 === undefined ? {} : { note: prepared.note }),
+          }
+        }
+        const rawSelections = args.selections
+        const selectionInputs: CastSelectionInput[] = Array.isArray(rawSelections) ? rawSelections as unknown as CastSelectionInput[] : []
+        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' as const,
+          kind: 'save_cast' as const,
+          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', 'owned', 'shared'].includes(args.source) ? args.source : undefined
         const pick = (value: unknown): string | undefined => typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
         const serverFilters = {
@@ -641,12 +833,68 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
           ...(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 === undefined ? {} : { source }),
           ...(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 === undefined) throw new AudioGenError('Voice recommendation is unavailable (LLM service not wired).', 'recommend-unavailable')
+          const recommendations = await config.recommend(requirement, result.voices, topK)
+          // 与面板共用同一份推荐记录（最近 50 条，失败不影响结果）。
+          void 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 === undefined ? {} : { 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 === undefined ? {} : { language: item.language }),
+              ...(item.locale === undefined ? {} : { locale: item.locale }),
+              ...(item.accent === undefined ? {} : { accent: item.accent }),
+              ...(item.gender === undefined ? {} : { gender: item.gender }),
+              ...(item.age === undefined ? {} : { age: item.age }),
+              ...(item.use_case === undefined ? {} : { use_case: item.use_case }),
+              ...(item.category === undefined ? {} : { category: item.category }),
+              ...(item.labels === undefined ? {} : { labels: item.labels }),
+              ...(item.descriptive === undefined ? {} : { descriptive: item.descriptive }),
+              ...(item.description === undefined ? {} : { description: item.description }),
+              ...(item.preview_url === undefined ? {} : { preview_url: item.preview_url }),
+              reason: item.reason,
+            })),
+          }).catch(() => { /* best-effort */ })
+          return {
+            status: 'ok' as const,
+            kind: 'recommend' as const,
+            vendor: result.vendor,
+            channel: channel.name,
+            requirement,
+            candidate_count: result.voices.length,
+            recommendations,
+            ...(result.note === undefined ? {} : { note: result.note }),
+          }
+        }
         return {
           status: 'ok' as const,
           kind: 'list' as const,

package/src/client/AudioGenPanel.tsx

@@ -67,7 +67,7 @@ export function AudioGenPanel(props: { api: AudiogenApi; scope: AudiogenScope })
             data-active={tab === 'voices' ? 'true' : 'false'}
             onClick={() => setTab('voices')}
           >
-            <MicIcon /> {tt('tab.voices')}
+            <MicIcon /> 音色管理
           </button>
         </div>
       </header>