音乐条控制 Nagi-ovo/dsh-music-tui

dsh-music-tui

在 dsh-TUI 里查看并控制已经运行的 YesPlayMusic TUI。插件提供 /music 命令和提示框上方的紧凑音乐条，不修改 DeepSeek Harness、dsh-TUI 或 YesPlayMusic 本体，也不会自动启动播放器。

能做什么

- /music 或 /music show：打开音乐条（默认隐藏）
- /music hide：关闭音乐条
- /music status：一次性显示曲名、歌手、专辑与进度详情
- /music toggle：发送播放/暂停切换
- /music next：发送下一首
- /music prev：发送上一首
- /music seek ：跳到歌曲的绝对时间，例如 /music seek 90.5
- 音乐条显示小封面、曲名、歌手、进度、实时频谱和上一首/播放暂停/下一首/关闭按钮

fullscreen 模式下，鼠标按钮与 slash 命令等价，进度条支持点击定位和拖动预览；松手时只发送一次 seek。inline 模式请使用 /music seek 。控制正在等待时会暂时禁用重复操作，切歌或暂停不会擅自打开、关闭音乐条。富状态视图可用时最多占三行，并随终端宽度降级：窄屏优先保留三个控制和关闭按钮。旧版宿主没有常驻状态行，/music 会返回一次性详情。
按钮图标跟随 YPM 的 icons = "unicode" | "nerd" 设置；旧 YPM 没有上报该字段时安全回退到 Unicode。
宿主支持 Kitty graphics 时封面会显示为平滑真图；其他终端、inline、辅助功能模式或终端多路复用器会自动使用同尺寸的半块字符缩略图，不需要额外配置。
终端达到 80 列时，音乐条右侧才订阅真实音频频谱；80/96/120 列分别使用 12/18/24 格，超过 120 列后每增加 2 列再增加 1 格，最多 48 格。窄屏会释放本插件的频谱订阅；若 YPM 自身没有显示频谱，分析器也随之停用。内置 blocks、led、 braille、shade 四种紧凑样式，也可以跟随 YPM 当前支持的同名样式。

控制结果只会说“已发送”。YesPlayMusic 的 CLI 确认的是命令已接收，而不是播放器已经完成切歌；插件随后会重新读取状态，绝不把确认包冒充最终播放状态。
播放器离线时音乐条会保留并提示重新启动；若 YPM 声称正在播放、但远端进度连续 6 秒没有前进，音乐条会停止可能失真的频谱并提示重启，状态恢复后自动重连。

前置条件

- Node.js ^22.19 || >=24
- dsh-TUI >=0.9.2 <0.11.0
- YesPlayMusic TUI 及其 ypm CLI （当前验证版本：ypm 0.11.0；实时频谱需要此版本）
- macOS 或 Linux；ypm 的 TUI 远程控制面使用本机 Unix socket

先确认 ypm 在 PATH 中：

ypm --version

安装

当前版本通过 GitHub Release 分发。从对应 tag 安装本地工作树：

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"

参与开发时，省略 --branch v0.1.0 --depth 1 即可使用最新分支。

先在另一个终端或后台启动 YesPlayMusic TUI，再启动 DSH：

dsh --profile dsh-tui

不需要改 YesPlayMusic 源码，也不需要在 YesPlayMusic 仓库里安装插件。
本插件不会替你启动或关闭 YesPlayMusic。

音乐条的显示状态只属于当前 TUI。你在一个 TUI 里执行 /music，不会打开其他 TUI 的音乐条；多个 TUI 的播放控制仍会操作同一个 YesPlayMusic TUI 实例。

配置

默认配置已经写进 cordis.patch.yml：

| 键 | 默认值 | 说明 |
| executable | ypm | CLI 名称或绝对路径 |
| showStatus | true | 是否启用可由 /music 打开的音乐条；启动时仍保持隐藏 |
| pollIntervalMs | 3000 | 在线轮询间隔（1000 至 60000 ms） |
| timeoutMs | 3000 | 单次 CLI 硬超时（250 至 30000 ms） |
| spectrumStyle | follow | off / follow / blocks / led / braille / shade |

