前言¶

dsh-music-player-tui 是一个面向 dsh-tui 的 DeepSeek Harness（DSH）TUI 插件。它把本地音乐播放器放进终端场景：输入 /music 打开全屏场景，选择本地音乐目录，扫描常见音频格式，再调用本机播放器进程出声。

它主要解决一个具体问题：在 dsh-tui 里边操作边听本地音乐，并且退出全屏场景后音乐不中断。

这是什么¶

heshuren371/dsh-music-player-tui 是 heshuren371 维护的 MIT 许可插件，用于 dsh-tui 宿主。

它的核心思路是：

• 在 dsh-tui 内提供 /music 全屏音乐场景。
• 扫描本地目录中的音频文件，生成曲目列表。
• 由宿主 spawn 本机播放器进程，例如 mpv、ffplay、afplay。
• 退出场景后播放进程继续存在，音乐不停止，随时可以再次输入 /music 回到场景。

核心功能¶

已核实的功能包括：

• 本地目录递归扫描：flac / mp3 / m4a / aac / ogg / opus / wav。
• 内嵌标签解析；缺省时回退「歌手 - 歌名」文件名约定。
• 曲目列表显示歌名、歌手、时长。
• 使用 ↑/↓ 或 j/k 选择曲目，窗口随终端高度自适应。
• 鼠标支持：悬停移动选择光标，点击列表行直接播放。
• 排序：歌名、歌手、时长，可切换升降序；播放顺序等于可见列表顺序。
• 搜索过滤：歌名、歌手、文件名。
• 循环模式：列表循环、单曲循环、播完即停。
• 快进快退：←/→ 调整 ±5s，Shift 下调整 ±30s。
• 音量调整：+/- 每次调整 5%。
• 退出场景后音乐不中断。
• 删除曲目：场景内 x 二次确认，或 /music delete <关键词>。
• 状态持久化：目录、音量、循环模式、最后播放曲目与进度。
• /music 子命令直达：dir / play [关键词] / pause / next / prev / vol / refresh / delete。
• 标准 bundle 插件：零核心改动，进插件清单，卸载即净。
• 播放后端自动探测：mpv、ffplay（ffmpeg）、afplay（macOS 自带）。

安装与启用¶

1、确认前置条件：已安装并能运行 dsh-tui，版本 ≥ 0.8；首次运行会自动初始化 profile。

2、添加插件：

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

3、重启 dsh-tui，输入 /music 回车。全屏场景出现即表示启用成功。

4、建议安装 mpv，以获得更完整的播放控制：

brew install mpv

mpv 后端支持无缝暂停、即时音量/seek、精确进度。没有 mpv 时，插件会探测 ffplay（ffmpeg）或 afplay（macOS 自带）。三个后端都没有时插件照常挂载，起播会提示安装 mpv/ffmpeg。

典型用法¶

安装并设置目录后，可以在 dsh-tui 内使用下面的 /music 子命令：

/music dir ~/Music
/music play
/music play 关键词
/music pause
/music next
/music prev
/music vol 60
/music refresh
/music delete 关键词

对应含义：

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

在 /music 全屏场景内，还可以使用：

• Enter：播放选中曲目。
• Space：暂停或继续。
• q / Esc：退出场景，音乐继续播放。
• x：删除选中曲目，再按一次 x 确认；本地文件一并删除，不可恢复。

播放后端¶

声音由运行 dsh-tui 宿主的那台机器上的本机播放器进程发出。插件会自动探测以下后端：

• mpv：建议安装。支持无缝暂停、即时音量/seek、精确进度。
• ffplay（ffmpeg）：备选后端。暂停依赖 POSIX 信号（SIGSTOP/SIGCONT）；Windows 建议直接安装 mpv。
• afplay：macOS 自带兜底后端。不能快进快退，音量在下次起播时生效。

如果三个后端都没有，插件照常挂载，起播时会提示安装 mpv/ffmpeg。

适用场景与注意¶

适合：

• 在 dsh-tui 里边操作边听本地音乐。
• 希望退出全屏场景后播放不中断。
• 只使用本地音频文件，使用本机播放器进程出声。
• 需要简单的曲目列表、搜索、排序、切歌、暂停、音量控制。

注意：

• 删除曲目会删除本地文件，不可恢复。
• /music delete <关键词> 需要唯一匹配。
• 场景内 x 删除需要二次确认。
• afplay 为兜底后端，不能快进快退，音量在下次起播时生效。
• 三个播放后端都没有时，插件照常挂载，但起播会提示安装 mpv/ffmpeg。
• 插件以 trusted-in-process 方式运行在 dsh-tui 宿主进程内，不是沙箱。
• 它实际会做三件事：读取指定音乐目录、spawn 本机播放器进程、在场景内二次确认或命令唯一匹配时删除对应曲目文件；除此之外不读写任何文件、不访问网络。
• 依赖闭包仅 music-metadata（纯 JS，无 native/build 步骤、无 override/patch）；状态优先写入用户目录，已安装包目录保持只读。
• 状态文件位于 ~/.dsh-music-player-tui/state.json。卸载仅移除插件包，不触碰音频文件；状态文件保留，手动删除该目录可彻底清除。
• 规范当前为 Draft/Experimental：本插件声明的是实验适配，不代表官方认证或对所有 DSH Host 的兼容性承诺。
• 插件以当前 dsh-tui 宿主进程权限运行，安装前应检查源码与许可证。许可证为 MIT。

结尾¶

dsh-music-player-tui 的价值在于把本地音乐播放放进 dsh-tui 场景：可以扫描本地目录、排序搜索、播放暂停切歌、调整音量，并且退出场景后音乐继续播放。

仓库地址：https://github.com/heshuren371/dsh-music-player-tui