dsh-audiogen 0.1.0

package/src/client/sidebar-entry.ts

@@ -0,0 +1,115 @@
+/**
+ * Sidebar entry injection.
+ *
+ * dsh's sidebar shell exposes no slot an external plugin can register into,
+ * so the entry row is injected at the DOM level after the shell's New Session
+ * button. A MutationObserver self-heals when React re-renders.
+ */
+
+import type { AudioGenController } from './controller.ts'
+import css from './panel.module.css'
+
+export const ENTRY_SELECTOR = '[data-dsh-audiogen-entry]'
+
+const ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 3.5h10v9H3z"/><path d="M1.5 5.5v5"/><path d="M14.5 5.5v5"/><path d="M6 6.5l4 1.5-4 1.5z"/></svg>'
+
+const FAMILY_ENTRY_SELECTOR = '[data-dsh-taskboard-entry], [data-dsh-ssh-entry], [data-dsh-imagegen-entry], [data-dsh-audiogen-entry]'
+
+function sidebarRoot(): HTMLElement | undefined {
+  const column = document.querySelector<HTMLElement>('[data-pane="sidebar"], [class*="sidebarCol"]')
+  if (column === null) return undefined
+  const logoOwner = column.querySelector<HTMLElement>('[class*="logoRow"]')?.parentElement
+  return logoOwner ?? (column.firstElementChild as HTMLElement | undefined)
+}
+
+function newSessionButton(root: HTMLElement): HTMLButtonElement | undefined {
+  const nested = root.querySelector<HTMLButtonElement>('button[class*="newSession"]')
+  if (nested !== null) return nested
+  for (const child of root.children) {
+    if (child.tagName === 'BUTTON') return child as HTMLButtonElement
+  }
+  return undefined
+}
+
+function createEntry(controller: AudioGenController, label: string, tooltip: string): HTMLButtonElement {
+  const entry = document.createElement('button')
+  entry.type = 'button'
+  entry.dataset.dshAudiogenEntry = ''
+  entry.className = css.entry
+  entry.setAttribute('aria-label', label)
+  entry.setAttribute('title', tooltip)
+  entry.innerHTML = '<span class="' + css.entryIcon + '">' + ICON + '</span><span class="' + css.entryLabel + '">' + label + '</span>'
+  entry.addEventListener('click', () => { controller.toggle() })
+  return entry
+}
+
+function placeEntry(root: HTMLElement, entry: HTMLButtonElement): boolean {
+  const button = newSessionButton(root)
+  if (button === undefined) return false
+  if (entry.parentElement !== root) {
+    const row = button.closest('[class*="logoRow"]')
+    const base = (row !== null && row.parentElement === root) ? row : button
+    const family = Array.from(root.children).filter(
+      (el): el is HTMLElement => el instanceof HTMLElement && el.matches(FAMILY_ENTRY_SELECTOR),
+    )
+    const anchor = family.length > 0 ? family[family.length - 1].nextElementSibling : base.nextElementSibling
+    root.insertBefore(entry, anchor)
+  }
+  return true
+}
+
+export function mountSidebarEntry(controller: AudioGenController, label: string, tooltip: string): () => void {
+  const entry = createEntry(controller, label, tooltip)
+  let root: HTMLElement | undefined
+  let placed = false
+
+  const tryPlace = (): void => {
+    if (root !== undefined && !root.isConnected) {
+      rootObserver.disconnect()
+      root = undefined
+      placed = false
+    }
+    if (placed) {
+      if (document.body.contains(entry)) return
+      rootObserver.disconnect()
+      root = undefined
+      placed = false
+    }
+    root ??= sidebarRoot()
+    if (root === undefined) return
+    placed = placeEntry(root, entry)
+    if (placed) {
+      rootObserver.observe(root, { childList: true, subtree: true })
+    }
+  }
+
+  const waitObserver = new MutationObserver(() => { tryPlace() })
+  waitObserver.observe(document.body, { childList: true, subtree: true })
+
+  const rootObserver = new MutationObserver(() => {
+    if (root === undefined || !root.isConnected) {
+      placed = false
+      tryPlace()
+      return
+    }
+    if (!root.contains(entry)) {
+      placed = placeEntry(root, entry)
+    }
+  })
+
+  const syncActive = () => {
+    if (controller.getSnapshot().panelOpen) entry.dataset.active = 'true'
+    else delete entry.dataset.active
+  }
+  const unsubscribe = controller.subscribe(syncActive)
+  syncActive()
+
+  tryPlace()
+
+  return () => {
+    waitObserver.disconnect()
+    rootObserver.disconnect()
+    unsubscribe()
+    entry.remove()
+  }
+}

