dsh-music-player 0.2.1 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 DeepSeek Harness 本地音乐 + AI 讲书插件（bundle）。
 
-在 Host 进程扫描本地音乐目录（默认 `~/Music`，可在面板里改）并以 HTTP Range 流式给浏览器提供音频；浏览器侧提供**正在播放条**（上一首/播放暂停/下一首/停止、播放模式、音量、实时频谱）与浮动的**播放面板**（曲目列表 / 目录设置）。支持 **AI 讲书**：本地 `.txt` 小说经 MiMo TTS 合成朗读，自动识别书名/前言/章节/尾声，可跳章、可选声音。同时注册 `music_play` 模型工具，让 agent 可按关键词播放音乐或启动讲书。
+在 Host 进程扫描本地音乐目录（默认 `~/Music`，可在面板里改）并以 HTTP Range 流式给浏览器提供音频；浏览器侧提供**正在播放条**（上一首/播放暂停/下一首/停止、播放模式、音量、实时频谱）与浮动的**播放面板**（曲目列表 / 自建歌单 / 目录设置）。支持 **AI 讲书**：本地 `.txt` 小说经 MiMo TTS 合成朗读，自动识别书名/前言/章节/尾声，可跳章、可选声音。同时注册 `music_play` 模型工具，让 agent 可按关键词播放音乐或启动讲书。
 
 ## 特性
 
@@ -16,6 +16,7 @@ DeepSeek Harness 本地音乐 + AI 讲书插件（bundle）。
 - AI 讲书：本地 `.txt` 小说经 MiMo TTS 合成朗读，自动识别**书名/前言/章节/尾声**结构，播放条带**章节目录**跳转、章节切歌，可选 4 种中文 AI 声音（默认白桦）
 - `music_play` 模型工具：agent 可按关键词播放本地音乐，也可按小说名启动 AI 讲书
 - 支持的格式：`mp3 / m4a / m4b / aac / flac / wav / ogg / opus / webm / aiff`（自动递归扫描子目录，上限 500 首）
+- **自建歌单**：可新建多个歌单，从本地文件（支持多选、可跨目录）添加歌曲；播放条爱心按钮一键收藏到默认歌单「我最喜欢」；歌单作为播放来源时，顺序/乱序循环只在该歌单内进行
 
 ## 截图
 
@@ -66,8 +67,8 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
 
 插件为「Host 端 + Web 端」双面结构：
 
-- Host 端（`lib/index.js`）：音乐扫描、HTTP 流式、`music_play` 工具、AI 讲书（小说结构解析 + TTS 合成）
-- Web 端（`lib/client.js`）：浏览器里的播放条 / 播放面板 / 频谱 / 讲书控制
+- Host 端（`lib/index.js`）：音乐扫描、HTTP 流式、歌单 CRUD/持久化、`music_play` 工具、AI 讲书（小说结构解析 + TTS 合成）
+- Web 端（`lib/client.js`）：浏览器里的播放条 / 播放面板 / 频谱 / 歌单（收藏、一键清空）/ 讲书控制
 
 两者由一个 `cordis.patch.yml` 插入 `music-player` 行并自动组对（在 Web 端 `dsh.client` 声明即指回该行名并加载浏览器半体）：
 
@@ -79,6 +80,19 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
 
 播放模式与音量保存在浏览器 `localStorage`，当前曲目与进度也会在刷新后恢复（浏览器的自动播放可能被拦截，点一次 ▶ 即可解锁）。
 
+## 自建歌单（收藏）
+
+播放面板「音乐」页内新增子标签：**曲库 / ♥ 我最喜欢 / ＋**，支持自建歌单并把歌单作为播放来源——此时顺序/乱序循环只在该歌单内进行。
+
+- **新建歌单**：点「＋」输入名称即建（可建多个）。
+- **曲库加入**：在「曲库」列表每首歌行尾有「＋」按钮，点击可把该曲加入任一已有歌单，或直接新建歌单加入。
+- **添加歌曲**：进入某歌单 → 点「添加歌曲」→ 打开本地文件多选框（可多选、可跨目录）加入歌单；歌单内每首歌支持上移/下移排序与移除。
+- **清空歌单**：每个歌单（含「我最喜欢」）详情内都有「清空」按钮，二次确认后一键移除全部歌曲（歌曲文件不会被删除）。
+- **收藏**：播放条上的爱心按钮一键把当前曲加入默认歌单「我最喜欢」，再点取消；「我最喜欢」固定不可删除/重命名。
+- **播放范围**：在歌单里点歌，则顺序/乱序/单曲循环都在该歌单内；在「曲库」点歌则回到全库循环。
+- **命令**：`music_play` 工具新增 `playlist` 参数，可让 agent 直接播放某个歌单（如「播放歌单 我最喜欢」）。
+- 歌单数据保存在 `~/.dsh/music-player-playlists.json`，刷新/重启不丢；歌单可包含曲库目录之外的本地音频文件。
+
 ## AI 讲书
 
 把本地 `.txt` 小说交给 AI 朗读（复用 DSH 已配置的 xiaomi/MiMo TTS）。**AI 语音目前仅支持 xiaomi 提供方（限时免费），请在设置中配置好再使用此功能。**
@@ -101,11 +115,11 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
 
 ## 开发
 
-需要 Node.js ≥ 20（vitest 建议 20.19+）与 npm。开发依赖仅 `vitest`：
+需要 Node.js ≥ 20（vitest 建议 20.19+）与 npm。开发依赖：`vitest` + `react`/`react-dom`/`jsdom`（用于前端渲染冒烟测试）：
 
 ```sh
 npm install
-npm test        # 跑 vitest 测试套件
+npm test        # 跑 vitest 测试套件（Host 单测 + Web 渲染冒烟，共 50+ 用例）
 ```
 
 修改 `lib/` 后，在本机 profile 里用 link 方式本地调试并验证：

package/lib/client.js

@@ -56,6 +56,7 @@ window.__ModuleLoader__.load({
     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 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) {} };
