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