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 技能 允许代理根据你的请求安装和切换宠物。