前言¶
在 DSH 里長時間掛着面板寫代碼或跑任務時，常會希望背景音樂不另開應用、也不把音頻文件上傳到第三方。瀏覽器自帶的播放體驗往往和麪板割裂，歌單也難和當前工作區放在一起管理。dsh-local-music-player 是面向 DSH Web UI 的本地優先音樂播放器與歌單管理插件：音頻和歌單留在當前瀏覽器的 IndexedDB，通過左側欄入口進入完整播放器界面，並支持在切換 DSH 面板時通常繼續後臺播放。
下面介紹插件定位、能力邊界、安裝方式與日常使用，事實以倉庫 README 與 npm 包信息爲準。
這是什麼¶
維護者爲 XM-Zou，npm 包名爲 dsh-local-music-player，當前 README 標明已發佈版本爲 0.7.3，許可證 MIT。插件在 DSH 客戶端側以 Web 平臺腳本注入（platform: "web"），無構建步驟、無運行時依賴；要求宿主 DSH >= 0.2.1（engines.dsh 聲明），README 寫明已在 DSH 0.2.2-rc.1 的 Desktop / Web UI 上測試。
一句話定位：在 DSH 全局左側欄增加「音樂」入口，提供導入本地音頻、歌單分類、播放控制、搜索與 ZIP 備份恢復，數據不上傳、插件不發起網絡請求。
核心功能¶
入口與導入¶
- 點擊全局左側欄「音樂」圖標進入播放器頁面。
- 「導入音樂」選文件，或把音頻拖到頁面。
- 「導入文件夾」：文件夾名自動成爲新歌單名，內部音頻一併導入；音樂庫已有曲目會複用，不重複導入。
元數據與列表展示¶
- 讀取 ID3v2 標題與封面；不識別歌手和專輯。
- 文件名含書名號《》時，優先用書名號內文字作歌名，號外文字作歌曲信息；無《》時用 ID3 標題或文件名。
- 舊版導入的曲目可通過頂部「重新解析歌曲信息」按新規則更新，無需重新導入。
- 列表顯示所屬歌單（無歌單顯示「未分類」），副標題顯示歌曲信息。
歌單與播放¶
- 新建、重命名、刪除歌單；一曲可加入多個歌單；側欄歌單可拖動排序。
- 置頂「未分類」歌單：未加入任何歌單的曲目自動歸入，且不可刪除。
- 刪除歌單默認保留歌曲：僅在本歌單的進「未分類」，仍在他處的留在原歌單；也可選同時從音樂庫刪除，共享曲目刪除前會提示。
- 播放/暫停、上下曲、進度、音量、隨機、順序/列表循環/單曲循環。
- 切換 DSH 面板時通常會繼續播放；暫停、退出 DSH 或宿主掛起時停止。
- 按歌名、歌曲信息或文件名過濾；最近導入優先顯示。
- 使用 DSH 主題 token，亮/暗主題與窄窗口適配；界面中英雙語。
備份與存儲¶
- 音頻 Blob 與歌單保存在瀏覽器 IndexedDB。
- 頂部備份：導出爲 ZIP（含
audio/、covers/、playlists.json），或從 ZIP 合併恢復；已存在歌曲複用，同名歌單合併。導入兼容舊版 v1 備份。
安裝與啓用¶
npm 爲首選來源：dsh-local-music-player@0.7.3。若桌面端「插件」界面因鏡像返回 E500 安裝失敗，README 建議用 CLI 並顯式指定 registry.npmjs.org。市場條目可能略晚於 npm；市場裏版本不是 0.7.3 時可用 npm 命令安裝。
DSH Desktop 界面：打開 設置 → 插件，在安裝來源裏填寫：
dsh-local-music-player
DSH Web（CLI）（dsh.cmd 爲 Desktop 自帶 CLI 的完整路徑，按本機 DSH 安裝目錄修改）：
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile web add dsh-local-music-player --registry=https://registry.npmjs.org
dsh 已在 PATH 時可簡寫：
dsh plugin --profile web add dsh-local-music-player --registry=https://registry.npmjs.org
DSH Desktop（CLI）：
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-local-music-player --registry=https://registry.npmjs.org
若曾用本地目錄鏈接安裝，先移除再裝：
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop remove dsh-local-music-player
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-local-music-player --registry=https://registry.npmjs.org
npm 未同步或網絡異常時，可用 GitHub 源碼安裝（README 給出的形式）：
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile web add github:XM-Zou/dsh-local-music-player --registry=https://registry.npmjs.org
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add github:XM-Zou/dsh-local-music-player --registry=https://registry.npmjs.org
也可直接下載 Release 包：dsh-local-music-player-0.7.3.tgz（見 GitHub Releases v0.7.3）。
插件市場在 插件 → 發現（Discover） 搜索；社區市場頁：https://awesome-dsh-plugin.com/p/XM-Zou/dsh-local-music-player/。DSH 生態上插件獨立分發，與 DeepSeek / 幻方無官方從屬關係，安裝前宜自行查看源碼與 MIT 許可證。
典型用法¶
經過上面的步驟啓用後，可按 README 順序操作：
- 點擊左側欄「音樂」圖標。
- 點擊「導入音樂」，或將音頻拖到頁面。
- 需要整庫分文件夾入庫時，點「導入文件夾」。
- 新建歌單，在歌曲行點 + 加入一個或多個歌單。
- 點歌曲播放；底部欄調節進度、音量、隨機與循環模式。
備份：點頂部右側備份圖標，「導出音樂庫」得到 ZIP；「導入音樂庫」會合併到現有庫。ZIP 內多歌單共享的曲目會在各歌單文件夾各有一份副本，體積會變大；空歌單也會生成空文件夾。
數據、隱私與限制¶
- 導入數據在當前 DSH 瀏覽器 origin 的 IndexedDB；清除站點數據、端口/origin 變化或換瀏覽器配置，可能導致庫不可見。
- 插件無遙測；能否播放某格式取決於宿主 Chromium/Electron 解碼能力（README 列舉常見 MP3、FLAC、WAV、M4A/AAC、OGG、Opus）。
- 已知限制：暫無雲同步；ZIP 備份不支持 ZIP64，單包超過 4 GB 無法導出；受瀏覽器存儲配額約束，超大庫可能導入失敗；庫不跨設備共享。
插件在已安裝的 DSH profile 對應客戶端環境中運行，權限與當前 DSH 進程/瀏覽器上下文一致；若對本地文件訪問範圍有要求，安裝前應閱讀倉庫源碼。
結尾¶
dsh-local-music-player 把本地聽音、歌單整理和 ZIP 遷移收進 DSH 左欄，適合希望在同一面板內後臺聽歌、且不接受音頻上雲的 DSH Web / Desktop 用戶。目錄與源碼：
