宠物
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→ 进入生成流程。 - 桌面应用:宝可梦图鉴风格的生成界面——包含动画蛋、孵化特效和草稿选择器。
生成的工作方式(两步、成本可控的流程):
- 基础草稿——生成少量成本低廉、仅基于 prompt 的"这只宠物应该长什么样"变体。你选择其中一个,或者重新混搭/重试以获得新一轮结果。
- 孵化——将选定的基础图作为参考图像,为每种 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_PROVIDERenv 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安装。
另请参阅
petdexskill 可让 agent 按需为你安装和切换宠物。