宠物

Hermes 可以显示一个动画宠物——一个小型吉祥物精灵图，会随 agent 的行为（空闲、运行工具、思考、完成、失败）在 CLI、TUI 和桌面应用上做出反应。宠物来自公开的 petdex 图库。

宠物纯粹是装饰性的。它们对提示词缓存、token 或 agent 行为毫无影响——精灵图只是显示层的事。该特性默认关闭，在你安装并选择一只宠物前一直休眠。

工作原理

• 宠物安装到你 profile 的 pets/ 目录（<HERMES_HOME>/pets/<slug>/），因此每个 profile 保留自己的一套。

• 选择宠物会把 display.pet.slug 和 display.pet.enabled 写入 config.yaml——没有任何内容存为机密或环境变量。

• 每个界面监听它本就在跟踪的活动，并映射到六种动画状态之一。映射集中在一处，使各界面行为一致：

  agent 活动	宠物状态
  工具/回合刚失败	failed
  计划完成（所有 todo 完成）	jump（庆祝）
  回合干净结束	wave
  工具正在执行	run
  模型正在思考/阅读	review
  回合进行中（未指定）	run
  等待你（clarify/审批提示打开）	waiting（在旧的 8 行 sheet 上回退为 idle）
  无事发生	idle

渲染

在终端（CLI/TUI）中，当你的终端支持图形协议（kitty、Ghostty、WezTerm、iTerm2 或 sixel）时，Hermes 以完整保真度渲染精灵图。否则自动回退到真彩色 Unicode 半块渲染。在管道或重定向中（无 TTY），终端渲染按设计禁用。

桌面应用把宠物画成画布上的浮动精灵图，并在设置 → 外观中切换。

快速开始（CLI）

# 浏览图库（按子串过滤）
hermes pets list
hermes pets list cat

# 一步安装并激活宠物
hermes pets install boba --select

# 在终端中预览/播放动画（Ctrl+C 停止）
hermes pets show

# 检查你的配置
hermes pets doctor

hermes pets 命令

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 <描述>（别名 /generate-pet），或 hermes pets → 生成流程。
• 桌面应用：Pokédex 风格的生成 UI——一枚动画蛋、孵化特效和草稿选择器。

生成方式（两步、成本有界的流程）：

1. 基础草稿——生成几个廉价、纯提示词的"这只宠物该长什么样"变体。你选一个，或 remix/重试用新一轮。
2. 孵化——以选定的基础图为参考图，为每个 Hermes 状态（idle、思考、使用工具等）生成一条有依据的动画行，再确定性地切分成帧，打包成标准 petdex/Codex 图集（8×9 网格、192×208 单元格）。结果是一张你可保留的有效精灵图——还可 petdex submit。

图像后端

生成使用活动的图像生成提供商，但它需要参考图依据，使每条动画行都与基础图保持同一角色。支持参考的后端：Nous Portal、OpenRouter、OpenAI（gpt-image-2）和 Krea。OpenRouter/Nous 默认运行质量优先的模型链。

• 解析顺序优先 Nous Portal → OpenAI → OpenRouter。
• 若未配置支持参考的后端，生成会给出可操作错误，指向 hermes tools → Image Generation。（安装/领养既有图库宠物不需要图像后端。）
• 用 HERMES_PET_IMAGE_PROVIDER 环境变量覆盖后端（如 HERMES_PET_IMAGE_PROVIDER=openrouter）。

桌面应用

在桌面应用中你可以用两种方式管理宠物：

• Cmd+K → "Pets…"——不离开键盘即可浏览、搜索、领养和切换宠物（与主题选择器一致）。
• 设置 → 外观——同一个图库，外加一个尺寸滑块，拖动时实时缩放浮动吉祥物。

两者都就地领养/切换/缩放浮动吉祥物——尺寸变更即时生效；领养新宠物片刻内即点亮。

漫游

设置 → 外观有一个 Roam 开关：开启后，agent 空闲时宠物会自己在窗口里溜达——走过表面、停顿、在各处之间跳。漫游仅在宠物在窗口内、处于活动状态且 agent 休息时运行；任何 agent 驱动的状态（工作、庆祝）立即接管。该开关默认关闭，跨重启持久。

Alt+滚轮缩放

按住 Alt 在宠物上滚动鼠标滚轮即可就地缩放——在应用窗口和弹出浮层中都有效。浮层朝光标位置缩放，所得比例持久保存，跨重启存活并与应用内宠物保持同步。

情绪反应

对 agent 说点好听的——"good bot"、"thank you"、"ily"、<3 或一个爱心 emoji——宠物会以漂浮爱心（桌面）或爱心闪屏（CLI/TUI）回应。检测是一份精选、零 token 的词表，在每条用户消息上本地匹配（无模型调用）；它在指向 agent 的喜爱和感谢上触发，而非一般正面情绪。所有界面——CLI 宠物、TUI、桌面浮动宠物和弹出浮层——都基于同一信号反应。

弹出浮层

Shift+点击浮动宠物可把它弹出成自己的透明、置顶桌面窗口。在那里，即使 Hermes 最小化它也保持可见（Codex 风格），因此一眼就能知道 agent 在做什么。

弹出后的手势：

只有弹出的宠物会显示对话气泡（working…、thinking…、your turn……）——在窗口内，应用本身就是界面，因此宠物保持安静。

该浮层纯粹是应用内宠物的提线木偶——它没有独立的网关连接，也从不出现在 Dock 或应用切换器中。

配置

所有设置位于 config.yaml 的 display.pet 下：

display:
  pet:
    enabled: false        # 总开关（选择宠物后为 true）
    slug: ""              # 活动宠物；空 = 第一只已安装
    render_mode: auto      # auto | kitty | iterm | sixel | unicode | off
    scale: 0.33           # 主尺寸旋钮（相对原生 192x208 帧）
    unicode_cols: 0       # 终端宽度硬覆盖（0 = 由 scale 推导）

• scale 是唯一的主尺寸旋钮。一个数字缩放所有界面：桌面画布按它缩放像素，CLI/TUI 据此推导终端列宽。半块回退会限制在可读性下限——它不能像真像素 kitty/GUI 渲染那样缩得极小而不糊成一团，因此同一 scale 在 kitty 下锐利、在半块下则被下限卡住。
• render_mode: auto 检测 kitty/iTerm2/sixel 并回退到 Unicode 半块。显式设置可强制某协议，或设为 off 在保留桌面宠物的同时禁用终端渲染。
• unicode_cols 独立于 scale 固定终端列宽；留 0 则由 scale 推导宽度。

故障排查

运行 hermes pets doctor——它报告：

• pets 目录及已安装宠物；
• display.pet.enabled、display.pet.slug 和解析出的活动宠物；
• 配置的 render_mode、检测到的终端图形协议、以及 TTY 的有效模式；
• Pillow（用于精灵图解码）是否可导入。

当宠物已安装、已选择、已启用且 Pillow 可用时，它打印 ✓ ready。

常见坑：

• 宠物只有在已安装且已选择（enabled: true）时才显示。
• 在管道/重定向中（无 TTY），终端渲染按设计禁用。
• petdex npm CLI 安装到 ~/.codex/pets；Hermes 改用自己按 profile 隔离的 <HERMES_HOME>/pets/——请通过 hermes pets 安装。

另见

• hermes-agent skill 可应你要求替你安装和切换宠物（见其 references/petdex.md）。