hermes教程-Spotify

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 或首次运行设置

最快的方式。运行：

hermes tools

滚动到 🎵 Spotify，按空格键启用，然后按 s 保存。同样的开关在首次运行的 hermes setup / hermes setup tools 流程中也可用。Spotify 是选择加入的，因此在那里启用它会运行与 hermes tools 相同的提供者感知配置。

Hermes 会直接带你进入 OAuth 流程 —— 如果你还没有 Spotify 应用，它会引导你内联创建一个。完成后，工具集将一次性启用并完成认证。

如果你更喜欢分开执行这些步骤（或者稍后重新认证），请使用下面的两步流程。

两步流程

1. 启用工具集

hermes tools

打开 🎵 Spotify 开关，保存，当内联向导打开时，关闭它（Ctrl+C）。工具集保持开启；只有认证步骤被推迟。

2. 运行登录向导

hermes auth spotify

7 个 Spotify 工具只有在步骤 1 之后才会出现在代理的工具集中 —— 它们默认是关闭的，这样不需要它们的用户就不会在每次 API 调用时发送额外的工具模式。

如果没有设置 HERMES_SPOTIFY_CLIENT_ID，Hermes 会内联引导你完成应用注册：

1. 在浏览器中打开 https://developer.spotify.com/dashboard
2. 打印需要粘贴到 Spotify“创建应用”表单中的确切值
3. 提示你输入获得的 Client ID
4. 将其保存到 ~/.hermes/.env，以便将来运行跳过此步骤
5. 直接进入 OAuth 同意流程

批准后，令牌将写入 ~/.hermes/auth.json 中的 providers.spotify 下。活跃的推理提供者不会改变 —— Spotify 认证独立于你的 LLM 提供者。

创建 Spotify 应用（向导要求的内容）

当仪表板打开时，点击创建应用并填写：

同意条款并点击保存。在下一页点击设置 → 复制Client ID并粘贴到 Hermes 提示中。这是 Hermes 唯一需要的值 —— PKCE 不使用客户端密钥。

通过 SSH / 在无头环境中运行

如果设置了 SSH_CLIENT 或 SSH_TTY，Hermes 会在向导和 OAuth 步骤中跳过自动打开浏览器。复制 Hermes 打印的仪表板 URL 和授权 URL，在本地机器的浏览器中打开，然后正常进行 —— 本地 HTTP 监听器仍在远程主机的端口 43827 上运行。你的笔记本电脑浏览器无法直接访问远程回环地址，除非使用 SSH 本地转发：

ssh -N -L 43827:127.0.0.1:43827 user@remote-host

对于跳板机/堡垒机设置以及其他注意事项（mosh、tmux、端口冲突），请参阅 通过 SSH / 远程主机的 OAuth。

验证

hermes auth status spotify

显示令牌是否存在以及访问令牌何时过期。刷新是自动的：当任何 Spotify API 调用返回 401 时，客户端会交换刷新令牌并重试一次。刷新令牌在 Hermes 重启后仍然存在，因此只有在 Spotify 账户设置中撤销应用或运行 hermes auth logout spotify 时才需要重新认证。

使用

登录后，代理可以访问 7 个 Spotify 工具。你可以自然地与代理对话 —— 它会选择正确的工具和操作。为了获得最佳行为，代理会加载一个配套技能，教授规范的使用模式（单次搜索然后播放、何时不预检 get_state 等）。

> 播放一些迈尔斯·戴维斯
> 我在听什么
> 将这首曲目添加到我的深夜爵士播放列表
> 跳到下一首歌
> 创建一个名为“Focus 2026”的新播放列表，并添加我最后播放的三首歌
> 我保存的专辑中哪些是 Radiohead 的
> 搜索 Blackbird 的原声翻唱
> 将播放转移到我的厨房音箱

工具参考

所有改变播放状态的操作都接受可选的 device_id 来指定目标设备。如果省略，Spotify 会使用当前活跃设备。

spotify_playback

控制和检查播放，以及获取最近播放的历史。

spotify_devices

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

spotify_search

搜索目录。query 是必需的。可选：types（track / album / artist / playlist / show / episode 的数组）、limit、offset、market。

spotify_playlists

spotify_albums

spotify_library

统一访问已保存的曲目和已保存的专辑。使用 kind 参数选择集合。

必需：kind = tracks 或 albums，加上 action。

功能矩阵：免费版 vs Premium

只读工具在免费账户上可用。任何改变播放状态或队列的操作都需要 Premium。

调度：Spotify + cron

由于 Spotify 工具是常规的 Hermes 工具，在 Hermes 会话中运行的 cron 作业可以按任何计划触发播放。无需新代码。

早晨唤醒播放列表

hermes cron add \
  --name "morning-commute" \
  "0 7 * * 1-5" \
  "将播放转移到我的厨房音箱，并开始我的'Morning Commute'播放列表。音量设为 40。开启随机播放。"

每个工作日上午 7 点会发生什么：

1. Cron 启动一个无头 Hermes 会话。
2. 代理读取提示，调用 spotify_devices list 按名称找到“厨房音箱”，然后 spotify_devices transfer → spotify_playback set_volume → spotify_playback set_shuffle → spotify_search + spotify_playback play。
3. 音乐在目标音箱上开始播放。总成本：一个会话，几次工具调用，无需人工输入。

夜间放松

hermes cron add \
  --name "wind-down" \
  "30 22 * * *" \
  "暂停 Spotify。然后将音量设为 20，这样明天我再次启动时声音会小一些。"

注意事项

• cron 触发时必须存在活跃设备。 如果没有 Spotify 客户端在运行（手机/桌面/Connect 音箱），播放操作会返回 403 no active device。对于早晨播放列表，技巧是定位一个始终在线的设备（Sonos、Echo、智能音箱），而不是你的手机。
• 任何改变播放状态的操作都需要 Premium —— play、pause、skip、volume、transfer。只读的 cron 作业（例如“通过邮件发送我最近播放的曲目”）在免费版上可以正常工作。
• cron 代理继承你的活跃工具集。 必须在 hermes tools 中启用 Spotify，cron 会话才能看到 Spotify 工具。
• cron 作业以 skip_memory=True 运行，因此它们不会写入你的记忆存储。

完整的 cron 参考：Cron 作业。

退出登录

hermes auth logout spotify

从 ~/.hermes/auth.json 中移除令牌。要同时清除应用配置，从 ~/.hermes/.env 中删除 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 —— 你使用的是免费账户，但尝试使用改变播放状态的操作。请参阅上面的功能矩阵。

get_currently_playing 返回 204 No Content —— 当前没有任何设备在播放。这是 Spotify 的正常响应，不是错误；Hermes 会将其显示为带有解释的空结果（is_playing: false）。

INVALID_CLIENT: Invalid redirect URI —— Spotify 应用设置中的重定向 URI 与 Hermes 使用的 URI 不匹配。默认是 http://127.0.0.1:43827/spotify/callback。要么将其添加到应用允许的重定向 URI 列表中，要么将 HERMES_SPOTIFY_REDIRECT_URI 设置为你在 ~/.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 被占用时才需要更改。

文件位置