光听歌还不够，它还能听书：把本地 .txt/.epub 小说丢给 AI 朗读，想听哪章点哪章、声音随便挑。现在还能听新闻：让 agent 用联网搜索收集当天头条（热点/国内/国际/科技/财经/体育/娱乐，或 AI 等任意自定义主题），整理筛选成口播稿用 AI 声音播报——支持每日多定时任务定时、静默收集、文字版阅读。还能听网络电台：中文主流台（央广/凤凰/CCTV 伴音等，含 HLS 流）与全球电台一键开播。最绝的是它注册了 music_play 等模型工具——你连鼠标都不用动，在对话框里跟 agent 说句「播放周杰伦的歌」，音乐分分钟响起来，摸鱼摸出新境界。

特性

本地音频流式播放，刷新后断点续播
顺序播放、单曲循环、乱序播放三种模式
实时频谱可视化，两种样式可在「系统配置」切换（默认柱状图）：柱状图与波形图（示波器式连续曲线，按低/中/高频分成三条层次线）
实时歌词/字幕：本地歌曲自动显示同步歌词——优先读取文件内嵌歌词（FLAC LYRICS/MP3 USLT 标签，无需额外 .lrc），其次同名 .lrc，都没有时自动在线匹配；在线 QQ 歌曲显示官方歌词（外语歌带逐句翻译）；AI 讲书时显示当前朗读句子。单击播放条歌词可打开完整歌词/字幕面板（标识当前进度、可拖动/拉伸、位置独立记忆），面板默认开启透明模式——歌词像直接悬浮在页面上，可在「系统配置」关闭
播放时防止电脑熄屏/休眠（需浏览器支持，如 Chrome/Edge）
播放条位置可换：在「系统配置 → 播放条位置」（配置页最后一项）里三选一——输入框上方（默认）/ 页面底部 / 悬浮可拖动。悬浮条是紧凑的三行卡片（歌词整行 / 歌名+频谱 / 播放控制，行高固定不随歌词有无跳动），整条可以直接拖着挪地方，位置会记住（配置页可「重置位置」回到默认右下角）；改到底部/悬浮后，播放条不再挂在输入框区域，因此对话里的询问弹窗（会接管输入区）也不会再把它一起盖住——弹窗开着照样能暂停/切歌
滚轮调音量：鼠标停在音量条上直接滚轮即可加减音量，按滚动快慢分两档步进——慢速滚动每次 1%（细调）、快速滚动每次 5%（快速拉大/拉小）；上滚加、下滚减，滚轮被音量条消费，不会连带把外层对话滚走。鼠标滚轮慢慢拨与触控板细碎轻推都算慢速，鼠标快速连拨、触控板用力快滑算快速（阈值见 lib/client.js 的 VOL_WHEEL_* 常量）
播放列表面板可自由拖动，右下角可拖拽调整大小，位置与尺寸跨刷新记忆
AI 讲书：本地 .txt / .epub 小说 AI 语音朗读，自动识别书名/前言/章节/尾声结构，播放条带章节目录跳转（打开即定位到当前正在播放的章节）、章节切换，可选 4 种中文 AI 声音（默认白桦）
music_play 模型工具：agent 可按关键词播放本地音乐，也可按小说名启动 AI 讲书
每日新闻播报：agent 用 web search 收集当天头条（可分类别/自定义主题），整理筛选后 AI 语音播报；播放面板「新闻播报」页签随时回看、挑条目播放、看文字版；支持每日多定时任务定时与静默收集（详见下文「每日新闻播报」）
多标签页统一播放器：同时开多个 DSH 标签页时，所有标签页共用同一个播放器——同一时刻只有一页出声，其余页静音并同步显示同一首歌/同一进度/同一播放状态（曲目、歌手、歌词、播放模式、音量、讲书章节全都一致），在任意一页点播放/暂停、上一首/下一首或直接点歌，都会作用到这个唯一播放器上（详见 FAQ）
支持的格式：mp3 / m4a / m4b / aac / flac / wav / ogg / opus / webm / aiff（自动递归扫描子目录，上限 500 首）
真实音质识别：扫描时自动识别每首歌的音质档位，播放条显示「格式 · 音质档」（如 FLAC · 无损 / MP3 · 高音质 / MP3 · 标准），与在线音乐的音质标签一致
自建歌单：可新建多个歌单，从本地文件（支持多选、可跨目录）添加歌曲；播放条爱心按钮一键收藏到默认歌单「我最喜欢」；歌单作为播放来源时，顺序/乱序循环只在该歌单内进行
在线 QQ 音乐：面板内置「QQ音乐」页签——微信/QQ 扫码登录（解锁 VIP/高音质）、我的歌单/推荐歌单/分类歌单/排行榜/新歌/搜索浏览、卡片式歌单展示、一键收藏到「我喜欢」
在线酷狗音乐：面板内置「酷狗音乐」页签——酷狗 App 扫码登录（解锁高音质）、推荐/分类歌单/排行榜（TOP500 等）/统一搜索/我的歌单，逐字歌词内嵌翻译；详见下文「在线酷狗音乐」
在线网易云音乐：面板内置「网易云」页签——扫码登录后浏览/搜索/播放（免费歌 320k 高音质直链、VIP 歌试听片段）、我的歌单/推荐/分类歌单/排行榜、YRC 逐字歌词与 LRC+逐句翻译；详见下文「在线网易云音乐」
网络电台：面板内置「网络电台」页签——radio-browser 全球开放电台目录（数万台、无登录），按台名/国家/标签搜索，中文电台/热门电台按主题分组浏览、收藏与最近播放；支持 HLS(m3u8) 电台（央广/凤凰/CRI/CCTV 伴音等中文主流台），Host 端纯 Node 把 HLS 转成浏览器直接可播的音频流，无新依赖；music_play 传 source=radio 可按台名直接开播；详见下文「网络电台」

