DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

Soyoanon-mygo /

Soyoanon-mygo/dsh-music-companion

Topic repository only

一个能让dsh听懂你的歌单 并根据你的歌品向你主动推荐歌曲的dsh插件

★ 5 Stars1 Forks1 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@d9e981e1

dsh-music-companion

让你的 DSH 知道你在听什么,并且听得懂。

一个很小的扩展:桌面端读出系统媒体会话里正在播放的歌,经一个极简 hub 传给远端 agent。于是她能在聊天里自然接一句「你在听《春日影》?」,也能慢慢攒出你的听歌口味,哪天主动推一首过来。(本项目大部分代码由dsh生成,可能存在一些未知bug 欢迎提交修改)

目前的更新状态:v0.3更新完成 暂未上架dsh插件市场


它长什么样

下面两段是真实对话(已脱敏)。

她读得懂你在听什么

从今天的记录里看: 你的主线是日系乐队那种"动画片尾曲感"——ずっと真夜中でいいのに、ヨルシカ、MyGO、トゲナシトゲアリ,术力口那一块也不少。 但你又很吃杂食:从白光的老上海跳到巴西 funk、phonk,中间夹一笔说唱,还听了一段《觉醒年代》配乐。 晚上你偏抒情:悔やむと書いてミライ、影色舞、綺麗事这一串,情绪挺沉。白天赶工就挑有鼓点的。 还有一个发现,你一天扫了六十来首,很多听了 20 秒就切——你不是在听,你是在挑。

她读到的是 music_history:歌名、歌手、以及每首听了多久。"20 秒就切"和"从头听到尾"在她眼里是两种完全不同的事。

她会自己开口

(你切到《アシェンプテル》,暂停在中段) 还在放《アシェンプテル》,暂停在中段。是路上听了一半就下车了,还是切出去不听了?到家了吗?

这次不是你去问她。behavior.onSongChange 决定她能不能开口,quietHours 和 minGapSeconds 决定她多久才说一次——免得变成每换一首歌就播报的复读机。


它不做什么

先划清边界,省得误会:

  • 不是播放器。 在 DSH 里放歌这件事已经有人做得很好了(见相关项目)。
  • 不上传音频。 只传几行元数据,没有音频流。
  • 不碰你的账号凭证。 不读 cookie、不登录、不调网易云的私有接口。歌曲 ID 是从客户端自己的播放队列文件里读的,纯粹是本地文件。
  • 不保证 7×24 采集。 插件形态下,只有 DSH 进程活着 的时候才读得到系统媒体会话——DSH 退出(托盘图标右键「退出」)或电脑睡眠期间什么都不记。想做到「只要开机就在听」,要么给 DSH 开开机自启,要么用独立进程方式跑(见快速开始里的方式 B)。两条路的数据格式完全一样,同时跑也不冲突。

它做什么

能力 版本
知道你此刻在听什么、有没有在听、听到第几秒 现版本
记住你最近听过哪些歌、每首听了多久 现版本
拿到歌曲 ID、时长、来源(音乐 / B站视频 / 其他) 现版本
agent 主动把歌推进你的推荐队列 现版本
换歌时自己决定要不要搭话(而不是每首都播报) 现版本
记住口味,推歌之后知道有没有被听 现版本
打包成 DSH host 插件 现版本
上架 DSH 插件市场 v0.4
让dsh能登上网易云 开启一起听 v0.4

架构

三层,中间只有一个 HTTP 边界。任何一层挂了都不影响聊天——音乐是附加层,不是依赖。

┌───────────────────────────┐
│  你的电脑                  │
│                           │
│  网易云 / Spotify / B站    │
│      ↓ 系统媒体会话(SMTC)  │
│  watcher  ── 每 20s 读一次  │
│      │  + 本地队列查 song id│
└──────┼────────────────────┘
       │  POST /v1/now-playing
       │  (每轮都发,带进度)
       ▼
┌───────────────────────────┐
│  music-hub(一台小服务器)  │
│  收 · 存 · 给              │
│  纯 Node,零依赖,无数据库   │
└──────┬────────────────────┘
       │  127.0.0.1
       ▼
