Spotify
Hermes 可以直接控制 Spotify —— 包括播放、播放队列、搜索、歌单、收藏的歌曲/专辑以及听歌历史 —— 通过 Spotify 官方 Web API 和 PKCE OAuth 实现。令牌存储在 ~/.hermes/auth.json 中，并会在收到 401 错误时自动刷新；你只需在每台机器上登录一次。
与 Hermes 内置的 OAuth 集成（如 Google、GitHub Copilot、Codex）不同，Spotify 要求每位用户注册自己的轻量级开发者应用。Spotify 不允许第三方发布一个可供所有人使用的公共 OAuth 应用。整个过程仅需约两分钟，而 hermes auth spotify 会引导你完成所有步骤。
前提条件
- 一个 Spotify 账户。免费版 支持搜索、歌单、资料库和活动工具。高级版（Premium） 是控制播放功能（播放、暂停、跳过、快进、音量调节、添加到队列、设备间转移）所必需的。
- 已安装并运行的 Hermes Agent。
- 若使用播放控制功能：必须有一个活跃的 Spotify Connect 设备——至少在一个设备（手机、桌面、网页播放器、音箱）上打开 Spotify 应用，以便 Web API 可以控制它。如果没有活跃设备，你会收到一条提示“
403 Forbidden”并显示“无活跃设备”；请在任意设备上打开 Spotify 后重试。
设置
一键式：hermes tools 或首次运行设置
最快路径。运行：
```bash
hermes tools
滚动至 ``🎵 Spotify``，按空格键启用，然后按 ``s`` 保存。该开关也可在首次运行的 ``hermes setup`` / ``hermes setup tools`` 流程中找到。Spotify 保持可选状态，因此在此处启用即执行与 ``hermes tools`` 相同的、基于提供者的配置流程。
Hermes 会直接进入 OAuth 流程——如果你还没有 Spotify 应用，它将在线引导你创建一个。完成后，工具集将被启用且已认证，一步到位。
如果你更倾向于分步操作（或稍后重新认证），请使用以下两步流程。
### 两步流程
#### 1. 启用工具集
```bash
```bash
hermes tools
将 ``🎵 Spotify`` 开关设为开启，保存，当内联向导弹出时，按 Ctrl+C 关闭它（无需完成）。工具集保持开启状态；仅认证步骤被推迟。
#### 2. 运行登录向导
```bash
```bash
hermes auth spotify
只有完成第 1 步后，7 个 Spotify 工具才会出现在代理的工具集中——默认情况下它们是关闭的，这样不希望使用这些功能的用户不会在每次 API 调用中携带额外的工具模式。
如果未设置 ``HERMES_SPOTIFY_CLIENT_ID``，Hermes 将在线引导你完成应用注册：
1. 在你的浏览器中打开 `https://developer.spotify.com/dashboard``
2. 打印出需要粘贴到 Spotify “创建应用” 表单中的精确值
3. 提示你输入从 Spotify 返回的 Client ID
4. 将其保存至 ``~/.hermes/.env``，以便后续运行跳过此步骤
5. 直接进入 OAuth 授权流程
授权成功后，令牌将写入 ``providers.spotify`` 的 ``~/.hermes/auth.json`` 中。当前推理提供者**不会改变**——Spotify 认证与你的 LLM 提供者完全独立。
### 创建 Spotify 应用（向导所需信息）
当仪表板打开后，点击 **Create app** 并填写以下内容：
| 字段 | 值 |
|------|----|
| 应用名称 | 任意（例如 ``hermes-agent``） |
| 应用描述 | 任意（例如 ``personal Hermes integration``） |
| 网站 | 留空 |
| 重定向 URI | `http://127.0.0.1:43827/spotify/callback`` |
| 使用的 API/SDK | 勾选 **Web API** |
同意条款后点击 **Save**。在下一页点击 **Settings** → 复制 **Client ID** 并粘贴到 Hermes 提示框中。这是 Hermes 所需的唯一值——PKCE 不需要客户端密钥（client secret）。
### 通过 SSH 或无头环境运行
如果设置了 ``SSH_CLIENT`` 或 ``SSH_TTY``，Hermes 将跳过向导和 OAuth 步骤中的自动浏览器打开。请复制 Hermes 输出的仪表板 URL 和授权 URL，在本地机器的浏览器中打开，然后正常操作——远程主机上的本地 HTTP 监听器仍会在端口 ``43827`` 上运行。你的笔记本电脑浏览器无法直接访问远程回环地址，除非建立 SSH 本地转发：
```bash
ssh -N -L 43827:127.0.0.1:43827 user@remote-host
关于跳板机 / 堡垒机、mosh、tmux、端口冲突等特殊情况，请参阅 OAuth over SSH / Remote Hosts。
验证
```bash
hermes auth status spotify
显示令牌是否存在以及访问令牌何时过期。刷新机制是自动的：当任何 Spotify API 调用返回 401 时，客户端会用刷新令牌换取新令牌，并重试一次。刷新令牌在 Hermes 重启后仍然保留，因此你只需在 Spotify 账户设置中撤销应用权限，或运行 ``hermes auth logout spotify`` 时才需要重新认证。
## 使用方法
登录成功后，代理将拥有 7 个 Spotify 工具。你可以自然地与代理对话——它会自动选择正确的工具和操作。为了获得最佳行为表现，代理会加载一个配套技能，学习标准使用模式（如“先搜索再播放”、“何时不应预检 `get_state`”等）。
```bash
play some miles davis what am I listening to add this track to my Late Night Jazz playlist skip to the next song make a new playlist called "Focus 2026" and add the last three songs I played which of my saved albums are by Radiohead search for acoustic covers of Blackbird transfer playback to my kitchen speaker
工具参考
所有涉及播放控制的操作都支持可选的 device_id 参数，用于指定特定设备。若省略，则 Spotify 使用当前活跃设备。
spotify_playback
控制和检查播放状态，同时获取最近播放记录。
| 操作 | 用途 | 高级版？ |
|---|---|---|
get_state | 完整播放状态（歌曲、设备、进度、随机/重复模式） | 否 |
get_currently_playing | 当前播放的歌曲（返回 204 时表示无内容，见下文） | 否 |
play | 开始/恢复播放。可选参数：context_uri、uris、offset、position_ms | 是 |
pause | 暂停播放 | 是 |
next / previous | 跳过当前歌曲 | 是 |
seek | 跳转至 position_ms | 是 |
set_repeat | state = track / context / off | 是 |
set_shuffle | state = true / false | 是 |
set_volume | volume_percent = 0–100 | 是 |
recently_played | 最近播放的歌曲列表。可选参数：limit、before、after（Unix 毫秒时间戳） | 否 |
spotify_devices
| 操作 | 用途 |
|---|---|
list | 你账户可见的所有 Spotify Connect 设备 |
transfer | 将播放转移到 device_id。可选参数 play: true 在转移后启动播放 |
Home Assistant 管理的音箱
如果 Home Assistant 管理的音箱已支持 Spotify Connect（例如 Sonos、Echo、Nest 或其他支持 Connect 的音箱），它们将在 Spotify 可见时自动出现在 spotify_devices list 中。Hermes 无需建立 Home Assistant ↔ Spotify 桥接——Spotify 本身原生处理设备路由。
你可以让 Hermes 将播放转移到音箱的显示名称（例如：“把 Spotify 转移到厨房音箱”），或调用 spotify_devices list 并传入确切的 device_id 到 spotify_devices transfer 来进行脚本化操作。如果音箱未出现，请打开 Spotify 应用或该音箱的 Spotify 集成一次，使 Spotify 将其注册为有效的 Connect 目标。
spotify_queue
| 操作 | 用途 | 高级版？ |
|---|---|---|
get | 当前播放队列中的歌曲 | 否 |
add | 将 uri 添加到队列 | 是 |
spotify_search
在目录中进行搜索。query 为必填项。可选参数：types（数组形式的 track / album / artist / playlist / show / episode）、limit、offset、market。#### spotify_playlists
| 操作 | 目的 | 必需参数 |
|---|---|---|
list | 用户的播放列表 | — |
get | 单个播放列表 + 曲目 | playlist_id |
create | 新建播放列表 | name（可选：description、public、collaborative） |
add_items | 添加曲目 | playlist_id、uris（可选：position） |
remove_items | 移除曲目 | playlist_id、uris（可选：snapshot_id） |
update_details | 重命名 / 编辑 | playlist_id + 以下任意一项：name、description、public、collaborative |
spotify_albums
| 操作 | 目的 | 必需参数 |
|---|---|---|
get | 专辑元数据 | album_id |
tracks | 专辑曲目列表 | album_id |
spotify_library
统一访问已收藏的歌曲和已收藏的专辑。通过 kind 参数选择集合。
| 操作 | 目的 |
|---|---|
list | 分页库列表 |
save | 将 ids / uris 添加到库中 |
remove | 从库中移除 ids / uris |
必需：kind` = `tracks` 或 `albums，以及 action。
功能对比：免费版 vs 高级版
只读工具可在免费账户上使用。任何涉及播放或队列修改的操作均需高级版。
| 免费版可用 | 高级版必需 |
|---|---|
spotify_search（全部） | spotify_playback — 播放、暂停、下一首、上一首、快进、设置重复、设置随机、设置音量 |
spotify_playback — get_state, get_currently_playing, recently_played | spotify_queue — add |
spotify_devices — list | spotify_devices — transfer |
spotify_queue — get | |
spotify_playlists（全部） | |
spotify_albums（全部） | |
spotify_library（全部） |
调度：Spotify + cron
由于 Spotify 工具是标准的 Hermes 工具，一个在 Hermes 会话中运行的 cron 任务可以按任意时间表触发播放。无需编写新代码。
早晨唤醒播放列表
hermes cron add \
--name "morning-commute" \
"0 7 * * 1-5" \
"Transfer playback to my kitchen speaker and start my 'Morning Commute' playlist. Volume to 40. Shuffle on."
每天工作日早上 7 点发生：
- Cron 启动一个无头 Hermes 会话。
- 代理读取提示，调用
spotify_devices list查找名为“厨房音箱”的设备，然后执行spotify_devices transfer→spotify_playback set_volume→spotify_playback set_shuffle→spotify_search+spotify_playback play。 - 音乐在目标音箱上开始播放。总成本：一次会话，几次工具调用，无需人工干预。
夜间放松时段
hermes cron add \
--name "wind-down" \
"30 22 * * *" \
"Pause Spotify. Then set volume to 20 so it's quiet when I start it again tomorrow."
注意事项
- cron 触发时必须存在活跃设备。 如果没有 Spotify 客户端正在运行（手机/桌面/Connect 音箱），播放操作将返回
403 no active device。对于早晨播放列表，诀窍是选择一个始终开启的设备（如 Sonos、Echo、智能音箱），而不是你的手机。 - 任何修改播放状态的操作都需要高级版 —— 播放、暂停、跳过、调节音量、转移播放。只读的 cron 任务（例如定时“给我发送最近播放的歌曲”）在免费版上也能正常运行。
- cron 代理继承你当前的工具集。 若想让 cron 会话看到 Spotify 工具，必须在
hermes tools中启用 Spotify。 - cron 任务以
skip_memory=True运行，因此不会写入你的记忆存储。
完整 cron 参考：Cron 任务。
注销登录
hermes auth logout spotify
从 ~/.hermes/auth.json 中移除令牌。若要同时清除应用配置，请删除 HERMES_SPOTIFY_CLIENT_ID（以及如果你设置了的话，还有 HERMES_SPOTIFY_REDIRECT_URI）中的内容，或重新运行向导。
要在 Spotify 侧撤销应用权限，请访问 连接到你账户的应用，点击 移除访问权限。
故障排除
403 Forbidden — Player command failed: No active device found — 你需要在至少一个设备上运行 Spotify。打开手机、桌面或网页播放器上的 Spotify 应用，播放任意歌曲一秒以注册设备，然后重试。spotify_devices list 显示当前可见的设备列表。
403 Forbidden — Premium required — 你使用的是免费账户，但尝试执行了修改播放状态的操作。请参阅上方的功能矩阵。
204 No Content 出现在 get_currently_playing 上 — 当前没有任何设备正在播放。这是 Spotify 的正常响应，并非错误；Hermes 会将其作为解释性空结果呈现（is_playing: false）。
INVALID_CLIENT: Invalid redirect URI — 你的 Spotify 应用设置中的重定向 URI 与 Hermes 使用的不匹配。默认值为 ``http://127.0.0.1:43827/spotify/callback`. Either add that to your app's allowed redirect URIs, or set HERMES_SPOTIFY_REDIRECT_URI in ~/.hermes/.env，请将其更改为你在注册时填写的值。
429 Too Many Requests — Spotify 的速率限制。Hermes 返回友好错误信息；等待一分钟后重试。如果问题持续存在，你可能在脚本中运行了一个过紧的循环——Spotify 的配额大约每 30 秒重置一次。
401 Unauthorized 不断出现 — 你的刷新令牌已被撤销（通常是因为你从账户中移除了该应用，或应用被删除）。请再次运行 hermes auth spotify。
向导未自动打开浏览器 — 如果你通过 SSH 登录或处于无显示环境的容器中，Hermes 会检测到并跳过自动打开。复制它打印的仪表板 URL 并手动打开。
高级功能：自定义权限范围
默认情况下，Hermes 会请求所有已发布工具所需的权限范围。如需限制访问权限，可进行覆盖：
hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
权限范围参考：Spotify Web API 权限范围。如果请求的权限少于某个工具所需，该工具调用将因 403 错误而失败。
高级功能：自定义客户端 ID / 重定向 URI
hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback
或永久设置在 ~/.hermes/.env 中：
HERMES_SPOTIFY_CLIENT_ID=<your_id>
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
重定向 URI 必须在你的 Spotify 应用设置中列入白名单。默认值适用于绝大多数用户——仅当端口 43827 被占用时才更改。
数据存放位置
| 文件 | 内容 |
|---|---|
~/.hermes/auth.json → providers.spotify | 访问令牌、刷新令牌、过期时间、权限范围、重定向 URI |
~/.hermes/.env | HERMES_SPOTIFY_CLIENT_ID，可选 HERMES_SPOTIFY_REDIRECT_URI |
| Spotify 应用 | 由你拥有，位于 developer.spotify.com/dashboard；包含客户端 ID 和重定向 URI 白名单列表 |