在 DeepSeek Harness (DSH) 的 TUI 插件生態中，與第三方應用集成是常見需求。當用戶在 dsh-TUI 中運行 YesPlayMusic TUI 時，需要一種方式在不打斷當前終端流的情況下查看播放狀態和控制播放。dsh-music-tui 插件通過命令接口和狀態欄集成，解決了這一問題。
該插件爲 dsh-TUI 提供了對 YesPlayMusic TUI 的控制能力與正在播放狀態展示。它通過 /music 命令與頂部的音樂條組件工作，不修改 DeepSeek Harness、dsh-TUI 或 YesPlayMusic 本體源碼。
核心功能¶
插件主要包含以下能力：
- 命令控制：提供
/music命令族，用於顯示/隱藏音樂條、查看狀態、切換播放/暫停、切歌及跳轉進度。 - 音樂條顯示：在提示框上方展示小封面、曲名、歌手、實時進度、實時頻譜以及控制按鈕（上一首/播放暫停/下一首/關閉）。
- Kitty Graphics 支持：在支持 Kitty graphics 的終端中，封面會顯示爲平滑的真圖。
- 頻譜樣式：內置
blocks、led、braille、shade四種緊湊樣式，且可跟隨 YPM 的設置。 - 富狀態視圖降級：在舊版宿主或窄屏環境下，自動降級爲一次性顯示詳情，保留核心控制功能。
前置條件¶
在安裝前，請確保環境滿足以下要求：
- Node.js：
^22.19 || >=24 - dsh-TUI：版本需在
>=0.9.2 <0.11.0之間 - YesPlayMusic TUI 及 ypm CLI：插件通過公開的 CLI 進行控制，實時頻譜需要此版本支持
安裝與啓用¶
當前版本爲 v0.1.0。通過以下命令克隆倉庫並安裝：
git clone --branch v0.1.0 --depth 1 https://github.com/Nagi-ovo/dsh-music-tui.git && cd dsh-music-tui && pnpm install --frozen-lockfile && pnpm build && dsh plugin --profile dsh-tui add "$PWD"
安裝後，插件會加載配置。音樂條默認隱藏，需通過命令喚出。
典型用法¶
使用 /music 命令進行交互：
/music show：打開音樂條/music hide：關閉音樂條/music status：一次性顯示曲名、歌手、專輯與進度詳情/music toggle：切換播放/暫停/music next：播放下一首/music prev：播放上一首/music seek <秒>：跳到歌曲的絕對時間（例如/music seek 90.5）
在 fullscreen 模式下，進度條支持點擊定位與拖動預覽；inline 模式則需使用 seek 命令。
配置¶
默認配置寫入 cordis.patch.yml，主要項如下：
| 鍵 | 默認值 | 說明 |
|---|---|---|
executable |
ypm |
CLI 名稱或絕對路徑 |
showStatus |
true |
是否啓用音樂條；設爲 false 時僅保留命令功能 |
pollIntervalMs |
3000 |
在線輪詢狀態間隔 |
timeoutMs |
3000 |
單次 CLI 調用超時 |
spectrumStyle |
follow |
頻譜樣式：off / follow / blocks / led / braille / shade |
如需覆蓋配置，可在 profile 的 cordis.patch.yml 中按同一 id 寫入完整配置。
注意事項¶
- 依賴運行：插件不會自動啓動 YesPlayMusic TUI。必須先在後臺或另一個終端啓動 ypm，再啓動 DSH。
- 權限邊界：插件僅調用公開的
ypmCLI，不直連私有 Unix Socket，也不修改宿主或目標應用的源碼。 - 安全與信任：插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證（MIT）。
- 狀態同步：控制結果僅返回“已發送”，不自動確認播放完成，需通過重新讀取狀態確認最終結果。
