dsh-audiogen 0.4.13 → 0.4.15

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

package/skills/sfx/SKILL.md

@@ -33,3 +33,9 @@ whenToUse: 用户请求生成音效、提示音、环境音、UI 音，或触发
 | prompt_influence | prompt_influence | 0-1，默认 0.3；越高越贴提示词，越低越多样 |
 
 > 响应为 audio/mpeg 二进制。请求同时携带 `xi-api-key` 与 `Authorization: Bearer`，兼容 New API 类网关。
+>
+> 网关自动回退：当渠道 API 地址不是 ElevenLabs 官方域名且官方协议被网关拒绝时
+> （404 Invalid URL / 401 Invalid token，例如 ai.farmmx.com 未映射 `/v1/sound-generation`），
+> 引擎自动改用 OpenAI 兼容形态重试：`POST {base}/audio/speech` + `Authorization: Bearer` +
+> `model=eleven_text_to_sound_v2` + `text/duration_seconds/prompt_influence/loop` 字段。
+> 官方地址（api.elevenlabs.io）直连时不触发回退。音色设计在网关无对应兼容端点，会明确报错不便死等。

package/skills/voice-management/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: dsh-audiogen-voice-management
+description: 浏览/筛选/删除厂商音色库（MiniMax、ElevenLabs）并复用选定音色生成 TTS。当用户提到「音色管理 / 音色列表 / 查看有哪些音色 / 删除音色 / 筛选音色 / 用某个音色 TTS / 声音列表」时触发。与资源库（本地生成结果）无关，请勿混淆。
+whenToUse: 需要查看某个渠道（MiniMax / ElevenLabs）有哪些可用音色、按语言/关键词筛选音色、删除某个自建音色，或拿到音色 voice_id 后用它生成语音时。
+---
+
+# 厂商音色管理（dsh-audiogen）
+
+插件提供 `manage_audio_voices` 工具，对接厂商官方音色管理接口：
+
+| 渠道 | 浏览 | 删除 |
+|---|---|---|
+| MiniMax | `POST /v1/get_voice`（system 预置 + voice_cloning/voice_generation 自建） | `POST /v1/delete_voice`（仅自建） |
+| ElevenLabs | `GET /v1/voices`（自有）+ `GET /v1/shared-voices`（社区共享库） | `DELETE /v1/voices/{voice_id}`（仅自有） |
+
+## 浏览音色（action=list）
+
+```json
+{"action": "list", "channel": "MiniMax", "language": "zh", "keyword": "少女", "source": "custom"}
+```
+
+- `channel`：设置中的渠道名称或 id；缺省用默认渠道，多渠道时必须指定。
+- `language`：语言子串（`en` / `zh` / `ja`，或 `Chinese (Mandarin)` 等）。
+- `keyword`：音色名/描述/口音/用途中的自由词。
+- `source`：`system`（官方预置）| `custom`（MiniMax 自建）| `owned`（ElevenLabs 自有）| `shared`（ElevenLabs 社区库）。
+- 返回每条含 `voice_id` / `name` / `source` / `deletable` / `description` / `preview_url`。
+
+## 删除音色（action=delete）
+
+```json
+{"action": "delete", "channel": "MiniMax", "voice_id": "voice_abc123", "confirm": true}
+```
+
+- 仅 `deletable=true`（custom/owned）的音色可删；官方/共享/系统音色会被拒绝。
+- 删除不可逆：必须显式传 `confirm: true`，且 `voice_id` 用 `action=list` 返回的精确值。
+
+## 闭环：选定音色 → 生成 TTS
+
+1. `manage_audio_voices(list)` 找到符合需求的音色，记录其 `voice_id`。
+2. `generate_audio(mode="tts", voice="<voice_id>", channel="<渠道名>", prompt="...")` 生成语音。
+
+MiniMax TTS 的 `voice` 参数需要官方 voice_id；ElevenLabs 的 `voice` 参数可填音色 name 或 voice_id（网关渠道强制 voice_id）。
+
+## 常见错误
+
+- `channel-choice-required`：多个渠道未指定 → 先 `manage_audio_voices(list, channel=...)` 或询问用户。
+- 删除被拒（`system`/`shared` 只读）：换个 `source=custom`/`owned` 的音色。
+- 拉取失败：渠道 API 地址/密钥错误，或网关不支持音色管理端点（Stability、自定义 OpenAI 兼容渠道无此能力，会明确提示不支持）。

package/src/agent-audio-tools.ts

