dsh-audiogen 0.3.5 → 0.4.1

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.3.5",
+  "version": "0.4.1",
   "type": "module",
   "main": "lib/index.js",
   "exports": {

package/skills/design/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: dsh-audiogen-voice-design
+description: DSH AI 音频插件（dsh-audiogen）的音色设计技能：调用 generate_audio(mode=voice_design) 并指定厂商/渠道——MiniMax（POST /v1/voice_design，prompt + preview_text）或 ElevenLabs（POST /v1/text-to-voice/design，voice_description + 试听文本 100-1000 字符，过短自动生成；返回 previews[].audio_base_64 与 generated_voice_id 供后续 TTS 复用）。
+whenToUse: 用户请求设计/创建新音色、音色试听，或触发 /audio:design 时使用。
+---
 # 音色/音效设计
 
 ## 触发

package/skills/music/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: dsh-audiogen-music
+description: DSH AI 音频插件（dsh-audiogen）的音乐生成技能：调用 generate_audio(mode=music)；覆盖 MiniMax（music-3.0/2.6/cover，lyrics 歌词、is_instrumental 纯音乐、audio_setting 采样率 16000-44100/码率 32000-256000/格式 mp3-wav-pcm、时长）、ElevenLabs（/v1/music，music_v2，时长 3-600s、lyrics_text、force_instrumental）与 Stability（stable-audio 2/2.5/3，官方 v2beta 或 OpenAI 兼容 /v1/audio/speech 双通道，seed/steps/cfg_scale/duration）。
+whenToUse: 用户请求生成音乐、配乐、BGM、纯音乐、歌曲，或触发 /audio:music 时使用；MiniMax 未给歌词且未要求纯音乐时，先补一段歌词或设置 is_instrumental。
+---
 # 音乐生成
 
 ## 触发
@@ -50,3 +55,27 @@
 | seed / generation_mode / finetune_* | — | 高级字段，暂未透出 |
 
 > 响应为音频字节流（audio/*，常为 mp3）。请求同时携带 `xi-api-key` 与 `Authorization: Bearer`，以兼容 New API 类网关（官方站任一头即可）。
+
+## Stability Stable Audio（官方 v2beta，multipart/form-data）
+
+官方端点（文本到音频，TTS 描述 / 音乐 / 音效统一走该接口，不同模型参数不同）：
+- `POST /v2beta/audio/stable-audio/text-to-audio` → 模型 `stable-audio-3`（202 异步，随后轮询 GET /v2beta/audio/results/{id}）
+- `POST /v2beta/audio/stable-audio-2/text-to-audio` → 模型 `stable-audio-2` / `stable-audio-2.5`（同步返回音频）
+
+| 字段 | 工具/面板参数 | 说明 |
+| --- | --- | --- |
+| prompt | prompt | 必填，描述性提示词（乐器/情绪/风格/体裁，≤10000 字符） |
+| model | model | stable-audio-3 / stable-audio-2.5 / stable-audio-2 |
+| duration | duration | 秒数：3 ≤380（默认 190）；2/2.5 ≤190（默认 190） |
+| seed | seed | 0-4294967294，默认 0=随机；同参数同 seed 可复现 |
+| steps | steps | 采样步数：2 → 30-100（默认 50）；2.5/3 → 4-8（默认 8） |
+| cfg_scale | cfg_scale | 1-25：2 默认 7，2.5/3 默认 1；越高越贴提示词 |
+| output_format | format | mp3 / wav |
+
+> 引擎按模型自动收敛步数/时长区间；渠道 preset/apiUrl 含 `stability` 或模型名以 `stable-audio-` 开头即走官方协议（自定义渠道同样适用）。
+
+### 双通道（自动选择）
+- **官方 v2beta**：apiUrl 为 `https://api.stability.ai`（含 `/v2beta`、`/v2beta/audio` 形态）→ multipart 原生端点（2/2.5 同步、3 异步轮询）。
+- **OpenAI 兼容网关**：apiUrl 以 `/v1` 结尾或含 `/audio/speech`（如 New API）→ `POST {apiUrl}/audio/speech`，JSON：
+  `{ "model": "stable-audio-2.5", "input": "<prompt>", "output_format": "mp3", "duration": 30, "seed": 0, "steps": 8, "cfg_scale": 1 }`（网关把该模型映射到 Stable 上游）。
+- 一方返回 `404 Invalid URL`（未路由）时自动换另一方重试；参数在两种通道均按模型收敛（duration/seed/steps/cfg_scale/output_format）。

package/skills/sfx/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: dsh-audiogen-sfx
+description: DSH AI 音频插件（dsh-audiogen）的音效生成技能：调用 generate_audio(mode=sfx)；覆盖 ElevenLabs（/v1/sound-generation，eleven_text_to_sound_v2，loop 无缝循环、prompt_influence 0-1、duration_seconds 0.5-30）与 MiniMax、Stability 等渠道的对应字段与常见错误处理。
+whenToUse: 用户请求生成音效、提示音、环境音、UI 音，或触发 /audio:sfx 时使用。
+---
 # 音效生成
 
 ## 触发

package/skills/tts/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: dsh-audiogen-tts
+description: DSH AI 音频插件（dsh-audiogen）的 TTS 文本转语音技能：先确认渠道/模型/音色，再调用 generate_audio(mode=tts)；包含 MiniMax 官方 t2a_v2 全字段（语速/音量/音调/情绪/采样率/码率/声道/发音词典/字幕/变声/双音色混合）、ElevenLabs 与 Stable Audio 的对应参数说明，以及常见错误（voice-required、网关 404 Invalid URL 等）的处理。
+whenToUse: 用户提出朗读、配音、语音合成、TTS，或触发 /audio:tts 时使用；MiniMax 必须提供音色 voice_id。
+---
 # TTS 文本转语音
 
 ## 触发

package/src/agent-audio-tools.ts

@@ -9,14 +9,15 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { randomUUID } from 'node:crypto'
 import type { AudioChannel } from './audio-engine.ts'
 import { generateAudio, AudioGenError } from './audio-engine.ts'
-import { appendHistory, saveAudioFile } from './audio-store.ts'
-import type { AudioMode, GenerateAudioRequest } from './protocol.ts'
+import { appendHistory, saveAudioFile, saveToLibrary, listLibrary } from './audio-store.ts'
+import type { AudioMode, GenerateAudioRequest, LibraryType } from './protocol.ts'
 
 export interface AgentAudioToolConfig {
   enabled: boolean
   allowAgentAudioGeneration: boolean
   channels: AudioChannel[]
   defaultChannelId: string
+  autoSaveToLibrary: boolean
 }
 
 interface AgentAudioRef {
@@ -27,12 +28,29 @@ interface AgentAudioRef {
   voiceId?: string
 }
 
+/** Internal: the persisted file name, needed for library copies. */
+interface SavedAudioRef extends AgentAudioRef {
+  file: string
+}
+
+/** Per-model group in a multi-model comparison result. */
+interface AgentAudioGroup {
+  model: string
+  audio: AgentAudioRef[]
+  resources?: string[]
+  error?: string
+}
+
 interface AgentAudioResult {
   status: string
   message: string
   mode: AudioMode
   model: string
   audio: AgentAudioRef[]
+  /** Resource-library entry ids when the audio was saved to the library. */
+  resources?: string[]
+  /** Per-model results when several models were generated with the same prompt. */
+  groups?: AgentAudioGroup[]
   error?: string
 }
 
@@ -48,6 +66,17 @@ const audioRefSchema = {
   },
 } as const
 