@@ -169,6 +170,9 @@ window.__ModuleLoader__.load({
       // persists in localStorage and rides the chunk URL so the host re-synthesizes.
       // voiceSwitching = a new voice is being synthesized in the background.
       voices: [], voice: '白桦', voiceSwitching: false,
+      // 自建歌单：manifest.playlists 即数据源；scope 为当前播放范围（曲库/歌单），
+      // subTab 为音乐页内的子标签（'library' 或歌单 id）。
+      playlists: [], scope: { kind: 'library' }, subTab: 'library',
     };
     const listeners = new Set();
     function set(patch) {
@@ -176,6 +180,7 @@ window.__ModuleLoader__.load({
       if ('mode' in patch) savePref(PREF_MODE, patch.mode);
       if ('volume' in patch) savePref(PREF_VOL, String(patch.volume));
       if ('voice' in patch) savePref(PREF_VOICE, patch.voice);
+      if ('scope' in patch) savePref(PREF_SCOPE, JSON.stringify(patch.scope));
       for (const fn of [...listeners]) fn();
     }
     function useStore() {
@@ -190,6 +195,154 @@ window.__ModuleLoader__.load({
     }
     const trackById = (id) => (store.tracks || []).find((t) => t.id === id) || null;
 
+    // ---- 自建歌单：范围 / 解析 / 收藏 ----
+    const FAV_PLAYLIST_ID = 'pl-fav';
+    const playlistById = (id) => (store.playlists || []).find((p) => p.id === id) || null;
+    // 解析任意可播放对象：歌单成员 id（'p:'+path）优先，其次曲库曲目。
+    function resolvePlayable(id) {
+      if (id === null || id === undefined) return null;
+      if (String(id).startsWith('p:')) {
+        for (const p of store.playlists || []) {
+          const m = (p.tracks || []).find((t) => t.id === id);
+          if (m) return m;
+        }
+        return null;
+      }
+      return trackById(id);
+    }
+    // 当前范围的有序 id 列表：歌单非空则用歌单，否则回退曲库（空/已删歌单优雅回退）。
+    function activeIds() {
+      const s = store.scope || { kind: 'library' };
+      if (s.kind === 'playlist') {
+        const pl = playlistById(s.id);
+        if (pl && pl.tracks && pl.tracks.length > 0) return pl.tracks.map((t) => t.id);
+        return (store.tracks || []).map((t) => t.id);
+      }
+      return (store.tracks || []).map((t) => t.id);
+    }
+    function scopeKey() {
+      const s = store.scope || { kind: 'library' };
+      return s.kind === 'playlist' ? 'pl:' + s.id : 'lib';
+    }
+    // 当前播放曲目对应的绝对路径（用于收藏判断）。
+    function currentTrackPath() {
+      if (store.currentId === null) return null;
+      if (String(store.currentId).startsWith('p:')) return String(store.currentId).slice(2);
+      const t = trackById(store.currentId);
+      return t && t.path ? t.path : null;
+    }
+    function isCurrentFaved() {
+      const path = currentTrackPath();
+      if (path === null) return false;
+      const fav = playlistById(FAV_PLAYLIST_ID);
+      return fav !== null && (fav.tracks || []).some((m) => m.path === path);
+    }
+    function updatePlaylistInStore(pl) {
+      if (!pl || !pl.id) return;
+      set({ playlists: (store.playlists || []).map((p) => (p.id === pl.id ? pl : p)) });
+    }
+    function apiPlaylistAdd(id, paths, then) {
+      fetch('/dsh-music/playlist/add', {
+        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(() => {});
+    }
+    function apiPlaylistRemove(id, paths, then) {
+      fetch('/dsh-music/playlist/remove', {
+        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(() => {});
+    }
+    function apiPlaylistReorder(id, paths) {
+      fetch('/dsh-music/playlist/reorder', {
+        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); }).catch(() => {});
+    }
+    // 收藏切换：加入/移出「我最喜欢」。
+    function toggleFav() {
+      const path = currentTrackPath();
+      if (path === null) return;
+      const fav = playlistById(FAV_PLAYLIST_ID);
+      if (fav === null) return;
+      if (isCurrentFaved()) apiPlaylistRemove(FAV_PLAYLIST_ID, [path]);
+      else apiPlaylistAdd(FAV_PLAYLIST_ID, [path]);
+    }
+    // 从歌单/曲库点歌：来源即范围。
+    function startPlayFrom(id, kind, plId) {
+      if (kind === 'playlist') set({ scope: { kind: 'playlist', id: plId } });
+      else set({ scope: { kind: 'library' } });
+      startPlay(id);
+    }
+    // 歌单管理：新建 / 重命名 / 删除 / 移动歌曲。
+    function onCreatePlaylist() {
+      const name = window.prompt('新建歌单名称', '');
+      if (name === null) return;
+      const trimmed = name.trim();
+      if (trimmed === '') return;
+      fetch('/dsh-music/playlist', {
+        method: 'POST', cache: 'no-store',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: trimmed }),
+      }).then((r) => r.json()).then((r) => {
+        if (r && r.playlist) {
+          set({ playlists: [...(store.playlists || []), r.playlist], subTab: r.playlist.id });
+        }
+      }).catch(() => {});
+    }
+    function onRenamePlaylist(pl) {
+      const name = window.prompt('重命名歌单「' + pl.name + '」', pl.name);
+      if (name === null) return;
+      const trimmed = name.trim();
+      if (trimmed === '' || trimmed === pl.name) return;
+      fetch('/dsh-music/playlist/rename', {
+        method: 'POST', cache: 'no-store',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id: pl.id, name: trimmed }),
+      }).then((r) => r.json()).then((r) => { if (r && r.playlist) updatePlaylistInStore(r.playlist); }).catch(() => {});
+    }
+    function onDeletePlaylist(pl) {
+      if (!window.confirm('删除歌单「' + pl.name + '」？歌曲文件不会被删除。')) return;
+      fetch('/dsh-music/playlist/delete', {
+        method: 'POST', cache: 'no-store',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id: pl.id }),
+      }).then((r) => r.json()).then((r) => {
+        if (r && r.ok) {
+          const next = (store.playlists || []).filter((p) => p.id !== pl.id);
+          set({ playlists: next, subTab: 'library' });
+          if (store.scope && store.scope.kind === 'playlist' && store.scope.id === pl.id) {
+            set({ scope: { kind: 'library' } });
+          }
+        }
+      }).catch(() => {});
+    }
+    // 一键清空歌单（任何歌单都可用，含系统「我最喜欢」；仅从歌单移除，不删文件）。
+    function onClearPlaylist(pl) {
+      const n = (pl.tracks || []).length;
+      if (n === 0 && !pl.missing) return;
+      if (!window.confirm('清空歌单「' + pl.name + '」？将移除全部 ' + n + ' 首歌曲' + (pl.missing > 0 ? '（另有 ' + pl.missing + ' 首已失效一并清除）' : '') + '，歌曲文件不会被删除。')) return;
+      fetch('/dsh-music/playlist/clear', {
+        method: 'POST', cache: 'no-store',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id: pl.id }),
+      }).then((r) => r.json()).then((r) => {
+        if (r && r.playlist) updatePlaylistInStore(r.playlist);
+      }).catch(() => {});
+    }
+    function movePlaylistTrack(pl, path, dir) {
+      const paths = (pl.tracks || []).map((t) => t.path);
+      const i = paths.indexOf(path);
+      const j = i + dir;
+      if (i < 0 || j < 0 || j >= paths.length) return;
+      const next = paths.slice();
+      const tmp = next[i]; next[i] = next[j]; next[j] = tmp;
+      apiPlaylistReorder(pl.id, next);
+    }
+
     // restore persisted prefs
     try {
       const m = loadPref(PREF_MODE);
@@ -296,21 +449,23 @@ window.__ModuleLoader__.load({
       } catch { if (!isPrefetch && isCurrent()) set({ vizState: 'unavailable' }); }
     }
     function prefetchNext() {
-      if (store.tracks.length === 0 || store.currentId === null) return;
+      const ids = activeIds();
+      if (ids.length === 0 || store.currentId === null) return;
       let nextId = null;
       if (store.mode === 'shuffle') {
         // Prefetch the queued next track so a shuffle "next" starts instantly.
-        if (shuffleQueue.length === store.tracks.length) {
+        ensureShuffleReady();
+        if (shuffleQueue.length === ids.length) {
           const pos = shuffleQueue.indexOf(store.currentId);
           if (pos >= 0 && pos + 1 < shuffleQueue.length) nextId = shuffleQueue[pos + 1];
         }
       } else {
-        const idx = store.tracks.findIndex((t) => t.id === store.currentId);
-        const next = store.tracks[(idx + 1) % store.tracks.length];
-        if (next !== undefined) nextId = next.id;
+        const idx = ids.indexOf(store.currentId);
+        const next = ids[(idx + 1) % ids.length];
+        if (next !== undefined) nextId = next;
       }
       if (nextId !== null) {
-        const next = trackById(nextId);
+        const next = resolvePlayable(nextId);
         if (next !== undefined && !envCache.has(next.id)) loadEnvelope(next.id, next.url, true);
       }
     }
@@ -321,15 +476,30 @@ window.__ModuleLoader__.load({
     const smoothCur = new Float32Array(SMOOTH_BARS);
     const smoothPeak = new Float32Array(SMOOTH_BARS);
     const targetBuf = new Float32Array(SMOOTH_BARS);
-    // Accent color for the spectrum bars, read from the theme-derived
-    // --dsh-music-accent (see PLAYER_CSS), cached once.
+    // Accent color for the spectrum bars. DSH defines its --dsw-alias-* theme
+    // tokens on <body> — never on :root — so --dsh-music-accent must be read
+    // from body (reading documentElement would always return the fallback and
+    // the bars would never follow the theme). The value is cached but the cache
+    // is invalidated whenever the theme changes at runtime: the ThemePresenter
+    // projects tokens + the dark attribute onto body, so a MutationObserver on
+    // body's style/dark-attribute keeps the bars tracking live brand changes.
     let accentColor = null;
+    let accentObserver = null;
+    function readAccent() {
+      const el = document.body || document.documentElement;
+      return getComputedStyle(el).getPropertyValue('--dsh-music-accent').trim() || '#2f9e6e';
+    }
     function currentAccent() {
-      if (accentColor === null) {
-        accentColor = getComputedStyle(document.documentElement).getPropertyValue('--dsh-music-accent').trim() || '#2f9e6e';
-      }
+      if (accentColor === null) accentColor = readAccent();
       return accentColor;
     }
+    function watchAccent() {
+      if (accentObserver !== null) return accentObserver;
+      if (typeof MutationObserver === 'undefined') return null;
+      accentObserver = new MutationObserver(() => { accentColor = readAccent(); });
+      accentObserver.observe(document.body, { attributes: true, attributeFilter: ['style', 'data-ds-dark-theme'] });
+      return accentObserver;
+    }
     function drawBars(canvas, useCaps) {
       const c = canvas.getContext('2d');
       const w = canvas.width; const h = canvas.height;
@@ -394,8 +564,9 @@ window.__ModuleLoader__.load({
     // played one, instead of random-without-repeat or list-order neighbors.
     let shuffleQueue = [];
     let shufflePos = -1;
+    let shuffleScopeKey = null;
     function buildShuffleQueue(anchorId) {
-      const ids = store.tracks.map((t) => t.id);
+      const ids = activeIds();
       // Fisher-Yates
       for (let i = ids.length - 1; i > 0; i--) {
         const j = Math.floor(Math.random() * (i + 1));
@@ -407,19 +578,25 @@ window.__ModuleLoader__.load({
         if (ai !== 0) { ids.splice(ai, 1); ids.unshift(a); }
       }
       shuffleQueue = ids;
+      shuffleScopeKey = scopeKey();
       shufflePos = a !== null && ids[0] === a ? 0 : -1;
     }
-    function syncShufflePos() {
+    // 确保乱序队列与当前范围一致（范围切换后自动重建）。
+    function ensureShuffleReady() {
       if (store.mode !== 'shuffle') return;
-      if (store.currentId === null) return;
-      if (shuffleQueue.length !== store.tracks.length || !shuffleQueue.includes(store.currentId)) {
+      const ids = activeIds();
+      if (shuffleScopeKey !== scopeKey() || shuffleQueue.length !== ids.length
+        || (store.currentId !== null && !shuffleQueue.includes(store.currentId))) {
         buildShuffleQueue(store.currentId);
-        return;
       }
-      shufflePos = shuffleQueue.indexOf(store.currentId);
+      if (store.currentId !== null) shufflePos = shuffleQueue.indexOf(store.currentId);
+    }
+    function syncShufflePos() {
+      if (store.mode !== 'shuffle') return;
+      ensureShuffleReady();
     }
     function startPlay(id) {
-      const track = trackById(id);
+      const track = resolvePlayable(id);
       if (track === null) return;
       restoredMusicPos = null;
       bookRestorePos = -1;
@@ -672,13 +849,13 @@ window.__ModuleLoader__.load({
     }
     function togglePlay() {
       if (store.pendingId !== null && store.currentId === null) { startPlay(store.pendingId); return; }
-      if (store.currentId === null) { if (store.tracks.length > 0) startPlay(store.tracks[0].id); return; }
+      if (store.currentId === null) { const ids = activeIds(); if (ids.length > 0) startPlay(ids[0]); return; }
       if (audio.paused) {
         // A restored track's <audio> was not pre-loaded (restore never touches
         // the element, to avoid the Chromium 'getTopURL' quirk), so load it now,
         // then apply the deferred seek so it resumes from the saved spot.
         if (restoredMusicPos !== null && restoredMusicPos > 0) {
-          const track = trackById(store.currentId);
+          const track = resolvePlayable(store.currentId);
           if (track !== null && audio.currentSrc !== new URL(track.url, window.location.href).href) {
             audio.src = track.url;
             audio.load();
@@ -704,19 +881,17 @@ window.__ModuleLoader__.load({
         // Envelope decoding is deferred to play (see loadTracks) — decode the
         // restored track lazily so its spectrum is ready once it resumes.
         if (!String(store.currentId).startsWith('book:')) {
-          const track = trackById(store.currentId);
+          const track = resolvePlayable(store.currentId);
           if (track !== null && !envCache.has(track.id)) loadEnvelope(track.id, track.url);
         }
       } else audio.pause();
     }
     function step(delta) {
-      if (store.tracks.length === 0) return;
-      if (store.mode === 'shuffle' && store.tracks.length > 1) {        // Walk the shuffled queue: next plays the next unplayed track, prev
+      const ids = activeIds();
+      if (ids.length === 0) return;
+      if (store.mode === 'shuffle' && ids.length > 1) {        // Walk the shuffled queue: next plays the next unplayed track, prev
         // returns to the previously played one (not a list-order neighbor).
-        if (shuffleQueue.length !== store.tracks.length
-          || store.currentId === null || !shuffleQueue.includes(store.currentId)) {
-          buildShuffleQueue(store.currentId);
-        }
+        ensureShuffleReady();
         const pos = shuffleQueue.indexOf(store.currentId);
         if (store.currentId === null) {
           // Nothing playing yet: start from the head of the shuffled queue.
@@ -740,9 +915,9 @@ window.__ModuleLoader__.load({
         }
         return;
       }
-      const idx = store.tracks.findIndex((t) => t.id === store.currentId);
-      const nextIdx = idx < 0 ? 0 : (idx + delta + store.tracks.length) % store.tracks.length;
-      startPlay(store.tracks[nextIdx].id);
+      const idx = ids.indexOf(store.currentId);
+      const nextIdx = idx < 0 ? 0 : (idx + delta + ids.length) % ids.length;
+      startPlay(ids[nextIdx]);
     }
     // In book (AI 讲书) mode the transport prev/next buttons jump between
     // CHAPTERS instead of music tracks. The current chapter is the section
@@ -970,10 +1145,31 @@ window.__ModuleLoader__.load({
       };
     }
 
+    // Restore the persisted playback scope (playlist/library); a stale playlist id falls back.
+    function restoreScope(plists) {
+      const raw = loadPref(PREF_SCOPE);
+      try {
+        const o = JSON.parse(raw);
+        if (o && o.kind === 'playlist' && (plists || []).some((p) => p.id === o.id)) {
+          set({ scope: { kind: 'playlist', id: o.id } });
+          return;
+        }
+      } catch (e) {}
+      set({ scope: { kind: 'library' } });
+    }
+
     function restorePlayback(list) {
       const saved = loadPlayback();
       if (saved === null) return;
-      const track = list.find((t) => t.id === saved.id);
+      // A saved current track may be a library track or a playlist member ('p:'+path).
+      let track = list.find((t) => t.id === saved.id);
+      let scope = { kind: 'library' };
+      if (track === undefined && String(saved.id).startsWith('p:')) {
+        for (const p of store.playlists || []) {
+          const m = (p.tracks || []).find((t) => t.id === saved.id);
+          if (m) { track = m; scope = { kind: 'playlist', id: p.id }; break; }
+        }
+      }
       if (track === undefined) return;
       const pos = Number.isFinite(saved.position) ? saved.position : 0;
       const savedDur = Number.isFinite(saved.duration) && saved.duration > 0 ? saved.duration : 0;
@@ -984,7 +1180,7 @@ window.__ModuleLoader__.load({
       set({
         currentId: track.id, currentName: track.name,
         position: pos, duration: savedDur,
-        pendingId: null, pendingName: null, error: null,
+        pendingId: null, pendingName: null, error: null, scope,
       });
       if (pos > 0) {
         restoredMusicPos = pos;
@@ -1077,6 +1273,7 @@ window.__ModuleLoader__.load({
         set({
           root: result.root || null, bookRoot: result.bookRoot || null,
           tracks: result.tracks || [], books: result.books || [],
+          playlists: result.playlists || [],
           count: result.count || 0, loading: false, error: result.error || null,
           ttsConfigured: !!result.ttsConfigured, ttsReason: result.ttsReason || '',
           voices: Array.isArray(result.voices) ? result.voices : [],
@@ -1085,6 +1282,7 @@ window.__ModuleLoader__.load({
         // Envelope (spectrum) decoding is deferred to actual playback — no need
         // to decode several full files eagerly at page load; the current track's
         // envelope decodes on play (startPlay / resume).
+        restoreScope(result.playlists || []);
         restoreLatest(list);
       } catch (err) {
         set({ loading: false, error: '\u65e0\u6cd5\u8bfb\u53d6\u97f3\u4e50\u5e93\uff1a' + String((err && err.message) || err) });
@@ -1261,7 +1459,7 @@ window.__ModuleLoader__.load({
         vizBadge = React.createElement('button', {
           className: 'dsh-music-bar-warn',
           title: '\u9891\u8c31\u4e0d\u53ef\u7528\uff0c\u70b9\u51fb\u91cd\u8bd5',
-          onClick: () => { const t = trackById(s.currentId); if (t !== null) loadEnvelope(t.id, t.url); },
+          onClick: () => { const t = resolvePlayable(s.currentId); if (t !== null) loadEnvelope(t.id, t.url); },
         }, '\u9891\u8c31\u4e0d\u53ef\u7528\uff0c\u70b9\u51fb\u91cd\u8bd5');
       }
       const note = React.createElement(MusicNote, { className: 'dsh-music-note' });
@@ -1277,6 +1475,16 @@ window.__ModuleLoader__.load({
         sectionBadge = React.createElement('span', { className: 'dsh-music-bar-section', title: s.currentSection },
           '\u25b8 ' + s.currentSection);
       }
+      // 自建歌单：收藏爱心按钮（收藏时用主题色）。
+      const faved = hasTrack && !isBook && isCurrentFaved();
+      const heartBtn = hasTrack && !isBook ? React.createElement('button', {
+        className: 'dsh-music-bar-btn fav' + (faved ? ' on' : ''),
+        title: faved ? '取消收藏（从「我最喜欢」移除）' : '收藏到「我最喜欢」',
+        onClick: toggleFav,
+      }, React.createElement('svg', {
+        viewBox: '0 0 24 24', width: 14, height: 14,
+        fill: faved ? 'currentColor' : 'none', stroke: 'currentColor', strokeWidth: 2, 'aria-hidden': true,
+      }, React.createElement('path', { d: 'M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z' }))) : null;
       return React.createElement('div', { className: 'dsh-music-bar-wrap' },
         React.createElement('div', { className: 'dsh-music-bar' + (isBook ? ' book' : '') },
           hasTrack
@@ -1291,6 +1499,7 @@ window.__ModuleLoader__.load({
                 ? React.createElement('span', { className: 'dsh-music-bar-hint' }, '\u26a0 \u81ea\u52a8\u64ad\u653e\u88ab\u62e6\u622a\uff0c\u70b9\u51fb\u25b6\u89e3\u9501')
                 : React.createElement('span', { className: 'dsh-music-bar-time' }, fmtTime(s.position) + ' / ' + fmtTime(s.duration)))
             : null,
+          heartBtn,
           hasTrack ? React.createElement('button', { className: 'dsh-music-bar-btn', title: isBook ? '\u4e0a\u4e00\u7ae0' : '\u4e0a\u4e00\u9996', onClick: () => (isBook ? stepBook(-1) : step(-1)) }, '\u23ee') : null,
           hasTrack ? React.createElement('button', { className: 'dsh-music-bar-btn', title: '\u64ad\u653e/\u6682\u505c', onClick: togglePlay }, s.playing ? '\u23f8' : '\u25b6') : null,
           hasTrack ? React.createElement('button', { className: 'dsh-music-bar-btn', title: isBook ? '\u4e0b\u4e00\u7ae0' : '\u4e0b\u4e00\u9996', onClick: () => (isBook ? stepBook(1) : step(1)) }, '\u23ed') : null,
@@ -1425,6 +1634,12 @@ window.__ModuleLoader__.load({
       // Draggable panel position ({x, y, h} left/top/height once dragged; null = default right/bottom)
       const [pos, setPos] = useState(loadPanelPos);
       const dragRef = useRef(null);
+      // 曲库每行「＋」打开的「加入歌单」菜单：{track, x, y}（锚点=按钮右上角视口坐标）。
+      const [addMenu, setAddMenu] = useState(null);
+      const openAddMenu = (track, e) => {
+        const r = e.currentTarget.getBoundingClientRect();
+        setAddMenu({ track, x: r.right, y: r.top });
+      };
 
       // Once the panel is dragged we switch from CSS right/bottom anchoring to an
       // explicit left/top/height. Locking the height matters: with only top+left set
@@ -1485,18 +1700,26 @@ window.__ModuleLoader__.load({
         const active = list.querySelector('.dsh-music-track.active');
         if (active !== null && typeof active.scrollIntoView === 'function') active.scrollIntoView({ block: 'nearest' });
       }, [s.panelOpen, s.currentId]);
+      // 面板关闭时清掉「加入歌单」弹层状态，避免重开面板时残留。
+      useEffect(() => { if (!s.panelOpen) setAddMenu(null); }, [s.panelOpen]);
       if (!s.panelOpen) return null;
       const rows = s.tracks.map((t) => {
         const active = t.id === s.currentId;
         const playing = active && s.playing;
-        return React.createElement('button', {
-          key: t.id,
-          className: 'dsh-music-track' + (active ? ' active' : ''),
-          title: t.url,
-          onClick: () => { if (active) togglePlay(); else startPlay(t.id); },
-        },
-          React.createElement('span', { className: 'dsh-music-track-name' }, (playing ? '\u25b6 ' : '') + t.name),
-          React.createElement('span', { className: 'dsh-music-track-size' }, formatSize(t.size)),
+        return React.createElement('div', { key: t.id, className: 'dsh-music-track-row' + (active ? ' active' : '') },
+          React.createElement('button', {
+            className: 'dsh-music-track' + (active ? ' active' : ''),
+            title: t.url,
+            onClick: () => { if (active) togglePlay(); else startPlayFrom(t.id, 'library'); },
+          },
+            React.createElement('span', { className: 'dsh-music-track-name' }, (playing ? '\u25b6 ' : '') + t.name),
+            React.createElement('span', { className: 'dsh-music-track-size' }, formatSize(t.size)),
+          ),
+          React.createElement('button', {
+            className: 'dsh-music-playlist-mini add',
+            title: '加入歌单',
+            onClick: (e) => { e.stopPropagation(); openAddMenu(t, e); },
+          }, '\uff0b'),
         );
       });
       const bookRows = s.books.map((b) => {
@@ -1516,8 +1739,29 @@ window.__ModuleLoader__.load({
         className: 'dsh-music-tab' + (s.tab === key ? ' active' : ''),
         onClick: () => set({ tab: key }),
       }, label);
+      // 音乐页子标签：曲库 / 我最喜欢 / ＋ / 自建歌单
+      const subTabBtn = (key, label, extraCls, rkey) => React.createElement('button', {
+        key: rkey,
+        className: 'dsh-music-subtab' + (s.subTab === key ? ' active' : '') + (extraCls ? ' ' + extraCls : ''),
+        title: label,
+        onClick: () => set({ subTab: key }),
+      }, label);
+      const musicSubTabs = React.createElement('div', { className: 'dsh-music-subtabs' },
+        subTabBtn('library', '\u66f2\u5e93'),
+        subTabBtn(FAV_PLAYLIST_ID, '\u2665 \u6211\u6700\u559c\u6b22'),
+        // 自建歌单排在 ＋ 号之前；＋ 固定在末尾用于新建。
+        (s.playlists || []).filter((p) => p.id !== FAV_PLAYLIST_ID).map((p) => subTabBtn(p.id, p.name, null, p.id)),
+        React.createElement('button', { className: 'dsh-music-subtab add', title: '新建歌单', onClick: onCreatePlaylist }, '\uff0b'),
+      );
+      const isPlaylistView = s.subTab !== 'library';
+      const plView = isPlaylistView ? playlistById(s.subTab) : null;
+      const musicBody = plView
+        ? React.createElement(PlaylistDetail, { pl: plView })
+        : (rows.length > 0
+          ? rows
+          : React.createElement('div', { className: 'dsh-music-empty' }, '\u6682\u65e0\u97f3\u4e50\u3002\u70b9\u51fb\u4e0a\u65b9\u201c\u9009\u62e9\u97f3\u4e50\u76ee\u5f55\u201d\u5e76\u9009\u62e9\u76ee\u5f55\u540e\u81ea\u52a8\u626b\u63cf\u3002'));
       const listBody = s.tab === 'music'
-        ? (rows.length > 0 ? rows : React.createElement('div', { className: 'dsh-music-empty' }, '\u6682\u65e0\u97f3\u4e50\u3002\u70b9\u51fb\u4e0a\u65b9\u201c\u9009\u62e9\u97f3\u4e50\u76ee\u5f55\u201d\u5e76\u9009\u62e9\u76ee\u5f55\u540e\u81ea\u52a8\u626b\u63cf\u3002'))
+        ? musicBody
         : (s.books.length > 0
           ? bookRows
           : (s.ttsConfigured
@@ -1533,11 +1777,16 @@ window.__ModuleLoader__.load({
           React.createElement('button', { className: 'dsh-music-icon-btn', title: '\u5173\u95ed', onClick: () => set({ panelOpen: false }) }, '\u2715')),
         React.createElement('div', { className: 'dsh-music-tabs' }, tabBtn('music', '\u97f3\u4e50'), tabBtn('book', '\u5c0f\u8bf4')),
         React.createElement(DirectorySetting, null),
+        s.tab === 'music' ? musicSubTabs : null,
         // While a novel is playing, keep music-only errors/scanning out of the
         // panel (novel status shows on the playback bar instead).
         !isBook && s.error ? React.createElement('div', { className: 'dsh-music-error' }, s.error) : null,
         !isBook && s.loading ? React.createElement('div', { className: 'dsh-music-loading' }, '\u626b\u63cf\u4e2d\u2026') : null,
         React.createElement('div', { className: 'dsh-music-list', ref: (el) => { listRef.current = el; } }, listBody),
+        addMenu ? React.createElement(AddToPlaylistMenu, {
+          track: addMenu.track, anchor: { x: addMenu.x, y: addMenu.y },
+          onClose: () => setAddMenu(null),
+        }) : null,
       );
     }
     // Directory setting block, embedded in the player panel (the former
@@ -1630,6 +1879,151 @@ window.__ModuleLoader__.load({
         saveRoot(p, isBook ? 'book' : 'music');
       }
     }
+    // 「加入歌单」弹层：曲库每行「＋」点击后出现，列出所有歌单（含我最喜欢）并可新建。
+    // 用 fixed 定位（锚点为按钮视口坐标），避免被面板滚动列表裁剪。
+    function AddToPlaylistMenu({ track, anchor, onClose }) {
+      const ref = useRef(null);
+      useEffect(() => {
+        const onDown = (e) => { if (ref.current !== null && !ref.current.contains(e.target)) onClose(); };
+        document.addEventListener('mousedown', onDown);
+        return () => document.removeEventListener('mousedown', onDown);
+      }, [onClose]);
+      const openUp = (anchor.y || 0) > ((window.innerHeight || 0) - 240);
+      const style = {
+        left: Math.max(8, (anchor.x || 0) - 150),
+        top: openUp ? (anchor.y || 0) - 6 : (anchor.y || 0) + 8,
+        transform: openUp ? 'translateY(-100%)' : 'none',
+      };
+      const list = store.playlists || [];
+      const addTo = (id) => { apiPlaylistAdd(id, [track.path], () => onClose()); };
+      const addNew = () => {
+        const name = window.prompt('新建歌单名称', '');
+        if (name === null) return;
+        const trimmed = name.trim();
+        if (trimmed === '') return;
+        fetch('/dsh-music/playlist', {
+          method: 'POST', cache: 'no-store',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ name: trimmed }),
+        }).then((r) => r.json()).then((r) => {
+          if (r && r.playlist) {
+            set({ playlists: [...(store.playlists || []), r.playlist] });
+            apiPlaylistAdd(r.playlist.id, [track.path], () => onClose());
+          }
+        }).catch(() => onClose());
+      };
+      return React.createElement('div', { className: 'dsh-music-add-pop', ref, style },
+        list.length > 0 ? list.map((p) => React.createElement('button', {
+          key: p.id,
+          className: 'dsh-music-add-pop-item',
+          title: '加入「' + p.name + '」',
+          onClick: () => addTo(p.id),
+        }, (p.id === FAV_PLAYLIST_ID ? '\u2665 ' : '') + p.name + '\uff08' + p.count + '\uff09')) : null,
+        React.createElement('button', { className: 'dsh-music-add-pop-item new', onClick: addNew }, '\uff0b \u65b0\u5efa\u6b4c\u5355'),
+      );
+    }
+    // 歌单详情：添加歌曲 + 重命名/删除 + 歌曲列表（移除/上移/下移）。
+    function PlaylistDetail({ pl }) {
+      const [pickerOpen, setPickerOpen] = useState(false);
+      const rows = (pl.tracks || []).map((t, idx) => {
+        const active = t.id === store.currentId;
+        const playing = active && store.playing;
+        return React.createElement('div', { key: t.id, className: 'dsh-music-playlist-row' + (active ? ' active' : '') },
+          React.createElement('button', {
+            className: 'dsh-music-track',
+            title: t.url,
+            onClick: () => { if (active) togglePlay(); else startPlayFrom(t.id, 'playlist', pl.id); },
+          },
+            React.createElement('span', { className: 'dsh-music-track-name' }, (playing ? '\u25b6 ' : '') + (idx + 1) + '. ' + t.name),
+            React.createElement('span', { className: 'dsh-music-track-size' }, formatSize(t.size)),
+          ),
+          React.createElement('button', { className: 'dsh-music-playlist-mini', title: '上移', onClick: (e) => { e.stopPropagation(); movePlaylistTrack(pl, t.path, -1); } }, '\u2191'),
+          React.createElement('button', { className: 'dsh-music-playlist-mini', title: '下移', onClick: (e) => { e.stopPropagation(); movePlaylistTrack(pl, t.path, 1); } }, '\u2193'),
+          React.createElement('button', { className: 'dsh-music-playlist-mini del', title: '从歌单移除', onClick: (e) => { e.stopPropagation(); apiPlaylistRemove(pl.id, [t.path]); } }, '\u00d7'),
+        );
+      });
+      return React.createElement('div', { className: 'dsh-music-playlist' },
+        React.createElement('div', { className: 'dsh-music-playlist-head' },
+          React.createElement('button', { className: 'dsh-music-playlist-btn', onClick: () => setPickerOpen(true) }, '\uff0b \u6dfb\u52a0\u6b4c\u66f2'),
+          React.createElement('button', { className: 'dsh-music-playlist-btn', onClick: () => onClearPlaylist(pl) }, '清空'),
+          !pl.fixed ? React.createElement('button', { className: 'dsh-music-playlist-btn', onClick: () => onRenamePlaylist(pl) }, '重命名') : null,
+          !pl.fixed ? React.createElement('button', { className: 'dsh-music-playlist-btn', onClick: () => onDeletePlaylist(pl) }, '删除') : null,
+          pl.missing > 0 ? React.createElement('span', { className: 'dsh-music-playlist-missing', title: '部分歌曲文件已被移动或删除' }, pl.missing + ' 首已失效') : null,
+        ),
+        rows.length > 0 ? rows : React.createElement('div', { className: 'dsh-music-empty dsh-music-playlist-empty' }, '歌单为空，点击「添加歌曲」从本地文件选择音乐。'),
+        pickerOpen ? React.createElement(FilePicker, { pl, onClose: () => setPickerOpen(false) }) : null,
+      );
+    }
+    // 文件系统多选器：浏览目录 + 勾选音频文件，用于歌单「添加歌曲」。
+    function FilePicker({ pl, onClose }) {
+      const [cur, setCur] = useState({ path: '', name: '', up: null, dirs: [], files: [] });
+      const [sel, setSel] = useState(new Set());
+      const [err, setErr] = useState(null);
+      const [busy, setBusy] = useState(false);
+      const browse = async (p) => {
+        setErr(null);
+        try {
+          const data = await jsonGet('/dsh-music/files?path=' + encodeURIComponent(p || ''));
+          if (data && data.error) { setErr(data.error); return; }
+          setCur({ path: data.path || '', name: data.name || '', up: data.up || null, dirs: data.dirs || [], files: data.files || [] });
+        } catch (e) { setErr('读取目录失败：' + String((e && e.message) || e)); }
+      };
+      // 默认定位到音乐目录（store.root），未配置时回退家目录。
+      useEffect(() => { browse(store.root || ''); }, []);
+      const toggle = (p) => {
+        const next = new Set(sel);
+        if (next.has(p)) next.delete(p); else next.add(p);
+        setSel(next);
+      };
+      const confirmAdd = async () => {
+        const paths = [...sel];
+        if (paths.length === 0 || busy) { onClose(); return; }
+        setBusy(true);
+        apiPlaylistAdd(pl.id, paths, () => onClose());
+      };
+      return React.createElement('div', { className: 'dsh-music-picker-overlay' },
+        React.createElement('div', { className: 'dsh-music-picker' },
+          React.createElement('div', { className: 'dsh-music-picker-head' },
+            React.createElement('span', { className: 'dsh-music-picker-title' }, '\u6dfb\u52a0\u6b4c\u66f2\u5230\u300c' + pl.name + '\u300d'),
+          ),
+          React.createElement('div', { className: 'dsh-music-picker-cur', title: cur.path }, cur.name || cur.path || '\u5bb6\u76ee\u5f55'),
+          React.createElement('div', { className: 'dsh-music-picker-list' },
+            (cur.dirs || []).map((d) => React.createElement('button', {
+              key: d.path, className: 'dsh-music-picker-item', title: d.path,
+              onClick: () => browse(d.path),
+            }, '\ud83d\udcc1 ' + d.name)),
+            (cur.files || []).map((f) => {
+              const checked = sel.has(f.path);
+              return React.createElement('button', {
+                key: f.path,
+                className: 'dsh-music-file-item' + (checked ? ' checked' : ''),
+                title: f.path,
+                onClick: () => toggle(f.path),
+              },
+                React.createElement('span', { className: 'dsh-music-file-check' }, checked ? '\u2713' : ''),
+                React.createElement('span', { className: 'dsh-music-file-name' }, f.name),
+                React.createElement('span', { className: 'dsh-music-track-size' }, formatSize(f.size)),
+              );
+            }),
+            err ? React.createElement('div', { className: 'dsh-music-error' }, err) : null,
+          ),
+          React.createElement('div', { className: 'dsh-music-picker-foot' },
+            React.createElement('button', { className: 'dsh-music-settings-btn ghost', onClick: () => goUp() }, '上一级'),
+            React.createElement('button', { className: 'dsh-music-settings-btn', onClick: confirmAdd, disabled: busy }, '确定添加（' + sel.size + '）'),
+            React.createElement('button', { className: 'dsh-music-settings-btn ghost', onClick: onClose }, '取消'),
+          ),
+        ),
+      );
+      function goUp() {
+        const u = cur.up;
+        if (u === '__drives__') { browse('__drives__'); return; }
+        if (u) { browse(u); return; }
+        if (cur.path === '' || cur.path === '/' || /^[A-Za-z]:[\\/]?$/.test(cur.path)) return;
+        const idx = Math.max(cur.path.lastIndexOf('/'), cur.path.lastIndexOf('\\'));
+        if (idx <= 0) return;
+        browse(cur.path.slice(0, idx));
+      }
+    }
 
     const inject = ['slots'];
     function apply(ctx) {
@@ -1648,6 +2042,7 @@ window.__ModuleLoader__.load({
         attachAudioElements();
         const unbind = bindAudio();
         startRaf();
+        const accentWatch = watchAccent();
         // Browsers auto-release a wake lock when the page is hidden; re-acquire
         // on return if playback is still running, and drop it on hide so we
         // don't hold it while the tab is backgrounded.
@@ -1667,6 +2062,8 @@ window.__ModuleLoader__.load({
         return () => {
           window.removeEventListener('pagehide', onPageHide);
           document.removeEventListener('visibilitychange', onVis); stopRaf(); unbind(); closeDecodeCtx(); releaseWakeLock();
+          if (accentWatch !== null) accentWatch.disconnect();
+          accentObserver = null;
         };
       }, 'music-player: audio + viz engine');
 
@@ -1693,6 +2090,14 @@ window.__ModuleLoader__.load({
             if (store.currentId !== null && String(store.currentId).startsWith('book:')) stepBook(-1); else step(-1);
             return;
           }
+          // play with a playlist: switch scope to that playlist and start it.
+          if (intent.playlistId) {
+            const pl = playlistById(intent.playlistId);
+            if (pl && pl.tracks && pl.tracks.length > 0) {
+              startPlayFrom(pl.tracks[0].id, 'playlist', pl.id);
+            }
+            return;
+          }
           // play (default): needs an id — a book id (e.g. "b0") starts AI 讲书.
           if (intent.id === undefined) return;
           const book = bookById(intent.id);
@@ -1701,11 +2106,11 @@ window.__ModuleLoader__.load({
             resumeOrPlayBook(book.id);
             return;
           }
-          const track = trackById(intent.id);
+          const track = resolvePlayable(intent.id);
           if (track !== null) {
             audio.src = track.url;
             audio.load();
-            set({ currentId: intent.id, currentName: track.name, error: null });
+            set({ currentId: intent.id, currentName: track.name, error: null, scope: { kind: 'library' } });
             loadEnvelope(intent.id, track.url);
             prefetchNext();
             savePlayback();
@@ -1740,8 +2145,13 @@ window.__ModuleLoader__.load({
     const PLAYER_CSS = '\n' +
       // Accent follows the host app's theme brand color (stable from the start —
       // no green-default-to-sampled-blue flash); green is only the fallback when
-      // the app exposes no brand color.
-      ':root { --dsh-music-accent: var(--dsw-alias-brand-primary, #2f9e6e); }\n' +
+      // the app exposes no brand color. The alias must be declared on BODY, not
+      // :root: DSH defines its --dsw-alias-* theme tokens on <body> only, and a
+      // var() reference resolves against the element that declares it — on
+      // :root (html) it cannot see body's tokens and would always fall back to
+      // green. Declared on body, the reference resolves and children inherit
+      // the theme's actual brand color.
+      'body { --dsh-music-accent: var(--dsw-alias-brand-primary, #2f9e6e); }\n' +
       '.dsh-music-bar-wrap { box-sizing: border-box; width: 100%; padding: 0 var(--dsh-composer-side-clearance, 16px); }\n' +
       '.dsh-music-bar { box-sizing: border-box; display: flex; align-items: center; gap: 8px; width: 100%; max-width: var(--dsh-composer-card-max-width, 780px); margin: 0 auto; padding: 4px 10px; font-size: 12px; color: var(--dsw-alias-label-secondary, #8a8f98); background: var(--dsw-alias-bg-layer-1, rgba(0,0,0,0.04)); border: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,0.2)); border-radius: 8px; }\n' +
       '.dsh-music-bar-idle { color: var(--dsw-alias-label-primary, #e6e6e6); font-weight: 500; display: inline-flex; align-items: center; }\n' +
@@ -1811,11 +2221,11 @@ window.__ModuleLoader__.load({
       '.dsh-music-settings-cur { flex: 1; min-width: 0; padding: 6px 10px; border-radius: 8px; border: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,0.3)); background: var(--dsw-alias-bg-layer-1, rgba(0,0,0,0.04)); color: var(--dsw-alias-label-primary, #e6e6e6); font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n' +
       '.dsh-music-settings-btn { padding: 6px 12px; border-radius: 8px; border: none; background: var(--dsh-music-accent, #2f9e6e); color: #fff; cursor: pointer; font-size: 13px; white-space: nowrap; }\n' +
       '.dsh-music-settings-btn.ghost { background: transparent; border: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,0.3)); color: var(--dsw-alias-label-secondary, #8a8f98); }\n' +
-      '.dsh-music-picker-overlay { position: absolute; inset: 0; z-index: 70; display: flex; align-items: center; justify-content: center; background: rgba(0,0,0,0.45); }\n' +
-      '.dsh-music-picker { box-sizing: border-box; width: 88%; max-height: 80%; display: flex; flex-direction: column; gap: 8px; padding: 12px; background: var(--dsw-alias-bg-overlay, #1e1f22); border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.35)); border-radius: 12px; color: var(--dsw-alias-label-primary, #e6e6e6); }\n' +
-      '.dsh-music-picker-head { display: flex; align-items: center; }\n' +
+      '.dsh-music-picker-overlay { position: absolute; inset: 0; z-index: 70; display: flex; overflow: auto; padding: 16px; background: rgba(0,0,0,0.45); }\n' +
+      '.dsh-music-picker { box-sizing: border-box; width: 88%; max-height: 100%; margin: auto; display: flex; flex-direction: column; gap: 8px; padding: 12px; background: var(--dsw-alias-bg-overlay, #1e1f22); border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.35)); border-radius: 12px; color: var(--dsw-alias-label-primary, #e6e6e6); }\n' +
+      '.dsh-music-picker-head { display: flex; align-items: center; flex: none; }\n' +
       '.dsh-music-picker-title { font-weight: 600; }\n' +
-      '.dsh-music-picker-cur { font-size: 12px; color: var(--dsw-alias-label-secondary, #8a8f98); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n' +
+      '.dsh-music-picker-cur { flex: none; font-size: 12px; color: var(--dsw-alias-label-secondary, #8a8f98); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n' +
       '.dsh-music-picker-list { flex: 1; overflow-y: auto; display: flex; flex-direction: column; gap: 2px; }\n' +
       '.dsh-music-picker-item { text-align: left; padding: 6px 8px; border: none; background: transparent; border-radius: 6px; color: var(--dsw-alias-label-primary, #e6e6e6); cursor: pointer; font-size: 13px; }\n' +
       '.dsh-music-picker-item:hover { background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.06)); }\n' +
@@ -1834,7 +2244,42 @@ window.__ModuleLoader__.load({
       '.dsh-music-toc-item.active { color: var(--dsh-music-accent, #2f9e6e); }\n' +
       '.dsh-music-toc-type { flex: none; font-size: 10px; padding: 1px 5px; border-radius: 4px; background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.08)); color: var(--dsw-alias-label-secondary, #8a8f98); }\n' +
       '.dsh-music-toc-item.active .dsh-music-toc-type { background: var(--dsh-music-accent, #2f9e6e); color: #fff; }\n' +
-      '.dsh-music-toc-heading { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n';
+      '.dsh-music-toc-heading { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n' +
+      // 自建歌单：音乐页子标签 / 歌单详情 / 文件多选 / 播放条收藏
+      '.dsh-music-subtabs { display: flex; gap: 4px; flex-wrap: wrap; }\n' +
+      '.dsh-music-subtab { flex: none; padding: 4px 10px; border: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,0.3)); background: transparent; border-radius: 16px; color: var(--dsw-alias-label-secondary, #8a8f98); cursor: pointer; font-size: 12px; max-width: 140px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n' +
+      '.dsh-music-subtab:hover { background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.06)); }\n' +
+      '.dsh-music-subtab.active { background: var(--dsh-music-accent, #2f9e6e); border-color: var(--dsh-music-accent, #2f9e6e); color: #fff; }\n' +
+      '.dsh-music-subtab.add { width: 30px; padding: 4px 0; text-align: center; color: var(--dsh-music-accent, #2f9e6e); }\n' +
+      '.dsh-music-playlist { display: flex; flex-direction: column; flex: 1; }\n' +
+      '.dsh-music-playlist-empty { flex: 1; display: flex; align-items: center; justify-content: center; }\n' +
+      '.dsh-music-playlist-head { display: flex; align-items: center; gap: 6px; padding: 2px 2px 0; }\n' +
+      '.dsh-music-playlist-btn { flex: none; background: transparent; border: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,0.3)); border-radius: 6px; color: var(--dsw-alias-label-secondary, #8a8f98); cursor: pointer; font-size: 11px; padding: 2px 8px; }\n' +
+      '.dsh-music-playlist-btn:hover { color: var(--dsh-music-accent, #2f9e6e); }\n' +
+      '.dsh-music-playlist-missing { flex: none; margin-left: auto; font-size: 11px; color: var(--dsw-alias-state-warn-primary, #d9a441); }\n' +
+      '.dsh-music-playlist-row { display: flex; align-items: center; gap: 4px; }\n' +
+      '.dsh-music-playlist-row .dsh-music-track { flex: 1; min-width: 0; }\n' +
+      '.dsh-music-playlist-row.active .dsh-music-track { color: var(--dsh-music-accent, #2f9e6e); }\n' +
+      '.dsh-music-playlist-mini { flex: none; width: 20px; height: 20px; padding: 0; border: none; background: transparent; border-radius: 4px; color: var(--dsw-alias-label-secondary, #8a8f98); cursor: pointer; font-size: 12px; line-height: 1; }\n' +
+      '.dsh-music-playlist-mini:hover { background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.06)); color: var(--dsh-music-accent, #2f9e6e); }\n' +
+      '.dsh-music-playlist-mini.del:hover { color: var(--dsw-alias-state-error-primary, #e5534b); }\n' +
+      '.dsh-music-file-item { display: flex; align-items: center; gap: 8px; width: 100%; text-align: left; padding: 6px 8px; border: none; background: transparent; border-radius: 6px; color: var(--dsw-alias-label-primary, #e6e6e6); cursor: pointer; font-size: 12px; }\n' +
+      '.dsh-music-file-item:hover { background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.06)); }\n' +
+      '.dsh-music-file-item.checked { background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.1)); color: var(--dsh-music-accent, #2f9e6e); }\n' +
+      '.dsh-music-file-check { flex: none; width: 14px; height: 14px; border-radius: 3px; border: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,0.4)); display: inline-flex; align-items: center; justify-content: center; font-size: 10px; }\n' +
+      '.dsh-music-file-item.checked .dsh-music-file-check { background: var(--dsh-music-accent, #2f9e6e); border-color: var(--dsh-music-accent, #2f9e6e); color: #fff; }\n' +
+      '.dsh-music-file-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n' +
+      // 曲库每行：track 按钮 + 行尾「＋」（加入歌单）
+      '.dsh-music-track-row { display: flex; align-items: center; gap: 4px; }\n' +
+      '.dsh-music-track-row .dsh-music-track { flex: 1; min-width: 0; }\n' +
+      '.dsh-music-track-row.active .dsh-music-track { color: var(--dsh-music-accent, #2f9e6e); }\n' +
+      '.dsh-music-playlist-mini.add { color: var(--dsh-music-accent, #2f9e6e); }\n' +
+      '.dsh-music-add-pop { position: fixed; z-index: 1200; min-width: 150px; max-width: 210px; display: flex; flex-direction: column; gap: 2px; padding: 6px; background: var(--dsw-alias-bg-overlay, #1e1f22); border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.35)); border-radius: 10px; box-shadow: 0 8px 24px rgba(0,0,0,0.3); }\n' +
+      '.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-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';
 
     return module.exports;
   },

package/lib/index.js

@@ -352,12 +352,89 @@ export function apply(ctx) {
     }
   }
   const publicTracks = () => tracks.map((t) => ({
-    id: t.id, name: t.name, url: t.url, size: t.size, ext: t.ext,
+    id: t.id, name: t.name, url: t.url, size: t.size, ext: t.ext, path: t.path,
   }))
   const publicBooks = () => books.map((b) => ({
     id: b.id, name: b.name, size: b.size, url: '/dsh-music/book/' + b.id,
   }))
 
+  // ---- 自建歌单（playlists）----
+  // 歌单数据独立持久化到 ~/.dsh/music-player-playlists.json。成员以「绝对路径」为稳定键，
+  // 不受曲库重扫的 id 变化影响；「我最喜欢」(pl-fav) 是系统默认歌单，首次启动自动创建。
+  const FAV_PLAYLIST_ID = 'pl-fav'
+  const FAV_PLAYLIST_NAME = '我最喜欢'
+  let playlists = [] // [{id,name,fixed,trackPaths:[absPath],createdAt,updatedAt}]
+
+  const playlistsFile = async () => {
+    const h = await getHome()
+    const base = (process.env.DSH_HOME) || (h === null ? null : h + '/.dsh')
+    return base === null ? null : base + '/music-player-playlists.json'
+  }
+  const loadPlaylists = async () => {
+    const file = await playlistsFile()
+    let list = []
+    if (file !== null) {
+      try {
+        const text = readFileSync(file, 'utf8')
+        const data = JSON.parse(text)
+        if (data && Array.isArray(data.playlists)) list = data.playlists
+      } catch { /* unreadable -> start with the system playlist only */ }
+    }
+    list = list
+      .filter((p) => p && typeof p === 'object' && typeof p.id === 'string' && typeof p.name === 'string')
+      .map((p) => ({
+        id: p.id, name: p.name, fixed: !!p.fixed,
+        trackPaths: Array.isArray(p.trackPaths)
+          ? p.trackPaths.filter((x) => typeof x === 'string' && x !== '')
+          : [],
+        createdAt: p.createdAt || 0, updatedAt: p.updatedAt || 0,
+      }))
+    // 系统默认歌单「我最喜欢」恒存在（固定第二位）。
+    if (!list.some((p) => p.id === FAV_PLAYLIST_ID)) {
+      list.unshift({ id: FAV_PLAYLIST_ID, name: FAV_PLAYLIST_NAME, fixed: true, trackPaths: [], createdAt: Date.now(), updatedAt: Date.now() })
+    }
+    playlists = list
+  }
+  const savePlaylists = async () => {
+    const file = await playlistsFile()
+    if (file === null) return
+    try {
+      mkdirSync(dirname(file), { recursive: true })
+      writeFileSync(file, JSON.stringify({ version: 1, playlists }, null, 2) + '\n', 'utf8')
+    } catch { /* best-effort */ }
+  }
+  const findPlaylist = (id) => playlists.find((p) => p.id === id) || null
+  // 把歌单成员（绝对路径）解析为可播放对象；文件已删/不可读 -> null（计入 missing）。
+  const resolvePlaylistMember = (path) => {
+    try {
+      const st = statSync(path)
+      if (!st.isFile()) return null
+      return {
+        id: 'p:' + path,
+        name: basename(path),
+        url: '/dsh-music/file?path=' + encodeURIComponent(path),
+        size: st.size || 0,
+        path,
+      }
+    } catch { return null }
+  }
+  const publicPlaylist = (p) => {
+    const members = p.trackPaths.map(resolvePlaylistMember).filter(Boolean)
+    return {
+      id: p.id, name: p.name, fixed: p.fixed,
+      count: members.length,
+      missing: p.trackPaths.length - members.length,
+      tracks: members,
+    }
+  }
+  const publicPlaylists = () => playlists.map(publicPlaylist)
+  // /dsh-music/file 只放行已登记路径（歌单成员 ∪ 曲库扫描集），防任意文件访问。
+  const isRegisteredAudioPath = (path) => {
+    const inPlaylist = playlists.some((p) => p.trackPaths.includes(path))
+    const inLibrary = tracks.some((t) => t.path === path)
+    return inPlaylist || inLibrary
+  }
+
   const scan = async (rootPath, kinds = { music: true, books: false }) => {
     const target = await ctx.fs.resolve(rootPath)
     const info = await ctx.fs.stat(target)
@@ -456,6 +533,7 @@ export function apply(ctx) {
     if (broot === null) broot = root // default books = music dir
     musicRoot = root
     bookRoot = broot
+    await loadPlaylists()
     try {
       return await refresh()
     } catch (err) {
@@ -882,6 +960,7 @@ export function apply(ctx) {
         const ts = await ttsState()
         writeJson(res, {
           root: musicRoot, bookRoot, tracks: publicTracks(), books: publicBooks(), count: tracks.length,
+          playlists: publicPlaylists(),
           ttsConfigured: ts.configured, ttsReason: ts.reason, voices: MIMO_VOICES,
         })
         return
@@ -1043,6 +1122,210 @@ export function apply(ctx) {
         }
         return
       }
+      // ---- 自建歌单 CRUD ----
+      // POST /dsh-music/playlist {name} -> 新建
+      if (pathname === '/dsh-music/playlist' && req.method === 'POST') {
+        await ensureStarted()
+        const body = await readBody(req)
+        const name = body && typeof body.name === 'string' ? body.name.trim() : ''
+        if (name === '') { writeJson(res, { ok: false, error: '歌单名不能为空' }, 400); return }
+        const id = 'pl-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 7)
+        playlists.push({ id, name, fixed: false, trackPaths: [], createdAt: Date.now(), updatedAt: Date.now() })
+        await savePlaylists()
+        writeJson(res, { ok: true, playlist: publicPlaylist(findPlaylist(id)) })
+        return
+      }
+      // POST /dsh-music/playlist/rename {id,name}
+      if (pathname === '/dsh-music/playlist/rename' && req.method === 'POST') {
+        await ensureStarted()
+        const body = await readBody(req)
+        const pl = findPlaylist(body && typeof body.id === 'string' ? body.id : '')
+        const name = body && typeof body.name === 'string' ? body.name.trim() : ''
+        if (pl === null) { writeJson(res, { ok: false, error: '歌单不存在' }, 404); return }
+        if (name === '') { writeJson(res, { ok: false, error: '歌单名不能为空' }, 400); return }
+        if (pl.fixed) { writeJson(res, { ok: false, error: '系统默认歌单不可重命名' }, 400); return }
+        pl.name = name
+        pl.updatedAt = Date.now()
+        await savePlaylists()
+        writeJson(res, { ok: true, playlist: publicPlaylist(pl) })
+        return
+      }
+      // POST /dsh-music/playlist/delete {id}
+      if (pathname === '/dsh-music/playlist/delete' && req.method === 'POST') {
+        await ensureStarted()
+        const body = await readBody(req)
+        const id = body && typeof body.id === 'string' ? body.id : ''
+        const idx = playlists.findIndex((p) => p.id === id)
+        if (idx < 0) { writeJson(res, { ok: false, error: '歌单不存在' }, 404); return }
+        if (playlists[idx].fixed) { writeJson(res, { ok: false, error: '系统默认歌单不可删除' }, 400); return }
+        playlists.splice(idx, 1)
+        await savePlaylists()
+        writeJson(res, { ok: true })
+        return
+      }
+      // POST /dsh-music/playlist/add {id,paths:[...]}（去重、保序追加、跳过无效/非音频）
+      if (pathname === '/dsh-music/playlist/add' && req.method === 'POST') {
+        await ensureStarted()
+        const body = await readBody(req)
+        const pl = findPlaylist(body && typeof body.id === 'string' ? body.id : '')
+        const paths = Array.isArray(body && body.paths)
+          ? body.paths.filter((x) => typeof x === 'string' && x.trim() !== '')
+          : []
+        if (pl === null) { writeJson(res, { ok: false, error: '歌单不存在' }, 404); return }
+        let added = 0
+        for (const raw of paths) {
+          const p = raw.trim()
+          if (!isAudioName(p) || pl.trackPaths.includes(p)) continue
+          try { const st = statSync(p); if (!st.isFile()) continue } catch { continue }
+          pl.trackPaths.push(p)
+          added++
+        }
+        if (added > 0) pl.updatedAt = Date.now()
+        await savePlaylists()
+        writeJson(res, { ok: true, added, playlist: publicPlaylist(pl) })
+        return
+      }
+      // POST /dsh-music/playlist/remove {id,paths:[...]}
+      if (pathname === '/dsh-music/playlist/remove' && req.method === 'POST') {
+        await ensureStarted()
+        const body = await readBody(req)
+        const pl = findPlaylist(body && typeof body.id === 'string' ? body.id : '')
+        const paths = new Set(Array.isArray(body && body.paths) ? body.paths : [])
+        if (pl === null) { writeJson(res, { ok: false, error: '歌单不存在' }, 404); return }
+        const before = pl.trackPaths.length
+        pl.trackPaths = pl.trackPaths.filter((p) => !paths.has(p))
+        if (pl.trackPaths.length !== before) pl.updatedAt = Date.now()
+        await savePlaylists()
+        writeJson(res, { ok: true, removed: before - pl.trackPaths.length, playlist: publicPlaylist(pl) })
+        return
+      }
+      // POST /dsh-music/playlist/clear {id}（一键清空：移出全部歌曲，含已失效；任何歌单都允许，fixed 也可清空）
+      if (pathname === '/dsh-music/playlist/clear' && req.method === 'POST') {
+        await ensureStarted()
+        const body = await readBody(req)
+        const pl = findPlaylist(body && typeof body.id === 'string' ? body.id : '')
+        if (pl === null) { writeJson(res, { ok: false, error: '歌单不存在' }, 404); return }
+        const cleared = pl.trackPaths.length
+        pl.trackPaths = []
+        pl.updatedAt = Date.now()
+        await savePlaylists()
+        writeJson(res, { ok: true, cleared, playlist: publicPlaylist(pl) })
+        return
+      }
+      // POST /dsh-music/playlist/reorder {id,paths:[...]}（全量顺序替换，补回未提及的旧成员）
+      if (pathname === '/dsh-music/playlist/reorder' && req.method === 'POST') {
+        await ensureStarted()
+        const body = await readBody(req)
+        const pl = findPlaylist(body && typeof body.id === 'string' ? body.id : '')
+        const paths = Array.isArray(body && body.paths) ? body.paths.filter((x) => typeof x === 'string') : []
+        if (pl === null) { writeJson(res, { ok: false, error: '歌单不存在' }, 404); return }
+        const current = new Set(pl.trackPaths)
+        const reordered = paths.filter((p) => current.has(p))
+        for (const p of pl.trackPaths) if (!reordered.includes(p)) reordered.push(p)
+        pl.trackPaths = reordered
+        pl.updatedAt = Date.now()
+        await savePlaylists()
+        writeJson(res, { ok: true, playlist: publicPlaylist(pl) })
+        return
+      }
+      // ---- 文件系统多选器：列目录 + 音频文件（歌单「添加歌曲」用）----
+      // 与 /dsh-music/dir 相同的浏览体验（上级/跨盘符），但额外返回音频文件供多选勾选。
+      if (pathname === '/dsh-music/files' && req.method === 'GET') {
+        await ensureStarted()
+        const raw = url.searchParams.get('path') || ''
+        try {
+          if (raw === '__drives__') {
+            const isWin = typeof process !== 'undefined' && process.platform === 'win32'
+            if (isWin) {
+              const roots = []
+              for (const letter of 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') {
+                const root = letter + ':\\'
+                try { if (existsSync(root)) roots.push({ name: root, path: root }) } catch {}
+              }
+              writeJson(res, { path: '__drives__', name: '\u672c\u673a\u78c1\u76d8', up: null, dirs: roots, files: [] })
+            } else {
+              writeJson(res, { path: '/', name: '/', up: null, dirs: [], files: [] })
+            }
+            return
+          }
+          const base = raw === '' ? ((await getHome()) || '/') : raw
+          const expanded = base.startsWith('~/') ? ((await getHome()) || '') + '/' + base.slice(2) : base
+          const target = await ctx.fs.resolve(expanded)
+          const info = await ctx.fs.stat(target)
+          if (info === undefined || info.type !== 'directory') {
+            writeJson(res, { error: '目录不存在或不可读', path: expanded }, 400)
+            return
+          }
+          const abs = ctx.fs.processPath(target)
+          const atRoot = pathParse(abs).dir === abs
+          const up = atRoot ? (process.platform === 'win32' ? '__drives__' : null) : dirname(abs)
+          const dirs = []
+          const files = []
+          for (const e of listEntries(abs)) {
+            try {
+              if (e.isDir) { dirs.push({ name: e.name, path: pathJoin(abs, e.name) }); continue }
+              if (isAudioName(e.name)) {
+                const st = statSync(pathJoin(abs, e.name))
+                if (st.isFile()) {
+                  files.push({ name: e.name, path: pathJoin(abs, e.name), size: st.size || 0, ext: e.name.slice(e.name.lastIndexOf('.') + 1).toLowerCase() })
+                }
+              }
+            } catch { /* skip unreadable entries */ }
+          }
+          writeJson(res, { path: abs, name: basename(abs) || abs, up, dirs, files })
+        } catch (err) {
+          writeJson(res, { error: String((err && err.message) || err) }, 500)
+        }
+        return
+      }
+      // ---- 通用文件流式路由（歌单成员专用，Range/seek）----
+      // 只放行已登记路径（任一歌单成员 ∪ 曲库扫描集）。直接用 node:fs 读写，
+      // 避免 DSH ctx.fs 对工作区外路径的围栏（与讲书读取小说文件的方式一致）。
+      if (pathname === '/dsh-music/file' && (req.method === 'GET' || req.method === 'HEAD')) {
+        await ensureStarted()
+        const rawPath = url.searchParams.get('path') || ''
+        if (rawPath === '') { res.writeHead(400); res.end(); return }
+        if (!isAudioName(rawPath) || !isRegisteredAudioPath(rawPath)) { res.writeHead(403); res.end(); return }
+        let st
+        try { st = statSync(rawPath) } catch { res.writeHead(404); res.end(); return }
+        if (!st.isFile()) { res.writeHead(404); res.end(); return }
+        const size = st.size || 0
+        let start = 0
+        let end = size - 1
+        let status = 200
+        const range = req.headers.range
+        if (typeof range === 'string') {
+          const m = /^bytes=(\d*)-(\d*)$/.exec(range.trim())
+          if (m !== null && (m[1] !== '' || m[2] !== '')) {
+            if (m[1] !== '') {
+              start = parseInt(m[1], 10)
+              end = m[2] !== '' ? Math.min(parseInt(m[2], 10), size - 1) : size - 1
+            } else {
+              start = Math.max(size - parseInt(m[2], 10), 0)
+              end = size - 1
+            }
+            if (!Number.isFinite(start) || start > end || start >= size) {
+              res.writeHead(416, { 'Content-Range': 'bytes */' + size })
+              res.end()
+              return
+            }
+            status = 206
+          }
+        }
+        const bytes = readFileSync(rawPath)
+        const slice = bytes.slice(start, end + 1)
+        const headers = {
+          'Content-Type': audioType(rawPath),
+          'Accept-Ranges': 'bytes',
+          'Content-Length': String(end - start + 1),
+          'Cache-Control': 'no-store',
+        }
+        if (status === 206) headers['Content-Range'] = 'bytes ' + start + '-' + end + '/' + size
+        res.writeHead(status, headers)
+        if (req.method === 'HEAD') { res.end(); return }
+        res.end(slice)
+        return
+      }
       // audio streaming
       if (req.method !== 'GET' && req.method !== 'HEAD') { res.writeHead(405); res.end(); return }
       // Ensure the library scan completes before resolving a track, so a
@@ -1100,12 +1383,13 @@ export function apply(ctx) {
   const PLAY_ACTIONS = ['play', 'pause', 'resume', 'stop', 'next', 'prev']
   const tool = {
     name: 'music_play',
-    description: '控制 DSH 本地音乐库与小说库的播放。播放时可按歌曲名/歌手/小说名关键词搜索并播放（不传 query 则播放第一首音乐，没有音乐则播放第一本小说）；也可用 action 执行暂停/继续/停止/下一首·下一章/上一首·上一章。',
+    description: '控制 DSH 本地音乐库与小说库的播放。播放时可按歌曲名/歌手/小说名关键词搜索并播放（不传 query 则播放第一首音乐，没有音乐则播放第一本小说），或按歌单名播放自建歌单（playlist 参数）；也可用 action 执行暂停/继续/停止/下一首·下一章/上一首·上一章。',
     parameters: {
       type: 'object',
       additionalProperties: false,
       properties: {
         query: { type: 'string', description: '歌曲名/歌手/小说名关键词，用于搜索并播放。仅当 action 为 play（默认）时使用，可留空' },
+        playlist: { type: 'string', description: '歌单名关键词，播放指定自建歌单（含默认歌单「我最喜欢」）。仅当 action 为 play（默认）时使用，优先级高于 query，可留空' },
         action: { type: 'string', enum: PLAY_ACTIONS, description: '要执行的动作：play 播放（默认）、pause 暂停、resume 继续、stop 停止、next 下一首/下一章、prev 上一首/上一章' },
       },
     },
@@ -1127,8 +1411,10 @@ export function apply(ctx) {
       const musicCount = tracks.length
       const bookCount = books.length
       const action = args && typeof args.action === 'string' && PLAY_ACTIONS.includes(args.action) ? args.action : 'play'
+      // 歌单播放不依赖曲库是否为空（歌单可含曲库外的本地文件），因此先于空库守卫判断。
+      const playlistQuery = args && typeof args.playlist === 'string' ? args.playlist.trim().toLowerCase() : ''
 
-      if (musicCount === 0 && bookCount === 0) {
+      if (musicCount === 0 && bookCount === 0 && playlistQuery === '') {
         const notice = '本地音乐库与小说库均为空。请打开播放列表面板，点击「选择音乐目录」/「选择小说目录」配置。'
         return { action, played: false, track: '', matches: 0, count: 0, notice }
       }
@@ -1145,6 +1431,25 @@ export function apply(ctx) {
         return { action, played: false, track: '', matches: 0, count: Math.max(musicCount, bookCount), notice }
       }
 
+      // play with a playlist name: play the whole playlist (priority over query).
+      if (playlistQuery !== '') {
+        const pools = playlists.filter((p) => p.name.toLowerCase().includes(playlistQuery))
+        const hit = playlists.find((p) => p.name.toLowerCase() === playlistQuery) || pools[0]
+        if (hit === undefined) {
+          const names = playlists.map((p) => p.name).join('、') || '（暂无歌单）'
+          return { action, played: false, track: '', matches: 0, count: 0, notice: '没有找到歌单「' + (args && args.playlist) + '」。现有歌单：' + names }
+        }
+        const members = publicPlaylist(hit).tracks
+        if (members.length === 0) {
+          return { action, played: false, track: '', matches: 0, count: 0, notice: '歌单「' + hit.name + '」为空，请先在播放面板该歌单里点「添加歌曲」加入音乐。' }
+        }
+        pendingIntent = { action: 'play', playlistId: hit.id, playlistName: hit.name, id: members[0].id, name: members[0].name }
+        return {
+          action, played: true, track: members[0].name, matches: members.length, count: members.length,
+          notice: '已请求播放歌单「' + hit.name + '」（' + members.length + ' 首）。若被拦截请点 ▶ 解锁。',
+        }
+      }
+
       // play: search both music tracks and novels (.txt). A book-only match
       // starts AI 讲书; otherwise fall back to the music behaviour.
       const query = args && typeof args.query === 'string' ? args.query.trim().toLowerCase() : ''
@@ -1197,7 +1502,7 @@ export function apply(ctx) {
   // ---- light prompt hint so the agent knows it can play local music/novels ----
   ctx.systemPrompt.section({
     name: 'tool:music-player', order: 116,
-    text: '本机已挂载本地音乐播放器与 AI 讲书：可用 music_play 工具按关键词播放 ~/Music（或设置的目录）里的音乐，或按小说名播放本地 .txt 小说（AI 讲书，需配置 xiaomi/MiMo TTS）；并支持 action 暂停/继续/停止/下一首·下一章/上一首·上一章。',
+    text: '本机已挂载本地音乐播放器与 AI 讲书：可用 music_play 工具按关键词播放 ~/Music（或设置的目录）里的音乐，或按歌单名播放自建歌单（playlist 参数），或按小说名播放本地 .txt 小说（AI 讲书，需配置 xiaomi/MiMo TTS）；并支持 action 暂停/继续/停止/下一首·下一章/上一首·上一章。',
   })
 
   void ensureStarted()

package/package.json

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