截图

播放本地音乐	播放QQ音乐

播放酷狗音乐	AI讲书

QQ音乐面板	酷狗音乐面板

安装

需要已安装 dsh CLI。

从 npm 安装（推荐，已发布到 registry）

# 把 <profile> 换成实际 profile 名，如 web
dsh plugin --profile <profile> add dsh-music-player

从 GitHub 安装（备用来源）

# 把 <profile> 换成实际 profile 名，如 web
dsh plugin --profile <profile> add github:kendu76/dsh-music-player

安装后重启 DSH，打开 Web GUI：

聊天输入区上方会出现「DSH音乐播放器」播放条
点击右侧「列表」按钮打开播放面板
在面板顶部点击「选择音乐目录」并选定音乐目录（默认 ~/Music），自动递归扫描
之后可直接在对话框里让 agent 播放，例如「播放周杰伦的歌」

配置

插件为「Host 端 + Web 端」双面结构：

Host 端（lib/index.js）：音乐扫描、HTTP 流式、歌单 CRUD/持久化、music_play/news_broadcast/news_schedule 工具、AI 讲书（小说结构解析 + TTS 合成）、新闻播报（期次持久化 + 口播稿渲染分块 + TTS 懒合成）
Web 端（lib/client.js）：浏览器里的播放条 / 播放面板 / 频谱 / 歌单（收藏、一键清空）/ 讲书控制 / 新闻播报页签

两者由一个 cordis.patch.yml 插入 music-player 行并自动组对（在 Web 端 dsh.client 声明即指回该行名并加载浏览器半体）：

- insert:
    - id: music-player
      name: 'dsh-music-player'

播放模式与音量等播放偏好都保存在 Host 端（见下），刷新后当前曲目与进度也会恢复（浏览器的自动播放可能被拦截，点一次 ▶ 即可解锁）。

状态持久化（重要）：所有播放状态都持久化在 Host 端文件 ~/.dsh/music-player-prefs.json，包括：音量、播放顺序、AI 讲书声音、播放范围、面板位置、上次播放的曲目/进度、每本小说的进度、QQ 搜索历史、QQ 面板所在层、QQ「我喜欢」收藏兜底。因此即使在 dsh-desktop 桌面版（每次启动随机端口、浏览器存储按源隔离）下，重启后这些状态照样能找回。 升级兼容：旧版本（<0.7）把同样的键存在浏览器 localStorage 里。升级后客户端优先读 Host，Host 没有的记录会自动回退读取旧 localStorage 副本并迁移进 Host，升级不丢用户数据。音乐/小说目录、自建歌单、QQ 登录态也持久化在 Host 端（见下文），同样不受影响。

自建歌单（收藏）

播放面板「本地音乐」页内新增子标签：曲库 / ♥ 我最喜欢 / ＋，支持自建歌单并把歌单作为播放来源——此时顺序/乱序循环只在该歌单内进行。