@@ -11,6 +11,10 @@ import type { AudioChannel } from './audio-engine.ts'
 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,
+  deleteVendorVoice,
+} from './voice-manager.ts'
 import type { AudioMode, GenerateAudioRequest, LibraryType } from './protocol.ts'
 
 export interface AgentAudioToolConfig {
@@ -546,8 +550,127 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
       return { status: 'ok' as const, count: entries.length, entries }
     },
   }))
+
+  /** 厂商音色管理：浏览/筛选 + 删除（仅自建）。删除不可逆，必须 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, with language/keyword/source filtering; 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.',
+    parameters: {
+      action: { type: 'string', enum: ['list', 'delete'], required: true, description: 'list = browse/filter voices; 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).' },
+      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.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          status: { type: 'string', required: true, enum: ['ok'] },
+          kind: { type: 'string', required: true, enum: ['list', 'delete'] },
+          vendor: { type: 'string', required: true },
+          channel: { type: 'string', required: true },
+          count: { type: 'integer' },
+          truncated: { type: 'boolean' },
+          voices: {
+            type: 'array',
+            items: {
+              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' },
+                accent: { type: 'string' },
+                gender: { type: 'string' },
+                age: { type: 'string' },
+                use_case: { type: 'string' },
+                description: { type: 'string' },
+                preview_url: { type: 'string' },
+              },
+            },
+          },
+          voice_id: { type: 'string' },
+          deleted: { type: 'boolean' },
+          message: { type: 'string' },
+          note: { type: 'string' },
+        },
+      } as const,
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    timeoutMs: 120_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      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)
+      const action = args.action === 'delete' ? 'delete' : 'list'
+      if (action === 'list') {
+        const source = typeof args.source === 'string' && ['system', 'custom', 'owned', 'shared'].includes(args.source) ? args.source : undefined
+        const result = await listVendorVoices(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 }),
+        })
+        return {
+          status: 'ok' as const,
+          kind: 'list' as const,
+          vendor: result.vendor,
+          channel: channel.name,
+          count: result.voices.length,
+          ...(result.truncated ? { truncated: true } : {}),
+          voices: result.voices,
+          ...(result.note === undefined ? {} : { note: result.note }),
+        }
+      }
+      const voiceId = typeof args.voice_id === 'string' ? args.voice_id.trim() : ''
+      if (voiceId === '') throw new AudioGenError('delete requires voice_id (the exact voice_id from action=list).', 'voice-id-required')
+      if (args.confirm !== true) throw new AudioGenError('Deletion is irreversible: pass confirm=true after verifying the voice_id.', 'voice-delete-requires-confirm')
+      const deleted = await deleteVendorVoice(channel, voiceId)
+      return {
+        status: 'ok' as const,
+        kind: 'delete' as const,
+        vendor: deleted.vendor,
+        channel: channel.name,
+        voice_id: deleted.voice_id,
+        deleted: true,
+        message: `已删除音色 ${deleted.voice_id}（${channel.name}）`,
+      }
+    },
+  }))
+
   return () => {
     disposer()
     searchDisposer()
+    managementDisposer()
+  }
+}
+
+/** 解析工具目标渠道：默认渠道 > 唯一可用渠道；多渠道未指定时要求显式选择。 */
+function resolveVoiceManagementChannel(config: AgentAudioToolConfig, requested: unknown): AudioChannel {
+  const usable = config.channels.filter(channel => channel.apiUrl.trim() !== '' && channel.apiKey.trim() !== '')
+  if (usable.length === 0) {
+    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')
+  }
+  const wanted = typeof requested === 'string' ? requested.trim() : ''
+  if (wanted === '') {
+    if (usable.length === 1) return usable[0]!
+    const target = usable.find(channel => channel.id === config.defaultChannelId)
+    if (target !== undefined) return target
+    const options = usable.map(channel => `"${channel.name}"`).join(', ')
+    throw new AudioGenError(`Multiple audio channels are configured — specify the channel (one of: ${options}).`, 'channel-choice-required')
   }
+  const direct = usable.find(channel => channel.name === wanted || channel.id === wanted)
+  if (direct !== undefined) return direct
+  const partial = usable.filter(channel => channel.name.toLowerCase().includes(wanted.toLowerCase()))
+  if (partial.length === 1) return partial[0]!
+  const options = usable.map(channel => channel.name).join(', ')
+  throw new AudioGenError(`Audio channel "${wanted}" is not configured. Choose one of: ${options}.`, 'channel-not-configured')
 }

