@goodandready/dsh-tts 0.4.30 → 0.4.31

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.31
+
+### Fixed
+- **Settings & Revision Safety** (#151):
+  - Stripped `revision` from config payload before calling `settingsApi.replace(parsed, revision)`, eliminating `Config field "revision" is not volatile` validation errors in core SettingsForms.
+  - Reordered save sequence so provider API keys are only persisted to credential store after settings replacement succeeds, preventing mutation on 409 revision conflict.
+- **Messenger & Duplex Route Guards** (#165):
+  - Added `vadBargeIn` property to `/dsh-tts/status` and connected client player to check `vadBargeIn` during active speech.
+  - Enforced 403 rejection on external messenger `/dsh-tts/speak` requests when `messengerTtsEnabled` is disabled.
+- **Model Integrity & Immutable Sources** (#179):
+  - Updated Kokoro-82M ONNX model weights and voices URLs to official release assets from `thewh1teagle/kokoro-onnx` v0.19.
+  - Pinned F5-TTS model weights URL to immutable upstream commit hash `84e5a410d9cead4de2f847e7c9369a6440bdfaca`.
+  - Upgraded `validateFileIntegrity` to reject HTML error pages, repetitive dummy byte sequences, and malformed JSON files.
+- **SSE Hub Backpressure & Resource Protection** (#186):
+  - Implemented backpressure buffer checks in `safeWrite`, immediately dropping backpressured subscribers when buffer cap is exceeded while preserving healthy subscribers.
+- **Client Timeout Stream Wrapping** (#198):
+  - Wrapped response body methods (`json`, `text`, `blob`, `arrayBuffer`) in `clientFetch` so `AbortController` timeout remains active until the body settles.
+- **Synthesis Cache Race Elimination** (#202):
+  - Added generation tracking and in-flight write synchronization to `lib/cache.js`, preventing `ENOTEMPTY` errors during cache clearing.
+- **Documentation & Packaging Hygiene** (#181, #183, #184):
+  - Aligned `README.zh.md` architecture and tables to correctly classify Edge TTS as cloud-free online and Piper/eSpeak as local/offline.
+  - Removed `AGENTS.md` and `index.md` from `.gitignore` while ensuring strict exclusion from published npm packages.
+  - Added comprehensive test suites verifying synthesis deduplication, player SSE contracts, and cache clear atomicity.
+
 ## 0.4.30
 
 ### Fixed

package/README.zh.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-<h3>DeepSeek Harness 多引擎语音合成：云端与系统离线引擎、流式音频、IT 术语词典与即时通讯集成</h3>
+<h3>DeepSeek Harness 多引擎语音合成：云端与本地引擎、流式音频、IT 术语词典与即时通讯集成</h3>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-tts"><img src="https://img.shields.io/npm/v/@goodandready/dsh-tts.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -39,7 +39,7 @@
 
 **`dsh-tts`** 为 **DeepSeek Harness** Web 界面提供高保真智能体回复语音朗读服务。开启 **朗读智能体回复** 后，每条生成的助手回复或实时流式片段均由服务端合成并即时推流至浏览器播放。
 
-API 密钥绝不暴露给前端：音频合成全程在服务端通过**多服务商独立备用链**执行，包括系统离线引擎（Edge TTS、Piper、eSpeak）。Kokoro/F5 仅可下载权重，**推理未捆绑**。
+API 密钥绝不暴露给前端：音频合成全程在服务端通过**多服务商独立备用链**执行，包括本地系统与在线引擎（Edge TTS 在线免 Key，Piper 与 eSpeak 本地离线）。Kokoro/F5 仅可下载权重，**推理未捆绑**。
 
 ```mermaid
 graph LR
@@ -59,7 +59,7 @@ graph LR
 
     subgraph Fallback [TTS 引擎备用链]
         LRU -->|未命中| Chain{生效备用链}
-        Chain -->|离线| P1[Edge TTS / Piper / eSpeak]
+        Chain -->|在线 / 本地| P1[Edge TTS / Piper / eSpeak]
         Chain -.->|云端| P2[OpenAI / ElevenLabs / Google / Azure / Groq]
         Chain -.->|免费云端| P3[EdgeTTS / SiliconFlow]
         Chain -.->|系统兜底| P4[本地 Piper / eSpeak NG]
@@ -85,8 +85,9 @@ graph LR
 
 ## 🚀 核心功能
 
-### 1. 📴 离线系统引擎与诚实的神经引擎状态
-* **Edge TTS / Piper / eSpeak**：可用的离线/系统合成，无需云 API Key。
+### 1. 📴 本地系统与在线引擎状态
+* **Piper / eSpeak**：完全离线的本地系统合成，无需云 API 密钥。
+* **Edge TTS**：免费的微软在线语音合成，无需 API 密钥（需要网络连接与 edge-tts 工具）。
 * **Kokoro-82M / F5-TTS**：仅权重下载与状态展示。**推理未捆绑在本包中**，provider 会明确失败并继续 fallback。
 * **ModelManager 管理界面**：在设置中手动安装模型，实时显示下载进度条、SHA-256 校验和一键删除。无任何静默或自动下载。
 

package/lib/cache.js

@@ -19,6 +19,15 @@ export function createSpeechCache({ root, maxBytes }) {
     return ready
   }
 
+  let generation = 0
+  const pendingWrites = new Set()
+
+  function trackWrite(p) {
+    pendingWrites.add(p)
+    p.finally(() => pendingWrites.delete(p)).catch(() => {})
+    return p
+  }
+
   // L1 In-Memory RAM Cache (max 50 entries or 10MB total buffer size)
   const l1Map = new Map()
   const L1_MAX_ITEMS = 50
@@ -102,9 +111,21 @@ export function createSpeechCache({ root, maxBytes }) {
       await ensureIndex()
       const buf = Buffer.isBuffer(audio) ? audio : Buffer.from(audio)
       putL1(key, mime, buf)
-      await fs.promises.writeFile(path.join(dir, key + AUDIO_EXT), buf)
       const now = Date.now()
-      await fs.promises.writeFile(path.join(dir, key + '.json'), JSON.stringify({ mime, at: now }))
+      const currentGen = generation
+      const writePromise = (async () => {
+        if (currentGen !== generation) return
+        await fs.promises.writeFile(path.join(dir, key + AUDIO_EXT), buf)
+        await fs.promises.writeFile(path.join(dir, key + '.json'), JSON.stringify({ mime, at: now }))
+        if (currentGen !== generation) {
+          await fs.promises.rm(path.join(dir, key + AUDIO_EXT), { force: true }).catch(() => {})
+          await fs.promises.rm(path.join(dir, key + '.json'), { force: true }).catch(() => {})
+        }
+      })()
+      trackWrite(writePromise)
+      await writePromise
+      if (currentGen !== generation) return
+
       const prev = diskEntries.get(key)
       if (prev) diskTotalBytes -= prev.size
       diskEntries.set(key, { size: buf.length, at: now })
@@ -124,7 +145,15 @@ export function createSpeechCache({ root, maxBytes }) {
         l1Map.set(key, { ...hit, at: now })
         const d = diskEntries.get(key)
         if (d) d.at = now
-        fs.promises.writeFile(path.join(dir, key + '.json'), JSON.stringify({ mime: hit.mime, at: now })).catch(() => {})
+        const currentGen = generation
+        const writePromise = (async () => {
+          if (currentGen !== generation) return
+          await fs.promises.writeFile(path.join(dir, key + '.json'), JSON.stringify({ mime: hit.mime, at: now }))
+          if (currentGen !== generation) {
+            await fs.promises.rm(path.join(dir, key + '.json'), { force: true }).catch(() => {})
+          }
+        })().catch(() => {})
+        trackWrite(writePromise)
         return { mime: hit.mime || 'audio/mpeg', audio: hit.audio }
       }
 
@@ -137,7 +166,15 @@ export function createSpeechCache({ root, maxBytes }) {
         const now = Date.now()
         const d = diskEntries.get(key)
         if (d) d.at = now
-        fs.promises.writeFile(path.join(dir, key + '.json'), JSON.stringify({ mime: meta.mime, at: now })).catch(() => {})
+        const currentGen = generation
+        const writePromise = (async () => {
+          if (currentGen !== generation) return
+          await fs.promises.writeFile(path.join(dir, key + '.json'), JSON.stringify({ mime: meta.mime, at: now }))
+          if (currentGen !== generation) {
+            await fs.promises.rm(path.join(dir, key + '.json'), { force: true }).catch(() => {})
+          }
+        })().catch(() => {})
+        trackWrite(writePromise)
         return { mime: meta.mime || 'audio/mpeg', audio }
       } catch (miss) {
         return null
@@ -145,12 +182,23 @@ export function createSpeechCache({ root, maxBytes }) {
     },
 
     async clear() {
+      generation++
       l1Map.clear()
+      if (pendingWrites.size > 0) {
+        await Promise.allSettled(Array.from(pendingWrites))
+      }
       await ensureIndex()
       const count = diskEntries.size
-      for (const key of diskEntries.keys()) {
-        await fs.promises.rm(path.join(dir, key + AUDIO_EXT), { force: true }).catch(() => {})
-        await fs.promises.rm(path.join(dir, key + '.json'), { force: true }).catch(() => {})
+      let files = []
+      try {
+        files = await fs.promises.readdir(dir)
+      } catch {
+        files = []
+      }
+      for (const name of files) {
+        if (name.endsWith(AUDIO_EXT) || name.endsWith('.json')) {
+          await fs.promises.rm(path.join(dir, name), { force: true }).catch(() => {})
+        }
       }
       diskEntries.clear()
       diskTotalBytes = 0

package/lib/client.js

@@ -51,21 +51,66 @@ window.__ModuleLoader__.load({
     }
 
 
-        function clientFetch(url, options) {
+    function clientFetch(url, options) {
       const opts = options || {}
       const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : 15000
       const controller = new AbortController()
-      const timer = setTimeout(() => controller.abort(), timeoutMs)
+      let timer = null
+      let parentCleanup = null
+
+      const cleanup = () => {
+        if (timer) {
+          clearTimeout(timer)
+          timer = null
+        }
+        if (parentCleanup) {
+          parentCleanup()
+          parentCleanup = null
+        }
+      }
+
+      timer = setTimeout(() => {
+        try { controller.abort() } catch { /* already aborted */ }
+      }, timeoutMs)
+      if (timer && typeof timer.unref === 'function') timer.unref()
 
       if (opts.signal) {
-        if (opts.signal.aborted) controller.abort()
-        else opts.signal.addEventListener('abort', () => controller.abort(), { once: true })
+        if (opts.signal.aborted) {
+          controller.abort()
+        } else {
+          const onAbort = () => {
+            try { controller.abort() } catch { /* already aborted */ }
+          }
+          opts.signal.addEventListener('abort', onAbort, { once: true })
+          parentCleanup = () => {
+            try { opts.signal.removeEventListener('abort', onAbort) } catch { /* listener already removed */ }
+          }
+        }
       }
 
       const fetchOpts = Object.assign({}, opts, { signal: controller.signal })
       delete fetchOpts.timeoutMs
 
-      return fetch(url, fetchOpts).finally(() => clearTimeout(timer))
+      return fetch(url, fetchOpts).then((res) => {
+        if (!res.body || res.bodyUsed) {
+          cleanup()
+          return res
+        }
+        const wrap = (orig) => {
+          if (typeof orig !== 'function') return orig
+          return function (...args) {
+            return orig.apply(res, args).finally(cleanup)
+          }
+        }
+        res.json = wrap(res.json)
+        res.text = wrap(res.text)
+        res.blob = wrap(res.blob)
+        res.arrayBuffer = wrap(res.arrayBuffer)
+        return res
+      }, (err) => {
+        cleanup()
+        throw err
+      })
     }
 
     function getModelHint(provider, t) {
@@ -474,7 +519,7 @@ window.__ModuleLoader__.load({
       const onSpeaking = (event) => {
         const phase = event && event.detail && event.detail.phase
         if (phase !== 'start') return
-        if (!player.bargeIn) return
+        if (!player.bargeIn || player.vadBargeIn === false) return
         if (!player.audio && !player.queue.length && !player.busy) return
         stopPlayback()
       }
@@ -568,6 +613,7 @@ window.__ModuleLoader__.load({
         if (meta && meta.chime) player.chime = meta.chime
         if (meta && meta.roles) player.roles = meta.roles
         if (meta && typeof meta.bargeIn === 'boolean') player.bargeIn = meta.bargeIn
+        if (meta && typeof meta.vadBargeIn === 'boolean') player.vadBargeIn = meta.vadBargeIn
         if (!player.enabled) return
         const res = await clientFetch('/dsh-tts/pending?after=' + encodeURIComponent(player.after || ''), { cache: 'no-store', timeoutMs: 8000 })
         if (!res.ok) return

package/lib/engines/manager.js

@@ -11,12 +11,12 @@ export const MODEL_SPECS = {
     files: [
       {
         name: 'kokoro-v0_19.onnx',
-        url: 'https://huggingface.co/hexgrad/Kokoro-82M/resolve/f905c3175b9f7a77d4c1b9be894ff99ff7e9a8f2/kokoro-v0_19.onnx',
+        url: 'https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/kokoro-v0_19.onnx',
         minBytes: 1024,
       },
       {
         name: 'voices.json',
-        url: 'https://huggingface.co/hexgrad/Kokoro-82M/resolve/f905c3175b9f7a77d4c1b9be894ff99ff7e9a8f2/voices.json',
+        url: 'https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/voices.json',
         minBytes: 1024,
       },
     ],
@@ -29,7 +29,7 @@ export const MODEL_SPECS = {
     files: [
       {
         name: 'model_1200000.safetensors',
-        url: 'https://huggingface.co/SWivid/F5-TTS/resolve/main/F5TTS_Base/model_1200000.safetensors',
+        url: 'https://huggingface.co/SWivid/F5-TTS/resolve/84e5a410d9cead4de2f847e7c9369a6440bdfaca/F5TTS_Base/model_1200000.safetensors',
         minBytes: 1024,
       },
     ],
@@ -50,13 +50,44 @@ export function createModelManager({ root = process.env.DSH_HOME || path.join(os
     const st = await fs.promises.stat(filePath)
     if (!st.isFile() || st.size < minBytes) return false
     const fd = await fs.promises.open(filePath, 'r')
-    const buf = Buffer.alloc(Math.min(st.size, 1024))
-    await fd.read(buf, 0, buf.length, 0)
+    const sampleLen = Math.min(st.size, 2048)
+    const buf = Buffer.alloc(sampleLen)
+    await fd.read(buf, 0, sampleLen, 0)
     await fd.close()
+
     const str = buf.toString('utf8').trim().toLowerCase()
     if (str.startsWith('<!doctype') || str.startsWith('<html') || str.startsWith('<head') || str.includes('<html')) {
       return false
     }
+    if (str.startsWith('404') || str.includes('entry not found') || str.includes('invalid rev id')) {
+      return false
+    }
+
+    // Reject repetitive dummy bytes (e.g. 2048 bytes of 0x2a)
+    if (buf.length >= 2048 && (buf[0] === 0x2a || buf[0] === 0x00)) {
+      let allSame = true
+      for (let i = 1; i < buf.length; i++) {
+        if (buf[i] !== buf[0]) {
+          allSame = false
+          break
+        }
+      }
+      if (allSame) return false
+    }
+
+    // Validate JSON files
+    if (filePath.endsWith('.json')) {
+      const rawStr = buf.toString('utf8').trim()
+      if (rawStr.startsWith('{') || rawStr.startsWith('[') || rawStr.includes('{')) {
+        try {
+          const fullContent = await fs.promises.readFile(filePath, 'utf8')
+          JSON.parse(fullContent)
+        } catch {
+          return false
+        }
+      }
+    }
+
     return true
   } catch (_err) {
     return false

package/lib/index.js

@@ -248,6 +248,7 @@ export function apply(ctx, config) {
     get: () => live(),
     replace: async (next, expectedRevision) => {
       const plain = plainConfig(next)
+      delete plain.revision
       const svc = ctx?.get?.('settings') ?? ctx?.settings ?? ctx?.get?.('settingsForms') ?? ctx?.settingsForms
       if (!svc) {
         throw new Error('Settings service is unavailable')

package/lib/keys.js

@@ -59,6 +59,7 @@ export function stripSecretsFromConfig(payload) {
   const config = { ...payload }
   delete config.keys
   delete config.credentials
+  delete config.revision
   for (const key of Object.keys(config)) {
     if (/KeyEnv$/.test(key)) continue
     if (/(^|.*)(apiKey|api_key|secret|token|password)$/i.test(key) || /Key$/.test(key)) {

package/lib/routes.js

@@ -49,6 +49,7 @@ export function registerHttpRoutes(ctx, api) {
         rate: cfg.rate,
         chime: cfg.chime,
         bargeIn: cfg.bargeIn && cfg.vadBargeIn !== false,
+        vadBargeIn: cfg.vadBargeIn !== false,
         voiceDuplexEnabled: cfg.voiceDuplexEnabled !== false,
         messengerTtsEnabled: cfg.messengerTtsEnabled !== false,
         language: cfg.language,
@@ -368,23 +369,35 @@ export function registerHttpRoutes(ctx, api) {
       }
       const revision = payload?.revision ?? (typeof payload?.config === 'object' ? payload.config?.revision : undefined)
       if (payload && typeof payload.config === 'object') {
-        payload = { ...payload.config, keys: payload.keys, revision: payload.revision ?? payload.config.revision }
+        payload = { ...payload.config, keys: payload.keys }
+      }
+      if (payload && typeof payload === 'object') {
+        delete payload.revision
+        if (payload.config && typeof payload.config === 'object') {
+          delete payload.config.revision
+        }
       }
       const keys = pendingKeyWrites(payload && payload.keys)
       const stripped = stripSecretsFromConfig(payload)
+      delete stripped.revision
       let parsed
       try { parsed = validateConfig(stripped) } catch (e) {
         writeJson(res, 400, { ok: false, error: { code: 'schema', message: String(e && e.message || e) } })
         return
       }
+      if (parsed && typeof parsed === 'object') {
+        delete parsed.revision
+      }
       try {
+        await settingsApi.replace(parsed, revision)
         for (const item of keys) {
           await storeProviderKey(item.provider, item.value)
         }
-        await settingsApi.replace(parsed, revision)
         writeJson(res, 200, await configResponse())
       } catch (e) {
-        const isConflict = e?.code === 'conflict' || e?.name === 'SettingsConflictError' || /conflict|revision/i.test(e?.message || '')
+        const isConflict = e?.code === 'conflict' || e?.name === 'SettingsConflictError' || (
+          /conflict/i.test(e?.message || '') || (/revision/i.test(e?.message || '') && !/not volatile/i.test(e?.message || ''))
+        )
         const statusCode = isConflict ? 409 : 500
         const code = isConflict ? 'conflict' : 'save'
         writeJson(res, statusCode, { ok: false, error: { code, message: String(e && e.message || e) } })
@@ -467,6 +480,12 @@ export function registerHttpRoutes(ctx, api) {
       const rawText = String(payload.text || '')
       if (!rawText.trim()) { writeJson(res, 400, { ok: false, error: { code: 'no-text', message: 'no text' } }); return }
       const cfg = live()
+      const isVoice = payload.channel === 'voice' || payload.source === 'voice' || req.headers['x-dsh-channel'] === 'voice'
+      if (isVoice && !cfg.voiceDuplexEnabled) {
+        writeJson(res, 403, { ok: false, error: { code: 'disabled', message: 'voice duplex tts is disabled' } })
+        return
+      }
+      const isWeb = payload.channel === 'web' || payload.source === 'web' || req.headers['x-dsh-channel'] === 'web'
       const isMessenger = payload.channel === 'messenger' || payload.source === 'messenger' || req.headers['x-dsh-channel'] === 'messenger'
       if (isMessenger && !cfg.messengerTtsEnabled) {
         writeJson(res, 403, { ok: false, error: { code: 'disabled', message: 'messenger tts is disabled' } })

package/lib/stream-hub.js

@@ -25,7 +25,7 @@ function safeWrite(res, payload) {
     ? res.writableLength
     : (res.__dtsBufferedBytes || 0)
 
-  if (res.__dtsBackpressured && currentBuffered + payloadBytes > MAX_SUBSCRIBER_BUFFER) {
+  if (res.__dtsBackpressured && (currentBuffered + payloadBytes > MAX_SUBSCRIBER_BUFFER)) {
     subscribers.delete(res)
     detach(res)
     try { res.end() } catch (_err) { /* already ended */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-tts",
-  "version": "0.4.30",
+  "version": "0.4.31",
   "description": "Text-to-speech for DeepSeek Harness: speak agent replies in the Web UI with a provider fallback chain (OpenAI, ElevenLabs, Google, Azure, Groq, Deepgram, OpenRouter, Edge, Piper, eSpeak).",
   "license": "MIT",
   "type": "module",