新建歌单：点「＋」输入名称即建（可建多个）。
曲库加入：在「曲库」列表每首歌行尾有「＋」按钮，点击可把该曲加入任一已有歌单，或直接新建歌单加入。
添加歌曲：进入某歌单 → 点「添加歌曲」→ 打开本地文件多选框（可多选、可跨目录）加入歌单；歌单内每首歌支持上移/下移排序与移除。
清空歌单：每个歌单（含「我最喜欢」）详情内都有「清空」按钮，二次确认后一键移除全部歌曲（歌曲文件不会被删除）。
收藏：播放条上的爱心按钮一键把当前曲加入默认歌单「我最喜欢」，再点取消；「我最喜欢」固定不可删除/重命名。
播放范围：在歌单里点歌，则顺序/乱序/单曲循环都在该歌单内；在「曲库」点歌则回到全库循环。
命令：music_play 工具新增 playlist 参数，可让 agent 直接播放某个歌单（如「播放歌单我最喜欢」）。
歌单数据保存在 ~/.dsh/music-player-playlists.json，刷新/重启不丢；歌单可包含曲库目录之外的本地音频文件。

在线 QQ 音乐

播放面板顶部切到「QQ音乐」页签即可在线听歌。需先扫码登录（QQ 登录或微信登录），登录后可浏览/搜索/播放并访问「我的歌单」，VIP 曲目可播高音质。

使用声明（重要）：在线 QQ 音乐功能通过非官方接口访问 QQ 音乐资源，所播放/收藏的内容版权归版权方及 QQ 音乐平台所有。本功能仅供个人学习、技术研究、日常试听使用， 严禁用于任何商业用途、公开传播、二次分发或盈利行为。使用本功能即表示您已知悉并同意：

您应对自己的使用行为及其后果负责；

因使用非官方接口登录/播放导致的账号风控、封禁、限流，以及可能引发的法律、版权纠纷，均由使用者自行承担；

本项目作者不承担任何因此产生的直接或间接责任。如您不同意以上条款，请勿使用本功能。

登录：两种扫码方式——QQ 登录或微信登录（推荐）。登录态保存在 Host 端（~/.dsh/music-player-qq-cookie.json），刷新/重启不丢；面板右上角可退出登录。
浏览：6 个子页签——我的歌单 / 推荐歌单 / 分类歌单 / 排行榜 / 新歌 / 搜索。
- 我的歌单：登录后展示当前账号的歌单（卡片式），本人创建的歌单卡片右上角可一键删除（二次确认；「我喜欢」不可删除）。
- 推荐歌单：热门推荐 12 条，底部「加载更多」可续载。
- 分类歌单：60+ 分类（默认折叠显示 8 个，可展开），每个分类的歌单支持「加载更多」。
- 排行榜：巅峰榜/地区榜/特色榜等分组，点榜单看歌曲（带榜单封面卡片），榜单歌曲一次全量加载（如热歌榜 299 首，无需「加载更多」）。
- 新歌：新歌速递（最新/内地/港台/欧美/韩国等）。
- 搜索：搜歌曲与歌单，带搜索历史（Host 持久化，最近 10 条）。
播放：点击任意歌曲即可播放（同一播放条 + 频谱）；歌单详情/排行榜详情/新歌速递头部有「▶ 播放全部」按钮，一键把整列表加入播放队列、从第一首开始顺序播放；VIP 标识显示在歌名后，行尾显示歌手名。进入歌单/播放列表时自动定位到正在播放的那一首，且正在播放的条目以高亮选中态显示。
收藏：播放条爱心按钮把当前在线曲目收藏到 QQ 音乐「我喜欢」，已收藏歌曲爱心实时点亮。
续播：在线播放进度（当前曲目 + 队列）刷新后自动恢复，点 ▶ 续播。
在线曲目不占本地曲库的 500 首上限，与本地/讲书完全隔离。

在线酷狗音乐

播放面板侧栏切到「酷狗音乐」页签。需先用酷狗 App 扫码登录才能试听（未登录可浏览榜单/歌单/搜索，但取链播放需要登录态）。登录后支持：