showStatus: false 不会注册音乐条；此时 /music 与 /music show 退化为一次性详情，status 与播放控制仍可用。宿主没有富视图能力，或富视图因键冲突/行预算被拒绝时也采用相同降级，不启动后台轮询。

要覆盖配置，在 profile 自己的 cordis.patch.yml 里按同一行 id 写完整配置：

- id: dsh-music-tui
config:
executable: /absolute/path/to/ypm
showStatus: true
pollIntervalMs: 3000
timeoutMs: 3000
spectrumStyle: follow

设计边界

dsh-TUI /music + status
│
▼
@dsh-tui-ecosystem/music
│ execFile / spawn(argv), no shell
▼
ypm --json --tui …
│
▼
running YesPlayMusic TUI

- 插件只调用公开 ypm CLI，不直连私有 Unix Socket。
- 目标固定为 TUI；不会在 GUI 与 TUI 之间猜测。
- 播放状态不写入 DSH 会话日志。只有 DSH 命令注册表正常产生的 command/run / command/done 记录。
- 外部 JSON、stderr 和歌曲元数据全部校验、去终端控制字符并限制长度。
- 音乐条注册成功后默认每 3 秒读取一次状态；播放时每秒在本地推进显示进度，暂停时冻结。一次读取失败保留旧状态，连续两次失败才清除；离线后轮询退避。
- 频谱只在音乐条可见、存在歌曲且终端至少 80 列时，通过公开的 ypm --json --tui spectrum --fps 12 NDJSON 流订阅。协议固定为 32 个取值范围为 0 至 255 的 bins；不读取 PCM、不直连 socket，断流会清掉旧画面并有界退避重连，隐藏、变窄或卸载会中止子进程。
- follow 只跟随 YPM 的 blocks、led、braille、shade；遇到其他样式安全回退为 blocks。重复帧不会触发无意义的 TUI 重绘。
- 新版 ypm 通过 seekable 显式宣告 seek 能力，并用 iconStyle 投影用户已选的图标模式。
旧版未上报时，进度仍可读、但不会伪装成可拖动，图标回退到 Unicode。
- 新版 ypm 可选返回 coverUrl。插件只下载 HTTPS music.126.net 及其子域的 JPEG/PNG（按文件魔数识别，兼容 CDN 错标响应头），每次重定向都重新校验，并限制为 2 秒、256 KiB 与 1024×1024 像素；失败只显示占位封面。
- 封面只在 URL 变化时读取，内存最多缓存 16 张。旧版 ypm 没有 coverUrl 时文本与控制照常工作。
- 图片由插件解码成 96×96 RGBA，并同时生成 6×3 字符回退；Kitty 协议探测、上传、定位与清理由宿主统一负责，插件不会直接向终端写转义序列。
- 卸载时清理 timer、命令、音乐条、封面请求并中止子进程。
- 音乐条以能力探测接入富状态视图，不提高 dsh-TUI ^0.9.2 的最低兼容版本；没有富视图 API 时只保留 /music 的一次性详情和播放控制，不创建常驻状态，也不轮询。
- 当前 DSH profile loader 仍用 Cordis bundle 挂载第三方插件；命令在没有 verified Component identity 时走规范记录的 C-070 同进程兼容路径。
dsh-plugin.json 的 host entry 是独立的标准 FacetModule；adapter-dsh 存在时，它会先接管 /music，旧 Cordis 注册随即让位，避免双注册。两条路径共用同一命令实现与已配置的 controller。

当前信任模型是 trusted-in-process：manifest 权限用于兼容性、授权和审计，不是进程隔离或安全沙箱。

本地开发与验证

pnpm install --frozen-lockfile
pnpm verify

本地装进 profile：

dsh plugin --profile dsh-tui add "$PWD"

然后分别验证：/music 的 show/hide/status/toggle/next/prev/seek、fullscreen 点击与拖动进度、 32/60/80/96/120 列布局和四种频谱样式，以及旧宿主降级、播放器离线、ypm 不在 PATH 和插件卸载。

许可证

MIT