┌───────────────────────────┐
│  mcp-music                 │
│  三个工具:在听什么 / 最近听 │
│  / 推首歌                   │
└──────┬────────────────────┘
       ▼
   DSH agent

为什么用系统媒体会话

Windows 10 起有个系统级接口 Windows.Media.Control,任务栏那个播放小条就是它。它不碰任何播放器的内部结构,换网易云、Spotify、foobar2000 都能读到,也不会随客户端版本失效。

代价是网易云不上报播放位置(Position 永远是 0)。所以它的进度是 watcher 自己累加推断的:换歌从 0 开始,按前一次采样的播放状态累加,暂停期间不计时。支持播放位置的播放器优先使用 SMTC 报告的位置。

听歌时长和播放位置分开记录。 拖到第 3 分钟不代表听了 3 分钟;listenedSeconds 只累计实际采样到的播放时间。播放器消失、来源被过滤、SMTC 读取失败或采样间隔超过两轮时,不补算中间的空白时间。轮询仍有边界误差,网易云的估算进度也无法跟随拖动进度条。

为什么读本地队列拿 song id

agent 想查歌词、拉热评、找相似歌,都得先有数字 id,而 SMTC 只给歌名和歌手。按名字去搜索接口反查,同名歌一撞就废。

网易云客户端自己会在 %LOCALAPPDATA%\Netease\CloudMusic\webdata\file\playingList 里写一份播放队列,带精确 id 和时长,是明文 JSON。读它比调接口更准、更快、也更不容易被风控。

匹配时有个坑:SMTC 常常只报主歌手(「指错」),本地队列里却是全部歌手(「指错/星尘」)。所以匹配是分级的——先找歌手集合完全一致的,再找歌手互相包含的,最后如果歌名在队列里唯一就直接用。


快速开始

需要 Node.js ≥ 22。只能在 Windows 上用(读的是系统媒体会话)。

方式 A:装成 DSH 插件(推荐,一步搞定)

dsh plugin --profile <你的 profile> add /absolute/path/to/packages/watcher

装完重启一次 DSH——host 插件只在启动时加载,装着不重启是跑不起来的。

插件自己做三件事:

  1. 起一个本地 hub(127.0.0.1:8787,数据在 ~/.dsh-music-companion/data/)
  2. 每 20 秒读一次系统媒体会话,上报给 hub
  3. 把四个工具注册进 agent(music_now_playing / music_history / music_recommend / music_taste)

重启后直接问她「我在听什么」,不用另起进程、也不用配 MCP。

采集只在 DSH 进程活着时进行。 DSH 退出(托盘图标右键「退出」)或电脑睡眠期间不记录。要真正「开机就在听」,给 DSH 开开机自启即可。

想接自己的服务器? 在 config.json 里把 hub.url 指向它——只要不是 127.0.0.1 / localhost,插件就会跳过内置 hub,直接往那边报(跨机器场景见方式 B)。

方式 B:手动部署(跨机器 / 调试用)

三件套分开跑,适合 watcher 和 agent 不在同一台机器的情况。

1. 起 hub

MUSIC_HUB_TOKEN=$(openssl rand -hex 24) node packages/music-hub/src/hub.mjs

默认监听 127.0.0.1:8787。数据落在 packages/music-hub/data/,纯 JSON,出问题 cat 一下就能明白。

