Petdex：把编程助手的每一次工具调用，变成桌面上的一只动画宠物

编程代理的陪伴感，从一次 npx 命令开始

开发者在终端里跑 Codex 或 Claude Code 时，看到的只有滚动日志和状态提示。Petdex 想改变这一点：它把编程代理的活动变成桌面上一个浮动的动画宠物。宠物会在每次工具调用时切换状态，比如 idle、running、failed、waiting。这个项目由三部分组成：一个 Web 画廊、一个 npm CLI、一个桌面应用。CLI 负责安装宠物，桌面应用负责显示和响应代理活动。它解决的不是效率问题，而是注意力和情绪反馈问题，让长时间等待代理执行时有一个可视的、带情绪的信号。适合那些愿意为开发环境增加一点个性的人。

宠物格式：一个文件夹，一张精灵表，九种状态

每个宠物都是一个文件夹，里面只有两个文件：pet.json 和 spritesheet.webp（或 .png）。pet.json 记录名称、slug、标签、vibes、kind、帧大小和动画状态。精灵表是一个 8x9 的网格，每个帧是 192x208 像素，对应九种状态行：idle、running-right、running-left、waving、jumping、failed、waiting、running、review。v2 格式是 8x11 网格，多出两行供客户端自定义。这个格式的关键在于状态映射：Codex 和受支持的编程代理会把它们的活动钩子映射到这些状态。也就是说，宠物不是随机播放动画，而是严格对应代理的实时状态。这种标准化让社区贡献的宠物可以即插即用，不需要为每个代理单独适配。

安装与使用：一条命令装宠物，桌面应用做连接

安装一个已收录的宠物只需要一行命令：npx petdex install boba。执行后会在 ~/.petdex/pets/boba/ 下生成 pet.json 和精灵表。桌面应用需要从 petdex.dev/download 下载，支持 macOS、Linux 和 Windows。打开后按 Cmd+, 打开设置，在 Pets 里选择宠物，在 Agents 里一键连接你的编程代理，不需要碰终端。CLI 还支持提交宠物：npx petdex submit ./my-pet/，或者通过网页提交。整个流程把浏览、安装、切换、提交都压缩成一条命令或一次点击。对于本地全栈开发，仓库提供了 bun run dev:docker，用 Docker 或 Podman 大约 30 秒启动。

桌面应用的架构取舍：Zig 钩子服务器，没有 WebView

桌面应用是原生 SDK 应用，内部跑了一个 Zig 编写的钩子服务器，监听 127.0.0.1:7777。README 明确说当前发布路径没有 WebView 或 Node sidecar。这个设计意味着桌面应用本身很轻，不需要加载一个浏览器引擎，也不会为了渲染一个宠物而启动 Node 进程。但这也带来一个限制：应用必须依赖本地回环端口，如果你的系统有严格的防火墙规则或安全代理，这个端口可能被拦截。另一个隐含问题是，Zig 钩子服务器只负责接收代理活动事件，桌面应用的渲染和状态切换逻辑都在原生层，这意味着扩展桌面端功能需要改 Zig 代码，而不是用 JavaScript。对于想定制桌面端行为的开发者，这个门槛比纯 Electron 应用高。

CLI 与 API：面向构建者的两个稳定接口

除了终端用户，Petdex 也为构建者提供了两个稳定表面。第一个是 HTTP API：petdex.dev/api/manifest 返回所有已批准宠物的 slug、精灵表 URL、动画状态和元数据。第二个是宠物包格式本身。README 声称已有 21 个开源或源码可得项目基于这两个接口构建，并维护了一个 built-with 目录。这意味着你可以用这个 API 做自己的桌面客户端、可穿戴设备、SDK 或 Discord 机器人。CLI 本身是 Bun + TypeScript 写的，通过 Clerk OAuth 和 PKCE 做认证。提交宠物时，CLI 会把 zip 上传到 R2 预签名 URL，然后走管理审查。这个流程把社区提交和分发都集中到一条命令里，降低了参与门槛。

审查与版权：48 小时下架承诺，但资产许可由提交者决定

宠物是用户提交的粉丝艺术，Petdex 不声称拥有任何底层 IP。如果版权方要求下架，可以通过 GitHub issue 模板提交 takedown 请求，项目承诺 48 小时内审查。但注意，仓库代码是 MIT，宠物资产由提交者自己声明许可。这意味着你安装一个宠物时，不能默认它可以用在商业项目里。对于公司团队，如果想把宠物嵌入内部工具，必须逐个核对每个宠物的许可声明。这个机制是合理的，因为宠物是社区驱动的，但也是采用前需要明确的边界。另一个限制是，提交的宠物需要经过管理审查，所以不是所有提交都能立刻出现在画廊里。

替代方案：自己写状态轮询，还是用现成的终端主题

Petdex 并不是唯一给编程代理增加视觉反馈的方式。你可以不依赖任何框架，直接在代理的输出流里写一个脚本，监听工具调用事件，然后调用任何动画库来显示状态。这种方式的优势是完全可控，不依赖 Petdex 的宠物格式和桌面应用，也不需要打开一个本地端口。缺点是你得自己处理状态映射、精灵表渲染和跨平台问题。另一个替代方案是使用终端主题或自定义提示符，比如在 shell 里用颜色或图标表示代理状态，但这种方式只能停留在终端内，无法做到桌面悬浮。Petdex 的差异点在于它把宠物格式、分发渠道和代理状态映射都标准化了，省去了重复造轮子的工作。

编辑结论

Petdex 适合两类人：一类是每天长时间盯着终端或桌面，希望给编程代理增加一点视觉反馈的开发者；另一类是想基于宠物格式或 HTTP API 做二次开发的构建者。不适合那些把终端界面视为纯工具、不愿意引入额外桌面进程的人，也不适合对宠物 IP 有严格版权管理需求的企业。在采用之前，先确认你的编程代理是否在官方支持的列表里，因为动画状态映射依赖代理的活动钩子，不在列表内的代理可能只会显示静止帧。另外，桌面应用当前通过 Zig 钩子服务器监听 127.0.0.1:7777，如果你的安全策略禁止本地回环端口监听，需要先评估这一设计。最后，宠物资产由提交者自行声明许可，商用前必须逐个核对每个宠物的授权，仓库本身只保证代码是 MIT。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes