单身汉（DSH）播放器

运行在 DeepSeek Harness（dsh）内的 AI 原生插件化音乐播放器。
聚合网易云 / QQ 音乐、逐字卡拉OK歌词、花再（HALO PIXELBAR）音箱歌词同步；DeepSeek 全程对话操控——点歌、进度音量、队列收藏、音箱场景、闹钟提醒，一个插件全包。

架构设计与里程碑详见 PLAN.md。

┌─ dsh web (127.0.0.1:3080) ──────────────────────────────┐
│  浏览器半  React 播放面板（♪ 可拖动悬浮球）                 │
│  · 搜索/曲库/队列/账号     · Canvas2D 逐字卡拉OK           │
│        ▲│ 2s 轮询：上报播放状态 ← 命令队列 → 执行          │
├─────────▼──────────────────────────────────────────────┤
│  宿主半  Cordis 插件（dsh 进程内，Node）                   │
│  · 平台 BFF（网易 NCM / QQ fcg 签名直连 / 酷狗移动端搜索）                  │
│  · 音频代理（Range + Referer 注入）                        │
│  · AI 工具集 ×12 · 定时调度 · 通知分发                      │
│  · 花再 HID 驱动 ──USB──▶ 音箱（歌词/时钟/场景/频谱）        │
└─────────────────────────────────────────────────────────┘

特性

• 标准 dsh bundle：一个 npm 包同时含宿主半（Cordis 插件）与浏览器半（React UI），dsh plugin add 即装即用；工具经 dsh tools 服务注册，模型自动发现调用
• AI 原生 ×12 工具：对话「放一首晴天」「下一首」「音量调到40%」「把稻香加进队列」「明早7点半放歌叫我起床」「30分钟后暂停」「换个赛博朋克场景」——搜索、播放、进度、音量、队列、收藏、睡眠定时、音乐闹钟、音箱屏控全部可说
• 通知双通道：声音提示音与花再音箱文字提醒相互独立，各自开关；任何外部系统可 POST /notify 触发
  • 自定义提示音：设置页上传 mp3/wav/ogg/m4a/flac（服务端魔数校验防伪装，≤3MB），可一键恢复内置「叮咚」
  • 音箱文字置顶：通知默认置顶常驻，直到手动消除（/halo/notify/dismiss）或切歌；也可设为 N 秒自动让位歌词，暂停状态下到点回时钟
• 定时任务：设置页可视化配置——音乐闹钟（时间+关键词+备注，随时增删）与睡眠定时器（分钟数启停+倒计时）；每日到点搜歌开播并做双通道提醒，持久化本地；总开关一键停用
• 反向推送：切歌事件以折叠通知写入最近活跃的会话动态（不唤醒模型、零 token）；需至少一个已打开的对话，开关可控
  • 聚合搜索：网易云（原生 weapi/eapi 复刻，零依赖）+ QQ 音乐（fcg 直连 + sha1 签名，移植自 Mineradio）+ 酷狗（移动端搜索直连，仅搜索发现、播放受限）；关键词历史与最近结果跨开关保留