package/src/index.ts

@@ -0,0 +1,201 @@
+/**
+ * dsh-audiogen — host half.
+ *
+ * Mounts the plugin settings section (multi-provider audio channels), the
+ * /api/dsh-audiogen route family (settings bridge, presets, generation proxy,
+ * audio/history serving), and the Agent audio tool. The browser half
+ * (./client) renders the sidebar entry and the audio generation panel.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from 'schemastery'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tools'
+import { AUDIOGEN_SETTINGS_NAMESPACE, type ChannelConfig, type ModelMapping } from './protocol.ts'
+import { makeRoutes, type ChannelsView, type SettingsSeam } from './routes.ts'
+import type { AudioChannel } from './audio-engine.ts'
+import { registerAgentAudioTools, type AgentAudioToolConfig } from './agent-audio-tools.ts'
+import { audioPresetById } from './audio-presets.ts'
+
+/** Stable cordis plugin name. */
+export const name = 'audiogen'
+
+/** Services required before the surfaces can mount. */
+export const inject = ['webServer', 'systemPrompt']
+
+/** The branded settings namespace of this plugin. */
+export const AudioGenSettingsNamespace = settingsNamespace(AUDIOGEN_SETTINGS_NAMESPACE)
+
+export interface Config {
+  enabled?: boolean
+  announceToAgent?: boolean
+  allowAgentAudioGeneration?: boolean
+  channels?: ChannelConfig[]
+  channelSecrets?: Record<string, string>
+  defaultChannelId?: string
+  defaultModel?: string
+}
+
+export const Config: z<Config> = z.object({
+  enabled: z.boolean().default(true),
+  announceToAgent: z.boolean().default(true),
+  allowAgentAudioGeneration: z.boolean().default(true),
+  channels: z.array(z.object({
+    id: z.string(),
+    preset: z.string().default(''),
+    name: z.string().default(''),
+    apiUrl: z.string().default(''),
+    models: z.array(z.object({
+      alias: z.string(),
+      id: z.string(),
+    })).default([]),
+  })).default([]),
+  channelSecrets: z.dict(z.string().role('secret')).default({}),
+  defaultChannelId: z.string().default(''),
+  defaultModel: z.string().default(''),
+})
+
+const DEFAULT_ENABLED = true
+const DEFAULT_ANNOUNCE = true
+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 音频」时即指本插件，请据此协作。'
+
+function guidanceFor(channels: AudioChannel[], defaultChannelId: string): string {
+  if (channels.length === 0) {
+    return `${AUDIOGEN_GUIDANCE} 尚未配置任何渠道：请先在「设置 → 插件 → AI 音频」添加渠道并填写 API 地址与密钥。`
+  }
+  const table = channels.map(channel => {
+    const aliases = channel.models.map(model => model.alias).join('、')
+    const mark = channel.id === defaultChannelId ? '（默认渠道）' : ''
+    const key = channel.apiKey === '' ? '（未填密钥）' : ''
+    const models = channel.models.length === 0 ? '未配置模型/音色' : `可用模型/音色：${aliases}`
+    return `渠道「${channel.name}」${mark}[${channel.apiUrl}] ${models}${key}`
+  }).join('；')
+  return `${AUDIOGEN_GUIDANCE} 当前渠道与模型：${table}。`
+}
+
+function normalizeChannels(value: unknown): ChannelConfig[] {
+  if (!Array.isArray(value)) return []
+  const out: ChannelConfig[] = []
+  for (const item of value) {
+    if (item === null || typeof item !== 'object') continue
+    const raw = item as Record<string, unknown>
+    const id = typeof raw.id === 'string' ? raw.id.trim() : ''
+    if (id === '') continue
+    const models: ModelMapping[] = []
+    if (Array.isArray(raw.models)) {
+      for (const entry of raw.models) {
+        if (entry === null || typeof entry !== 'object') continue
+        const record = entry as Record<string, unknown>
+        const alias = typeof record.alias === 'string' ? record.alias.trim() : ''
+        const upstream = typeof record.id === 'string' ? record.id.trim() : ''
+        if (alias === '') continue
+        models.push({ alias, id: upstream === '' ? alias : upstream })
+      }
+    }
+    out.push({
+      id,
+      preset: typeof raw.preset === 'string' ? raw.preset : '',
+      name: typeof raw.name === 'string' ? raw.name.trim() : '',
+      apiUrl: typeof raw.apiUrl === 'string' ? raw.apiUrl.trim() : '',
+      models,
+    })
+  }
+  return out
+}
+
+export interface EffectiveConfig {
+  enabled: boolean
+  announceToAgent: boolean
+  allowAgentAudioGeneration: boolean
+  channels: AudioChannel[]
+  defaultChannelId: string
+  defaultModel: string
+}
+
+export function apply(ctx: Context, config?: Config): void {
+  let current: () => Config = () => config ?? {}
+
+  const resolve = (): EffectiveConfig => {
+    const value = current() ?? {}
+    const channels = normalizeChannels(value.channels)
+    const secrets: Record<string, string> = { ...(value.channelSecrets ?? {}) }
+    const named = channels.map(channel => ({
+      ...channel,
+      name: channel.name === '' ? (audioPresetById(channel.preset)?.name ?? '未命名渠道') : channel.name,
+    }))
+    const defaultChannelId = typeof value.defaultChannelId === 'string' && named.some(channel => channel.id === value.defaultChannelId)
+      ? value.defaultChannelId
+      : named[0]?.id ?? ''
+    return {
+      enabled: value.enabled ?? DEFAULT_ENABLED,
+      announceToAgent: value.announceToAgent ?? DEFAULT_ANNOUNCE,
+      allowAgentAudioGeneration: value.allowAgentAudioGeneration ?? DEFAULT_ALLOW_AGENT_AUDIO,
+      channels: named.map(channel => ({
+        ...channel,
+        apiKey: typeof secrets[channel.id] === 'string' ? secrets[channel.id] : '',
+      })),
+      defaultChannelId,
+      defaultModel: typeof value.defaultModel === 'string' ? value.defaultModel.trim() : '',
+    }
+  }
+
+  const channelsView = (): ChannelsView => {
+    const value = resolve()
+    return { channels: value.channels, defaultChannelId: value.defaultChannelId }
+  }
+
+  ctx.inject(['settings', 'webServer'], (sctx) => {
+    const seam = sctx.get('settings') as unknown as SettingsSeam
+    sctx.effect(() => {
+      const routes = makeRoutes({
+        settings: seam,
+        resolveChannels: channelsView,
+      })
+      const disposers = routes.map(route => ctx.webServer.register(route))
+      return () => { for (const dispose of disposers) dispose() }
+    }, 'dsh-audiogen: routes')
+  })
+
+  ctx.inject(['tools'], (tctx) => {
+    tctx.effect(() => registerAgentAudioTools(tctx, (): AgentAudioToolConfig => {
+      const value = resolve()
+      return {
+        enabled: value.enabled,
+        allowAgentAudioGeneration: value.allowAgentAudioGeneration,
+        channels: value.channels,
+        defaultChannelId: value.defaultChannelId,
+      }
+    }), 'dsh-audiogen: agent audio tools')
+  })
+
+  let disposeSection: (() => void) | undefined
+  const sync = (): void => {
+    if (disposeSection !== undefined) {
+      disposeSection()
+      disposeSection = undefined
+    }
+    const value = resolve()
+    if (!value.enabled || !value.announceToAgent) return
+    disposeSection = ctx.systemPrompt.section({
+      name: 'plugin:dsh-audiogen',
+      order: SECTION_ORDER,
+      text: guidanceFor(value.channels, value.defaultChannelId),
+    })
+  }
+
+  installSettingsSection(ctx, AudioGenSettingsNamespace, Config, config ?? {}, {
+    setSource: (source) => {
+      current = source
+      sync()
+    },
+    onChange: sync,
+  })
+
+  sync()
+}