package/src/audio-engine.ts

@@ -245,7 +245,7 @@ async function openAITTS(channel: AudioChannel, request: GenerateAudioRequest, s
   return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
 }
 
-async function elevenLabs(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+async function elevenLabsOfficial(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   const base = endpointBase(channel.apiUrl)
   const model = (request.upstream ?? request.model) || 'eleven_multilingual_v2'
   // 官方使用 xi-api-key；额外携带 Authorization Bearer 以兼容 New API 类网关。
@@ -299,17 +299,20 @@ async function elevenLabs(channel: AudioChannel, request: GenerateAudioRequest,
 
   // ------------- ElevenLabs Music（POST /v1/music） -------------
   // 模型：music_v1 / music_v2；prompt 与 composition_plan 二选一（引擎用 prompt）。
+  // 未提供歌词时按纯音乐处理（force_instrumental=true），不再要求必须有歌词。
   if (request.mode === 'music') {
     const endpoint = `${base}/music`
     const musicModel = (request.upstream ?? request.model) || 'music_v1'
+    const lyrics = request.lyrics?.trim() ?? ''
+    const instrumental = request.isInstrumental === true || lyrics === ''
     const body: Record<string, unknown> = {
       model_id: musicModel,
       prompt: request.prompt,
       ...(request.duration !== undefined && Number.isFinite(request.duration)
         ? { music_length_ms: Math.round(Math.min(600_000, Math.max(3_000, request.duration * 1000))) }
         : {}),
-      ...(request.lyrics !== undefined && request.lyrics.trim() !== '' ? { lyrics_text: request.lyrics.trim() } : {}),
-      ...(request.isInstrumental !== undefined ? { force_instrumental: request.isInstrumental } : {}),
+      ...(lyrics === '' ? {} : { lyrics_text: lyrics }),
+      ...(instrumental ? { force_instrumental: true } : {}),
     }
     const response = await fetchWithTimeout(endpoint, {
       method: 'POST',
@@ -379,6 +382,166 @@ async function elevenLabs(channel: AudioChannel, request: GenerateAudioRequest,
   return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
 }
 
+/**
+ * 官方 ElevenLabs 请求被网关拒绝的信号:官方路径未映射(404 Invalid URL)或
+ * 网关要求 Bearer 认证而非 xi-api-key(401/403 Invalid token / Invalid API key)。
+ * New API 类中转(如 ai.farmmx.com)对 ElevenLabs 官方协议通常返回这类错误。
+ */
+function isGatewayRouteMiss(error: unknown): boolean {
+  return error instanceof AudioGenError
+    && error.code === 'audio-api-error'
+    && /\bHTTP (404|401|403)\b/.test(error.message)
+    && /\bInvalid URL\b|\bInvalid token\b|\bInvalid API key\b/i.test(error.message)
+}
+
+/** 网关兼容形态的请求头:仅 Bearer(携带 xi-api-key 会被网关按官方协议校验而 401)。 */
+function gatewayHeaders(apiKey: string): Record<string, string> {
+  return {
+    authorization: `Bearer ${apiKey.trim()}`,
+    'content-type': 'application/json',
+    accept: 'audio/mpeg, application/json',
+  }
+}
+
+/** /audio/speech 兼容端点:base 已以此结尾时直接复用,否则拼接。 */
+function speechGatewayEndpoint(base: string): string {
+  return /\/audio\/speech(\?|$)/i.test(base) ? base : `${base}/audio/speech`
+}
+
+/**
+ * ElevenLabs 渠道的网关兼容形态(OpenAI 风格):路径用 /audio/speech(音效/TTS)
+ * 或 /music(音乐),认证用 Bearer、模型用 `model` 字段。
+ *
+ * 适配未映射 ElevenLabs 官方端点(404 Invalid URL)或要求 Bearer 认证
+ * (401 Invalid token)的 New API 类中转,如 ai.farmmx.com。
+ */
+async function elevenLabsGatewayCompat(
+  channel: AudioChannel,
+  request: GenerateAudioRequest,
+  signal?: AbortSignal,
+): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  const base = endpointBase(channel.apiUrl)
+  const headers = gatewayHeaders(channel.apiKey)
+
+  // music → POST /music(Bearer + model;官方形态在此类网关上是 401 Invalid token)。
+  if (request.mode === 'music') {
+    const endpoint = /\/music(\?|$)/i.test(base) ? base : `${base}/music`
+    const musicModel = (request.upstream ?? request.model) || 'music_v1'
+    const lyrics = request.lyrics?.trim() ?? ''
+    const instrumental = request.isInstrumental === true || lyrics === ''
+    const body: Record<string, unknown> = {
+      model: musicModel,
+      prompt: request.prompt,
+      ...(request.duration !== undefined && Number.isFinite(request.duration)
+        ? { music_length_ms: Math.round(Math.min(600_000, Math.max(3_000, request.duration * 1000))) }
+        : {}),
+      ...(lyrics === '' ? {} : { lyrics_text: lyrics }),
+      ...(instrumental ? { force_instrumental: true } : {}),
+    }
+    const response = await fetchWithTimeout(endpoint, {
+      method: 'POST',
+      redirect: 'follow',
+      headers,
+      body: JSON.stringify(body),
+      signal,
+    }, UPSTREAM_TIMEOUT_MS)
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '')
+      throw new AudioGenError(`ElevenLabs music gateway-compatible API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+    }
+    return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+  }
+
+  // 音色设计在网关兼容层没有对应端点,直接给出可操作的错误说明。
+  if (request.mode === 'voice_design') {
+    throw new AudioGenError(
+      '当前网关不支持 ElevenLabs 音色设计端点(POST /v1/text-to-voice/design);该模式请改用 MiniMax 渠道或 ElevenLabs 官方 API。',
+      'voice-design-unsupported',
+    )
+  }
+
+  // sfx / tts → POST /audio/speech(OpenAI 兼容形态;网关把 model=eleven_text_to_sound_v2 映射到音效生成)。
+  // 音效必须传 OpenAI 标准的 `input`(实测 ai.farmmx.com 类 new-api 网关:input+duration_seconds
+  // 会走 ElevenLabs 音效生成;若传 ElevenLabs 官方字段 `text`,网关会把它当 TTS 文本朗读出来)。
+  const endpoint = speechGatewayEndpoint(base)
+  const isSfx = request.mode === 'sfx'
+  const model = (request.upstream ?? request.model)
+    || (isSfx ? 'eleven_text_to_sound_v2' : 'eleven_multilingual_v2')
+  // 网关(new-api 类中转)对 ElevenLabs TTS 强制校验 voice/voice_id,缺失直接 400;
+  // 在发送前拦截,给出可操作的提示,而不是把网关 400 原样抛给用户。
+  if (!isSfx) {
+    const voice = request.voice?.trim() ?? ''
+    if (voice === '') {
+      const voiceEntries = (channel.models ?? []).filter(entry => {
+        const candidate = entry as { alias: string; id: string; category?: string }
+        return candidate.category === 'tts' && candidate.id.trim() !== '' && candidate.id !== candidate.alias
+      })
+      const suggestions = voiceEntries.map(entry => `${entry.alias}（${entry.id}）`)
+      throw new AudioGenError(
+        `ElevenLabs 网关渠道的 TTS 必须携带音色 voice_id（网关强制校验，缺失会返回 400 voice or voice_id is required）：请在「音色」字段填入官方音色 ID${
+          suggestions.length === 0 ? '' : `，可选用以下音色：${suggestions.slice(0, 4).join('、')}`
+        }。`,
+        'voice-required',
+      )
+    }
+  }
+  const body: Record<string, unknown> = isSfx
+    ? {
+        model,
+        input: request.prompt,
+        ...(request.duration !== undefined && Number.isFinite(request.duration)
+          ? { duration_seconds: Math.min(30, Math.max(0.5, request.duration)) }
+          : {}),
+        ...(request.loop !== undefined ? { loop: request.loop } : {}),
+        ...(request.promptInfluence !== undefined && Number.isFinite(request.promptInfluence)
+          ? { prompt_influence: Math.min(1, Math.max(0, request.promptInfluence)) }
+          : {}),
+      }
+    : {
+        model,
+        input: request.prompt,
+        voice: request.voice!.trim(),
+        response_format: request.format ?? 'mp3',
+        ...(request.speed !== undefined ? { speed: request.speed } : {}),
+      }
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    redirect: 'follow',
+    headers,
+    body: JSON.stringify(body),
+    signal,
+  }, UPSTREAM_TIMEOUT_MS)
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    throw new AudioGenError(
+      `ElevenLabs ${isSfx ? 'sound effects' : 'TTS'} gateway-compatible API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`,
+      'audio-api-error',
+    )
+  }
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
+/**
+ * ElevenLabs 渠道入口:官方端点优先;官方协议被网关(New API 类中转)拒绝时,
+ * 自动改用 OpenAI 兼容形态重试,使同一渠道同时兼容 ElevenLabs 官方 API 与
+ * ai.farmmx.com 类中转。官方地址(api.elevenlabs.io)直连不触发回退。
+ */
+async function elevenLabs(
+  channel: AudioChannel,
+  request: GenerateAudioRequest,
+  signal?: AbortSignal,
+): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  if (/elevenlabs\.io/i.test(channel.apiUrl)) {
+    return elevenLabsOfficial(channel, request, signal)
+  }
+  try {
+    return await elevenLabsOfficial(channel, request, signal)
+  } catch (error) {
+    if (!isGatewayRouteMiss(error)) throw error
+  }
+  return elevenLabsGatewayCompat(channel, request, signal)
+}
+
 function minimaxApiBase(base: string): string {
   const trimmed = endpointBase(base)
   return /\/v1$/i.test(trimmed) ? trimmed : `${trimmed}/v1`
@@ -551,22 +714,19 @@ async function minimax(channel: AudioChannel, request: GenerateAudioRequest, sig
     // audio_setting{format, sample_rate, bitrate}。音频输出配置为固定枚举：
     // format mp3|wav|pcm；sample_rate 16000|24000|32000|44100；
     // bitrate 32000|64000|128000|256000，超出枚举的值回退默认。
+    // 歌词为空时一律按纯音乐生成（is_instrumental=true）：面板/Agent 无论是否
+    // 显式勾选「纯音乐」都能出结果，不再因缺歌词报错。
     const MUSIC_FORMATS = new Set(['mp3', 'wav', 'pcm'])
     const MUSIC_SAMPLE_RATES = new Set([16000, 24000, 32000, 44100])
     const MUSIC_BITRATES = new Set([32000, 64000, 128000, 256000])
     const lyrics = request.lyrics?.trim() ?? ''
-    if (lyrics === '' && request.isInstrumental !== true) {
-      throw new AudioGenError(
-        'MiniMax 音乐生成需要歌词（lyrics 参数），或在「纯音乐」模式（is_instrumental=true）下生成；也可让面板/Agent 先为提示词创作一段歌词。',
-        'lyrics-required',
-      )
-    }
+    const instrumental = request.isInstrumental === true || lyrics === ''
     const endpoint = `${base}/music_generation`
     const body: Record<string, unknown> = {
       model,
       prompt: request.prompt,
       ...(lyrics === '' ? {} : { lyrics }),
-      ...(request.isInstrumental !== undefined ? { is_instrumental: request.isInstrumental } : {}),
+      ...(instrumental ? { is_instrumental: true } : {}),
       ...(request.duration !== undefined ? { duration: request.duration } : {}),
       audio_setting: {
         format: MUSIC_FORMATS.has(request.format ?? 'mp3') ? (request.format ?? 'mp3') : 'mp3',

package/src/client/api.ts

@@ -16,6 +16,8 @@ export interface GenerateResponse {
   historyError?: string
   /** Resource-library entries created by the generation (auto-save). */
   resources?: Array<{ id: string; name: string; type: string }>
+  /** 引擎兜底提示（如：未提供歌词时按纯音乐生成）。 */
+  note?: string
   code?: string
   message?: string
 }

package/src/client/audio-panel.module.css

@@ -1171,6 +1171,13 @@
   grid-column: 1 / -1;
 }
 
+/* 勾选纯音乐后禁用的歌词框 */
+.textarea:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+  background: var(--dsw-alias-bg-layer-2, #f3f4f6);
+}
+
 /* 模式胶囊 */
 .modeIcon {
   font-size: 13px;

package/src/client/field-specs.ts

@@ -91,7 +91,7 @@ export function presetSupports(preset: string, key: FieldKey, mode: AudioMode):
 }
 
 const SPECS: Record<FieldKey, Omit<FieldSpec, 'key' | 'presets'>> = {
-  duration: { label: '时长（秒）', type: 'number', min: 1, max: 120, placeholder: '30', hint: 'duration；MiniMax 音乐 ≤190、ElevenLabs 音乐 3-600（转 ms）、Stability 按模型 190/380' },
+  duration: { label: '时长（秒）', type: 'number', min: 1, max: 200, placeholder: '30', hint: 'duration；MiniMax 音乐 ≤190、ElevenLabs 音乐 3-600（转 ms）、Stability 按模型 190/380' },
   format: { label: '输出格式', type: 'select', options: ['mp3', 'wav', 'pcm', 'flac', 'ogg'], hint: 'format / output_format / response_format' },
   lyrics: { label: '歌词（纯音乐模式可留空；多段用空行分隔）', type: 'text', placeholder: '第一段歌词…\n\n第二段歌词…', hint: 'MiniMax lyrics / ElevenLabs lyrics_text' },
   instrumental: { label: '纯音乐（无歌词/人声）', type: 'checkbox', hint: 'MiniMax is_instrumental / ElevenLabs force_instrumental' },

package/src/client/studio-view.tsx

@@ -424,6 +424,8 @@ export function StudioView(props: {
       props.showToast('已保存到资源库')
       props.onLibraryChanged()
     }
+    // 引擎兜底提示（如未提供歌词时自动按纯音乐生成），最后展示避免被覆盖。
+    if (response.note !== undefined && response.note.trim() !== '') props.showToast(response.note)
     reload()
     return generated
   }
@@ -756,7 +758,13 @@ export function StudioView(props: {
         return (
           <label className={css.label} key={spec.key} title={spec.hint}>
             <span>{spec.label}</span>
-            <textarea className={css.textarea} value={lyrics} onChange={event => setLyrics(event.target.value)} placeholder={'第一段歌词…\n\n第二段歌词…'} />
+            <textarea
+              className={css.textarea}
+              disabled={instrumental}
+              value={lyrics}
+              onChange={event => setLyrics(event.target.value)}
+              placeholder={instrumental ? '纯音乐模式无需填写歌词' : '第一段歌词…\n\n第二段歌词…'}
+            />
           </label>
         )
       case 'instrumental':

package/src/index.ts

@@ -82,7 +82,7 @@ const DEFAULT_ALLOW_AGENT_AUDIO = true
 
 const SECTION_ORDER = 160
 
-export const AUDIOGEN_GUIDANCE = '本机已安装 dsh-audiogen 插件（DSH AI 音频）：侧边栏「AI 音频」入口。能力：通过「渠道」对接多个音频生成厂商（OpenAI TTS、ElevenLabs、MiniMax、Stability Audio、自定义 OpenAI 兼容接口），支持 TTS 文本转语音、音乐生成和音效生成。API 地址与密钥在 GUI 设置中按渠道配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发。Agent 可直接调用 `generate_audio` 提交 TTS/音乐/音效任务，默认等待完成并返回同源音频 URL。限制：生成消耗上游 API 额度；音频内容由上游模型生成；模型只能使用用户在各渠道配置目录中的模型。用户提到「音频 / 语音 / TTS / 配乐 / 音效 / AI 音频」时即指本插件，请据此协作。'
+export 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 音频」时即指本插件，请据此协作。'
 
 function guidanceFor(channels: AudioChannel[], defaultChannelId: string): string {
   if (channels.length === 0) {

package/src/protocol.ts

@@ -8,7 +8,7 @@
 export const AUDIOGEN_SETTINGS_NAMESPACE = 'dsh-audiogen'
 
 /** Published package version shared by the host updater and the client UI. */
-export const PLUGIN_VERSION = '0.4.13'
+export const PLUGIN_VERSION = '0.4.14'
 
 /** Same-origin route family (loopback-only, mirroring dsh-imagegen). */
 export const SETTINGS_API = {

package/src/routes.ts

@@ -515,7 +515,12 @@ export function makeRoutes(deps: AudiogenRoutesDeps): WebRoute[] {
               // library-save is best-effort: generation and history already succeeded
             }
           }
-          writeJson(res, 200, { ok: true, outputs: generated, history, ...(resources === undefined ? {} : { resources }) })
+          // ---- 音乐兜底提示：未提供歌词时引擎按纯音乐生成，告知前端一声 ----
+          const instrumentalFallback = request.mode === 'music'
+            && request.isInstrumental !== true
+            && (request.lyrics === undefined || request.lyrics.trim() === '')
+          const note = instrumentalFallback ? '未提供歌词，已按纯音乐生成' : undefined
+          writeJson(res, 200, { ok: true, outputs: generated, history, ...(resources === undefined ? {} : { resources }), ...(note === undefined ? {} : { note }) })
         } catch (error) {
           const code = error instanceof AudioGenError ? error.code : 'generate-failed'
           writeJson(res, 200, { ok: false, code, message: messageOf(error) })