Chuyển tới nội dung chính

{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

Spotify

Spotify: phát, tìm kiếm, xếp hàng, quản lý danh sách phát và thiết bị.

Siêu dữ liệu kỹ năng​

NguồnĐi kèm (được cài đặt theo mặc định)
Đường dẫn

skills/media/spotify ` | | Phiên bản |

1.0.0 ` | | Tác giả | Đại lý Hermes | | Giấy phép | MIT | | Nền tảng | Linux, macOS, Windows | | Thẻ |

spotify

, `music

, `playback

, `playlists

, media | | Kỹ năng liên quan | XPROTECTX14XPROTECTX |

Tham khảo: đầy đủ SKILL.md​

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

Spotify

Kiểm soát tài khoản Spotify của người dùng thông qua bộ công cụ Hermes Spotify (7 công cụ). Hướng dẫn thiết lập: https://Hermes-agent.NousResearch.com/docs/user-guide/features/spotify

Khi nào nên sử dụng kỹ năng này​

Người dùng nói những điều như "phát X", "tạm dừng", "bỏ qua", "xếp hàng X", "nội dung đang phát", "tìm kiếm X", "thêm vào danh sách phát X của tôi", "tạo danh sách phát", "lưu danh sách này vào thư viện của tôi", v.v.

7 công cụ​

`spotify_playback

  • phát, tạm dừng, tiếp theo, trước đó, tìm kiếm, set_repeat, set_shuffle, set_volume, get_state, get_currently_playing, near_played

spotify_devices — danh sách, chuyển giao​

`spotify_queue

  • nhận, thêm

`spotify_search

  • tìm kiếm danh mục

spotify_playlists — liệt kê, lấy, tạo, thêm_items, delete_items, update_details​

spotify_albums — nhận, theo dõi​

spotify_library — liệt kê/lưu/xóa bằng `kind: "tracks"|"albums" ``Các hành động thay đổi phát lại yêu cầu Spotify Premium; Các hoạt động tìm kiếm/thư viện/danh sách phát hoạt động trên Miễn phí.

Mẫu Canonical (giảm thiểu lệnh gọi công cụ)​

"Phát <nghệ sĩ/bài hát/album"​

Một tìm kiếm, sau đó phát bằng URI. KHÔNG lặp qua các kết quả tìm kiếm mô tả chúng trừ khi người dùng yêu cầu các tùy chọn.

` spotify_search(&#123;"query": "miles davis kind of blue", "types": ["album"], "limit": 1}) → got album URI spotify:album:1weenld61qoidwYuZ1GESA spotify_playback(&#123;"action": "play", "context_uri": "spotify:album:1weenld61qoidwYuZ1GESA"})

``Để "phát một số &lt;nghệ sĩ" (không có bài hát cụ thể), hãy ưu tiên types: ["artist"] và phát URI ngữ cảnh nghệ sĩ — Spotify xử lý tính năng phát ngẫu nhiên thông minh. Nếu người dùng nói "bài hát" hoặc "bản nhạc đó", hãy tìm kiếm types: ["track"] và chuyển uris: [track_uri] ` để phát.

"Đang chơi gì thế?" / "Tôi đang nghe gì vậy?"​

Một cuộc gọi — không xâu chuỗi get_state sau get_currently_playing.

` spotify_playback(&#123;"action": "get_currently_playing"})

``Nếu nó trả về 204/trống (is_playing: false

), hãy thông báo cho người dùng rằng không có gì đang phát. Đừng thử lại.

"Tạm dừng" / "Bỏ qua" / "Tập 50"​

Hành động trực tiếp, không cần kiểm tra trước chuyến bay.

` spotify_playback(&#123;"action": "pause"}) spotify_playback(&#123;"action": "next"}) spotify_playback(&#123;"action": "set_volume", "volume_percent": 50})

`

"Thêm vào danh sách phát <tên danh sách phát của tôi"​

spotify_playlists list để tìm ID danh sách phát theo tên 2. Lấy URI bản nhạc (từ hiện đang phát hoặc tìm kiếm) 3. spotify_playlists add_items với danh sách phát_id và URI

` spotify_playlists(&#123;"action": "list"}) → found "Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo spotify_playback(&#123;"action": "get_currently_playing"}) → current track uri = spotify:track:0DiWol3AO6WpXZgp0goxAV spotify_playlists(&#123;"action": "add_items", "playlist_id": "37i9dQZF1DX4wta20PHgwo", "uris": ["spotify:track:0DiWol3AO6WpXZgp0goxAV"]})

`

"Tạo danh sách phát tên X và thêm 3 bài hát tôi phát gần đây nhất"​

`

spotify_playback(&#123;"action": "recently_played", "limit": 3}) spotify_playlists(&#123;"action": "create", "name": "Focus 2026"}) → got playlist_id back in response spotify_playlists(&#123;"action": "add_items", "playlist_id": <id>, "uris": [<3 uris>]})

`

"Lưu / hủy lưu / cái này đã được lưu chưa?"​

Sử dụng spotify_library với kind phù hợp.

` spotify_library(&#123;"kind": "tracks", "action": "save", "uris": ["spotify:track:..."]}) spotify_library(&#123;"kind": "albums", "action": "list", "limit": 50})

`

"Chuyển phát lại tới <thiết bị của tôi"​

`

spotify_devices(&#123;"action": "list"}) → pick the device_id by matching name/type spotify_devices(&#123;"action": "transfer", "device_id": "<id", "play": true})

`

Chế độ lỗi nghiêm trọng`**​

`403 Forbidden — No active device found

** trên mọi hành động phát lại có nghĩa là Spotify không hoạt động ở bất kỳ đâu. Nói với người dùng: "Trước tiên hãy mở Spotify trên điện thoại/máy tính để bàn/trình phát web của bạn, bắt đầu bất kỳ bản nhạc nào trong một giây, sau đó thử lại." Đừng thử lại cuộc gọi công cụ một cách mù quáng - nó sẽ thất bại theo cách tương tự. Bạn có thể gọi spotify_devices list để xác nhận; danh sách trống có nghĩa là không có thiết bị hoạt động.

** `403 Forbidden — Premium required

** có nghĩa là người dùng đang ở trạng thái Miễn phí và đã cố gắng thay đổi quá trình phát lại. Đừng thử lại; nói với họ rằng hành động này cần Premium. Đọc vẫn hoạt động (tìm kiếm, danh sách phát, thư viện, get_state).

** 204 No Content trên `get_currently_playing

** KHÔNG phải là lỗi - điều đó có nghĩa là không có gì đang phát. Công cụ trả về `is_playing: false

. Chỉ cần báo cáo điều đó cho người dùng.

** `429 Too Many Requests

** = giới hạn tốc độ. Đợi và thử lại một lần. Nếu điều đó tiếp tục xảy ra nghĩa là bạn đang lặp - hãy dừng lại.

** 401 UnauthoriZed sau khi thử lại** — mã thông báo làm mới đã bị thu hồi. Yêu cầu người dùng chạy lại `Hermes auth spotify

.

Định dạng URI và ID​

Spotify sử dụng ba định dạng ID có thể hoán đổi cho nhau. Các công cụ chấp nhận cả ba và bình thường hóa:

  • URI: spotify:track:0DiWol3AO6WpXZgp0goxAV (ưu tiên) -URL: `https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV

  • ID trần: 0DiWol3AO6WpXZgp0goxAV ``Khi nghi ngờ, hãy sử dụng URI đầy đủ. Kết quả tìm kiếm trả về các URI trong trường uri — chuyển trực tiếp các URI đó.Các loại thực thể: track

, `album

, `artist

, `playlist

, `show

, `episode

. Sử dụng đúng loại cho hành động — spotify_playback.play với context_uri yêu cầu album/danh sách phát/nghệ sĩ; uris mong đợi một loạt URI theo dõi.`##Những việc KHÔNG nên làm

  • Không gọi get_state trước mỗi hành động. Spotify chấp nhận phát/tạm dừng/bỏ qua mà không cần xem trước. Chỉ kiểm tra trạng thái khi người dùng hỏi "đang phát" hoặc bạn cần giải thích về thiết bị/bản nhạc.
  • Không mô tả kết quả tìm kiếm trừ khi được hỏi. Nếu người dùng nói "chơi X", hãy tìm kiếm, lấy URI hàng đầu, phát nó. Họ sẽ nghe thấy nó sai nếu nó sai.
  • **Không thử lại 403 Premium required hoặc `403 No active device

.** Những thông tin này sẽ có hiệu lực vĩnh viễn cho đến khi người dùng thực hiện hành động.

  • Không sử dụng spotify_search để tìm danh sách phát theo tên — tìm kiếm danh mục công khai của Spotify. Danh sách phát của người dùng đến từ `spotify_playlists list

.

  • Không kết hợp kind: "tracks" với URI album trong spotify_library (hoặc ngược lại). Công cụ này chuẩn hóa ID nhưng điểm cuối API lại khác.