跳到主要內容

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 端點不同。