package/src/protocol.ts

@@ -0,0 +1,179 @@
+/**
+ * Wire contract shared by the host and client halves of dsh-audiogen:
+ * settings namespace, route paths, generate payload/result shapes.
+ * Pure types and constants — safe for the client bundle to inline.
+ */
+
+/** Settings namespace this plugin owns (host settings seam + bridge). */
+export const AUDIOGEN_SETTINGS_NAMESPACE = 'dsh-audiogen'
+
+/** Published package version shared by the host updater and the client UI. */
+export const PLUGIN_VERSION = '0.1.0'
+
+/** Same-origin route family (loopback-only, mirroring dsh-imagegen). */
+export const SETTINGS_API = {
+  describe: '/api/dsh-audiogen/settings/describe',
+  mutate: '/api/dsh-audiogen/settings/mutate',
+} as const
+
+/** The audio-generation proxy route. */
+export const GENERATE_API = '/api/dsh-audiogen/generate' as const
+
+/** Host-mediated built-in provider catalog (channels the user can instantiate). */
+export const PRESETS_API = '/api/dsh-audiogen/presets' as const
+
+/** Loopback-only audio file reader for panel/tool-result previews. */
+export const AUDIO_API = {
+  file: '/api/dsh-audiogen/audio',
+} as const
+
+/** Host-persisted generation history routes. */
+export const HISTORY_API = {
+  list: '/api/dsh-audiogen/history/list',
+  append: '/api/dsh-audiogen/history/append',
+  remove: '/api/dsh-audiogen/history/remove',
+  clear: '/api/dsh-audiogen/history/clear',
+  audio: '/api/dsh-audiogen/history/audio',
+} as const
+
+/** Maximum number of history entries retained host-side (oldest evicted). */
+export const HISTORY_MAX = 50
+
+/** Audio generation modes. */
+export type AudioMode = 'tts' | 'music' | 'sfx'
+
+/** One model mapping in a channel's catalog: display alias → upstream id. */
+export interface ModelMapping {
+  /** User-facing model/voice name (defaults to the upstream id). */
+  alias: string
+  /** Upstream model or voice id sent to the provider. */
+  id: string
+}
+
+/**
+ * One configured audio channel (provider). Secrets never live here — the API
+ * key is stored at `channelSecrets.<channelId>`.
+ */
+export interface ChannelConfig {
+  /** Stable channel id (the channelSecrets dict is keyed by it). */
+  id: string
+  /** Preset provider id this channel was created from ('' = custom). */
+  preset: string
+  /** Display name shown in the list, panel, and Agent guidance. */
+  name: string
+  /** Provider base URL. */
+  apiUrl: string
+  /** The channel's model/voice catalog (alias → upstream id). */
+  models: ModelMapping[]
+}
+
+/** One built-in provider as the settings card consumes it. */
+export interface PresetProviderView {
+  id: string
+  name: string
+  apiUrl: string
+  hint: string
+  models: ModelMapping[]
+}
+
+/** A client → host generate request. */
+export interface GenerateAudioRequest {
+  mode: AudioMode
+  /** User-facing model/voice alias; host maps to upstream id. */
+  model: string
+  /** TTS text or music/sfx prompt. */
+  prompt: string
+  /** Optional voice alias for TTS. */
+  voice?: string
+  /** Optional speaking rate / speed multiplier. */
+  speed?: number
+  /** Requested duration in seconds (music/sfx). */
+  duration?: number
+  /** Output format, e.g. mp3, wav, pcm. */
+  format?: string
+  /** Channel this request targets (host falls back to default). */
+  channelId?: string
+  /** Channel display name snapshot (host-filled). */
+  channel?: string
+  /** Upstream model id actually sent (host-filled from alias mapping). */
+  upstream?: string
+}
+
+/** One generated audio, normalized host-side to base64. */
+export interface GeneratedAudio {
+  /** Raw base64 payload (no data: prefix). */
+  b64: string
+  /** MIME type, e.g. audio/mpeg. */
+  mime: string
+  /** Exact encoded byte length. */
+  bytes: number
+  /** Optional duration in seconds when the API reports one. */
+  duration?: number
+  /** Same-origin URL served by the host ('' when unavailable). */
+  url: string
+  /** Stable audio id / file name. */
+  id: string
+}
+
+/** Successful generate outcome. */
+export interface GenerateAudioResult {
+  outputs: GeneratedAudio[]
+  /** Updated host-persisted history, when returned. */
+  history?: HistoryEntry[]
+  /** Persistence failure after audio was generated. */
+  historyError?: string
+}
+
+/** One audio reference as the browser consumes it. */
+export interface HistoryAudioRef {
+  /** Same-origin URL. */
+  url: string
+  /** MIME type, e.g. audio/mpeg. */
+  mime: string
+  /** Duration in seconds when known. */
+  duration?: number
+}
+
+/** A saved generation as the browser consumes it. */
+export interface HistoryEntry {
+  id: string
+  createdAt: number
+  mode: AudioMode
+  model: string
+  prompt: string
+  voice?: string
+  speed?: number
+  duration?: number
+  format?: string
+  audio: HistoryAudioRef[]
+  channelId?: string
+  channel?: string
+}
+
+/** A history entry the client submits for persistence (audio still carries base64). */
+export interface HistoryEntryInput {
+  id: string
+  createdAt: number
+  mode: AudioMode
+  model: string
+  prompt: string
+  voice?: string
+  speed?: number
+  duration?: number
+  format?: string
+  audio: GeneratedAudio[]
+  channelId?: string
+  channel?: string
+}
+
+/** The plugin settings fields edited by the settings card and panel. */
+export interface AudiogenConfig {
+  enabled?: boolean
+  announceToAgent?: boolean
+  allowAgentAudioGeneration?: boolean
+  channels?: ChannelConfig[]
+  channelSecrets?: Record<string, string>
+  defaultChannelId?: string
+  /** Optional default voice/model alias for quick generation. */
+  defaultModel?: string
+}