dsh-music-player 0.6.1 → 0.6.2

package/README.md

@@ -13,7 +13,7 @@ DeepSeek Harness 本地音乐/小说播放插件。
 - 本地音频流式播放（HTTP Range），刷新后断点续播
 - 顺序播放、单曲循环、乱序播放三种模式
 - 实时 8 段频谱可视化（真实 FFT 频段，解码时离线计算、跟随播放位置）
-- **实时歌词/字幕**：本地音频自动匹配同名 `.lrc` 逐行显示；在线 QQ 歌曲自动取官方歌词（外语歌带逐句翻译「原文 ／ 翻译」）；AI 讲书时显示当前朗读句子（逐句滚动）。歌词/字幕显示在播放条频谱之后、时长之前，仅在闲置（控件组折叠）时展示，鼠标进入操作时自动收起
+- **实时歌词/字幕**：本地音频自动匹配同名 `.lrc` 逐行显示；**本地没有同名 `.lrc` 时自动在线兜底**（QQ 音乐官方歌词 → LRCLIB 免费同步歌词，结果按曲目缓存避免重复请求）；在线 QQ 歌曲自动取官方歌词（外语歌带逐句翻译「原文 ／ 翻译」）；AI 讲书时显示当前朗读句子（逐句滚动）。歌词/字幕显示在播放条频谱之后、时长之前，仅在闲置（控件组折叠）时展示，鼠标进入操作时自动收起；**AI 讲书还有一条「已读字符/全书字符」的全书进度细线**（按已读字数实时计算，不依赖合成时长，切块不回退，操作时再显示「N%」）
 - 播放时申请屏幕唤醒锁，防止听歌时熄屏/休眠（支持 Wake Lock 的浏览器，如 Chrome/Edge）
 - 播放列表面板可自由拖动，右下角可拖拽调整大小，位置与尺寸跨刷新记忆
 - AI 讲书：本地 `.txt` / `.epub` 小说经 MiMo TTS 合成朗读，自动识别**书名/前言/章节/尾声**结构，播放条带**章节目录**跳转（打开即定位到当前正在播放的章节）、章节切歌，可选 4 种中文 AI 声音（默认白桦）
@@ -147,6 +147,7 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
    - **章节目录**（📖 按钮）：自动识别全书结构（书名/前言/章节/尾声），点击弹出**位于按钮正上方**的目录（自动定位到当前正在播放的章节），点击任意章节即从该章开头朗读
    - **后退 / 前进**：讲书模式下跳上一章 / 下一章（音乐模式下仍是上一首 / 下一首）
    - **AI 声音**：点音量按钮，在弹层选择声音——冰糖（女）、茉莉（女）、苏打（男）、白桦（男，默认）
+   - **全书进度**：播放条底部有一条「已读字符/全书字符」的进度细线，操作时显示「N%」——按已读字数实时计算，无需先合成全书就能给出稳定的整体进度（切块不回退；字符量来自源文本，因此总长总是可知，而总时长得合成完才知道），刷新页面后也会立即恢复显示（无需先点播放）
 4. 刷新页面后从上次位置续读（断点续播）。
 
 支持的格式：
@@ -179,7 +180,7 @@ dsh plugin --profile <profile> add ./   # 或直接改 profile 里的 link 目
 点面板顶部「选择音乐目录」，选一个包含音频文件的实际目录（默认 `~/Music`）。目录路径不可读或不存在时会回退到默认目录而不是报错。
 
 **改了音乐目录/新增了歌曲，但列表没更新？**
-播放器在启动时扫描，并在每次“选择音乐目录”时重扫。想强制刷新当前目录，重新打开一次面板或点一次目录设置即可（扫描上限 500 首、递归子目录深度上限 4 层）。
+播放器在启动时扫描一次，并支持手动重扫：点「选择音乐目录」旁边的新增 **「刷新」按钮**，会重新遍历当前目录并更新列表（音乐与小说通用；无需重选目录）。扫描上限 500 首、递归子目录深度上限 4 层。
 
 **`music_play` 工具说"音乐库为空"？**
 说明还没有可用的音乐目录。请先打开播放面板，点「选择音乐目录」配置一次。
@@ -193,6 +194,9 @@ AI 语音目前仅支持 xiaomi 提供方（限时免费）。请先在 DSH 模
 **听书偶尔"没声音但时间还在走"？**
 这种一般是某一段的合成结果异常（返回了退化/静音音频），或瞬时合成失败。0.3.3 起 Host 端会严格校验合成音频（拒绝空数据/非 PCM 等退化 WAV）并自动重试一次瞬时失败，同时把每次合成结果记录在诊断日志里。若再遇到，可访问 `http://<DSH地址>/dsh-music/tts-logs` 查看最近 60 条合成记录（含失败原因、退化音频事件），据此定位具体是哪个块出的问题。
 
+**本地音乐没有 .lrc，歌词是怎么来的？**
+播放器会**在线兜底取词**：先用文件名（可带歌手/时长）在 QQ 音乐匿名接口匹配官方歌词（外语歌带逐句翻译），QQ 无果再查 LRCLIB（免费公开歌词库，返回同步 LRC）。结果按曲目在进程内缓存（正命中 6 小时 / 空命中 30 分钟），避免重复请求；无匹配或失败时静默保持无歌词，不影响播放。歌词为版权内容，仅供个人试听。
+
 **想支持更多音频格式？**
 格式支持由 Host 端 `AUDIO_TYPES` 表驱动，在 `lib/index.js` 里加扩展名与 MIME 即可（播放器本身用浏览器原生 `<audio>` 解码，最终能否播放还取决于浏览器对该编码的支持）。
 

package/lib/client.js

