前言¶
在 DSH Web GUI 里长时间盯会话和工具输出时，很多人会在另一个窗口或系统播放器里放背景音。那样和当前界面是割裂的：切窗口、对不上页面状态，也没有和 DSH 同一套扩展方式。若希望音乐控件就长在 Web 界面里、又能拖本地文件或粘贴 B 站 / 网易云 / QQ 音乐链接入队，就需要走 DSH 的插件槽位，而不是改宿主源码。
下面介绍社区插件 dsh-music-on（维护者 lilcandi）：在 Web 客户端右下角挂一枚可拖动的音乐胶囊，展开后是播放卡片与可选的底部频谱。插件归类为客户端，通过宿主公开的槽位、服务与路由接入，README 明确写明不修改宿主任何文件。
这是什么¶
dsh-music-on 是面向 DSH Web GUI 的音乐台插件：右下角常驻可拖动胶囊，点开为播放卡片；支持拖入本地音频、粘贴 B 站 / 网易云音乐 / QQ 音乐歌单或单曲链接（及直链音频）解析入队；页面底部可显示实时频谱，并提供多套画法与配色主题。
- 目录页：https://www.skillhub.cn/plugins/lilcandi/dsh-music-on
- 源码与文档：https://github.com/lilcandi/dsh-music-on
- 当前包版本（
package.json）：0.2.0 - 许可证：MIT
- 宿主兼容范围（
engines.dsh）：>=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-0 <0.3.0-0
DSH 生态强调「一切皆插件」；SkillHub 等社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。安装前请自行查看仓库源码与许可证——插件逻辑在当前 DSH 进程权限下运行。
核心功能¶
播放与队列¶
- 队列播放，上一首 / 下一首，进度条拖动，音量旋钮（悬停时可用滚轮调节）。
- 三种循环模式，切歌带淡入淡出。
本地音频¶
将文件拖到播放卡片上即可入队播放。README 列出的格式包括：mp3、wav、ogg、m4a、flac、aac、opus、webm。
链接解析¶
一次可粘贴多条，类型可混用：
- B 站视频
- 网易云音乐歌单 / 单曲
- QQ 音乐歌单 / 单曲
- 直链音频
浏览器无法直连部分平台接口（同源策略、Referer 等），解析与流媒体由宿主侧路由代劳（见下文「宿主路由」）。对拿不到直链的曲目（例如会员或版权限制），插件诚实降级：跳过伪造 URL，队列中标注原因，可跳转原平台页面。
频谱与主题¶
- 六种频谱样式：圆点、粗柱、方块阵列、对称声波、折线、时域波形；可调宽度、柱数、灵敏度、光晕、高度、帧率、层级，以及贴底通栏或嵌在卡片内。
- 七套配色主题：鲸鱼蓝白（默认）、极光青紫、薄荷绿、落日橙、玫瑰粉、霓虹赛博、极简灰白。
- 平台曲目使用专辑封面，B 站曲目使用视频封面。
设置、收藏与历史¶
在 Web GUI 中打开 设置 → 音乐台，分为界面、外观主题、播放、链接与歌单、频谱五组。设置页内另有收藏与最近播放两张表，链接可一键回放。
安装与启用¶
在已配置 web profile 的环境下，从 GitHub 安装（README 注明首次可能要求授权构建，需按提示在 profile 的 pnpm-workspace.yaml 中配置 allowBuilds）：
dsh plugin --profile web add github:lilcandi/dsh-music-on
安装完成后强制刷新浏览器（Ctrl+F5）。若装载成功，右下角应出现音乐胶囊，设置页左侧会出现「音乐台」导航项。
从本地路径安装（可选）¶
dsh plugin --profile web add file:J:/plugin/dsh-music-on
路径按本机实际目录替换。亦可按 README「手工挂载」编辑 profile 的 package.json，将 dsh-music-on 写入 dependencies 与 dsh.profile.bundles，再在 profile 目录执行 pnpm install。注意：仅编写 cordis.patch.yml 而未把包名加入 dsh.profile.bundles 时，插件不会被挂载。
验证装载（可选）¶
README 提供 PowerShell 示例：在日志中检索 dsh-music-on，或请求 combo 中的 client.js 看状态码是否为 200。
典型用法¶
- 安装并刷新页面后，点击右下角胶囊展开播放卡片。
- 听本地文件：把音频文件拖到卡片区域，即入队并开始播放。
- 听在线歌单：复制 B 站、网易云或 QQ 音乐的链接，粘贴到插件提供的输入区域（可一次多条）；等待解析后按队列播放。
- 调外观：进入 设置 → 音乐台，切换频谱样式、配色主题及播放相关选项。
- 回看链接：在设置页的收藏或最近播放表中选择条目一键回放。
实现要点（给插件开发者）¶
了解这些约束有助于排错，内容与仓库 README 一致。
浏览器半边零转译：宿主对插件客户端代码是静态投递、不做转译，因此 src/client/** 在运行时须使用 react.createElement，不得在交付给浏览器的 bundle 里保留 JSX 语法；client.js 由 scripts/build-client.mjs 用 esbuild 打成单文件，避免相对路径 require 导致整插件加载失败。
宿主半边：index.js 提供 /api/dsh-music-on/resolve（链接解析）与 /api/dsh-music-on/stream（音频流转发）。网易云 / QQ 等 CDN 直链通过 HMAC 不透明票据（stream?mt=<token>）下发，避免 stream?src= 退化为开放代理；票据 TTL 为 10 分钟，宿主重启后旧票据失效。
每批曲目上限：宿主 MAX_STREAM_TRACKS 与客户端 MAX_PLATFORM_TRACKS 均为 60，由测试断言两端一致。
适用场景与注意¶
适合：主要在 DSH Web GUI 中工作、希望背景音乐与界面同屏、需要快速拖本地试听或粘贴国内常见平台歌单链接的用户。
注意：
- 插件依赖 DSH Web 客户端扩展机制，安装命令使用
--profile web。 - 部分平台曲目因版权或会员策略无直链，行为是标注不可用而非假装可播。
- 安装与运行等同于信任该仓库代码在当前 DSH 进程中的执行；请阅读 MIT 许可证与
src/host/下的网络与票据逻辑后再用于生产环境。
结尾¶
dsh-music-on 把可拖动播放器、多平台链接入队、本地拖放与可配置频谱收进 DSH Web 右下角，并通过宿主路由处理解析与流媒体，而不改宿主文件。需要细节、截图与加载链路说明时，以 GitHub README 为准。
