前言¶
在 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