@@ -453,6 +453,9 @@ window.__ModuleLoader__.load({
       // 空串 = 未取到（非 QQ / 取链失败），播放条只显示「QQ音乐」。
       currentQuality: '',
       playing: false, position: 0, duration: 0, volume: 0.8,
+      // AI 讲书全书进度（0..1）：已读字符 / 全书字符。Host 的 charOffsets 就绪前为 0；
+      // 总字符数无需合成即可知，因此能给出稳定的「读到哪了」比例（时长占比做不到）。
+      bookProgress: 0,
       panelOpen: false, loading: false, error: null, pendingId: null, pendingName: null,
       mode: 'order', vizState: 'ok', tab: 'music',
       // true once the Host prefs snapshot is loaded (volume/mode/playback from
@@ -485,6 +488,8 @@ window.__ModuleLoader__.load({
       prompt: null,
       // 自定义确认弹窗（替代浏览器 confirm）：{ title, message, onOk, okText, danger } | null。
       confirm: null,
+      // 「加入歌单」成功/失败提示：{ text, ok, id } | null。面板窗口内居中显示，2s 自动消失。
+      toast: null,
     };
     const listeners = new Set();
     function set(patch) {
@@ -505,6 +510,19 @@ window.__ModuleLoader__.load({
       }, []);
       return snap;
     }
+    // 「加入歌单」成功/失败提示：统一在面板窗口内居中显示（成功绿色 / 失败红色），
+    // 2 秒后自动消失。连续触发时只保留最后一条（前一条立即被顶掉）。
+    let toastTimer = null;
+    let toastSeq = 0;
+    function showToast(text, ok) {
+      const id = ++toastSeq;
+      set({ toast: { text, ok: !!ok, id } });
+      if (toastTimer !== null) clearTimeout(toastTimer);
+      toastTimer = setTimeout(() => {
+        toastTimer = null;
+        if (store.toast && store.toast.id === id) set({ toast: null });
+      }, 2000);
+    }
     // 自定义输入弹窗（替代浏览器 prompt）：openPrompt 打开、closePrompt 关闭，
     // onOk(value) 在用户点「确定」时收到去空格后的值；点「取消」/关闭不回调。
     let promptSeq = 0;
@@ -585,7 +603,7 @@ window.__ModuleLoader__.load({
         method: 'POST', cache: 'no-store',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ id, paths }),
-      }).then((r) => r.json()).then((r) => { if (r && r.playlist) updatePlaylistInStore(r.playlist); if (then) then(r); }).catch(() => {});
+      }).then((r) => r.json()).then((r) => { if (r && r.playlist) updatePlaylistInStore(r.playlist); if (then) then(r); }).catch(() => { if (then) then(null); });
     }
     function apiPlaylistRemove(id, paths, then) {
       fetch('/dsh-music/playlist/remove', {
@@ -787,13 +805,19 @@ window.__ModuleLoader__.load({
       if (store.currentId === null) { clearPref(PREF_PLAYBACK); return; }
       if (String(store.currentId).startsWith('book:')) { saveCurrentBookPlayback(); return; }
       if (String(store.currentId).startsWith('qq:')) {
-        // 在线曲目：保存曲目 + 队列（刷新后可恢复）。流地址每次经代理重新获取，可续播。
+        // 在线曲目：保存曲目 + 队列 + 播放位置（刷新/重启后可从中途续播）。
+        // 流地址每次经代理重新获取（Range 透传），所以位置 seek 始终有效。
         const mid = String(store.currentId).slice(3);
         const song = (store.qqQueue || []).find((t) => String(t.songmid || t.id) === mid);
         if (!song) return;
         savePref(PREF_PLAYBACK, JSON.stringify({
           kind: 'qq', id: store.currentId, name: store.currentName,
           artists: store.currentArtists || [],
+          // 与本地曲目一致：恢复中的曲目还没真正加载，currentTime 可能短暂为 0，
+          // 用钉住的 restoredMusicPos 覆盖，避免把已恢复的位置写成 0。
+          position: (restoredMusicPos !== null && restoredMusicPos > 0) ? restoredMusicPos : (audio.currentTime || 0),
+          // 顺手持久化已知时长：恢复时浏览器尚未加载元数据，避免显示 "0:00"。
+          duration: Number.isFinite(audio.duration) ? audio.duration : 0,
           queue: store.qqQueue || [], source: store.qqSource || '在线',
           ts: Date.now(),
         }));
@@ -834,6 +858,11 @@ window.__ModuleLoader__.load({
     // 右引号字符：断在句尾标点后、若紧跟右引号则连同引号一起收进本行，避免把 「”」
     // 单独留在一行。
     const SUB_QUOTE_CLOSE = new Set('”」』"'.split(''));
+    // 断行「容忍」余量：当必须按 SUBTITLE_MAX 边界硬切时，允许本行再多收几个有效字，
+    // 以落到边界后不远处的一个自然停顿（断句标点）上，或吞掉本块末尾的极小残留——这样
+    // 每行更完整，避免「……他说」被硬切、也避免末尾残留一个极短行。仅在越过边界后累计
+    // 额外有效字 ≤ 该值时生效，防止行无限变长。
+    const SUBTITLE_TOLERANCE = 3;
     const isSubLowSurrogate = (code) => code >= 0xDC00 && code <= 0xDFFF;
     // 标点集合：不计入「字数」（仍是显示内容，只是长度统计时不算字）。
     const SUB_PUNCT = new Set('，。！？…：；、“”‘’（）《》〈〉［］【】—～·`~!@#$%^&*()-_=+[]{};\':",.<>/?\\|'.split(''));
@@ -849,7 +878,9 @@ window.__ModuleLoader__.load({
     // 把「当前讲书块文本」直接切成字幕行：每行 ≤ SUBTITLE_MAX（去标点字数），优先在
     // 逗号/顿号/句号等自然停顿处换行（不避让引号——长对话也按内部标点优雅切断，而不是
     // 触发兜底硬切），断口后紧跟的右引号会随本行收走。仅当窗口内没有任何停顿标点时才
-    // 按字数边界断。标点不计字数；空白/换行折叠为空格。
+    // 按字数边界硬切；硬切前先做「容忍」：若边界后不远处就是断句标点，或本块马上就要
+    // 结束，就把断行位置往后挪一点，让这一行更完整（见 SUBTITLE_TOLERANCE）。标点不计
+    // 字数；空白/换行折叠为空格。
     function wrapSubtitleLine(text) {
       const raw = String(text || '');
       const fold = (s) => s.replace(/\s+/g, ' ').trim();
@@ -872,7 +903,29 @@ window.__ModuleLoader__.load({
         for (let j = start; j < end; j++) {
           if (SUBTITLE_CLAUSE_BREAKS.indexOf(raw[j]) !== -1) brk = j;
         }
-        let lineEnd = brk > start ? brk + 1 : Math.max(start + 1, end);
+        let lineEnd;
+        if (brk > start) {
+          lineEnd = brk + 1;
+        } else {
+          // 需要硬切。先容忍：向后看 SUBTITLE_TOLERANCE 个有效字范围内有没有断句标点，
+          // 有则把行尾挪到该标点之后（行更完整）。再容忍「块尾」：若边界后只剩极小残留
+          // （≤ SUBTITLE_TOLERANCE 个有效字），直接吞掉，避免末尾出一个极短行。
+          let where = -1;
+          let extra = 0;
+          for (let j = end; j < n; j++) {
+            if (isSubContent(raw[j])) {
+              extra++;
+              if (extra > SUBTITLE_TOLERANCE) break; // 超出容忍范围，不再往后找停顿
+            }
+            if (SUBTITLE_CLAUSE_BREAKS.indexOf(raw[j]) !== -1) { where = j; break; }
+          }
+          if (where !== -1) {
+            lineEnd = where + 1;
+          } else {
+            const tailContent = countSubContent(raw.slice(end));
+            lineEnd = (tailContent > 0 && tailContent <= SUBTITLE_TOLERANCE) ? n : Math.max(start + 1, end);
+          }
+        }
         // 断句后把紧跟在后面的右引号一并收进本行（如 「。.””」），避免引号单独成行。
         while (lineEnd < n && SUB_QUOTE_CLOSE.has(raw[lineEnd])) lineEnd++;
         lines.push(fold(raw.slice(start, lineEnd)));
@@ -914,6 +967,27 @@ window.__ModuleLoader__.load({
       }
       return Math.max(0, ans);
     }
+    // 讲书「已读字符/全书字符」的实时进度（0..1）。字符数无需合成即可由 Host 精确算出
+    // （charOffsets 已缓存于 bookMetaCache），因此能得到稳定的全书占比——而时长占比
+    // 做不到：全书总时长在合成本书之前不可知。块内按播放时间占比插值（假设语速大致
+    // 恒定），跨块由 charOffsets[from] 阶梯推进，整体单调、切块不回退。meta 未就绪时
+    // 返回 0（进度条先不渲染），不阻塞其它功能。
+    function bookProgressFor() {
+      const id = currentBookId();
+      const meta = id !== null ? bookMetaCache.get(id) : undefined;
+      const offsets = meta && Array.isArray(meta.charOffsets) ? meta.charOffsets : [];
+      if (offsets.length < 2) return 0;
+      const total = offsets[offsets.length - 1];
+      if (!(total > 0)) return 0;
+      const k = bookFromRef;
+      if (k < 0 || k >= offsets.length - 1) return 0;
+      const dur = Number.isFinite(subtitleDur) && subtitleDur > 0
+        ? subtitleDur
+        : (Number.isFinite(audio.duration) && audio.duration > 0 ? audio.duration : 0);
+      const frac = dur > 0 ? Math.max(0, Math.min(1, (audio.currentTime || 0) / dur)) : 0;
+      const consumed = offsets[k] + (offsets[k + 1] - offsets[k]) * frac;
+      return consumed > 0 ? Math.max(0, Math.min(1, consumed / total)) : 0;
+    }
     function resetLyric() {
       musicLyric = [];
       subtitleLines = [];
@@ -953,7 +1027,8 @@ window.__ModuleLoader__.load({
         if (text !== store.lyricText) set({ lyricText: text });
       }
     }
-    // 拉取并解析本地曲目的 .lrc 歌词；无 .lrc / 切歌后返回皆静默。
+    // 拉取并解析本地曲目的歌词：优先同名 .lrc（/lyric）；本地无则在线兜底
+    // （/lyric/online：Host 按 QQ 音乐 → LRCLIB 匹配取词）。无词/切歌后返回皆静默。
     function loadLyricForTrack(id) {
       resetLyric();
       lyricTrackId = id;
@@ -963,9 +1038,40 @@ window.__ModuleLoader__.load({
       fetch('/dsh-music/lyric?path=' + encodeURIComponent(track.path), { cache: 'no-store' })
         .then((r) => r.json())
         .then((d) => {
-          if (!d || !d.ok || !Array.isArray(d.lrc)) return;
           if (store.currentId !== id) return; // 取词期间已切歌
-          musicLyric = d.lrc;
+          if (d && d.ok && Array.isArray(d.lrc) && d.lrc.length > 0) {
+            musicLyric = d.lrc;
+            updateLyric();
+            return;
+          }
+          // 本地无同名 .lrc → 在线兜底（QQ → LRCLIB）
+          loadOnlineLyric(id, track);
+        })
+        .catch(() => {});
+    }
+    // 从文件名 stem 拆「歌手 - 歌名」。常见命名：'周杰伦 - 乱舞春秋'、'周杰伦、温岚 - 屋顶'、
+    // '周杰伦 余妮 - 懦夫'、'周杰伦 - 李玟 - 刀马旦'。以最后一个 ' - '/'–'/'—' 为界：
+    // 前段当歌手（可含多位/空格/顿号），后段当歌名；没有分隔符时整段当歌名（歌手留空）。
+    // 拆出干净歌名 + 歌手能显著提高在线歌词匹配精度（否则前缀会拖低匹配分）。
+    function splitArtistTitle(stem) {
+      const m = /^(.*)[-–—]\s*(.+)$/.exec(String(stem || ''));
+      if (!m) return { title: String(stem || ''), artist: '' };
+      return { title: m[2].trim(), artist: m[1].trim() };
+    }
+    // 本地歌曲在线歌词兜底：把文件名拆出的歌名/歌手 + 时长交给 Host 去 QQ/LRCLIB 匹配取词。
+    function loadOnlineLyric(id, track) {
+      const base = String(track.name || '').split(/[\\/]/).pop();
+      const { title, artist } = splitArtistTitle(stripExt(base));
+      const params = new URLSearchParams({ path: track.path, title });
+      if (artist !== '') params.set('artist', artist);
+      else if (Array.isArray(track.artists) && track.artists.length > 0) params.set('artist', track.artists.join('/'));
+      if (Number.isFinite(audio.duration) && audio.duration > 0) params.set('duration', String(Math.round(audio.duration)));
+      fetch('/dsh-music/lyric/online?' + params.toString(), { cache: 'no-store' })
+        .then((r) => r.json())
+        .then((d) => {
+          if (!d || !d.ok || !Array.isArray(d.lrc) || d.lrc.length === 0) return;
+          if (store.currentId !== id) return; // 取词期间已切歌
+          musicLyric = mergeLyricTrans(d.lrc, d.trans);
           updateLyric();
         })
         .catch(() => {});
@@ -1359,7 +1465,7 @@ window.__ModuleLoader__.load({
       bookRestorePos = -1;
       audio.src = track.url;
       audio.load();
-      set({ currentId: id, currentName: track.name, currentArtists: track.artists || [], pendingId: null, pendingName: null, error: null, tocOpen: false, currentSection: '', qqFaved: false, currentQuality: (track && track.quality) || '' });
+      set({ currentId: id, currentName: track.name, currentArtists: track.artists || [], pendingId: null, pendingName: null, error: null, tocOpen: false, currentSection: '', qqFaved: false, currentQuality: (track && track.quality) || '', bookProgress: 0 });
       syncShufflePos();
       loadEnvelope(id, track.url);
       loadLyricForTrack(id);
@@ -1456,6 +1562,10 @@ window.__ModuleLoader__.load({
             title: (m && m.title) || '',
             author: (m && m.author) || '',
             sections: (m && Array.isArray(m.sections)) ? m.sections : [],
+            // 逐块累积字符偏移 + 全书总字符：用于「已读字符/全书字符」的实时进度。
+            // 旧 Host 没有这俩字段时优雅降级（进度条保持 0/不显示），不影响其它功能。
+            charOffsets: (m && Array.isArray(m.charOffsets) && m.charOffsets.length > 1) ? m.charOffsets : [],
+            totalChars: m && typeof m.totalChars === 'number' && m.totalChars > 0 ? m.totalChars : -1,
           };
           bookMetaCache.set(id, meta);
         }
@@ -1534,7 +1644,7 @@ window.__ModuleLoader__.load({
       // near-instant (server-side synthesis cache) so we don't flash a spinner
       // at every chunk boundary. Only user-initiated plays show it.
       const showBuffer = !silent;
-      set({ currentId: 'book:' + id, currentName: book.name, currentArtists: [], pendingId: null, pendingName: null, error: null, vizState: 'ok', currentSection: '', bookToc: [], currentQuality: '' });
+      set({ currentId: 'book:' + id, currentName: book.name, currentArtists: [], pendingId: null, pendingName: null, error: null, vizState: 'ok', currentSection: '', bookToc: [], currentQuality: '', bookProgress: 0 });
       // Load the chapter structure for the toc + the current-section label (the
       // current section is derived from the chunk index once the meta arrives).
       const startFrom = from;
@@ -1675,6 +1785,9 @@ window.__ModuleLoader__.load({
             try { audio.currentTime = bookRestorePos; } catch (e) {}
           }
           if (bookTotal >= 0 && bookFromRef + 1 < bookTotal) preloadBook(id, bookFromRef + 1);
+          // 恢复续播的这块之前没有拉取过字幕（restore 不动 audio、playBookFrom 不经过
+          // 这里），必须补一次 loadBookSubtitle，否则续播后整块无字幕、直到切块才出现。
+          loadBookSubtitle(id, bookFromRef);
         }
         const promise = audio.play();
         if (promise !== undefined && typeof promise.catch === 'function') promise.catch((err) => { if (isAutoplayBlocked(err)) set({ error: '浏览器拦截了自动播放，请点击播放按钮' }); });
@@ -1798,7 +1911,7 @@ window.__ModuleLoader__.load({
       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: '', lyricText: '', voiceSwitching: 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: '', lyricText: '', voiceSwitching: false, bookProgress: 0 });
       resetLyric();
       clearPref(PREF_PLAYBACK);
       if (stoppedBook !== null) clearBookPlayback(stoppedBook.name);
@@ -1838,6 +1951,12 @@ window.__ModuleLoader__.load({
       // block (it reads like one long audiobook). Music is unchanged.
       const bookTimeBase = () => (store.currentId !== null && String(store.currentId).startsWith('book:')) ? bookBaseTime : 0;
       const onTime = () => {
+        // 讲书：按「已读字符/全书字符」实时推进全书进度条。不用 position/duration 的
+        // 时间占比——那是当前块内比例，切块会回退；且全书总时长在合成本书前不可知。
+        if (String(store.currentId).startsWith('book:')) {
+          const bp = bookProgressFor();
+          if (bp !== store.bookProgress) set({ bookProgress: bp });
+        }
         // A restored music track keeps showing its restored position until real
         // playback has clearly advanced past it. The <audio> currentTime is
         // unreliable right after a restore — it can seek to the spot and then
@@ -1871,6 +1990,9 @@ window.__ModuleLoader__.load({
               try { audio.currentTime = bookRestorePos; } catch (e) {}
             }
             set({ position: bookBaseTime + bookRestorePos });
+            // 补齐：pin 阶段也推进字幕——续播时该块的实时字幕可能还没就绪，这里在
+            // 每次 timeupdate 都尝试定位当前句，避免「先空白、切块后才出字幕」。
+            updateLyric();
             return;
           }
         }
@@ -2005,8 +2127,10 @@ window.__ModuleLoader__.load({
     function restorePlayback(list) {
       const saved = loadPlayback();
       if (saved === null) return;
-      // 在线 QQ 曲目：恢复当前曲目 + 队列 + 在线 scope + 在线 tab。
+      // 在线 QQ 曲目：恢复当前曲目 + 队列 + 播放位置 + 在线 scope + 在线 tab。
       if (saved.kind === 'qq' || (saved.id && String(saved.id).startsWith('qq:'))) {
+        const pos = Number.isFinite(saved.position) && saved.position > 0 ? saved.position : 0;
+        const savedDur = Number.isFinite(saved.duration) && saved.duration > 0 ? saved.duration : 0;
         set({
           currentId: saved.id,
           currentName: saved.name || 'QQ音乐',
@@ -2014,10 +2138,14 @@ window.__ModuleLoader__.load({
           scope: { kind: 'qq' },
           qqQueue: Array.isArray(saved.queue) ? saved.queue : [],
           qqSource: saved.source || '在线',
+          // 恢复在线曲目的中途位置：播放条立即显示保存的位置；用户点 ▶ 续播时
+          // togglePlay 会经 restoredMusicPos 把流 seek 到该位置（与本地曲目一致）。
+          position: pos, duration: savedDur,
           pendingId: null, pendingName: null, error: null,
           tab: 'qq',
           currentQuality: '',
         });
+        restoredMusicPos = pos > 0 ? pos : null;
         // 更新时间戳，避免被当作旧数据。
         savePref(PREF_PLAYBACK, JSON.stringify({ ...saved, ts: Date.now() }));
         // 恢复在线曲目后按「我喜欢」集合刷新爱心状态。
@@ -2098,8 +2226,13 @@ window.__ModuleLoader__.load({
       // 立刻显示正在播放的章节（而不是等用户点 ▶、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) });
+        if (meta === null) return;
+        // 刷新后书尚未播放（自动播放被拦截），onTime 不会触发、bookProgress 仍为 0，
+        // 必须先在这里按「已读字符/全书字符」补一次，进度条才能立即显示正确的整体进度
+        // （audio 未加载时 frac=0，即当前块起点位移 offset[from]；播放后由 onTime 微调）。
+        const bp = bookProgressFor();
+        if (bp !== store.bookProgress) set({ bookProgress: bp });
+        if (meta.sections.length > 0) 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.
@@ -2182,6 +2315,29 @@ window.__ModuleLoader__.load({
         set({ loading: false, error: '设置目录失败：' + String((err && err.message) || err) });
       });
     }
+    // 手动刷新：重新扫描当前音乐/小说目录并更新列表（面板「刷新」按钮）。
+    // 与 saveRoot 一致只刷新列表、不调用 restoreLatest，避免把播放中的在线 QQ
+    // 曲目/tab 跳走。返回 promise 供按钮等待扫描完成以复位「刷新中…」。
+    function rescanLibrary() {
+      return fetch('/dsh-music/rescan', {
+        method: 'POST', cache: 'no-store',
+        headers: { 'content-type': 'application/json' },
+      }).then((r) => r.json()).then((result) => {
+        if (result && result.ok) {
+          set({
+            root: result.root || null, bookRoot: result.bookRoot || null,
+            tracks: result.tracks || [], books: result.books || [],
+            playlists: result.playlists || [],
+            count: result.count || 0, error: null,
+            voices: Array.isArray(result.voices) ? result.voices : [],
+          });
+        } else {
+          set({ error: (result && result.error) || '刷新失败' });
+        }
+      }).catch((err) => {
+        set({ error: '刷新失败：' + String((err && err.message) || err) });
+      });
+    }
 
     function fmtTime(seconds) {
       if (!Number.isFinite(seconds) || seconds <= 0) return '0:00';
@@ -2466,8 +2622,12 @@ window.__ModuleLoader__.load({
       // 无内容（点击停止 / 插件刚安装）时恒定工作态：不透明度 100%、控件组展开，无任何特效。
       const active = barHover || anyPopOpen || !hasTrack;
       const barDimmed = !active;
-      // 播放进度细线：有内容且已获取时长时，按 position/duration 计算填充百分比。
-      const progressPct = (hasTrack && s.duration > 0) ? Math.min(100, Math.max(0, (s.position / s.duration) * 100)) : 0;
+      // 播放进度细线：音乐按 position/duration（单曲时长），讲书按「已读字符/全书字符」
+      // 的 bookProgress——全书总时长在合成本书前不可知，用时长占比会切块回退，字符占比
+      // 才稳定且只增不减。
+      const progressPct = isBook
+        ? Math.min(100, Math.max(0, s.bookProgress * 100))
+        : ((hasTrack && s.duration > 0) ? Math.min(100, Math.max(0, (s.position / s.duration) * 100)) : 0);
       return React.createElement('div', { className: 'dsh-music-bar-wrap' },
         React.createElement('div',
           { className: 'dsh-music-bar' + (isBook ? ' book' : '') + (barDimmed ? ' dimmed' : ''), onMouseEnter: showBarBtns, onMouseLeave: onBarLeave },
@@ -2488,7 +2648,9 @@ window.__ModuleLoader__.load({
             hasTrack
               ? (showHint
                   ? React.createElement('span', { className: 'dsh-music-bar-hint' }, '⚠ 自动播放被拦截，点击▶解锁')
-                  : (isBook ? null : (!barDimmed ? React.createElement('span', { className: 'dsh-music-bar-time' }, fmtTime(s.position) + ' / ' + fmtTime(s.duration)) : null)))
+                  : (isBook
+                      ? (!barDimmed ? React.createElement('span', { className: 'dsh-music-bar-time' }, Math.round(s.bookProgress * 100) + '%') : null)
+                      : (!barDimmed ? React.createElement('span', { className: 'dsh-music-bar-time' }, fmtTime(s.position) + ' / ' + fmtTime(s.duration)) : null)))
               : null,
             React.createElement('div', { className: 'dsh-music-bar-btns' },
               heartBtn,
@@ -2544,8 +2706,8 @@ window.__ModuleLoader__.load({
             React.createElement(VolumeSlider, null),
           )) : null,
           // 播放进度细线：绝对定位在播放条底部，与播放条等宽、高约 1px，随播放实时填充。
-          // 仅音乐模式显示（AI 讲书是累计时钟、按章节推进，不做单条进度线）。
-          hasTrack && !isBook && s.duration > 0
+          // 音乐按单曲时长，讲书按「已读字符/全书字符」的 bookProgress（见 progressPct）。
+          hasTrack && (isBook || s.duration > 0)
             ? React.createElement('div', { className: 'dsh-music-bar-progress' },
                 React.createElement('div', { className: 'dsh-music-bar-progress-fill', style: { width: progressPct + '%' } }))
             : null,
@@ -2739,6 +2901,9 @@ window.__ModuleLoader__.load({
       const [histOpen, setHistOpen] = useState(false);
       const histRef = useRef(null);
       const histPopRef = useRef(null); // portal 到 body 的历史下拉（点击内部不关闭）
+      // 恢复「在线播放列表」层：prefsReady 早于 restorePlayback 灌 qqQueue，队列就绪前
+      // 先标记待恢复，等 qqQueue 非空后由下方 effect 补上（避免刷新后直接显示「暂无歌曲」）。
+      const queueRestorePending = useRef(false);
       // 浏览。
       const [minePlays, setMinePlays] = useState([]);
       const [mineLoaded, setMineLoaded] = useState(false);
@@ -2750,7 +2915,6 @@ window.__ModuleLoader__.load({
       const [browseLoading, setBrowseLoading] = useState(false);
       // 「加入歌单」弹窗：{ song, x, y }（锚点=「＋」按钮的视口坐标），点击弹出我的歌单列表。
       const [qqJoin, setQqJoin] = useState(null);
-      const [qqJoinMsg, setQqJoinMsg] = useState('');
       const qqJoinRef = useRef(null);
       // 点击弹窗外关闭「加入歌单」弹窗。
       useEffect(() => {
@@ -2821,11 +2985,40 @@ window.__ModuleLoader__.load({
         if (!ui || ui.layer !== 'playlist') return;
         setLayer('playlist');
         if (ui.plId) {
-          json('/dsh-music/qq/playlist/' + encodeURIComponent(ui.plId)).then((d) => { if (d && d.ok) setActivePl({ ...d.playlist, source: ui.plName || '歌单' }); });
+          // 与 openPlaylist 同款加载态：先显示「加载中…」而不是空列表。QQ 歌单详情
+          // 接口（fcg_ucc_getcdinfo_byids）在页面刚加载时首次请求常返回空 songlist
+          // （冷缓存/会话未就绪），单次请求就会停在「暂无歌曲」——这正是「刷新后
+          // 播放列表为空、返回重进才出来」的原因。这里对空结果/失败自动重试几次。
+          setPlLoading(true);
+          void loadPlaylistForRestore(ui.plId, ui.plName);
         } else {
-          setActivePl({ name: s.qqSource || '在线播放列表', songs: s.qqQueue || [], source: s.qqSource || '在线' });
+          // 「在线播放列表」（openQueue 保存的 plId=''）：prefsReady 置位早于
+          // restorePlayback 把 qqQueue 灌好，直接快照 s.qqQueue 会拿到空数组导致
+          // 「暂无歌曲」。这里标记待恢复，由下方 [s.qqQueue] effect 在队列就绪后补上。
+          queueRestorePending.current = true;
+          setActivePl({ name: store.qqSource || '在线播放列表', songs: store.qqQueue || [], source: store.qqSource || '在线' });
         }
       };
+      // 恢复的「在线播放列表」：等 restorePlayback 把 qqQueue 灌好后应用（修复刷新后
+      // 该层显示为空的问题）；用户手动离开该层（返回/进入歌单）时取消待恢复。
+      useEffect(() => {
+        if (queueRestorePending.current && store.qqQueue && store.qqQueue.length > 0) {
+          queueRestorePending.current = false;
+          setActivePl({ name: store.qqSource || '在线播放列表', songs: store.qqQueue, source: store.qqSource || '在线' });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [s.qqQueue]);
+      // 恢复歌单层：拉取歌单详情，空结果/失败自动重试（退避递增），成功后置入 activePl。
+      const loadPlaylistForRestore = async (plId, plName, attempts = 3) => {
+        let d = null;
+        for (let i = 0; i < attempts; i++) {
+          d = await json('/dsh-music/qq/playlist/' + encodeURIComponent(plId));
+          if (d && d.ok && d.playlist && Array.isArray(d.playlist.songs) && d.playlist.songs.length > 0) break;
+          if (i + 1 < attempts) await new Promise((r) => setTimeout(r, 400 * (i + 1)));
+        }
+        if (d && d.ok && d.playlist) setActivePl({ ...d.playlist, source: plName || '歌单' });
+        setPlLoading(false);
+      };
       // ① 挂载时只做本地初始化：读搜索历史（Host 持久化）+ 查登录态（status 由
       // host 读本地 cookie 文件，不发任何外部网络请求）。外部数据（分类/推荐/我的
       // 歌单）一律延后到登录后（见下方 [loggedIn] effect），未登录零外部请求——
@@ -2986,6 +3179,7 @@ window.__ModuleLoader__.load({
       }
       function backToTops() { setTopDetail(null); setTopTotal(0); setTopHasMore(false); }
       async function openPlaylist(pl, mine) {
+        queueRestorePending.current = false; // 手动进入歌单，取消「在线播放列表」待恢复
         setActivePl(null); setLayer('playlist'); setPlLoading(true); saveUi('playlist', pl.id, pl.name);
         // _dirId：从歌单移除歌曲需要 QQ 歌单的目录 id（「我的歌单」卡片带 dirId）；
         // mine 标记这是「我自己的歌单」（含「我喜欢」），详情里才允许用「−」从该歌单移除。
@@ -2999,7 +3193,7 @@ window.__ModuleLoader__.load({
         setActivePl({ name: s.qqSource || '在线播放列表', songs: s.qqQueue || [], source: s.qqSource || '播放中' });
         setLayer('playlist'); saveUi('playlist', '', '');
       }
-      function backToMain() { setLayer('main'); setActivePl(null); saveUi('main', '', ''); }
+      function backToMain() { queueRestorePending.current = false; setLayer('main'); setActivePl(null); saveUi('main', '', ''); }
       async function doSearch(kwOverride) {
         const kw = (kwOverride !== undefined ? String(kwOverride) : q).trim();
         if (kw === '') { setSearched(false); setQError(''); return; }
@@ -3152,15 +3346,16 @@ window.__ModuleLoader__.load({
         } catch (err) { setQError(String((err && err.message) || err)); }
       }
       // 「加入歌单」：打开弹窗（列出我的歌单），并把歌曲加入所选歌单 / 新建歌单。
+      // 成功/失败统一走面板居中的 toast 提示（成功关闭弹窗；失败保留弹窗可重试）。
       function openQqJoin(song, e) {
         const r = e.currentTarget.getBoundingClientRect();
         if (minePlays.length === 0 && !mineLoaded) loadMine();
-        setQqJoinMsg('');
         setQqJoin({ song, x: r.right, y: r.top });
       }
       async function qqJoinAddTo(pl) {
         const song = qqJoin && qqJoin.song;
         if (!song) return;
+        const name = (pl && pl.name) || '歌单';
         try {
           // dirId 用歌单的权威 dirId（dirid），tid 固定 0（「我喜欢」dirId=201,tid=0 的可用模式）。
           const d = await jsonPost('/dsh-music/qq/playlist-add', { song, dirId: (pl && (pl.dirId || pl.tid || pl.id)) || 0, tid: 0 });
@@ -3172,7 +3367,8 @@ window.__ModuleLoader__.load({
             loadMine();
           }
           setQqJoin(null);
-        } catch (err) { setQqJoinMsg(String((err && err.message) || err)); }
+          showToast('添加到' + name + '成功', true);
+        } catch (err) { showToast('添加到' + name + '失败', false); }
       }
       async function qqJoinCreate() {
         const song = qqJoin && qqJoin.song;
@@ -3189,7 +3385,8 @@ window.__ModuleLoader__.load({
             }
             loadMine();
             setQqJoin(null);
-          } catch (err) { setQqJoinMsg(String((err && err.message) || err)); }
+            showToast('添加到' + ((created && created.name) || trimmed) + '成功', true);
+          } catch (err) { showToast('添加到' + trimmed + '失败', false); }
         });
       }
       const qqJoinMenu = qqJoin ? portalToBody((() => {
@@ -3200,7 +3397,6 @@ window.__ModuleLoader__.load({
           transform: openUp ? 'translateY(-100%)' : 'none',
         };
         return React.createElement('div', { className: 'dsh-music-add-pop', ref: qqJoinRef, style },
-          qqJoinMsg ? React.createElement('div', { className: 'dsh-music-hint', style: { padding: '2px 8px', color: 'var(--dsw-alias-state-error-primary, #e5534b)' } }, qqJoinMsg) : null,
           minePlays.length > 0 ? minePlays.map((p) => React.createElement('button', {
             key: p.id, className: 'dsh-music-add-pop-item',
             title: '加入「' + p.name + '」',
@@ -3767,6 +3963,7 @@ window.__ModuleLoader__.load({
         }) : null,
         s.prompt ? React.createElement(PromptModal, { key: s.prompt.id, panelRef }) : null,
         s.confirm ? React.createElement(ConfirmModal, { key: s.confirm.title, panelRef }) : null,
+        s.toast ? React.createElement('div', { className: 'dsh-music-panel-toast' + (s.toast.ok ? ' ok' : ' err') }, s.toast.text) : null,
       );
     }
     // 自定义输入弹窗（替代浏览器 prompt）：新建/重命名歌单等需要名称输入的场景。
@@ -3838,9 +4035,12 @@ window.__ModuleLoader__.load({
       const [curName, setCurName] = useState('');
       const [curCrumbs, setCurCrumbs] = useState([]);
       const [dirError, setDirError] = useState(null);
+      // 手动刷新按钮：扫描进行中禁用并显示「刷新中…」。
+      const [refreshing, setRefreshing] = useState(false);
       const isBook = s.tab === 'book';
       const activeRoot = isBook ? s.bookRoot : s.root;
       const pickerTitle = isBook ? '选择小说目录' : '选择音乐目录';
+      const refreshTitle = isBook ? '重新扫描小说目录' : '重新扫描音乐目录';
       const hint = isBook
         ? '支持 .txt / .epub 文件，AI语音目前仅支持xiaomi提供方（限时免费），请在设置中配置好再使用此功能。'
         : '支持 mp3 / m4a / flac / wav / ogg / opus / aac / webm 等格式，自动递归扫描子目录。';
@@ -3848,7 +4048,19 @@ window.__ModuleLoader__.load({
         React.createElement('div', { className: 'dsh-music-settings-row' },
           React.createElement('span', { className: 'dsh-music-settings-cur', title: activeRoot || '' },
             '📁 ' + (activeRoot || '未配置')),
-          React.createElement('button', { className: 'dsh-music-settings-btn', onClick: () => openPicker() }, pickerTitle)),
+          React.createElement('button', { className: 'dsh-music-settings-btn', onClick: () => openPicker() }, pickerTitle),
+          // 手动刷新：重新扫描当前目录（新增文件后无需重选目录即可看到）。
+          React.createElement('button', {
+            className: 'dsh-music-settings-btn ghost',
+            title: refreshTitle,
+            disabled: refreshing,
+            onClick: async () => {
+              if (refreshing) return;
+              setRefreshing(true);
+              await rescanLibrary();
+              setRefreshing(false);
+            },
+          }, refreshing ? '刷新中…' : '刷新')),
         React.createElement('p', { className: 'dsh-music-hint' }, hint),
         pickerOpen ? portalToBody(React.createElement('div', { className: 'dsh-music-picker-overlay' },
           React.createElement('div', { className: 'dsh-music-picker', style: panelCenterStyle(panelRef, pickerOpen, 320, Math.round(window.innerHeight * 0.72)) },
@@ -3924,7 +4136,15 @@ window.__ModuleLoader__.load({
         transform: openUp ? 'translateY(-100%)' : 'none',
       };
       const list = store.playlists || [];
-      const addTo = (id) => { apiPlaylistAdd(id, [track.path], () => onClose()); };
+      // 加入已有歌单：成功关弹窗并居中提示，失败保留弹窗（可换歌单重试）居中提示。
+      const addTo = (id) => {
+        const pl = list.find((p) => p.id === id);
+        const name = (pl && pl.name) || '歌单';
+        apiPlaylistAdd(id, [track.path], (r) => {
+          if (r && r.ok && r.playlist) { onClose(); showToast('添加到' + name + '成功', true); }
+          else showToast('添加到' + name + '失败', false);
+        });
+      };
       const addNew = () => {
         openPrompt('新建歌单名称', '', (trimmed) => {
           if (!trimmed) return;
@@ -3935,9 +4155,14 @@ window.__ModuleLoader__.load({
           }).then((r) => r.json()).then((r) => {
             if (r && r.playlist) {
               set({ playlists: [...(store.playlists || []), r.playlist] });
-              apiPlaylistAdd(r.playlist.id, [track.path], () => onClose());
+              apiPlaylistAdd(r.playlist.id, [track.path], (add) => {
+                if (add && add.ok && add.playlist) { onClose(); showToast('添加到' + r.playlist.name + '成功', true); }
+                else showToast('添加到' + r.playlist.name + '失败', false);
+              });
+            } else {
+              showToast('添加到' + trimmed + '失败', false);
             }
-          }).catch(() => onClose());
+          }).catch(() => showToast('添加到' + trimmed + '失败', false));
         });
       };
       return React.createElement('div', { className: 'dsh-music-add-pop', ref, style },
@@ -4190,7 +4415,7 @@ window.__ModuleLoader__.load({
       // （宽度 0.12s 平滑过渡）。播放条容器已 overflow:hidden，细线两端会被裁剪到
       // 圆角形状内，不会「戳出」圆角之外；pointer-events:none 避免挡住下方交互。
       '.dsh-music-bar-progress { position: absolute; left: 0; right: 0; bottom: 0; height: 1px; overflow: hidden; pointer-events: none; background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.1)); }\n' +
-      '.dsh-music-bar-progress-fill { height: 100%; background: var(--dsh-music-accent, #2f9e6e); transition: width 0.12s linear; }\n' +
+      '.dsh-music-bar-progress-fill { height: 100%; background: color-mix(in srgb, var(--dsh-music-accent, #2f9e6e) 55%, var(--dsw-alias-bg-base)); transition: width 0.12s linear; }\n' +
       '.dsh-music-bar-idle { color: var(--dsw-alias-label-primary, #e6e6e6); font-weight: 500; display: inline-flex; align-items: center; }\n' +
       '.dsh-music-bar-name { max-width: 36%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; display: inline-flex; align-items: center; min-width: 0; }\n' +
       '.dsh-music-note { color: var(--dsh-music-accent, #2f9e6e); flex: none; margin-right: 4px; }\n' +
@@ -4449,6 +4674,12 @@ window.__ModuleLoader__.load({
       '.dsh-music-add-pop-item { display: block; width: 100%; text-align: left; padding: 5px 8px; border: none; background: transparent; border-radius: 6px; color: var(--dsw-alias-label-primary, #e6e6e6); cursor: pointer; font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n' +
       '.dsh-music-add-pop-item:hover { background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.06)); color: var(--dsh-music-accent, #2f9e6e); }\n' +
       '.dsh-music-add-pop-item.new { color: var(--dsh-music-accent, #2f9e6e); border-top: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,0.2)); margin-top: 2px; padding-top: 6px; }\n' +
+      // 「加入歌单」成功/失败提示：面板窗口内绝对居中，颜色跟随 DSH 主题
+      // （成功 = 主题强调色 --dsh-music-accent；失败 = 主题错误色），2s 自动消失。
+      '.dsh-music-panel-toast { position: absolute; left: 50%; top: 50%; transform: translate(-50%, -50%); z-index: 20; padding: 8px 18px; border-radius: 8px; font-size: 13px; font-weight: 500; color: var(--dsh-music-accent-fg, #fff); background: rgba(30,31,34,0.92); box-shadow: 0 6px 20px rgba(0,0,0,0.35); pointer-events: none; white-space: nowrap; max-width: 90%; text-align: center; animation: dsh-music-toast-in 0.18s ease; }\n' +
+      '.dsh-music-panel-toast.ok { background: var(--dsh-music-accent, #2f9e6e); }\n' +
+      '.dsh-music-panel-toast.err { background: var(--dsw-alias-state-error-primary, #e5534b); }\n' +
+      '@keyframes dsh-music-toast-in { from { opacity: 0; transform: translate(-50%, -50%) scale(0.94); } to { opacity: 1; transform: translate(-50%, -50%) scale(1); } }\n' +
       '.dsh-music-bar-btn.fav { color: var(--dsw-alias-label-secondary, #8a8f98); }\n' +
       '.dsh-music-bar-btn.fav.on { color: var(--dsh-music-accent, #2f9e6e); }\n';
 

package/lib/index.js

@@ -314,6 +314,7 @@ import { dirname, basename, parse as pathParse, join as pathJoin } from 'node:pa
 import { inflateRawSync, inflateSync } from 'node:zlib'
 import * as os from 'node:os'
 import * as QQ from './qq.js'
+import { getOnlineLyric } from './lyric.js'
 
 // ---- book structure parsing (title / preface / chapters / epilogue) ----
 // Heuristic, rule-based parser that splits a novel's normalized text into
@@ -1378,6 +1379,27 @@ export function apply(ctx) {
     return null
   }
 
+  // ---- 本地歌曲在线歌词兜底缓存（按 track.path，LRU + TTL）----
+  // 正命中 6h、空命中 30min：避免每次播放重复打 QQ/LRCLIB；容量上限 500 条。
+  const lyricOnlineCache = new Map()
+  const LYRIC_ONLINE_TTL = 6 * 60 * 60 * 1000
+  const LYRIC_ONLINE_TTL_EMPTY = 30 * 60 * 1000
+  const LYRIC_ONLINE_MAX = 500
+  const lyricOnlineCacheGet = (path) => {
+    const e = lyricOnlineCache.get(path)
+    if (!e) return null
+    if (Date.now() - e.ts > e.ttl) { lyricOnlineCache.delete(path); return null }
+    return e.payload
+  }
+  const lyricOnlineCacheSet = (path, payload, ttl) => {
+    if (lyricOnlineCache.has(path)) lyricOnlineCache.delete(path)
+    lyricOnlineCache.set(path, { ts: Date.now(), ttl, payload })
+    if (lyricOnlineCache.size > LYRIC_ONLINE_MAX) {
+      const k = lyricOnlineCache.keys().next().value
+      if (k !== undefined) lyricOnlineCache.delete(k)
+    }
+  }
+
   const scan = async (rootPath, kinds = { music: true, books: false }) => {
     const target = await ctx.fs.resolve(rootPath)
     const info = await ctx.fs.stat(target)
@@ -1868,6 +1890,13 @@ export function apply(ctx) {
     const cum = []
     let acc = 0
     for (const c of chunks) { acc += c.length; cum.push(acc) }
+    // 逐块累积字符偏移：charOffsets[k] = 前 k 个块的字符数之和（charOffsets[0]=0，
+    // charOffsets[total] = 全书总字符数）。浏览器端用它做「已读字符 / 全书字符」的
+    // 实时进度——每块字符数已知，无需合成也能得到稳定的全书占比（时长做不到：
+    // 全书总时长在合成本书之前是不可知的）。
+    const charOffsets = new Array(chunks.length + 1)
+    charOffsets[0] = 0
+    for (let i = 0; i < chunks.length; i++) charOffsets[i + 1] = charOffsets[i] + chunks[i].length
     const upperBound = (x) => {
       let lo = 0, hi = cum.length - 1, ans = 0
       while (lo <= hi) {
@@ -1889,7 +1918,10 @@ export function apply(ctx) {
         startLine: s.startLine,
       }
     })
-    bookMetaCache[absPath] = { title: st.title, author: st.author, total: chunks.length, sections }
+    bookMetaCache[absPath] = {
+      title: st.title, author: st.author, total: chunks.length,
+      sections, charOffsets, totalChars: charOffsets[chunks.length],
+    }
     return bookMetaCache[absPath]
   }
 
@@ -1973,6 +2005,24 @@ export function apply(ctx) {
         })
         return
       }
+      // 手动重扫：重新遍历当前音乐/小说目录并返回最新列表（面板「刷新」按钮调用）。
+      if (pathname === '/dsh-music/rescan' && req.method === 'POST') {
+        await ensureStarted()
+        try {
+          const r = await refresh()
+          const ts = await ttsState()
+          writeJson(res, {
+            ok: true, root: r.root, bookRoot: r.bookRoot,
+            tracks: r.tracks, books: r.books, count: r.count,
+            playlists: publicPlaylists(),
+            ttsConfigured: ts.configured, ttsReason: ts.reason, voices: MIMO_VOICES,
+            qqLoggedIn: !!qq.cookie, qqUin: qqUin(), qqNickname: qq.nickname,
+          })
+        } catch (err) {
+          writeJson(res, { ok: false, error: String((err && err.message) || err) }, 500)
+        }
+        return
+      }
       // 播放偏好读写（volume/mode/voice/scope/panel-pos/playback/books-playback）。
       // GET 返回完整快照；POST 为合并语义：{ prefs: {k:v,...} } 写入，
       // { remove: [k,...] } 删除指定键。见 lib/index.js 的 serverPrefs 说明。
@@ -2135,6 +2185,9 @@ export function apply(ctx) {
               id, name: book.name, size: book.size,
               total: chunks.length,
               title: meta.title, author: meta.author, sections: meta.sections,
+              // 逐块累积字符偏移 + 全书总字符：浏览器端据此算「已读字符/全书字符」
+              // 的实时进度条（见 check-book progress）。
+              charOffsets: meta.charOffsets, totalChars: meta.totalChars,
             })
             return
           }
@@ -2596,6 +2649,61 @@ export function apply(ctx) {
         }
         return
       }
+      // ---- 本地歌曲在线歌词兜底（QQ 音乐 → LRCLIB）----
+      // 客户端先请求 /lyric；本地无同名 .lrc 时再请求本端点：先复查本地（幂等），
+      // 无则在线取词（QQ 匿名官方歌词含逐句翻译；LRCLIB 免费同步 LRC），按 track.path
+      // LRU 缓存避免重复请求；无匹配/失败返回 hasLyric:false，播放不受影响。
+      if (pathname === '/dsh-music/lyric/online' && req.method === 'GET') {
+        await ensureStarted()
+        const rawPath = url.searchParams.get('path') || ''
+        if (rawPath === '') { writeJson(res, { ok: false, error: 'missing path' }, 400); return }
+        if (!isAudioName(rawPath) || !isRegisteredAudioPath(rawPath)) { writeJson(res, { ok: false, error: 'forbidden' }, 403); return }
+        // 本地同名 .lrc 优先（幂等：若已出现则直接返回本地，不浪费在线请求）。
+        const lrcPath = findLrcForAudio(rawPath)
+        if (lrcPath !== null) {
+          try {
+            const lrc = parseLrc(readBufToString(readFileSync(lrcPath)))
+            writeJson(res, { ok: true, hasLyric: lrc.length > 0, source: 'local', lrc })
+          } catch (err) {
+            writeJson(res, { ok: false, hasLyric: true, error: String((err && err.message) || err) }, 500)
+          }
+          return
+        }
+        // 在线兜底：LRU 缓存命中直接返回（正命中 6h / 空命中 30min）。
+        const cached = lyricOnlineCacheGet(rawPath)
+        if (cached !== null) { writeJson(res, cached); return }
+        // 搜索关键词：优先客户端给的标题（文件名去扩展名），否则从路径派生命名。
+        let title = (url.searchParams.get('title') || '').trim()
+        if (title === '') {
+          const fn = basename(rawPath)
+          const dot = fn.lastIndexOf('.')
+          title = dot > 0 ? fn.slice(0, dot) : fn
+        }
+        const artist = (url.searchParams.get('artist') || '').trim()
+        const durRaw = Number(url.searchParams.get('duration'))
+        const duration = Number.isFinite(durRaw) && durRaw > 0 ? durRaw : null
+        await loadQQCookie()
+        let payload = { ok: true, hasLyric: false }
+        try {
+          const hit = await getOnlineLyric({ title, artist, duration, qqCookie: qq.cookie })
+          if (hit !== null) {
+            const lrc = parseLrc(hit.lrcText)
+            payload = {
+              ok: true, hasLyric: lrc.length > 0, source: hit.source,
+              lrc, matched: hit.matched,
+              ...(hit.transText !== '' ? { trans: parseLrc(hit.transText) } : {}),
+            }
+          }
+        } catch (err) {
+          payload = { ok: false, error: String((err && err.message) || err) }
+        }
+        // 只缓存成功响应（含空结果）：错误/瞬时故障不缓存，避免之后 30 分钟都不再重试。
+        if (payload.ok) {
+          lyricOnlineCacheSet(rawPath, payload, payload.hasLyric ? LYRIC_ONLINE_TTL : LYRIC_ONLINE_TTL_EMPTY)
+        }
+        writeJson(res, payload)
+        return
+      }
       // ---- 通用文件流式路由（歌单成员专用，Range/seek）----
       // 只放行已登记路径（任一歌单成员 ∪ 曲库扫描集）。直接用 node:fs 读写，
       // 避免 DSH ctx.fs 对工作区外路径的围栏（与讲书读取小说文件的方式一致）。

package/lib/lyric.js

@@ -0,0 +1,186 @@
+/**
+ * lib/lyric.js — 本地歌曲「在线歌词兜底」：QQ 音乐 → LRCLIB。
+ *
+ * 场景：本地音乐没有同名 .lrc 时，先用文件名（可带歌手/时长）在 QQ 匿名接口搜歌、
+ * 取官方歌词（含逐句翻译）；QQ 无果再查 LRCLIB（免费、无需 key、返回同步 LRC）。
+ *
+ * 纯 Node（Node ≥ 20，用全局 fetch），无第三方依赖，无编译步骤。
+ *
+ * ⚠️ 合规：歌词文本/翻译版权归著作权人及对应平台所有，仅供个人学习、技术研究、
+ * 日常个人试听使用；严禁商业用途、公开传播、二次分发。非官方接口随时可能变更，
+ * 所有出网请求带超时，失败一律静默回退（保持「无歌词」的现状，不打扰播放）。
+ */
+
+import * as QQ from './qq.js'
+
+const LRCLIB_API = 'https://lrclib.net/api'
+const LRCLIB_UA = 'dsh-music-player/1.0 (local lyric fallback; rate-limited+cached)'
+
+// 出网统一超时（与 qq.js 同构）：Node fetch 默认无超时，端点挂起会让播放流程卡住。
+async function fetchWithTimeout(url, opts = {}, timeoutMs = 10000) {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  try {
+    return await fetch(url, { ...opts, signal: ctrl.signal })
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// =====================================================================
+// LRCLIB（https://lrclib.net）— 免费公开歌词 API，无需 key、CORS 开启、返回同步 LRC。
+// 端点：GET /api/search?q=  （模糊，返回数组 ≤20 条，无结果返回空数组）
+//       GET /api/get/<id>  （按 id 取单条）
+// 记录字段：id / trackName / artistName / albumName / duration / instrumental /
+//          plainLyrics / syncedLyrics（标准 LRC：[mm:ss.xx] 时间戳 + [ti:]/[ar:] 元数据）
+// 注意：URL 查询参数必须百分号编码（直接放中文会 400）——用 URLSearchParams 构造。
+// =====================================================================
+
+// 搜索并归一化为候选数组（只保留带同步歌词的非纯音乐候选；纯音乐没有逐字歌词意义）。
+export async function lrclibSearch(keyword) {
+  const p = new URLSearchParams({ q: String(keyword || '') })
+  const res = await fetchWithTimeout(`${LRCLIB_API}/search?${p.toString()}`, {
+    headers: { Accept: 'application/json', 'User-Agent': LRCLIB_UA },
+  })
+  if (res.status !== 200) throw new Error('lrclib search http ' + res.status)
+  const arr = await res.json().catch(() => null)
+  if (!Array.isArray(arr)) throw new Error('lrclib search payload')
+  return arr
+    .filter((r) => r && typeof r.trackName === 'string'
+      && typeof r.syncedLyrics === 'string' && r.syncedLyrics.trim() !== '')
+    .map((r) => ({
+      id: r.id,
+      title: r.trackName,
+      artist: r.artistName || '',
+      duration: Number(r.duration),
+      instrumental: !!r.instrumental,
+      synced: r.syncedLyrics,
+    }))
+}
+
+// =====================================================================
+// 匹配打分：把候选（标题/歌手/时长/是否纯音乐）与期望值比对，返回 0..100 置信度。
+// 标题为主信号（精确 60 / 包含 42 / 分词重叠），歌手为强副信号（精确 30 / 包含 20），
+// 时长相近加分，纯音乐重罚。仅当分数 ≥ MIN_SCORE 才采信，避免「错配歌词」比「没有歌词」更糟。
+// 导出供测试。
+// =====================================================================
+
+// 归一化用于比对：小写、去空白与常见分隔/标点/括号/引号。
+export function normalizeText(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[\s\u3000\-_/\\,.;:，。；：！？!?·'"“”‘’（）()\[\]【】《》〈〉<>「」『』…—～~]+/g, '')
+    .trim()
+}
+
+// 轻量分词：拉丁词 + CJK 二元组（2-gram），供「包含」都不满足时做重叠匹配。
+function tokenize(s) {
+  const out = []
+  for (const w of s.match(/[a-z0-9]+/g) || []) out.push(w)
+  const cjk = s.replace(/[a-z0-9]+/g, '')
+  for (let i = 0; i + 1 < cjk.length; i++) out.push(cjk.slice(i, i + 2))
+  return out
+}
+
+export function scoreCandidate(cand, want) {
+  const wt = normalizeText(want && want.title)
+  const wa = want && want.artist ? normalizeText(want.artist) : ''
+  const ct = normalizeText(cand && cand.title)
+  const ca = cand && cand.artist ? normalizeText(cand.artist) : ''
+  let score = 0
+  if (wt !== '' && ct !== '') {
+    if (ct === wt) score += 60
+    else if (ct.includes(wt) || wt.includes(ct)) score += 42
+    else {
+      const wts = tokenize(wt); const cts = tokenize(ct)
+      const inter = wts.filter((t) => cts.includes(t)).length
+      if (inter > 0) score += Math.min(40, inter * 12)
+    }
+  }
+  if (wa !== '' && ca !== '') {
+    if (ca === wa) score += 30
+    else if (ca.includes(wa) || wa.includes(ca)) score += 20
+  } else if (wa === '') {
+    score += 5 // 未知歌手：中性偏袒（不惩罚，也不确认）
+  }
+  const cd = Number(cand && cand.duration)
+  const wd = Number(want && want.duration)
+  if (Number.isFinite(cd) && cd > 0 && Number.isFinite(wd) && wd > 0) {
+    const d = Math.abs(cd - wd)
+    if (d <= 5) score += 12
+    else if (d <= 15) score += 6
+  }
+  if (cand && cand.instrumental) score -= 40
+  return score
+}
+
+// 在候选中挑最高分者；返回 { best, score }（best 可为 null）。
+export function pickBest(candidates, want) {
+  let best = null, bestScore = -1
+  for (const c of candidates) {
+    const s = scoreCandidate(c, want)
+    if (s > bestScore) { bestScore = s; best = c }
+  }
+  return { best, score: bestScore }
+}
+
+// 采信阈值：标题精确(60)即接受；「包含 + 时长接近」也可达 ~54；含糊不取。
+const MIN_SCORE = 52
+
+// =====================================================================
+// 在线兜底主入口：依次尝试 QQ 音乐 → LRCLIB。
+// 入参 { title, artist, duration?, qqCookie? }；返回统一结构或 null：
+//   { source: 'qq'|'lrclib', matched: {title, artist, songmid?|id?, score},
+//     lrcText, transText }   // transText 仅 QQ（逐句翻译，可为空串）
+// 两个源都失败/无好匹配时返回 null（调用方按「无歌词」处理）。
+// =====================================================================
+export async function getOnlineLyric({ title = '', artist = '', duration = null, qqCookie = '' } = {}) {
+  const want = {
+    title: String(title || '').trim(),
+    artist: String(artist || '').trim(),
+    duration: Number.isFinite(duration) ? duration : null,
+  }
+  if (want.title === '') return null
+
+  // 1) QQ 音乐（匿名搜索 + 官方歌词，可带逐句翻译）
+  try {
+    const kw = want.artist !== '' ? want.title + ' ' + want.artist : want.title
+    const s = await QQ.search(kw, qqCookie, 1)
+    const cands = (s.results || []).map((r) => ({
+      title: r.title,
+      artist: (r.artists || []).join('/'),
+      duration: Number(r.interval),
+      songmid: r.songmid,
+      instrumental: false,
+    }))
+    const { best, score } = pickBest(cands, want)
+    if (best && best.songmid && score >= MIN_SCORE) {
+      const g = await QQ.getLyric(best.songmid, qqCookie)
+      const lrcText = (g.lyric || '').trim()
+      if (lrcText !== '') {
+        return {
+          source: 'qq',
+          matched: { title: best.title, artist: best.artist, songmid: best.songmid, score },
+          lrcText,
+          transText: (g.trans || '').trim(),
+        }
+      }
+    }
+  } catch { /* QQ 失败/无匹配 → 尝试下一源 */ }
+
+  // 2) LRCLIB（免费、无需 key、同步 LRC）
+  try {
+    const cands = await lrclibSearch(want.title)
+    const { best, score } = pickBest(cands, want)
+    if (best && best.synced && score >= MIN_SCORE) {
+      return {
+        source: 'lrclib',
+        matched: { title: best.title, artist: best.artist, id: best.id, score },
+        lrcText: best.synced.trim(),
+        transText: '',
+      }
+    }
+  } catch { /* 失败静默 */ }
+
+  return null
+}

package/package.json

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