前言¶
在 DSH 裏寫代碼或跟模型對話時，背景往往開着網易雲桌面客戶端。系統托盤能切歌，但界面裏看不到歌名和歌詞；想讓模型幫忙暫停或調音量，又沒有現成的橋。瀏覽器裏另開一個網頁播放器則意味着重複登錄、重複佔資源。
dsh-cloudmusic-player（維護者 jx70，GitHub 倉庫 jx70/dsh-cloudmusic-player）是在 DeepSeek Harness 右下角掛的一塊懸浮小卡片：控制的是你本機已經在跑的那個網易雲客戶端，不另起播放器、不要求在插件裏登錄。裝好之後，界面能切歌、拖音量、滾歌詞（含外語歌譯文），模型還多一個 cloudmusic_player 工具。下面介紹它做什麼、怎麼裝、怎麼用，以及 Windows 上的前提與限制。
它是什麼¶
一塊浮在 DSH 界面右下角的小卡片；點開是迷你播放器。數據來源是當前正在播放的曲目與進度，不是獨立音源。
| 能力 | 說明 |
|---|---|
| 換歌 / 播放暫停 | 上一首、下一首、播放暫停 |
| 音量 | APP 只改網易雲進程音量；SYS 改系統總音量，兩路讀數獨立 |
| 滾動歌詞 | 當前行居中高亮，進度連續插值 |
| 外語歌譯文 | 原文下多一行中文，來自客戶端同源翻譯 |
| 拖動 / 收起 | 位置記在 localStorage；可收成只顯示歌名的小膠囊 |
| 給模型用 | 工具名 cloudmusic_player，可暫停、切歌、調音量、讀歌詞 |
做不到的事（README 明確列出）：不能拖動進度條 seek（native 車道無此通道）、不能搜索歌曲、不能改播放列表。
進度在 Windows 上主要靠讀客戶端寫入的 %LOCALAPPDATA%\NetEase\CloudMusic\cloudmusic.elog 並解碼狀態機；若客戶端註冊了系統媒體會話（SMTC），則優先走 SMTC（且 SMTC 下可 seek）。插件不讀取、不落盤日誌裏的 musicurl，也不碰 cookie。
環境與要求¶
| 項 | 要求 |
|---|---|
| 系統 | Windows 10 1809+ 纔有完整播放控制後端 |
| PowerShell | 5.1（powershell.exe）；README 寫明 PowerShell 7 無 WinRT 投影，播放控制會不可用 |
| 客戶端 | 網易雲音樂桌面版 |
| DSH | ≥ 0.1.0-rc.6；Node ≥ 22 |
| 形態 | Web / CLI / 桌面版（dsh-desktop）均可裝 UI；macOS / Linux 可裝懸浮框與歌詞，播放控制與音量顯示「本機不支持」 |
插件以當前 DSH 進程權限運行。安裝前建議在 GitHub 查看源碼與 MIT 許可證，再決定是否加入你的 profile。
安裝與啓用¶
Web / CLI¶
dsh plugin --profile web add dsh-cloudmusic-player
執行後重開 DSH。右下角會出現小膠囊，點 ⌃ 展開播放器。
dsh 桌面版¶
dsh plugin --profile desktop add dsh-cloudmusic-player
node scripts/enable-desktop.mjs # 把包接進桌面 profile（冪等）
桌面版每次啓動會重寫 profiles/desktop/package.json，因此需要 scripts/enable-desktop.mjs 建 junction 並向 ~/.dsh/cordis.patch.yml 追加帶條件的 patch，避免與 web profile 搶同一路由。僅檢查或卸載可用：
node scripts/enable-desktop.mjs --check
node scripts/enable-desktop.mjs --remove
經上面的步驟，發行版插件文件會落在 ~/.dsh/profiles/<profile>/node_modules/；改發行版需重新 add 新版本。本地 link: 開發則改代碼後重載插件即可。
典型用法¶
- 拖動：按住卡片頂部空白或收起態膠囊拖到任意位置。
- 收起：右上角 ⌃，再點一次展開。
- 音量：拖滑塊；
APP/SYS切換作用域。鬆手後 110 ms 內的連續拖動會合併爲一次請求。 - 歌詞：有
songId時直取；否則按歌名、歌手、時長搜索。署名行（作詞/作曲等）更淡顯示且不參與高亮。外文歌默認疊譯文；在配置裏設lyricsTranslation: false可關閉。 - 進度條：native 車道只展示，不能拖 seek；SMTC 車道可 seek。
- 歌詞對不上：點當前那一行，用該行 LRC 時間戳作兜底錨點（日誌讀不到時）。
排錯時 README 建議先看自檢端點（權威）：
http://127.0.0.1:3080/api/cloudmusic-player/health?deep=1
桌面版改用其隨機端口。常見現象如「沒在放歌」先確認客戶端是否在播、processName 是否匹配；切歌無反應常是 hotkeyNext / hotkeyPrev 與客戶端「設置 → 快捷鍵」不一致。
配置¶
在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中可覆蓋插件項，例如：
- insert:
- id: cloudmusic-player
name: dsh-cloudmusic-player
config:
processName: cloudmusic
aumidPattern: 'cloudmusic|netease|wangyi'
volumeScope: process
lyricsEnabled: true
lyricsTranslation: true
lyricsOffsetMs: 0
powershellPath: powershell.exe
hotkeyPlayPause: 'Ctrl+Alt+P'
hotkeyNext: 'Ctrl+Alt+Right'
hotkeyPrev: 'Ctrl+Alt+Left'
elogEnabled: true
elogPath: ''
elogPollMs: 400
其中 volumeScope、lyricsEnabled、lyricsTranslation 等標爲 volatile 的項改完即時生效，無需重載插件。更多字段見倉庫內 docs/DESIGN.md 配置全表。
適用場景與注意¶
適合：主要在 Windows 上用 DSH（寫代碼、CLI 或桌面版），同時習慣網易雲桌面客戶端放歌，希望在同一界面看歌詞、調音量，或讓模型通過 cloudmusic_player 代操作 playback 的用戶。
注意：
- 只控制「已經在放的那首」，不登錄、不搜索、不建歌單。
- 進度依賴客戶端 elog；讀不到時會降級爲本地計時與點歌詞校準，起點可能有滯後。
- 播放暫停通過模擬全局熱鍵，需與客戶端快捷鍵一致；極靜段落偶發誤判 README 有說明。
- 歌詞與譯文走網易雲 web 接口，可能限流或字段變更；插件不補譯。
- DSH 社區目錄（如 SkillHub 條目）是獨立生態站點，與 DeepSeek / 幻方無官方從屬關係；插件亦非官方應用商店內建應用。
當前 npm 包版本爲 0.2.0（見倉庫 package.json）。
結尾¶
dsh-cloudmusic-player 把「本機網易雲」接到 DSH 懸浮 UI 與模型工具上：不重複開播放器，在 Windows 上通過 elog / SMTC 與 PowerShell 後端拿到真進度與控制。若你的日常是 DSH + 網易雲桌面版，可先按 profile 執行官方 dsh plugin add，桌面版別忘了 enable-desktop.mjs，再用 health?deep=1 確認鏈路。
- 目錄頁：https://www.skillhub.cn/plugins/jx70/dsh-cloudmusic-player
- 源碼與文檔：https://github.com/jx70/dsh-cloudmusic-player