浏览：推荐歌单（600+ 热门精选）/ 分类歌单 / 排行榜（TOP500、国潮音乐榜等 57 个，榜单歌曲一次全量加载，如 TOP500=500 首）/ 统一搜索（歌曲 + 歌单）/ 我的歌单（可在歌单详情里移除歌曲）。歌单详情与排行榜详情头部同样有「▶ 播放全部」，整列表入队、从第一首顺序播放。
逐字歌词：KRC 逐字行窗口（与 QQ 的 QRC 同级精度），内嵌翻译自动并入歌词显示。
高音质：按「无损 → Hi-Res → 320k → 128k」梯队请求，tracker 按账号权限授予真实档位，播放条显示实际品质标签。
续播：与 QQ 同构——播放进度+队列独立持久化，刷新后自动恢复；单曲取链失败自动跳下一首。
登录态保存在 Host 端（~/.dsh/music-player-kugou-cookie.json，0600，含设备指纹），刷新/重启不丢。

使用声明：与在线 QQ 音乐相同——非官方接口、仅供个人学习试听、严禁商业用途；账号风控风险由使用者自行承担。技术细节与端点调研见 docs/kugou-integration-research.md。

在线网易云音乐

播放面板侧栏切到「网易云」页签。需先用网易云音乐 App 扫码登录（与 QQ/酷狗一致，未登录只显示登录入口），登录后支持：

播放：免费歌曲直接拿 320k 高音质直链播放（播放条显示「网易云 · 高音质」）；VIP/数字专辑歌曲仅能播 45 秒试听片段（显示「试听」）。
浏览：推荐歌单 / 分类歌单（65 个分类）/ 官方排行榜（飙升榜、新歌榜等 63 个榜单）/ 统一搜索（歌曲 + 歌单，多分型）。歌单详情（含超大歌单，如 200 首的热歌榜自动批量补齐）与榜单详情头部均有「▶ 播放全部」。
歌词：YRC 逐字行窗口（与 QQ QRC / 酷狗 KRC 同级精度，命中时生效）；普通歌曲回退整行 LRC，外语歌带逐句翻译（tlyric）与罗马音。
我的歌单：登录后可查看「我喜欢的音乐」与自建/收藏歌单；公开歌单详情页可一键「☆ 收藏 / ★ 已收藏」（收藏进「我的歌单」，取消收藏同按钮）。
续播：播放进度 + 队列独立持久化，刷新后自动恢复；单曲版权受限/取链失败自动跳下一首。
登录态保存在 Host 端（~/.dsh/music-player-netease-cookie.json，0600），刷新/重启不丢。
另有「匿名取链」能力保留在后端：agent 用 music_play 工具传 source=netease 时，未登录也能播免费曲（供对话场景直接点播）。

使用声明：与在线 QQ 音乐相同——非官方接口、仅供个人学习试听、严禁商业用途；账号风控风险由使用者自行承担。技术细节与端点调研见 docs/netease-integration-research.md。

网络电台

播放面板切到「网络电台」页签即可在线听全球电台（radio-browser.info 开放目录，无需登录、无 key）。子页签：我的电台（收藏）/ 最近播放 / 中文电台 / 热门电台 / 搜索。

数据源：radio-browser.info 社区目录（~4 万电台，CC 开放数据），多镜像自动故障转移；按台名/国家/标签/主题搜索或浏览。
中文电台 / 热门电台：按主题分组浏览（中文=全部/新闻/音乐/交通/财经/文艺/故事/体育；热门=全部/音乐/新闻/古典/摇滚/爵士/谈话），「加载更多」分页拉取，会话内缓存切回不重拉。
HLS(m3u8) 支持：央广/凤凰/CRI/CCTV 伴音等中文主流台多为 HLS 流（实测 CN 目录约四成为 HLS）。Host 端纯 Node（lib/hls.js）实时解析 m3u8（支持 master 嵌套、防盗链 token 与 scheme-relative URL）→ 逐分片归一化为 AAC(ADTS) 连续流喂给浏览器——兼容 MPEG-TS 分片（央广/凤凰/CCTV）与裸 ADTS 分片（蜻蜓/喜马拉雅系 .aac，如「华语金曲500首」）两种容器，无需 hls.js/ffmpeg 任何新依赖，浏览器 <audio> 直接可播（LIVE 直播态/断流自动重连与纯流台一致）。HLS 台在列表显示绿色「HLS」徽章、播放条标「电台 · HLS」。
收藏：点行尾 ♥ 收藏到本地收藏夹（~/.dsh/music-player-radio.json），「我的电台」随时回听。
命令：music_play 工具传 source=radio + 台名/国家，agent 可直接搜台开播（如「播放网络电台中国之声」）。
直播流不 seek、无进度条（LIVE 态）；个别台站可能失效或编码特殊（fMP4/加密等非 AAC）时会明确提示换台。

