petdex

Petdex 技能

浏览、安装并选择来自公共 petdex 画廊的动画“宠物”吉祥物。已安装的宠物会响应 Agent 的活动状态（空闲、运行工具、审核、出错、完成），并显示在 Hermes CLI、TUI 和桌面应用中。此技能用于管理 hermes pets CLI 和 display.pet 配置，不会生成精灵图。

适用场景

• 用户想要桌面或终端吉祥物，或询问“pets”／petdex。
• 用户想要更换、预览或停用当前宠物。
• 排查宠物未显示的原因（终端图形支持、配置）。

前提条件

• 可访问网络，以读取 petdex.dev 画廊和清单（只读，无需身份验证）。
• Pillow（Hermes 的核心依赖项），用于解码精灵图——已安装。
• 如需在终端中实现完整保真渲染：需要支持图形的终端（kitty、 Ghostty、WezTerm、iTerm2 或 sixel）。否则会自动使用真彩色 Unicode 半块字符回退方案。

运行方法

使用 terminal 工具运行 hermes pets <subcommand>。

快速参考

目标	命令
浏览画廊	hermes pets list（添加子字符串进行筛选：hermes pets list cat）
列出已安装的宠物	hermes pets list --installed
安装宠物	hermes pets install <slug>（添加 --select 将其设为当前宠物）
设置当前宠物	hermes pets select <slug>（省略 slug 可打开选择器）
调整宠物在所有位置的大小	hermes pets scale <factor>（例如 0.5，范围限制为 0.1–3.0）
在终端中预览／播放动画	hermes pets show [slug] [--cycle] [--state run]
停用宠物	hermes pets off
移除宠物	hermes pets remove <slug>
诊断设置	hermes pets doctor

操作步骤

1. 查找宠物：运行 hermes pets list <query> 并记下其 slug。
2. 安装并启用：运行 hermes pets install <slug> --select。
3. 预览：运行 hermes pets show（按 Ctrl+C 停止）。
4. 确认设置：运行 hermes pets doctor——查看解析出的宠物、已配置的渲染模式、检测到的终端图形协议以及实际生效的模式。

宠物会安装到 <HERMES_HOME>/pets/<slug>/（按配置档案区分）。选择宠物后，会将 display.pet.slug 和 display.pet.enabled 写入 config.yaml。

配置

config.yaml 中的 display.pet 配置项：

• enabled（bool）——总开关。
• slug（str）——当前宠物；留空时使用第一个已安装的宠物。
• render_mode——auto（自动检测）| kitty | iterm | sixel | unicode | off。
• scale（float）——原生 192×208 帧的屏幕显示尺寸（默认值为 0.33， 范围限制为 0.1–3.0）。使用此设置可调整所有界面的大小；可通过 hermes pets scale <factor>、/pet scale 斜杠命令或桌面端的 Appearance 滑块进行设置。
• unicode_cols（int）——Unicode 回退方案的列宽。

注意事项

• 只有安装并选中宠物（enabled: true）后，宠物才会显示。
• 在管道或重定向中（没有 TTY）时，终端渲染会按设计禁用。
• petdex npm CLI 会将宠物安装到 ~/.codex/pets；Hermes 使用其自身按配置档案区分的 <HERMES_HOME>/pets/——请通过 hermes pets 安装。

验证

• 如果宠物已安装、选中并启用，且 Pillow 可以导入，hermes pets doctor 会报告 ✓ ready。