dsh-music-player 0.3.2 → 0.3.4

package/README.md

@@ -15,7 +15,7 @@ DeepSeek Harness 本地音乐/小说播放插件。
 - 实时 7 段频谱可视化（解码音频包络驱动）
 - 播放时申请屏幕唤醒锁，防止听歌时熄屏/休眠（支持 Wake Lock 的浏览器，如 Chrome/Edge）
 - 播放列表面板可自由拖动，右下角可拖拽调整大小，位置与尺寸跨刷新记忆
-- AI 讲书：本地 `.txt` 小说经 MiMo TTS 合成朗读，自动识别**书名/前言/章节/尾声**结构，播放条带**章节目录**跳转、章节切歌，可选 4 种中文 AI 声音（默认白桦）
+- AI 讲书：本地 `.txt` 小说经 MiMo TTS 合成朗读，自动识别**书名/前言/章节/尾声**结构，播放条带**章节目录**跳转（打开即定位到当前正在播放的章节）、章节切歌，可选 4 种中文 AI 声音（默认白桦）
 - `music_play` 模型工具：agent 可按关键词播放本地音乐，也可按小说名启动 AI 讲书
 - 支持的格式：`mp3 / m4a / m4b / aac / flac / wav / ogg / opus / webm / aiff`（自动递归扫描子目录，上限 500 首）
 - **自建歌单**：可新建多个歌单，从本地文件（支持多选、可跨目录）添加歌曲；播放条爱心按钮一键收藏到默认歌单「我最喜欢」；歌单作为播放来源时，顺序/乱序循环只在该歌单内进行
@@ -108,7 +108,7 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
 1. 打开播放面板，切到「小说」标签，点「选择小说目录」选定包含 `.txt` 的目录（默认与音乐目录相同）。
 2. 点击某一本小说开始朗读；也可让 agent 用 `music_play` 工具按小说名播放（如「播放《中国制造》」）。
 3. 播放条上的讲书控制：
-   - **章节目录**（📖 按钮）：自动识别全书结构（书名/前言/章节/尾声），弹出目录，点击任意章节即从该章开头朗读
+   - **章节目录**（📖 按钮）：自动识别全书结构（书名/前言/章节/尾声），点击弹出**位于按钮正上方**的目录（自动定位到当前正在播放的章节），点击任意章节即从该章开头朗读
    - **后退 / 前进**：讲书模式下跳上一章 / 下一章（音乐模式下仍是上一首 / 下一首）
    - **AI 声音**：点音量按钮，在弹层选择声音——冰糖（女）、茉莉（女）、苏打（男）、白桦（男，默认）
 4. 刷新页面后从上次位置续读（断点续播）。
@@ -152,6 +152,9 @@ AI 语音目前仅支持 xiaomi 提供方（限时免费）。请先在 DSH 模
 **讲书播放时点后退/前进没反应？**
 讲书模式下后退/前进是跳上一章/下一章；如果当前小说没有识别出章节结构（目录按钮提示"暂无章节结构"），则无法跳章，只能整本顺序播。
 
+**听书偶尔"没声音但时间还在走"？**
+这种一般是某一段的合成结果异常（返回了退化/静音音频），或瞬时合成失败。0.3.3 起 Host 端会严格校验合成音频（拒绝空数据/非 PCM 等退化 WAV）并自动重试一次瞬时失败，同时把每次合成结果记录在诊断日志里。若再遇到，可访问 `http://<DSH地址>/dsh-music/tts-logs` 查看最近 60 条合成记录（含失败原因、退化音频事件），据此定位具体是哪个块出的问题。
+
 **想支持更多音频格式？**
 格式支持由 Host 端 `AUDIO_TYPES` 表驱动，在 `lib/index.js` 里加扩展名与 MIME 即可（播放器本身用浏览器原生 `<audio>` 解码，最终能否播放还取决于浏览器对该编码的支持）。
 

package/lib/client.js