• 逐字卡拉OK：YRC/QRC 词级时间轴解析 + Canvas2D 双色填充染色；单行精简模式适配窄界面；界面歌词可一键开关（关闭不影响音箱同步）
• 登录收藏：网易云 / QQ 扫码登录（二维码过期自动换新；扫码确认返回 502 带 Cookie 时也按成功处理）、QQ Cookie 粘贴兜底；本地 ❤ 与平台红心双向同步
• 随便听听：一键生成「曲库+平台红心 Top30（按播放次数）+ 6 首随机新歌」的打乱歌单并开播
• 推荐：曲库页多分组——登录时「每日个性化推荐」+ 官方榜单随机轮换 ×2（日期种子，每天新鲜、当天稳定）；未登录同样有随机榜单组
• 曲库多列表：本地红心 / 自定义列表 / 最近播放，支持导入导出 JSON 备份，数据存 $DSH_HOME 纯本地
• 花再同步：USB HID 驱动 HALO PIXELBAR 音箱实时显示歌词（换行推送、切歌信息、暂停回时钟）；配置改动即时下发；取消勾选同步或退出时自动恢复时钟界面；node-hid 加载失败/设备未找到等原因直接显示在设置页
• 四种播放模式：顺序 / 列表循环 / 单曲循环 / 随机
• 跨平台音源回退：取流失败自动降级音质 → 跨平台同名同歌手换源 → 队列跳歌（20s 预算 + token 防竞态，骨架移植自 Mineradio provider-fallback）
• 设置面板：音质偏好、「通知与定时」四开关 + 自定义提示音上传、闹钟/睡眠定时可视化配置、花再同步开关与显示参数（对齐/滚动/每行字数/通知时长/暂停时钟）
• 可插拔音源架构：MusicProvider 合同 + ProviderRegistry（对标 HaloLyricSync factory.py）。新增平台只需在 providers/<x>.ts 实现合同、installBuiltinProviders() 注册一次，routes/tools/merge 自动适配，无需改动消费方
• 通知测试入口：设置页可一键触发 POST /api/dsh-music/notify 验证双通道（声音 + 音箱文字）
• 切歌可靠性：音频元素 load() 强制重载，彻底解决「选了新歌仍播旧歌」
• 随便听听加速：备选榜单并行请求、红心获取 3s 超时兜底、未登录直接跳过
• 登录状态修复：authStatus 错误显式兜底，不再卡在"检测中"
  • 用户侧音源管理：设置面板「音乐源」分组可实时启停各平台（GET /providers + POST /providers/toggle），状态持久化；停用后聚合搜索仅走启用源
  • 酷狗音源（搜索发现）：providers/kugou.ts 实现 MusicProvider 合同、零依赖直连移动端搜索，作为首个新增第三方源；其播放接口需签名/dfid，轻量手段取不到直链，故仅作搜索扩源，点播回退至网易云/QQ
• 不重复造轮子：平台 API 层、卡拉OK算法、音源回退骨架均自 Mineradio 移植改造；插件机制完全复用 dsh Cordis 体系

安装

