动画宠物画廊 crafter-station/petdex

Petdex

Codex 动画伙伴的公开画廊。

一条命令就能浏览、安装和提交宠物。

petdex.dev
· Built with Petdex · Discord · npm

Petdex 是什么

Petdex 由三部分协同组成：

1. 网页画廊，位于 petdex.dev，社区在这里提交、评审并展示 Codex sprite 格式的动画宠物。
2. 命令行工具，一条命令就能把任意宠物装到你的机器上，并直接送进 Codex。
3. 桌面应用，让宠物漂浮在屏幕上，实时响应你编码智能体的活动。

每只宠物就是一个文件夹。每个文件夹就是一条宝可梦图鉴条目。每条条目距离 npx petdex install 只差一步。

快速开始

按这份清单操作，就能装好宠物、在 Codex 里看到它，并连上桌面应用。

1. 安装一只现成的宠物：

npx petdex install boba

你应该会看到 ~/.petdex/pets/boba/，里面有 pet.json 和一张 spritesheet。

2. 从 petdex.dev/download 获取桌面应用。它支持 macOS、Linux 和 Windows。

3. 打开它，然后在宠物上按 Cmd+, 打开 Settings。
在 Pets 下选择你的宠物，在 Agents 下逐个点击连接你的编码智能体。全程不用碰终端。

宠物会漂浮在工作区上方，你的智能体每调用一次工具，它就播放一次动画。

已登录的创作者还能把审核通过的宠物归入个人合集，入口在个人主页的 Collections 标签页，或者用命令行：

npx petdex collection create --title "My pets" --pets boba,mochi

面向用户

| 你想…… | 这样做 |
| 浏览宠物 | 访问 petdex.dev |
| 安装宠物 | npx petdex install <slug> |
| 切换当前吉祥物 | 打开桌面应用里的 Settings（Cmd+,） |
| 运行桌面悬浮宠物 | 从 petdex.dev/download 下载 |
| 制作宠物 | 在 Codex 里使用 hatch-pet 技能，或用 Petdex 创作工具 自己做一个 |
| 提交宠物 | npx petdex submit ./my-pet/，或通过网页提交器上传 |
| 管理合集 | npx petdex collection list，或使用个人资料页的 Collections 标签页 |
| 加入社区 | Discord |

完整命令行参考：packages/petdex-cli/README.md。

个人合集每个账号上限 10 个。24 只宠物的上限限制的是增长，而不是已存储的行，所以在上限出现之前创建的合集仍然可以改名或缩减，但不能扩充。命令行支持列出、创建、编辑、删除，以及输出 JSON 供自动化使用。

面向构建者

如果你想在 Petdex 之上做东西（桌面客户端、可穿戴设备、SDK、Discord 机器人，什么都行），有两个稳定的接口面：

- HTTP API。 petdex.dev/api/manifest 返回所有已审核通过的宠物，包含 slug、精灵图 URL、动画状态和元数据。
- 宠物包格式。 每只宠物都是一个 pet.json 加一个 spritesheet.{webp,png}，按 8x9 网格渲染，每帧 192x208，或使用 v2 的 8x11 网格。

已有 21 个开源和源码可得的项目构建在这两个接口面之上。目录见 petdex.dev/built-with，然后通过 issue 模板提交你的项目。

架构

crafter-station/petdex
├── src/
│ ├── app/[locale]/ Public site: gallery, /pets/<slug>, /collections, /built-with, /community, /create, /download, /submit, /u/<handle>, ...
│ ├── app/api/cli/ CLI endpoints: OAuth config, submit (zip → presigned R2), collection management, dedup check, register
│ ├── app/api/manifest/ Public manifest: every approved pet with its spritesheet URL
│ ├── app/api/admin/ Admin review surface for submissions, edits, collection requests
│ └── lib/db/schema.ts Drizzle schema (Postgres)
├── packages/
│ ├── petdex-cli/ npm petdex catalog client (auth, list, install, submit, edit, collection management)
│ ├── petdex-desktop-native/ Native SDK floating mascot for macOS, Linux and Windows
│ ├── petdex-desktop-windows/ Legacy Tauri Windows implementation (not the release path)
│ └── discord-bot/ Discord.js bot for the Petdex server
├── public/built-with/ Screenshots for the community page
├── public/brand/ Logos, OS icons, Discord icon
└── drizzle/ SQL migrations (Postgres schema history)

Web 技术栈：Next.js 16、React 19、Tailwind、Drizzle、Postgres、Redis、Clerk、R2。
命令行：Bun + TypeScript，以单个 npm 二进制文件发布。通过 Clerk OAuth + PKCE 认证。
桌面端：原生 SDK 应用，内置进程内 Zig 钩子服务器，监听 127.0.0.1:7777。当前发布路径不含 WebView，也不含 Node sidecar。

本地开发

支持两条路径。

| 目标 | 命令 | 准备 |
| 本地全栈 | bun run dev:docker | 需要 Docker 或 Podman，预热约 30s。 |
| 对接真实服务 | bun run dev | 填好 .env.local（仅维护者）。 |

git clone https://github.com/crafter-station/petdex.git
cd petdex
bun install
bun run dev:docker

打开 localhost:3000。完整指南见 CONTRIBUTING.md。

宠物包格式

每只宠物由两个文件组成：

my-pet/
├── pet.json Metadata: name, slug, tags, vibes, kind, frame size, animation states
└── spritesheet.webp 8x9 or v2 8x11 frame grid of 192x208 px each (or .png)

原生渲染器支持九行状态：idle、running-right、running-left、waving、jumping、failed、waiting、running、review。Codex 和受支持的编码智能体会把各自的活动钩子映射到这些状态。v2 8x11 图集还留出两行，供接入的客户端自行使用。

参与贡献

- 提交宠物： petdex.dev/submit 或 npx petdex submit <path>。
- 收录你的项目： 提一个 Built with Petdex issue。
- 修 bug 或加功能： 先读 CONTRIBUTING.md，再提 PR。
- 来聊聊： Discord 有发布频道（#wip、#ship-or-sink）、反馈频道（#cli-feedback）和展示频道（#showcase）。

宠物 IP 与下架

宠物是用户提交的同人作品。Petdex 不对任何底层 IP 主张权利。如果你持有某个角色的权利，希望下架某只宠物，请提交下架请求，我们会在 48 小时内审核。

协议

源代码采用 MIT。宠物素材归提交者所有，遵循其自行声明的协议。

Made by Crafter Station.
Lead: @RaillyHugo.