dsh-music-player 1.0.2 → 1.0.3

package/README.md

@@ -16,6 +16,7 @@ DeepSeek Harness 音乐/小说播放插件。
 - **实时歌词/字幕**：本地歌曲自动显示同步歌词——优先读取文件**内嵌歌词**（FLAC `LYRICS`/MP3 `USLT` 标签，无需额外 `.lrc`），其次同名 `.lrc`，都没有时自动在线匹配；在线 QQ 歌曲显示官方歌词（外语歌带逐句翻译）；AI 讲书时显示当前朗读句子。**单击播放条歌词**可打开完整歌词/字幕面板（标识当前进度、可拖动/拉伸、位置独立记忆），面板默认开启**透明模式**——歌词像直接悬浮在页面上，可在「系统配置」关闭
 - 播放时防止电脑熄屏/休眠（需浏览器支持，如 Chrome/Edge）
 - **播放条位置可换**：在「系统配置 → 播放条位置」（配置页最后一项）里三选一——**输入框上方**（默认）/ **页面底部** / **悬浮可拖动**。悬浮条是紧凑的三行卡片（歌词整行 / 歌名+频谱 / 播放控制，行高固定不随歌词有无跳动），整条可以直接拖着挪地方，位置会记住（配置页可「重置位置」回到默认右下角）；改到底部/悬浮后，播放条不再挂在输入框区域，因此对话里的询问弹窗（会接管输入区）也不会再把它一起盖住——弹窗开着照样能暂停/切歌
+- **滚轮调音量**：鼠标停在音量条上直接滚轮即可加减音量，按滚动快慢分两档步进——**慢速滚动每次 1%**（细调）、**快速滚动每次 5%**（快速拉大/拉小）；上滚加、下滚减，滚轮被音量条消费，不会连带把外层对话滚走。鼠标滚轮慢慢拨与触控板细碎轻推都算慢速，鼠标快速连拨、触控板用力快滑算快速（阈值见 `lib/client.js` 的 `VOL_WHEEL_*` 常量）
 - 播放列表面板可自由拖动，右下角可拖拽调整大小，位置与尺寸跨刷新记忆
 - AI 讲书：本地 `.txt` / `.epub` 小说 AI 语音朗读，自动识别**书名/前言/章节/尾声**结构，播放条带**章节目录**跳转（打开即定位到当前正在播放的章节）、章节切换，可选 4 种中文 AI 声音（默认白桦）
 - `music_play` 模型工具：agent 可按关键词播放本地音乐，也可按小说名启动 AI 讲书

package/lib/client.js

