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 | 状态 |
|---|
| 1.3.0 | 0.2.0 | 推荐（npm latest / lts）。新增：① 卡片音量调节；② 滚动歌词（逐字卡拉OK，五平台歌词 + 音源脚本 lyric）；③ **系统媒体控件（SMTC）**元数据/封面与硬件媒体键。也兼容 0.1.7 / 0.1.5 |
| 1.2.3 | 0.2.0 | 仍可用（无歌词/音量 UI/SMTC）。修：音源持久化、切歌竞态、不再在升级/卸载时删数据 |
| 1.2.2 | 0.2.0 | ⚠️ 不建议再用：导入的音源只写进兜底文件、重启后可能"消失"；升级插件可能清空本机数据 |
| 1.1.0 | 0.1.7 | 仍在 0.1.x 的用户用它（也兼容 0.1.5）。⚠️ 0.2.0 及以上无法激活（插件不工作）；能升级 DSH 就换 1.3.0 |
| 1.0.x | 0.1.7 之前 | 历史版本。（例外：1.0.2 只配 0.1.7 及以后；1.0.1 只配 0.1.5 及更早） |
怎么选：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 在当前内核不支持时自动降级为不做任何事（不影响播放）。
文档
| 文档 | 内容 |
|---|
| 架构与阅读指南 | 先看这个：文件职责表、四条主数据流、不能碰的硬约束、"我要改 X 该动哪里"、已知技术债 |
| 技术说明 | 架构、音源脚本沙箱与安全模型、Electron 宿主、codec 双契约、存储与本地数据、排查手册 |
| 版本台账 | 插件 × DSH 对照、每次 DSH 跳跃的断裂点、发布流程与 dist-tag 规则 |
| 开发文档 | 本地构建/调试/打包/测试、按 DSH 版本安装、验收清单 |
| 画像设计 | 音乐画像的算法设计与验证结论 |
