dsh-blue-sea-player

Readme

# 蓝海之约播放器（dsh-blue-sea-player）

DeepSeek Harness（DSH）Web 界面里**常驻的鲸鱼娘音乐播放器**挂件：打开 DSH 页面自动出现，
可随意拖动，左侧 CD 机 + 右侧「主体 + 播放列表」连成一块，支持皮肤背景、资产管理、
收纳 & 小球隐藏模式与三种播放模式。

> **鲸鱼娘形象来源 bilibili @上善无形 @ZipZipPipe（署名保留，勿删除）**
> 完整署名链与许可见 **[NOTICE](NOTICE)**（CC BY-NC-SA 4.0，禁止商用）。
> 插件制作：爱与诗歌剧；默认音乐为 AI 音乐，来源于 bilibili @爱与诗歌剧。

## 效果图

| 展开状态 | 收纳状态 |
|---|---|
| ![预展开](preview/expanded.png) | ![预收纳](preview/collapsed.png) |

| 小球隐藏模式 | 设置 · 皮肤管理 | 设置 · 资产管理 |
|---|---|---|
| ![预小球](preview/ball.png) | ![预皮肤](preview/skins.png) | ![预资产](preview/assets.png) |

## 特性

- 🐋 **自动常驻**：每次打开 DSH Web 页面自动出现（tapIndex 注入，无需手动开启）
- 🖱️ **可随意拖动**：位置记忆（localStorage）
- 💿 **CD 机**：播放哪首就转哪首的圆形 CD 封面（封面自动 1:1 裁剪 + 中心蓝色音符标签，固定不随盘转）；CD 下方**居中滚动歌名**（过长自动走马灯）+ **白色 9 节律动线**（每节节奏独立不同步）
- 🎚️ **主体**：歌名 + **5 节律动线**（不同步）+ **模式按钮**（单=单曲循环 / 顺=列表循环 / 随=随机），进度条支持**按住拖动**，音量滑杆，上一首/播放/下一首
- 📜 **播放列表**：点击播放、当前曲目金色高亮、播放中自动读取时长
- 🗂️ **右上角三键**：隐藏（直接收成小球）/ 收纳·展开 / ⚙ 设置
- 🧲 **收纳**：只留 LOGO 高度的条带（隐藏 CD 与列表，露出皮肤顶部画面）；**靠左右边缘自动收成鲸鱼娘头像小球**，小球可拖动（位置记忆），点击还原到小球位置
- ⚙️ **设置**：
  - **资产管理**：新增（封面图片 → 音乐文件 → 名字，选歌自动填名；封面 canvas 现场处理成圆形 CD 图）/ 批量删除 / 卡片「管理」菜单（修改 / 删除二次确认）
  - **皮肤管理**：12 套皮肤一键切换（鲸鸣岛 / 无微不至 / 闪耀女仆长 / 晨光携游 / 最后的誓约 / 携手前行 + 笔记女仆版：初见 / 提议 / 学习 / 新发现 / 逛街 / 宴会）；**皮肤轮播**：多选皮肤 → 设置间隔（分钟）→ 自动轮播，随时停止，配置记忆

## 默认内容

- **12 套皮肤**：`assets/skins/*.webp`（直接替换同名文件即可换肤；新增需同步 `assets/skins.json` 与 `lib/index.js` 的 `SKIN_NAMES`）
- **5 首默认歌曲**：随包分发（`assets/music/*.mp3` + `assets/default-covers/*.webp`），首次启动自动播种入资产库：
  - Promise of the Blue Ocean（蓝海之约）/ Clumsy Maid（冒失女仆）/ Moon of the Sea, Stardust（海月·星辰）/ Versatile Head Maid（全能女仆长）/ Longing of the Sea（海之思）

## 安装

```powershell
dsh plugin --profile web add link:<本目录绝对路径>
```

重启 `dsh web`，刷新页面即出现播放器（新增插件包需重启；皮肤名、歌曲、客户端脚本的修改刷新即生效）。

## 使用

