DeepSeek Harness 插件：本地音乐播放器

前言¶

DeepSeek Harness（DSH）的设计理念之一是“一切皆插件”。对于需要在本地管理媒体资源的开发者或用户，在会话视图中直接嵌入播放器比打开外部应用或文件浏览器更高效。本地音乐播放器插件正是为此设计，它将播放功能集成到 DSH 的会话视图标签环中。

插件介绍¶

该插件由开发者 heshuren371 维护，是一个基于 Web 技术实现的本地音乐播放器。它在会话视图的标签页中增加了一个“音乐”标签，提供 macOS Music 风格的 UI，支持常见音频格式，并具备元数据补全、均衡器等高级功能。

核心功能¶

插件通过递归扫描本地目录来管理音乐库，支持以下功能：

文件支持：支持 FLAC、MP3、M4A、AAC、OGG、Opus、WAV、MP4、MOV、WebM、MKV、AVI 等常见格式。
波形与进度：基于 FFmpeg 解码音频并提取峰值，显示真实波形进度条。
均衡器：提供 10 段均衡器，内置原声、流行、摇滚、古典、爵士、低音增强、人声、电子等预设曲线。
播放控制：默认开启 300ms/700ms 的交叉淡化切歌功能，支持单曲循环与列表循环。
元数据管理：支持在线补全元数据（QQ音乐、iTunes、网易云、MusicBrainz），标签写入采用原子化操作，支持重命名文件。
ReplayGain：提供响度归一化功能，优先读取文件内嵌标签，支持单曲/专辑模式。
系统集成：集成 MediaSession，支持锁屏显示与控制中心通知。
视频支持：支持 MV 三档判定（direct/remux/transcode），并调用 FFmpeg 进行缓存处理。

安装与启用¶

安装前请确保系统已安装 Node.js（^22.19.0 || >=24.0.0）和 pnpm，并已安装 FFmpeg。

安装插件：

    dsh plugin --profile web add github:heshuren371/dsh-music-player

检查安装：

    dsh plugin --profile web ls

启用插件：
安装后需重启 dsh web 并刷新页面，在会话顶部的标签环中找到“音乐”标签页即可使用。

开发与调试¶

插件源码基于 TypeScript 编写，构建产物提交至仓库。如需开发调试：

git clone https://github.com/heshuren371/dsh-music-player.git
cd dsh-music-player
pnpm install
cd .. && dsh plugin --profile web add link:./dsh-music-player
pnpm run dev

网络调试：确认插件 API 通路正常：

curl -s -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:<端口>/dsh-music/api/session"

常见问题：
* Desktop 端限制：CLI 拒绝写入文件，需通过应用菜单安装，安装后需重启应用或按 F12 刷新。
* 标签不显示：确认 dsh plugin --profile web ls 中存在该插件，且页面已刷新。

权限与依赖¶

插件运行需要以下权限和依赖：

权限：fs.read（读取音乐）、fs.write（写入标签）、fs.delete（删除文件）、net.fetch（在线补全元数据）、transport.api（API 交互）、storage.local（缓存）。
依赖：Node.js（^22.19.0 || >=24.0.0）、pnpm、FFmpeg（用于波形提取、MV 处理和元数据测量）。

注意事项¶

兼容性：插件支持 DSH >=0.1.6-alpha.1 <0.2.0 || >=0.2.0-0 <0.3.0-0（0.1.7-rc.2 兼容）。
功能限制：插件目前不支持随机播放和歌词页。Apple FairPlay 加密的离线包（.movpkg）无法播放，扫描时会自动跳过。
文件安全：标签写入和重命名文件是原子操作，中途中断不会损坏原文件。