前言¶
在 DSH 工作台里写提示词、跑任务时，很多人会开另一个窗口听歌。社区里已有面向网易云的 DSH 音乐类插件，若你日常用的是酷狗 PC 客户端，歌单和最近在听都锁在本地加密库里，和对话界面是两套系统。维护者 dasazira-QAQ 的 dsh-kugou-music 把搜索、队列播放、逐字歌词和本机歌单读入接到 DSH 里：接口走酷狗公开 Web API，本地库用 WASM 解密后只读查询。插件归类为联网工具，当前 GitHub 星标为 0；README 标明非官方，仅供个人学习自用，请尊重版权。
这是什么¶
dsh-kugou-music 是标准 DSH bundle（dsh.bundle.patch + dsh.client），仅适配 Web 客户端（platform: "web"）。它在输入框上方或左侧边栏提供播放器 UI，Host 在本机 loopback 注册 /kugou-music-api，前端通过该 HTTP 服务完成搜歌、取流、歌词和本地歌单。
- 仓库：dasazira-QAQ/dsh-kugou-music
- 社区目录：SkillHub 插件页
- 许可证：MIT（
package.json版本 0.1.2） - 运行要求：
dsh >= 0.1.0，node >= 22.13.0
核心功能¶
播放与队列¶
- 按歌曲名或歌手搜索，点选只把当前曲目加入队列。
- 播放模式：列表循环、顺序播放、随机播放；随机模式下「上一首」会回到真正播过的那一首。
- 队列持久化，重启 DSH 后仍保留。
- 支持音量、进度拖动、上一首 / 下一首。
- 可配置全局热键（播放暂停、上一首、下一首，含组合键），并可设置打字时是否响应；0.1.2 起打字时也可使用组合热键（可开关）。
歌单¶
- 本地歌单：读取本机酷狗 PC 客户端数据库（路径为 Windows 下的
%APPDATA%\KuGou8\KGMusicV3.db，加密 SQLite），解密后列出当前账号各设备列表、最近播放、本地文件。按数据库修改时间缓存，客户端写库后自动重解密，首次约 200ms。只读当前登录账号（从 Cookie 的KugooID解析）的设备列表。 - 链接导入：粘贴酷狗歌单分享链接（含
t1.kugou.com短链），自动翻页；导入后可「替换列表」或「加入列表」（自动去重）。 - 曲目带 VIP / 免费标签（分享接口无
pay_type时用musicpack_advance推断）。 - 云歌单（如「我喜欢」）本地只存名称，歌曲在服务器上，需通过链接导入等方式获取。
歌词¶
- 优先 KRC 逐字歌词，普通歌回退 LRC。
- 使用酷狗自带翻译（KRC 的
[language:]段，type: 1）；无翻译时显示「暂无翻译」。 - 歌词随播放高亮并自动滚动。
界面¶
- 两套 UI：输入框播放条、左侧边栏；在设置中切换，切换不中断播放。
- 播放条宽度预设：贴合对话框 / 略窄 / 紧凑（锁定与悬浮均生效）；可锁定、解锁拖动、复位。
- 侧边栏可收起为圆形气泡，气泡可锁定和拖动；气泡歌词行数 1–4、字号 10–16px（仅侧边栏气泡）。
- 白 / 黑玻璃主题，8 个预设色加自定义色盘；背景可选毛玻璃或完全透明。
- 可将歌词条显示在左侧边栏（工作文件夹下方）。
账号与 VIP¶
填写酷狗网页版 Cookie 后可播放 VIP / 付费曲（匿名状态下酷狗侧拿不到付费歌播放地址）。插件可显示酷狗头像、昵称、UID。Cookie 仅存本机 ~/.dsh/kugou-music/cookie.txt，README 说明不上传至第三方。
本地加密音频¶
.kgm、.kgma、.vpr、.kgg（含 xxx.kgm.flac）在 Host 侧用与解锁数据库相同的 WASM（Project Unlock Music 的 @clamber_l/crypto）解密后流式返回，不落盘。若下载已是明文（例如标准 FLAC），则直接播放。
安装与启用¶
下面命令来自仓库 README，请将 <你的 profile> 换成实际 profile 名。
# 从 npm 安装（推荐）
dsh plugin --profile <你的 profile> add dsh-kugou-music
# 或从本地目录
dsh plugin --profile <你的 profile> add "file:/绝对路径/dsh-kugou-music"
也可手动：把插件目录放进 profile 的 node_modules/，在 profile package.json 的 dependencies 增加 "dsh-kugou-music": "link:<绝对路径>"，并在 dsh.profile.bundles 增加 "dsh-kugou-music"。
安装完成后需完全退出 DSH 再重新打开。插件以当前 DSH 进程权限运行，安装前建议自行查看源码与 MIT 许可证；涉及解密本地库与 Cookie 时，只应在可信环境使用。
典型用法¶
- 启动 DSH 后，输入框上方会出现播放条，点左侧
^展开面板。 - 歌单 → 本地歌单：在已安装酷狗 PC 客户端且路径可访问时，列出本机解密后的列表与最近播放。
- 歌单 → 链接导入：粘贴分享链接导入曲目。
- 齿轮 → 外观：调整主题、颜色、背景、气泡歌词、热键、界面模式。
- 齿轮 → 账号：填写 Cookie（见下节）。
获取 Cookie 的 README 步骤摘要：
- 浏览器打开
kugou.com并登录。 - 打开开发者工具（
F12或Ctrl+Shift+I），进入 Application（中文为「应用」）→Storage → Cookies → https://www.kugou.com，过滤kg_后复制为name=value; name2=value2填入插件；或在 Console 中输入copy(document.cookie)（勿直接粘贴未允许的脚本，必要时先输入allow pasting）。
Host 提供的 loopback API 包括搜索、公开歌单、播放、歌词、本地列表、本地音频流、账号信息与 Cookie 读写等，例如：
GET /search?q=&page=&size=
GET /playlist?id=&size=
GET /play?hash=&albumId=
GET /lyric?hash=&duration=
GET /local-lists
GET /local-files
GET /local-audio?path=
GET /profile
POST /cookie { cookie }
完整列表见仓库 README「接口」一节。
实现要点（便于排查）¶
| 环节 | 做法 |
|---|---|
| 搜索 | songsearch.kugou.com/song_search_v2 |
| 公开歌单 | m.kugou.com/plist/list/<id>（每页 10 条，自动翻页） |
| 分享歌单 | m3ws.kugou.com/v2/zlist/list + infSign 签名 |
| 播放地址 | m.kugou.com/app/i/getSongInfo.php |
| VIP 播放 | wwwapi.kugou.com/play/songinfo + MD5 签名 |
| 歌词 | krcs.kugou.com/search → lyrics.kugou.com/download |
| 本地数据库 | WASM 解密 → 临时 SQLite → node:sqlite |
| 前端挂载 | 注册到 conversation.input.dock 与 shell.overlay 的 React 组件 |
本地库解密逻辑：用 @clamber_l/crypto WASM 解密，结果写入系统临时文件（不修改原始库），再读取 RecentlyPlayedItem、DeviceDefaultList_*、LocalFile 等表。
适用场景与注意¶
适合：已在 DSH Web 端工作、使用酷狗生态，希望在同一界面搜歌、看逐字歌词和翻译、导入分享歌单，并在 Windows 上读取酷狗 PC 本地库的用户。
已知限制（摘自 README）：
- 匿名无法播放 VIP / 付费曲。
- 播放地址有时效，长时间暂停后可能失效，重新点播即可。
- 云歌单内容需链接导入或其它方式，不能仅靠本地库名展开。
- KGM 解密依赖第三方 WASM，未在所有加密版本上验证。
- 窗口标题栏会拦截顶部点击，侧边栏实现上已下移 54px 规避。
README 提供 B 站演示视频：只有网易云接 dsh 没有酷狗？这回有了！。
结尾¶
dsh-kugou-music 把酷狗搜索、队列播放、KRC 歌词与翻译、本机加密歌单读取和两套可定制 UI 收进 DSH 插件形态；安装用 npm 包名 dsh-kugou-music，配置 Cookie 与热键后即可在工作台内完成常见听歌流程。详情与 issue 见 GitHub 仓库，目录索引见 SkillHub。
