dsh-music

Readme

# dsh-music 🎧

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

采用与 [dsh-genui](https://github.com/omdsh-dev/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 服务，否则按钮不出现）

## 安装

```bash
# 本地开发（链接安装）
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"}}`

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

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

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

完整字段规范见 [SKILL.md](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）

```bash
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` 可能需要用户点一次播放按钮（卡片会提示）。
- 仅供个人学习使用，音乐版权归各平台所有。