dsh-music-plus

一个基于 dsh-music-player 修改而来的 DeepSeek Harness 本地音乐 / 播客 / 网络电台插件。它保留本地音乐播放、频谱可视化、自建歌单，移除了原版的在线 QQ 音乐、在线酷狗音乐、AI 讲书（TTS）、实时歌词/字幕，并新增了播客 RSS 订阅与在线播放与网络电台（内置 CC0 电台库）。为与原版共存不混淆，包名与内部标识已整体改名为 dsh-music-plus（独立插件行、独立 /dsh-music-plus/* 路由、独立状态文件、独立 music_play_plus 工具）。

---

来源项目（Based on）

• 原项目：kendu76/dsh-music-player
• 基准提交：4eb448d — fix: 酷狗取链进行中去重——HEAD/GET 并发只取一次链（减少重复请求）（原作者 kendu76）
• 本项目：dsh-music-plus（在原项目基础上的本地修改版）

本仓库属于个人学习/二次开发用途：未改动原项目的 MIT 许可；在线 QQ/酷狗、AI 讲书、歌词等能力是基于原作者实现做的功能裁剪与扩展。

---

主要变更（逐条）

1. 移除在线 QQ 音乐：删除 QQ 登录/搜索/歌单/排行榜/取链等整套能力，以及 lib/qq.js、lib/qrc.js 与对应路由、客户端 QQ 面板。
2. 移除在线酷狗音乐：删除酷狗扫码登录/榜单/搜索/取链/KRC 歌词整套能力，以及 lib/kugou.js、lib/krc.js 与对应路由、客户端酷狗面板。
3. 移除 AI 讲书（TTS）：删除 .txt/.epub 小说扫描、结构解析、MiMo TTS 合成、章节目录/声音选择/进度细线，以及 /dsh-music-plus/book/*、/dsh-music-plus/tts-logs 路由；lib/index.js 不再依赖 llm。
4. 移除实时歌词 / 字幕：删除本地 .lrc 匹配、在线兜底取词、歌词动效 / 卡拉OK 扫色、/dsh-music-plus/lyric* 路由，以及 lib/lyric.js 与播放条的歌词 UI。
5. 新增播客 RSS 订阅与在线播放：
   • 新增 lib/podcast.js（纯 RSS 2.0 / Atom 解析：CDATA、命名空间 media:*、自闭合 <link/>、itunes:duration 秒/时间串、enclosure 音频地址识别）。
   • Host 端新增 /dsh-music-plus/podcasts（列表）、/podcasts/add、/podcasts/refresh、/podcasts/remove 路由，订阅持久化到 ~/.dsh/dsh-music-plus-podcasts.json。
   • 客户端新增「播客」页签：顶部订阅源横排卡片 + 聚合视图。默认（不点任何源）显示所有源的最新单集（按发布时间新→旧，每行带来源徽标）；点具体源则只显示该源全部单集（同样新→旧）；点末尾的「全部」回到聚合视图。点任意一集即用现有播放器在线播放。
6. 整体改名与完全隔离（避免与原版混淆/冲突）：
   • package.json name → dsh-music-plus。
   • cordis.patch.yml 行 id: music-player-plus、name: dsh-music-plus。
   • lib/index.js export const name = 'dsh-music-plus'。
   • lib/client.js .load({ id: 'dsh-music-plus' })。
   • HTTP 路由前缀 /dsh-music → /dsh-music-plus。
   • Host 状态文件改名：music-player-*.json → dsh-music-plus-*.json（prefs / playlists / podcasts / state）。
   • 模型工具 music_play → music_play_plus（systemPrompt 同步更新）。
   • lib/index.js 的 inject 移除已不使用的 llm。
7. 目录选择器跨盘符修复：给「选择音乐目录」与歌单「添加歌曲」等选择器加了「⬆ 上级目录」/「⬆ 本机磁盘（切换盘符）」按钮，解决 Windows 上只能选 C:\Users\...\Music、选不到 E:\ / F:\ 的问题（根因是客户端 browse() 未使用服务端返回的 up 字段）。
8. 新增网络电台：
   • 新增 lib/radio.js（零依赖解析：M3U/M3U8、PLS、XSPF、ASX、README 电台清单、radio-browser JSON）与 lib/radio-host.js（电台库状态、源管理、探活、路由）。
   • 内置 conafun/recommended-radio-streams（CC0 1.0，可自由内置）的快照 lib/radio-data.json：16 个风格、432 台；可在电台页一键从 GitHub 更新，且用户的收藏/隐藏/改名按电台 id 全部保留。
   • 界面统一在插件面板里：播放面板新增「网络电台」页签（与 本地音乐 / 播客 / 系统配置 并列），风格分类浏览、搜索、收藏、探活、添加单台、导入外部电台源、风格管理都在这一页；播放复用现有 <audio> 引擎与播放条（不新增播放器界面）。
   • 直播语义：无进度、不能快进；断流按 1/2/4/8/12 秒退避自动重连，5 次失败自动换台；.pls/.m3u 清单由 Host 解析成真实流地址；.m3u8(HLS) 标「需 HLS」并置灰。
   • music_play_plus 增加 radio / radioCategory 参数（对话里说「放个爵士电台」即可）。
   • 电台库独立持久化到 ~/.dsh/dsh-music-plus-radio.json；新增测试 test/radio.test.js。
9. 精简与测试同步：删除对应旧测试（qq*、kugou*、kg-*、lyric、qrc），重写 test/index.test.js 与 test/client.test.js，新增 test/podcast.test.js；docs/ 删除已过时的 QQ/酷狗/在线歌词等调研文档，保留 playlists-design.md。调整 package.json 的 description / keywords / test 脚本（--pool=threads 以规避部分环境 fork 池 EPERM）。

---

与原版的差异 & 亮点

差异一目了然：

能力	原版 dsh-music-player	本版 dsh-music-plus
本地音乐播放（音质识别/断点续播）	✅	✅（保留）
实时频谱（柱状图/波形图）	✅	✅（保留）
自建歌单 / 收藏「我最喜欢」	✅	✅（保留）
music_play 模型工具	music_play	music_play_plus
在线 QQ 音乐	✅	❌（移除）
在线酷狗音乐	✅	❌（移除）
AI 讲书（TTS 朗读小说）	✅	❌（移除）
实时歌词 / 字幕	✅	❌（移除）
播客 RSS 订阅 + 在线播放	❌	✅（新增，亮点）
网络电台（内置 432 台 / 16 风格）	❌	✅（新增，亮点）
目录选择器跨盘符（E/F 盘）	⚠️ 选不到	✅（修复）

亮点：

• 多订阅源聚合视图：顶部一排订阅源卡片，默认展示所有源的最新单集（新→旧、带来源徽标），点具体源只看它，点「全部」返回聚合——订阅再多也不乱。
• 纯本地解析：播客 RSS/Atom 解析无第三方依赖（lib/podcast.js），Host 用 Node 内置 fetch 拉取，music_play_plus 工具让 agent 可搜索本地音乐/歌单/电台。
• 网络电台，零配置开箱可用：内置 CC0 电台库（16 个风格 / 432 台），打开播放面板的「网络电台」页签点 ▶ 就能听；支持搜索、收藏、一键探活（🟢/🔴）、按风格筛选。也能手填单台或整批导入 M3U / PLS / XSPF / ASX / radio-browser 源。电台与本地音乐 / 播客 / 系统配置同在播放面板里，操作集中在一处。
• 与原版完全隔离：独立插件行、独立 /dsh-music-plus/* 路由、独立状态文件，可与原版并存不冲突；模型工具改为 music_play_plus 避免与 music_play 重复注册。

---

环境要求

• Node.js ≥ 20（播客 / 网络电台的 Host 端用内置 fetch）
• 已安装 dsh CLI（DeepSeek Harness）
• npm / pnpm（DSH 的 plugin 子命令通过 pnpm 管理 profile 依赖）
• 联网：本地音乐与自建歌单完全离线；播客订阅、电台探活 / 内置库更新 / 外部电台源需要能访问对应站点（内置 CC0 电台库已随插件打包，首次打开即可用，不联网也能看到并播放直连台）

---

功能特性

• 本地音频流式播放（HTTP Range）
• 断点续播：本地音乐与播客在刷新/重启后都会恢复到上次播放的曲目/单集与进度（点一下 ▶ 续播，无需重新翻找）。网络电台不参与——直播流没有进度可续，也不会覆盖音乐/播客的断点记录
• 可拖动进度条：播放条底部的细进度线可点击/拖动，定点播放任意位置（音乐与播客通用；电台是直播，不能拖）
• 顺序 / 单曲循环 / 乱序三种模式
• 实时频谱可视化（柱状图 12 段 / 波形图三频段，两种样式可在「系统配置」切换）
• 播放时申请屏幕唤醒锁
• 自建歌单（新建/添加歌曲/排序/清空；播放条爱心收藏到「我最喜欢」）
• 播客订阅（订阅/刷新/退订；聚合视图 + 单源详情；在线播放）
• 网络电台：
  • 内置 CC0 电台库 16 个风格 / 432 台，按风格分类浏览、搜索、收藏
  • 探活：一键并发探测哪些台还能连上（🟢 在线含延迟 / 🔴 离线含原因 / ⚪ 未检测）
  • 自己加台：手填单台，或整批导入 M3U/M3U8、PLS、XSPF、ASX、radio-browser JSON
  • 风格管理：自定义风格、隐藏不听的风格、改名、↑↓ 排序
  • 直播语义：断流按 1/2/4/8/12 秒退避自动重连，5 次失败自动换台；HLS 台标记并置灰
  • agent 可点播：music_play_plus 的 radio / radioCategory 参数
• 支持格式：mp3 / m4a / m4b / aac / flac / wav / ogg / opus / webm / aiff（递归扫描，上限 500 首）
• 真实音质识别：解析文件头显示「格式 · 音质档」（如 FLAC · 无损）

---

本地安装（重要：非 npm 安装）

本项目不是通过 npm install -g 或 dsh plugin add <npm 包名> 安装，而是把本地源码目录作为插件源安装到某个 DSH profile。请按下面步骤做。

1. 把项目放到本地

# 方式 A：git 克隆（推荐）
git clone <你的仓库 URL> dsh-music-plus
cd dsh-music-plus

# 方式 B：直接下载 ZIP 解压到本地某个目录（记住这个目录路径，下面会用到）

2. 用 dsh plugin add 以本地目录方式装入 profile

# 把 <profile> 换成实际 profile 名（如 web），把 <项目绝对路径> 换成上面那个目录
dsh plugin --profile <profile> add <项目绝对路径>

例如：

dsh plugin --profile web add F:\DeepseekHarness\dsh-music-plus

说明：dsh plugin add 会把 pnpm add <dir> 转发到该 profile 目录；正因为本地目录里的 package.json name 已是 dsh-music-plus，所以它会作为独立插件 dsh-music-plus 安装，不会覆盖/和原版 dsh-music-player 混淆。

3. 重启 DSH / 刷新 Web 页面

重启 DSH 或刷新 http://127.0.0.1:3080，聊天区上方会出现「DSH音乐播放器」播放条；点播放条上的「列表」打开面板，左侧页签是 本地音乐 / 播客 / 网络电台 / 系统配置：

• 本地音乐：点「选择音乐目录」选音乐目录（默认 ~/Music）→ 自动扫描 → 点歌播放；下方还有「曲库 / ♥ 我最喜欢 / 自建歌单」子标签。
• 播客：粘贴任意 RSS / Atom 订阅链接 → 点「订阅」；顶部源卡片选源、默认看「全部」聚合最新单集，点任意一集在线播放。
• 网络电台：内置 16 个风格共 432 台，按风格或搜索挑一台，点行首 ▶ 用播放条播放；也能在「＋ 添加 / 编辑电台」「电台源」里自己加台或整批导入外部电台源。
• 系统配置：频谱样式 / 进度条 / 音质徽章 / 播放条背景 / 沉浸感等开关。

4. （可选）让 agent 直接播放

music_play_plus 工具已注册，在对话框里直接说就行：

你说	走的参数	效果
「播放周杰伦的歌」	query	按关键词搜本地音乐
「播放歌单 我最喜欢」	playlist	按歌单名播放自建歌单
「放个爵士电台」	radioCategory	从该风格里选一台电台
「播放 NTS」	radio	按台名关键词选一台电台
「暂停 / 继续 / 下一首」	action	播放条的下述传输控制

小提示：播客音频与电台流都以源站地址直接播放；若某源未开 CORS，频谱可能不显示，但播放不受影响。浏览器若拦截自动播放，在播放条上点一次 ▶ 即可解锁。

---

本地安装可能遇到的坑

• ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION（供应链最小发布年龄策略）：若是 profile 里某些三方包发布太新被 DSH/pnpm 的供应链策略拦截，可用「本次临时关闭年龄校验」的方式安装：

  dsh plugin --profile <profile> add --config.minimumReleaseAge=0 <项目绝对路径>
  

  或按 DSH 提示，在 pnpm-workspace.yaml 的 minimumReleaseAgeExclude 里加入这些包名。

---

本地卸载

因为是用本地目录安装的，卸载就是从 profile 里移除这个包：

dsh plugin --profile <profile> remove dsh-music-plus

例如：

dsh plugin --profile web remove dsh-music-plus

• 若卸载也被供应链策略拦截，同样加 --config.minimumReleaseAge=0：

  dsh plugin --profile <profile> remove --config.minimumReleaseAge=0 dsh-music-plus
  

• 卸载后，该 profile 里不再有 dsh-music-plus 这个插件；Host 端状态文件（见下方「状态文件一览」）会保留在磁盘上（不影响其它插件），如需彻底清理可手动删除这些文件。

---

目录选择器（跨盘符）

「选择音乐目录」会列出本机所有磁盘（__drives__ 视图），并提供「⬆ 本机磁盘（切换盘符）」/「⬆ 上级目录」按钮，因此可以方便切到 E:\、F:\ 等任意盘符的目录。

---

播客使用一览

• 订阅：粘贴 RSS 2.0 / Atom 链接 → 订阅。
• 聚合视图（默认）：顶部源横排，默认显示所有源最新单集（新→旧，带来源徽标）。
• 单源视图：点某个源卡片 → 只看该源（新→旧）。
• 返回聚合：点横排末尾的「全部」。
• 播放：点任意一集即用现有播放器播放；当前订阅即播放来源，顺序/乱序在该订阅内循环。

---

网络电台使用一览

入口：播放条上的「列表」→ 打开播放面板 → 左侧「网络电台」页签（与 本地音乐 / 播客 / 系统配置 并列）。电台的全部界面都在这一页，与插件其它设置在同一处。

• 内置库：来自 conafun/recommended-radio-streams（CC0 1.0）的快照，16 个风格 / 432 台（电子、爵士·布鲁斯、氛围·Lo-Fi、金属·重型、新闻·谈话、游戏·芯片音乐、世界音乐……）。
• 挑台：顶部按风格筛选（含「全部」「★ 收藏」「已隐藏」），或用搜索框按台名/风格/主页搜。
• 播放：点行首 ▶，用现有播放条播放。直播流没有进度、不能快进；断流会自动重连（1/2/4/8/12 秒退避），5 次仍失败自动切下一台。
• 收藏：行尾 ☆ 收藏，出现在「★ 收藏」里。
• 探活：「检测当前列表」/「检测全部」会并发探测每台是否还能连上，结果显示为 🟢（含延迟）/ 🔴（含原因）/ ⚪（未检测），鼠标悬停可看是多久前测的。
• 添加单台：「＋ 添加 / 编辑电台」填 流地址（必填）、名称、主页、风格、标签。.pls / .m3u 清单地址也支持（播放前由 Host 解析出真实流地址）。
• 导入外部源：「电台源」里粘一个清单链接即可整批导入，支持 M3U/M3U8、PLS、XSPF、ASX，以及 radio-browser.info 的 JSON（例：https://de1.api.radio-browser.info/json/stations/bytag/jazz?limit=100）。
• 风格管理：新建自定义风格、隐藏不听的风格、改名、↑↓ 调整顺序（顺序即电台列表的分组顺序）。
• 内置库更新：「从 GitHub 更新」重拉上游 README；你的收藏、隐藏、改名、自定义电台全部按电台 id 保留。想退回插件自带快照点「恢复内置」。
• 让 agent 放电台：直接说「放个爵士电台」「播放 NTS」，agent 会用 music_play_plus 的 radio / radioCategory 参数点播。

已知取舍：.m3u8（HLS）直播共 12 台，浏览器原生 <audio> 播不了，界面会标「需 HLS」并置灰（要支持需要引入约 1MB 的 hls.js，本版不做）。电台流直连播放不需要 CORS；未开 CORS 的源只是频谱不显示，播放不受影响。

---

状态文件一览

全部落在 ~/.dsh/（Windows 是 C:\Users\<你>\.dsh\），与可选的另一个插件 dsh-music-player 并存互不干扰：

文件	内容	删了会怎样
dsh-music-plus-state.json	音乐目录（曲库根）	回到默认 ~/Music，需重选目录
dsh-music-plus-prefs.json	播放偏好（音量 / 模式 / 频谱样式 / 面板位置 / 断点）	偏好回默认，断点续播丢失
dsh-music-plus-playlists.json	自建歌单与「我最喜欢」	歌单丢失（不会删音乐文件）
dsh-music-plus-podcasts.json	播客订阅与已抓取的单集列表	订阅丢失，可重新粘贴链接
dsh-music-plus-podcast-play.json	播客断点（独立通道，避免与音乐互相覆盖）	播客续播位置丢失
dsh-music-plus-radio.json	网络电台：手填电台、外部电台源、收藏、隐藏、改名、自定义风格、探活结果	你的电台增改丢失；内置 432 台快照在插件包里，会重新出现

电台状态分两层：内容层（内置快照 + 外部源 + 手填电台）可再生成，用户层（收藏 / 隐藏 / 改名）按电台 id（= 流地址 hash）保存。所以「从 GitHub 更新内置库」「刷新外部源」都不会丢你的数据。

---

测试

cd <项目根目录>
npm install          # 安装开发依赖（vitest / react / jsdom）
npm test             # 跑全量：Host 单测 + 播客解析 + 网络电台（解析器/电台库/面板页签）+ Web 渲染冒烟

若 npm test 报 spawn EPERM（fork 池被部分环境拦截），package.json 的 test/ci 已用 --pool=threads 规避。

---

License

MIT — 原项目版权归原作者，本修改版同样以 MIT 发布。