合规：目录为 CC 开放数据，播放的是各电台公开直播流；仅供个人收听，不录制/不二次分发，遵守台站 ToS。设计与实测记录见 docs/internet-radio-design.md。

AI 讲书

把本地 .txt / .epub 小说交给 AI 朗读。AI 语音目前仅支持xiaomi提供方（限时免费），请在设置中配置好再使用此功能。

前置

在 DSH 的模型设置里配置一个xiaomi提供方（含 api key）。未配置时，小说列表会提示"未配置xiaomi提供方"。

使用

打开播放面板，切到「小说」标签，点「选择小说目录」选定包含 .txt / .epub 的目录（默认与音乐目录相同）。
点击某一本小说开始朗读；也可让 agent 用 music_play 工具按小说名播放（如「播放《中国制造》」）。
播放条上的讲书控制：
- 章节目录（📖 按钮）：自动识别全书结构（书名/前言/章节/尾声），点击弹出位于按钮正上方的目录（自动定位到当前正在播放的章节），点击任意章节即从该章开头朗读
- 后退 / 前进：讲书模式下跳上一章 / 下一章（音乐模式下仍是上一首 / 下一首）
- AI 声音：点音量按钮，在弹层选择声音——冰糖（女）、茉莉（女）、苏打（男）、白桦（男，默认）
- 全书进度：播放条底部有一条「已读字符/全书字符」的进度细线，操作时显示「N%」——按已读字数实时计算，无需先合成全书就能给出稳定的整体进度（切块不回退；字符量来自源文本，因此总长总是可知，而总时长得合成完才知道），刷新页面后也会立即恢复显示（无需先点播放）
刷新页面后从上次位置续读（断点续播）。

支持的格式：

.txt（自动识别 UTF-8 / UTF-16 / GBK/GB18030 编码，无需手工转码）
.epub（自动解压并按其目录（spine）顺序把章节转成纯文本朗读；标题/作者取自 epub 元数据，可识别章节结构；加密/DRM 的章节会自动跳过）

每日新闻播报

让 agent 用联网搜索收集当天头条，整理筛选成口播稿后用 AI 语音播报。前置：DSH 的 web 搜索可用（web_search，内置 DeepSeek 搜索提供方）；语音播报需配置 xiaomi 提供方（与 AI 讲书共用，未配置时简报仍会生成、只是不可播）。

使用

对话即时播报（收集完立即播放）：对 agent 说「播报今天的新闻」。它会按类别搜索当天头条（默认热点/国内/国际/科技/财经/体育/娱乐，可任意指定，如「播一下 AI 相关的新闻」）、跨源去重、每条写口播摘要并标注来源，然后自动开播；说「收集一下今天的新闻，先别播」则只生成不出声。
面板回看：播放面板「新闻播报」页签——期次按时间倒序排列（当日期次全保留，跨天自动清理），未播放的标「待播」；点进详情可播整期 / 播某类 / 点某一条新闻从该条播；「文字版」按钮可全文阅读（不方便听语音时）。播放条上与讲书一致：📖 类别目录跳转、上/下一类、逐句字幕、AI 声音切换、N% 已读进度。
每日定时（Host 自维护）：在「新闻播报」页签的「⏰ 每日定时」里可视化配置多定时任务（如 08:00 / 12:30 / 18:00），每个定时任务可独立指定收集范围与新闻条数（1-20，默认 8；选了多个类别时各类别尽量平均分配），并勾选「收集后立即播放」（不勾选 = 静默收集，只更新简报不出声；熄屏/锁屏时也不会自动出声——该期保持「待播」徽标，解锁后点播即可，见下方 FAQ）；也可勾选「仅工作日执行」——按工作日历判断：周一至周五扣除法定节假日放假不跑、周末调休补班视为工作日照常。节假日数据按需自动联网获取（仅在到点判断「仅工作日」定时任务、且日历缺失/过期时才查询 timor.tech，失败自动回退内置表/周一至周五），无需任何手工维护。保存即生效——定时器由插件在 DSH 主机进程内自维护（无需 agent 创建/同步 DSH 定时任务、无需手动开会话），到点自动执行。也可对 agent 说「每天早上 9 点播报新闻」让其引导配置。可在「⏰ 每日定时」里给执行会话选一个新闻会话模型（不选则跟随当前活跃会话）。
手动补收：定时任务行有「▶ 立即执行」——一键自动跑一轮（不等时刻）；同一定时任务 10 分钟内重复收集会被自动跳过。
RSS 信源池（可选加强，默认开启，Host 后台自动使用）：内置 10 个核心源（中新网时政/国际/财经/体育/文化/即时/要闻 + IT之家 + 量子位 + 少数派，全部实测今日新鲜、开箱即用、零配置），池条目带可靠发布时间作为第一信源——每次新闻收集执行前自动懒拉取最新数据（无后台定时器、无需手动刷新），agent 先从池中筛选（按定时任务范围预筛注入指令），web_search 只作补盲（热点榜单、自定义主题、池外突发）；某源连续失败自动停用 24h。无 UI、无需任何配置——面板不展示信源池，Host 直接在后台使用（详见 RFC docs/news-rss-pool-rfc.md）。关掉信源池也不影响功能——收集完全退回 web_search，能力不降级。
工具层确定性去重：news_broadcast 提交时对标题归一化 + 相似度比对，自动剔除与本期次内或当日已有期次重复的条目（notice 透明报告）；同一事件多个来源时，更权威源（official > major > secondary > kol）可升级替换当日旧期次里的旧条目。同类任务当天多次执行不会因去重短收：收集指令会注入【已报条目】清单（今天已播过哪些），且仅当当天该定时任务已执行过时才要求每类按目标条数 1.5~2 倍提交候选缓冲去重（首次执行零冗余、不浪费 token）；工具层先去重（剔除重复候选）、再按定时任务条数收敛到目标——收集 8 条就播 8 条（详见 RFC §7.5）。

