dsh-music-player-tui

DeepSeek Harness TUI 界面（dsh-tui）的本地音乐播放器插件。输入 /music 打开全屏「音乐」场景（与 /trace 轨迹场景同款机制），在终端里边聊边听歌。

A local music player plugin for the dsh-tui terminal front door — /music opens a full-screen scene (same machinery as the /trace trajectory scene) so you can listen while you chat.

快速安装 / Quick Install

前置条件：已安装并能运行 dsh-tui（≥ 0.8，首次运行会自动初始化 profile）。

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

重启 dsh-tui，输入 /music 回车——全屏场景出现即成功。想锁定版本：github:heshuren371/dsh-music-player-tui#v0.3.0。

建议再装个 mpv（brew install mpv）：无缝暂停、即时音量/seek、精确进度，听感最好；没有也不影响使用（自动回退 ffplay/afplay）。

功能 / Features

• 📁 本地目录递归扫描：flac / mp3 / m4a / aac / ogg / opus / wav，内嵌标签解析（缺省回退「歌手 - 歌名」文件名约定）
• 🎵 曲目列表：歌名、歌手、时长；↑/↓ 或 j/k 选择，窗口随终端高度自适应
• 🔀 排序：歌名 / 歌手 / 时长，升降序切换；播放顺序 = 可见列表顺序（排序/搜索后，「下一首」就是你看到的下一行）
• 🔍 搜索过滤：歌名 / 歌手 / 文件名
• 🔁 循环模式：列表循环 / 单曲循环 / 播完即停
• ⏩ 快进快退：←/→ ±5s（Shift ±30s）；音量 +/- 调整（每次 5%）——mpv 后端下即时生效、无接缝
• ⏯️ 退出场景音乐不中断：播放进程由宿主 spawn，关掉场景照样唱，随时 /music 回来
• 🗑️ 删除曲目：场景内 x 二次确认（本地文件一并删除，不可恢复），或 /music delete <关键词>（需唯一匹配）
• 💾 状态持久化：目录 / 音量 / 循环模式 / 最后播放曲目与进度（~/.dsh-music-player-tui/state.json，旧版包内 lib/state.json 自动迁移），重启后曲目以暂停态 cue 在原位置
• 🎛️ /music 子命令直达：dir / play [关键词] / pause / next / prev / vol / refresh / delete，不进场景也能操控
• 🧩 标准 bundle 插件：零核心改动，进插件清单，卸载即净

播放后端 / Playback backends

TUI 没有浏览器，播放靠宿主本机的播放器进程（自动探测，先到先得）：

后端	说明
mpv	推荐。JSON IPC 常驻进程：换歌不重启解码（切歌无间隙）、暂停/继续干净无爆音、音量与 seek 即时写入、time-pos 精确进度。brew install mpv / apt install mpv
ffplay（ffmpeg）	备选。全格式、快进快退（-ss 重启解码，有极短接续缝）；暂停靠 SIGSTOP 冻结进程，个别机器上可能有缓冲残响。brew install ffmpeg / apt install ffmpeg
afplay（macOS 自带）	兜底。不能快进快退，音量在下次起播时生效

三个都没有时插件照常挂载，起播会提示安装 mpv/ffmpeg。ffplay 后端的暂停依赖 POSIX 信号（SIGSTOP/SIGCONT），Windows 建议直接装 mpv。

键位 / Keys（场景内）

键	功能
Enter	播放选中曲目
Space	暂停 / 继续
↑/↓ 或 k/j	移动选择（PageUp/PageDown 翻页，Home/End 首尾）
n / p	下一首 / 上一首
← / →	快退 / 快进 5s（Shift = 30s，仅 ffplay）
+ / -	音量 ±5%
s / r	切换排序字段（歌名→歌手→时长）/ 切换升降序
l	循环模式（列表 → 单曲 → 播完即停）
/	搜索（Enter 确认，Esc 取消）
u	设置音乐目录（粘贴路径，Enter 确认；支持 ~）
x	删除选中曲目（再按一次 x 确认；本地文件一并删除，不可恢复）
R	重新扫描当前目录
q / Esc	退出场景（音乐继续播放）

/music 子命令

/music                  打开全屏音乐场景
/music dir <路径>        设置目录并扫描（如 /music dir ~/Music）
/music play [关键词]     播放当前/第一首；带关键词播首个匹配曲目
/music pause            暂停 / 继续
/music next | prev      切歌
/music vol <0-100>      音量
/music refresh          重新扫描
/music delete <关键词>   删除曲目文件（需唯一匹配，不可恢复）

