xiaoyuan-assistant 0.5.45

package/src/voice/hewoyi.js

@@ -0,0 +1,774 @@
+import { getReceivedCommandAudio, saveReceivedCommandAudio } from './localReceivedTTS.js'
+
+const RECEIVED_COMMAND_TEXT = '收到指令，请您稍等。'
+
+export class HewoyiTTSProvider {
+  constructor(options = {}) {
+    this.apiUrl = options.apiUrl || 'https://api.hewoyi.com/api/ai/audio/speech'
+    this.apiKey = options.apiKey || ''
+    this.voice = options.voice || 'zh-CN-XiaoyiNeural'
+    this.format = options.format || 'mp3'
+    this.speed = options.speed ?? ''
+    this.model = options.model ?? ''
+    this.type = options.type || 'speech'
+    this.requestTimeoutMs = Math.max(2500, Number(options.requestTimeoutMs ?? 7000))
+    this.debug = options.debug !== false
+    this.currentAudio = null
+    this.currentUrl = null
+    this.localReceivedAudio = null
+    this.localReceivedUrl = null
+    this.currentSource = null
+    this.audioContext = null
+    this.receivedCacheBlob = null
+    this.receivedCacheLoaded = false
+    this.receivedCacheLoadPromise = null
+  }
+
+  log(...args) {
+    if (this.debug && typeof console !== 'undefined') console.log('[小园 TTS]', ...args)
+  }
+
+  error(...args) {
+    if (this.debug && typeof console !== 'undefined') console.error('[小园 TTS]', ...args)
+  }
+
+  enabled() {
+    return Boolean(this.apiKey)
+  }
+
+  getAudioContext() {
+    if (typeof window === 'undefined') return null
+    const AudioContextClass = window.AudioContext || window.webkitAudioContext
+    if (!AudioContextClass) return null
+    if (!this.audioContext) this.audioContext = new AudioContextClass()
+    return this.audioContext
+  }
+
+  async unlock() {
+    let contextReady = true
+    const ctx = this.getAudioContext()
+    if (ctx) {
+      try {
+        if (ctx.state === 'suspended') await ctx.resume()
+        contextReady = ctx.state === 'running'
+      } catch (_) {
+        contextReady = false
+      }
+    }
+
+    // 前置提示音优先读取 NPM 包内置的 voice 音频；包内没有时再读取浏览器 IndexedDB。
+    // 当前 voice 第一次没有本地资源时，才走接口并在成功后缓存；后续直接本地播放。
+    try {
+      await this.loadReceivedCommandCache()
+    } catch (error) {
+      this.error('读取本地“收到指令”TTS 缓存失败:', error)
+    }
+
+    return contextReady
+  }
+
+  async loadReceivedCommandCache() {
+    // voice 可能被宿主在运行时切换；切换 voice 后必须重新查该 voice 对应的本地缓存。
+    if (this.receivedCacheVoice !== this.voice) {
+      this.receivedCacheVoice = this.voice
+      this.receivedCacheBlob = null
+      this.receivedCacheLoaded = false
+      this.receivedCacheLoadPromise = null
+    }
+
+    if (this.receivedCacheLoaded) return this.receivedCacheBlob
+    if (this.receivedCacheLoadPromise) return await this.receivedCacheLoadPromise
+
+    this.receivedCacheLoadPromise = getReceivedCommandAudio(this.voice)
+      .then((blob) => {
+        this.receivedCacheBlob = blob
+        this.receivedCacheLoaded = true
+        if (blob) this.log('命中本地“收到指令”TTS缓存，voice:', this.voice, 'size:', blob.size)
+        else this.log('未命中本地“收到指令”TTS缓存，voice:', this.voice)
+        return blob
+      })
+      .catch((error) => {
+        this.receivedCacheLoaded = true
+        this.receivedCacheBlob = null
+        this.error('读取本地“收到指令”TTS缓存失败:', error?.message || error)
+        return null
+      })
+
+    return await this.receivedCacheLoadPromise
+  }
+
+  async cacheReceivedCommandFromResult(result) {
+    if (!result) return false
+
+    let blob = null
+    if (result.kind === 'blob' && result.blob) {
+      blob = result.blob
+    } else if (result.kind === 'url' && result.url) {
+      // 接口返回的 source URL 可以直接播放；如果音频服务器允许 CORS，则顺便把同一份音频落到 IndexedDB。
+      // CORS 不允许时仍保持在线播放，不影响本次请求。
+      try {
+        const response = await fetch(result.url, {
+          method: 'GET',
+          mode: 'cors',
+          cache: 'no-store'
+        })
+        if (response.ok) blob = await response.blob()
+      } catch (error) {
+        this.error('收到指令音频本地缓存失败（不影响当前在线播放）:', error?.message || error)
+        return false
+      }
+    }
+
+    if (!blob || !blob.size) return false
+
+    try {
+      const saved = await saveReceivedCommandAudio(this.voice, blob)
+      if (saved) {
+        this.receivedCacheBlob = blob
+        this.receivedCacheLoaded = true
+        this.log('已缓存“收到指令，请您稍等。”到 IndexedDB，voice:', this.voice, 'size:', blob.size)
+      }
+      return saved
+    } catch (error) {
+      this.error('保存“收到指令”TTS本地缓存失败:', error?.message || error)
+      return false
+    }
+  }
+
+  stop() {
+    this.stopLocalReceivedOnly()
+    if (this.currentSource) {
+      try { this.currentSource.stop(0) } catch (_) {}
+      try { this.currentSource.disconnect() } catch (_) {}
+      this.currentSource = null
+    }
+
+    if (this.currentAudio) {
+      try {
+        this.currentAudio.pause()
+        this.currentAudio.currentTime = 0
+        this.currentAudio.removeAttribute('src')
+        this.currentAudio.load()
+      } catch (_) {}
+      this.currentAudio = null
+    }
+
+    if (this.currentUrl && typeof URL !== 'undefined') {
+      try { URL.revokeObjectURL(this.currentUrl) } catch (_) {}
+      this.currentUrl = null
+    }
+  }
+
+  buildQuery(text) {
+    const params = new URLSearchParams()
+    params.set('key', this.apiKey)
+    params.set('text', String(text || '').slice(0, 4096))
+    params.set('voice', this.voice)
+    params.set('format', this.format)
+    if (this.speed !== '') params.set('speed', this.speed)
+    if (this.model !== '') params.set('model', this.model)
+    params.set('type', this.type)
+    return params
+  }
+
+  async requestAudioSource(text) {
+    if (!this.enabled()) {
+      throw new Error('合我意 TTS 未配置 apiKey')
+    }
+
+    const params = this.buildQuery(text)
+    const url = `${this.apiUrl}?${params.toString()}`
+    this.log('发起请求:', url.replace(/([?&]key=)[^&]*/i, '$1***'))
+
+    let response
+    let timeoutId = null
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : null
+    try {
+      if (controller) timeoutId = window.setTimeout(() => controller.abort(), this.requestTimeoutMs)
+      response = await fetch(url, {
+        method: 'GET',
+        headers: {
+          Accept: 'text/html,application/json,audio/mpeg,audio/wav,audio/*,*/*;q=0.8'
+        },
+        signal: controller?.signal
+      })
+    } catch (error) {
+      this.error('请求没有到达接口:', error)
+      throw new Error(`合我意 TTS 请求失败：${error?.message || error}`)
+    }
+
+    if (timeoutId) window.clearTimeout(timeoutId)
+
+    const contentType = (response.headers.get('content-type') || '').toLowerCase()
+    this.log('接口响应:', response.status, contentType)
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => '')
+      throw new Error(`合我意 TTS 请求失败 ${response.status}${body ? `：${body.slice(0, 500)}` : ''}`)
+    }
+
+    // 直接返回音频：优先返回 Blob
+    if (contentType.startsWith('audio/')) {
+      const blob = await response.blob()
+      return { kind: 'blob', blob }
+    }
+
+    // 当前接口实际返回的是 HTML，例如：
+    // <audio controls><source src="https://.../speech?..." type="audio/mpeg"></audio>
+    // 所以这里不能只按 JSON 解析。
+    const body = await response.text()
+    const trimmed = body.trim()
+
+    if (contentType.includes('text/html') || /<audio\b|<source\b/i.test(trimmed)) {
+      const sourceUrl = this.extractAudioSourceFromHtml(trimmed)
+      if (sourceUrl) {
+        this.log('HTML 音频地址:', sourceUrl)
+        return { kind: 'url', url: sourceUrl }
+      }
+    }
+
+    // 某些环境 content-type 可能不标准，但 body 实际是 JSON
+    try {
+      const payload = JSON.parse(trimmed)
+      return await this.parseAudioResponse(payload)
+    } catch (_) {
+      throw new Error(`合我意 TTS 返回无法解析，原始内容：${trimmed.slice(0, 1200)}`)
+    }
+  }
+
+  extractAudioSourceFromHtml(html) {
+    if (!html) return null
+
+    // 优先 source[src]
+    const sourceMatch = html.match(/<source[^>]+src\s*=\s*["']([^"']+)["']/i)
+    if (sourceMatch?.[1]) {
+      return this.decodeHtmlAttribute(sourceMatch[1])
+    }
+
+    // 再兼容 audio[src]
+    const audioMatch = html.match(/<audio[^>]+src\s*=\s*["']([^"']+)["']/i)
+    if (audioMatch?.[1]) {
+      return this.decodeHtmlAttribute(audioMatch[1])
+    }
+
+    return null
+  }
+
+  decodeHtmlAttribute(value) {
+    return String(value || '')
+      .replace(/&amp;/gi, '&')
+      .replace(/&quot;/gi, '"')
+      .replace(/&#39;/gi, "'")
+      .replace(/&lt;/gi, '<')
+      .replace(/&gt;/gi, '>')
+  }
+
+  findAudioCandidate(value, seen = new Set()) {
+    if (!value || typeof value !== 'object' || seen.has(value)) return null
+    seen.add(value)
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        const found = this.findAudioCandidate(item, seen)
+        if (found) return found
+      }
+      return null
+    }
+
+    for (const [key, item] of Object.entries(value)) {
+      if (typeof item === 'string' && item.trim()) {
+        const normalizedKey = key.toLowerCase().replace(/[-_]/g, '')
+        const candidate = item.trim()
+        const looksLikeAudioKey = /audio|sound|speech|file|url|src|path/.test(normalizedKey)
+        const looksLikeAudioValue = candidate.startsWith('http://') || candidate.startsWith('https://') || candidate.startsWith('data:audio/') || candidate.startsWith('base64,')
+        if (looksLikeAudioValue && (looksLikeAudioKey || candidate.startsWith('data:') || candidate.startsWith('base64,'))) {
+          return candidate
+        }
+      }
+
+      const nested = this.findAudioCandidate(item, seen)
+      if (nested) return nested
+    }
+
+    return null
+  }
+
+  async parseAudioResponse(payload) {
+    const code = payload?.code
+    if (code != null && Number(code) !== 200) {
+      throw new Error(`合我意 TTS 失败：${payload?.msg || JSON.stringify(payload)}`)
+    }
+
+    const candidate = this.findAudioCandidate(payload)
+    this.log('JSON 音频结果:', candidate ? candidate.slice(0, 180) : '未找到')
+
+    if (!candidate) {
+      throw new Error(`合我意 TTS 未返回可播放音频，请检查接口返回：${JSON.stringify(payload).slice(0, 1000)}`)
+    }
+
+    if (candidate.startsWith('data:')) {
+      const response = await fetch(candidate)
+      return await response.blob()
+    }
+
+    if (candidate.startsWith('base64,')) {
+      return await this.base64ToBlob(candidate.slice(7), `audio/${this.format}`)
+    }
+
+    const audioResponse = await fetch(candidate)
+    if (!audioResponse.ok) {
+      throw new Error(`合我意 TTS 音频下载失败 ${audioResponse.status}`)
+    }
+    return await audioResponse.blob()
+  }
+
+  async base64ToBlob(base64, mimeType) {
+    const binary = atob(base64)
+    const bytes = new Uint8Array(binary.length)
+    for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i)
+    return new Blob([bytes], { type: mimeType })
+  }
+
+  async playWithWebAudio(blob, options = {}) {
+    const waitForEnd = options?.waitForEnd === true
+    const ctx = this.getAudioContext()
+    if (!ctx) return false
+
+    try {
+      if (ctx.state === 'suspended') await ctx.resume()
+      if (ctx.state !== 'running') return false
+
+      const buffer = await blob.arrayBuffer()
+      const audioBuffer = await ctx.decodeAudioData(buffer.slice(0))
+
+      return await new Promise((resolve, reject) => {
+        const source = ctx.createBufferSource()
+        source.buffer = audioBuffer
+        source.connect(ctx.destination)
+        this.currentSource = source
+
+        let settled = false
+        const finish = (ok, error) => {
+          if (settled) return
+          settled = true
+          if (this.currentSource === source) this.currentSource = null
+          try { source.disconnect() } catch (_) {}
+          if (error) reject(error)
+          else resolve(ok)
+        }
+
+        source.onended = () => {
+          if (this.currentSource === source) this.currentSource = null
+          try { source.disconnect() } catch (_) {}
+          if (waitForEnd) finish(true)
+        }
+        try {
+          source.start(0)
+          // 普通步骤：source.start() 后立即放行。AI 分析结果：等待 onended。
+          if (!waitForEnd) finish(true)
+        } catch (error) {
+          finish(false, error)
+        }
+      })
+    } catch (error) {
+      this.error('WebAudio 播放失败，准备回退 Audio:', error)
+      return false
+    }
+  }
+
+  async playWithAudioElement(blob, options = {}) {
+    const waitForEnd = options?.waitForEnd === true
+    const minStartHoldMs = Number(options?.minStartHoldMs || 0)
+    const url = URL.createObjectURL(blob)
+    this.currentUrl = url
+
+    return await new Promise((resolve, reject) => {
+      const audio = new Audio()
+      this.currentAudio = audio
+      audio.preload = 'auto'
+      audio.src = url
+
+      let settled = false
+      const finish = (ok, error) => {
+        if (settled) return
+        settled = true
+        if (error) reject(error)
+        else resolve(ok)
+      }
+
+      audio.onended = () => {
+        this.log('AudioElement 播放完成')
+        if (waitForEnd) finish(true)
+      }
+      audio.onerror = () => {
+        this.stop()
+        finish(false, new Error('合我意 TTS 音频播放失败'))
+      }
+
+      // 这里只在真正触发 HTMLMediaElement `playing` 事件后放行。
+      // play() Promise 仅代表浏览器接受了播放请求，并不等于已经开始出声。
+      let playPromise
+      const onPlaying = () => {
+        audio.removeEventListener('playing', onPlaying)
+        this.log('AudioElement 已真正开始播放')
+        if (!waitForEnd) {
+          if (minStartHoldMs > 0) {
+            window.setTimeout(() => finish(true), minStartHoldMs)
+          } else {
+            finish(true)
+          }
+        }
+      }
+      audio.addEventListener('playing', onPlaying, { once: true })
+
+      try {
+        playPromise = audio.play()
+      } catch (err) {
+        audio.removeEventListener('playing', onPlaying)
+        this.stop()
+        finish(false, err)
+        return
+      }
+
+      if (playPromise?.catch) {
+        playPromise.catch((err) => {
+          audio.removeEventListener('playing', onPlaying)
+          this.stop()
+          finish(false, err)
+        })
+      }
+    })
+  }
+
+  async playReceivedCommandLocal(options = {}) {
+    const waitForEnd = options?.waitForEnd === true
+
+    if (!this.receivedCacheLoaded) {
+      await this.loadReceivedCommandCache()
+    }
+
+    if (!this.receivedCacheBlob) return false
+
+    // “收到指令，请您稍等”使用独立 Audio 通道。
+    // 后续步骤的 TTS 不再调用 stop() 时把这条前置提示音一并切掉，
+    // 否则多步骤指令会出现日志命中本地缓存、但耳朵没听到的情况。
+    return await this.playLocalReceivedElement(this.receivedCacheBlob, { waitForEnd })
+  }
+
+  async playLocalReceivedElement(blob, options = {}) {
+    const waitForEnd = options?.waitForEnd === true
+    if (!(blob instanceof Blob) || !blob.size) return false
+
+    this.stopLocalReceivedOnly()
+
+    const url = URL.createObjectURL(blob)
+    this.localReceivedUrl = url
+    const audio = new Audio()
+    this.localReceivedAudio = audio
+    audio.preload = 'auto'
+    audio.playsInline = true
+    audio.src = url
+
+    return await new Promise((resolve) => {
+      let settled = false
+      const finish = (ok) => {
+        if (settled) return
+        settled = true
+        if (waitForEnd) this.stopLocalReceivedOnly()
+        resolve(ok)
+      }
+
+      const onPlaying = () => {
+        audio.removeEventListener('playing', onPlaying)
+        this.log('本地“收到指令”音频已真正开始播放')
+        // 只要真正开始播放就放行后续流程，不等待整段语音结束。
+        if (!waitForEnd) finish(true)
+      }
+      audio.addEventListener('playing', onPlaying, { once: true })
+      audio.onended = () => {
+        if (this.localReceivedAudio === audio) this.localReceivedAudio = null
+        if (this.localReceivedUrl === url) {
+          try { URL.revokeObjectURL(url) } catch (_) {}
+          this.localReceivedUrl = null
+        }
+        if (waitForEnd) finish(true)
+      }
+      audio.onerror = (event) => {
+        this.error('本地“收到指令”音频播放失败:', event)
+        finish(false)
+      }
+
+      let playPromise
+      try {
+        playPromise = audio.play()
+      } catch (error) {
+        finish(false)
+        return
+      }
+      if (playPromise?.catch) {
+        playPromise.catch((error) => {
+          this.error('本地“收到指令”音频 play() 失败:', error)
+          finish(false)
+        })
+      }
+    })
+  }
+
+  stopLocalReceivedOnly() {
+    if (this.localReceivedAudio) {
+      try { this.localReceivedAudio.pause() } catch (_) {}
+      try { this.localReceivedAudio.currentTime = 0 } catch (_) {}
+      try { this.localReceivedAudio.removeAttribute('src') } catch (_) {}
+      try { this.localReceivedAudio.load() } catch (_) {}
+      this.localReceivedAudio = null
+    }
+    if (this.localReceivedUrl) {
+      try { URL.revokeObjectURL(this.localReceivedUrl) } catch (_) {}
+      this.localReceivedUrl = null
+    }
+  }
+
+  async playBlobForGate(blob, options = {}) {
+    const waitForEnd = options?.waitForEnd === true
+    const localReceived = options?.localReceived === true
+    // 固定“收到指令”提示音优先使用 HTMLAudioElement。
+    // 原因：WebAudio 在 source.start() 后立即 resolve，再被下一条 TTS stop()，
+    // 浏览器可能还没来得及把首个音频帧送到扬声器，表现为“日志显示播放，但用户听不到”。
+    if (localReceived) {
+      return await this.playWithAudioElement(blob, {
+        waitForEnd,
+        minStartHoldMs: waitForEnd ? 0 : 120
+      })
+    }
+
+    const played = await this.playWithWebAudio(blob, { waitForEnd })
+    if (played) return true
+    return await this.playWithAudioElement(blob, { waitForEnd })
+  }
+
+  async playWithSource(url, options = {}) {
+    const waitForEnd = options?.waitForEnd === true
+    const isLocalReceived = options?.localReceived === true
+    if (!url) return false
+
+    // 普通网络音频只替换上一条“动态播报”，不要把独立的本地“收到指令”提示音切掉。
+    this.stopCurrentSpeechOnly()
+
+    return await new Promise((resolve) => {
+      const audio = isLocalReceived && this.localReceivedAudio
+        ? this.localReceivedAudio
+        : new Audio()
+
+      this.currentAudio = audio
+      if (!isLocalReceived) {
+        audio.preload = 'auto'
+        audio.playsInline = true
+        audio.src = url
+      } else {
+        audio.preload = 'auto'
+        audio.playsInline = true
+        if (audio.src !== new URL(url, window.location.href).href) {
+          audio.src = url
+          audio.load()
+        } else if (audio.readyState === 0) {
+          audio.load()
+        }
+      }
+
+      let settled = false
+      let fallbackTimer = null
+      const finish = (ok, error) => {
+        if (settled) return
+        settled = true
+        if (fallbackTimer) window.clearTimeout(fallbackTimer)
+        if (error) {
+          if (this.currentAudio === audio) this.currentAudio = null
+          this.error(isLocalReceived ? '本地“收到指令”音频播放失败:' : 'Audio URL 播放失败:', error)
+        }
+        resolve(ok)
+      }
+
+      const onPlaying = () => {
+        audio.removeEventListener('playing', onPlaying)
+        this.log(isLocalReceived ? '本地“收到指令”音频已真正开始播放' : 'Audio URL 已真正开始播放:', url)
+        if (!waitForEnd) finish(true)
+      }
+      audio.addEventListener('playing', onPlaying, { once: true })
+      audio.onended = () => {
+        if (this.currentAudio === audio) this.currentAudio = null
+        if (waitForEnd) finish(true)
+      }
+      audio.onerror = () => finish(false, new Error('音频元素播放失败'))
+
+      let playPromise
+      try {
+        audio.currentTime = 0
+        playPromise = audio.play()
+      } catch (err) {
+        finish(false, err)
+        return
+      }
+      if (playPromise?.catch) {
+        playPromise.catch((err) => finish(false, err))
+      }
+
+      // 某些浏览器在本地资源很短或缓存命中时，事件顺序可能异常；
+      // readyState 已经可播放时，用 requestAnimationFrame 再检查一次。
+      if (!waitForEnd && audio.readyState >= 3) {
+        fallbackTimer = window.setTimeout(() => {
+          if (!settled && !audio.paused && audio.currentTime > 0) finish(true)
+        }, 80)
+      }
+    })
+  }
+
+  stopCurrentSpeechOnly() {
+    if (this.currentSource) {
+      try { this.currentSource.stop(0) } catch (_) {}
+      try { this.currentSource.disconnect() } catch (_) {}
+      this.currentSource = null
+    }
+    if (this.currentAudio) {
+      try { this.currentAudio.pause() } catch (_) {}
+      try { this.currentAudio.currentTime = 0 } catch (_) {}
+      try { this.currentAudio.removeAttribute('src') } catch (_) {}
+      try { this.currentAudio.load() } catch (_) {}
+      this.currentAudio = null
+    }
+    if (this.currentUrl && typeof URL !== 'undefined') {
+      try { URL.revokeObjectURL(this.currentUrl) } catch (_) {}
+      this.currentUrl = null
+    }
+  }
+
+  async speakReceivedCommandAsync() {
+    const value = RECEIVED_COMMAND_TEXT
+
+    // 这是独立于普通 TTS 的异步通道：绝不阻塞 manager.run。
+    // 当前 voice 有本地包内资源/IndexedDB 时，直接播放；没有时才后台请求一次并缓存。
+    try {
+      await this.loadReceivedCommandCache()
+
+      if (this.receivedCacheBlob) {
+        this.log('异步播放本地“收到指令”TTS，不请求网络，voice:', this.voice)
+        void this.playReceivedCommandLocal({ waitForEnd: false }).catch((error) => {
+          this.error('异步播放本地“收到指令”失败:', error?.message || error)
+        })
+        return true
+      }
+
+      if (!this.enabled()) {
+        return false
+      }
+
+      this.log('异步首次获取“收到指令”TTS，voice:', this.voice)
+      const result = await this.requestAudioSource(value)
+      if (result?.kind === 'url' && result.url) {
+        void this.playWithSource(result.url, { waitForEnd: false }).catch((error) => {
+          this.error('异步播放“收到指令”TTS失败:', error?.message || error)
+        })
+        void this.cacheReceivedCommandFromResult(result)
+        return true
+      }
+      if (result?.kind === 'blob' && result.blob) {
+        void this.playBlobForGate(result.blob, { waitForEnd: false }).catch((error) => {
+          this.error('异步播放“收到指令”TTS失败:', error?.message || error)
+        })
+        void this.cacheReceivedCommandFromResult(result)
+        return true
+      }
+    } catch (error) {
+      this.error('异步前置“收到指令”TTS失败:', error?.message || error)
+    }
+
+    // 不阻塞主流程；浏览器原生 TTS 作为最后兼容由 SpeechService 自己决定。
+    return false
+  }
+
+  async speak(text, options = {}) {
+    const waitForEnd = options?.waitForEnd === true
+    const value = String(text || '').trim()
+    if (!value || !this.enabled()) return false
+
+    this.stopCurrentSpeechOnly()
+
+    // 固定前置提示音：当前 voice 优先命中 NPM 包内置音频，其次命中浏览器 IndexedDB。
+    // 同 voice 已有本地资源：完全不请求 API。
+    // 同 voice 没有本地资源：第一次正常请求 TTS，播放后异步缓存；后续直接本地播放。
+    if (value.replace(/[，。！？、,.!?\s]/g, '') === RECEIVED_COMMAND_TEXT.replace(/[，。！？、,.!?\s]/g, '')) {
+      await this.loadReceivedCommandCache()
+
+      if (this.receivedCacheBlob) {
+        this.log('使用本地“收到指令”TTS缓存，不请求网络，voice:', this.voice)
+        const played = await this.playReceivedCommandLocal({ waitForEnd })
+        if (played) return true
+        this.error('本地“收到指令”缓存播放失败，切换浏览器原生 TTS')
+        return await this.speakWithBrowser(value, { waitForEnd })
+      }
+
+      this.log('当前 voice 没有本地缓存，第一次调用合我意 TTS，voice:', this.voice)
+      try {
+        const result = await this.requestAudioSource(value)
+
+        // 首次请求先播放；缓存作为后台任务，不能拖慢“收到指令”门禁。
+        if (result?.kind === 'url' && result.url) {
+          const played = await this.playWithSource(result.url, { waitForEnd })
+          if (played) {
+            void this.cacheReceivedCommandFromResult(result)
+            return true
+          }
+        } else if (result?.kind === 'blob' && result.blob) {
+          const played = await this.playBlobForGate(result.blob, { waitForEnd })
+          if (played) {
+            void this.cacheReceivedCommandFromResult(result)
+            return true
+          }
+        }
+      } catch (error) {
+        this.error('首次“收到指令”TTS请求失败，切换浏览器原生 TTS:', error?.message || error)
+      }
+
+      return await this.speakWithBrowser(value, { waitForEnd })
+    }
+
+    this.log('开始播报:', value)
+
+    const result = await this.requestAudioSource(value)
+
+    // HTML 返回的是 <source src="...">，优先直接使用接口返回的音频地址播放。
+    // 不先 fetch 这个 URL，避免再次触发 CORS 导致 WebAudio 无法读取跨域音频。
+    if (result?.kind === 'url' && result.url) {
+      const played = await this.playWithSource(result.url, { waitForEnd })
+      if (played) return true
+
+      // URL 直接播放失败时，再尝试 fetch + Blob（有 CORS 时可用）
+      try {
+        const audioResponse = await fetch(result.url, { mode: 'cors' })
+        if (audioResponse.ok) {
+          const blob = await audioResponse.blob()
+          const webAudioPlayed = await this.playWithWebAudio(blob, { waitForEnd })
+          if (webAudioPlayed) return true
+          return await this.playWithAudioElement(blob, { waitForEnd })
+        }
+      } catch (error) {
+        this.error('音频 URL 读取失败:', error)
+      }
+      return false
+    }
+
+    if (result?.kind === 'blob' && result.blob) {
+      const webAudioPlayed = await this.playWithWebAudio(result.blob, { waitForEnd })
+      if (webAudioPlayed) {
+        this.log('WebAudio 已开始播放，放行后续业务')
+        return true
+      }
+
+      const played = await this.playWithAudioElement(result.blob)
+      if (played) this.log('AudioElement 已开始播放，放行后续业务')
+      return played
+    }
+
+    return false
+  }
+
+}