一次执行 = 一个会话

**每次执行（定时到点或手动立即执行）都会新建一个独立的「执行会话」**去收集并绑定结果——上下文干净聚焦、互不干扰，不再有常驻复用会话。
执行会话自动归入侧边栏 「新闻收集」分组（专属工作区目录 ~/.dsh/news），不再散落在「未分组」里；分组名可在工作区菜单里随意重命名。
每天凌晨 3 点自动清理「今天之前」的新闻：删除前一天及更早的全部期次与失败记录（不再保留多天新闻），并联动销毁/归档对应的执行会话；插件每次启动时也会立即检查一次，存在非今天的新闻就直接清理（清理幂等，手动触发 POST /dsh-music/news/purge-stale 走同一入口）。
每期次/失败记录都会记录对应的执行会话 id；删除某期新闻时，会连同删除它对应的执行会话（结果与会话一一对应、可清理）。
定时器在 DSH 主机进程内自维护（Node setInterval 读已保存的定时任务偏好），完全脱离会话存活——会话销毁不影响每天到点触发；宿主重启后按持久化偏好自动重建定时器。

数据与边界

收集与整理由 agent 在会话内完成（每次都是新鲜搜索，无常驻爬虫）；播报稿由插件端模板渲染。期次持久化在 ~/.dsh/music-player-news.json，音频不落盘（播放时按块懒合成）。
宁缺毋假：收集失败（如主机断网、搜索服务故障）时该期次不生成、绝不用旧数据顶替；失败原因透传工具错误（不做推断），面板展示并支持补收。仅浏览器离线不影响收集（收集在 DSH 主机进程完成，浏览器没开只影响"出声"）。
每条新闻必标来源（如「新华社」「微博热搜」）；内容由 AI 自动收集整理，以来源报道为准，请自行甄别。

开发

需要 Node.js ≥ 20（vitest 建议 20.19+）与 npm。开发依赖：vitest + react/react-dom/jsdom（用于前端渲染冒烟测试）：

npm install
npm test        # 跑 vitest 测试套件（Host 单测 + Web 渲染冒烟，共 500+ 用例）

修改 lib/ 后，在本机 profile 里用 link 方式本地调试并验证：

dsh plugin --profile <profile> add ./   # 或直接改 profile 里的 link 目标

项目结构、测试策略与发布流程详见 CONTRIBUTING.md。

常见问题

播放没有声音 / 显示"浏览器拦截了自动播放"？ 浏览器安全策略禁止未经交互的音频播放。首次自动播放被拦截是正常的——在播放条上点一次 ▶ 即可解锁，之后恢复播放。

