在 DeepSeek Harness (DSH) 的 TUI 插件生态中，与第三方应用集成是常见需求。当用户在 dsh-TUI 中运行 YesPlayMusic TUI 时，需要一种方式在不打断当前终端流的情况下查看播放状态和控制播放。dsh-music-tui 插件通过命令接口和状态栏集成，解决了这一问题。
该插件为 dsh-TUI 提供了对 YesPlayMusic TUI 的控制能力与正在播放状态展示。它通过 /music 命令与顶部的音乐条组件工作，不修改 DeepSeek Harness、dsh-TUI 或 YesPlayMusic 本体源码。
核心功能¶
插件主要包含以下能力：
- 命令控制：提供
/music命令族，用于显示/隐藏音乐条、查看状态、切换播放/暂停、切歌及跳转进度。 - 音乐条显示：在提示框上方展示小封面、曲名、歌手、实时进度、实时频谱以及控制按钮（上一首/播放暂停/下一首/关闭）。
- Kitty Graphics 支持：在支持 Kitty graphics 的终端中，封面会显示为平滑的真图。
- 频谱样式：内置
blocks、led、braille、shade四种紧凑样式，且可跟随 YPM 的设置。 - 富状态视图降级：在旧版宿主或窄屏环境下，自动降级为一次性显示详情，保留核心控制功能。
前置条件¶
在安装前，请确保环境满足以下要求：
- Node.js：
^22.19 || >=24 - dsh-TUI：版本需在
>=0.9.2 <0.11.0之间 - YesPlayMusic TUI 及 ypm CLI：插件通过公开的 CLI 进行控制，实时频谱需要此版本支持
安装与启用¶
当前版本为 v0.1.0。通过以下命令克隆仓库并安装：
git clone --branch v0.1.0 --depth 1 https://github.com/Nagi-ovo/dsh-music-tui.git && cd dsh-music-tui && pnpm install --frozen-lockfile && pnpm build && dsh plugin --profile dsh-tui add "$PWD"
安装后，插件会加载配置。音乐条默认隐藏，需通过命令唤出。
典型用法¶
使用 /music 命令进行交互：
/music show：打开音乐条/music hide：关闭音乐条/music status：一次性显示曲名、歌手、专辑与进度详情/music toggle：切换播放/暂停/music next：播放下一首/music prev：播放上一首/music seek <秒>：跳到歌曲的绝对时间（例如/music seek 90.5）
在 fullscreen 模式下，进度条支持点击定位与拖动预览；inline 模式则需使用 seek 命令。
配置¶
默认配置写入 cordis.patch.yml，主要项如下：
| 键 | 默认值 | 说明 |
|---|---|---|
executable |
ypm |
CLI 名称或绝对路径 |
showStatus |
true |
是否启用音乐条；设为 false 时仅保留命令功能 |
pollIntervalMs |
3000 |
在线轮询状态间隔 |
timeoutMs |
3000 |
单次 CLI 调用超时 |
spectrumStyle |
follow |
频谱样式：off / follow / blocks / led / braille / shade |
如需覆盖配置，可在 profile 的 cordis.patch.yml 中按同一 id 写入完整配置。
注意事项¶
- 依赖运行：插件不会自动启动 YesPlayMusic TUI。必须先在后台或另一个终端启动 ypm，再启动 DSH。
- 权限边界：插件仅调用公开的
ypmCLI，不直连私有 Unix Socket，也不修改宿主或目标应用的源码。 - 安全与信任：插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。
- 状态同步：控制结果仅返回“已发送”，不自动确认播放完成，需通过重新读取状态确认最终结果。