本插件 运行时零 npm 依赖：网易云为原生 weapi/eapi 复刻（仅 node:crypto + fetch），
框架（@deepseek-ai/*）由 dsh 宿主在运行时提供，不再作为 peerDependency 被 pnpm 自动安装。
因此从 dsh 市场安装不会再触发 symlink 权限错误（EPERM）；pnpm pack 后安装实测仅装 0 个依赖。

• 从 dsh 市场安装（推荐）：在插件市场搜索 dsh-music-huazai 一键安装，重启 dsh web 即可。

• 本地开发 / 手动安装：

  pnpm install
  pnpm build
  dsh plugin --profile web add <本仓库路径>
  # 重启 dsh web，刷新页面，右下角 ♪ 即播放器
  

本地开发：仓库以 link: 方式接入 profile。改完代码 pnpm build；
宿主半变更需重启 dsh web（可用 scripts/dev-server.ps1 启停），浏览器半变更刷新页面即可。

使用

1. 听歌：点 ♪（悬浮球可拖到任意位置）→ 搜索 → 点结果即播；或点「🎲 随便听听」一键随机开播
2. 发现：「曲库」Tab —— 顶部推荐区含每日个性化 + 随机轮换榜单（chips 切换），下方管理你的多个列表
3. 收藏：任意曲目行点 ♡ 存入本地红心；网易登录状态下自动同步到平台红心
4. 账号：「账号」Tab —— 网易云 / QQ 均支持扫码登录（请用对应手机 App 的扫一扫），QQ 也可粘贴 Cookie（需含 uin= 与 qm_keyst=）
5. AI 全程操控：在 dsh 对话框直接说——
   • 「放一首周杰伦的晴天」「下一首」「现在放的什么」「跳到1分30秒」
   • 「把稻香加进队列，然后单曲循环」「音量调到40%」「收藏这首歌」
   • 「明早7点半放首轻音乐叫我起床」「30分钟后暂停」（睡眠定时）
   • 「音箱换个赛博朋克场景」「显示频谱样式2」「屏色改成 #3366ff」
6. 花再同步：音箱 USB 连接电脑后，在设置面板开启「启用歌词同步」（默认关闭）；取消勾选或退出/停服时自动恢复时钟界面
7. 备份：曲库「导出」下载全部列表 JSON，「导入」恢复

AI 工具

全部经 dsh tools 服务注册，模型按 JSON schema 自动调用；播放执行经桥接命令队列下发浏览器半。

通知入口：POST /api/dsh-music/notify {title, text} —— 按设置分发声音提示音与音箱文字，供外部脚本/其他插件触发提醒。

HTTP API（同源 /api/dsh-music/*）

数据存储：登录态、曲库列表、播放统计、插件设置、闹钟均在 $DSH_HOME/dsh-music-huazai/ 下，纯本地。

冒烟测试

pnpm exec tsx scripts/smoke-m2.ts   # 平台层：搜索/取流/歌词/登录态（真实API）
pnpm exec tsx scripts/smoke-m4.ts   # 歌词解析：LRC/YRC/翻译对齐（21项断言）
pnpm exec tsx scripts/smoke-m6.ts   # 花再协议：包构建/校验/emoji清洗（无需硬件）

诊断脚本（登录/音箱排障时用）：

pnpm exec tsx scripts/diag-qr.ts          # 网易/QQ 扫码三步链路（无需扫码）
pnpm exec tsx scripts/diag-qq-prod.ts     # QQ 扫码生产路径轮询状态
pnpm exec tsx scripts/diag-netease-auth.ts # 已存网易云 Cookie 有效性核验
pnpm exec tsx scripts/diag-halo-sync.ts   # 花再全链路：加载→连接→下发文字（真实硬件）

无头浏览器综合 E2E（需先 pnpm build 并 powershell -File scripts/dev-server.ps1 启动 dsh web）：

pnpm exec tsx scripts/e2e-all.ts   # Playwright 无头 Chrome 全功能自测：面板/搜索/播放/音乐源开关/闹钟/推荐，
                                    # 并捕获 console.error、pageerror 与 >=400 失败请求，用于发现回归

已知问题与对策

致谢

• Mineradio — 本项目大量源代码移植自它：平台 API 层（QQ fcg 签名直连、聚合搜索）、逐字卡拉OK同步算法（YRC/QRC 解析、词级插值）、花再音箱桥接（halo-sync 模式与 HID 协议）。感谢原作者的出色工作。
• deepseek-harness — Cordis 插件体系与 Web UI 插槽
• HaloLyricSync / HaloPixelToolBox / Seraph310/halo-pixelbar-mcp — 花再 HID 协议
• NeteaseCloudMusicApi — 网易云 weapi/eapi 协议参考（本项目已原生复刻其加密与请求约定，零运行时依赖）

开源许可

本项目基于源代码移植自 Mineradio，依其 MIT 许可的授权条款，以 GPL-3.0 协议发布。

本程序为自由软件：你可以依据自由软件基金会发布的 GNU 通用公共许可证（GPL）第 3 版对其再次分发和/或修改。详见仓库根目录的 LICENSE 文件，或访问 https://www.gnu.org/licenses/。

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Contains code ported from Mineradio (MIT License).

更新日志

v0.1.0 (2026-08-24)

修复

• 网易云红心「取消收藏」失效（布尔值与字符串比较 bug）
• 内置音源停用状态不持久化（重启后强制重新启用）
• 音频代理 SSRF 防护（仅允许 qq.com / music.126.net）
• 切歌未生效（新增 audio.load() 强制重载音频源）
• 登录状态卡在"检测中"（authStatus 错误显式兜底）
• 设置页反向推送复选框不可点击（label 添加 onClick 触发 checkbox）
• 推荐区日期种子轮换所有榜单 ×2（当天固定、跨天变化）
• 随便听听响应慢（备选榜单并行请求、红心获取 3s 超时兜底、未登录直接跳过）
• 队列徽标改为响应式订阅（实时更新数字）
• 酷狗曲目显示正确图标"酷"
• 闹钟调度抗卡顿/睡眠补偿（检测跨越分钟并补触发）
• Karaoke rAF 按需运行（仅播放中且有歌词时渲染）
• QQ 扫码登录标注"实验性/最佳努力"

优化

• 抽取公共路由辅助函数到 src/routes/helpers.ts（去重 5 个函数）
• 删除无用导入 trackKey