DeepSeek Harness 插件：本地音樂播放器

前言¶

DeepSeek Harness（DSH）的設計理念之一是“一切皆插件”。對於需要在本地管理媒體資源的開發者或用戶，在會話視圖中直接嵌入播放器比打開外部應用或文件瀏覽器更高效。本地音樂播放器插件正是爲此設計，它將播放功能集成到 DSH 的會話視圖標籤環中。

插件介紹¶

該插件由開發者 heshuren371 維護，是一個基於 Web 技術實現的本地音樂播放器。它在會話視圖的標籤頁中增加了一個“音樂”標籤，提供 macOS Music 風格的 UI，支持常見音頻格式，並具備元數據補全、均衡器等高級功能。

核心功能¶

插件通過遞歸掃描本地目錄來管理音樂庫，支持以下功能：

文件支持：支持 FLAC、MP3、M4A、AAC、OGG、Opus、WAV、MP4、MOV、WebM、MKV、AVI 等常見格式。
波形與進度：基於 FFmpeg 解碼音頻並提取峯值，顯示真實波形進度條。
均衡器：提供 10 段均衡器，內置原聲、流行、搖滾、古典、爵士、低音增強、人聲、電子等預設曲線。
播放控制：默認開啓 300ms/700ms 的交叉淡化切歌功能，支持單曲循環與列表循環。
元數據管理：支持在線補全元數據（QQ音樂、iTunes、網易雲、MusicBrainz），標籤寫入採用原子化操作，支持重命名文件。
ReplayGain：提供響度歸一化功能，優先讀取文件內嵌標籤，支持單曲/專輯模式。
系統集成：集成 MediaSession，支持鎖屏顯示與控制中心通知。
視頻支持：支持 MV 三檔判定（direct/remux/transcode），並調用 FFmpeg 進行緩存處理。

安裝與啓用¶

安裝前請確保系統已安裝 Node.js（^22.19.0 || >=24.0.0）和 pnpm，並已安裝 FFmpeg。

安裝插件：

    dsh plugin --profile web add github:heshuren371/dsh-music-player

檢查安裝：

    dsh plugin --profile web ls

啓用插件：
安裝後需重啓 dsh web 並刷新頁面，在會話頂部的標籤環中找到“音樂”標籤頁即可使用。

開發與調試¶

插件源碼基於 TypeScript 編寫，構建產物提交至倉庫。如需開發調試：

git clone https://github.com/heshuren371/dsh-music-player.git
cd dsh-music-player
pnpm install
cd .. && dsh plugin --profile web add link:./dsh-music-player
pnpm run dev

網絡調試：確認插件 API 通路正常：

curl -s -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:<端口>/dsh-music/api/session"

常見問題：
* Desktop 端限制：CLI 拒絕寫入文件，需通過應用菜單安裝，安裝後需重啓應用或按 F12 刷新。
* 標籤不顯示：確認 dsh plugin --profile web ls 中存在該插件，且頁面已刷新。

權限與依賴¶

插件運行需要以下權限和依賴：

權限：fs.read（讀取音樂）、fs.write（寫入標籤）、fs.delete（刪除文件）、net.fetch（在線補全元數據）、transport.api（API 交互）、storage.local（緩存）。
依賴：Node.js（^22.19.0 || >=24.0.0）、pnpm、FFmpeg（用於波形提取、MV 處理和元數據測量）。

注意事項¶

兼容性：插件支持 DSH >=0.1.6-alpha.1 <0.2.0 || >=0.2.0-0 <0.3.0-0（0.1.7-rc.2 兼容）。
功能限制：插件目前不支持隨機播放和歌詞頁。Apple FairPlay 加密的離線包（.movpkg）無法播放，掃描時會自動跳過。
文件安全：標籤寫入和重命名文件是原子操作，中途中斷不會損壞原文件。