1. **播放**：点击列表任意一首；播放中 CD 旋转、律动线舞动、右上角模式按钮切换播放模式
2. **拖动**：按住面板空白处（按钮/列表/滑杆除外）拖动
3. **收纳 / 隐藏**：右上角「收纳」收成条带；「隐藏」直接收成小球；收纳后拖到左右边缘也会自动成球；球可拖、点击展开
4. **新增歌曲**：⚙ 设置 → 资产管理 → ＋新增 → 选封面图（可选）→ 选音乐（mp3/wav/ogg/m4a，自动填名）→ 保存
5. **换皮肤**：⚙ 设置 → 皮肤管理 → 点选任意一套（立即生效并记忆）

## 宿主路由

| 路由 | 说明 |
|---|---|
| `GET /dsh-player/player.js` | 客户端脚本（每次读盘，改完刷新生效） |
| `GET /dsh-player/skins.json` | 皮肤清单 |
| `GET /dsh-player/bg/<skin>.webp` | 播放器底图（白名单皮肤） |
| `GET /dsh-player/ball.png` | 收纳小球底图（鲸鱼娘头像） |
| `GET /dsh-player/assets.json` | 资产（歌曲）列表 |
| `POST /dsh-player/assets` · `POST /dsh-player/assets/batch` | 新增 / 批量删除 |
| `PUT /dsh-player/asset/<id>` · `DELETE /dsh-player/asset/<id>` | 修改 / 删除单曲 |
| `GET /dsh-player/cover/<id>.<ext>` | CD 封面（512×512 圆形） |
| `GET /dsh-player/media/<id>.<ext>` | 上传的音频（支持 Range 分段，进度拖动顺畅） |
| `GET /dsh-player/track/<file>` | 包内默认音频（支持 Range） |
| `tapIndex` | 自动注入 `<script defer src="/dsh-player/player.js">` |

用户数据（您的歌曲资产）保存在 `<DSH_HOME>/dsh-blue-sea-player/`（assets.json + covers/ + audio/）。

## 版权与署名

- **鲸鱼娘形象**：一创 上善（[Pixiv](https://www.pixiv.net/users/62155430) · [Bilibili 上善无形](https://b23.tv/8h5L4xz)）→ 二创 zipzip/ZipZipPipe（[Pixiv](https://www.pixiv.net/users/18604994) · [Bilibili](https://b23.tv/Pnw6nG8)）——详见 **NOTICE**
- **许可**：素材为衍生创作，**CC BY-NC-SA 4.0（禁止商用，须保留完整署名链）**；插件代码 **MIT**（见 LICENSE）
- **插件制作**：爱与诗歌剧；**默认音乐**：AI 音乐，来源于 bilibili @爱与诗歌剧

## 目录结构

```text
dsh-blue-sea-player/
├── package.json          # DSH bundle 插件元数据
├── cordis.patch.yml      # 挂载声明
├── lib/index.js          # 宿主侧插件本体（路由 / 资产库 / 音频分段）
├── assets/
│   ├── player.js         # 客户端脚本（每次读盘）
│   ├── skins/            # 12 套皮肤底图
│   ├── skins.json        # 皮肤清单
│   ├── ball.png          # 收纳小球头像
│   ├── music/            # 默认 5 首歌曲
│   └── default-covers/   # 默认歌曲封面（圆形 CD 图）
├── preview/              # 效果图（README 展示用）
├── scripts/preview.mjs   # 效果图生成器（node scripts/preview.mjs <探针地址>）
├── NOTICE                # 形象署名链与许可
├── LICENSE               # MIT
└── README.md
```

## 常见问题

- **播放器不出现**：确认 bundle 已入 profile（`dsh --profile web --dump-config` 可见 `dsh-blue-sea-player`）并重启过 dsh web
- **进度条拖动会被重置**：确认运行的是本版本（音频路由支持 Range；旧版本需重启）
- **音乐文件提示格式不支持**：已支持 BOM 容忍 + MIME 兜底；确认文件为 mp3/wav/ogg/m4a
- **卡片封面有旧白圆**：封面 v1 遗留样式，管理 → 修改 → 重新选图保存一次即可

## License

MIT（插件代码）；素材署名链与许可见 NOTICE。