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