PetsHermes 可以顯示一個動畫 寵物 —— 一個小吉祥物精靈，它會根據代理（agent）正在執行的操作（空閒、運行工具、思考、完成、失敗）在 CLI、TUI 和 桌面應用 中做出反應。寵物來自公共 petdex 畫廊。寵物純粹是裝飾性的。它們對 提示緩存、令牌或代理的行為沒有任何影響 —— 精靈僅用於顯示。該功能 默認關閉，直到你安裝並選擇一個寵物之前都處於休眠狀態。

工作原理

• 寵物被安裝到你配置文件的 pets/ 目錄中（<HERMES_HOME>/pets/<slug>/），因此每個 配置文件 都擁有自己的一套寵物。

• 選擇寵物會將 display.pet.slug 和 display.pet.enabled 寫入 config.yaml —— 沒有任何內容作為密鑰或環境變量存儲。

• 每個界面監視其已經跟蹤的活動，並將其映射到六種動畫狀態之一。映射邏輯集中在一處，以確保所有界面的行為一致：

  代理活動	寵物狀態
  工具/回合剛剛失敗	failed
  計劃完成（所有待辦事項已完成）	jump（慶祝）
  回合乾淨利落地完成	wave
  工具正在執行	run
  模型正在思考/閱讀	review
  回合進行中（未指定）	run
  等待用戶操作（澄清/批准提示已打開）	waiting（在傳統的 8 行工作表中回退到 idle）
  無活動發生	idle

渲染

在終端（CLI/TUI）中，如果你的終端支持圖形協議（kitty、Ghostty、WezTerm、iTerm2 或 sixel），Hermes 將以全保真度渲染精靈。否則，它會自動回退到真彩色 Unicode 半塊 渲染。在管道或重定向中（無 TTY），終端渲染按設計被禁用。

桌面應用將寵物繪製為畫布上的浮動精靈，並通過 設置 → 外觀 進行切換。

快速開始（CLI）

# Browse the gallery (filter by substring)
hermes pets list
hermes pets list cat

# Install a pet and make it active in one step
hermes pets install boba --select

# Preview / animate it in your terminal (Ctrl+C to stop)
hermes pets show

# Check your setup
hermes pets doctor

hermes pets 命令

目標	命令
瀏覽畫廊	hermes pets list [query] [--limit N]
列出已安裝的寵物	hermes pets list --installed
安裝寵物	hermes pets install <slug> [--select] [--force]
設置活躍寵物	hermes pets select [slug]（省略 slug 以使用選擇器）
全局調整寵物大小	hermes pets scale <factor>（例如 0.5，限制在 0.1–3.0 之間）
預覽/動畫演示	hermes pets show [slug] [--state <s>] [--cycle] [--once] [--mode <m>] [--scale <f>]
禁用寵物	hermes pets off
移除已安裝的寵物	hermes pets remove <slug>
診斷設置	hermes pets doctor

hermes pets show 標誌：

• --state — 播放單個狀態（idle、wave、run、failed、review、jump）。
• --cycle — 循環播放所有狀態。
• --once — 播放一次而不是循環。
• --mode — 覆蓋渲染協議（kitty、iterm、sixel、unicode、auto）。
• --scale — 覆蓋屏幕顯示比例（0 = 使用配置值）。

/pet 斜槓命令

在 CLI 和 TUI 中，你可以在不離開會話的情況下管理寵物：

• /pet — 切換寵物的開啟/關閉狀態（如果沒有活躍寵物，則採用第一個已安裝的寵物）。
• /pet list — 瀏覽畫廊。
• /pet scale <factor> — 全局調整寵物大小（例如 /pet scale 0.5）。
• /pet <slug> — 採用特定的寵物。
• /pet off — 禁用寵物。

在 TUI 中，/pet list 會打開一個交互式選擇器覆蓋層；在桌面應用中，它會打開 Cmd+K 寵物面板。

生成寵物（/hatch）

除了從畫廊安裝預製寵物外，Hermes 還可以根據文本描述 生成全新的寵物 —— 這是其自帶的 AI 精靈生成流水線。

• CLI/TUI：/hatch <description>（別名 /generate-pet），或 hermes pets → 生成流程。
• 桌面應用：類似 Pokédex 風格的 生成 UI —— 包含動畫蛋、孵化特效和草稿選擇器。

生成工作原理（一個兩步、成本受限的流程）：

1. 基礎草稿 — 生成少量廉價、僅基於提示的“這個寵物應該長什麼樣”的變體。你可以選擇一個，或者重新混合/重試以獲取新一輪草稿。
2. 孵化 — 選定的基礎草稿用作參考圖像，為每個 Hermes 狀態（空閒、思考、使用工具等）生成一行 grounded 動畫，這些動畫被確定性切片為幀，並打包到標準的 petdex/Codex 圖集中（8×9 網格，單元格大小為 192×208）。結果是一個有效的精靈表，你可以保留它——甚至可以提交到 petdex submit。

