DSH 生态强调插件化与 Agent 能力的扩展。在开发 Agent 应用时，往往需要音频播放能力，或者希望将音乐播放器无缝集成到工作流中。dsh-music-player 是一个专注于简约的 Web 端播放器插件，支持网易云与本地音乐源，并提供完整的 Agent SKILL，允许 AI 自定义播放器风格、控制播放，并将队列与搜索功能集成在官方设置页。
核心功能¶
悬浮窗播放器
插件提供常驻挂载的悬浮窗，支持毛玻璃与发光效果。具备逐字歌词显示、可拖拽进度条与音量控制功能。收起悬浮窗不会中断播放。
本地音乐支持
通过指定文件夹加载本地音乐。音频路径会保存在队列中，支持同名 .lrc 文件自动加载歌词，以及 MP3 内嵌封面显示。
网易云在线
支持在线搜索、歌词获取与播放地址解析。官方 API 优先，被限流时自动降级到备用网关。VIP 歌曲（如《起风了》）需在官方设置页填写 Cookie 才能播放。支持通过歌单 ID 或链接批量导入歌曲。
Agent 控制
提供完整的 Agent SKILL，包含搜歌、播新歌、队列增删查、播放控制、播完通知以及自定义 CSS 与 UI 配置等工具。播完一首歌后，插件会清空队列并发送通知，便于 Agent 决定是否添加新歌。
安装与启用¶
前置准备
首次安装前需注意：如果环境中的 pnpm 版本 ≥ 10，默认会拒绝执行 git 依赖的构建脚本。需在 profile 的 pnpm-workspace.yaml 中添加 allowBuilds 声明，然后重跑安装命令。
安装命令
dsh plugin --profile web add github:xiaoqiezi-china/dsh-music-player
版本锁定
建议在安装命令后钉住 commit SHA 以固定版本，方便后续回滚：
dsh plugin --profile web add github:xiaoqiezi-china/dsh-music-player#<commit-sha>
使用示例¶
- 加载歌词：确保本地音乐文件夹中存在与音频文件同名的
.lrc文件，插件会自动加载。 - VIP 体验：进入官方设置页，在网易云相关配置中填入 Cookie，即可播放 VIP 歌曲。
- Agent 交互：Agent 可调用搜歌、播新歌等工具，将音乐播放整合到对话流中。
注意事项¶
- 构建依赖：pnpm ≥ 10 环境下，务必在 profile 配置中处理 git 构建脚本的信任问题。
- 播完行为：播放模式设定为顺序播放时，播完一首会自动清空队列并发送通知，提示 Agent 添加新歌。
- API 稳定性：播放地址解析优先使用官方 API，若遇限流会自动切换至备用网关。
总结¶
dsh-music-player 是一个轻量、干净的 Web 端音乐播放方案。它解决了在 DSH 环境中集成音频播放的需求，特别是通过 Agent SKILL 实现了音乐控制与 AI 的深度结合。完整的文档与源码可参考以下链接。
