Spotify 音乐控制

Spotify：播放、搜索、队列、管理播放列表和歌曲

Spotify

通过 Hermes Spotify 工具集（7 个工具）控制用户的 Spotify 账号。设置指南：https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify

使用场景 this skill

用户说类似"播放 X"、"暂停"、"跳过"、"加入 X 的队列"、"现在在播什么"、"搜索 X"、"加到我的 X 歌单"、"创建一个歌单"、"保存到我的音乐库"等。

7 个工具

spotify_playback — 播放、暂停、下一个、上一个、跳转、设置循环、设置随机、设置音量、获取状态、获取当前播放、近期播放

spotify_devices — 列出、切换设备

spotify_queue — 获取队列、添加队列

spotify_search — 搜索目录

spotify_playlists — 列出、获取、创建、添加曲目、移除曲目、更新详情

spotify_albums — 获取专辑、获取专辑曲目

spotify_library — 列出/保存/删除（通过 kind: "tracks"|"albums"）

播放变更操作需要 Spotify Premium；搜索/音乐库/歌单操作在免费版可用。

规范模式（最少化工具调用）

"播放 <艺人/歌曲/专辑>"

一次搜索，然后通过 URI 播放。禁止遍历搜索结果逐一描述（除非用户要求）。

spotify_search({"query": "miles davis kind of blue", "types": ["album"], "limit": 1})
→ 获得专辑 URI spotify:album:1weenld61qoidwYuZ1GESA
spotify_playback({"action": "play", "context_uri": "spotify:album:1weenld61qoidwYuZ1GESA"})

对于"播放一些 <艺人>"（无特定歌曲），优先用 types: ["artist"] 搜索并播放艺人上下文 URI——Spotify 处理智能随机播放。如果用户说"那首歌"或"那个曲目"，搜索 types: ["track"] 并传递 uris: [track_uri] 来播放。

"在播什么？" / "我在听什么？"

单次调用——不要在 get_currently_playing 之后链式调用 get_state。

spotify_playback({"action": "get_currently_playing"})

如果返回 204/空（is_playing: false），告知用户没有在播放。不重试。

"暂停" / "跳过" / "音量 50"

直接执行，无需预检。

spotify_playback({"action": "pause"})
spotify_playback({"action": "next"})
spotify_playback({"action": "set_volume", "volume_percent": 50})

"加到我的 <歌单名> 歌单"

spotify_playlists list 按名称查找歌单 ID

获取曲目 URI（从当前播放中获取，或搜索）

spotify_playlists add_items 传入 playlist_id 和 URIs

spotify_playlists({"action": "list"})
→ 找到"Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo
spotify_playback({"action": "get_currently_playing"})
→ 当前曲目 uri = spotify:track:0DiWol3AO6WpXZgp0goxAV
spotify_playlists({"action": "add_items",
                   "playlist_id": "37i9dQZF1DX4wta20PHgwo",
                   "uris": ["spotify:track:0DiWol3AO6WpXZgp0goxAV"]})

"创建一个叫 X 的歌单，添加我最近播放的 3 首歌"

spotify_playback({"action": "recently_played", "limit": 3})
spotify_playlists({"action": "create", "name": "Focus 2026"})
→ 获得 playlist_id
spotify_playlists({"action": "add_items", "playlist_id": , "uris": [<3 uris>]})

"保存/取消保存/这个保存了吗？"

使用 spotify_library 并传入正确的 kind。

spotify_library({"kind": "tracks", "action": "save", "uris": ["spotify:track:..."]})
spotify_library({"kind": "albums", "action": "list", "limit": 50})

"把播放切换到我的 <设备>"

spotify_devices({"action": "list"})
→ 按名称/类型匹配 device_id
spotify_devices({"action": "transfer", "device_id": "", "play": true})

关键失败模式

403 Forbidden — No active device found 在任何播放操作上出现，意味着 Spotify 没有在任何地方运行。告知用户："先在你的手机/桌面/网页播放器上打开 Spotify，随便播放一首歌，然后再试。"不要盲目重试——会得到同样的失败。可以调用 spotify_devices list 确认；空列表意味着没有活跃设备。

403 Forbidden — Premium required 表示用户在免费版尝试了播放变更。禁止重试；告知用户此操作需要 Premium。读取操作仍可用（搜索、歌单、音乐库、get_state）。

204 No Content on get_currently_playing 不是错误——意味着没有在播放。工具返回 is_playing: false。直接向用户报告即可。

429 Too Many Requests = 速率限制。等一下重试一次。如果持续发生，说明你在循环——停止。

401 Unauthorized 重试后仍出现 — 刷新令牌已撤销。告知用户重新运行 hermes auth spotify。

URI 和 ID 格式

Spotify 使用三种可互换的 ID 格式。工具接受全部三种并自动规范化：

URI：spotify:track:0DiWol3AO6WpXZgp0goxAV（首选）

URL：https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV

纯 ID：0DiWol3AO6WpXZgp0goxAV

不确定时使用完整 URI。搜索结果在 uri 字段返回 URI——直接传递。

实体类型：track、album、artist、playlist、show、episode。对不同操作使用正确的类型——spotify_playback.play 配合 context_uri 需要 album/playlist/artist；uris 需要曲目 URI 数组。

不要做的事

不要在每个操作前调用 get_state。Spotify 接受播放/暂停/跳过无需预检。只有当用户问"在播什么"或你需要推理设备/曲目时才检查状态。

不要描述搜索结果（除非用户要求）。如果用户说"播放 X"，搜索、拿最上面的 URI、播放。如果错了用户会听到。

收到 403 Premium required 或 403 No active device 不要重试。这些是永久性问题，需用户操作才能解决。

不要用 spotify_search 搜索歌单名称。那搜索的是公开 Spotify 目录。用户歌单来自 spotify_playlists list。

不要在 spotify_library 中混用 kind: "tracks" 和专辑 URI（或反过来）。工具会规范化 ID，但 API 端点不同。