播放条固定在输入框上方，太抢注意力 / 想让它挪个地方？ 打开播放面板 →「系统配置」→ 最下方的「播放条位置」，三选一：

选项	说明
输入框上方	默认（与旧版一致），全宽显示在输入卡片上方
页面底部	贴在窗口底边、横向对齐会话列的一条细条；插件会给输入区底座补一段等高的下内边距，让输入卡片整体上移，因此这条既压不住输入框、也不遮住对话内容
悬浮可拖动	紧凑三行卡片，高度固定不跳：① 歌词独占整行（第一行，中文歌词基本不用截断；当前没有歌词时留同高占位，所以有词/无词、空闲/播放中都不会变高变矮）② 歌名 + 实时频谱（频谱紧跟歌名/音质徽章）③ 时长 + 播放控制。整条可直接拖动，位置记在 Host 上、刷新后仍在；默认贴窗口右下角，「悬浮位置 → 重置位置」可复位

悬浮条闲置时会按「沉浸感」变淡，鼠标移上去恢复——不抢注意力但也一眼能找到。另外：改用页面底部或悬浮位置后，播放条不再挂在输入框区域，对话里的询问弹窗（它会接管输入区）不会再连播放条一起盖住，弹窗开着也能直接暂停/切歌。

同时开了好几个 DSH 标签页，会不会两首歌一起响？ 不会。插件把多个标签页收拢成一个播放器：同一时刻只有一页出声（由开始播放的那一页担任「出声页」），其余页自动静音并同步显示同一个播放器的状态——同一首歌、同一播放进度、同一播放/暂停状态，歌词、播放模式、音量、讲书章节都一致。在任意一页上的操作都会作用到这个唯一播放器：播放/暂停、上一首/下一首、停止、音量、播放模式、讲书换声音/跳章、点歌/点电台/点书/点新闻期次，都会转发到出声页执行。静音的那些页会在播放条歌名后显示 「此页静音」 徽标，提示声音来自另一个标签页。出声页被关闭时，其余页会停在最后的位置（不会两页抢播），在任意一页点 ▶ 即可就地接着播（讲书按 Host 上保存的进度续播）。

音乐面板显示"暂无音乐"或"不是有效的音乐目录"？ 点面板顶部「选择音乐目录」，选一个包含音频文件的实际目录（默认 ~/Music）。目录路径不可读或不存在时会回退到默认目录而不是报错。

改了音乐目录/新增了歌曲，但列表没更新？ 播放器在启动时扫描一次，并支持手动重扫：点「选择音乐目录」旁边的新增 「刷新」按钮，会重新遍历当前目录并更新列表（音乐与小说通用；无需重选目录）。扫描上限 500 首、递归子目录深度上限 4 层。

music_play 工具说"音乐库为空"？ 说明还没有可用的音乐目录。请先打开播放面板，点「选择音乐目录」配置一次。

小说列表提示"未配置 xiaomi/MiMo TTS 模型"？ AI 语音目前仅支持 xiaomi 提供方（限时免费）。请先在 DSH 模型设置里配置 xiaomi/MiMo provider（含 api key），再使用讲书功能。

讲书播放时点后退/前进没反应？ 讲书模式下后退/前进是跳上一章/下一章；如果当前小说没有识别出章节结构（目录按钮提示"暂无章节结构"），则无法跳章，只能整本顺序播。

听书偶尔"没声音但时间还在走"？ 这种一般是某一段的合成结果异常（返回了退化/静音音频），或瞬时合成失败。0.3.3 起 Host 端会严格校验合成音频（拒绝空数据/非 PCM 等退化 WAV）并自动重试一次瞬时失败，同时把每次合成结果记录在诊断日志里。若再遇到，可访问 http://<DSH地址>/dsh-music/tts-logs 查看最近 60 条合成记录（含失败原因、退化音频事件），据此定位具体是哪个块出的问题。

本地音乐没有 .lrc，歌词是怎么来的？ 播放器会在线兜底取词：先用文件名（可带歌手/时长）在 QQ 音乐匿名接口匹配官方歌词（外语歌带逐句翻译），QQ 无果再查 LRCLIB（免费公开歌词库，返回同步 LRC）。结果按曲目在进程内缓存（正命中 6 小时 / 空命中 30 分钟），避免重复请求；无匹配或失败时静默保持无歌词，不影响播放。歌词为版权内容，仅供个人试听。