@@ -57,7 +57,12 @@ window.__ModuleLoader__.load({
       const half = Math.min(maxW / 2, vw / 2 - margin);
       const left = Math.max(margin + half, Math.min(vw - margin - half, clampLeft));
       if (estH > 0 && r && r.height > 0 && r.top - 6 - estH < margin) {
-        return { position: 'fixed', left: Math.round(left), top: Math.round(r.bottom + 6), transform: 'translate(-50%, 0)' };
+        // 翻到锚点下方时必须**显式 bottom:'auto'**：弹层基础 CSS 里还留着
+        // `bottom: calc(100% + 6px)`（它们当年是 bar 内部的 absolute 弹层）。固定高度的弹层
+        // 靠「over-constrained 忽略 bottom」侥幸正常，而 height:auto 的弹层（讲书音量弹窗）
+        // 会把 top 与 bottom 一起算 → 高度算成负值 → 盒子塌成 0、背景卡片消失、内容溢出。
+        // 显式清掉后由内联 top 独占定位。
+        return { position: 'fixed', left: Math.round(left), top: Math.round(r.bottom + 6), bottom: 'auto', transform: 'translate(-50%, 0)' };
       }
       const top = (r && r.height > 0) ? Math.max(0, r.top - 6) : vh - 40;
       return { position: 'fixed', left: Math.round(left), top: Math.round(top), transform: 'translate(-50%, -100%)' };
@@ -89,9 +94,13 @@ window.__ModuleLoader__.load({
       // 顶边贴按钮底 + 6px，高度改用下方可用空间，避免弹窗顶出视口被裁。
       if (availAbove < 160) {
         const availBelow = Math.max(120, vh - r.bottom - 6 - topGap);
+        // bottom:'auto' 的理由同 anchorAbove：这两个弹层（章节目录 / 讲书音量）是 height:auto，
+        // 基础 CSS 的 `bottom: calc(100% + 6px)` 不减掉的话，top 与 bottom 会一起参与计算，
+        // 盒子高度算成负值 → 卡片壳塌成 0、只剩溢出的内容（悬浮条被拖到页面顶部时必现）。
         return {
           ...base,
           top: Math.round(r.bottom + 6),
+          bottom: 'auto',
           maxHeight: Math.round(Math.min(60 * vh / 100, 480, availBelow)),
         };
       }
@@ -980,7 +989,7 @@ window.__ModuleLoader__.load({
       if (cmd === 'kgPlay') { startKGPlayback(a.song, a.queue, a.label, a.from); return; }
       if (cmd === 'ncPlay') { startNCPlayback(a.song, a.queue, a.label, a.from); return; }
       if (cmd === 'radioPlay') { startRadioPlayback(a.station); return; }
-      if (cmd === 'newsPlay') { playNewsFrom(a.id, Number(a.from) || 0); return; }
+      if (cmd === 'newsPlay') { playNewsFrom(a.id, Number(a.from) || 0, !!a.whole); return; }
     }
     function xtabHandle(ev) {
       const m = ev && ev.data;
@@ -1326,7 +1335,10 @@ window.__ModuleLoader__.load({
         .then((r) => r.json().then((d) => ({ d, status: r.status })).catch(() => ({ d: null, status: r.status })))
         .then(({ d, status }) => {
           if (d && d.ok) {
-            set({ qqFaved: !!d.faved });
+            // 成功即清掉上一次失败的红色报错（面板顶部那条 dsh-music-error）：
+            // 失败留下的报错只由「播放」清（onPlay 里 set({error:null})），重试成功却不清
+            // 会一直挂在面板顶部，像是操作失败了。
+            set({ qqFaved: !!d.faved, error: null });
             // 同步本地「我喜欢」id/mid 集合，便于后续曲目判断（并持久化兜底）。
             if (sid || smid) {
               const ids = new Set(store.qqFavIds || []);
@@ -1504,7 +1516,8 @@ window.__ModuleLoader__.load({
         .then(({ d, status }) => {
           if (isKgAuthDead(d)) markKgAuthDead(d.error);
           if (d && d.ok) {
-            set({ kgFaved: action === 'add' });
+            // 同 QQ：重试成功即清掉上一次失败的红色报错。
+            set({ kgFaved: action === 'add', error: null });
             // 同步本地「我喜欢」hash 集合 + fileId 映射，便于后续曲目判断。
             const hashes = new Set(store.kgFavHashes || []);
             const files = (store.kgFavFiles || []).slice();
@@ -1550,7 +1563,7 @@ window.__ModuleLoader__.load({
         body: JSON.stringify({ action: faved ? 'remove' : 'add', station: st }),
       }).then((r) => r.json()).then((d) => {
         if (d && d.ok) {
-          set({ radioFavs: (d.favs || []).slice(), radioFavLoaded: true });
+          set({ radioFavs: (d.favs || []).slice(), radioFavLoaded: true, error: null });
         } else set({ error: (d && d.error) || '收藏操作失败' });
       }).catch(() => set({ error: '收藏操作失败，请重试' }));
     }
@@ -1886,6 +1899,21 @@ window.__ModuleLoader__.load({
       const consumed = offsets[k] + (offsets[k + 1] - offsets[k]) * frac;
       return consumed > 0 ? Math.max(0, Math.min(1, consumed / total)) : 0;
     }
+    // 指定块「起点」的进度（0..1）：切块/跳类/跳条目/换声音时用作进度条的种子值。
+    // 旧实现是在这些时刻把 bookProgress 直接清 0，等下一块首个 timeupdate 才跳回
+    // offsets[k]/total——期间细线会塌到 0%（下一块若在冷合成「AI 合成中…」，整个
+    // 等待期都停在 0%）。用块起点做种子可以做到：自动切块时与上一块末端的值无缝相接
+    // （不闪、不缩），跳转时直接显示目标位置而不是先归零再跳。
+    // meta 尚未缓存（全新期次首次播放）时返回 0，与旧行为一致，不阻塞播放。
+    function bookProgressAtChunk(id, from) {
+      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 = Math.max(0, Math.min(offsets.length - 2, Number(from) || 0));
+      return Math.max(0, Math.min(1, offsets[k] / total));
+    }
     // 卡拉OK帧级驱动：timeupdate 只有 ~4Hz——行切换平均迟到 125ms、最差 250ms，
     // 观感就是「每句歌词慢半拍」。这里提供 karaokeFrame()，挂在既有的可视化 rAF
     // 循环（startRaf）里每帧执行：播放中直接读 audio.currentTime 定位行，换行延迟
@@ -2874,6 +2902,9 @@ window.__ModuleLoader__.load({
     // <audio> error 时自动跳到下一首；连续跳过次数达到队列长度（整列都试过）
     // 即停止报错——且停止后不再 step，杜绝无限循环跳歌。成功播放(onPlay)清零。
     let qqErrorSkipCount = 0;
+    // 本地曲目连续解码/加载失败的跳过次数：与 qqErrorSkipCount 同理，避免整库坏文件时
+    // 无限跳歌。成功播放（onPlaying）清零。
+    let localErrorSkipCount = 0;
     function buildShuffleQueue(anchorId) {
       const ids = activeIds();
       // Fisher-Yates
@@ -3018,6 +3049,16 @@ window.__ModuleLoader__.load({
       const e = newsById(id);
       return e === null ? null : { id: e.id, name: e.title, url: '/dsh-music/news/' + e.id, path: '', isNews: true };
     };
+    // 按「播放条主文案」（本地书=文件名，新闻期次=期次标题）反查虚拟书。
+    // 每本讲书的续播记录就是按这个名字存的（见 saveCurrentBookPlayback），刷新恢复要用它
+    // 把记录还原成可播放的 book 对象——新闻期次不在 store.books（曲库）里，必须单独兜一层。
+    const bookByName = (name) => {
+      if (typeof name !== 'string' || name === '') return null;
+      const local = (store.books || []).find((b) => b.name === name);
+      if (local !== undefined) return local;
+      const e = (newsEditions || []).find((x) => x && x.title === name);
+      return e === undefined ? null : { id: e.id, name: e.title, url: '/dsh-music/news/' + e.id, path: '', isNews: true };
+    };
     const markNewsPlayed = (id) => {
       fetch('/dsh-music/news/played', {
         method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id }),
@@ -3025,13 +3066,22 @@ window.__ModuleLoader__.load({
         .catch(() => {});
     };
     // 从新闻期次某块起播（条目跳播/类别跳播/整期播放都归到这里）。
-    function playNewsFrom(id, from) {
+    // `whole` =「播放整期」语义（面板上的整期 ▶、定时任务/agent 的播报意图）。
+    // 已在播同一期时**不重复播放**：整期 ▶ 被再次点击（或意图重复投递）不该把正在听的
+    // 期次从头重播、让听众丢掉当前位置；目标块与当前块相同的条目/类别跳转同理（那只是
+    // 又点了一次正在播的那一条）。真正的「从这一条/这一类重新开始」仍照常跳转。
+    function playNewsFrom(id, from, whole) {
+      const f = from || 0;
       // 多标签页：镜像态下由出声页来播这一期（否则会出现「本页在念新闻、出声页还在放歌」）。
-      if (xtabForward('newsPlay', { id, from: from || 0 })) return;
+      // 守卫交给出声页判定——块号（bookFromRef）不跨页同步，只有出声页知道真实位置。
+      if (xtabForward('newsPlay', { id, from: f, whole: !!whole })) return;
+      if (store.currentId === 'book:' + id && (whole || f === bookFromRef)) return;
       void loadNewsEditions().then((list) => {
         if (!list.some((e) => e.id === id)) return;
+        // 列表回来时这一期可能已经被上一次点击起播了（连点/双击两次单击）：同样不重复播放。
+        if (store.currentId === 'book:' + id && (whole || f === bookFromRef)) return;
         markNewsPlayed(id);
-        playBook(id, from || 0);
+        playBook(id, f);
       });
     }
     const bookById = (id) => (store.books || []).find((b) => b.id === id) || newsBookById(id) || null;
@@ -3217,6 +3267,10 @@ window.__ModuleLoader__.load({
     let restoredMusicPos = null; // restored music position to display until the audio truly reaches it
     let newsResume = null; // 新闻打断快照：{ newsId, kind, id? }（新闻播完自动切回原内容；null=无快照）
     let bookRestorePos = -1;   // restored book's in-chunk position, seeked on play
+    // 换声音的块内续播点：{ from, pos }（只对 from 这一块有效；null=无）。
+    // 与 bookRestorePos 刻意分开——那个带「恢复点越界就跳下一块」的 pastEnd 语义，适合
+    // 刷新续播；换声音时新合成的块时长会变，沿用它会直接吞掉本条新闻的剩余内容。
+    let voiceResume = null;
     // 刚发生过 ended→切块：其后到达的重复 ended 属于旧块陈旧事件（吞掉）；
     // 下一块真正开始播放（play promise 兑现）或用户主动重播/停止时清除。
     let bookJustAdvanced = false;
@@ -3362,7 +3416,13 @@ 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, currentSection: '', bookToc: [], currentQuality: '', bookProgress: 0, scope: { kind: 'book' }, bookBuffering: false, bookBufferingSilent: false, bookError: '', bookBufferingSince: 0 });
+      // 进度条种子（见 bookProgressAtChunk）：切块时显示新块起点，而不是先归零再跳。
+      // 换声音（同一块的重新合成）例外——内容位置没变，保持当前显示不回退，真正的
+      // 位置随后由 applyVoiceResume 的 seek + timeupdate 校正。
+      const seedProgress = (voiceResume !== null && voiceResume.from === from)
+        ? Math.max(bookProgressAtChunk(id, from), store.bookProgress)
+        : bookProgressAtChunk(id, from);
+      set({ currentId: 'book:' + id, currentName: book.name, currentArtists: [], pendingId: null, pendingName: null, error: null, currentSection: '', bookToc: [], currentQuality: '', bookProgress: seedProgress, scope: { kind: 'book' }, bookBuffering: false, bookBufferingSilent: false, bookError: '', bookBufferingSince: 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;
@@ -3370,6 +3430,13 @@ window.__ModuleLoader__.load({
         if (meta !== null && meta.sections.length > 0) {
           set({ currentSection: sectionForChunk(meta.sections, startFrom) });
         }
+        // meta 是这一步才到位的（本会话从未缓存过该书的 charOffsets → 上面种子的
+        // 计算结果是 0）：补一次块起点进度，让它立即显示正确位置而不是停在 0%。
+        // 只在严格前进时写（bp > 当前值），因此绝不会把已经播放推进的显示拉回去。
+        if (currentBookId() === id && bookFromRef === startFrom) {
+          const bp = bookProgressAtChunk(id, startFrom);
+          if (bp > store.bookProgress) set({ bookProgress: bp });
+        }
       });
       set(wasFresh
         ? { bookBuffering: true, bookBufferingSilent: !showBuffer, bookError: '', bookBufferingSince: Date.now() }
@@ -3460,7 +3527,7 @@ window.__ModuleLoader__.load({
       }
     }
     // `from` lets the toc jump straight to a chapter's chunk index.
-    function playBook(id, from = 0) { if (xtabForward('playBook', { id, from })) return; unlockAutoplay(); bookTotal = -1; bookBufferedFrom = -1; bookBaseTime = 0; bookRestorePos = -1; bookAutoRetried = false; bookJustAdvanced = false; clearBookUnwedge(); clearBookGrace(); bookPlaySeq++; bookFallbackFor = ''; revokeBookBlob(); playBookFrom(id, from, false); saveCurrentBookPlayback(); }
+    function playBook(id, from = 0) { if (xtabForward('playBook', { id, from })) return; unlockAutoplay(); bookTotal = -1; bookBufferedFrom = -1; bookBaseTime = 0; bookRestorePos = -1; voiceResume = null; bookAutoRetried = false; bookJustAdvanced = false; clearBookUnwedge(); clearBookGrace(); bookPlaySeq++; bookFallbackFor = ''; revokeBookBlob(); 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.
@@ -3541,6 +3608,7 @@ window.__ModuleLoader__.load({
         // 恢复定位钉只属于「被恢复的那一块」：切到下一块必须丢弃，否则下一块的
         // 音频会被 seek 回上一块的恢复位置（跳到末尾即刻结束 → 卡住/无声音/字幕不动）。
         bookRestorePos = -1;
+        voiceResume = null; // 换声音的续播点同样只属于那一块
         restoredMusicPos = null;
         const endedDur = Number.isFinite(audio.duration) ? audio.duration : (audio.currentTime || 0);
         if (Number.isFinite(endedDur)) bookBaseTime += endedDur;
@@ -3579,6 +3647,30 @@ window.__ModuleLoader__.load({
     // 关键：onDur（durationchange）也调用——只挂在 timeupdate 上时，若元素被钳在
     // 块尾（不再播放、不再派发 timeupdate），pastEnd 补救永远不会被评估，续播就会
     // 永久卡在「没声音、字幕不动」。
+
+    // 换声音的块内续播：新声音的块就绪后把播放位置 seek 回断点，而不是从本条新闻的
+    // 开头重播。与 bookRestorePos（刷新续播）刻意分开：那个带着「恢复点越界就跳下一块」
+    // 的 pastEnd 语义——换声音时新合成的块时长会变，沿用它会直接吞掉本条新闻的剩余内容。
+    // 这里越界只夹到块尾（最坏情况＝本条重播一遍），绝不前进块号。
+    // 只尝试一次：本环境对讲书 WAV 的 seek 可能不生效，反复 seek 会形成紧密循环
+    // （seek→timeupdate→seek…，实测 ct 永远停在 0.00、无声、字幕不动）。
+    // 返回 true 表示「刚 seek 过」——调用方应跳过本帧的位置/进度更新，让 post-seek 的
+    // timeupdate 去校正（否则会把 seek 前的旧位置写回显示）。
+    function applyVoiceResume() {
+      const vr = voiceResume;
+      if (vr === null) return false;
+      if (!String(store.currentId || '').startsWith('book:') || bookFromRef !== vr.from) {
+        voiceResume = null; // 已切到别的块/别的书：本次续播点作废
+        return false;
+      }
+      const dur = (Number.isFinite(audio.duration) && audio.duration > 0) ? audio.duration : 0;
+      if (!(dur > 0)) return false; // 时长未知：留给 onDur / 下一帧
+      voiceResume = null;           // 一次性：无论 seek 是否生效都不再重试
+      const target = Math.max(0, Math.min(vr.pos, Math.max(0, dur - 0.25)));
+      if (target < 0.2) return false; // 断点本来就在块首：无需 seek
+      try { audio.currentTime = target; } catch (e) {}
+      return true;
+    }
     function evaluateBookRestorePin() {
       if (!(bookRestorePos >= 0) || !String(store.currentId || '').startsWith('book:')) return false;
       const ct = audio.currentTime || 0;
@@ -3624,7 +3716,7 @@ window.__ModuleLoader__.load({
       bookPlaySeq++;
       bookFallbackFor = '';
       revokeBookBlob();
-      bookTotal = -1; bookFromRef = 0; bookBufferedFrom = -1; bookBaseTime = 0; bookRestorePos = -1; bookJustAdvanced = false;
+      bookTotal = -1; bookFromRef = 0; bookBufferedFrom = -1; bookBaseTime = 0; bookRestorePos = -1; bookJustAdvanced = false; voiceResume = null;
     }
     function togglePlay() {
       // 多标签页：镜像态下播放/暂停归出声页——本页的 <audio> 是暂停的，直接执行会
@@ -3895,6 +3987,10 @@ window.__ModuleLoader__.load({
           set({ voiceSwitching: false });
           if (currentBookId() === id && bookFromRef === from) {
             unlockAutoplay();
+            // 断点取「旧声音真正停下的这一刻」（合成期间旧声音一直在播，所以不能在
+            // 函数入口取）+ 新块就绪后由 applyVoiceResume 把位置 seek 回去：换声音
+            // 不再从本条新闻开头重播。
+            voiceResume = { from, pos: audio.currentTime || 0 };
             playBookFrom(id, from, true);
           }
         })
@@ -3990,6 +4086,9 @@ window.__ModuleLoader__.load({
         // 讲书：按「已读字符/全书字符」实时推进全书进度条。不用 position/duration 的
         // 时间占比——那是当前块内比例，切块会回退；且全书总时长在合成本书前不可知。
         if (String(store.currentId).startsWith('book:')) {
+          // 换声音的兜底：onDur 没到达时（个别环境 duration 早就绪）也要把位置 seek 回
+          // 断点。刚 seek 过则跳过本帧更新，避免把 seek 前的旧位置写回进度条。
+          if (voiceResume !== null && applyVoiceResume()) return;
           const bp = bookProgressFor();
           if (bp !== store.bookProgress) set({ bookProgress: bp });
         }
@@ -4056,6 +4155,8 @@ window.__ModuleLoader__.load({
           // 钳到块尾、不再播放、不再派发 timeupdate 时永远轮不到补救（冷启动续播
           // 「响一下→没声音、字幕不动」的残留卡死点）。
           if (bookRestorePos >= 0 && String(store.currentId).startsWith('book:')) evaluateBookRestorePin();
+          // 换声音：时长一就绪就把位置 seek 回块内断点（只试一次，见 applyVoiceResume）。
+          if (voiceResume !== null) applyVoiceResume();
           set({ duration: (bookTimeBase() + audio.duration) });
         }
       };
@@ -4187,6 +4288,20 @@ window.__ModuleLoader__.load({
             markOnlineAuthFailed('nc', '网易云音乐');
             return;
           }
+          // 本地曲目解码/加载失败：最常见的原因是**文件末帧被截断**——Chrome 改用 Rust
+          // 写的 Symphonia 解码器后比旧解码器严格，最后一个不完整帧会直接报
+          // MEDIA_ERR_DECODE（"malformed stream: mpa: invalid packet length"），
+          // 表现为「放到 99.9% 突然停住、不切下一首」。
+          // 一个坏文件不该终止整个播放：自动跳到下一首继续；连续跳过次数达到当前队列
+          // 长度（整列都是坏文件）才停下报错，且停下后不再 step，杜绝无限跳歌。
+          if (!isOnlineTrack) {
+            const localQueueLen = activeIds().length;
+            if (localQueueLen > 1 && localErrorSkipCount < localQueueLen) {
+              localErrorSkipCount++;
+              step(1);
+              return;
+            }
+          }
           set({ error: '音频加载或解码失败', playing: false });
         }
       };
@@ -4204,7 +4319,7 @@ window.__ModuleLoader__.load({
       // 时清零——绝不能挂在 'play' 上：play() 把 paused 置 false 就会派发 'play'，加载失败
       // 的源同样会先收到它，用它清零会让计数每轮归零，整列曲目全失败时无限回绕切歌
       // （实测：QQ 登录过期后整列 VIP 曲目 404，播放条无限循环切歌、不报错、停不下来）。
-      const onPlaying = () => { if (xtabMirroring) return; qqErrorSkipCount = 0; if (!String(store.currentId || '').startsWith('book:')) setupLiveViz(); resumeVizCtx(); };
+      const onPlaying = () => { if (xtabMirroring) return; qqErrorSkipCount = 0; localErrorSkipCount = 0; if (!String(store.currentId || '').startsWith('book:')) setupLiveViz(); resumeVizCtx(); };
       audio.addEventListener('playing', onPlaying);
       return () => {
         audio.pause();
@@ -4356,6 +4471,9 @@ window.__ModuleLoader__.load({
       savePref(PREF_PLAYBACK_NC, JSON.stringify({ ...saved, ts: Date.now() }));
     }
 
+    // 新闻期次恢复的重试守卫：记下「已经为哪个名字补拉过 /news 列表」，每个名字至多一次，
+    // 避免期次已删除时每次恢复都发一轮请求。
+    let newsRestoreRetryName = null;
     // Restore a novel's playback after a refresh (or when resuming a book):
     // same book, same chunk, same cumulative clock, and same in-chunk position —
     // paused (tap ▶ to resume), matching how music is restored. When targetName
@@ -4373,8 +4491,25 @@ window.__ModuleLoader__.load({
         }
       }
       if (entry === null || !name) return;
-      const book = store.books.find((b) => b.name === name);
-      if (book === undefined) return; // the book is no longer in the library
+      // 名字 → 虚拟书：本地讲书（store.books）或**新闻期次**（期次标题，见 bookByName）。
+      const book = bookByName(name);
+      if (book === null) {
+        // 新闻期次列表是异步拉取的，而刷新恢复跑在 /manifest 之后、面板拉 /news 之前——
+        // 这时 bookByName 找不到期次标题。拉一次期次列表再重试（每个名字至多一次，
+        // 避免「期次已删除」时反复请求）。
+        if (newsRestoreRetryName !== name) {
+          newsRestoreRetryName = name;
+          void loadNewsEditions().then((list) => {
+            if (newsRestoreRetryName !== name) return; // 已被后续恢复取代
+            // 请求期间用户已经自己播了别的（currentId 非空）→ 不抢走播放器。
+            if (store.currentId !== null) { newsRestoreRetryName = null; return; }
+            if (!(list || []).some((e) => e && e.title === name)) { newsRestoreRetryName = null; return; }
+            restoreBookPlayback(name);
+          });
+        }
+        return; // 不在曲库也不是现存的期次：放弃（书/期次已删）
+      }
+      newsRestoreRetryName = null;
       const from = Number.isFinite(entry.from) && entry.from >= 0 ? entry.from : 0;
       const base = Number.isFinite(entry.base) ? entry.base : 0;
       const pos = Number.isFinite(entry.pos) ? entry.pos : 0;
@@ -4730,6 +4865,20 @@ window.__ModuleLoader__.load({
     const StopIcon = iconSvg('M6 6h12v12H6z');
 
     // ---- components ----
+    // ---- 音量滚轮调速参数 ----
+    // 在音量条上滚动滚轮即可调音量，步进按滚动快慢分两档：慢速 1%、快速 5%。
+    // 「快慢」同时看两个信号——连续两次滚轮事件的间隔、以及单次滚动量——这样鼠标
+    // 滚轮和触控板都能得到符合直觉的结果：
+    //   - 鼠标滚轮：一格约 100（像素模式），慢慢拨 → 间隔大 → 慢速 1%；快速连拨 → 5%。
+    //   - 触控板：轻推是每帧 1~5 的细碎增量，即使事件密集（间隔很小）也判为慢速（1%）；
+    //     用力快滑时单次增量明显变大 → 5%。
+    //   - 归一化后单次滚动量达到 VOL_WHEEL_FAST_DELTA（多行/惯性滑动）直接算快速。
+    // 要改手感只调下面这几个数即可。
+    const VOL_WHEEL_STEP_SLOW = 0.01;  // 慢速滚动：每次 1%
+    const VOL_WHEEL_STEP_FAST = 0.05;  // 快速滚动：每次 5%
+    const VOL_WHEEL_FAST_GAP_MS = 80;  // 两次滚轮事件间隔小于此值算「连续快速」
+    const VOL_WHEEL_MIN_DELTA = 20;    // 判为快速所需的单次最小滚动量（滤掉触控板细碎滚动）
+    const VOL_WHEEL_FAST_DELTA = 200;  // 单次滚动量达到此值直接算快速（多行/惯性滑动）
     // Custom vertical volume slider. The native <input type=range> cannot be
     // fully restyled in current Chrome (track keeps gray border lines and the
     // thumb ignores width/height once appearance:none is set), so the slider is
@@ -4739,6 +4888,8 @@ window.__ModuleLoader__.load({
       const s = useStore();
       const trackRef = useRef(null);
       const draggingRef = useRef(false);
+      // 上一次滚轮事件的时刻，用于判断两次滚动是否「连续快速」。
+      const wheelAtRef = useRef(0);
       const valueFor = (clientY) => {
         const el = trackRef.current;
         if (el === null) return s.volume;
@@ -4762,6 +4913,34 @@ window.__ModuleLoader__.load({
         draggingRef.current = false;
         if (e.currentTarget.hasPointerCapture(e.pointerId)) e.currentTarget.releasePointerCapture(e.pointerId);
       };
+      // 滚轮调音量。必须用原生监听器注册（passive: false）：React 的 onWheel 走被动
+      // 监听，在被动监听里 preventDefault 无效，滚轮会连带把外层对话/面板一起滚走。
+      useEffect(() => {
+        const el = trackRef.current;
+        if (el === null) return undefined;
+        const onWheel = (e) => {
+          // deltaMode: 0=像素 1=行 2=页，先统一折算成像素量再比较快慢。
+          const unit = e.deltaMode === 1 ? 16 : (e.deltaMode === 2 ? 100 : 1);
+          const d = e.deltaY * unit;
+          if (d === 0) return;
+          e.preventDefault(); // 这一次滚轮由音量条消费，不再冒泡去滚动页面
+          if (draggingRef.current) return; // 拖拽中音量由指针位置决定，忽略滚轮
+          const now = Date.now();
+          const gap = now - wheelAtRef.current;
+          wheelAtRef.current = now;
+          const fast = (gap < VOL_WHEEL_FAST_GAP_MS && Math.abs(d) >= VOL_WHEEL_MIN_DELTA)
+            || Math.abs(d) >= VOL_WHEEL_FAST_DELTA;
+          const step = fast ? VOL_WHEEL_STEP_FAST : VOL_WHEEL_STEP_SLOW;
+          // 上滚（deltaY < 0）加音量、下滚减音量。先钳位再交给 changeVolume：
+          // 它转发给「出声页」的是钳位前的原值，钳位放在这里可避免越界值被广播出去。
+          // 结果按 0.1% 取整，防止浮点累加出 0.8300000000000001 这类脏值落进 prefs。
+          const raw = store.volume + (d < 0 ? step : -step);
+          const next = Math.round(Math.min(1, Math.max(0, raw)) * 1000) / 1000;
+          changeVolume(next);
+        };
+        el.addEventListener('wheel', onWheel, { passive: false });
+        return () => el.removeEventListener('wheel', onWheel);
+      }, []);
       const pct = Math.round(s.volume * 100);
       return React.createElement('div',
         { className: 'dsh-music-vol-slider', ref: trackRef,
@@ -5519,7 +5698,14 @@ window.__ModuleLoader__.load({
             .catch(() => showToast('删除失败', false));
         }, '删除', true);
       };
-      const playFrom = (id, from) => playNewsFrom(id, from || 0);
+      const playFrom = (id, from, whole) => playNewsFrom(id, from || 0, whole);
+      // 「播放整期」：该期已在播时绝不从头重播——正在播就禁用（title 提示），暂停中则
+      // 从当前位置继续。与讲书列表「点当前这本 = 播放/暂停」同一约定：列表里的播放控件
+      // 不重播正在播的内容（误触一次就会丢掉听到的位置）。
+      const playWhole = (id) => {
+        if (playingEditionId() === id) { if (!s.playing) togglePlay(); return; }
+        playFrom(id, 0, true);
+      };
 
       // ---- 定时编辑器辅助 ----
       // 范围摘要文本（手动执行指令用）：scope 必填；空/旧 null 范围兜底展示全部预设类别。
@@ -5646,7 +5832,15 @@ window.__ModuleLoader__.load({
               fmtTs(e.createdAt) + (chips ? ' · ' + chips : '')),
           ),
           React.createElement('div', { className: 'dsh-music-news-card-actions' },
-            React.createElement('button', { className: 'dsh-music-settings-btn', title: '播放整期', onClick: (ev) => { ev.stopPropagation(); playFrom(e.id, 0); } }, '▶'),
+            // 正在播的这一期：▶ 禁用（不重播、也不提供第二个暂停入口）；暂停中的这一期：
+            // ▶ 变「继续播放」，点了从当前位置接着播。
+            React.createElement('button', {
+              className: 'dsh-music-settings-btn',
+              title: playing ? (s.playing ? '正在播放中' : '继续播放') : '播放整期',
+              disabled: playing && s.playing,
+              style: (playing && s.playing) ? { opacity: 0.45, cursor: 'default' } : undefined,
+              onClick: (ev) => { ev.stopPropagation(); playWhole(e.id); },
+            }, '▶'),
             React.createElement('button', {
               className: 'dsh-music-icon-btn', title: '删除',
               onClick: (ev) => { ev.stopPropagation(); deleteEdition(e.id); },
@@ -5705,10 +5899,42 @@ window.__ModuleLoader__.load({
         if (meta === null) return React.createElement('div', { className: 'dsh-music-empty' }, '加载中…');
         const id = meta.id;
         let seq = 0;
+        // 正在播的那一条：由「已读字符占比 + charOffsets」反推当前块号（bookProgress 本就
+        // 跨页同步、meta 本地就有，因此镜像页也算得对），再按 itemChunk 区间落到具体条目
+        // ——一条新闻一个块，超长条目被切成多块时归到它的起始区间。播放中/暂停中都算
+        // 「正在播这一条」，用于标注 + 禁用它自己的 ▶（点了也不会重播，见 playNewsFrom）。
+        const curChunk = (() => {
+          if (playingEditionId() !== id) return -1;
+          const offs = meta.charOffsets || [];
+          const total = offs.length > 0 ? offs[offs.length - 1] : 0;
+          if (!(total > 0)) return -1;
+          const consumed = (s.bookProgress || 0) * total;
+          let k = 0;
+          for (let i = 0; i < offs.length - 1; i++) { if (offs[i] <= consumed) k = i; else break; }
+          return k;
+        })();
+        // itemChunk 是按条目顺序升序的「该条起始块号」：当前块落在哪一条，就是起始块号
+        // ≤ 当前块的最后一条（一条一个块时即「起始块号 == 当前块」；超长条目被切成多块时
+        // 也不会误标到别的条目上）。
+        const curItemIdx = (() => {
+          if (curChunk < 0) return -1;
+          const chunks = meta.itemChunk || [];
+          let best = -1;
+          for (let i = 0; i < chunks.length; i++) {
+            if (typeof chunks[i] === 'number' && chunks[i] <= curChunk) best = i;
+            else break;
+          }
+          return best;
+        })();
+        const itemPlaying = (idx) => idx === curItemIdx;
         const sections = (meta.sections || []).map((sec, si) => {
+          // 正在播这一期时标出当前类别（currentSection 由块号映射得到）：让「现在在念哪一类」
+          // 一眼可见，而不是靠点一下才知道。
+          const curSec = playingEditionId() === id && s.currentSection === sec.heading;
           const rows = (meta.categories ? meta.categories[si].items : []).map((it) => {
             seq += 1;
             const chunk = (meta.itemChunk || [])[seq - 1] || 0;
+            const curItem = itemPlaying(seq - 1);
             // 文字版（readOnly）：文章排版——标题段 + 完整摘要段 + 来源行；不截断、无 ▶。
             if (readOnly) {
               return React.createElement('div', { key: seq, style: { marginBottom: 10 } },
@@ -5724,15 +5950,27 @@ window.__ModuleLoader__.load({
                 title: it.summary,
                 onClick: () => { if (!readOnly) playFrom(id, chunk); },
               },
-                React.createElement('span', { className: 'dsh-music-track-name' }, seq + '. ' + it.title),
+                React.createElement('span', { className: 'dsh-music-track-name' },
+                  curItem ? React.createElement('span', { className: 'dsh-music-news-card-badge live', style: { marginRight: 6 } }, '正在播') : null,
+                  seq + '. ' + it.title),
                 React.createElement('span', { className: 'dsh-music-track-size' }, (it.source || '来源未知') + (it.publishedAt ? ' · ' + it.publishedAt : '') + ' · ' + it.summary),
               ),
-              readOnly ? null : React.createElement('button', { className: 'dsh-music-settings-btn', title: '从这条开始播', onClick: () => playFrom(id, chunk) }, '▶'),
+              // 正在播的这一条：▶ 禁用（点了也不会重播——守卫在 playNewsFrom，这里只是把
+              // 状态显示出来，免得用户以为按钮坏了）。
+              readOnly ? null : React.createElement('button', {
+                className: 'dsh-music-settings-btn',
+                title: curItem ? '正在播放中' : '从这条开始播',
+                disabled: curItem,
+                style: curItem ? { opacity: 0.45, cursor: 'default' } : undefined,
+                onClick: () => playFrom(id, chunk),
+              }, '▶'),
             );
           });
           return React.createElement('div', { key: si },
             React.createElement('div', { style: { fontWeight: 600, margin: '8px 0 4px', display: 'flex', alignItems: 'center', justifyContent: 'space-between' } },
-              React.createElement('span', null, sec.heading + '（' + sec.itemCount + '）'),
+              React.createElement('span', null,
+                curSec ? React.createElement('span', { className: 'dsh-music-news-card-badge live', style: { marginRight: 6 } }, '正在播') : null,
+                sec.heading + '（' + sec.itemCount + '）'),
               readOnly ? null : React.createElement('button', { className: 'dsh-music-settings-btn ghost', onClick: () => playFrom(id, sec.fromChunk) }, '▶'),
             ),
             rows,
@@ -5762,7 +6000,17 @@ window.__ModuleLoader__.load({
           React.createElement('div', { className: 'dsh-music-news-head' },
             headBar(edition.title || '期次详情', { kind: 'list' }),
             React.createElement('div', { style: { display: 'flex', gap: 8, marginBottom: 6 } },
-              readOnly ? null : React.createElement('button', { className: 'dsh-music-settings-btn', onClick: () => playFrom(view.id, 0) }, '▶ 播放整期'),
+              readOnly ? null : (() => {
+                const cur = playingEditionId() === view.id;
+                const busy = cur && s.playing;
+                return React.createElement('button', {
+                  className: 'dsh-music-settings-btn',
+                  title: busy ? '正在播放中' : (cur ? '继续播放' : '播放整期'),
+                  disabled: busy,
+                  style: busy ? { opacity: 0.45, cursor: 'default' } : undefined,
+                  onClick: () => playWhole(view.id),
+                }, busy ? '正在播放' : (cur ? '▶ 继续播放' : '▶ 播放整期'));
+              })(),
               React.createElement('button', { className: 'dsh-music-settings-btn ghost', onClick: () => setView(readOnly ? { kind: 'detail', id: view.id } : { kind: 'read', id: view.id }) }, readOnly ? '◀ 条目视图' : '文字版'),
               readOnly ? null : React.createElement('button', { className: 'dsh-music-settings-btn ghost', style: { color: '#c0392b' }, onClick: () => deleteEdition(view.id) }, '删除'),
             ),
@@ -6458,7 +6706,9 @@ window.__ModuleLoader__.load({
                   setLoginReason(''); // 已重新登录：清掉失效原因
                   resetKgAuthExpired(); // 新登录态：清掉「登录已过期」标记
                   // 同步全局 store：让「关于」页运行状态即时显示酷狗昵称（对齐 QQ 登录同步 qqLoggedIn 的先例）。
-                  set({ kgLoggedIn: true, kgNickname: c.nickname || '' });
+                  // 重新登录成功 = 失效原因已消除：连面板顶部那条陈旧报错一起清掉
+                  // （否则它会一直挂到下次播放歌曲，见 QQ 面板 [s.error] 的渲染）。
+                  set({ kgLoggedIn: true, kgNickname: c.nickname || '', error: null });
                   // 登录成功直接关闭二维码弹窗，不显示任何提示。
                   setLoginOpen(false); setLoginMsg('');
                 } else if (c.status === 'expired') { setLoginMsg('二维码已过期，请点击刷新'); }
@@ -7430,7 +7680,8 @@ window.__ModuleLoader__.load({
                   // 同步全局 store（对齐 QQ/酷狗）：引擎侧判定「整列播不出来 → 疑似登录失效」
                   // 依赖 store.ncLoggedIn，不同步就会漏判（它原本只来自 manifest，登录发生在页面
                   // 加载之后时是旧的）。
-                  set({ ncLoggedIn: true, ncNickname: c.nickname || '' });
+                  // 同酷狗：重新登录成功即清掉陈旧报错。
+                  set({ ncLoggedIn: true, ncNickname: c.nickname || '', error: null });
                   // 切到「我的歌单」+ 加载由 [loggedIn] effect 统一处理（刷新/登录两路都覆盖）
                 } else if (c.status === 'expired') { setLoginMsg('二维码已过期，请点击刷新'); }
                 else if (c.status === 'scanned') { setLoginMsg('已扫码，请在手机上确认'); pollTimer.current = setTimeout(tick, 1500); }
@@ -8237,6 +8488,11 @@ window.__ModuleLoader__.load({
       const topBusy = useRef({});
       const [cnMap, setCnMap] = useState({});
       const cnBusy = useRef({});
+      // 「加载更多」进行中的**可见**状态（'top:all' / 'cn:music' … → true）。
+      // topBusy/cnBusy 是 ref（防重入用，不触发渲染），因而点「加载更多」后直到请求返回
+      // 都不会重渲染 → 按钮文案永远停在「加载更多」、看不到「加载中…」（与在线音乐页面
+      // 用 state 驱动的表现不一致）。这里用一份 state 专供按钮文案/可用态。
+      const [dirBusyUi, setDirBusyUi] = useState({});
       const [err, setErr] = useState('');
       // 目录首屏加载失败态（自动重试耗尽）：{ kind:'top'|'cn', group }。命中时该组视图
       // 显示「加载失败 + 手动重试」，而不是永远停在「加载中…」（此前失败只能切走再切回）。
@@ -8288,6 +8544,7 @@ window.__ModuleLoader__.load({
         };
         const sleep = (ms) => new Promise((r) => { dirRetryTimer.current = setTimeout(r, ms); });
         busyRef.current[g] = true;
+        setDirBusyUi((m) => ({ ...m, [kind + ':' + g]: true })); // 让按钮立刻变「加载中…」
         setErr('');
         setDirFail((f) => (f && f.kind === kind && f.group === g ? null : f));
         const offset = cur ? cur.offset : 0;
@@ -8304,6 +8561,7 @@ window.__ModuleLoader__.load({
         }
         const showResult = stillActive();
         busyRef.current[g] = false;
+        setDirBusyUi((m) => { const n = { ...m }; delete n[kind + ':' + g]; return n; }); // 按钮恢复「加载更多」
         if (d && d.ok && Array.isArray(d.stations)) {
           const page = d.stations;
           const prev = cur ? cur.rows : [];
@@ -8427,13 +8685,21 @@ window.__ModuleLoader__.load({
       }, label);
       // 「加载更多」底部按钮：目录还有下一页（未到底）时显示；点击追加下一页。
       // kind: 'top' | 'cn'；data 为该组的 { rows, done } 状态。
+      // 与在线音乐（QQ / 酷狗 / 网易云）同款：`.dsh-music-qq-loadmore` +
+      // `.dsh-music-qq-loadmore-btn` 的胶囊按钮（类名源自 QQ 页，但早已是各在线页共用的
+      // 样式）。此前电台页用的是通用 .dsh-music-settings-btn + 内联 padding，两处观感不一致。
       const loadMoreFooter = (kind, data) => {
-        const busy = kind === 'top' ? topBusy.current[topGroup] : cnBusy.current[cnGroup];
+        const g = kind === 'top' ? topGroup : cnGroup;
+        // 文案/可用态取自 state（dirBusyUi）而不是 topBusy/cnBusy 这两个 ref：ref 变化不触发
+        // 渲染，点了按钮也看不到「加载中…」（见 dirBusyUi 处说明）。
+        const busy = !!dirBusyUi[kind + ':' + g];
         if (data === undefined || data.done) return null;
-        return React.createElement('div', { style: { display: 'flex', justifyContent: 'center', padding: '10px 0 4px' } },
+        return React.createElement('div', { className: 'dsh-music-qq-loadmore' },
           React.createElement('button', {
-            className: 'dsh-music-settings-btn', disabled: !!busy,
-            onClick: () => { if (kind === 'top') loadTop(topGroup, true); else loadCn(cnGroup, true); },
+            className: 'dsh-music-qq-loadmore-btn',
+            // 不置 disabled（与在线音乐一致：忙碌态只把文案换成「加载中…」，不换个灰按钮的
+            // 样子）；重入由 loadDirPage 的 busyRef 守卫兜住。
+            onClick: () => { if (busy) return; if (kind === 'top') loadTop(topGroup, true); else loadCn(cnGroup, true); },
           }, busy ? '加载中…' : '加载更多'));
       };
       const listEl = (() => {
@@ -9104,7 +9370,7 @@ window.__ModuleLoader__.load({
             d = await fetch('/dsh-music/qq/login/check?key=' + encodeURIComponent(key), { cache: 'no-store', signal: ctrl ? ctrl.signal : undefined }).then((r) => r.json());
           } finally { if (timer) clearTimeout(timer); }
           if (!d || !d.ok) { setLoginStatus((d && d.error) || '查询失败，正在重试…'); schedulePoll(); return; }
-          if (d.status === 'success') { clearPoll(); setLoggedIn(true); setUin(d.uin || ''); setNickname(d.nickname || ''); setLayer('main'); setActivePl(null); saveUi('main', '', ''); closeLogin(); refreshQQFavIds(); resetQQAuthExpired(); set({ qqLoggedIn: true, qqLoginFrom: d.loginFrom || '' }); }
+          if (d.status === 'success') { clearPoll(); setLoggedIn(true); setUin(d.uin || ''); setNickname(d.nickname || ''); setLayer('main'); setActivePl(null); saveUi('main', '', ''); closeLogin(); refreshQQFavIds(); resetQQAuthExpired(); set({ qqLoggedIn: true, qqLoginFrom: d.loginFrom || '', error: null }); }
           else if (d.status === 'scanned') { setLoginStatus('已扫码，请在手机上确认'); schedulePoll(); }
           else if (d.status === 'expired') { clearPoll(); setLoginStatus('二维码已过期'); }
           else if (d.status === 'failed') { clearPoll(); setLoginStatus(d.message || '登录失败'); }
@@ -10849,7 +11115,8 @@ window.__ModuleLoader__.load({
               return;
             }
             newsResume = snapshotNewsResume(intent.id);
-            playNewsFrom(intent.id, 0);
+            // whole=true：「播这一期」语义——同一期已在播时（重复投递/冷却窗回推）不从头重播。
+            playNewsFrom(intent.id, 0, true);
             return;
           }
           // 网络电台（agent source=radio 或面板点击）：intent 带完整 station 字段

package/lib/fetch-limit.js

@@ -0,0 +1,84 @@
+/**
+ * lib/fetch-limit.js — 极简出网限流器（并发上限 + 最小启动间隔 + **有界**队列）。
+ *
+ * 背景：插件里有若干「不依赖用户交互」的自动出网请求（典型：本地歌曲没歌词时按歌自动
+ * 触发的在线歌词兜底）。连续切歌时它们会对第三方非官方接口形成无上限的并发请求，既可能
+ * 耗尽配额/被限流封禁，也没有任何资源上限（CWE-770）。本模块提供一个小而明确的限流器：
+ *
+ *   - maxConcurrent：同时在跑的请求数上限；
+ *   - minGapMs：两次**启动**之间的最小间隔（上一次请求过去足够久时，下一次立即启动——
+ *     即空闲时首个请求不额外等待）；
+ *   - maxQueue：排队长度上限，超出立即失败（**资源有界**，而不是无限堆积）。
+ *
+ * 关键语义（与「超时兜底」配合使用，别写反）：
+ *   调用方应**先**起自己的超时计时器，再把请求交给 limiter.run()，并把 signal 传进来。
+ *   这样排队等待也吃这份超时预算：排队超时 → 立刻出队失败、**根本不会发出上游请求**；
+ *   否则队列一长，超时兜底会被排队拖成 ⌊k/并发⌋×timeout，退化成「明明做了超时却还是会
+ *   长时间卡住」。
+ *
+ * 无第三方依赖；实例是进程内共享的，请按调用方（模块/端点）各建一个实例，避免相互排队。
+ */
+
+function makeAbortError() {
+  // 与 fetch 被 abort 时抛出的错误同形（调用方一律按「失败 → 静默回退」处理）。
+  const err = new Error('The operation was aborted')
+  err.name = 'AbortError'
+  return err
+}
+
+/**
+ * @param {{ maxConcurrent?: number, minGapMs?: number, maxQueue?: number }} [opts]
+ * @returns {{ run: (task: () => any, o?: { signal?: AbortSignal }) => Promise<any>, queued: () => number, running: () => number }}
+ */
+export function createLimiter({ maxConcurrent = 2, minGapMs = 250, maxQueue = 8 } = {}) {
+  let running = 0
+  let lastStartAt = 0
+  let gapTimer = null
+  const queue = []
+
+  const pump = () => {
+    if (gapTimer !== null) return          // 已安排了下一次启动（间隔未到）
+    if (running >= maxConcurrent) return   // 并发已满
+    if (queue.length === 0) return
+    const wait = Math.max(0, lastStartAt + minGapMs - Date.now())
+    if (wait > 0) {
+      // 只在「距上次启动不足 minGapMs」时才等——空闲后的第一个请求 wait=0、立即启动。
+      gapTimer = setTimeout(() => { gapTimer = null; pump() }, wait)
+      return
+    }
+    const item = queue.shift()
+    running += 1
+    lastStartAt = Date.now()
+    item.start()
+    pump()                                 // 还有额度就继续（仍受 minGapMs 约束）
+  }
+
+  const release = () => {
+    running = Math.max(0, running - 1)
+    pump()
+  }
+
+  const run = (task, { signal } = {}) => new Promise((resolve, reject) => {
+    if (signal && signal.aborted) { reject(makeAbortError()); return }
+    if (queue.length >= maxQueue) { reject(new Error('fetch queue full (' + maxQueue + ')')); return }
+    const item = { start: null }
+    // 排队期间被 abort（调用方的超时到点）：直接出队、失败，不发上游请求。
+    const onAbort = () => {
+      const i = queue.indexOf(item)
+      if (i >= 0) queue.splice(i, 1)
+      reject(makeAbortError())
+    }
+    if (signal) signal.addEventListener('abort', onAbort, { once: true })
+    item.start = () => {
+      if (signal) signal.removeEventListener('abort', onAbort)
+      Promise.resolve().then(task).then(
+        (value) => { release(); resolve(value) },
+        (err) => { release(); reject(err) },
+      )
+    }
+    queue.push(item)
+    pump()
+  })
+
+  return { run, queued: () => queue.length, running: () => running }
+}

package/lib/index.js

@@ -2846,7 +2846,7 @@ export function apply(ctx) {
   const kgTakeInFlight = new Map() // hash -> Promise<entry>
 
   // 登录态动作的统一包装：直接原样请求，不做任何前置续命/刷新。
-  // 决策（2026-09-06）：主动续命已停用（见下方 maybeRefreshKgSession 注释）——
+  // 决策（2026-09-06 停用 / 2026-09-20 删除实现）：不做主动续命——
   // 社区实证 login_by_token 是「探活/续期」而非换发，token 常态可活数周；
   // 与其定时打扰官方（反感频繁调用），不如 token 真过期时由业务请求撞
   // 20017/20018 → 让用户重新扫码一次（酷狗无其他续命手段，重扫是唯一正道）。
@@ -2905,62 +2905,9 @@ export function apply(ctx) {
     const file = await kgCookieFile()
     if (file !== null) { try { writeFileSync(file, JSON.stringify({ session: kg.session, loggedIn: false, savedAt: Date.now() }), { encoding: 'utf8', mode: 0o600 }) } catch { /* ignore */ } }
   }
-  // ══════════════════════════════════════════════════════════════════
-  // 【停用】酷狗主动续命（maybeRefreshKgSession）——2026-09-06 起不再调用。
-  //
-  // 决策背景：社区实证（MakcRe issue #117 作者亲述 + lx-music + kgqd）表明——
-  //   1. login_by_token 是「用原 token+userid 重新登录探活」而非换发新 token，
-  //      token 无硬性 24h 寿命，常态可活数周（官方有时半月~一月才作废）；
-  //   2. 官方反感频繁调用续命接口；且登录后立刻 refresh / 定时 refresh 的额外
-  //      调用，实测曾导致 token 被提前作废（登录后 ~24h 就失效的异常现象）；
-  //   3. 与其定时打扰官方，不如 token 真过期时由业务请求撞 20017/20018 → 让用户
-  //      重新扫码一次（酷狗无其他续命手段，重扫是唯一正道）。
-  // 停用后 token 生命周期 = 完全由酷狗侧决定；过期时 kgWithFreshToken 的 catch
-  // 分支清 cookie + kgLoginDead，前端跳回扫码页提示重新登录。
-  //
-  // 保留下方实现注释供未来需要时恢复（若酷狗 token 寿命显著缩短再评估启用）。
-  // ══════════════════════════════════════════════════════════════════
-  // 主动续命：登录态还在但距上次刷新超过 KG_REFRESH_TTL（24h）时，先静默调一次
-  // v5/login_by_token（社区惯例：每天一次/每次重启一次，官方反感频繁调用）。
-  // ⚠️ 续命失败【不登出】——对齐 lx-music（refresh 失败仅记日志、保留旧 token，
-  // 下轮再试）。login_by_token 是「用原 token 探活/续期」而非换发（MakcRe issue
-  // #117：token 无硬性 24h 寿命，常态可活数周）；续命失败多数是临时网络/风控，
-  // 直接 clearKGCookie 会把用户硬登出。token 是否真死由后续业务请求的
-  // 20017/20018 判定（kgWithFreshToken 的 catch 分支负责，那里才登出）。
-  // ⚠️ 在途去重：TTL 到期瞬间的并发请求（取链 HEAD/GET 几乎同时到达）会各自
-  // 用同一个旧 token 发两次 login_by_token——若酷狗换发新 token 时作废旧
-  // token，第二发必收 20018，会把还活着的会话误判成「登录已死」清掉。这里把
-  // 在途刷新的 Promise 共享给并发调用：同一时刻最多只有一次真实刷新请求。
-  // const KG_REFRESH_TTL = 24 * 60 * 60 * 1000
-  // let kgRefreshInFlight = null
-  // const maybeRefreshKgSession = async () => {
-  //   await loadKGCookie()
-  //   if (!kg.loggedIn) return
-  //   if (kgSavedAt > 0 && Date.now() - kgSavedAt < KG_REFRESH_TTL) return
-  //   if (kgRefreshInFlight) return kgRefreshInFlight
-  //   const tokenAtStart = kg.session.token
-  //   kgRefreshInFlight = (async () => {
-  //     try {
-  //       const refreshed = await KG.refreshSession(kg.session)
-  //       // 刷新期间发生了重扫/登出（token 已换）→ 本次结果作废：不回写旧 token 的
-  //       // 刷新产物，避免覆盖刚登录的新会话。
-  //       if (kg.session.token !== tokenAtStart) return
-  //       if (!refreshed.token) return
-  //       kg.session.token = refreshed.token
-  //       kg.session.vip_type = refreshed.vip_type || kg.session.vip_type
-  //       kg.session.vip_token = refreshed.vip_token || kg.session.vip_token
-  //       if (refreshed.t1) kg.session.t1 = refreshed.t1
-  //       await saveKGCookie()
-  //     } catch (e) {
-  //       // 续命失败不登出：可能只是瞬时网络/风控抖动。token 是否真死交给后续业务
-  //       // 请求的 20017/20018 判定（kgWithFreshToken catch 分支才 clearKGCookie）。
-  //       kg.logger && kg.logger.warn && kg.logger.warn('酷狗主动续命失败（保留登录态）：' + String((e && e.message) || e))
-  //     } finally {
-  //       kgRefreshInFlight = null
-  //     }
-  //   })()
-  //   return kgRefreshInFlight
-  // }
+  // 这里原本是一整段注释形式的 maybeRefreshKgSession 实现（含 KG_REFRESH_TTL / 在途去重），
+  // 已随 lib/kugou.js 的 refreshSession 于 2026-09-20 一起删除（停用理由见上一条注释；
+  // 需要旧实现时从 git 历史找回），避免读者误以为这条路径还活着。
 
   // 取链结果短缓存（同 QQ）：同一首歌的 <audio> 加载与频谱信封两次请求命中 /kg/play，
   // 缓存保证两拿到的档位一致且省一次 tracker 往返。失败原因随 entry 带回给路由展示。

package/lib/kugou.js

@@ -931,99 +931,9 @@ export function explainKgError(json, httpStatus) {
   return `${msg || ('error_code=' + code)}（HTTP ${httpStatus}）`
 }
 
-// =====================================================================
-// Token 刷新（v5/login_by_token）：kgqd 生产环境每次用前先刷新。
-// 把扫码签发的 token 兑换为标准作用域 token，顺带回填 vip_type/vip_token/t1，
-// 可消除部分网关接口的 20017 类拒绝。方案（MakcRe module/login_token.js 移植）：
-//   p3 = AES(固定 key32/iv16) 加密 {clienttime, token} → HEX
-//   params = AES(md5(randKey)前32位 作 AES-256 key、其后16位作 iv) 加密 {} → HEX
-//   pk = RSA-NO-PADDING(右侧补零到模长) 加密 {clienttime_ms, params 盐}
-//   应答 data.secu_params 用同一派生密钥解出新 token 集合
-// =====================================================================
-
-function kxAes256Hex(jsonObj, keyStr) {
-  const encKey = Buffer.from(keyStr, 'utf8')                       // 32 字符 hex 串按 utf8 → AES-256
-  const encIv = Buffer.from(keyStr.slice(keyStr.length - 16), 'utf8')
-  const cipher = crypto.createCipheriv('aes-256-cbc', encKey, encIv)
-  return Buffer.concat([cipher.update(JSON.stringify(jsonObj), 'utf8'), cipher.final()]).toString('hex')
-}
-
-function kxRandomSeed16() {
-  const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789'
-  let out = ''
-  const bytes = crypto.randomBytes(16)
-  for (let i = 0; i < 16; i++) out += alphabet[bytes[i] % alphabet.length]
-  return out
-}
-
-export async function refreshSession(session = {}) {
-  const s = normSession(session)
-  if (!s.token) throw new Error('未登录，无法刷新登录态')
-  const ms = Date.now()
-  const p3 = kxAes256Hex({ clienttime: Math.floor(ms / 1000), token: s.token }, '90b8382a1bb4ccdcf063102053fd75b8')
-  const paramSeed = kxRandomSeed16()
-  const paramKeyFull = md5Hex(paramSeed)                 // 32 位 → AES-256 密钥（utf8）；末 16 位作 iv
-  const encIv = paramKeyFull.slice(paramKeyFull.length - 16, paramKeyFull.length)
-  const c2 = crypto.createCipheriv('aes-256-cbc', Buffer.from(paramKeyFull, 'utf8'), Buffer.from(encIv, 'utf8'))
-  const paramsHex = Buffer.concat([c2.update('{}', 'utf8'), c2.final()]).toString('hex')
-  // RSA-NO-PADDING：右侧补零到「模长字节数」后直接 modexp（等价参考实现的 manual pad + rawEncrypt）
-  const pub = PLAYLIST_RSA_PUB
-  const json = JSON.stringify({ clienttime_ms: ms, key: paramSeed })
-  const pubKeyObj = crypto.createPublicKey(pub)
-  const modBits = (pubKeyObj.asymmetricKeyDetails && pubKeyObj.asymmetricKeyDetails.modulusLength) || 1024
-  const modLen = Math.ceil(modBits / 8)
-  if (Buffer.byteLength(json, 'utf8') > modLen) throw new Error('登录刷新：pk 载荷超长')
-  const padded = Buffer.alloc(modLen)
-  Buffer.from(json, 'utf8').copy(padded, 0)
-  const pk = crypto.publicEncrypt({ key: pubKeyObj, padding: crypto.constants.RSA_NO_PADDING }, padded).toString('hex')
-
-  const dataMap = {
-    dfid: s.dfid || '-',
-    p3,
-    plat: 1,
-    // 设备型号与客户端构建串：贴近真实 Android 上报形态，供服务端风控辨识
-    //（lx-music-api-server modules/refresh/kg.py 同款字段，gitversion 抄同值；
-    //  UA/t3/need_toneinfo 维持现状即可，两套变体均被服务端接受）。
-    dev: '23127PN0CC',
-    gitversion: 'a23c277',
-    t1: 0,
-    t2: 0,
-    t3: 'MCwwLDAsMCwwLDAsMCwwLDA=',
-    pk,
-    params: paramsHex,
-    userid: String(s.userid || '0'),
-    clienttime_ms: ms,
-  }
-  const bodyText = JSON.stringify(dataMap)
-  const { d } = gatewayDefaults(s)
-  const merged = { ...d, ...dataMap }
-  const q = new URLSearchParams({ ...merged, signature: signAndroid(merged, bodyText) })
-  const res = await fetchWithTimeout(`http://login.user.kugou.com/v5/login_by_token?${q.toString()}`, {
-    method: 'POST',
-    headers: { ...GATEWAY_HEADERS(normSession(s), d.clienttime), 'Content-Type': 'application/json' },
-    body: bodyText,
-  }, 15000)
-  const j = await res.json().catch(() => null)
-  if (!j || Number(j.status) !== 1 || !(j.data && (j.data.secu_params || j.data.token))) {
-    throw new Error('刷新登录态失败：' + explainKgError(j, res.status))
-  }
-  if (!j.data.secu_params) {
-    return { token: String(j.data.token || ''), userid: String(j.data.userid || s.userid), vip_type: '', vip_token: '', t1: '' }
-  }
-  // 解开 secu_params：HEX → AES-256-CBC(同 params 派生密钥)
-  const decKeyFull = md5Hex(paramSeed)
-  const d2 = crypto.createDecipheriv('aes-256-cbc', Buffer.from(decKeyFull, 'utf8'), Buffer.from(decKeyFull.slice(16), 'utf8'))
-  const plain = Buffer.concat([d2.update(Buffer.from(String(j.data.secu_params), 'hex')), d2.final()]).toString('utf8')
-  let obj
-  try { obj = JSON.parse(plain) } catch { obj = { token: plain } }
-  return {
-    token: String(obj.token || ''),
-    userid: String(obj.userid || s.userid),
-    vip_type: String(obj.vip_type != null ? obj.vip_type : ''),
-    vip_token: String(obj.vip_token != null ? obj.vip_token : ''),
-    t1: String(obj.t1 != null ? obj.t1 : ''),
-  }
-}
+// 注：酷狗 token 主动续命（v5/login_by_token 兑换/探活）已于 2026-09-06 停用、2026-09-20 连同
+// 实现（refreshSession / kxAes256Hex / kxRandomSeed16）一起删除——为什么不做续命见 lib/index.js
+// 里 kgWithFreshToken 上方那条决策注释；需要旧实现时从 git 历史找回。
 
 // =====================================================================
 // 个人歌单（cloudlist.service，需登录 token/userid）

package/lib/lyric.js

@@ -15,16 +15,30 @@
 import * as QQ from './qq.js'
 import * as KG from './kugou.js'
 import * as NC from './netease.js'
+import { createLimiter } from './fetch-limit.js'
 
 const LRCLIB_API = 'https://lrclib.net/api'
 const LRCLIB_UA = 'dsh-music-player/1.0 (local lyric fallback; rate-limited+cached)'
 
+// 出网限流（CWE-770）：LRCLIB 兜底是**每次换歌自动触发**、不依赖用户交互的请求，连续切歌时
+// 最容易对第三方接口形成无上限并发。给它一个进程内共享的限流器：并发 2 + 最小启动间隔
+// 250ms + 队列上限 8（超出立即失败，资源有界）。
+// 范围说明：只作用于本模块的 LRCLIB 请求（歌词链最后一跳）。qq/kugou/netease/radio 各自的
+// fetchWithTimeout 走的是**播放关键路径**（点歌/搜索直接调用），在那里加队列会让起播变慢，
+// 故未纳入；若日后要统一限流，直接复用 lib/fetch-limit.js，按模块各建一个实例即可。
+const lrclibLimiter = createLimiter({ maxConcurrent: 2, minGapMs: 250, maxQueue: 8 })
+
 // 出网统一超时（与 qq.js 同构）：Node fetch 默认无超时，端点挂起会让播放流程卡住。
+// 计时器必须在**入队之前**启动：排队等待也吃这份超时预算——排队到点即出队失败、根本不发
+// 上游请求。否则队列一长，超时兜底会被排队拖成 ⌊k/并发⌋×timeout，等于没兜住。
 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 })
+    return await lrclibLimiter.run(
+      () => fetch(url, { ...opts, signal: ctrl.signal }),
+      { signal: ctrl.signal },
+    )
   } finally {
     clearTimeout(timer)
   }
@@ -40,11 +54,12 @@ async function fetchWithTimeout(url, opts = {}, timeoutMs = 10000) {
 // =====================================================================
 
 // 搜索并归一化为候选数组（只保留带同步歌词的非纯音乐候选；纯音乐没有逐字歌词意义）。
-export async function lrclibSearch(keyword) {
+// timeoutMs 覆盖「排队 + 出网」全过程（默认 10s，与 fetchWithTimeout 一致；测试用它跑小值）。
+export async function lrclibSearch(keyword, { timeoutMs = 10000 } = {}) {
   const p = new URLSearchParams({ q: String(keyword || '') })
   const res = await fetchWithTimeout(`${LRCLIB_API}/search?${p.toString()}`, {
     headers: { Accept: 'application/json', 'User-Agent': LRCLIB_UA },
-  })
+  }, timeoutMs)
   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')

package/lib/news-core.js

@@ -473,8 +473,14 @@ const normShiftScope = (scope) => {
  */
 export function sanitizeSchedulePrefs(input, prev) {
   const base = prev && typeof prev === 'object' ? prev : {}
+  // enabled 的「未提供」判定必须看字段本身，而不是看 input 是不是对象：Host 的 loadNews()
+  // 就是 sanitizeSchedulePrefs({}, 磁盘快照) —— input 恒为 truthy 的空对象，旧写法会一路
+  // 走 `input.enabled !== false` → 恒为 true，把用户存下的 false 悄悄改回 true（面板里表现为
+  // 「取消勾选后再进去又勾上了」，定时器照旧触发）。与 model/shifts 及 sanitizeRssPrefs 同款：
+  // 显式传了才覆盖，没传就保留 prev。
+  const hasEnabled = !!input && typeof input === 'object' && input.enabled !== undefined
   const out = {
-    enabled: input && typeof input === 'object' ? input.enabled !== false : base.enabled !== false,
+    enabled: hasEnabled ? input.enabled !== false : base.enabled !== false,
     model: sanitizeModelSelection(input && input.model !== undefined ? input.model : base.model),
     shifts: [],
     prefVersion: Number.isInteger(base.prefVersion) ? base.prefVersion : 0,

package/lib/whatsnew.js

@@ -41,6 +41,37 @@ export const WELCOME = {
 // 版本更新条目：新 → 旧。type 仅支持 feature / improve / fix（未知类型按
 // improve 渲染兜底）。date 为该版本发布日期（YYYY-MM-DD）。
 export const WHATS_NEW = [
+  {
+    version: '1.0.3',
+    date: '2026-09-20',
+    title: '播放与播报体验修复一批',
+    sections: [
+      {
+        type: 'feature',
+        items: [
+          '音量条支持鼠标滚轮调速（慢速 1% / 快速 5%）',
+        ],
+      },
+      {
+        type: 'improve',
+        items: [
+          '新闻播报 / AI 讲书的进度条：切到下一条时不再瞬间归零',
+          '正在播的新闻期次：面板 ▶ 不再把整期从头重播（暂停中变为「继续播放」），详情页标出正在播的类别与条目',
+          '网络电台的「加载更多」与在线音乐样式统一，并显示「加载中…」',
+        ],
+      },
+      {
+        type: 'fix',
+        items: [
+          '本地曲目解码或加载失败时自动跳下一首，不再把播放停死',
+          '「启用每日定时」可以真正关闭了（此前关掉后会被自动勾回、到点照旧触发）',
+          '新闻播报换 AI 声音后从当前位置继续；刷新页面后也能恢复播放进度',
+          '悬浮条拖到页面顶部时，音量 / 播放模式 / 章节目录弹窗不再错位',
+          'QQ / 酷狗 / 网易云重新登录或收藏成功后，不再残留「请重新登录」提示',
+        ],
+      },
+    ],
+  },
   {
     version: '1.0.2',
     date: '2026-09-19',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-music-player",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Vibe coding时的好伴侣",
   "type": "module",
   "main": "lib/index.js",