lx-music-for-dsh

LX Music 增强控制插件 —— 为 deepseek_harness 提供侧边栏播放卡片、播放/音源管理界面与 LLM 点歌能力。开箱即用，不需要任何外部服务。

功能

• 侧边栏迷你播放卡片（位于「设置」按钮上方）：封面、歌名-歌手、可拖动/点击跳转的进度条、 上一首/播放暂停/下一首、音量调节、播放模式切换（列表循环/单曲循环/随机/顺序，点击循环切换）、 播放列表弹窗、设置齿轮。 音量：点喇叭图标弹出一根竖滑块（不常驻占位）；面板由独立组件 src/ui/VolumePopover.tsx 手写 DOM portal 挂到 <body> 并用 fixed 定位， 因此不会被卡片裁断，窗口变矮时还会自动翻到按钮下方。拖动中只本地预览、抬手才同步给 host （避免一次拖动打几十个 remote 调用）。 （歌词入口当前先隐藏：原「词」按钮的位置换成了喇叭；歌词链路本身完整保留， 需要时把 src/ui/Card.tsx 里那段歌词按钮加回来即可恢复。）

• 滚动歌词窗口（入口当前隐藏，链路完整保留）：当前句高亮并自动居中、逐字（卡拉OK）高亮、 翻译/音译、点任意一行跳到那一句、字号调节、「回到当前」、手动滚动后不再抢滚动条。 歌词来源按「音源脚本 lyric action → 内置五平台歌词接口 → lxserver → 演示数据」降级； 拿不到歌词时窗口里直接说明原因（不是每个平台每首歌都有歌词）。

• 系统媒体控件（SMTC / 硬件媒体键）：把歌名、歌手、专辑、专辑封面与播放进度/状态推给 Windows 媒体面板（Electron/Chromium 的 navigator.mediaSession），并把面板与键盘上的 播放/暂停/上一首/下一首/快进快退接回播放器。修掉了"面板一直显示会话名、没有封面"的问题 （那时插件没写 MediaMetadata，Chromium 只能用页面标题兜底）。歌词窗口底部与设置窗口 「音质策略」页各有一行自检信息，告诉你到底推出去了什么（系统面板没有回读 API）。

• 主窗口（点击卡片主体打开，可调大小、记忆位置）：搜索（关键词/歌手/平台过滤）、 搜索结果（音质/时长、+队尾 / +下一首）、播放列表管理（拖拽排序、删除、清空、导出文本）。

• 设置窗口（点击齿轮）：音源管理（文件/URL/粘贴导入并自动启用、启停/删除/排序）、 音质策略（默认音质、平台优先级）、自动拉取规则（切歌自动最高音质、降级策略）。

• 细粒度 LLM 音乐工具集：music_search / music_play / music_playlist / music_prev / music_next / music_control，以及兼容入口 search_and_play； 内置滑动窗口防刷（默认 6 次/分钟）。

• 音乐画像（实验性 · 默认关闭）：music_profile 读口味画像与"可直取"的曲目候选； music_play_song 精确点播一首确定的歌（优先用画像里已确认的平台 id 零搜索播放， 退化到按曲名+艺人严格确认，确认不到就明确失败——不会拿翻唱或别的版本顶替）； music_taste 读写口味（like/dislike/forget/note/summary）。 另随插件注册 skill taste-aware-picking，把"先查画像 → 挑一首确定的歌 → 精确播放"流程版本化。

  ⚠️ 实验性功能，默认关闭：开启入口在 设置 →「实验性」页 → 红色警示 → 「了解风险并开启…」→ 确认框。未开启时：不采集任何收听行为、不写点歌日志、不注册 skill、 卡片上不显示 ♪ 入口。数据全部在本机处理、不上传；本插件不会在卸载/升级时自动删除数据， 需要清理时用「设置 → 实验性 → 清理本机数据」（详见 技术说明 §4）。

快速开始

方式一：npm（推荐）

npm i lx-music-for-dsh@latest
dsh plugin --profile <你的profile> add lx-music-for-dsh@latest

方式二：下载 Release 里的预构建包（离线可用，不需要构建、不需要 allowBuilds）

从 Releases 下载 lx-music-for-dsh-<版本>.tgz，然后：

dsh plugin --profile <你的profile> add <下载下来的 .tgz 完整路径>

装好后 彻底退出并重启 DSH（关窗口不算）——本版本修改插件代码后必须完全重启才会加载新代码， 插件页/卡片会一直显示上一次启动时的旧状态。这是已知问题，会在下个大版本修复。

只改了 client 半边（本版的音量面板、卡片 UI 都属于此类）时，刷新页面即可看到新代码； 改到 host 半边（工具注册、歌词/直链解析、SMTC 桥等）才必须重启进程。

确认是否生效：看 $DSH_HOME/lx-music-plugin-status.json（存在即说明 host 半边被调用过， 里面按阶段记录了 storage 是否就绪、音源落盘后端（sourceStore: domain|file）、注册了几个工具）。 sourceStore 必须是 domain —— 若是 file，说明音源只写进了兜底文件 $DSH_HOME/storages/lx-music-sources.json。排查步骤见 技术说明 §5.2。

DSH 版本兼容性对照表

怎么选：DSH 0.2.0+ → 1.3.0｜DSH 0.1.7 → 1.1.0（或直接升 1.3.0）｜DSH ≤ 0.1.5 → 1.0.1。

• 全部已发布版本、每个版本的可用性说明、发布流程与 dist-tag 规则： docs/versioning.md。
• 升级到 1.3.0 不需要动 DSH 版本；存储布局迁移自动完成（旧 lx_music.json 会改名为 lx_music.json.migrated-<时间戳> 保留，可随时回退）。
• 1.2.2 → 1.2.3 的一个手工动作：若你在 profile 的 cordis.patch.yml 里手写过 cleanupOnUninstall: true，请改成 false（或删掉该行用默认值）——1.2.2 的随包 patch 把它设成了 true，会让每次升级/热重载在 8 秒后删掉 $DSH_HOME/storages/lx_music/（播放列表、设置与音源一起没了）。
• 1.3.0 的歌词/SMTC 是"装了就有"：没有新增配置项，也没有新增 npm 依赖。 歌词拿不到时窗口会写明原因；SMTC 在当前内核不支持时自动降级为不做任何事（不影响播放）。

文档