要跨机器用,把 MUSIC_HUB_HOST 设成 0.0.0.0,并且务必设一个足够长的 MUSIC_HUB_TOKEN——/v1/* 全部接口都要鉴权。

2. 起 watcher

MUSIC_HUB_URL=http://127.0.0.1:8787 \
MUSIC_HUB_TOKEN=<上面那个> \
node packages/watcher/watcher.mjs

加 --once 只读一次就退出,适合确认到底读到了什么;平时调试不重启 DSH 就用这个方式。

3. 挂 mcp-music

npm install --prefix packages/mcp-music

然后在 DSH 的 MCP 配置里加一条:

mcp-servers:
  mcp-music:
    command: node
    args: ["/absolute/path/to/packages/mcp-music/src/server.mjs"]
    env:
      MUSIC_HUB_URL: "http://127.0.0.1:8787"
      MUSIC_HUB_TOKEN: "<同一个 token>"

现在问她「我在听什么」,她会去查。

每 20 秒读一次,每轮都上报(进度在变),但相同的歌只会写一次历史。


配置与调参

三个组件共用一份 config.json,改一个地方三个都读到。

文件放哪

按顺序找,取第一个存在的:

  1. $MUSIC_CONFIG 指定的路径(临时切换配置、调试用)
  2. ./config.json(在仓库根目录跑时最方便)
  3. $XDG_CONFIG_HOME/dsh-music-companion/config.json
  4. ~/.config/dsh-music-companion/config.json
  5. %APPDATA%\dsh-music-companion\config.json(Windows)

仓库根目录的 config.example.json 复制成 config.json 就能用,后者已被 .gitignore 排除。

优先级:环境变量 > config.json > 内置默认值。 环境变量永远能临时压过文件,试参数时不用改文件。

完整参数

键 环境变量 默认 说明
hub.url MUSIC_HUB_URL http://127.0.0.1:8787 hub 地址,watcher 与 mcp 都读
hub.token MUSIC_HUB_TOKEN 空 /v1/* 全接口的鉴权密钥
hub.host MUSIC_HUB_HOST 127.0.0.1 hub 绑定地址,跨机要改成 0.0.0.0
hub.port MUSIC_HUB_PORT 8787 hub 端口
hub.dataDir MUSIC_HUB_DATA packages/music-hub/data 数据落盘目录
hub.staleSeconds MUSIC_HUB_STALE_SECONDS 600 多久没更新就标 stale: true
watcher.pollSeconds MUSIC_POLL_SECONDS 20 多久读一次系统媒体会话
watcher.device MUSIC_DEVICE desktop-windows 设备标识,多机时区分
watcher.ignoreSources — [] 不当作"在听歌"的来源

过滤不想被记录的来源

watcher.ignoreSources 收 netease / bilibili / other 三个值。被过滤的来源 watcher 根本不会上报,hub 和 agent 都看不到——看网课不该进听歌记录。

"watcher": { "ignoreSources": ["bilibili"] }

主动开口

behavior 段决定「她什么时候该主动说话」。换歌时 hub 按策略决定要不要叫醒 agent,叫醒之后说不说由 agent 自己判断——不想说就当没看见。

键 说明 默认
onSongChange always 每首都接话 / ask 看她心情 / silent 从不主动 ask
minGapSeconds 两次主动开口之间的最小间隔,防刷屏 180
quietHours 这段时间内绝不主动说话,支持跨零点 ["23:30","07:00"]
ignoreSource 这些来源的变化不触发发言 ["bilibili"]
notify.kind none 只记录不打扰 / qq-bridge 通过 QQ 桥接叫醒 / webhook 通用 none
notify.url qq-bridge 模式下的地址,如 http://127.0.0.1:3100 —
notify.consoleToken 桥接控制台令牌 —
notify.key 会话标识,如 private:1234567 —
notify.message 叫醒时的提示词,支持 {title} {artists} {album} 见 config.example.json

为什么只叫醒、不直接把歌名塞进对话:把歌名塞给它,它就只会复述歌名;只告诉它「有变化了」,它才会自己决定要不要看、要不要开口。真人也不是每首歌都要点评一句。

一个必须知道的细节:qq-bridge 的 notify-ai 触发的是 silent 回合——那一轮 agent 的文字输出不会自动发到 QQ,它必须显式调用发送工具(例如 qq_send_private_message)才发得出去。这是设计使然(避免打扰),不是 bug。

调试

看 watcher 到底读到了什么:

node packages\watcher\watcher.mjs --once

启动时会打三行:配置来源、读到的本地队列条数、这一轮的歌。链路通不通一眼就看得出来。

确认 hub 收到没有:

curl -sS -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/v1/now-playing

看 hub 日志:

tail -f /var/log/music-hub.log

塞一条假数据试场景(注意 track 这一层不能省,直接发 {"title":...} 会返回 track.title is required):

curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"track":{"title":"晴天","artists":["周杰伦"],"duration":269},"progress":30,"playing":true}' \
  http://127.0.0.1:8787/v1/now-playing

Windows 上别在 PowerShell 里硬拼 JSON 引号,写成文件再 --data-binary @payload.json 省事得多。


工具

工具 说明
music_now_playing 现在在听什么:歌名、歌手、专辑、ID、时长、进度、累计听歌时间、来源
music_history(limit) 最近听过的歌,倒序,附「上一首听了多久」
music_recommend(title, artist, reason?, id?) 把一首歌放进推荐队列,等桌面端拉取
music_taste(...) 读/写她对主人口味的了解。不带参数是读,带参数是整体覆盖写

前两个只读,后两个有副作用。

推荐闭环:music_recommend 写进去的是 status: "pending"。等你真的听了那首歌(watcher 上报的歌名/歌手能对上),hub 会自动把它标成 listened 并记下听到的时刻——这样她下次就知道自己的推荐准不准。

口味怎么来的:music_taste 是一个空槽,插件不替你总结。她可以自己从 music_history 里看出「这个人连续听了三首回春丹」,然后调 music_taste 写下来:歌手亲密度(-5..5)、风格标签、几句笔记。下次再推歌前先读一次,就不会推你已经明确不喜欢的东西。

数据长什么样

hub 存的 now-playing.json:

{
  "track": {
    "title": "陪葬夏天的健忘录",
    "artists": ["指错"],
    "album": "陪葬夏天的健忘录",
    "id": "2757490399",
    "duration": 218
  },
  "progress": 51,
  "playing": true,
  "listenedSeconds": 51,
  "device": "desktop-windows",
  "source": "netease",
  "startedAt": "2026-10-26T10:12:45.821Z",
  "updatedAt": "2026-10-26T10:13:36.317Z",
  "stale": false,
  "ageSeconds": 0
}

当前状态的 listenedSeconds 是当前歌曲累计听了多久;历史中一条记录的同名字段仍表示「换到这首歌之前,上一首累计听了多久」,第一条为 null。暂停/继续不会重复追加历史,暂停时选中的歌要等真正播放才入历史。配合上一首的 duration 就能判断你是听完了还是跳过:

  • 听了 40s / 218s ≈ 18% → 跳过
  • 听了 195s / 218s ≈ 89% → 听完

计数会随当前状态落盘,hub 重启后继续累计。旧 watcher 没有上报听歌计数时,hub 按播放状态和有效上报间隔估算,超过 hub.staleSeconds 的空白不计入。已有历史不改写;旧版当前状态缺少计数时从升级后的有效采样开始统计,不用墙上时间回推。

运行测试

仓库根目录执行,无需安装额外依赖,也无需实际打开播放器:

npm test
npm run test:smoke

回归测试覆盖插件与独立 hub 的 HTTP 行为、暂停/恢复、切歌、拖动进度、采集间断、重启恢复和连接配置。测试使用临时目录与临时端口,不读取个人配置或真实 SMTC 媒体数据。CI 在 Windows / Linux 的 Node.js 22 和 24 上运行。


设计取舍

  • 状态用 JSON 文件,不用数据库。 单用户、写频率不到 0.1Hz、读全在本机。文件的好处是出问题能直接看,agent 也能直接读。
  • 同一首歌反复暂停不重复记。 幂等键是 歌名|歌手,一首歌听一下午只算听了一次。
  • 进度是自己算的,不是读的。 网易云不报位置,只能靠累加计时。这是已知的精度损失,明写在数据里而不是假装准。
  • hub 不主动把歌名塞进对话。 v0.2 会改成「只告诉 agent 有变化」,由她自己决定接不接话——真人也不是每首歌都要评论。
  • 来源单独一个字段。 SMTC 会把 B 站视频也算成"正在播放",所以 source 用来区分 netease / bilibili / other,免得听歌记录里混进一堆网课。

相关项目

这几个都是「在 DSH 里放歌」,和我们方向不同,但值得一看:

  • doitian/dsh-music — 带 AI DJ 的网易云播放器
  • ZhaoZiyangShaanxi/dsh-netease-music — 读取本地客户端实现自动登录
  • Caiccc-a11y/dsh-wyymusic-player — 右侧栏播放器

许可

MIT

—/ 5

No ratings yet

Manifest verification required

Commit d9e981e1ac6d

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout