spotify

Spotify

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

何时使用此技能

用户提出类似“播放 X”“暂停”“跳过”“把 X 加入队列”“正在播放什么”“搜索 X”“添加到我的 X 播放列表”“创建播放列表”“将此内容保存到我的媒体库”等请求时。

这 7 个工具

• spotify_playback — 播放、暂停、下一首、上一首、跳转、设置重复播放、设置随机播放、设置音量、获取状态、获取当前播放内容、最近播放记录
• spotify_devices — 列出、切换
• spotify_queue — 获取、添加
• spotify_search — 搜索曲库
• spotify_playlists — 列出、获取、创建、添加项目、移除项目、更新详情
• spotify_albums — 获取、曲目
• spotify_library — 使用 kind: "tracks"|"albums" 列出／保存／移除

更改播放状态的操作需要 Spotify Premium；搜索／媒体库／播放列表操作在 Free 账号上也可使用。

规范模式（尽量减少工具调用）

“播放 <艺人／曲目／专辑>”

搜索一次，然后按 URI 播放。除非用户要求提供选项，否则不要逐一介绍搜索结果。

spotify_search({"query": "miles davis kind of blue", "types": ["album"], "limit": 1})
→ got album 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})

“添加到我的 <播放列表名称> 播放列表”

1. 使用 spotify_playlists list 按名称查找播放列表 ID
2. 获取曲目 URI（从当前播放内容中获取，或进行搜索）
3. 使用 spotify_playlists add_items，并传入 playlist_id 和 URI

spotify_playlists({"action": "list"})
→ found "Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo
spotify_playback({"action": "get_currently_playing"})
→ current track 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"})
→ got playlist_id back in response
spotify_playlists({"action": "add_items", "playlist_id": <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"})
→ pick the device_id by matching name/type
spotify_devices({"action": "transfer", "device_id": "<id>", "play": true})

关键故障模式

任何播放操作出现 403 Forbidden — No active device found 都表示 Spotify 未在任何设备上运行。告诉用户：“先在手机／桌面／网页播放器上打开 Spotify，随便播放一首曲目几秒钟，然后重试。”不要盲目重试工具调用 — 结果仍会相同。你可以调用 spotify_devices list 进行确认；列表为空表示没有活动设备。

403 Forbidden — Premium required 表示用户使用的是 Free 账号，并尝试更改播放状态。不要重试；告诉用户此操作需要 Premium。读取操作仍可用（搜索、播放列表、媒体库、get_state）。

get_currently_playing 返回 204 No Content 并非错误 — 这表示当前没有播放内容。工具会返回 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 需要专辑／播放列表／艺人 URI；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 端点不同。