跳到主要内容

Spotify

控制 Spotify — 播放音乐、搜索曲库、管理播放列表和资料库、检查设备和播放状态。当用户要求播放/暂停/将音乐加入队列、搜索歌曲/专辑/艺术家、管理播放列表或检查当前播放内容时加载。假设已启用 Hermes Spotify 工具集并运行了 hermes auth spotify。

技能元数据​

来源捆绑（默认安装）
路径skills/media/spotify
版本1.0.0
作者Hermes Agent
许可证MIT
标签spotify, music, playback, playlists, media
相关技能gif-search

参考：完整 SKILL.md​

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

Spotify

通过 Hermes Spotify 工具集（7 个工具）控制用户的 Spotify 账户。设置指南：/docs/user-guide/features/spotify

何时使用此技能​

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

7 个工具​

  • spotify_playback — play, pause, next, previous, seek, set_repeat, set_shuffle, set_volume, get_state, get_currently_playing, recently_played
  • spotify_devices — list, transfer
  • spotify_queue — get, add
  • spotify_search — 搜索曲库
  • spotify_playlists — list, get, create, add_items, remove_items, update_details
  • spotify_albums — get, tracks
  • spotify_library — 使用 kind: "tracks"|"albums" 进行 list/save/remove

播放变更操作需要 Spotify Premium；搜索/资料库/播放列表操作在免费版上可用。

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

“播放 <艺术家/歌曲/专辑>”​

一次搜索，然后通过 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] 传递给 play 以进行播放。

“正在播放什么？” / “我在听什么？”​

单次调用 — 不要在 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. 使用 playlist_id 和 URIs 调用 spotify_playlists add_items
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>]})

“保存 / 取消保存 / 这个已保存了吗？”​

使用带有正确 kind 的 spotify_library。

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 意味着用户使用免费版并尝试变更播放状态。不要重试；告诉他们此操作需要 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 时期望专辑/播放列表/艺术家；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 端点不同。