前言¶
在 DeepSeek Harness（DSH）里长时间写代码、跑智能体时，很多人会希望有一套不离开界面的背景音乐。系统默认播放器会切到别的窗口，浏览器标签页里的音频又容易和 DSH 自身的语音播报、启动动画或其它插件抢控制权。社区插件 dsh-audio-player（维护者 edgewalker6666，分类：客户端）针对的是另一类需求：在 DSH 进程内自建播放链路，用独立悬浮窗管理曲库，并在可选情况下与启动动画对齐起止。
下面介绍它的定位、能力与安装用法；事实以 GitHub 仓库 README 为准。
这是什么¶
dsh-audio-player 是一个 DSH 内的 MP3 音频播放器：用户自行导入音乐，在可调大小的独立悬浮窗里播放；若当前环境有启动动画（优先适配长征机启动动画 dsh-startup-secret，其次 dsh-theme-prts），可切换到「启动动画同步」模式，从 0:00 起播，动画结束时渐隐并停止。
播放器使用自己的 HTMLAudioElement，不会暂停、静音或改动 DSH、启动动画、语音播报以及其它插件的声音。实现上 UI 放在 Shadow DOM，宿主只增加 #dsh-audio-player-host，不修改 DSH 的 React 树；悬浮窗 z-index 低于启动动画层，启动期间被动画盖住。
许可证为 MIT（README）；当前 package 版本 1.0.0，要求 DSH 0.2.1-rc.3（web profile / 桌面端）、Node >= 20。
核心功能¶
曲库与直接播放¶
- 导入 MP3：点「导入」多选文件，或把 MP3 拖进悬浮窗；文件会写入 DSH 数据目录，重启后仍在。
- 曲库：记录标题、时长、大小；单击选中、双击直接播放。
- 控制：播放 / 暂停、上一首 / 下一首、拖动进度、音量、静音、循环。
- 悬浮窗：拖标题栏移动，拖右边缘 / 下边缘 / 右下角缩放；折叠、隐藏为右下角悬浮球；位置与尺寸会记住。
也可把 MP3 复制到数据目录下的 tracks/，在播放器里点「刷新」重建索引；失效条目会被清理。
启动动画同步¶
同步依据动画的真实生命周期，而不是固定秒数：
| 启动动画 | 开始信号 | 结束信号 |
|---|---|---|
长征机（dsh-startup-secret，优先） |
#dsh-startup-root 移除 dsu-boot |
root 移除 / dsh-startup:done |
dsh-theme-prts |
html[data-prts-startup-active] 出现 |
属性移除 / 覆盖层移除 |
| 无启动动画 | 不会播放 | — |
音频比动画长时，只保留与动画时长相同的最前段；比动画短时放完即止。结束渐隐可在 0–3 秒 调节，默认 1.2 秒。若本次会话动画被跳过（例如已播过），启动音频不会擅自播放。
浏览器 / Electron 的自动播放策略可能要求一次用户点击后才出声；若启动音频被拦截，播放器会等待页面上第一次点击，再把音频对齐到动画当前进度。
持久化与 API¶
音乐、曲库、音量、模式、窗口状态保存在 %USERPROFILE%\.dsh\dsh-audio-player\（曲库 library.json，设置 config.json）。宿主路由包括 /dsh-audio-player/app.js、/api/state、/api/config、/api/tracks、/api/media/<id>（支持 HTTP Range）。自定义路由经 DSH connection 的信任栅栏，未认证请求返回 401。
MP3 要求标准 MPEG 音频（ID3v2 或帧同步头均可），单文件 <= 200 MB。
安装与启用¶
插件以当前 DSH 进程权限运行；安装前建议浏览源码与 MIT 许可证，确认符合你的环境策略。
从 GitHub 安装（Web profile）¶
在资料给出的命令如下。安装后需重启 dsh web 并刷新页面。
dsh plugin --profile web add github:edgewalker6666/dsh-audio-player
本地脚本安装（桌面端推荐）¶
在插件目录执行（README 示例为 desktop profile）：
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Profile desktop
脚本会建立 profile 下 node_modules\dsh-audio-player 目录联接、向 cordis.patch.yml 或 dsh.profile.bundles 登记，并在 profile 的 package.json 中登记本地依赖。完成后退出并重新打开 DSH（桌面端仅刷新页面不会加载新的 index 注入表）；Web 端同样需重启 dsh web 后刷新。
手动步骤见仓库 INSTALL.md。
典型用法¶
- 打开播放器，点「导入」选 MP3，或拖文件进悬浮窗。
- 在「曲库」选中曲目；双击可直接播放。
- 顶部模式在 直接播放 / 启动动画 间切换，或在「设置」里切换。
- 设置可调：直接播放音量、启动动画音量、结束渐隐、循环、重置窗口、打开音频文件夹、复制路径。
- 用标题栏移动窗口，用边缘与右下角缩放；
–折叠，×收成悬浮球。
适用场景与注意¶
适合：希望在 DSH 内常驻 BGM、且不想干扰其它插件音频的开发者；使用长征机或 PRTS 主题启动动画、希望开屏与音乐对齐的用户。
注意：
- 兼容性以 README 为准：Chromium 系（Electron / Edge / Chrome），需
HTMLAudioElement与 Shadow DOM。 - 卸载可用
uninstall.ps1 -Profile desktop，只移除安装登记与node_modules联接，不会删除~/.dsh/dsh-audio-player/里的音频与设置。 - 若重启后无悬浮窗，检查 profile 的
node_modules、桌面端cordis.patch.yml中- id: dsh-audio-player，避免 bundle 与 patch 重复登记；导入报 415 多为非有效 MP3。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区索引，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-audio-player 把 MP3 播放、曲库与可选启动动画同步收进 DSH 内部，音频链路与其它插件隔离。需要安装命令、数据路径与排查表时，以仓库 README 为准。
