dsh-music-player 0.1.0 → 0.1.2

package/README.md

@@ -9,24 +9,40 @@ DeepSeek Harness 本地音乐库播放器插件（bundle）。
 - 本地音频流式播放，支持 seek / 断点续播
 - 顺序播放、单曲循环、乱序播放三种模式
 - 实时 7 段频谱可视化（解码音频包络驱动）
+- 播放列表面板可自由拖动，位置跨刷新记忆
 - `music_play` 模型工具：agent 可按关键词让浏览器播放
 - 支持的格式：`mp3 / m4a / m4b / aac / flac / wav / ogg / opus / webm / aiff`（自动递归扫描子目录，上限 500 首）
 
+## 截图
+
+![播放条](assets/screenshot-bar.png)
+
+![播放面板](assets/screenshot-panel.png)
+
+![实时频谱](assets/screenshot-spectrum.png)
+
 ## 安装
 
 需要已安装 `dsh` CLI。
 
-直接从一个 git 托管安装（推荐，无构建步骤）：
+### 从 npm 安装（推荐，已发布到 registry）
+
+```sh
+# 把 <profile> 换成实际 profile 名，如 web
+dsh plugin --profile <profile> add dsh-music-player
+```
+
+### 从 GitHub 安装（备用来源）
 
 ```sh
-# 安装到你的 profile（把 <profile> 换成实际 profile 名，如 web）
+# 把 <profile> 换成实际 profile 名，如 web
 dsh plugin --profile <profile> add github:kendu76/dsh-music-player
 ```
 
-> 项目是手写的纯 JS（`lib/` 直接是发布产物），**没有**需要从源码构建的步骤，因此从 GitHub 直装即可使用，无需像 TypeScript 包那样为构建脚本授权。
+> 项目是手写的纯 JS（`lib/` 直接是发布产物），**没有**需要从源码构建的步骤，因此从 GitHub/npm 直装即可使用，无需像 TypeScript 包那样为构建脚本授权。
 
 安装后重启 DSH，打开 Web GUI：
-- 聊天输入区下方会出现「本地音乐播放器」播放条
+- 聊天输入区上方会出现「本地音乐播放器」播放条
 - 点击右侧「列表」按钮打开播放面板
 - 在面板顶部点击「选择音乐目录」并选定音乐目录（默认 `~/Music`），自动递归扫描
 - 之后可直接在对话框里让 agent 播放，例如「播放周杰伦的歌」
@@ -61,11 +77,38 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
 
 ## 开发
 
+需要 Node.js ≥ 20（vitest 建议 20.19+）与 npm。开发依赖仅 `vitest`：
+
+```sh
+npm install
+npm test        # 跑 vitest 测试套件
+```
+
+修改 `lib/` 后，在本机 profile 里用 link 方式本地调试并验证：
+
 ```sh
-# 修改 lib/ 后，在本机 profile 里用 link 方式本地调试
 dsh plugin --profile <profile> add ./   # 或直接改 profile 里的 link 目标
 ```
 
+项目结构、测试策略与发布流程详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 常见问题
+
+**播放没有声音 / 显示"浏览器拦截了自动播放"？**
+浏览器安全策略禁止未经交互的音频播放。首次自动播放被拦截是正常的——在播放条上点一次 ▶ 即可解锁，之后恢复播放。
+
+**音乐面板显示"暂无音乐"或"不是有效的音乐目录"？**
+点面板顶部「选择音乐目录」，选一个包含音频文件的实际目录（默认 `~/Music`）。目录路径不可读或不存在时会回退到默认目录而不是报错。
+
+**改了音乐目录/新增了歌曲，但列表没更新？**
+播放器在启动时扫描，并在每次“选择音乐目录”时重扫。想强制刷新当前目录，重新打开一次面板或点一次目录设置即可（扫描上限 500 首、递归子目录深度上限 4 层）。
+
+**`music_play` 工具说"音乐库为空"？**
+说明还没有可用的音乐目录。请先打开播放面板，点「选择音乐目录」配置一次。
+
+**想支持更多音频格式？**
+格式支持由 Host 端 `AUDIO_TYPES` 表驱动，在 `lib/index.js` 里加扩展名与 MIME 即可（播放器本身用浏览器原生 `<audio>` 解码，最终能否播放还取决于浏览器对该编码的支持）。
+
 ## License
 
 [MIT](LICENSE) © kendu76

package/lib/client.js

@@ -28,9 +28,21 @@ window.__ModuleLoader__.load({
     const PREF_VOL = 'dsh-music-volume';
     const PREF_PLAYBACK = 'dsh-music-playback';
     const PREF_ROOT = 'dsh-music-root';
+    const PREF_PANEL_POS = 'dsh-music-panel-pos';
     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) {} };
+    // Restore the playback-panel position ({x,y,h}) previously saved by dragging, if any.
+    function loadPanelPos() {
+      const raw = loadPref(PREF_PANEL_POS);
+      if (raw === null) return null;
+      try {
+        const p = JSON.parse(raw);
+        if (p && typeof p.x === 'number' && typeof p.y === 'number'
+          && typeof p.h === 'number' && p.h > 0) return p;
+      } catch (e) {}
+      return null;
+    }
     const jsonGet = (url) => fetch(url, { cache: 'no-store' }).then((r) => r.json());
 
     // ---- engine + shared store (React re-renders on set) ----
