better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/skins.md

@@ -0,0 +1,271 @@
+---
+sidebar_position: 10
+title: "皮肤与主题"
+description: "使用内置和用户自定义皮肤定制 Hermes CLI 的外观"
+---
+
+# 皮肤与主题
+
+皮肤控制 Hermes CLI 的**视觉呈现**：横幅颜色、spinner（加载动画）面孔与动词、响应框标签、品牌文本以及工具活动前缀。
+
+对话风格与视觉风格是两个独立的概念：
+
+- **Personality（个性）** 改变 agent 的语气和措辞。
+- **Skin（皮肤）** 改变 CLI 的外观。
+
+## 切换皮肤
+
+```bash
+/skin                # show the current skin and list available skins
+/skin ares           # switch to a built-in skin
+/skin mytheme        # switch to a custom skin from ~/.hermes/skins/mytheme.yaml
+```
+
+或在 `~/.hermes/config.yaml` 中设置默认皮肤：
+
+```yaml
+display:
+  skin: default
+```
+
+## 内置皮肤
+
+| 皮肤 | 描述 | Agent 品牌 | 视觉特征 |
+|------|------|-----------|---------|
+| `default` | 经典 Hermes — 金色与 kawaii 风格 | `Hermes Agent` | 暖金色边框，cornsilk 文字，spinner 中的 kawaii 面孔。熟悉的双蛇杖横幅。简洁亲切。 |
+| `ares` | 战神主题 — 深红与青铜 | `Ares Agent` | 深红色边框配青铜点缀。激进的 spinner 动词（"forging"、"marching"、"tempering steel"）。自定义剑盾 ASCII 艺术横幅。 |
+| `mono` | 单色 — 简洁灰度 | `Hermes Agent` | 全灰色，无彩色。边框为 `#555555`，文字为 `#c9d1d9`。适合极简终端或录屏场景。 |
+| `slate` | 冷蓝色 — 面向开发者 | `Hermes Agent` | 皇家蓝边框（`#4169e1`），柔和蓝色文字。沉稳专业。无自定义 spinner，使用默认面孔。 |
+| `daylight` | 适用于亮色终端的浅色主题，深色文字配冷蓝点缀 | `Hermes Agent` | 专为白色或亮色终端设计。深石板色文字配蓝色边框，浅色状态面板，补全菜单在亮色终端配置下保持清晰可读。 |
+| `warm-lightmode` | 适用于浅色终端背景的暖棕/金色文字 | `Hermes Agent` | 适合浅色终端的暖羊皮纸色调。深棕色文字配马鞍棕点缀，奶油色状态面板。比 daylight 主题更温暖的大地色系选择。 |
+| `poseidon` | 海神主题 — 深蓝与海沫绿 | `Poseidon Agent` | 深蓝到海沫绿渐变。海洋主题 spinner（"charting currents"、"sounding the depth"）。三叉戟 ASCII 艺术横幅。 |
+| `sisyphus` | 西西弗斯主题 — 朴素灰度，彰显坚韧 | `Sisyphus Agent` | 浅灰色配强烈对比。巨石主题 spinner（"pushing uphill"、"resetting the boulder"、"enduring the loop"）。巨石与山丘 ASCII 艺术横幅。 |
+| `charizard` | 火山主题 — 焦橙与余烬色 | `Charizard Agent` | 暖焦橙到余烬色渐变。火焰主题 spinner（"banking into the draft"、"measuring burn"）。龙剪影 ASCII 艺术横幅。 |
+
+## 可配置键完整列表
+
+### 颜色（`colors:`）
+
+控制 CLI 中所有颜色值。值为十六进制颜色字符串。
+
+| 键 | 描述 | 默认值（`default` 皮肤） |
+|----|------|------------------------|
+| `banner_border` | 启动横幅周围的面板边框 | `#CD7F32`（青铜色） |
+| `banner_title` | 横幅中的标题文字颜色 | `#FFD700`（金色） |
+| `banner_accent` | 横幅中的区块标题（Available Tools 等） | `#FFBF00`（琥珀色） |
+| `banner_dim` | 横幅中的弱化文字（分隔符、次要标签） | `#B8860B`（暗金菊色） |
+| `banner_text` | 横幅中的正文文字（工具名、技能名） | `#FFF8DC`（玉米丝色） |
+| `ui_accent` | 通用 UI 强调色（高亮、活动元素） | `#FFBF00` |
+| `ui_label` | UI 标签与标记 | `#4dd0e1`（青色） |
+| `ui_ok` | 成功指示器（对勾、完成） | `#4caf50`（绿色） |
+| `ui_error` | 错误指示器（失败、阻断） | `#ef5350`（红色） |
+| `ui_warn` | 警告指示器（注意、审批提示） | `#ffa726`（橙色） |
+| `prompt` | 交互式 prompt（提示符）文字颜色 | `#FFF8DC` |
+| `input_rule` | 输入区域上方的水平分隔线 | `#CD7F32` |
+| `response_border` | agent 响应框边框（ANSI 转义） | `#FFD700` |
+| `session_label` | 会话标签颜色 | `#DAA520` |
+| `session_border` | 会话 ID 弱化边框颜色 | `#8B8682` |
+| `status_bar_bg` | TUI 状态/用量栏的背景色 | `#1a1a2e` |
+| `voice_status_bg` | 语音模式状态徽章的背景色 | `#1a1a2e` |
+| `selection_bg` | TUI 鼠标选区高亮的背景色。未设置时回退到 `completion_menu_current_bg`。 | `#333355` |
+| `completion_menu_bg` | 补全菜单列表的背景色 | `#1a1a2e` |
+| `completion_menu_current_bg` | 当前活动补全行的背景色 | `#333355` |
+| `completion_menu_meta_bg` | 补全元信息列的背景色 | `#1a1a2e` |
+| `completion_menu_meta_current_bg` | 当前活动补全元信息列的背景色 | `#333355` |
+
+### Spinner（`spinner:`）
+
+控制等待 API 响应时显示的动画 spinner。
+
+| 键 | 类型 | 描述 | 示例 |
+|----|------|------|------|
+| `waiting_faces` | 字符串列表 | 等待 API 响应时循环显示的面孔 | `["(⚔)", "(⛨)", "(▲)"]` |
+| `thinking_faces` | 字符串列表 | 模型推理期间循环显示的面孔 | `["(⚔)", "(⌁)", "(<>)"]` |
+| `thinking_verbs` | 字符串列表 | spinner 消息中显示的动词 | `["forging", "plotting", "hammering plans"]` |
+| `wings` | [左, 右] 对的列表 | spinner 周围的装饰括号 | `[["⟪⚔", "⚔⟫"], ["⟪▲", "▲⟫"]]` |
+
+当 spinner 值为空时（如 `default` 和 `mono`），将使用 `display.py` 中的硬编码默认值。
+
+### 品牌（`branding:`）
+
+CLI 界面中使用的文字字符串。
+
+| 键 | 描述 | 默认值 |
+|----|------|--------|
+| `agent_name` | 横幅标题和状态显示中的名称 | `Hermes Agent` |
+| `welcome` | CLI 启动时显示的欢迎消息 | `Welcome to Hermes Agent! Type your message or /help for commands.` |
+| `goodbye` | 退出时显示的消息 | `Goodbye! ☤` |
+| `response_label` | 响应框标题上的标签 | ` ☤ Hermes ` |
+| `prompt_symbol` | 用户输入 prompt 前的符号（裸 token，渲染器会在后面添加空格） | `❯` |
+| `help_header` | `/help` 命令输出的标题文字 | `(^_^)? Available Commands` |
+
+### 其他顶级键
+
+| 键 | 类型 | 描述 | 默认值 |
+|----|------|------|--------|
+| `tool_prefix` | 字符串 | CLI 中工具输出行的前缀字符 | `┊` |
+| `tool_emojis` | 字典 | 各工具的 emoji 覆盖，用于 spinner 和进度显示（`{tool_name: emoji}`） | `{}` |
+| `banner_logo` | 字符串 | Rich 标记 ASCII 艺术 logo（替换默认的 HERMES_AGENT 横幅） | `""` |
+| `banner_hero` | 字符串 | Rich 标记英雄艺术图（替换默认的双蛇杖图案） | `""` |
+
+## 自定义皮肤
+
+在 `~/.hermes/skins/` 下创建 YAML 文件。用户皮肤会从内置 `default` 皮肤继承缺失的值，因此只需指定要更改的键。
+
+### 完整自定义皮肤 YAML 模板
+
+```yaml
+# ~/.hermes/skins/mytheme.yaml
+# Complete skin template — all keys shown. Delete any you don't need;
+# missing values automatically inherit from the 'default' skin.
+
+name: mytheme
+description: My custom theme
+
+colors:
+  banner_border: "#CD7F32"
+  banner_title: "#FFD700"
+  banner_accent: "#FFBF00"
+  banner_dim: "#B8860B"
+  banner_text: "#FFF8DC"
+  ui_accent: "#FFBF00"
+  ui_label: "#4dd0e1"
+  ui_ok: "#4caf50"
+  ui_error: "#ef5350"
+  ui_warn: "#ffa726"
+  prompt: "#FFF8DC"
+  input_rule: "#CD7F32"
+  response_border: "#FFD700"
+  session_label: "#DAA520"
+  session_border: "#8B8682"
+  status_bar_bg: "#1a1a2e"
+  voice_status_bg: "#1a1a2e"
+  selection_bg: "#333355"
+  completion_menu_bg: "#1a1a2e"
+  completion_menu_current_bg: "#333355"
+  completion_menu_meta_bg: "#1a1a2e"
+  completion_menu_meta_current_bg: "#333355"
+
+spinner:
+  waiting_faces:
+    - "(⚔)"
+    - "(⛨)"
+    - "(▲)"
+  thinking_faces:
+    - "(⚔)"
+    - "(⌁)"
+    - "(<>)"
+  thinking_verbs:
+    - "processing"
+    - "analyzing"
+    - "computing"
+    - "evaluating"
+  wings:
+    - ["⟪⚡", "⚡⟫"]
+    - ["⟪●", "●⟫"]
+
+branding:
+  agent_name: "My Agent"
+  welcome: "Welcome to My Agent! Type your message or /help for commands."
+  goodbye: "See you later! ⚡"
+  response_label: " ⚡ My Agent "
+  prompt_symbol: "⚡"
+  help_header: "(⚡) Available Commands"
+
+tool_prefix: "┊"
+
+# Per-tool emoji overrides (optional)
+tool_emojis:
+  terminal: "⚔"
+  web_search: "🔮"
+  read_file: "📄"
+
+# Custom ASCII art banners (optional, Rich markup supported)
+# banner_logo: |
+#   [bold #FFD700] MY AGENT [/]
+# banner_hero: |
+#   [#FFD700]  Custom art here  [/]
+```
+
+### 最简自定义皮肤示例
+
+由于所有值都继承自 `default`，最简皮肤只需指定要更改的部分：
+
+```yaml
+name: cyberpunk
+description: Neon terminal theme
+
+colors:
+  banner_border: "#FF00FF"
+  banner_title: "#00FFFF"
+  banner_accent: "#FF1493"
+
+spinner:
+  thinking_verbs: ["jacking in", "decrypting", "uploading"]
+  wings:
+    - ["⟨⚡", "⚡⟩"]
+
+branding:
+  agent_name: "Cyber Agent"
+  response_label: " ⚡ Cyber "
+
+tool_prefix: "▏"
+```
+
+## Hermes Mod — 可视化皮肤编辑器
+
+[Hermes Mod](https://github.com/cocktailpeanut/hermes-mod) 是一个社区构建的 Web UI，用于可视化创建和管理皮肤。无需手写 YAML，提供带实时预览的点击式编辑器。
+
+![Hermes Mod skin editor](https://raw.githubusercontent.com/cocktailpeanut/hermes-mod/master/nous.png)
+
+**功能说明：**
+
+- 列出所有内置和自定义皮肤
+- 将任意皮肤在可视化编辑器中打开，涵盖所有 Hermes 皮肤字段（颜色、spinner、品牌、工具前缀、工具 emoji）
+- 根据文字 prompt 生成 `banner_logo` 文字艺术
+- 将上传的图片（PNG、JPG、GIF、WEBP）转换为 `banner_hero` ASCII 艺术，支持多种渲染风格（盲文点阵、ASCII 字符渐变、方块、点阵）
+- 直接保存到 `~/.hermes/skins/`
+- 通过更新 `~/.hermes/config.yaml` 激活皮肤
+- 显示生成的 YAML 及实时预览
+
+### 安装
+
+**方式一 — Pinokio（一键安装）：**
+
+在 [pinokio.computer](https://pinokio.computer) 上找到并一键安装。
+
+**方式二 — npx（终端最快方式）：**
+
+```bash
+npx -y hermes-mod
+```
+
+**方式三 — 手动安装：**
+
+```bash
+git clone https://github.com/cocktailpeanut/hermes-mod.git
+cd hermes-mod/app
+npm install
+npm start
+```
+
+### 使用方法
+
+1. 启动应用（通过 Pinokio 或终端）。
+2. 打开 **Skin Studio**。
+3. 选择要编辑的内置或自定义皮肤。
+4. 从文字生成 logo，和/或上传图片作为英雄艺术图。选择渲染风格和宽度。
+5. 编辑颜色、spinner、品牌及其他字段。
+6. 点击 **Save** 将皮肤 YAML 写入 `~/.hermes/skins/`。
+7. 点击 **Activate** 将其设为当前皮肤（更新 `config.yaml` 中的 `display.skin`）。
+
+Hermes Mod 遵循 `HERMES_HOME` 环境变量，因此也适用于[配置文件](/user-guide/profiles)。
+
+## 操作说明
+
+- 内置皮肤从 `hermes_cli/skin_engine.py` 加载。
+- 未知皮肤自动回退到 `default`。
+- `/skin` 立即更新当前会话的活动 CLI 主题。
+- `~/.hermes/skins/` 中的用户皮肤优先于同名内置皮肤。
+- 通过 `/skin` 切换皮肤仅对当前会话有效。如需永久设为默认皮肤，请在 `config.yaml` 中配置。
+- `banner_logo` 和 `banner_hero` 字段支持 Rich 控制台标记（例如 `[bold #FF0000]text[/]`），可用于彩色 ASCII 艺术。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/spotify.md

@@ -0,0 +1,279 @@
+# Spotify
+
+Hermes 可以直接控制 Spotify——播放、队列、搜索、播放列表、已保存的曲目/专辑以及收听历史——通过 Spotify 官方 Web API 配合 PKCE OAuth 实现。Token（令牌）存储在 `~/.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` 并提示"no active device"；在任意设备上打开 Spotify 后重试即可。
+
+## 设置
+
+### 一键完成：`hermes tools` 或首次运行设置
+
+最快捷的方式。运行：
+
+```bash
+hermes tools
+```
+
+滚动到 `🎵 Spotify`，按空格键启用，再按 `s` 保存。同样的开关也可在首次运行 `hermes setup` / `hermes setup tools` 流程中找到。Spotify 默认为可选启用，在此处启用会触发与 `hermes tools` 相同的提供商感知配置流程。
+
+Hermes 会直接进入 OAuth 流程——如果你还没有 Spotify 应用，它会内联引导你创建一个。完成后，工具集即被启用并完成认证，一步到位。
+
+如果你希望分步操作（或稍后重新认证），请使用下方的两步流程。
+
+### 两步流程
+
+#### 1. 启用工具集
+
+```bash
+hermes tools
+```
+
+启用 `🎵 Spotify`，保存，当内联向导弹出时关闭它（Ctrl+C）。工具集保持开启状态，仅跳过认证步骤。
+
+#### 2. 运行登录向导
+
+```bash
+hermes auth spotify
+```
+
+7 个 Spotify 工具只有在完成第 1 步后才会出现在 agent 的工具集中——它们默认关闭，以避免不需要它们的用户在每次 API 调用时额外传输工具 schema。
+
+若未设置 `HERMES_SPOTIFY_CLIENT_ID`，Hermes 会内联引导你完成应用注册：
+
+1. 在浏览器中打开 `https://developer.spotify.com/dashboard`
+2. 打印需要粘贴到 Spotify "Create app" 表单中的确切值
+3. 提示你输入获得的 Client ID
+4. 将其保存到 `~/.hermes/.env`，后续运行时跳过此步骤
+5. 直接进入 OAuth 授权流程
+
+授权完成后，token 将写入 `~/.hermes/auth.json` 的 `providers.spotify` 下。当前推理提供商不会改变——Spotify 认证与你的 LLM 提供商无关。
+
+### 创建 Spotify 应用（向导所需内容）
+
+当 dashboard 打开后，点击 **Create app** 并填写：
+
+| 字段 | 值 |
+|-------|-------|
+| App name | 任意（例如 `hermes-agent`） |
+| App description | 任意（例如 `personal Hermes integration`） |
+| Website | 留空 |
+| Redirect URI | `http://127.0.0.1:43827/spotify/callback` |
+| Which API/SDKs? | 勾选 **Web API** |
+
+同意条款并点击 **Save**。在下一页点击 **Settings** → 复制 **Client ID** 并粘贴到 Hermes 提示中。这是 Hermes 唯一需要的值——PKCE 不使用 client secret。
+
+### 通过 SSH / 在无头环境中运行
+
+若设置了 `SSH_CLIENT` 或 `SSH_TTY`，Hermes 在向导和 OAuth 步骤中均会跳过自动打开浏览器。复制 Hermes 打印的 dashboard 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](../../guides/oauth-over-ssh.md)。
+
+## 验证
+
+```bash
+hermes auth status spotify
+```
+
+显示 token 是否存在以及 access token 的过期时间。刷新是自动的：当任何 Spotify API 调用返回 401 时，客户端会用 refresh token 换取新 token 并重试一次。Refresh token 在 Hermes 重启后仍然有效，只有在你的 Spotify 账号设置中撤销该应用，或运行 `hermes auth logout spotify` 后才需要重新认证。
+
+## 使用方法
+
+登录后，agent 可访问 7 个 Spotify 工具。你用自然语言与 agent 交流——它会选择正确的工具和操作。为获得最佳效果，agent 会加载一个配套技能，教授规范的使用模式（先搜索再播放、何时不需要预先调用 `get_state` 等）。
+
+```
+> 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`
+控制和查看播放状态，以及获取最近播放历史。
+
+| 操作 | 用途 | 需要 Premium？ |
+|--------|---------|----------|
+| `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 切换播放（例如"transfer Spotify to the kitchen speaker"），或在脚本中调用 `spotify_devices list` 获取确切的 `device_id` 后传给 `spotify_devices transfer`。若音箱未出现，请在 Spotify 应用或音箱的 Spotify 集成中打开一次，让 Spotify 将其注册为活跃的 Connect 目标。
+
+#### `spotify_queue`
+| 操作 | 用途 | 需要 Premium？ |
+|--------|---------|----------|
+| `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 Premium 版
+
+只读工具在免费账号上可用。任何修改播放状态或队列的操作都需要 Premium。
+
+| 免费版可用 | 需要 Premium |
+|---------------|------------------|
+| `spotify_search`（全部） | `spotify_playback` — play、pause、next、previous、seek、set_repeat、set_shuffle、set_volume |
+| `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 任务可以按任意计划触发播放，无需编写额外代码。
+
+### 早晨唤醒播放列表
+
+```bash
+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 点发生的事情：
+1. Cron 启动一个无头 Hermes 会话。
+2. Agent 读取 prompt（提示词），调用 `spotify_devices list` 按名称找到"kitchen speaker"，然后依次调用 `spotify_devices transfer` → `spotify_playback set_volume` → `spotify_playback set_shuffle` → `spotify_search` + `spotify_playback play`。
+3. 音乐在目标音箱上开始播放。总计：一个会话，几次工具调用，无需人工干预。
+
+### 夜间收尾
+
+```bash
+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、智能音箱），而非手机。
+- **任何修改播放状态的操作都需要 Premium**——播放、暂停、跳曲、音量、切换设备。只读 cron 任务（例如定时"发送我最近播放的曲目"）在免费版上可正常使用。
+- **cron agent 继承你的活跃工具集。** Spotify 必须在 `hermes tools` 中启用，cron 会话才能看到 Spotify 工具。
+- **Cron 任务以 `skip_memory=True` 运行**，不会写入你的记忆存储。
+
+完整 cron 参考：[Cron Jobs](./cron)。
+
+## 退出登录
+
+```bash
+hermes auth logout spotify
+```
+
+从 `~/.hermes/auth.json` 中移除 token。若还需清除应用配置，请从 `~/.hermes/.env` 中删除 `HERMES_SPOTIFY_CLIENT_ID`（以及 `HERMES_SPOTIFY_REDIRECT_URI`，如果你设置了的话），或重新运行向导。
+
+若要在 Spotify 侧撤销应用，请访问[已连接到你账号的应用](https://www.spotify.com/account/apps/)并点击 **REMOVE ACCESS**。
+
+## 故障排查
+
+**`403 Forbidden — Player command failed: No active device found`** — 你需要在至少一台设备上运行 Spotify。在手机、桌面端或网页播放器上打开 Spotify 应用，随便播放一首曲目以注册设备，然后重试。`spotify_devices list` 可显示当前可见的设备。
+
+**`403 Forbidden — Premium required`** — 你使用的是免费账号，但尝试执行需要 Premium 的播放操作。请参阅上方的功能矩阵。
+
+**`get_currently_playing` 返回 `204 No Content`** — 当前所有设备上均无内容播放。这是 Spotify 的正常响应，不是错误；Hermes 将其呈现为说明性的空结果（`is_playing: false`）。
+
+**`INVALID_CLIENT: Invalid redirect URI`** — 你的 Spotify 应用设置中的 redirect URI 与 Hermes 使用的不匹配。默认值为 `http://127.0.0.1:43827/spotify/callback`。请将其添加到应用的允许 redirect URI 列表中，或在 `~/.hermes/.env` 中将 `HERMES_SPOTIFY_REDIRECT_URI` 设置为你注册的值。
+
+**`429 Too Many Requests`** — Spotify 的速率限制。Hermes 会返回友好的错误提示；等待一分钟后重试。若持续出现，你可能在脚本中运行了紧密循环——Spotify 的配额大约每 30 秒重置一次。
+
+**`401 Unauthorized` 持续出现** — 你的 refresh token 已被撤销（通常是因为你从账号中移除了该应用，或应用被删除）。重新运行 `hermes auth spotify`。
+
+**向导未打开浏览器** — 若你通过 SSH 连接或在没有显示器的容器中运行，Hermes 会检测到并跳过自动打开。复制它打印的 dashboard URL 并手动打开。
+
+## 进阶：自定义 scope
+
+默认情况下，Hermes 会请求所有已发布工具所需的 scope。若需限制访问权限，可覆盖默认值：
+
+```bash
+hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
+```
+
+Scope 参考：[Spotify Web API scopes](https://developer.spotify.com/documentation/web-api/concepts/scopes)。若请求的 scope 少于某个工具所需，该工具的调用将以 403 失败。
+
+## 进阶：自定义 client ID / redirect URI
+
+```bash
+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
+```
+
+Redirect URI 必须在你的 Spotify 应用设置中加入白名单。默认值适用于绝大多数情况——只有在 43827 端口被占用时才需要更改。
+
+## 文件位置
+
+| 文件 | 内容 |
+|------|----------|
+| `~/.hermes/auth.json` → `providers.spotify` | access token、refresh token、过期时间、scope、redirect URI |
+| `~/.hermes/.env` | `HERMES_SPOTIFY_CLIENT_ID`，可选 `HERMES_SPOTIFY_REDIRECT_URI` |
+| Spotify 应用 | 由你在 [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard) 管理；包含 Client ID 和 redirect URI 白名单 |