dsh-plugin-music

DSH Music — 内嵌 DeepSeek Harness 的独立音乐播放器插件。UI 按 AlgerMusicPlayer 5.1(MIT)做 1:1 复刻,去掉原品牌后作为 DSH 原生插件运行;不依赖本机安装任何播放器。

• 宿主侧(Node/cordis):网易云音乐数据层(netease-cloud-music-api-alger)+ 本地 webserver 路由(数据 API + 音频流代理 + 下载落盘)
• 客户端(React,DSH 主区域整页):发现 / 歌单广场 / 排行榜 / 新碟上架 / 搜索 / 歌单详情 / 专辑 / 歌手 / 最近播放 / 我的音乐 / 设置,底部常驻播放条
• 播放器:队列、列表循环 / 单曲循环 / 随机、音量悬浮滑块、倍速、收藏、下载、播放历史、沉浸式歌词页、右键菜单、键盘快捷键
• 附加:聊天内可直接调用的 4 个工具(music_search / music_song_url / music_lyric / music_playlist_tracks)

歌单详情	播放列表

沉浸式歌词	歌单广场

安装

手动(推荐,当前未发布 npm)

编辑 ~/.dsh/profiles/desktop/package.json:

"dependencies": {
  "dsh-plugin-music": "file:C:/path/to/dsh-my-music"
},
"dsh": {
  "profile": {
    "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-plugin-music"]
  }
}

然后在该目录 pnpm install,重启 DSH;左侧图标栏会出现「音乐」。

发布后

dsh plugin --profile desktop add dsh-plugin-music

配置(~/.dsh/profiles/desktop/cordis.patch.yml)

- id: music
  config:
    cookie: 'MUSIC_U=xxxxxxxx'   # 可选兜底;界面扫码登录/退出后不再起作用
    requestTimeoutMs: 15000
    defaultLevel: standard       # 音频代理默认音质
    downloadDir: 'C:/Users/you/Music/DSH'  # 客户端下载目录,必须是绝对路径;留空用 ~/Music/DSH

功能

发现

• 每日推荐大卡(封面取色背景 + 前三首预览 + 一键播放)
• 登录后右侧为「私人 FM」卡(播放/暂停、换一首),未登录为热门歌单 2×2 封面墙
• 推荐歌单(悬停显示前三首曲目与播放按钮)、热门歌手横向滚动、新碟上架、新歌速递

歌单 / 排行榜 / 新碟

• 歌单广场按分类浏览(分类横向滚动),滚动到底自动加载下一页
• 排行榜 / 新碟上架按地区切换,卡片悬停显示播放量与更新频率

详情页

• 歌单:模糊封面背景 + 大封面 + 创建者/曲目数/播放量/总时长/简介;播放全部、随机播放
• 专辑:发行时间、唱片公司、简介、曲目表
• 歌手:圆形头像、简介、热门 50 首、专辑网格

播放器

• 播放条:顶部进度条(可点按/拖动,悬停显示时间)、封面悬停展开详情、歌名/歌手、上一首/播放/下一首、音量悬浮竖滑条(支持滚轮)、播放模式、收藏、下载、播放列表
• 播放列表抽屉:350px 右侧浮层,当前曲目高亮、单曲移除、清空确认
• 沉浸式播放页:封面模糊背景、大封面、迷你控制条、逐行歌词(当前行高亮、点击跳转、翻译开关、字号)
• 右键菜单:播放、下一首播放、收藏、查看专辑/歌手、下载
• 快捷键:空格播放/暂停、←/→ ±5 秒、↑/↓ 音量、Esc 关闭浮层(输入框内不拦截)
• 收藏与播放历史本地持久化;登录后收藏会顺带同步到网易云「我喜欢的音乐」

搜索

• 热搜榜(前三条高亮)、搜索历史、输入联想
• 单曲 / 歌单 / 专辑 / 歌手四类结果;单曲支持播放全部

账号

• 设置 → 账号 → 扫码登录(等待扫码 → 已扫码待确认 → 自动刷新)
• 二维码由宿主按网易云授权链接实时绘制;登录态写入 ~/.dsh/music-cookie.json,无需重启即对全部接口与音频代理生效
• 未登录可播标准音质/试听;VIP 歌曲需要登录会员账号

下载

播放条、歌曲行悬停区、右键菜单都有下载入口,走宿主 /music/api/download:按当前音质解析直链后由 Node 落盘,先写 .part 再改名;文件名中的 / \ * ? " < > | 与 .. 一律清洗,写入不会逃出 downloadDir。未登录或非会员时 VIP 曲目只能拿到试听片段,文件名会带 (试听) 后缀,下载完成的提示里也会标注。

落盘目录默认 ~/Music/DSH(可用插件配置 downloadDir 改成任意绝对路径)。下载完成的提示条带「打开目录」按钮,点击即在系统文件管理器里定位到刚下好的文件;设置 → 存储 里可以看到完整路径、最近下载的文件列表,并支持逐个「定位」:

