LLYlab/DBS

DBS — DSH BGM 服务（独立于 DET 的音乐播放器插件）

npm i dsh-bgm-service · MIT · 与 DET（dsh-essential-tools）、DLT（dsh-light-tool）命名一致

一个不属于 DET 的 DeepSeek Harness（DSH）插件：本地音乐库 + 浏览器浮动播放器 + AI 依据任务控制播放（模型工具 + 自动联动）+ 网络下载入库 + 乐评爬取（尽力而为）。

包名说明：npm 上的 dbs 已被 2014 年的无关包占用（charliedowler/dbs），因此发布名为 dsh-bgm-service；插件自身的短名仍是 DBS，宿主端点与 Web 路由仍是 dbs/、/dbs/stream/（与包名无关）。

✨ 功能
- 🎵 本地音乐库：扫描配置的 musicDir（或 musicDirs 多个目录）下 .mp3/.flac/.wav/.m4a/.aac/.ogg/.opus/.webm，文件名按 艺术家 - 标题 智能解析出曲目/艺术家/标签。
- 📁 添加本地文件：播放器歌单里「＋添加本地」选择本机音频文件，上传进音乐库（POST /dbs/upload）。
- 🖥 浮动播放器（左下角）：播放/暂停/上下首/音量/进度条/当前曲目；点「♪ 标题」展开歌单；点击任意曲目即播；播放结束自动下一首。流地址走宿主内建 HTTP（/dbs/stream/，支持 Range 拖动进度）。
- 🤖 AI 依据任务控制（后台音乐）：
- 模型工具：bgm_list / bgm_play{trackId|query} / bgm_play_auto{query} / bgm_next / bgm_prev / bgm_pause / bgm_stop / bgm_set_volume。
- 命令队列：宿主工具把动作压入队列，播放器定期轮询并执行——AI 可依当前任务/心情选曲（按标题/艺术家/标签关键词匹配）。
- 自动联动（autoLink: true）：会话开始 / 工具调用密集时自动切一段合适的 BGM（尽力而为）。
- ⬇️ 网络下载入库：dbsDownload(url) —— 从公网 URL 下载音频到本地音乐库（SSRF 校验：禁私网/环回；大小上限；按 Content-Type/扩展名落盘）。
- 📝 乐评爬取（尽力而为）：dbsReview(query) 默认抓取豆瓣音乐「简介」作为乐评，按查询词缓存；反爬时给出可读失败提示（请自行评估合规与频率限制）。

🚀 安装与接入

A. 从 npm 安装（推荐）
在 DSH 的 web profile 目录里
cd $env:USERPROFILE\.dsh\profiles
npm i dsh-bgm-service --cache .\.npm-cache
依赖 @deepseek-ai/schemastery 会随包一起装上；@deepseek-ai/dsh-typert-protocol、@deepseek-ai/dsh-tools 由 DSH 本体提供。

B. 本地开发（源码 junction）
1. 把本仓库放到你要的位置（例：D:\plugins\DSHBgmService）。
2. 建立符号链接（链接名必须等于包名 dsh-bgm-service，与 DLT 的 dsh-light-tool 同一约定）：
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-bgm-service" -Target "D:\plugins\DSHBgmService"

注册（A / B 都要做）
在 $env:USERPROFILE\.dsh\profiles\web\cordis.patch.yml 追加注册行：
- insert:
- id: dbs
name: 'dsh-bgm-service'
config:
musicDir: 'D:\Music'                     # 本地音乐主目录(自动扫描)
musicDirs: []                            # 额外本地目录(可选,可多个)
importDir: ''                            # 上传/下载落盘目录;为空则用第一个根
autoLink: false
defaultVolume: 0.6
reviewBase: 'https://music.douban.com'

生效
重启 DSH → 左下角出现 DBS 播放器；进入设置/对话即可见 bgm_ 工具（供 AI 调用）。
宿主改动需重启；客户端改动需刷新/重建。

🔒 安全口径
- 下载 URL 走 SSRF 防护（仅 http/https、禁私网/环回/元数据、无内嵌凭据）；文件路径始终限制在 musicDir 内。
- 音频仅由宿主在本机浏览器同源提供（/dbs/stream/），无第三方地址。
- 乐评抓取为尽力而为的公开页面解析，可能受目标站反爬限制；请遵守目标站点服务条款与合理频率，本插件不绕过验证码/登录。
- 不涉及任何 API key；无遥测/上报。

🧩 端点（宿主 dbs/*）
dbsList dbsScan dbsPending dbsCommand dbsDownload dbsReview
模型工具：bgm_list bgm_play bgm_play_auto bgm_next bgm_prev bgm_pause bgm_stop bgm_set_volume
Web 路由：GET /dbs/stream/（音频流，Range 支持）

🔧 审计与加固（2026-09-08）

| 类别 | 问题 | 处理 |
| --- | --- | --- |
| 安全（SSRF） | dbsDownload / 乐评抓取用 fetch(..., {redirect:"follow"}) —— 只校验了初始 URL，服务器回一个 302 指向 http://127.0.0.1/... 即可绕过 SSRF 防护 | 新增 fetchGuarded()：手动逐跳跟随、每跳复验私网/环回/元数据、最多 5 跳（已用桩测试验证：重定向到内网时第二跳根本不会发出） |
| 安全（超时） | 两处 fetch 均无 AbortSignal —— 不响应主机会把端点挂死 | 统一加 15s 超时 |
| 安全（DoS） | 下载先 arrayBuffer() 整体读入内存再判大小 —— 超大响应可撑爆内存 | 先看 Content-Length，再流式读取并按上限截断 |
| 功能 | 页面刚打开时 dbsList 可能返回空曲库（构造函数的首次扫描还没跑完），而客户端只在 apply 时拉一次列表 → 曲库一直空着 | 保存首次扫描的 Promise，dbsList 等待它；_ensureScanned(30s) 做新鲜度与并发去重 |
| 功能 | bgm_list 只返回 count，模型拿不到任何 id/标题 —— 与工具描述不符，实际无法挑曲 | 返回曲目列表（id/title/artist/tags，默认 40 首、上限 200），并在卡片里逐行渲染 |
| 质量 | pickFor 无条件 +标签数，导致「标签多但与 query 毫不相关」的曲子总是胜出 | 改为关键词命中优先（标题 5 / 标签 4 / 艺术家 3），标签数只在有命中时轻微加分 |
| 功能 | 客户端 useDbs 把同一个对象引用交给 setState（store 是原地修改的），React 因 Object.is 相同而 bail out → 播放器 UI 永不刷新 | 每次传新的浅拷贝 |
| 功能 | 播放器拖完会被纵向拉伸、拖不到位 | .dbs-root 的 CSS 带 bottom:14px；拖动写入 left/top 后 top 与 bottom 同时存在 → position:fixed 元素被拉伸。已改为写坐标时一并 bottom:auto;right:auto，并加 3px 拖动阈值避免误触 |
| 新增 | 最小化（变成小球） | 标题栏右侧「—」→ 收成 38px 圆球：可继续拖动、点击还原、播放中变色 |
| 健壮性 | decodeURIComponent 遇畸形 % 转义会抛 | 加兜底 |
| 清理 | 死代码 fsPath() | 删除 |

宿主改动需重启 DSH 生效；客户端改动需刷新/重建。

License
MIT