dsh-music-player 0.6.0 → 0.6.1

package/README.md

@@ -85,7 +85,13 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
       name: 'dsh-music-player'
 ```
 
-播放模式与音量保存在浏览器 `localStorage`，当前曲目与进度也会在刷新后恢复（浏览器的自动播放可能被拦截，点一次 ▶ 即可解锁）。
+播放模式与音量等播放偏好都保存在 **Host 端**（见下），刷新后当前曲目与进度也会恢复（浏览器的自动播放可能被拦截，点一次 ▶ 即可解锁）。
+
+> **状态持久化（重要）**：**所有**播放状态都持久化在 Host 端文件 `~/.dsh/music-player-prefs.json`，包括：
+> 音量、播放顺序、AI 讲书声音、播放范围、面板位置、上次播放的曲目/进度、每本小说的进度、QQ 搜索历史、QQ 面板所在层、QQ「我喜欢」收藏兜底。
+> 因此即使在 **dsh-desktop 桌面版**（每次启动随机端口、浏览器存储按源隔离）下，重启后这些状态照样能找回。
+> **升级兼容**：旧版本（<0.7）把同样的键存在浏览器 `localStorage` 里。升级后客户端**优先读 Host**，Host 没有的记录会**自动回退读取旧 `localStorage` 副本并迁移进 Host**，升级不丢用户数据。
+> 音乐/小说目录、自建歌单、QQ 登录态也持久化在 Host 端（见下文），同样不受影响。
 
 ## 自建歌单（收藏）
 
@@ -119,7 +125,7 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
   - 分类歌单：60+ 分类（默认折叠显示 8 个，可展开），每个分类的歌单支持「加载更多」。
   - 排行榜：巅峰榜/地区榜/特色榜等分组，点榜单看歌曲（带榜单封面卡片），榜单详情底部「加载更多」可分页续载全部歌曲。
   - 新歌：新歌速递（最新/内地/港台/欧美/韩国等）。
-  - 搜索：搜歌曲与歌单，带搜索历史（localStorage，最近 10 条）。
+  - 搜索：搜歌曲与歌单，带搜索历史（Host 持久化，最近 10 条）。
 - **播放**：点击任意歌曲即可播放（同一播放条 + 频谱）；VIP 标识显示在歌名后，行尾显示歌手名。进入歌单/播放列表时自动定位到正在播放的那一首，且正在播放的条目以高亮选中态显示。
 - **收藏**：播放条爱心按钮把当前在线曲目收藏到 QQ 音乐「我喜欢」，已收藏歌曲爱心实时点亮。
 - **续播**：在线播放进度（当前曲目 + 队列）刷新后自动恢复，点 ▶ 续播。

package/lib/client.js

@@ -7,8 +7,9 @@
  * Audio is a native <audio> element. A real FFT spectrum (8 log-spaced bands)
  * is computed offline from the decoded track (per 50ms window) and drawn on a
  * canvas rAF loop as a smooth equalizer that follows the current playback
- * position. Play mode and volume persist across reloads via localStorage; the
- * current track + position are restored without autoplay (a tap on ▶ resumes).
+ * position. Play mode and volume persist across reloads via the Host's prefs
+ * endpoint (/dsh-music/prefs — no browser storage); the current track +
+ * position are restored without autoplay (a tap on ▶ resumes).
  * Host communication is plain HTTP to the /dsh-music/(manifest|intent|set-root|id)
  * routes.
  */
@@ -80,6 +81,21 @@ window.__ModuleLoader__.load({
         maxHeight: Math.round(Math.min(60 * vh / 100, 480, avail)),
       };
     };
+    // 搜索历史下拉专用：锚定在搜索框正下方（fixed，左边缘与搜索框对齐、宽度一致），
+    // portal 到 body 以避开 .dsh-music-panel(overflow:hidden) / .dsh-music-qq-body
+    // (overflow-y:auto) 的裁剪（否则下拉在真实浏览器里不可见）。无锚点时回退到
+    // 视口顶部中央。
+    const anchorBelow = (el, maxW = 420) => {
+      const vw = window.innerWidth;
+      const r = (el && typeof el.getBoundingClientRect === 'function') ? el.getBoundingClientRect() : null;
+      const margin = 8;
+      const width = Math.min((r && r.width > 0) ? r.width : 380, maxW, vw - margin * 2);
+      const left = (r && r.width > 0)
+        ? Math.max(margin, Math.min(vw - margin - width, r.left))
+        : Math.max(margin, Math.round((vw - width) / 2));
+      const top = (r && r.height > 0) ? Math.round(r.bottom + 4) : margin;
+      return { position: 'fixed', left: Math.round(left), top, width: Math.round(width), maxHeight: 240 };
+    };
 
     // 以播放面板中心为基准的固定定位样式（面板可拖拽，弹窗随其居中）。
     // halfW 为目标弹窗的近似半宽；maxH 为弹窗最大高度（px）：垂直 clamp 用
@@ -130,24 +146,196 @@ window.__ModuleLoader__.load({
       }
     })();
 
-    // ---- persisted prefs / playback ----
+    // ---- persisted prefs (Host-backed, with legacy browser-storage fallback) ----
+    // Every pref lives in the Host's music-player-prefs.json, served via
+    // GET/POST /dsh-music/prefs and held in the in-memory `serverPrefs`
+    // snapshot here. dsh-desktop starts the Harness web server on a RANDOM port
+    // each launch, so the page origin changes every time — browser localStorage
+    // (keyed by origin) is therefore NOT authoritative and is never written.
+    // localStorage is kept only as a READ-ONLY upgrade source: old builds (<0.7)
+    // persisted these same key names there, so on upgrade we read Host first and
+    // fall back to the old browser copy, migrate it into the Host, then delete
+    // the browser copy. No user data is lost and no new data touches the browser.
     const PREF_MODE = 'dsh-music-mode';
     const PREF_VOL = 'dsh-music-volume';
     const PREF_PLAYBACK = 'dsh-music-playback';
     const PREF_BOOKS_PLAYBACK = 'dsh-music-books-playback';
-    const PREF_ROOT = 'dsh-music-root';
     const PREF_PANEL_POS = 'dsh-music-panel-pos';
     const PREF_VOICE = 'dsh-music-voice';
     const PREF_SCOPE = 'dsh-music-scope';
-    const PREF_QQ_FAV = 'dsh-music-qq-fav'; // 「我喜欢」收藏 songid/songmid（本地兜底，服务器读失败也可用）
-    const loadPref = (k) => { try { return localStorage.getItem(k); } catch (e) { return null; } };
-    const savePref = (k, v) => { try { localStorage.setItem(k, v); } catch (e) {} };
-    const clearPref = (k) => { try { localStorage.removeItem(k); } catch (e) {} };
+    const PREF_QQ_FAV = 'dsh-music-qq-fav'; // QQ「我喜欢」收藏 songid/songmid（Host 兜底）
+    const PREF_QQ_HISTORY = 'dsh-music-qq-history'; // QQ 搜索历史（最近在前，最多 10 条）
+    const PREF_QQ_UI = 'dsh-music-qq-ui';           // QQ 面板所在层/歌单 UI 状态
+    // Legacy single-book progress key (pre-0.2.1); migrated into the per-book
+    // map on upgrade so very old browser copies are not silently dropped.
+    const PREF_LEGACY_BOOK = 'dsh-music-book-playback';
+    // Every persisted key: written via savePref, read via loadPref, mirrored to
+    // the Host on a debounced flush.
+    const PREF_KEYS = new Set([
+      PREF_MODE, PREF_VOL, PREF_VOICE, PREF_SCOPE, PREF_PANEL_POS,
+      PREF_PLAYBACK, PREF_BOOKS_PLAYBACK, PREF_QQ_FAV, PREF_QQ_HISTORY, PREF_QQ_UI,
+    ]);
+    let serverPrefs = null;          // null = Host snapshot not fetched yet
+    let serverPrefsFetched = false;  // distinguishes "not fetched" from an early savePref
+    const serverDirtyKeys = new Set(); // keys changed since the last flush
+    const serverRemoveKeys = new Set(); // keys cleared since the last flush
+    let serverFlushTimer = null;
+    let serverFlushSeq = 0;
+    // Legacy browser-storage accessors (safe; quota/security errors are ignored).
+    // localStorage is READ-ONLY here: it is only a source for upgrading old
+    // (<0.7) records into the Host. The client never writes new data to it.
+    const legacyGet = (k) => { try { return localStorage.getItem(k); } catch (e) { return null; } };
+    const legacyRemove = (k) => { try { localStorage.removeItem(k); } catch (e) {} };
+    function loadPref(k) {
+      if (!PREF_KEYS.has(k)) return null;
+      // Host is authoritative — it survives origin changes (random port).
+      if (serverPrefs !== null && Object.prototype.hasOwnProperty.call(serverPrefs, k)) {
+        return serverPrefs[k];
+      }
+      // Upgrade compatibility: if the Host has no record yet, fall back to the
+      // old browser localStorage copy (same key names). loadServerPrefs migrates
+      // it into the Host after the snapshot is fetched.
+      return legacyGet(k);
+    }
+    function savePref(k, v) {
+      if (!PREF_KEYS.has(k)) return;
+      serverPrefs = serverPrefs || {};
+      serverPrefs[k] = v;
+      serverRemoveKeys.delete(k);
+      serverDirtyKeys.add(k);
+      // Host-only: no mirror write to localStorage. All data lives in the Host.
+      scheduleServerPrefsFlush();
+    }
+    function clearPref(k) {
+      if (!PREF_KEYS.has(k)) return;
+      serverPrefs = serverPrefs || {};
+      delete serverPrefs[k];
+      serverDirtyKeys.delete(k);
+      serverRemoveKeys.add(k);
+      // Also drop the legacy browser copy — otherwise loadPref would resurrect
+      // a cleared value from localStorage on the next read.
+      legacyRemove(k);
+      scheduleServerPrefsFlush();
+    }
+    function scheduleServerPrefsFlush() {
+      if (serverFlushTimer !== null) return;
+      serverFlushTimer = setTimeout(() => { serverFlushTimer = null; void flushServerPrefs(); }, 800);
+    }
+    async function flushServerPrefs() {
+      const seq = ++serverFlushSeq;
+      const patch = {};
+      for (const k of serverDirtyKeys) {
+        if (serverRemoveKeys.has(k)) continue;
+        if (serverPrefs && Object.prototype.hasOwnProperty.call(serverPrefs, k)) patch[k] = serverPrefs[k];
+      }
+      const remove = [...serverRemoveKeys];
+      serverDirtyKeys.clear();
+      serverRemoveKeys.clear();
+      if (Object.keys(patch).length === 0 && remove.length === 0) return;
+      const payload = JSON.stringify({ prefs: patch, remove });
+      // keepalive survives page teardown (pagehide flush), but browsers cap a
+      // keepalive body at 64KiB and THROW on anything larger — a long QQ queue
+      // (the playback save embeds the whole queue) easily exceeds that, which
+      // silently dropped playback POSTs. Use keepalive only for small payloads;
+      // larger ones go out as a plain fetch (the periodic ~5s saves keep the
+      // state current, so a pagehide cutoff is not a real loss).
+      const useKeepalive = payload.length <= 60 * 1024;
+      try {
+        const r = await fetch('/dsh-music/prefs', {
+          method: 'POST', cache: 'no-store', keepalive: useKeepalive,
+          headers: { 'content-type': 'application/json' },
+          body: payload,
+        });
+        if (r.ok && seq === serverFlushSeq) {
+          const d = await r.json();
+          if (d && d.prefs && typeof d.prefs === 'object') {
+            // The server confirms our merge. Keep any value that changed locally
+            // while this request was in flight (dirty keys / pending removals win
+            // over the response), so a concurrent save is never overwritten.
+            serverPrefs = { ...d.prefs, ...serverPrefs };
+            for (const k of serverRemoveKeys) delete serverPrefs[k];
+          }
+        }
+      } catch { /* best-effort: the change stays in the in-memory snapshot */ }
+    }
+    // Fetch the Host snapshot once; merge any pre-fetch local writes on top so
+    // an early savePref (before the fetch resolves) is never lost. On a cold
+    // start the page can load before the plugin's routes are registered, so a
+    // failed/empty first read is retried briefly instead of silently skipping
+    // the whole restore (that was why "restart shows nothing" could happen).
+    async function loadServerPrefs() {
+      if (serverPrefsFetched) return serverPrefs;
+      const local = serverPrefs; // possibly written by an early savePref
+      let got = false; // route responded with a valid prefs shape
+      for (let attempt = 0; attempt < 4 && !got; attempt++) {
+        let fetched = {};
+        try {
+          const d = await jsonGet('/dsh-music/prefs');
+          if (d && d.prefs && typeof d.prefs === 'object') { fetched = d.prefs; got = true; }
+        } catch { /* transient: route not ready yet */ }
+        serverPrefs = { ...fetched, ...(local || {}) };
+        if (!got && attempt < 3) await new Promise((r) => setTimeout(r, 250));
+      }
+      serverPrefsFetched = true;
+      migrateLegacyBrowserPrefs();
+      return serverPrefs;
+    }
+    // Upgrade path: adopt any old localStorage record the Host does not yet have
+    // (so a <0.7 browser copy survives the move to Host storage), and fold the
+    // legacy single-book key into the per-book map. Runs once, after the Host
+    // snapshot is fetched, so Host values always win. Once a record is adopted
+    // its browser copy is removed — localStorage is a read-only migration source
+    // and never holds data after it has been claimed by the Host.
+    function migrateLegacyBrowserPrefs() {
+      // Legacy single-book progress (pre-0.2.1) → per-book map.
+      try {
+        const legacyRaw = legacyGet(PREF_LEGACY_BOOK);
+        if (legacyRaw) {
+          const p = JSON.parse(legacyRaw);
+          if (p && typeof p.id === 'string' && typeof p.name === 'string' && p.name !== '') {
+            const map = readBooksPlayback();
+            if (!Object.prototype.hasOwnProperty.call(map, p.name)) {
+              map[p.name] = { from: p.from, base: p.base, pos: p.pos, total: p.total, ts: p.ts || Date.now() };
+              writeBooksPlayback(map);
+            }
+          }
+          legacyRemove(PREF_LEGACY_BOOK);
+        }
+      } catch (e) { /* malformed legacy copy: ignore */ }
+      // Any other legacy key: if the Host lacks it, adopt the browser copy (Host
+      // becomes authoritative) and remove the browser copy; if the Host already
+      // has it, just drop the stale browser duplicate. Either way localStorage
+      // ends up holding none of the managed prefs — it is only a one-way upgrade
+      // source and never keeps data once the Host snapshot has claimed it.
+      for (const k of PREF_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(serverPrefs, k)) {
+          legacyRemove(k);
+          continue;
+        }
+        const v = legacyGet(k);
+        if (v !== null) {
+          savePref(k, v);
+          legacyRemove(k);
+        }
+      }
+    }
+    // Apply persisted mode / volume / voice to the store + audio element.
+    // Mutates directly (no set()) so a pre-startup call does not re-trigger
+    // savePref; a later set() from loadTracks re-renders the UI.
+    function applyStoredPrefs() {
+      try {
+        const m = loadPref(PREF_MODE);
+        if (m === 'single' || m === 'order' || m === 'shuffle') store.mode = m;
+        const v = parseFloat(loadPref(PREF_VOL));
+        if (Number.isFinite(v)) { store.volume = Math.min(1, Math.max(0, v)); audio.volume = store.volume; }
+        const voice = loadPref(PREF_VOICE);
+        if (typeof voice === 'string' && voice !== '') store.voice = voice;
+      } catch (e) {}
+    }
     // ---- per-book novel progress (independent from music) ----
     // Every novel remembers its own position, keyed by its filename, so switching
     // between books — or to music — never loses another book's place. Music
     // progress lives in PREF_PLAYBACK and this subsystem never touches it.
-    const PREF_BOOK_PLAYBACK = 'dsh-music-book-playback'; // legacy single-book key
     function readBooksPlayback() {
       try {
         const raw = loadPref(PREF_BOOKS_PLAYBACK);
@@ -191,6 +379,12 @@ window.__ModuleLoader__.load({
     const PANEL_MAX_W = 720;
     const PANEL_MIN_H = 200;
     const PANEL_MAX_H_VH = 0.8;
+    // Auto-size (never-dragged) default height. The panel's height is content-
+    // driven (CSS max-height:72vh), but a fresh install has an empty track list
+    // whose min-height is only ~60px, so the panel would open absurdly short.
+    // Give the auto-size panel a comfortable default minimum so first-use looks
+    // right; this only applies while pos === null (never dragged/resized).
+    const PANEL_AUTO_MIN_H = '45vh';
     // Restore the playback-panel position ({x,y,w,h}) previously saved by
     // dragging/resizing, if any. Old saves ({x,y,h}) migrate with a default width.
     function loadPanelPos() {
@@ -261,6 +455,9 @@ window.__ModuleLoader__.load({
       playing: false, position: 0, duration: 0, volume: 0.8,
       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
+      // /dsh-music/prefs are authoritative); panel position re-applies on it.
+      prefsReady: false,
       bookBuffering: false, bookError: '', bookBufferingSince: 0, bookBufferingSilent: false,
       // chapter table of contents (book reader): section list of the current book,
       // whether the toc popup is open, and the heading of the section now playing.
@@ -271,8 +468,8 @@ window.__ModuleLoader__.load({
       // 播放模式弹层是否打开（portal 到 body 时让播放条按钮保持展开、不因移出而收起）。
       modeMenuOpen: false,
       // AI 讲书 TTS voice: available voices come from /manifest, the selection
-      // persists in localStorage and rides the chunk URL so the host re-synthesizes.
-      // voiceSwitching = a new voice is being synthesized in the background.
+      // persists in the Host prefs and rides the chunk URL so the host
+      // re-synthesizes. voiceSwitching = a new voice is being synthesized.
       voices: [], voice: '白桦', voiceSwitching: false,
       // 自建歌单：manifest.playlists 即数据源；scope 为当前播放范围（曲库/歌单），
       // subTab 为音乐页内的子标签（'library' 或歌单 id）。
@@ -579,31 +776,9 @@ window.__ModuleLoader__.load({
       apiPlaylistReorder(pl.id, next);
     }
 
-    // restore persisted prefs
-    try {
-      const m = loadPref(PREF_MODE);
-      if (m === 'single' || m === 'order' || m === 'shuffle') store.mode = m;
-      const v = parseFloat(loadPref(PREF_VOL));
-      if (Number.isFinite(v)) { store.volume = Math.min(1, Math.max(0, v)); audio.volume = store.volume; }
-      const voice = loadPref(PREF_VOICE);
-      if (typeof voice === 'string' && voice !== '') store.voice = voice;
-    } catch (e) {}
-
-    // Migrate legacy single-book progress (pre-0.2.1) into the per-book map once.
-    try {
-      const legacy = loadPref(PREF_BOOK_PLAYBACK);
-      if (legacy) {
-        const p = JSON.parse(legacy);
-        if (p && typeof p.id === 'string' && typeof p.name === 'string' && p.name !== '') {
-          const map = readBooksPlayback();
-          if (!Object.prototype.hasOwnProperty.call(map, p.name)) {
-            map[p.name] = { from: p.from, base: p.base, pos: p.pos, total: p.total, ts: p.ts || Date.now() };
-            writeBooksPlayback(map);
-          }
-        }
-        clearPref(PREF_BOOK_PLAYBACK);
-      }
-    } catch (e) {}
+    // restore persisted prefs (mode/volume/voice). Runs again after the Host
+    // snapshot is fetched (loadTracks), where the Host value is authoritative.
+    applyStoredPrefs();
 
     // Persist the current playback position. Music and novels are fully separate:
     // music writes PREF_PLAYBACK, novels write into the per-book map — neither
@@ -1254,8 +1429,8 @@ window.__ModuleLoader__.load({
       const b = bookById(id);
       if (b === null) return null;
       // The chosen TTS voice rides the URL so the host re-synthesizes with it.
-      // Only send voices we know (stale localStorage values are dropped; the host
-      // then falls back to its default 白桦).
+      // Only send voices we know (stale persisted voice selections are dropped;
+      // the host then falls back to its default 白桦).
       const known = (store.voices && store.voices.length > 0) ? store.voices : FALLBACK_VOICES;
       const v = store.voice && known.some((x) => x.id === store.voice) ? '&voice=' + encodeURIComponent(store.voice) : '';
       return b.url + '?from=' + from + v;
@@ -1959,15 +2134,14 @@ window.__ModuleLoader__.load({
     async function loadTracks() {
       set({ loading: true });
       try {
+        // Load the Host prefs snapshot first so every restore below reads the
+        // authoritative values (they survive dsh-desktop's random-port origin
+        // changes). Re-apply mode/volume/voice on top of whatever the
+        // synchronous startup restore already applied.
+        await loadServerPrefs();
+        applyStoredPrefs();
+        set({ prefsReady: true });
         const result = await jsonGet('/dsh-music/manifest');
-        const rememberedRoot = loadPref(PREF_ROOT);
-        // If the host came up with the default root but this browser remembers
-        // a different one (e.g. the host state file was not yet written on an
-        // older restart), re-apply it so the chosen directory is restored.
-        if (rememberedRoot !== null && rememberedRoot !== '' && result.root !== rememberedRoot) {
-          saveRoot(rememberedRoot);
-          return;
-        }
         set({
           root: result.root || null, bookRoot: result.bookRoot || null,
           tracks: result.tracks || [], books: result.books || [],
@@ -1994,7 +2168,6 @@ window.__ModuleLoader__.load({
         body: JSON.stringify({ path }),
       }).then((r) => r.json()).then((result) => {
         if (result && result.ok) {
-          if (result.root) savePref(PREF_ROOT, result.root);
           set({
             root: result.root || null, bookRoot: result.bookRoot || null,
             tracks: result.tracks || [], books: result.books || [],
@@ -2531,8 +2704,8 @@ window.__ModuleLoader__.load({
       }
     }
 
-    // 在线 QQ 面板的「上次所在层」只在本次会话首次挂载时恢复一次，避免切 tab
-    // （QQ 音乐 ↔ 本地音乐/AI讲书）重新挂载时又被 localStorage 里的旧层拉回播放列表页。
+    // 在线 QQ 面板的「上次所在层」只在本次会话首次恢复一次，避免切 tab
+    // （QQ 音乐 ↔ 本地音乐/AI讲书）重新挂载时又被持久化的旧层拉回播放列表页。
     let qqUiRestored = false;
     function QQOnlinePanel({ panelRef }) {
       const s = useStore();
@@ -2561,10 +2734,11 @@ window.__ModuleLoader__.load({
       const [plSearchPage, setPlSearchPage] = useState(1);
       const [plSearchLastLen, setPlSearchLastLen] = useState(0);
       const [plSearchingMore, setPlSearchingMore] = useState(false);
-      // 搜索历史（localStorage 持久化，最近在前）。
+      // 搜索历史（Host 持久化，最近在前）。
       const [hist, setHist] = useState([]);
       const [histOpen, setHistOpen] = useState(false);
       const histRef = useRef(null);
+      const histPopRef = useRef(null); // portal 到 body 的历史下拉（点击内部不关闭）
       // 浏览。
       const [minePlays, setMinePlays] = useState([]);
       const [mineLoaded, setMineLoaded] = useState(false);
@@ -2629,22 +2803,20 @@ window.__ModuleLoader__.load({
       const qqPlRef = useRef(null);
 
       const json = (url) => jsonGet(url).catch(() => ({ ok: false, error: '网络错误' }));
-      // 搜索历史（localStorage 持久化，最近在前，最多 10 条）。
-      const HIST_KEY = 'dsh-music-qq-history';
-      const loadHist = () => { try { const a = JSON.parse(localStorage.getItem(HIST_KEY)); return Array.isArray(a) ? a.filter((x) => typeof x === 'string' && x.trim()) : []; } catch { return []; } };
+      // 搜索历史（Host 持久化，最近在前，最多 10 条）。
+      const loadHist = () => { try { const a = JSON.parse(loadPref(PREF_QQ_HISTORY)); return Array.isArray(a) ? a.filter((x) => typeof x === 'string' && x.trim()) : []; } catch { return []; } };
       const saveHist = (kw) => {
         kw = (kw || '').trim();
         if (!kw) return;
         const next = [kw, ...loadHist().filter((x) => x !== kw)].slice(0, 10);
-        try { localStorage.setItem(HIST_KEY, JSON.stringify(next)); } catch {}
+        savePref(PREF_QQ_HISTORY, JSON.stringify(next));
         setHist(next);
       };
-      const clearHist = () => { try { localStorage.removeItem(HIST_KEY); } catch {} setHist([]); };
+      const clearHist = () => { clearPref(PREF_QQ_HISTORY); setHist([]); };
       const clearPoll = () => { if (pollRef.current !== null) { try { clearInterval(pollRef.current); } catch {} try { clearTimeout(pollRef.current); } catch {} pollRef.current = null; } };
       // 记住当前操作所在层（主UI / 播放列表UI），下次弹窗恢复。
-      const UI_KEY = 'dsh-music-qq-ui';
-      const saveUi = (layer2, plId, plName) => { try { localStorage.setItem(UI_KEY, JSON.stringify({ layer: layer2, plId: plId || '', plName: plName || '' })); } catch {} };
-      const loadUi = () => { try { return JSON.parse(localStorage.getItem(UI_KEY)); } catch { return null } };
+      const saveUi = (layer2, plId, plName) => { savePref(PREF_QQ_UI, JSON.stringify({ layer: layer2, plId: plId || '', plName: plName || '' })); };
+      const loadUi = () => { try { return JSON.parse(loadPref(PREF_QQ_UI)); } catch { return null } };
       const restoreUi = (ui) => {
         if (!ui || ui.layer !== 'playlist') return;
         setLayer('playlist');
@@ -2654,18 +2826,30 @@ window.__ModuleLoader__.load({
           setActivePl({ name: s.qqSource || '在线播放列表', songs: s.qqQueue || [], source: s.qqSource || '在线' });
         }
       };
-      // ① 挂载时只做本地初始化：读搜索历史（localStorage）+ 查登录态（status 由
+      // ① 挂载时只做本地初始化：读搜索历史（Host 持久化）+ 查登录态（status 由
       // host 读本地 cookie 文件，不发任何外部网络请求）。外部数据（分类/推荐/我的
       // 歌单）一律延后到登录后（见下方 [loggedIn] effect），未登录零外部请求——
       // 本插件 QQ 在线功能以「登录」为门槛。
       useEffect(() => {
         setHist(loadHist());
         jsonGet('/dsh-music/qq/status').then((d) => { if (d) { setLoggedIn(!!d.loggedIn); setUin(d.uin || ''); setNickname(d.nickname || ''); } }).catch(() => {});
-        // 点击搜索框外时关闭历史下拉。
-        const onDocClick = (e) => { if (histRef.current !== null && !histRef.current.contains(e.target)) setHistOpen(false); };
+        // 点击搜索框外时关闭历史下拉（含 portal 到 body 的下拉本身）。
+        const onDocClick = (e) => {
+          if (histRef.current !== null && histRef.current.contains(e.target)) return;
+          if (histPopRef.current !== null && histPopRef.current.contains(e.target)) return;
+          setHistOpen(false);
+        };
         document.addEventListener('mousedown', onDocClick);
         return () => { clearPoll(); document.removeEventListener('mousedown', onDocClick); };
       }, []);
+      // Host 预置快照异步到达：一旦就绪，重读搜索历史并恢复上次所在层（面板可能
+      // 先于 Host 快照挂载，挂载时读到的历史/层可能还是空的）。
+      useEffect(() => {
+        if (!s.prefsReady) return;
+        setHist(loadHist());
+        if (!qqUiRestored && loggedIn) { qqUiRestored = true; restoreUi(loadUi()); }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [s.prefsReady, loggedIn]);
       // ② 登录态变化时才加载在线数据：未登录（loggedIn=false）一个外部请求都不发；
       // 登录成功（setLoggedIn(true)）或已登录刷新页面（status 返回 true）时自动加载
       // 分类 / 我的歌单 / 推荐，并恢复上次所在层。登出后不再加载。
@@ -2675,8 +2859,10 @@ window.__ModuleLoader__.load({
         // 默认落在「我的歌单」tab：登录态下加载我的歌单；未登录时主 UI 不显示。
         loadMine();
         loadRecommended();
-        // 仅本次会话首次登录时恢复上次所在层；之后切 tab 重挂不再拉回旧层。
-        if (!qqUiRestored) { qqUiRestored = true; restoreUi(loadUi()); }
+        // 仅当 Host 预置就绪且本会话尚未恢复时，恢复上次所在层；之后切 tab 重挂
+        // 不再拉回旧层。若此刻预置还没到（面板先挂载），留给上方 [prefsReady]
+        // effect 在快照到达后恢复。
+        if (!qqUiRestored && s.prefsReady) { qqUiRestored = true; restoreUi(loadUi()); }
       }, [loggedIn]);
       // ③ 收藏/取消收藏「我喜欢」后刷新「我的歌单」，让「我喜欢」歌单数目随之更新。
       useEffect(() => {
@@ -3083,17 +3269,20 @@ window.__ModuleLoader__.load({
           onKeyDown: (e) => { if (e.key === 'Enter') doSearch(); },
           onFocus: () => { if (hist.length > 0) setHistOpen(true); },
         }),
-        React.createElement('button', { className: 'dsh-music-settings-btn', onClick: () => doSearch() }, searching ? '搜索中…' : '搜索'),
-        histOpen && hist.length > 0
-          ? React.createElement('div', { className: 'dsh-music-qq-hist' },
-            React.createElement('div', { className: 'dsh-music-qq-hist-head' },
-              React.createElement('span', { className: 'dsh-music-hint' }, '搜索历史'),
-              React.createElement('button', { className: 'dsh-music-qq-hist-clear', title: '清空历史', onClick: clearHist }, '清空')),
-            hist.map((kw, idx) => React.createElement('button', {
-              key: idx, className: 'dsh-music-qq-hist-item',
-              onClick: () => { setQ(kw); doSearch(kw); },
-            }, kw)))
-          : null);
+        React.createElement('button', { className: 'dsh-music-settings-btn', onClick: () => doSearch() }, searching ? '搜索中…' : '搜索'));
+      // 历史下拉 portal 到 body：搜索框在 .dsh-music-panel(overflow:hidden)/.dsh-music-qq-body
+      // (overflow-y:auto) 内，绝对定位子元素会被裁剪不可见；portaled + fixed 锚定
+      // 在搜索框正下方（与音量/模式/章节目录弹层同款逃逸方案）。
+      const histPop = (histOpen && hist.length > 0)
+        ? portalToBody(React.createElement('div', { className: 'dsh-music-qq-hist', style: anchorBelow(histRef.current, 420), ref: histPopRef },
+          React.createElement('div', { className: 'dsh-music-qq-hist-head' },
+            React.createElement('span', { className: 'dsh-music-hint' }, '搜索历史'),
+            React.createElement('button', { className: 'dsh-music-qq-hist-clear', title: '清空历史', onClick: clearHist }, '清空')),
+          hist.map((kw, idx) => React.createElement('button', {
+            key: idx, className: 'dsh-music-qq-hist-item',
+            onClick: () => { setQ(kw); doSearch(kw); },
+          }, kw))))
+        : null;
 
       // 扫码框以面板中心为基准居中（面板可拖拽），贴边时 clamp 不被裁掉。
       const qqLoginStyle = panelCenterStyle(panelRef, loginMode !== null, 170, 460);
@@ -3192,7 +3381,7 @@ window.__ModuleLoader__.load({
         } else {
           resultContent = React.createElement('div', null, plResults.map((p) => playRow(p)), plMoreBtn);
         }
-        body = React.createElement('div', null, searchBox,
+        body = React.createElement('div', null, searchBox, histPop,
           searched ? React.createElement('div', null, resultContent) : null);
       } else {
         let content;
@@ -3330,6 +3519,15 @@ window.__ModuleLoader__.load({
       // Draggable panel position + size ({x, y, w, h} left/top/width/height once
       // dragged or resized; null = CSS default: centered, 380px, auto height).
       const [pos, setPos] = useState(loadPanelPos);
+      // The Host prefs snapshot arrives async (loadTracks -> loadServerPrefs).
+      // Once it is ready, re-apply the persisted panel geometry — all prefs are
+      // Host-backed now, so the mount-time value above comes from the snapshot.
+      useEffect(() => {
+        if (!s.prefsReady) return;
+        const next = loadPanelPos();
+        if (next !== null) setPos(next);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [s.prefsReady]);
       const dragRef = useRef(null);   // head-drag state
       const resizeRef = useRef(null); // corner-resize state
       // 曲库每行「＋」打开的「加入歌单」菜单：{track, x, y}（锚点=按钮右上角视口坐标）。
@@ -3348,7 +3546,7 @@ window.__ModuleLoader__.load({
       // 面板常驻不卸载：关闭时仅用 display:none 隐藏（子树、QQ 面板状态全保留），
       // 重新打开时按播放类别重设 tab（见 togglePanel）并恢复显示。因此组件不会
       // 在关闭时 unmount，切 tab / 关面板重开都不会丢内部 useState 状态。
-      const rootStyle = { ...(pos === null ? null : { left: pos.x, top: pos.y, width: pos.w, height: pos.h, maxHeight: 'none', transform: 'none' }), display: s.panelOpen ? '' : 'none' };
+      const rootStyle = { ...(pos === null ? { minHeight: PANEL_AUTO_MIN_H } : { left: pos.x, top: pos.y, width: pos.w, height: pos.h, maxHeight: 'none', transform: 'none' }), display: s.panelOpen ? '' : 'none' };
 
       const onHeadDown = (e) => {
         if (e.button !== undefined && e.button !== 0) return;
@@ -3434,13 +3632,22 @@ window.__ModuleLoader__.load({
         if (!s.panelOpen) return;
         // Close the playlist panel when the user clicks outside it
         // (mousedown precedes the toggle's click, so both stay consistent).
-        // The directory/file pickers are portaled to <body>, so a click inside
-        // them is technically outside the panel's DOM — treat those as "inside"
-        // so interacting with the picker never closes the panel underneath.
-        // The「加入歌单」弹窗（含本地+QQ）同样 portal 到 body，点击其内菜单不应关面板。
+        // Several popups are PORTALED to <body> (to escape the panel's
+        // overflow:hidden clipping): directory/file pickers, the「加入歌单」menu,
+        // the QQ search-history dropdown, the chapter TOC, and the bar's
+        // mode/volume popups. A click inside any of them is technically outside
+        // the panel's DOM, but they are part of the panel/bar UI — treat them as
+        // "inside" so interacting never closes the panel underneath.
         const onDown = (e) => {
           if (panelRef.current !== null && !panelRef.current.contains(e.target)
-            && !(e.target.closest && (e.target.closest('.dsh-music-picker-overlay') || e.target.closest('.dsh-music-add-pop')))) {
+            && !(e.target.closest && (
+              e.target.closest('.dsh-music-picker-overlay')
+              || e.target.closest('.dsh-music-add-pop')
+              || e.target.closest('.dsh-music-qq-hist')
+              || e.target.closest('.dsh-music-toc')
+              || e.target.closest('.dsh-music-mode-pop')
+              || e.target.closest('.dsh-music-bar-vol-pop')
+            ))) {
             set({ panelOpen: false });
           }
         };
@@ -3870,6 +4077,10 @@ window.__ModuleLoader__.load({
         const onPageHide = () => {
           try { audio.pause(); } catch (e) {}
           try { preAudio.pause(); } catch (e) {}
+          // Best-effort flush of pending prefs to the Host before teardown
+          // (fetch uses keepalive; if the request is cut off, the periodic and
+          // debounced flushes have normally already persisted the state).
+          void flushServerPrefs();
         };
         document.addEventListener('visibilitychange', onVis);
         window.addEventListener('pagehide', onPageHide);

package/lib/index.js

@@ -1163,6 +1163,69 @@ export function apply(ctx) {
   }
   const findPlaylist = (id) => playlists.find((p) => p.id === id) || null
 
+  // ---- 播放偏好持久化（volume / mode / playback / 小说进度 / QQ UI）----
+  // 这些状态原本存在浏览器 localStorage，而 localStorage 按「源(origin)」隔离。
+  // dsh-desktop 每次启动给 Harness Web 服务分配一个随机端口，导致源每次变化、
+  // localStorage 每次都读不到——重启后音量/播放顺序/上次播放内容全丢。现在
+  // 所有持久化状态统一存 Host 端文件（DSH_HOME 固定不变，DSH 进程重启不丢），
+  // 客户端启动时 GET /prefs 以快照为准恢复，改动经 POST /prefs 合并写回。
+  // 值一律以字符串存储，与客户端 loadPref 对齐。
+  let serverPrefs = {} // { 'dsh-music-volume': '0.8', 'dsh-music-mode': 'order', ... }
+  const PREF_ALLOW = new Set([
+    'dsh-music-mode', 'dsh-music-volume', 'dsh-music-voice', 'dsh-music-scope',
+    'dsh-music-panel-pos', 'dsh-music-playback', 'dsh-music-books-playback',
+    'dsh-music-qq-fav', 'dsh-music-qq-history', 'dsh-music-qq-ui',
+  ])
+  const PREF_VALUE_MAX = 256 * 1024 // 单键上限（books 进度 map / QQ 队列可能较大）
+  const sanitizePrefs = (input) => {
+    const out = {}
+    if (!input || typeof input !== 'object') return out
+    for (const k of Object.keys(input)) {
+      if (!PREF_ALLOW.has(k)) continue
+      const v = input[k]
+      if (typeof v !== 'string' || v === '' || v.length > PREF_VALUE_MAX) continue
+      if (k === 'dsh-music-volume') {
+        const n = Number(v)
+        if (!Number.isFinite(n)) continue
+        out[k] = String(Math.min(1, Math.max(0, n)))
+        continue
+      }
+      if (k === 'dsh-music-mode') {
+        if (v !== 'single' && v !== 'order' && v !== 'shuffle') continue
+        out[k] = v
+        continue
+      }
+      out[k] = v
+    }
+    return out
+  }
+  const prefsFile = async () => {
+    const h = await getHome()
+    const base = (process.env.DSH_HOME) || (h === null ? null : h + '/.dsh')
+    return base === null ? null : base + '/music-player-prefs.json'
+  }
+  const loadPrefs = async () => {
+    const file = await prefsFile()
+    serverPrefs = {}
+    if (file === null) return serverPrefs
+    try {
+      const text = readFileSync(file, 'utf8')
+      const data = JSON.parse(text)
+      if (data && typeof data === 'object' && data.prefs && typeof data.prefs === 'object') {
+        serverPrefs = sanitizePrefs(data.prefs)
+      }
+    } catch { /* 不可读 -> 空 */ }
+    return serverPrefs
+  }
+  const savePrefs = async () => {
+    const file = await prefsFile()
+    if (file === null) return
+    try {
+      mkdirSync(dirname(file), { recursive: true })
+      writeFileSync(file, JSON.stringify({ version: 2, prefs: serverPrefs }, null, 2) + '\n', 'utf8')
+    } catch { /* best-effort */ }
+  }
+
   // ---- 在线 QQ 音乐：cookie 持久化 + 登录会话（扫码登录后取高音质直链） ----
   // cookie 仅存 Host 端（~/.dsh/music-player-qq-cookie.json，0600），不进入浏览器。
   const qq = { cookie: '', isVip: null, nickname: '' }
@@ -1910,6 +1973,27 @@ export function apply(ctx) {
         })
         return
       }
+      // 播放偏好读写（volume/mode/voice/scope/panel-pos/playback/books-playback）。
+      // GET 返回完整快照；POST 为合并语义：{ prefs: {k:v,...} } 写入，
+      // { remove: [k,...] } 删除指定键。见 lib/index.js 的 serverPrefs 说明。
+      if (pathname === '/dsh-music/prefs' && req.method === 'GET') {
+        await loadPrefs()
+        writeJson(res, { ok: true, prefs: serverPrefs })
+        return
+      }
+      if (pathname === '/dsh-music/prefs' && req.method === 'POST') {
+        const body = await readBody(req)
+        await loadPrefs()
+        const patch = sanitizePrefs(body && body.prefs ? body.prefs : body)
+        serverPrefs = { ...serverPrefs, ...patch }
+        const remove = Array.isArray(body && body.remove)
+          ? body.remove.filter((k) => typeof k === 'string' && PREF_ALLOW.has(k))
+          : []
+        for (const k of remove) delete serverPrefs[k]
+        await savePrefs()
+        writeJson(res, { ok: true, prefs: serverPrefs })
+        return
+      }
       if (pathname === '/dsh-music/set-root' && req.method === 'POST') {
         const body = await readBody(req)
         const rawPath = body && typeof body.path === 'string' ? body.path.trim() : ''

package/lib/qq.js

@@ -541,10 +541,6 @@ export async function getMyPlaylists(cookie = '') {
   const j = await postMusicu(body, cookie)
   const res = j.req_0 || j['music.musicasset.PlaylistBaseRead']
   const rawSnippet = (x) => { try { const s = JSON.stringify(x); return s ? s.slice(0, 300) : String(x) } catch { return String(x) } }
-  // 诊断日志：便于排查鉴权 / uin 不符导致的空歌单。
-  if (typeof console !== 'undefined' && typeof console.log === 'function') {
-    try { console.log('[dsh-music] my-playlists uin=' + uin + ' code=' + (res && res.code) + ' msg=' + ((res && (res.message || res.msg)) || '') + ' top=' + j.code + ' count=' + ((res && res.data && res.data.v_playlist || []).length) + ' raw=' + rawSnippet(j)) } catch { /* ignore */ }
-  }
   if (!res) throw new Error('我的歌单接口无响应（顶层 code=' + j.code + '，raw=' + rawSnippet(j) + '）')
   if (Number(res.code) !== 0) throw new Error('获取我的歌单失败：' + ((res.message || res.msg) || ('code ' + res.code)) + '｜raw=' + rawSnippet(res))
   const list = res.data?.v_playlist || []

package/package.json

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