开发

npm install
npm run build   # esbuild 打包 src/client.jsx → lib/client.js(ModuleLoader 工厂格式,CSS 内联)
npm test        # 冒烟:工具 + 全部 /music/api/* + 音频流 Range + 下载落盘 + 扫码登录状态机(真实网络)

本地视觉校验

design/render-test/ 内置一套 mock 宿主 API 的渲染页,可以脱离 DSH 直接看各个页面(截图在 design/shots/):

npm run preview:build
cd design/render-test && python -m http.server 8391
# 打开 http://127.0.0.1:8391/preview.html?scene=home

scene 可选:home / list / toplist / search / search-result / playlist / album / artist / user / settings / queue / full / context / queue-next / fav;加 &guest=1 可看未登录首页。queue-next 会演示「下一首播放」后的队列顺序,fav 会弹出「取消全部收藏」确认框。

队列与播放模式的逻辑抽在 src/ui/queue.js(纯函数,不依赖 React/DOM),由冒烟测试直接覆盖:insertNext(下一首播放的插位)、nextIndex(列表/单曲/随机)、prevIndex、shuffled。抽出来的原因是这些下标运算很容易在重构中悄悄改错,而纯函数可以被 Node 直接断言。

三条已被冒烟测试守住的约束

• src/ui 里只能用静态 import 引入本地模块。构建参数 minifyIdentifiers: false 下,esbuild 会把动态引入的解构变量编译成未改名的自由引用,运行期 ReferenceError 又被 .catch 吞掉,现象是「歌词永远空白」。
• 歌词取经典 lyric 接口(带 _nmclfl)而不是 lyric_new:后者把头部若干行返回成 JSON 富文本,纯音乐/逐字歌词缺失时反而整段丢行。
• 进度条(SeekBar)的交互层必须是铺满的透明原生 <input type="range">,只通过 onChange 取值。DSH 宿主会在 document/window 上挂指针监听(输入模态、点击外部关闭浮层),任何自定义 pointer 逻辑在宿主里都不可靠;原生 range 由浏览器内建控件处理点按/拖动,实测在宿主的 document 捕获阶段 stopPropagation 之下依然生效。

桌面端调试提示

DSH 的插件客户端 bundle 由 dsh-client-modules 提供,URL 按文件的 mtime/ctime/size 生成 rev,响应头是 cache-control: public, max-age=31536000, immutable。也就是改了 lib/client.js 之后,只在页面里切换/刷新不一定能拿到新包,请完全退出 DeepSeek Harness(托盘 → 退出)再重开。判断是否加载了新包:把鼠标悬停到播放条进度条上,提示文字带当前版本号(如 v1.0.3),或看 设置 → 关于 的版本号。

架构

DSH 桌面端
├─ 宿主插件 lib/index.js
│   ├─ /music/api/*        数据接口(见下)
│   ├─ /music/stream/:id   音频流代理(Range 透传,<audio> 直接指向此处)
│   └─ 4 个 agent 工具
└─ 客户端 lib/client.js(React,slots: main + sidebar.panellist)
    └─ 与宿主同源通信(无需 CORS),音频走本地代理解决混合内容

宿主接口一览:

路由	说明
/api/home	首页聚合(每日推荐 / 推荐歌单 / 热门歌手 / 新碟 / 新歌),单个板块失败不影响整页
/api/playlists、/api/playlists/categories	歌单广场分类与分页
/api/playlist/detail、/api/playlist/tracks	歌单详情与全部曲目
/api/toplists、/api/toplist/tracks	榜单列表与曲目
/api/album/new、/api/album/detail	新碟与专辑详情
/api/artist/top、/api/artist/detail、/api/artist/albums	歌手
/api/search、/api/search/hot、/api/search/suggest	搜索(结构化字段 + 旧版 detail 摘要)
/api/song/detail、/api/song/urls、/api/lyric	曲目元数据、直链、歌词
/api/personal/fm、/api/user/playlists、/api/like	私人 FM、我的歌单、喜欢
/api/download	下载落盘
/api/download/info	下载目录与最近落盘的音频文件(供设置页「存储」展示)
/api/download/open	在系统文件管理器里打开下载目录;带 name 时精确选中该文件(越界路径退化为打开目录)
/api/account、/api/login/qr/*、/api/logout	账号与扫码登录

数据层对网易云接口的网络类错误(TLS 断连 / 5xx)会重试两次,避免个别板块偶发空白。

免责声明

UI 结构复刻自 AlgerMusicPlayer(MIT,感谢原作者 algerkong);数据依赖社区维护的第三方接口库,仅供个人学习研究。音乐内容版权归网易云及版权方所有,请遵守当地法律,勿用于商业用途。不包含任何音源解锁组件。

License

MIT