dsh-music 🎧

DeepSeek Harness（DSH） 的音乐播放器卡片插件：模型在回复里输出一个 dsh-music 围栏，对话流里就地渲染一张可交互的播放器卡片——网易云 / QQ 音乐双后端、玻璃拟态悬浮歌词、节拍气泡特效、多主题。

采用与 dsh-genui 相同的部署形态：Node 宿主半区（教模型围栏语法 + 注册 music skill + 提供搜索/直链/歌词代理路由）+ 浏览器半区（DOM channel 观察 ```dsh-music 围栏并挂载卡片，零 React 依赖）。不装插件的会话永远不发围栏，一切如常。

功能

• 双后端：网易云（搜索 / 播放直链 / 歌词 / 翻译歌词）、QQ 音乐（搜索 / 歌词 / 封面）
  • 网易云免费歌曲可直接播放（默认请求 320kbps）
  • QQ 音乐免登录环境多数歌曲拿不到直链（腾讯要求请求签名）——卡片会自动跨后端到网易云找同名同歌手曲目播放，并在状态栏注明；两个后端都失败时标"不可播"并自动跳下一曲
• 主题：glass 玻璃拟态（封面氛围光 + 毛玻璃）｜ neon 霓虹发光｜ paper 纸感｜ vapor 蒸汽波，以及自定义主题对象（accent / bg / text / radius / bubbles / coverBlur）
• 歌词：bubble 悬浮玻璃歌词气泡（当前句 + 下一句，随播放浮动换行）｜ bar 内嵌三行滚动歌词栏（带翻译）｜ none
• 气泡特效：播放中气泡随节拍从唱片边缘升起（WebAudio 实时频谱驱动；跨域媒体频谱不可用时自动降级为模拟节拍）、点击卡片任意处气泡迸发、唱片随播放旋转 + 节拍脉冲；遵循 prefers-reduced-motion
• 播放器：搜索、播放队列（插播 / 追加）、循环 / 单曲 / 随机、音量、进度拖拽、本地喜欢收藏、电台模式（播完自动搜相似歌加队）、系统 MediaSession（锁屏 / 媒体键控制）、状态持久化（刷新恢复队列与偏好，直链过期自动重新解析）
• AI 推荐：状态栏「AI 推荐」按钮把当前曲目通过会话回传给模型，模型回复一个新的 dsh-music 围栏（需要宿主提供 sessions 服务，否则按钮不出现）

安装

# 本地开发（链接安装）
dsh plugin --profile web add link:/path/to/dsh-music

# 已发布到 npm 后
dsh plugin --profile web add dsh-music

装完重启 DSH web 界面即可。零运行时依赖，Node ≥ 20。

使用

对模型说：

• 「放一首周杰伦的晴天」→ 玻璃卡片 + 悬浮歌词，自动搜索解析播放
• 「来点深夜 lo-fi，蒸汽波主题」→ {"theme":"vapor","keyword":"深夜 lo-fi"}
• 「建一个粤语经典歌单，纸感主题，歌词用内嵌模式」→ playlist 围栏 + lyricMode:"bar"
• 「自定义主题，粉色强调色」→ {"theme":{"accent":"#f9a8d4","bg":"#3b0764"}}

围栏示例（模型自动生成，也可手写测试）：

{"theme":"glass","backend":"netease","keyword":"周杰伦 晴天","autoplay":true,"lyricMode":"bubble"}

{"title":"深夜电台","theme":{"accent":"#f0abfc","bg":"#2b1055"},"playlist":[
  {"title":"晴天","artist":"周杰伦"},
  {"title":"Lemon","artist":"米津玄師"}
]}

完整字段规范见 SKILL.md。

可选配置（环境变量）

变量	作用
DSH_MUSIC_NETEASE_COOKIE	网易云 Cookie：提高 VIP 歌曲/高码率直链成功率（默认 appver=2.9.7 匿名）
DSH_MUSIC_QQ_COOKIE	QQ 音乐 Cookie：填用户自己的 Cookie 后，QQ 侧免费歌曲有机会直接拿到直链

所有音乐请求经宿主 Node 侧代理（同源 /plugins/dsh-music/api/*），浏览器无跨域问题；插件不收集任何凭据，Cookie 仅随请求发往对应音乐站点。

本地预览（不需要 DSH）

node dev/gen-fixture.mjs   # 生成测试音频/封面/歌词 fixtures
node dev/server.mjs        # http://127.0.0.1:4531/preview.html?spec=glass

?spec=glass|neon|paper|vapor|custom 切主题；搜索词带 demo 前缀走本地 fixtures（确定性预览），否则走真实音乐接口（失败自动兜底 fixtures）。

架构

index.js               宿主半区：systemPrompt 区段 + music skill + /plugins/dsh-music/api 路由
src/backends/*.mjs     网易云 / QQ 音乐公开接口适配（搜索 / 直链 / 歌词）
client.js              浏览器半区：DOM channel 围栏渲染器 + 播放器卡片 + 主题 + 气泡粒子引擎
SKILL.md               music skill：围栏字段规范与模型行为准则
cordis.patch.yml       bundle 插入声明（dsh plugin add 时并入 profile）
dev/                   预览服务器与 fixtures

关键机制：

• 围栏 → 卡片：MutationObserver 观察会话 DOM，发现 language-dsh-music 代码块（或 label+pre 结构兜底）且 JSON 解析完整后，把围栏表面替换为卡片；流式阶段先显示"装载中"骨架，15 秒未完成自动还原代码块；宿主重渲染后自动重挂载，播放不中断（音频为全局单例）。
• LOCAL-FIRST：搜索 / 切歌 / 换主题全部在卡片内经插件自身 HTTP 路由完成，零模型往返；只有「AI 推荐」会向会话回传一条 [music-action] 消息。
• 多卡片共享：同一会话多张卡片是同一播放状态的控制器（对齐 dsh-genui panel-store 模型）。

已知边界

• QQ 音乐免登录直链受腾讯签名限制，仅搜索 / 歌词 / 封面保证可用（插件会自动降级到网易云播放）。
• 网易云 VIP / 下架歌曲无直链，同样走跨后端降级或标"不可播"。
• 浏览器自动播放策略：首次 autoplay 可能需要用户点一次播放按钮（卡片会提示）。
• 仅供个人学习使用，音乐版权归各平台所有。