圖像後端

生成使用活躍的 圖像生成提供商，但它需要 參考圖像 grounding，以便每個動畫行保持與基礎草稿相同的角色特徵。支持參考功能的後端：Nous Portal、OpenRouter、OpenAI (gpt-image-2) 和 Krea。OpenRouter/Nous 默認運行質量優先的模型鏈。

• 分辨率順序偏好：Nous Portal → OpenAI → OpenRouter。
• 如果未配置支持參考功能的後端，生成過程會顯示一個可操作的錯誤，指引你前往 hermes tools → 圖像生成。（安裝/採用現有的畫廊寵物不需要圖像後端。）
• 可以通過 HERMES_PET_IMAGE_PROVIDER 環境變量覆蓋後端（例如 HERMES_PET_IMAGE_PROVIDER=openrouter）。

桌面應用

在桌面應用中，你可以通過兩種方式管理寵物：

• Cmd+K → "Pets…" — 無需離開鍵盤即可瀏覽、搜索、領養和切換寵物（鏡像主題選擇器）。
• Settings → Appearance — 相同的畫廊，外加一個尺寸滑塊，拖動時可實時調整浮動吉祥物的尺寸。

兩者均可原地領養/切換/調整浮動吉祥物的大小——尺寸更改立即生效；領養新寵物後，它會在片刻內亮起。

彈出式疊加層

Shift+點擊浮動寵物，將其彈出到一個獨立的透明、始終置頂的桌面窗口中。在此狀態下，即使 Hermes 最小化（Codex 風格），它仍保持可見，因此只需瞥一眼即可知曉代理正在執行的操作。

彈出後的手勢操作：

手勢	操作
拖動	將寵物移動到屏幕上的任何位置，甚至應用窗口之外。其位置和彈出/收回狀態在重啟後保持不變。
單擊	打開一個迷你編寫器，向最近的會話發送提示詞——無需顯示應用主界面。
雙擊	切換應用窗口：如果窗口在前臺則最小化，如果隱藏則恢復。
Shift+點擊	將寵物收回到應用窗口內。
郵件圖標	僅當你離開期間某一輪對話結束時出現；點擊可將應用提升至最近的話題線程（並標記為已讀）。

只有彈出的寵物會顯示氣泡對話框（working…、thinking…、your turn 等）——在應用窗口內，應用本身即是交互界面，因此寵物在那裡保持靜默。

該疊加層是應用內寵物的純粹傀儡——它不攜帶獨立的網關連接，也不會出現在 Dock 欄或應用切換器中。

配置

所有設置均位於 config.yaml 中的 display.pet 下：

display:
  pet:
    enabled: false        # master on/off (true once you select a pet)
    slug: ""              # active pet; empty = first installed
    render_mode: auto      # auto | kitty | iterm | sixel | unicode | off
    scale: 0.33           # master size knob (relative to native 192x208 frames)
    unicode_cols: 0       # hard override for terminal width (0 = derive from scale)

• scale 是單一的主尺寸控制旋鈕。一個數值即可縮小所有界面：桌面畫布按其比例縮放像素，CLI/TUI 則據此推導終端列寬。半塊字符（half-block）回退模式會限制最低可讀性下限——它無法像真正的像素 kitty/GUI 渲染那樣無限縮小而不變得模糊，因此相同的 scale 在 kitty 下看起來清晰銳利，但在半塊字符模式下會被限制在下限。
• render_mode: auto 自動檢測 kitty/iTerm2/sixel 並回退到 unicode 半塊字符。顯式設置它以強制使用特定協議，或設置為 off 以禁用終端渲染，同時保留桌面上的寵物顯示。
• unicode_cols 獨立於 scale 固定終端列寬；將其保留為 0 以從 scale 推導寬度。

故障排除

運行 hermes pets doctor —— 它將報告：

• 寵物目錄及已安裝的寵物，
• display.pet.enabled、display.pet.slug 以及解析後的當前活躍寵物，
• 配置的 render_mode、檢測到的終端圖形協議，以及 TTY 的有效模式，
• Pillow（用於精靈解碼）是否可導入。

一旦寵物已安裝、選中、啟用且 Pillow 可用，它將打印 ✓ ready。

常見陷阱：

• 寵物僅在已安裝且已選中（enabled: true）時才會顯示。
• 在管道/重定向內部（無 TTY），終端渲染按設計被禁用。
• petdex npm CLI 安裝到 ~/.codex/pets；Hermes 使用其 own 配置文件作用域下的 <HERMES_HOME>/pets/ —— 請通過 hermes pets 進行安裝。

另見

• petdex 技能 允許代理根據你的請求安裝和切換寵物。