@@ -631,6 +631,7 @@ window.__ModuleLoader__.load({
       const id = currentBookId();
       if (id !== null) {
         unlockAutoplay();
+        bookAutoRetried = false; // manual retry resets the auto-retry budget
         set({ bookError: '', bookBuffering: true, bookBufferingSince: Date.now() });
         playBookFrom(id, bookFromRef, false);
       }
@@ -655,6 +656,9 @@ window.__ModuleLoader__.load({
     let lastPosSaveAt = 0;     // throttle for the periodic playback-state save
     let restoredMusicPos = null; // restored music position to display until the audio truly reaches it
     let bookRestorePos = -1;   // restored book's in-chunk position, seeked on play
+    // 当前块是否已自动重试过一次（瞬时 LLM 合成失败时先静音重试一次，
+    // 只有重试仍失败才弹错误 + 手动重试）。成功播放后复位。
+    let bookAutoRetried = false;
     const preAudio = new Audio();
     preAudio.preload = 'auto';
     const bookUrl = (id, from) => {
@@ -815,7 +819,7 @@ window.__ModuleLoader__.load({
       }
     }
     // `from` lets the toc jump straight to a chapter's chunk index.
-    function playBook(id, from = 0) { unlockAutoplay(); bookTotal = -1; bookBufferedFrom = -1; bookBaseTime = 0; bookRestorePos = -1; playBookFrom(id, from, false); saveCurrentBookPlayback(); }
+    function playBook(id, from = 0) { unlockAutoplay(); bookTotal = -1; bookBufferedFrom = -1; bookBaseTime = 0; bookRestorePos = -1; bookAutoRetried = false; playBookFrom(id, from, false); saveCurrentBookPlayback(); }
     // Play a novel from its saved progress when available (e.g. switching to
     // music and back), otherwise start fresh from the beginning. Explicit
     // chapter jumps keep using playBook(id, fromChunk) and are unaffected.
@@ -841,6 +845,8 @@ window.__ModuleLoader__.load({
       if (store.currentId === null || !String(store.currentId).startsWith('book:')) return false;
       const id = String(store.currentId).slice('book:'.length);
       if (bookFromRef + 1 < bookTotal) {
+        // 进入新块：每个块各拥有一次自动重试的机会。
+        bookAutoRetried = false;
         const endedDur = Number.isFinite(audio.duration) ? audio.duration : (audio.currentTime || 0);
         if (Number.isFinite(endedDur)) bookBaseTime += endedDur;
         playBookFrom(id, bookFromRef + 1, true);
@@ -1006,6 +1012,7 @@ window.__ModuleLoader__.load({
       audio.removeAttribute('src');
       audio.load();
       stopBookHelper();
+      bookAutoRetried = false;
       set({ currentId: null, currentName: null, playing: false, position: 0, duration: 0, pendingId: null, pendingName: null, vizState: 'ok', bookBuffering: false, bookError: '', bookBufferingSince: 0, bookBufferingSilent: false, tocOpen: false, currentSection: '', voiceSwitching: false });
       clearPref(PREF_PLAYBACK);
       if (stoppedBook !== null) clearBookPlayback(stoppedBook.name);
@@ -1105,6 +1112,9 @@ window.__ModuleLoader__.load({
         // next block until the whole book is done, then stop (never step into
         // the music list). Book ids are 'book:'-prefixed.
         if (store.currentId !== null && String(store.currentId).startsWith('book:')) {
+          // 切块进行中（bookBuffering 为真，新块还没开始播放）忽略旧块的
+          // ended：防止陈旧事件重复触发导致跳块/时间空走。
+          if (store.bookBuffering) return;
           if (!maybeAdvanceBook()) stop();
           return;
         }
@@ -1121,6 +1131,15 @@ window.__ModuleLoader__.load({
         // clear the "合成中…" spinner and surface a real message instead of
         // leaving the bar stuck buffering forever.
         if (store.currentId !== null && String(store.currentId).startsWith('book:')) {
+          // 瞬时 LLM 合成失败：先自动静音重试一次当前块（听书不中断），
+          // 重试仍失败才进入错误 + 手动重试。
+          if (!bookAutoRetried) {
+            bookAutoRetried = true;
+            const retryId = String(store.currentId).slice('book:'.length);
+            unlockAutoplay();
+            playBookFrom(retryId, bookFromRef, true);
+            return;
+          }
           set({ bookBuffering: false, bookBufferingSince: 0, playing: false, bookError: '\u8bb2\u4e66\u97f3\u9891\u83b7\u53d6\u5931\u8d25\uff0c\u8bf7\u91cd\u8bd5' });
           // Best-effort: fetch the URL to show the server's actual diagnostic
           // (e.g. "TTS 请求失败 401 ..."), which the <audio> error object lacks.
@@ -1238,6 +1257,13 @@ window.__ModuleLoader__.load({
         bookBuffering: false, bookBufferingSilent: false, bookError: '', bookBufferingSince: 0,
       });
       bookRestorePos = pos;
+      // 恢复后立即加载章节结构并计算当前章节：让播放条章节徽标与章节目录
+      // 立刻显示正在播放的章节（而不是等用户点 ▶、playBookFrom 才开始加载）。
+      // ensureBookToc 内部会 set bookToc；这里再补上 currentSection。
+      void ensureBookToc(book.id).then((meta) => {
+        if (meta === null || meta.sections.length === 0) return;
+        set({ currentSection: sectionForChunk(meta.sections, from) });
+      });
       // Refresh the chunk total in the background (the book file may have
       // changed since the save); fall back to the saved total on failure.
       const savedTotal = bookTotal;
@@ -1348,6 +1374,13 @@ window.__ModuleLoader__.load({
       return React.createElement('svg', { className: cls, width: 12, height: 12, viewBox: '0 0 24 24', fill: 'currentColor', 'aria-hidden': true },
         React.createElement('path', { d: 'M12 3v10.55A4 4 0 1 0 14 17V7h4V3h-6z' }));
     }
+    // 讲书（AI 听书）时名称前的话筒图标，贴合「朗读/播讲」功能，
+    // 与音乐的音符图标区分。
+    function MicIcon(props) {
+      const cls = props.className || '';
+      return React.createElement('svg', { className: cls, width: 12, height: 12, viewBox: '0 0 24 24', fill: 'currentColor', 'aria-hidden': true },
+        React.createElement('path', { d: 'M12 14c1.66 0 2.99-1.34 2.99-3L15 5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm5.3-3c0 3-2.54 5.1-5.3 5.1S6.7 14 6.7 11H5c0 3.41 2.72 6.23 6 6.72V21h2v-3.28c3.28-.48 6-3.3 6-6.72h-1.7z' }));
+    }
 
     // ---- components ----
     // Custom vertical volume slider. The native <input type=range> cannot be
@@ -1472,8 +1505,9 @@ window.__ModuleLoader__.load({
           onClick: () => { const t = resolvePlayable(s.currentId); if (t !== null) loadEnvelope(t.id, t.url); },
         }, '\u9891\u8c31\u4e0d\u53ef\u7528\uff0c\u70b9\u51fb\u91cd\u8bd5');
       }
-      const note = React.createElement(MusicNote, { className: 'dsh-music-note' });
       const isBook = s.currentId !== null && String(s.currentId).startsWith('book:');
+      // 名称前的图标：讲书用话筒图标，音乐用音符图标（空闲态无曲目 = 音乐）。
+      const note = React.createElement(isBook ? MicIcon : MusicNote, { className: 'dsh-music-note' });
       // While a novel chunk is being synthesized, show a live "合成中… Ns"
       // counter (so the wait is transparent, not an endless spinner) and, on
       // error, the real message plus a retry button. Music keeps its old UI.
@@ -1515,14 +1549,18 @@ window.__ModuleLoader__.load({
           hasTrack ? React.createElement('button', { className: 'dsh-music-bar-btn', title: isBook ? '\u4e0b\u4e00\u7ae0' : '\u4e0b\u4e00\u9996', onClick: () => (isBook ? stepBook(1) : step(1)) }, '\u23ed') : null,
           hasTrack ? React.createElement('button', { className: 'dsh-music-bar-btn', title: '\u505c\u6b62', onClick: stop }, '\u23f9') : null,
           // 章节目录按钮：仅讲书（book）时出现，点击弹出章节列表并可跳章。
-          // 与音量/播放列表按钮同款圆形样式（dsh-music-mode-trigger）。
-          isBook ? React.createElement('button', {
-            className: 'dsh-music-mode-trigger' + (s.tocOpen ? ' active' : ''),
-            title: '\u7ae0\u8282\u76ee\u5f55',
-            onClick: openToc,
-          }, React.createElement('svg', {
-            viewBox: '0 0 24 24', width: 16, height: 16, fill: 'currentColor', 'aria-hidden': true,
-          }, React.createElement('path', { d: 'M4 6h16v2H4V6zm0 5h16v2H4v-2zm0 5h10v2H4v-2z' }))) : null,
+          // 与音量/播放模式按钮同款圆形样式（dsh-music-mode-trigger）；弹层用
+          // 与音量/播放模式同款的「相对容器 + 绝对定位」锚在按钮正上方。
+          isBook ? React.createElement('div', { className: 'dsh-music-toc-trigger' },
+            React.createElement('button', {
+              className: 'dsh-music-mode-trigger' + (s.tocOpen ? ' active' : ''),
+              title: '\u7ae0\u8282\u76ee\u5f55',
+              onClick: openToc,
+            }, React.createElement('svg', {
+              viewBox: '0 0 24 24', width: 16, height: 16, fill: 'currentColor', 'aria-hidden': true,
+            }, React.createElement('path', { d: 'M4 6h16v2H4V6zm0 5h16v2H4v-2zm0 5h10v2H4v-2z' }))),
+            React.createElement(BookTocPanel, null),
+          ) : null,
           // 音乐播放模式按钮：仅在音乐语境（非讲书）显示，与章节目录按钮互斥。
           !isBook ? React.createElement(ModeDropdown, null) : null,
           React.createElement('div', { className: 'dsh-music-bar-vol', ref: volRef },
@@ -1599,6 +1637,7 @@ window.__ModuleLoader__.load({
     function BookTocPanel() {
       const s = useStore();
       const ref = useRef(null);
+      const listRef = useRef(null);
       useEffect(() => {
         if (!s.tocOpen) return;
         const onDown = (e) => {
@@ -1607,6 +1646,15 @@ window.__ModuleLoader__.load({
         document.addEventListener('mousedown', onDown);
         return () => document.removeEventListener('mousedown', onDown);
       }, [s.tocOpen]);
+      // 打开章节目录时定位到正在播放的章节：把高亮的当前章节滚动进可视区，
+      // 而不是从列表顶部开始。依赖 bookToc（打开时可能先为空、随后异步到达）。
+      useEffect(() => {
+        if (!s.tocOpen) return;
+        const list = listRef.current;
+        if (list === null) return;
+        const active = list.querySelector('.dsh-music-toc-item.active');
+        if (active !== null && typeof active.scrollIntoView === 'function') active.scrollIntoView({ block: 'nearest' });
+      }, [s.tocOpen, s.bookToc]);
       if (!s.tocOpen) return null;
       if (s.currentId === null || !String(s.currentId).startsWith('book:')) return null;
       const id = currentBookId();
@@ -1629,11 +1677,14 @@ window.__ModuleLoader__.load({
       const body = (s.bookToc || []).length > 0
         ? rows
         : React.createElement('div', { className: 'dsh-music-empty' }, '\u6682\u65e0\u7ae0\u8282\u7ed3\u6784\uff08\u8be5\u4e66\u65e0\u6cd5\u8bc6\u522b\u5206\u8282\u3002\uff09');
+      // 弹层用 CSS 定位在「章节目录」按钮正上方（与音量/播放模式弹窗同款：
+      // 相对容器 + position:absolute + bottom:calc(100%+6px) 居中），见
+      // .dsh-music-toc-trigger / .dsh-music-toc 样式。
       return React.createElement('div', { className: 'dsh-music-toc', ref },
         React.createElement('div', { className: 'dsh-music-toc-head' },
           React.createElement('span', { className: 'dsh-music-toc-title' }, '\u7ae0\u8282\u76ee\u5f55'),
           React.createElement('button', { className: 'dsh-music-icon-btn', title: '\u5173\u95ed', onClick: closeToc }, '\u2715')),
-        React.createElement('div', { className: 'dsh-music-toc-list' }, body),
+        React.createElement('div', { className: 'dsh-music-toc-list', ref: listRef }, body),
       );
     }
     function PlayerPanel() {
@@ -2187,10 +2238,6 @@ window.__ModuleLoader__.load({
         { name: 'shell.overlay', id: 'music-player-panel', order: 20 },
         () => React.createElement(PlayerPanel),
       )), 'music-player: overlay panel');
-      ctx.effect(() => slots.inject('shell.overlay', () => slots.register(
-        { name: 'shell.overlay', id: 'music-player-book-toc', order: 19 },
-        () => React.createElement(BookTocPanel),
-      )), 'music-player: book toc panel');
 
       ctx.effect(() => () => clearInterval(intentTimer), 'music-player: intent poll stop');
     }
@@ -2295,7 +2342,10 @@ window.__ModuleLoader__.load({
       // 讲书时章节名是主信息：占满剩余弹性空间、尽量完整显示；书名让出空间（可截断）。
       '.dsh-music-bar.book .dsh-music-bar-name { max-width: 24%; }\n' +
       '.dsh-music-bar-section { margin-left: 8px; flex: 0 1 auto; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; color: var(--dsw-alias-label-secondary, #8a8f98); font-size: 11px; border: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,0.25)); border-radius: 6px; padding: 0 6px; line-height: 16px; }\n' +
-      '.dsh-music-toc { position: fixed; right: 24px; bottom: 148px; width: 380px; max-height: 60vh; display: flex; flex-direction: column; gap: 8px; padding: 12px; background: var(--dsw-alias-bg-overlay, #1e1f22); border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.35)); border-radius: 12px; box-shadow: 0 12px 32px rgba(0,0,0,0.35); color: var(--dsw-alias-label-primary, #e6e6e6); font-size: 13px; z-index: 1000; }\n' +
+      '.dsh-music-toc-trigger { position: relative; flex: none; display: inline-flex; align-self: center; }\n' +
+      // 章节目录弹层：与音量/播放模式弹窗同款定位——相对容器 + 绝对定位，
+      // bottom:calc(100%+6px) 让其出现在按钮正上方，left:50% 居中。
+      '.dsh-music-toc { position: absolute; left: 50%; transform: translateX(-50%); bottom: calc(100% + 6px); width: 380px; max-height: 60vh; display: flex; flex-direction: column; gap: 8px; padding: 12px; background: var(--dsw-alias-bg-overlay, #1e1f22); border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.35)); border-radius: 12px; box-shadow: 0 12px 32px rgba(0,0,0,0.35); color: var(--dsw-alias-label-primary, #e6e6e6); font-size: 13px; z-index: 60; }\n' +
       '.dsh-music-toc-head { display: flex; align-items: center; gap: 6px; }\n' +
       '.dsh-music-toc-title { font-weight: 600; margin-right: auto; }\n' +
       '.dsh-music-toc-list { flex: 1; overflow-y: auto; display: flex; flex-direction: column; gap: 2px; }\n' +

package/lib/index.js

@@ -580,6 +580,9 @@ export function apply(ctx) {
   // Reuse the api key the user already configured in DSH. DSH stores configured
   // provider keys in ~/.dsh/.credentials.yaml keyed by the same name as
   // settings.yaml's apiKeyEnv, so read it there (falling back to a real env var).
+  // Since DSH v1 the file nests keys under a refs: block (two-space indent,
+  // root "version: 1"); older builds used a flat layout with keys at column 0.
+  // Allow leading whitespace so both layouts resolve.
   const readCredential = async (envName) => {
     if (!envName) return null
     if (process.env[envName]) return process.env[envName]
@@ -588,7 +591,7 @@ export function apply(ctx) {
       if (file === null || !existsSync(file)) return null
       const lines = readFileSync(file, 'utf8').split(/\r?\n/)
       for (const ln of lines) {
-        const m = new RegExp('^' + envName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*[:=]\\s*(.+?)\\s*$').exec(ln)
+        const m = new RegExp('^\\s*' + envName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*[:=]\\s*(.+?)\\s*$').exec(ln)
         if (m) return m[1]
       }
       return null
@@ -672,7 +675,7 @@ export function apply(ctx) {
   // Synthesize a chunk of prose into a Buffer of wav audio (non-streaming, format=wav).
   const synthesize = async (text, voice) => {
     const { baseURL, key } = await resolveTts()
-    if (!key) throw new Error('未配置 xiaomi/MiMo TTS 模型（缺少 api key）')
+    if (!key) throw new Error('未配置 xiaomi/MiMo 提供方（缺少 api key）')
     const body = {
       model: MIMO_DEFAULT_MODEL,
       messages: [
@@ -706,16 +709,59 @@ export function apply(ctx) {
     const data = json && json.choices && json.choices[0] && json.choices[0].message && json.choices[0].message.audio && json.choices[0].message.audio.data
     if (typeof data !== 'string') throw new Error('TTS 响应缺少音频数据')
     const buf = Buffer.from(data, 'base64')
-    // Verify it is actually a WAVE file so the browser <audio> can decode it;
-    // otherwise report a precise diagnosis instead of feeding it invalid bytes.
-    if (buf.length < 12 || buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WAVE') {
-      throw new Error('TTS 返回的不是有效的 WAV 音频（前4字节=' + (buf.length >= 4 ? buf.toString('ascii', 0, 4) : '<空>') + '）——请改用支持 wav 的模型或检查 API 返回')
-    }
+    // Verify it is actually a playable WAVE file so the browser <audio> can
+    // decode it; otherwise report a precise diagnosis instead of feeding it
+    // invalid bytes. A shallow RIFF/WAVE check is NOT enough: a header-only or
+    // non-PCM wav passes it and the browser then "plays" silence while the
+    // reader's clock keeps advancing — the exact "没声音但时长还在走" symptom.
+    // Parse the fmt + data chunks and reject degenerate files outright.
+    validateWav(buf)
     // Return the MiMo audio as-is: the 24kHz source played clearly in the smoke
     // test, and our naive linear-interpolation resample to 48kHz degraded
     // intelligibility. Revisit resampling only if it becomes the confirmed cause.
     return buf
   }
+  // Strict WAV sanity check: refuses to serve audio the browser would decode
+  // but hear as silence/broken output. Throws with a precise message so the
+  // client surfaces it (with retry) instead of playing a silent chunk.
+  const validateWav = (buf) => {
+    if (buf.length < 12 || buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WAVE') {
+      throw new Error('TTS 返回的不是有效的 WAV 音频（前4字节=' + (buf.length >= 4 ? buf.toString('ascii', 0, 4) : '<空>') + '）——请改用支持 wav 的模型或检查 API 返回')
+    }
+    // Walk the RIFF chunks to locate fmt + data.
+    let fmtFormat = -1
+    let fmtRate = -1
+    let fmtCh = -1
+    let fmtBits = -1
+    let dataSize = -1
+    let dataStart = -1
+    let off = 12
+    while (off + 8 <= buf.length) {
+      const id = buf.toString('ascii', off, off + 4)
+      const sz = buf.readUInt32LE(off + 4)
+      if (id === 'fmt ' && sz >= 16) {
+        fmtFormat = buf.readUInt16LE(off + 8)
+        fmtCh = buf.readUInt16LE(off + 10)
+        fmtRate = buf.readUInt32LE(off + 12)
+        fmtBits = buf.readUInt16LE(off + 22)
+      } else if (id === 'data') {
+        dataSize = sz
+        dataStart = off + 8 // payload begins right after the 8-byte chunk header
+      }
+      off += 8 + sz + (sz % 2)
+      if (off > buf.length) break
+    }
+    const actualData = (dataSize >= 0 && dataStart >= 0) ? Math.min(dataSize, Math.max(0, buf.length - dataStart)) : 0
+    const problems = []
+    if (fmtFormat !== 1) problems.push('非 PCM 格式(fmt=' + fmtFormat + ')')
+    if (!(fmtRate >= 4000 && fmtRate <= 192000)) problems.push('采样率异常(' + fmtRate + 'Hz)')
+    if (!(fmtCh >= 1 && fmtCh <= 8)) problems.push('声道数异常(' + fmtCh + ')')
+    if (dataSize < 2 || actualData < 2) problems.push('音频数据为空(data=' + dataSize + ')')
+    if (problems.length > 0) {
+      logTts({ kind: 'degenerate', detail: problems.join('，') })
+      throw new Error('TTS 返回的 WAV 异常（' + problems.join('，') + '）——该段无法朗读，请重试或检查 API')
+    }
+  }
 
   // In-memory synthesized-audio cache + in-flight dedup.
   // The browser requests the same chunk URL more than once per listen (the
@@ -728,11 +774,21 @@ export function apply(ctx) {
   const ttsAudioCache = new Map()
   const ttsAudioInflight = new Map()
   const MAX_TTS_CACHE_CHUNKS = 80
+  // Recent TTS synthesis diagnostics (successes with timing + every failure and
+  // every degenerate-wav rejection), served at /dsh-music/tts-logs so the user
+  // can confirm what a "没声音但时长还在走" episode was actually caused by.
+  const ttsLog = []
+  const MAX_TTS_LOG = 60
+  const logTts = (entry) => {
+    ttsLog.push({ ts: Date.now(), ...entry })
+    if (ttsLog.length > MAX_TTS_LOG) ttsLog.shift()
+  }
   const synthesizeCached = async (cacheKey, text, voice) => {
     const hit = ttsAudioCache.get(cacheKey)
     if (hit !== undefined) return hit
     const inFlight = ttsAudioInflight.get(cacheKey)
     if (inFlight !== undefined) return inFlight
+    const t0 = Date.now()
     const p = synthesize(text, voice)
       .then((buf) => {
         ttsAudioInflight.delete(cacheKey)
@@ -741,9 +797,14 @@ export function apply(ctx) {
           const oldest = ttsAudioCache.keys().next().value
           ttsAudioCache.delete(oldest)
         }
+        logTts({ kind: 'ok', key: cacheKey, ms: Date.now() - t0, bytes: buf.length, head: text.slice(0, 12) })
         return buf
       })
-      .catch((err) => { ttsAudioInflight.delete(cacheKey); throw err })
+      .catch((err) => {
+        ttsAudioInflight.delete(cacheKey)
+        logTts({ kind: 'error', key: cacheKey, ms: Date.now() - t0, error: String((err && err.message) || err).slice(0, 160), head: text.slice(0, 12) })
+        throw err
+      })
     ttsAudioInflight.set(cacheKey, p)
     return p
   }
@@ -1069,6 +1130,12 @@ export function apply(ctx) {
         writeJson(res, it || null)
         return
       }
+      // TTS 合成诊断日志（最近 60 条，含每次失败/退化 WAV），便于排查
+      // 「没声音但时长继续走」等异常。
+      if (pathname === '/dsh-music/tts-logs' && req.method === 'GET') {
+        writeJson(res, { logs: ttsLog.slice() })
+        return
+      }
       // AI 讲书：一本书的元信息（总块数）或某个块的 wav。
       //   GET /dsh-music/book/<id>/meta  -> { id, name, total, size }  (JSON)
       //   GET /dsh-music/book/<id>?from=n -> chunk n as wav audio

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-music-player",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "DeepSeek Harness 本地音乐 + AI 讲书插件：Host 扫描音乐目录并以 HTTP 流式提供音频、解析 .txt 小说结构并经 MiMo TTS 合成朗读，浏览器侧提供播放条/播放面板/章节目录跳转/多声音选择/实时频谱，并注册 music_play 模型工具",
   "type": "module",
   "main": "lib/index.js",