生态规范符合性 / Ecosystem compliance

本插件按 dsh-ecosystem-spec（dsh-TUI 生态准入规范 v0.15，Experimental）开发，包根提供标准清单 dsh-plugin.json：

• TUI-PKG-001：清单通过固定 revision 的 @dsh-std/manifest Community v0.15 解析（manifestVersion: 0.15、host facet v1alpha1、稳定 id dsh-music-player-tui）。
• TUI-PKG-002：声明闭环——所需协议（commands.dsh/v1alpha1 Command）、权限（commands.invoke）、贡献（/music 命令 + tui.dsh/v1alpha1 Scene 全屏场景）全部静态声明；不声明 provides / requires.services；无消息订阅。
• TUI-RUN-001：不假定运行机器有浏览器或 GUI；声音由运行 dsh-tui 宿主的那台机器上的本机播放器进程发出。远程 / headless 环境下场景与命令照常工作，宿主机没有播放后端时只提示安装 mpv/ffmpeg，不影响其他功能。插件不声明 remote attach 兼容。
• TUI-OBS-001：命令注册、场景注册、播放进程、定时器全部归属单一 activation，deactivate/卸载时经 cordis effect 统一 dispose，不留可调用 handler。
• TUI-OBS-002 清理语义：
  • deactivate / 退出 dsh-tui：装配层摘除命令与场景，mpv 常驻进程与 ffplay/afplay 子进程一并退出；
  • 卸载（dsh plugin remove）：仅移除插件包；不触碰你的音频文件；
  • purge：状态文件 ~/.dsh-music-player-tui/state.json（目录、音量、循环模式、断点）卸载后仍保留，彻底清除请手动删除该目录。≤0.2 版写在包内的 lib/state.json 会被自动读取迁移，可安全删除。
• TUI-TRUST-001 信任披露：本插件以 trusted-in-process 方式运行在 dsh-tui 宿主进程内，不是沙箱。清单中的 permission 仅用于兼容性展示与授权提示，不构成 OS/进程级安全边界。插件实际能力：读取你指定的音乐目录（递归扫描音频标签）、spawn 本机播放器进程（mpv/ffplay/afplay）、在你于场景内二次确认或命令唯一匹配时删除对应曲目文件。除此之外不读写任何文件、不访问网络。
• TUI-DEP-001：依赖闭包仅 music-metadata（纯 JS，无 native/build 步骤、无 override/patch）；状态优先写入用户目录，已安装包目录保持只读，artifact digest 可复验。

本地复验（需要 dsh-ecosystem-spec 检出且 vendor/dsh-std 已构建）：

npm run validate:manifest -- /path/to/dsh-ecosystem-spec
# 或设置环境变量 DSH_ECOSYSTEM_SPEC_DIR=/path/to/dsh-ecosystem-spec

校验内容：清单解析、profile 坐标闭环、Manifest 投影与扩展贡献校验、命令/场景 identity 与运行时代码一致性，以及对规范示例 host 的 admission decision（预期 compatible）。

规范当前为 Draft/Experimental：本插件声明的是「实验适配」，不代表官方认证或对所有 DSH Host 的兼容性承诺。

卸载 / Uninstall

dsh plugin --profile dsh-tui remove @local/dsh-music-player-tui

重启 dsh-tui 即彻底移除（装配层自动清理，播放进程随之退出）。插件只读你的音乐文件，卸载不动任何音频。状态文件保留在 ~/.dsh-music-player-tui/state.json，不需要断点续播时手动删掉即可。

结构 / Structure

dsh-plugin.json  dsh-TUI 生态准入清单（Community v0.15 manifest：命令/场景/权限声明）
lib/index.js     cordis 入口：/music 命令 + 场景注册 + 扫描/删除调度 + state.json 持久化
lib/player.js    播放引擎：mpv JSON IPC（常驻进程）/ ffplay / afplay 探测与降级、无缝暂停与音量、循环接力、精确进度
lib/scanner.js   目录扫描 + music-metadata 标签解析（与 web 版同一套逻辑）
lib/scene.js     全屏场景：宿主 React/ui 渲染（契约要求，无 JSX、无自带 React）
scripts/validate-manifest.mjs  本地准入校验（复用规范 conformance 机制）

与 Web 版 dsh-music-player 的关系：扫描/标签解析/删除安全校验逻辑共享，播放引擎重写（浏览器 <audio> + Range 流 → 本机播放器进程），UI 按 dsh-tui scenes 契约全新实现。

dsh-TUI · 插件市场 · 一个为 dsh-TUI 生态打造的插件

License

MIT