前言¶
在 DSH 里长时间挂着面板写代码或跑任务时，常会希望背景音乐不另开应用、也不把音频文件上传到第三方。浏览器自带的播放体验往往和面板割裂，歌单也难和当前工作区放在一起管理。dsh-local-music-player 是面向 DSH Web UI 的本地优先音乐播放器与歌单管理插件：音频和歌单留在当前浏览器的 IndexedDB，通过左侧栏入口进入完整播放器界面，并支持在切换 DSH 面板时通常继续后台播放。
下面介绍插件定位、能力边界、安装方式与日常使用，事实以仓库 README 与 npm 包信息为准。
这是什么¶
维护者为 XM-Zou，npm 包名为 dsh-local-music-player，当前 README 标明已发布版本为 0.7.3，许可证 MIT。插件在 DSH 客户端侧以 Web 平台脚本注入（platform: "web"），无构建步骤、无运行时依赖；要求宿主 DSH >= 0.2.1（engines.dsh 声明），README 写明已在 DSH 0.2.2-rc.1 的 Desktop / Web UI 上测试。
一句话定位：在 DSH 全局左侧栏增加「音乐」入口，提供导入本地音频、歌单分类、播放控制、搜索与 ZIP 备份恢复，数据不上传、插件不发起网络请求。
核心功能¶
入口与导入¶
- 点击全局左侧栏「音乐」图标进入播放器页面。
- 「导入音乐」选文件，或把音频拖到页面。
- 「导入文件夹」：文件夹名自动成为新歌单名，内部音频一并导入；音乐库已有曲目会复用，不重复导入。
元数据与列表展示¶
- 读取 ID3v2 标题与封面；不识别歌手和专辑。
- 文件名含书名号《》时，优先用书名号内文字作歌名，号外文字作歌曲信息；无《》时用 ID3 标题或文件名。
- 旧版导入的曲目可通过顶部「重新解析歌曲信息」按新规则更新，无需重新导入。
- 列表显示所属歌单（无歌单显示「未分类」），副标题显示歌曲信息。
歌单与播放¶
- 新建、重命名、删除歌单；一曲可加入多个歌单；侧栏歌单可拖动排序。
- 置顶「未分类」歌单：未加入任何歌单的曲目自动归入，且不可删除。
- 删除歌单默认保留歌曲：仅在本歌单的进「未分类」，仍在他处的留在原歌单；也可选同时从音乐库删除，共享曲目删除前会提示。
- 播放/暂停、上下曲、进度、音量、随机、顺序/列表循环/单曲循环。
- 切换 DSH 面板时通常会继续播放；暂停、退出 DSH 或宿主挂起时停止。
- 按歌名、歌曲信息或文件名过滤；最近导入优先显示。
- 使用 DSH 主题 token，亮/暗主题与窄窗口适配；界面中英双语。
备份与存储¶
- 音频 Blob 与歌单保存在浏览器 IndexedDB。
- 顶部备份：导出为 ZIP（含
audio/、covers/、playlists.json），或从 ZIP 合并恢复；已存在歌曲复用，同名歌单合并。导入兼容旧版 v1 备份。
安装与启用¶
npm 为首选来源：dsh-local-music-player@0.7.3。若桌面端「插件」界面因镜像返回 E500 安装失败，README 建议用 CLI 并显式指定 registry.npmjs.org。市场条目可能略晚于 npm；市场里版本不是 0.7.3 时可用 npm 命令安装。
DSH Desktop 界面：打开 设置 → 插件，在安装来源里填写：
dsh-local-music-player
DSH Web（CLI）（dsh.cmd 为 Desktop 自带 CLI 的完整路径，按本机 DSH 安装目录修改）：
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile web add dsh-local-music-player --registry=https://registry.npmjs.org
dsh 已在 PATH 时可简写：
dsh plugin --profile web add dsh-local-music-player --registry=https://registry.npmjs.org
DSH Desktop（CLI）：
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-local-music-player --registry=https://registry.npmjs.org
若曾用本地目录链接安装，先移除再装：
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop remove dsh-local-music-player
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-local-music-player --registry=https://registry.npmjs.org
npm 未同步或网络异常时，可用 GitHub 源码安装（README 给出的形式）：
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile web add github:XM-Zou/dsh-local-music-player --registry=https://registry.npmjs.org
& "D:\ruanjian\DSH\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add github:XM-Zou/dsh-local-music-player --registry=https://registry.npmjs.org
也可直接下载 Release 包：dsh-local-music-player-0.7.3.tgz（见 GitHub Releases v0.7.3）。
插件市场在 插件 → 发现（Discover） 搜索；社区市场页：https://awesome-dsh-plugin.com/p/XM-Zou/dsh-local-music-player/。DSH 生态上插件独立分发，与 DeepSeek / 幻方无官方从属关系，安装前宜自行查看源码与 MIT 许可证。
典型用法¶
经过上面的步骤启用后，可按 README 顺序操作：
- 点击左侧栏「音乐」图标。
- 点击「导入音乐」，或将音频拖到页面。
- 需要整库分文件夹入库时，点「导入文件夹」。
- 新建歌单，在歌曲行点 + 加入一个或多个歌单。
- 点歌曲播放；底部栏调节进度、音量、随机与循环模式。
备份：点顶部右侧备份图标，「导出音乐库」得到 ZIP；「导入音乐库」会合并到现有库。ZIP 内多歌单共享的曲目会在各歌单文件夹各有一份副本，体积会变大；空歌单也会生成空文件夹。
数据、隐私与限制¶
- 导入数据在当前 DSH 浏览器 origin 的 IndexedDB；清除站点数据、端口/origin 变化或换浏览器配置，可能导致库不可见。
- 插件无遥测；能否播放某格式取决于宿主 Chromium/Electron 解码能力（README 列举常见 MP3、FLAC、WAV、M4A/AAC、OGG、Opus）。
- 已知限制：暂无云同步；ZIP 备份不支持 ZIP64，单包超过 4 GB 无法导出；受浏览器存储配额约束，超大库可能导入失败；库不跨设备共享。
插件在已安装的 DSH profile 对应客户端环境中运行，权限与当前 DSH 进程/浏览器上下文一致；若对本地文件访问范围有要求，安装前应阅读仓库源码。
结尾¶
dsh-local-music-player 把本地听音、歌单整理和 ZIP 迁移收进 DSH 左栏，适合希望在同一面板内后台听歌、且不接受音频上云的 DSH Web / Desktop 用户。目录与源码：