+const groupSchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    model: { type: 'string', required: true },
+    audio: { type: 'array', required: true, items: audioRefSchema },
+    resources: { type: 'array', items: { type: 'string' } },
+    error: { type: 'string' },
+  },
+} as const
+
 const resultSchema = {
   type: 'object',
   additionalProperties: false,
@@ -57,6 +86,8 @@ const resultSchema = {
     mode: { type: 'string', required: true, enum: ['tts', 'music', 'sfx', 'voice_design'] },
     model: { type: 'string', required: true },
     audio: { type: 'array', required: true, items: audioRefSchema },
+    resources: { type: 'array', items: { type: 'string' } },
+    groups: { type: 'array', items: groupSchema },
     error: { type: 'string' },
   },
 } as const
@@ -96,15 +127,31 @@ function ensureConfigured(config: AgentAudioToolConfig): void {
   if (!usable) throw new AudioGenError('Audio API credentials are not configured. Open Settings > Plugins > AI Audio, add a channel and fill its API URL and API key.', 'audio-api-not-configured')
 }
 
+/** Library type from the generation mode, with an explicit override. */
+function libraryTypeOf(mode: AudioMode, override: unknown): LibraryType {
+  if (override === 'voice' || override === 'music' || override === 'sfx' || override === 'tts') return override
+  if (mode === 'voice_design') return 'voice'
+  return mode
+}
+
 /** Register the Agent audio tool. */
 export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioToolConfig): () => void {
   const disposer = ctx.tools.register(defineTool({
-    name: 'generate_audio',
-    description: 'Generate audio with the configured audio provider. Supports text-to-speech, music generation, sound effects and voice design (MiniMax /v1/voice_design, ElevenLabs /v1/text-to-voice/design). The tool call waits for the upstream result and returns same-origin audio URLs; pass those URLs to the user for playback or download. If multiple models are configured, first ask the user which one to use or pass model explicitly.',
+    name: 'generate_audio',    description: 'Generate audio with the configured audio provider. Supports text-to-speech, music generation, sound effects and voice design (MiniMax /v1/voice_design, ElevenLabs /v1/text-to-voice/design). The tool call waits for the upstream result and returns same-origin audio URLs; pass those URLs to the user for playback or download. If multiple models are configured, first ask the user which one to use or pass model explicitly.',
     parameters: {
       prompt: { type: 'string', required: true, description: 'For tts, the text to speak. For music/sfx, a descriptive prompt.' },
       mode: { type: 'string', enum: ['tts', 'music', 'sfx', 'voice_design'], description: 'Generation mode. Defaults to tts.' },
       model: { type: 'string', description: 'One of the configured audio models/voices. Defaults to the first configured model.' },
+      models: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Optional: several configured model aliases to generate the SAME prompt with each one, sequentially, for comparison (e.g. ["speech-2.8-hd","speech-2.6-hd"]). Cannot be combined with model; when present, models wins.',
+      },
+      model_params: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Optional per-model parameter overrides used with "models" (automatic by default = all models share the global params). Keys are model aliases; values are partial param objects using the same param names (format, duration, voice, speed, emotion, vol, pitch, sample_rate, bitrate, lyrics, is_instrumental, loop, prompt_influence, seed, steps, cfg_scale, subtitle_enable, aigc_watermark, language_boost, pronunciation_tone, voice_modify, timbre_weights). Unset fields fall back to the global values.',
+      },
       voice: { type: 'string', description: 'Optional voice id/name for TTS providers. Required for MiniMax TTS (e.g. male-qn-qingse, female-shaonv); fetch the account voices in Settings > Plugins > AI Audio.' },
       preview_text: { type: 'string', description: 'Optional preview text for voice_design.' },
       speed: { type: 'number', description: 'Optional speaking rate / speed multiplier where supported. MiniMax range 0.5-2.0 (default 1).' },
@@ -113,6 +160,9 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
       is_instrumental: { type: 'boolean', description: 'Generate purely instrumental music without vocals/lyrics (MiniMax is_instrumental). When true, lyrics may be omitted.' },
       loop: { type: 'boolean', description: 'Create a seamlessly looping sound effect (ElevenLabs sound generation loop, only for eleven_text_to_sound_v2).' },
       prompt_influence: { type: 'number', description: 'Sound effect prompt influence 0-1 (ElevenLabs prompt_influence, default 0.3): higher follows the prompt more closely, lower is more variable.' },
+      seed: { type: 'integer', description: 'Stable Audio random seed 0-4294967294 (default 0 = random); same seed yields reproducible audio.' },
+      steps: { type: 'integer', description: 'Stable Audio sampling steps, model-dependent: stable-audio-2 30-100, stable-audio-2.5/3 4-8 (out-of-range auto-clamped).' },
+      cfg_scale: { type: 'number', description: 'Stable Audio prompt adherence 1-25 (stable-audio-2 default 7, 2.5/3 default 1); higher follows the prompt more strictly.' },
       format: { type: 'string', description: 'Output format such as mp3 or wav. MiniMax music supports mp3/wav/pcm.' },
       // ---- MiniMax TTS only (ignored by other providers) ----
       emotion: { type: 'string', description: 'MiniMax TTS emotion, e.g. happy/sad/angry/nervous/fearful/bored (voice_setting.emotion).' },
@@ -145,13 +195,17 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
           type: 'object',
           additionalProperties: false,
           properties: {
-            voice_id: { type: 'string' },
-            weight: { type: 'integer' },
+            voice_id: { type: 'string', required: true },
+            weight: { type: 'integer', required: true },
           },
-          required: ['voice_id', 'weight'],
         },
         description: 'MiniMax TTS dual-voice blend weights (timbre_weights).',
       },
+      // ---- resource library ----
+      save_to_library: { type: 'boolean', description: 'Save the generated audio into the local resource library after success. Also enabled globally by the "auto save to library" setting; pass false to skip a single run.' },
+      library_name: { type: 'string', description: 'Resource name in the library. Defaults to the prompt.' },
+      library_type: { type: 'string', enum: ['voice', 'music', 'sfx', 'tts'], description: 'Resource type in the library. Defaults to the generation mode (voice_design → voice).' },
+      library_tags: { type: 'array', items: { type: 'string' }, description: 'Tags for the library resource.' },
     },
     output: {
       schema: resultSchema,
@@ -162,7 +216,218 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
     async execute(args, exec) {
       const config = resolve()
       ensureConfigured(config)
-      const mode = args.mode === 'music' ? 'music' : args.mode === 'sfx' ? 'sfx' : args.mode === 'voice_design' ? 'voice_design' : 'tts'
+      const mode: AudioMode = args.mode === 'music' ? 'music' : args.mode === 'sfx' ? 'sfx' : args.mode === 'voice_design' ? 'voice_design' : 'tts'
+      /** 把生成参数（snake_case 入参或 model_params 片段）映射为请求字段。 */
+      const mapParams = (raw: Record<string, unknown>): Partial<GenerateAudioRequest> => {
+        const voiceModify = typeof raw.voice_modify === 'object' && raw.voice_modify !== null
+          ? (() => {
+            const src = raw.voice_modify as Record<string, unknown>
+            const out: { pitch?: number; intensity?: number; timbre?: number; soundEffects?: string } = {}
+            if (typeof src.pitch === 'number') out.pitch = src.pitch
+            if (typeof src.intensity === 'number') out.intensity = src.intensity
+            if (typeof src.timbre === 'number') out.timbre = src.timbre
+            if (typeof src.sound_effects === 'string' && src.sound_effects.trim() !== '') out.soundEffects = src.sound_effects.trim()
+            return Object.keys(out).length > 0 ? out : undefined
+          })()
+          : undefined
+        const timbreWeights = Array.isArray(raw.timbre_weights)
+          ? raw.timbre_weights
+            .filter((item): item is { voice_id: string; weight: number } => typeof item === 'object' && item !== null && typeof (item as { voice_id?: unknown }).voice_id === 'string' && typeof (item as { weight?: unknown }).weight === 'number')
+            .map(item => ({ voiceId: (item.voice_id as string).trim(), weight: item.weight as number }))
+            .filter(item => item.voiceId !== '')
+          : undefined
+        const stringOrEmpty = (key: string): string | undefined => {
+          const value = raw[key]
+          return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+        }
+        const finiteOrUndefined = (key: string): number | undefined => {
+          const value = raw[key]
+          return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+        }
+        return {
+          ...(stringOrEmpty('voice') !== undefined ? { voice: stringOrEmpty('voice')! } : {}),
+          ...(stringOrEmpty('preview_text') !== undefined ? { previewText: stringOrEmpty('preview_text')! } : {}),
+          ...(finiteOrUndefined('speed') !== undefined ? { speed: finiteOrUndefined('speed')! } : {}),
+          ...(finiteOrUndefined('duration') !== undefined ? { duration: finiteOrUndefined('duration')! } : {}),
+          ...(stringOrEmpty('lyrics') !== undefined ? { lyrics: stringOrEmpty('lyrics')! } : {}),
+          ...(typeof raw.is_instrumental === 'boolean' ? { isInstrumental: raw.is_instrumental } : {}),
+          ...(typeof raw.loop === 'boolean' ? { loop: raw.loop } : {}),
+          ...(finiteOrUndefined('prompt_influence') !== undefined ? { promptInfluence: finiteOrUndefined('prompt_influence')! } : {}),
+          ...(finiteOrUndefined('seed') !== undefined ? { seed: finiteOrUndefined('seed')! } : {}),
+          ...(finiteOrUndefined('steps') !== undefined ? { steps: finiteOrUndefined('steps')! } : {}),
+          ...(finiteOrUndefined('cfg_scale') !== undefined ? { cfgScale: finiteOrUndefined('cfg_scale')! } : {}),
+          ...(stringOrEmpty('format') !== undefined ? { format: stringOrEmpty('format')! } : {}),
+          // ---- MiniMax / ElevenLabs / Stability 专属字段 ----
+          ...(stringOrEmpty('emotion') !== undefined ? { emotion: stringOrEmpty('emotion')! } : {}),
+          ...(finiteOrUndefined('vol') !== undefined ? { vol: finiteOrUndefined('vol')! } : {}),
+          ...(finiteOrUndefined('pitch') !== undefined ? { pitch: finiteOrUndefined('pitch')! } : {}),
+          ...(typeof raw.text_normalization === 'boolean' ? { textNormalization: raw.text_normalization } : {}),
+          ...(typeof raw.latex_read === 'boolean' ? { latexRead: raw.latex_read } : {}),
+          ...(Array.isArray(raw.pronunciation_tone) && raw.pronunciation_tone.length > 0
+            ? { pronunciationTone: raw.pronunciation_tone.filter((item): item is string => typeof item === 'string' && item.trim() !== '').map((item: string) => item.trim()) }
+            : {}),
+          ...(finiteOrUndefined('sample_rate') !== undefined ? { sampleRate: finiteOrUndefined('sample_rate')! } : {}),
+          ...(finiteOrUndefined('bitrate') !== undefined ? { bitrate: finiteOrUndefined('bitrate')! } : {}),
+          ...(finiteOrUndefined('channel') !== undefined ? { audioChannel: finiteOrUndefined('channel')! } : {}),
+          ...(typeof raw.force_cbr === 'boolean' ? { forceCbr: raw.force_cbr } : {}),
+          ...(typeof raw.subtitle_enable === 'boolean' ? { subtitleEnable: raw.subtitle_enable } : {}),
+          ...(typeof raw.aigc_watermark === 'boolean' ? { aigcWatermark: raw.aigc_watermark } : {}),
+          ...(stringOrEmpty('language_boost') !== undefined ? { languageBoost: stringOrEmpty('language_boost')! } : {}),
+          ...(voiceModify !== undefined ? { voiceModify } : {}),
+          ...(timbreWeights !== undefined && timbreWeights.length > 0 ? { timbreWeights } : {}),
+        }
+      }
+      const buildRequest = (picked: { channel: AudioChannel; alias: string; upstream: string }): GenerateAudioRequest => {
+        const base = mapParams(args as unknown as Record<string, unknown>)
+        // 每模型参数覆盖（model_params[alias]）；缺省 = 自动沿用全局配置
+        let override: Partial<GenerateAudioRequest> = {}
+        if (typeof args.model_params === 'object' && args.model_params !== null) {
+          const perModel = (args.model_params as Record<string, unknown>)[picked.alias]
+          if (typeof perModel === 'object' && perModel !== null) override = mapParams(perModel as Record<string, unknown>)
+        }
+        return {
+          mode,
+          model: picked.alias,
+          upstream: picked.upstream,
+          channelId: picked.channel.id,
+          channel: picked.channel.name,
+          prompt: typeof args.prompt === 'string' ? args.prompt.trim() : '',
+          ...base,
+          ...override,
+        }
+      }
+      /** 单模型执行：生成 + 保存文件 + 历史 + 可选资源库；错误收敛为分组结果。 */
+      const runOne = async (picked: { channel: AudioChannel; alias: string; upstream: string }): Promise<AgentAudioGroup> => {
+        const request = buildRequest(picked)
+        try {
+          const outputs = await generateAudio(picked.channel, request, exec.signal)
+          const audio: AgentAudioRef[] = []
+          const saved: SavedAudioRef[] = []
+          for (const [index, output] of outputs.entries()) {
+            const stored = await saveAudioFile(output.data, output.mime, `generated-${index + 1}`)
+            saved.push({
+              id: stored.id,
+              url: `/api/dsh-audiogen/audio/${encodeURIComponent(stored.file)}`,
+              file: stored.file,
+              mime: stored.mime,
+              bytes: stored.bytes,
+              ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
+            })
+            audio.push({
+              id: stored.id,
+              url: `/api/dsh-audiogen/audio/${encodeURIComponent(stored.file)}`,
+              mime: stored.mime,
+              bytes: stored.bytes,
+              ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
+            })
+          }
+          try {
+            await appendHistory({
+              id: randomUUID(),
+              createdAt: Date.now(),
+              mode: request.mode,
+              model: picked.alias,
+              prompt: request.prompt,
+              ...(request.voice === undefined ? {} : { voice: request.voice }),
+              ...(request.speed === undefined ? {} : { speed: request.speed }),
+              ...(request.duration === undefined ? {} : { duration: request.duration }),
+              ...(request.format === undefined ? {} : { format: request.format }),
+              audio: outputs.map((output, index) => ({
+                id: saved[index]!.id,
+                file: saved[index]!.file,
+                b64: Buffer.from(output.data).toString('base64'),
+                mime: saved[index]!.mime,
+                bytes: saved[index]!.bytes,
+                url: saved[index]!.url,
+                ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
+              })),
+              channelId: picked.channel.id,
+              channel: picked.channel.name,
+              params: { ...request },
+            })
+          } catch {
+            // History is best-effort and must not fail the agent tool.
+          }
+          // ---- 资源库保存：显式参数优先；设置自动入库时可用 false 跳过 ----
+          const wantSave = args.save_to_library === true || (config.autoSaveToLibrary && args.save_to_library !== false)
+          let resources: string[] | undefined
+          if (wantSave) {
+            try {
+              const entry = await saveToLibrary({
+                audioFiles: saved.map(item => ({
+                  id: item.id,
+                  file: item.file,
+                  mime: item.mime,
+                  ...(item.voiceId === undefined ? {} : { voiceId: item.voiceId }),
+                })),
+                type: libraryTypeOf(request.mode, args.library_type),
+                ...(typeof args.library_name === 'string' && args.library_name.trim() !== '' ? { name: args.library_name.trim() } : {}),
+                ...(Array.isArray(args.library_tags) ? { tags: args.library_tags.filter((tag): tag is string => typeof tag === 'string' && tag.trim() !== '').map(tag => tag.trim()) } : {}),
+                provenance: {
+                  mode: request.mode,
+                  prompt: request.prompt,
+                  channel: picked.channel.name,
+                  channelId: picked.channel.id,
+                  apiUrl: picked.channel.apiUrl,
+                  model: picked.alias,
+                  upstream: picked.upstream,
+                  ...(request.voice === undefined ? {} : { voice: request.voice }),
+                  params: { ...request },
+                },
+              })
+              resources = [entry.id]
+            } catch {
+              // library-save is best-effort; generation already succeeded.
+            }
+          }
+          return {
+            model: picked.alias,
+            audio,
+            ...(resources === undefined ? {} : { resources }),
+          }
+        } catch (error) {
+          if (exec.signal?.aborted === true) throw error
+          return {
+            model: picked.alias,
+            audio: [],
+            error: error instanceof Error ? error.message : String(error),
+          }
+        }
+      }
+      // ---- 多模型对比：同一 prompt 依次生成 ----
+      const requestedModels = Array.isArray(args.models)
+        ? [...new Set(args.models.filter((item: unknown): item is string => typeof item === 'string' && item.trim() !== '').map((item: string) => item.trim()))]
+        : []
+      if (requestedModels.length > 0 && mode !== 'voice_design') {
+        const groups: AgentAudioGroup[] = []
+        let succeeded = 0
+        for (const alias of requestedModels) {
+          let picked
+          try {
+            picked = resolveModel(config, alias)
+          } catch (error) {
+            groups.push({ model: alias, audio: [], error: error instanceof Error ? error.message : String(error) })
+            continue
+          }
+          const group = await runOne(picked)
+          groups.push(group)
+          if (group.error === undefined) succeeded++
+        }
+        return {
+          status: succeeded > 0 ? 'completed' : 'failed',
+          message: succeeded > 0
+            ? `Generated ${succeeded}/${groups.length} model(s) with the same prompt for comparison. The audio files can be played/downloaded from the returned URLs.`
+            : 'All model generations failed.',
+          mode,
+          model: groups[0]?.model ?? requestedModels[0]!,
+          audio: groups.flatMap(group => group.audio),
+          groups,
+          ...(succeeded === 0
+            ? { error: groups.map(group => `${group.model}: ${group.error ?? ''}`).filter(item => !item.endsWith(': ')).join('；') }
+            : {}),
+        }
+      }
+      // ---- 单模型（含音色设计） ----
       const picked = mode === 'voice_design'
         ? (() => {
           const usable = config.channels.filter(channel => channel.apiUrl.trim() !== '' && channel.apiKey.trim() !== '')
@@ -171,115 +436,97 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
           return { channel: target, alias: '', upstream: '' }
         })()
         : resolveModel(config, args.model)
-      const voiceModify = typeof args.voice_modify === 'object' && args.voice_modify !== null
-        ? (() => {
-          const raw = args.voice_modify as Record<string, unknown>
-          const out: { pitch?: number; intensity?: number; timbre?: number; soundEffects?: string } = {}
-          if (typeof raw.pitch === 'number') out.pitch = raw.pitch
-          if (typeof raw.intensity === 'number') out.intensity = raw.intensity
-          if (typeof raw.timbre === 'number') out.timbre = raw.timbre
-          if (typeof raw.sound_effects === 'string' && raw.sound_effects.trim() !== '') out.soundEffects = raw.sound_effects.trim()
-          return Object.keys(out).length > 0 ? out : undefined
-        })()
-        : undefined
-      const timbreWeights = Array.isArray(args.timbre_weights)
-        ? args.timbre_weights
-          .filter((item): item is { voice_id: string; weight: number } => typeof item === 'object' && item !== null && typeof (item as { voice_id?: unknown }).voice_id === 'string' && typeof (item as { weight?: unknown }).weight === 'number')
-          .map(item => ({ voiceId: (item.voice_id as string).trim(), weight: item.weight as number }))
-          .filter(item => item.voiceId !== '')
-        : undefined
-      const request: GenerateAudioRequest = {
-        mode,
-        model: picked.alias,
-        upstream: picked.upstream,
-        channelId: picked.channel.id,
-        channel: picked.channel.name,
-        prompt: args.prompt.trim(),
-        ...(typeof args.voice === 'string' && args.voice.trim() !== '' ? { voice: args.voice.trim() } : {}),
-        ...(typeof args.preview_text === 'string' && args.preview_text.trim() !== '' ? { previewText: args.preview_text.trim() } : {}),
-        ...(typeof args.speed === 'number' ? { speed: args.speed } : {}),
-        ...(typeof args.duration === 'number' ? { duration: args.duration } : {}),
-        ...(typeof args.lyrics === 'string' && args.lyrics.trim() !== '' ? { lyrics: args.lyrics.trim() } : {}),
-        ...(typeof args.is_instrumental === 'boolean' ? { isInstrumental: args.is_instrumental } : {}),
-        ...(typeof args.loop === 'boolean' ? { loop: args.loop } : {}),
-        ...(typeof args.prompt_influence === 'number' && Number.isFinite(args.prompt_influence) ? { promptInfluence: args.prompt_influence } : {}),
-        ...(typeof args.format === 'string' && args.format.trim() !== '' ? { format: args.format.trim() } : {}),
-        // ---- MiniMax TTS 专属字段 ----
-        ...(typeof args.emotion === 'string' && args.emotion.trim() !== '' ? { emotion: args.emotion.trim() } : {}),
-        ...(typeof args.vol === 'number' && Number.isFinite(args.vol) ? { vol: args.vol } : {}),
-        ...(typeof args.pitch === 'number' && Number.isFinite(args.pitch) ? { pitch: args.pitch } : {}),
-        ...(typeof args.text_normalization === 'boolean' ? { textNormalization: args.text_normalization } : {}),
-        ...(typeof args.latex_read === 'boolean' ? { latexRead: args.latex_read } : {}),
-        ...(Array.isArray(args.pronunciation_tone) && args.pronunciation_tone.length > 0
-          ? { pronunciationTone: args.pronunciation_tone.filter((item): item is string => typeof item === 'string' && item.trim() !== '').map((item: string) => item.trim()) }
-          : {}),
-        ...(typeof args.sample_rate === 'number' && Number.isFinite(args.sample_rate) ? { sampleRate: args.sample_rate } : {}),
-        ...(typeof args.bitrate === 'number' && Number.isFinite(args.bitrate) ? { bitrate: args.bitrate } : {}),
-        ...(typeof args.channel === 'number' && Number.isFinite(args.channel) ? { audioChannel: args.channel } : {}),
-        ...(typeof args.force_cbr === 'boolean' ? { forceCbr: args.force_cbr } : {}),
-        ...(typeof args.subtitle_enable === 'boolean' ? { subtitleEnable: args.subtitle_enable } : {}),
-        ...(typeof args.aigc_watermark === 'boolean' ? { aigcWatermark: args.aigc_watermark } : {}),
-        ...(typeof args.language_boost === 'string' && args.language_boost.trim() !== '' ? { languageBoost: args.language_boost.trim() } : {}),
-        ...(voiceModify !== undefined ? { voiceModify } : {}),
-        ...(timbreWeights !== undefined && timbreWeights.length > 0 ? { timbreWeights } : {}),
-      }
-      try {
-        const outputs = await generateAudio(picked.channel, request, exec.signal)
-        const audio: AgentAudioRef[] = []
-        for (const [index, output] of outputs.entries()) {
-          const saved = await saveAudioFile(output.data, output.mime, `generated-${index + 1}`)
-          audio.push({
-            id: saved.id,
-            url: `/api/dsh-audiogen/audio/${encodeURIComponent(saved.file)}`,
-            mime: saved.mime,
-            bytes: saved.bytes,
-            ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
-          })
-        }
-        try {
-          await appendHistory({
-            id: randomUUID(),
-            createdAt: Date.now(),
-            mode: request.mode,
-            model: picked.alias,
-            prompt: request.prompt,
-            ...(request.voice === undefined ? {} : { voice: request.voice }),
-            ...(request.speed === undefined ? {} : { speed: request.speed }),
-            ...(request.duration === undefined ? {} : { duration: request.duration }),
-            ...(request.format === undefined ? {} : { format: request.format }),
-            audio: outputs.map((output, index) => ({
-              id: audio[index]!.id,
-              b64: Buffer.from(output.data).toString('base64'),
-              mime: audio[index]!.mime,
-              bytes: audio[index]!.bytes,
-              url: audio[index]!.url,
-              ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
-            })),
-            channelId: picked.channel.id,
-            channel: picked.channel.name,
-          })
-        } catch {
-          // History is best-effort and must not fail the agent tool.
-        }
-        return {
-          status: 'completed',
-          message: 'Audio generation completed. The audio files can be played/downloaded from the returned URLs.',
-          mode: request.mode,
-          model: picked.alias,
-          audio,
-        }
-      } catch (error) {
-        if (exec.signal?.aborted === true) throw error
+      const one = await runOne(picked)
+      if (one.error !== undefined) {
         return {
           status: 'failed',
           message: 'Audio generation failed.',
-          mode: request.mode,
-          model: picked.alias,
+          mode,
+          model: one.model,
           audio: [],
-          error: error instanceof Error ? error.message : String(error),
+          error: one.error,
         }
       }
+      return {
+        status: 'completed',
+        message: 'Audio generation completed. The audio files can be played/downloaded from the returned URLs.',
+        mode,
+        model: one.model,
+        audio: one.audio,
+        ...(one.resources === undefined ? {} : { resources: one.resources }),
+      }
+    },
+  }))
+
+  const searchDisposer = ctx.tools.register(defineTool({
+    name: 'search_audio_library',
+    description: 'Search curated audio resources in the local resource library (voice / music / sfx / tts). Returns matching resources with type, category, name, tags, full provenance (channel, model, voiceId, prompt) and same-origin audio URLs the user can play. Use it before generating to reuse an existing voice, music bed or sound effect instead of generating a new one.',
+    parameters: {
+      type: { type: 'string', enum: ['voice', 'music', 'sfx', 'tts'], description: 'Filter by resource type.' },
+      category: { type: 'string', description: 'Filter by category (voice: male/female/custom; tts: the speaking voice key).' },
+      keyword: { type: 'string', description: 'Search name, tags, prompt and model.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          status: { type: 'string', required: true, enum: ['ok'] },
+          count: { type: 'integer', required: true },
+          entries: {
+            type: 'array', required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                id: { type: 'string', required: true },
+                name: { type: 'string', required: true },
+                type: { type: 'string', required: true, enum: ['voice', 'music', 'sfx', 'tts'] },
+                category: { type: 'string' },
+                tags: { type: 'array', items: { type: 'string' }, required: true },
+                prompt: { type: 'string', required: true },
+                model: { type: 'string' },
+                channel: { type: 'string' },
+                voiceId: { type: 'string' },
+                urls: { type: 'array', items: { type: 'string' }, required: true },
+              },
+            },
+          },
+        },
+      } as const,
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      const keyword = typeof args.keyword === 'string' ? args.keyword.trim().toLowerCase() : ''
+      const wantedType = args.type === 'voice' || args.type === 'music' || args.type === 'sfx' || args.type === 'tts' ? args.type : undefined
+      const wantedCategory = typeof args.category === 'string' && args.category.trim() !== '' ? args.category.trim() : undefined
+      const all = await listLibrary()
+      const entries = all.filter(entry => {
+        if (wantedType !== undefined && entry.type !== wantedType) return false
+        if (wantedCategory !== undefined && (entry.category ?? '') !== wantedCategory) return false
+        if (keyword !== '') {
+          const haystack = [entry.name, ...entry.tags, entry.provenance.prompt, entry.provenance.model ?? '', entry.provenance.channel ?? ''].join(' ').toLowerCase()
+          if (!haystack.includes(keyword)) return false
+        }
+        return true
+      }).slice(0, 30).map(entry => ({
+        id: entry.id,
+        name: entry.name,
+        type: entry.type,
+        ...(entry.category === undefined ? {} : { category: entry.category }),
+        tags: entry.tags,
+        prompt: entry.provenance.prompt,
+        ...(entry.provenance.model === undefined ? {} : { model: entry.provenance.model }),
+        ...(entry.provenance.channel === undefined ? {} : { channel: entry.provenance.channel }),
+        ...(entry.provenance.voiceId === undefined ? {} : { voiceId: entry.provenance.voiceId }),
+        urls: entry.files.map(file => file.url),
+      }))
+      return { status: 'ok' as const, count: entries.length, entries }
     },
   }))
-  return disposer
+  return () => {
+    disposer()
+    searchDisposer()
+  }
 }