有些音乐文件本身就带了歌词，会读取吗？ 会。播放器优先读取音频文件内嵌歌词（FLAC/OGG 的 LYRICS/UNSYNCEDLYRICS 标签、MP3 的 USLT 帧），无需额外 .lrc 文件，即可直接显示同步歌词。取词优先级为：同名 .lrc → 文件内嵌歌词 → 在线兜底（同名 .lrc 仍是第一优先，其次内嵌，都没有才走在线）。内嵌歌词通常就是标准 LRC 格式（含 [mm:ss] 时间戳），与普通 .lrc 一样逐句高亮、支持歌词面板。

本地歌词带翻译（原文/翻译逐句），能显示吗？ 能。若本地 .lrc（或内嵌歌词）里是「翻译行带自己的时间戳、紧跟在原句后」的写法，播放器会自动识别逐句翻译，并像在线歌词一样合并成「原文／翻译」显示（播放条与歌词面板都生效）。支持双向方向——既支持主流「外文歌 → 中文翻译」：

[00:01.00]Sparrows outside the window
[00:01.50]窗外的麻雀

也支持「中文歌 → 外文翻译」：

[00:01.00]窗外的麻雀
[00:01.50]Sparrows outside the window

识别从严：主语言由整首歌词统计决定（外文为主则中文行是翻译，中文为主则外文行是翻译），只有「相邻两行、时间戳接近」的翻译行才会被合并；歌名/水印等中英混杂的杂项行不误判，无翻译的歌词保持原样。

想支持更多音频格式？ 格式支持由 Host 端 AUDIO_TYPES 表驱动，在 lib/index.js 里加扩展名与 MIME 即可（播放器本身用浏览器原生 <audio> 解码，最终能否播放还取决于浏览器对该编码的支持）。

新闻播报里的新闻是怎么收集的？来源可靠吗？ 由 agent 在会话里用 web_search 联网搜索（内置 DeepSeek 搜索提供方），按类别多查询、跨源去重、只保留可确认时效的条目，每条必标来源（新华社、微博热搜等）。收集在 DSH 主机进程完成——浏览器没开不影响，只是不能出声；搜索服务故障/断网时该期次不生成（宁缺毋假），面板会显示失败原因并支持一键补收。

新闻定时任务设置了却不触发？ 定时器由插件在 DSH 主机进程内自维护（读面板已保存的定时任务偏好，每 30s 检查一次，到点触发）——请确认 dsh-desktop / dsh 服务主机进程保持运行；浏览器没开不影响收集（只影响出声）。每次触发会新建一个执行会话去收集并绑定结果（归入侧边栏「新闻收集」分组）。可在「新闻播报」页签的「⏰ 每日定时」里查看/修改定时任务；保存即生效。

勾了「收集后立即播放」，为什么熄屏/锁屏时没自动出声？ 熄屏/锁屏时插件不会自动起播新闻：页面不可见（后台标签/最小化/锁屏），或页面不再渲染帧（macOS 熄屏/锁屏时浏览器不把页面置为 hidden，但合成器停发帧）即视为「无人观看」——避免对着空房间把整期播完，也避免播放期反复申请/释放防熄屏锁让音频设备进出低功耗态（解锁瞬间的「咚咚」爆音）。该期会保持**「待播」**徽标，解锁后在「新闻播报」页签点一下即可播。若熄屏时本来就在听音乐/讲书（有人在听），定时播报照常插入，播完自动切回原内容。

收集时看到 web_fetch 报 WEB_BLOCKED_URL（non-public IP）？ 说明本机开着 TUN 代理的 fake-ip DNS 模式（Clash/mihomo、sing-box 等）：所有域名都会被解析成 198.18.x.x 这类代理内部地址，DSH 的 web_fetch 防 SSRF 保护会拒绝连接。收集流程会正常尝试抓取原文，但遇到这种报错会自动跳过、降级为只用 web_search 摘要继续整理，新闻照常生成。想让 web_fetch 恢复可用：把代理的 DNS 改为真实 IP 解析即可（Clash/mihomo 设 enhanced-mode: redir-host；sing-box 删除 DNS 配置里的 fakeip）。

新闻期次为什么少了 / 旧的去哪了？ 新闻只保留当天：每天凌晨 3 点自动删除前一天及更早的全部期次与失败记录（插件启动时也会立即检查一次），并归档对应的执行会话；当日期次全保留，也可以在面板里手动删除。「未听」的期次会带「待播」徽标，方便快速找到漏掉的。