前言¶
DeepSeek Harness（DSH）采用「一切皆插件」的理念，将各种能力以插件形式挂载到宿主上。音乐播放是高频且耗资源的场景：如果每次都把曲库塞进对话上下文，不仅会撑大系统提示，还会带来额外的 token 开销。尤其是本地音乐库规模较大时，这种做法会明显拖慢响应速度。
dsh-music-local 是一个本地音乐播放器插件，它的核心目标是在保持播放功能完整的前提下，做到零 token 消耗。
是什么¶
dsh-music-local 是 DeepSeek Harness 的本地音乐播放器插件，由维护者 xiao000xue 编写。
它把一个音乐根目录下的每个子目录（树形，任意深度）当成一个播放列表，支持直接流式播放音频文件。插件不做文件头读取，也不做转存或修改，所有播放都通过浏览器半体 ↔ 宿主 HTTP 路由完成，与 LLM 对话上下文完全解耦。
插件要求 DSH >= 0.2.0、Node >= 20。可选依赖 ffmpeg 仅用于 dts / dsd / ape 这类需要转码的格式。
为什么是零 token¶
插件刻意不执行以下操作：
- 不注册
music_play之类的模型工具 - 不往系统提示里注入音乐库清单
- 不使用
inject: ['llm', 'tools', 'systemPrompt'] - 不把曲库内容塞进对话上下文
因此它不会出现在模型的工具列表里，也不会撑大系统提示。音乐库的浏览、搜索、播放、切歌全部发生在浏览器半体 ↔ 宿主 HTTP 路由之间，与 LLM 毫无关系。无论你放 38 首歌还是 3.8 万首歌，每轮对话的 token 开销都是 0。
安装与启用¶
在 profile 目录里把插件装成依赖，下面三种方式任选其一。
方式 A — 直接从 GitHub 装（推荐）
cd "$DSH_HOME/profiles/desktop"
pnpm add github:xiao000xue/dsh-music-local
方式 B — 已经有本地源码副本
cd "$DSH_HOME/profiles/desktop"
pnpm add file:D:/dsh-plugins/dsh-music-local
方式 C — 完全不用包管理器
把本仓库整个目录复制到 $DSH_HOME/profiles/desktop/node_modules/dsh-music-local。插件不依赖任何第三方运行时库，有 lib/ 与 cordis.patch.yml 就能跑。
装好之后，在 profile 的 package.json 里把插件挂进 bundles，然后重启 DSH：
{
"dependencies": {
"dsh-music-local": "github:xiao000xue/dsh-music-local" // ← ① 依赖（随安装方式而定）
},
"dsh": {
"profile": {
"bundles": [
// ... 其它 bundle ...
"dsh-music-local" // ← ② 挂载
]
}
}
}
profile 位于 $DSH_HOME/profiles/<profile名>/package.json（桌面端通常是 desktop）。
插件自带的 cordis.patch.yml 会被自动读取（由 package.json 的 dsh.bundle.patch 声明），无需手改 profile 的 patch 文件。
使用¶
重启 DSH 后：
- 输入框下方会出现一条播放条，支持上一首 / 播放暂停 / 下一首 / 进度 / 音量 / 打开面板。
- 点右侧按钮展开播放面板（浮层，可拖动、可缩放，位置记在
localStorage）： - 左栏 = 树形歌单：音乐根目录下的每个子目录（任意深度）都是一个歌单节点，支持 ▸/▾ 逐层展开收起（展开状态记在
localStorage），歌单名右侧的数字是该文件夹（含子文件夹）的曲目数。 - 右栏 = 选中歌单的曲目，支持搜索框过滤（在哪个歌单里搜就只搜它的子树）。
- 点一行 = 播放（再点当前这首歌 = 播放/暂停），双击 = 从头播放。
- 顶部 = 设置，可改音乐根目录、重扫。
- 面板里右键 / 悬停曲目可以看到解析出的「歌手 - 歌名」。
设置的存放位置¶
| 文件 | 内容 |
|---|---|
$DSH_HOME/music-local.json |
音乐根目录、扫描开关等 |
$DSH_HOME/music-local-prefs.json |
上次播放曲目、播放模式、音量 |
$DSH_HOME 即 DSH 的数据目录（桌面端由机器级环境变量 DSH_HOME 指定）。
格式支持¶
分成两条路：
① 浏览器原生可播（直接给出 206 Partial Content + Range，秒开、可任意拖动）
mp3 m4a m4b m4r aac flac wav ogg oga opus webm
aif aiff aifc alac mp4 caf 3gp
② 需要 ffmpeg 实时转码（dts / dsd / ape 这类浏览器不认的格式）
dts dff dsf ape wma asf wv tta mpc tak ofr
ac3 eac3 amr au snd mid midi spx m4p
mkv avi mov flv rm rmvb wmv mpg mpeg ts vob
转码走管道，不落盘：ffmpeg -i <文件> -f s16le -，边解边送。
已探到时长时会在上方拼一个定长 WAV 头，于是 Range 请求能换算成 -ss 秒数，拖动进度条可用；探不到时长则回退为流式 WAV（能播，但不能精确拖动）。
ffmpeg 自动挑选¶
机器上可能装了好几份 ffmpeg.exe，其中不少是精简版（--disable-everything，只认识 mp4/mp3/flv），拿它转 dts 会直接 Invalid data found when processing input。
插件启动后会在常见位置搜 ffmpeg 并打分：
-muxers里有E s16le→ +4（能输出裸 PCM，转码才可用）-demuxers里有dts/dsf/dff/ape/asf/avi→ 每项 +1
得分最高的那份才会被用来转码，且会被真实解码验证。找不到或只有精简版时，面板「设置」里会明确标注是 完整版 / 精简版 / 未找到 ffmpeg，第 ① 类格式依旧正常播放。
性能¶
- 扫描：只解析文件名，不读文件头。3.8 万个文件约 3 秒。
- 缓存：扫描结果常驻内存，只做一次；之后所有请求都是内存命中（
/manifest、/tracks从 ~3.2 s 降到个位数毫秒）。 - 列表渲染：15k 行用原生 DOM + 分页（默认 300 条一页），不走 React 重渲染，滚动不掉帧。
- 曲名解析：文件名里
歌名-歌手与歌手-歌名混着来。用「配对对象去重计数」判定 —— 歌名只会配对到一个歌手，歌手会配对到很多歌名。比纯词频稳，能扛住「车载合辑里大量重名文件」这种脏数据。
HTTP 路由一览¶
宿主半体注册在前缀 /dsh-music-local 下：
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /config |
根目录、曲库统计、ffmpeg 探测状态 |
| POST | /config |
改根目录并重扫 |
| GET | /manifest |
播放列表 + 曲目清单（紧凑编码） |
| POST | /rescan |
强制重扫 |
| GET | /tracks |
分页取曲目（?ids=1 取 id 列表，?q= 过滤） |
| GET | /track |
单曲详情 |
| GET | /browse |
浏览目录（用于设置里选根目录） |
| GET | /probe |
探测时长 |
| GET | /stream/<id> |
音频流（支持 Range；转码轨用 ?t=<秒>&d=<时长>） |
| GET/POST | /prefs |
播放偏好读写 |
已知限制¶
- 转码轨的精确拖动依赖「能探到时长」，个别损坏文件的时长探测会失败，此时该曲不能精确 seek。
- 精简版 ffmpeg 只能转 mp4/mp3 类，第 ② 类格式会播不了 —— 面板会提示，放一份完整版 ffmpeg 到常见路径即可。
- 播放器不使用音频可视化（
createMediaElementSource在 DSH 里会导致静音），这是有意的取舍。
适用场景与注意¶
适合在本地有较大音乐库、希望保持对话上下文轻量、同时享受流式播放与树形歌单体验的场景。
插件以当前 DSH 进程权限运行。安装前应检查源码与许可证，确保符合你的使用环境。
短结尾¶
dsh-music-local 通过解耦 LLM 上下文与播放逻辑，实现零 token 消耗的本地音乐播放。它把目录结构转化为树形歌单，支持常见音频格式，并提供流式播放与进度拖拽。目录页与源码仓库见下：
- https://www.skillhub.cn/plugins/xiao000xue/dsh-music-local
- https://github.com/xiao000xue/dsh-music-local
