前言¶
在 DeepSeek Harness（DSH）里長時間寫代碼、跑智能體時，很多人會希望有一套不離開界面的背景音樂。系統默認播放器會切到別的窗口，瀏覽器標籤頁裏的音頻又容易和 DSH 自身的語音播報、啓動動畫或其它插件搶控制權。社區插件 dsh-audio-player（維護者 edgewalker6666，分類：客戶端）針對的是另一類需求：在 DSH 進程內自建播放鏈路，用獨立懸浮窗管理曲庫，並在可選情況下與啓動動畫對齊起止。
下面介紹它的定位、能力與安裝用法；事實以 GitHub 倉庫 README 爲準。
這是什麼¶
dsh-audio-player 是一個 DSH 內的 MP3 音頻播放器：用戶自行導入音樂，在可調大小的獨立懸浮窗裏播放；若當前環境有啓動動畫（優先適配長征機啓動動畫 dsh-startup-secret，其次 dsh-theme-prts），可切換到「啓動動畫同步」模式，從 0:00 起播，動畫結束時漸隱並停止。
播放器使用自己的 HTMLAudioElement，不會暫停、靜音或改動 DSH、啓動動畫、語音播報以及其它插件的聲音。實現上 UI 放在 Shadow DOM，宿主只增加 #dsh-audio-player-host，不修改 DSH 的 React 樹；懸浮窗 z-index 低於啓動動畫層，啓動期間被動畫蓋住。
許可證爲 MIT（README）；當前 package 版本 1.0.0，要求 DSH 0.2.1-rc.3（web profile / 桌面端）、Node >= 20。
核心功能¶
曲庫與直接播放¶
- 導入 MP3：點「導入」多選文件，或把 MP3 拖進懸浮窗；文件會寫入 DSH 數據目錄，重啓後仍在。
- 曲庫：記錄標題、時長、大小；單擊選中、雙擊直接播放。
- 控制：播放 / 暫停、上一首 / 下一首、拖動進度、音量、靜音、循環。
- 懸浮窗：拖標題欄移動，拖右邊緣 / 下邊緣 / 右下角縮放；摺疊、隱藏爲右下角懸浮球；位置與尺寸會記住。
也可把 MP3 複製到數據目錄下的 tracks/，在播放器裏點「刷新」重建索引；失效條目會被清理。
啓動動畫同步¶
同步依據動畫的真實生命週期，而不是固定秒數：
| 啓動動畫 | 開始信號 | 結束信號 |
|---|---|---|
長征機（dsh-startup-secret，優先） |
#dsh-startup-root 移除 dsu-boot |
root 移除 / dsh-startup:done |
dsh-theme-prts |
html[data-prts-startup-active] 出現 |
屬性移除 / 覆蓋層移除 |
| 無啓動動畫 | 不會播放 | — |
音頻比動畫長時，只保留與動畫時長相同的最前段；比動畫短時放完即止。結束漸隱可在 0–3 秒 調節，默認 1.2 秒。若本次會話動畫被跳過（例如已播過），啓動音頻不會擅自播放。
瀏覽器 / Electron 的自動播放策略可能要求一次用戶點擊後纔出聲；若啓動音頻被攔截，播放器會等待頁面上第一次點擊，再把音頻對齊到動畫當前進度。
持久化與 API¶
音樂、曲庫、音量、模式、窗口狀態保存在 %USERPROFILE%\.dsh\dsh-audio-player\（曲庫 library.json，設置 config.json）。宿主路由包括 /dsh-audio-player/app.js、/api/state、/api/config、/api/tracks、/api/media/<id>（支持 HTTP Range）。自定義路由經 DSH connection 的信任柵欄，未認證請求返回 401。
MP3 要求標準 MPEG 音頻（ID3v2 或幀同步頭均可），單文件 <= 200 MB。
安裝與啓用¶
插件以當前 DSH 進程權限運行；安裝前建議瀏覽源碼與 MIT 許可證，確認符合你的環境策略。
從 GitHub 安裝（Web profile）¶
在資料給出的命令如下。安裝後需重啓 dsh web 並刷新頁面。
dsh plugin --profile web add github:edgewalker6666/dsh-audio-player
本地腳本安裝（桌面端推薦）¶
在插件目錄執行（README 示例爲 desktop profile）：
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Profile desktop
腳本會建立 profile 下 node_modules\dsh-audio-player 目錄聯接、向 cordis.patch.yml 或 dsh.profile.bundles 登記，並在 profile 的 package.json 中登記本地依賴。完成後退出並重新打開 DSH（桌面端僅刷新頁面不會加載新的 index 注入表）；Web 端同樣需重啓 dsh web 後刷新。
手動步驟見倉庫 INSTALL.md。
典型用法¶
- 打開播放器，點「導入」選 MP3，或拖文件進懸浮窗。
- 在「曲庫」選中曲目；雙擊可直接播放。
- 頂部模式在 直接播放 / 啓動動畫 間切換，或在「設置」裏切換。
- 設置可調：直接播放音量、啓動動畫音量、結束漸隱、循環、重置窗口、打開音頻文件夾、複製路徑。
- 用標題欄移動窗口，用邊緣與右下角縮放；
–摺疊，×收成懸浮球。
適用場景與注意¶
適合：希望在 DSH 內常駐 BGM、且不想幹擾其它插件音頻的開發者；使用長征機或 PRTS 主題啓動動畫、希望開屏與音樂對齊的用戶。
注意：
- 兼容性以 README 爲準：Chromium 系（Electron / Edge / Chrome），需
HTMLAudioElement與 Shadow DOM。 - 卸載可用
uninstall.ps1 -Profile desktop，只移除安裝登記與node_modules聯接，不會刪除~/.dsh/dsh-audio-player/裏的音頻與設置。 - 若重啓後無懸浮窗，檢查 profile 的
node_modules、桌面端cordis.patch.yml中- id: dsh-audio-player，避免 bundle 與 patch 重複登記；導入報 415 多爲非有效 MP3。
DSH 生態強調「一切皆插件」；SkillHub 目錄頁 爲社區索引，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-audio-player 把 MP3 播放、曲庫與可選啓動動畫同步收進 DSH 內部，音頻鏈路與其它插件隔離。需要安裝命令、數據路徑與排查表時，以倉庫 README 爲準。