@@ -627,6 +639,52 @@ window.__ModuleLoader__.load({
       const s = useStore();
       const listRef = useRef(null);
       const panelRef = useRef(null);
+      // Draggable panel position ({x, y, h} left/top/height once dragged; null = default right/bottom)
+      const [pos, setPos] = useState(loadPanelPos);
+      const dragRef = useRef(null);
+
+      // 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
+      // and no height, a fixed element whose CSS also sets bottom collapses to fit
+      // the leftover space, so the panel's height jumps while dragging.
+      const style = pos === null ? null : { left: pos.x, top: pos.y, height: pos.h };
+
+      const onHeadDown = (e) => {
+        if (e.button !== undefined && e.button !== 0) return;
+        // don't start a drag from the close button
+        if (e.target.closest && e.target.closest('.dsh-music-icon-btn')) return;
+        const el = panelRef.current;
+        if (el === null) return;
+        const rect = el.getBoundingClientRect();
+        const h = pos !== null ? pos.h : rect.height;
+        const next = { x: pos !== null ? pos.x : rect.left, y: pos !== null ? pos.y : rect.top, h };
+        dragRef.current = {
+          startX: e.clientX, startY: e.clientY,
+          originX: next.x, originY: next.y, h,
+        };
+        setPos(next);
+        savePref(PREF_PANEL_POS, JSON.stringify(next));
+        e.currentTarget.setPointerCapture(e.pointerId);
+      };
+      const onHeadMove = (e) => {
+        const d = dragRef.current;
+        if (d === null) return;
+        let x = d.originX + (e.clientX - d.startX);
+        let y = d.originY + (e.clientY - d.startY);
+        const el = panelRef.current;
+        if (el !== null) {
+          x = Math.max(0, Math.min(x, window.innerWidth - el.offsetWidth));
+          y = Math.max(0, Math.min(y, window.innerHeight - el.offsetHeight));
+        }
+        const next = { x, y, h: d.h };
+        setPos(next);
+        savePref(PREF_PANEL_POS, JSON.stringify(next));
+      };
+      const onHeadUp = (e) => {
+        dragRef.current = null;
+        if (e.currentTarget.hasPointerCapture(e.pointerId)) e.currentTarget.releasePointerCapture(e.pointerId);
+      };
+
       useEffect(() => {
         if (!s.panelOpen) return;
         // Close the playlist panel when the user clicks outside it
@@ -658,8 +716,12 @@ window.__ModuleLoader__.load({
           React.createElement('span', { className: 'dsh-music-track-size' }, t.size ? Math.round(t.size / 1024 / 1024 * 10) / 10 + ' MB' : ''),
         );
       });
-      return React.createElement('div', { className: 'dsh-music-panel', ref: panelRef },
-        React.createElement('div', { className: 'dsh-music-panel-head' },
+      return React.createElement('div', { className: 'dsh-music-panel', ref: panelRef, style },
+        React.createElement('div', {
+          className: 'dsh-music-panel-head dsh-music-panel-drag',
+          onPointerDown: onHeadDown, onPointerMove: onHeadMove, onPointerUp: onHeadUp,
+        },
+          React.createElement('span', { className: 'dsh-music-panel-grip', 'aria-hidden': true }, '\u283f'),
           React.createElement('span', { className: 'dsh-music-panel-title' }, '\u64ad\u653e\u5217\u8868'),
           React.createElement('button', { className: 'dsh-music-icon-btn', title: '\u5173\u95ed', onClick: () => set({ panelOpen: false }) }, '\u2715')),
         React.createElement(DirectorySetting, null),
@@ -824,6 +886,8 @@ window.__ModuleLoader__.load({
       '.dsh-music-bar .dsh-music-mode-menu { align-self: center; }\n' +
       '.dsh-music-panel { position: fixed; right: 24px; bottom: 84px; width: 380px; max-height: 72vh; display: flex; flex-direction: column; gap: 8px; padding: 12px; background: var(--dsw-alias-bg-overlay, #1e1f22); border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,0.35)); border-radius: 12px; box-shadow: 0 12px 32px rgba(0,0,0,0.35); color: var(--dsw-alias-label-primary, #e6e6e6); font-size: 13px; z-index: 1000; pointer-events: auto; overflow: hidden; }\n' +
       '.dsh-music-panel-head { display: flex; align-items: center; gap: 6px; }\n' +
+      '.dsh-music-panel-drag { cursor: move; touch-action: none; user-select: none; }\n' +
+      '.dsh-music-panel-grip { color: var(--dsw-alias-label-secondary, #8a8f98); font-size: 12px; letter-spacing: -1px; opacity: 0.7; }\n' +
       '.dsh-music-panel-title { font-weight: 600; margin-right: auto; }\n' +
       '.dsh-music-icon-btn { background: transparent; border: none; color: var(--dsw-alias-label-secondary, #8a8f98); cursor: pointer; font-size: 14px; padding: 2px 6px; border-radius: 6px; }\n' +
       '.dsh-music-icon-btn:hover { color: var(--dsw-alias-label-primary, #e6e6e6); background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,0.06)); }\n' +

package/lib/index.js

@@ -232,6 +232,10 @@ export function apply(ctx) {
       }
       // 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
+      // streaming/HEAD request that arrives before any manifest call (or at
+      // startup) still finds its track instead of spuriously 404ing.
+      await ensureStarted()
       const id = pathname.slice('/dsh-music/'.length)
       const track = tracks.find((t) => t.id === id)
       if (track === undefined) { res.writeHead(404); res.end(); return }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-music-player",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "DeepSeek Harness 本地音乐库播放器：Host 扫描音乐目录并以 HTTP 流式提供音频，浏览器侧提供播放条/播放面板/设置页与实时频谱，并注册 music_play 模型工具",
   "type": "module",
   "main": "lib/index.js",
@@ -28,6 +28,14 @@
     "url": "git+https://github.com/kendu76/dsh-music-player.git"
   },
   "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "ci": "vitest run"
+  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -39,5 +47,8 @@
   },
   "peerDependencies": {
     "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
   }
 }