跳到主要内容

宠物

Kopi Agent 可以显示一个动画宠物——一个小吉祥物精灵,会根据 agent 的状态(空闲、运行工具、思考、完成、失败)做出反应,适用于 CLI、TUI 和桌面应用。宠物来自公开的 petdex 图库。

宠物纯粹是装饰性的。它们不会影响 prompt 缓存、token 或 agent 的行为——精灵只是一个显示层面的功能。该功能默认关闭,在你安装并选择宠物之前始终处于休眠状态。

工作原理​

  • 宠物安装在你 profile 的 pets/ 目录中(<KOPI_HOME>/pets/<slug>/),因此每个 profile 都保留自己的一套宠物。

  • 选择宠物时会将 display.pet.slug 和 display.pet.enabled 写入 config.yaml——不会以 secret 或 env var 的形式存储任何内容。

  • 各个界面监听它们本来就会跟踪的活动,并将其映射到六种动画状态之一。映射逻辑集中在一个地方,因此所有界面的行为保持一致:

    Agent 活动宠物状态
    某个工具/轮次刚刚失败failed
    一个计划已完成(所有 todo 均已完成)jump(庆祝)
    一轮对话顺利完成wave
    某个工具正在执行run
    模型正在思考/阅读review
    轮次进行中(未指定)run
    等待你的输入(打开了澄清/批准提示)waiting(在旧版 8 行素材表上回退为 idle)
    无事发生idle

渲染​

在终端(CLI/TUI)中,当你的终端支持图形协议(kitty、Ghostty、WezTerm、iTerm2 或 sixel)时,Kopi Agent 会以完整保真度渲染精灵。否则会自动回退到真彩色 Unicode 半块字符渲染。在管道或重定向中(无 TTY)时,出于设计考虑会禁用终端渲染。

桌面应用将宠物绘制为画布上的浮动精灵,并可通过 Settings → Appearance 开关。

快速开始(CLI)​

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

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

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

# Check your setup
kopi pets doctor

kopi pets 命令​

目标命令
浏览图库kopi pets list [query] [--limit N]
列出已安装的宠物kopi pets list --installed
安装宠物kopi pets install <slug> [--select] [--force]
设置当前宠物kopi pets select [slug](省略 slug 可打开选择器)
在所有界面调整宠物大小kopi pets scale <factor>(例如 0.5,限制范围为 0.1–3.0)
预览/播放动画kopi pets show [slug] [--state <s>] [--cycle] [--once] [--mode <m>] [--scale <f>]
禁用宠物kopi pets off
移除已安装的宠物kopi pets remove <slug>
诊断配置kopi pets doctor

kopi 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)​

除了从图库安装现成的宠物外,Kopi Agent 还可以从文字描述生成一只全新的宠物——即它自己的 AI 精灵生成流水线。

  • CLI/TUI:/hatch <description>(别名 /generate-pet),或 kopi pets → 进入生成流程。
  • 桌面应用:宝可梦图鉴风格的生成界面——包含动画蛋、孵化特效和草稿选择器。

生成的工作方式(两步、成本可控的流程):

  1. 基础草稿——生成少量成本低廉、仅基于 prompt 的"这只宠物应该长什么样"变体。你选择其中一个,或者重新混搭/重试以获得新一轮结果。
  2. 孵化——将选定的基础图作为参考图像,为每种 Kopi Agent 状态(空闲、思考、工具使用等)生成一行有据可依的动画,然后以确定性方式切割成帧,并打包为标准的 petdex/Codex 图集(8×9 网格,每格 192×208)。最终得到的是一张你可以保留的有效精灵表——你甚至可以 petdex submit。

图像后端​

生成使用当前活跃的图像生成 provider,但需要参考图像约束,以确保每行动画都与基础图保持同一角色。支持参考图的后端:KOPI Proxy、OpenRouter、OpenAI(gpt-image-2)和 Krea。OpenRouter/Nous 默认运行质量优先的模型链。

  • 解析顺序优先选择 KOPI Proxy → OpenAI → OpenRouter。
  • 如果没有配置支持参考图的后端,生成时会显示一条可操作的错误提示,指向 kopi tools → Image Generation。(安装/领养图库中已有的宠物不需要图像后端。)
  • 使用 KOPI_PET_IMAGE_PROVIDER env var 覆盖后端(例如 KOPI_PET_IMAGE_PROVIDER=openrouter)。

桌面应用​

在桌面应用中,你可以通过两种方式管理宠物:

  • Cmd+K → "Pets…" —— 无需离开键盘即可浏览、搜索、领养和切换宠物(与主题选择器一致)。
  • Settings → Appearance —— 同样的图库,外加一个尺寸滑块,拖动时可实时调整浮动吉祥物的大小。

领养、切换和调整大小都会就地作用于浮动吉祥物——尺寸更改会立即生效;领养新宠物后片刻即可点亮。

弹出式浮层​

Shift-点击浮动宠物,可将其弹出为一个独立的透明、置顶桌面窗口。弹出后,即使 Kopi Agent 已最小化,它仍保持可见(类似 Codex 的做法),因此只需一眼就能知道 agent 正在做什么。

弹出后的手势操作:

手势操作
拖动将宠物移动到屏幕任意位置,甚至移到应用窗口之外。其位置和弹出/收回状态在重启后仍会保留。
单击打开迷你输入框,向最近的会话发送提示词——无需唤起应用窗口。
双击切换应用窗口:若窗口在前台则最小化,若已隐藏则恢复。
Shift-点击将宠物收回应用窗口中。
邮件图标仅当你离开期间有回合完成时才会出现;点击可将应用提升到前台并打开最近的会话(同时标记为已读)。

只有弹出的宠物才会显示气泡对话框(working…、thinking…、your turn……)——在窗口内时,应用本身就是展示界面,因此宠物在那里保持安静。

该浮层只是应用内宠物的纯粹傀儡——它不携带独立的 gateway 连接,也绝不会出现在 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 推导宽度。

故障排查​

运行 kopi pets doctor ——它会报告:

  • 宠物目录以及已安装了哪些宠物,
  • display.pet.enabled、display.pet.slug 以及解析出的当前活动宠物,
  • 已配置的 render_mode、检测到的终端图形协议,以及 TTY 的生效模式,
  • Pillow(用于精灵解码)是否可导入。

当宠物已安装、已选择、已启用且 Pillow 可用时,它会输出 ✓ ready。

常见问题:

  • 只有宠物已安装且已选择时才会显示(enabled: true)。
  • 在管道/重定向中(无 TTY),终端渲染会按设计被禁用。
  • petdex npm CLI 会安装到 ~/.codex/pets;而 Kopi Agent 使用自己的按 profile 隔离的 <KOPI_HOME>/pets/ ——请通过 kopi pets 安装。

另请参阅​

  • petdex skill 可让 agent 按需为你安装和切换宠物。