动画宠物画廊crafter-station/petdex

Petdex

Codex 动画伙伴的公共画廊。

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

petdex.dev
 · 
使用 Petdex 构建
 · 
Discord
 · 
npm

什么是 Petdex

Petdex 由三个协同工作的部分组成：

1. petdex.dev 上的网页画廊，社区在这里以 Codex 精灵图格式提交、审核和展示动画宠物。
2. 一个 CLI，用一条命令即可将任意宠物安装到你的机器上，并直接送入 Codex。
3. 一个桌面应用，在你的屏幕上浮动显示一只宠物，并实时响应你的编码智能体的活动。

每只宠物都是一个文件夹。每个文件夹都是一条宝可梦图鉴条目。每条条目都只差一条 npx petdex install 命令。

快速开始

按照这份清单操作，即可安装一只宠物、在 Codex 中看到它，并将其连接到桌面应用。

1. 安装一只已知的宠物：

npx petdex install boba

你应该会看到 ~/.petdex/pets/boba/，其中包含 pet.json 和一张精灵图集。

2. 从 petdex.dev/download 获取桌面应用。它
可在 macOS、Linux 和 Windows 上运行。

3. 打开它，然后在宠物上按下 Cmd+, 打开设置。
在 Pets 下选择你的宠物，并在 Agents 下连接你的编码智能体，
每个只需点击一次。无需终端。

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

面向用户

| 你想要…… | 这样做 |
| --- | --- |
| 浏览宠物 | 访问 petdex.dev |
| 安装宠物 | npx petdex install  |
| 切换当前吉祥物 | 在桌面应用中打开设置（Cmd+,） |
| 运行桌面悬浮宠物 | 从 petdex.dev/download 下载 |
| 制作宠物 | 在 Codex 中使用 hatch-pet 技能，或使用 Petdex 创作工具 构建一只 |
| 提交宠物 | npx petdex submit ./my-pet/ 或通过网页提交器提交 |
| 加入社区 | Discord |

完整 CLI 参考：packages/petdex-cli/README.md。

面向构建者

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

- HTTP API。 petdex.dev/api/manifest 返回每个已批准的宠物及其 slug、精灵图 URL、动画状态和元数据。
- 宠物包格式。 每个宠物都是一个 pet.json 加上一个 spritesheet.{webp,png}，渲染为 192x208 帧的 8x9 网格，或 v2 的 8x11 网格。

已有 21 个开源和源码可获取的项目基于这些接口构建。请查看 petdex.dev/built-with 上的目录，然后通过 issue 模板提交你的项目。

架构

crafter-station/petdex
├── src/
│   ├── app/[locale]/          公开站点：图库、/pets/、/collections、/built-with、/community、/create、/download、/submit、/u/、...
│   ├── app/api/cli/           CLI 端点：OAuth 配置、提交（zip → 预签名 R2）、去重检查、注册
│   ├── app/api/manifest/      公开清单：每个已批准的宠物及其精灵图 URL
│   ├── app/api/admin/         提交、编辑、合集请求的管理审核界面
│   └── lib/db/schema.ts       Drizzle schema（Postgres）
├── packages/
│   ├── petdex-cli/            npm petdex 目录客户端（认证、列表、安装、提交）
│   ├── petdex-desktop-native/ 适用于 macOS、Linux 和 Windows 的原生 SDK 浮动吉祥物
│   ├── petdex-desktop-windows/ 旧版 Tauri Windows 实现（非发布路径）
│   └── discord-bot/           用于 Petdex 服务器的 Discord.js 机器人
├── public/built-with/         社区页面的截图
├── public/brand/              徽标、操作系统图标、Discord 图标
└── drizzle/                   SQL 迁移（Postgres schema 历史）

Web 技术栈：Next.js 16、React 19、Tailwind、Drizzle、Postgres、Redis、Clerk、R2。
CLI：Bun + TypeScript，作为单个 npm 二进制文件发布。通过 Clerk OAuth + PKCE 进行认证。
桌面端：原生 SDK 应用，在 127.0.0.1:7777 上运行进程内 Zig 钩子服务器。当前发布路径没有 WebView 或 Node sidecar。

本地开发

支持两种方式。

| 目标 | 命令 | 设置 |
| --- | --- | --- |
| 本地全栈 | bun run dev:docker | Docker 或 Podman，约 30 秒预热。 |
| 针对真实服务运行 | 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                元数据：名称、slug、标签、氛围、类型、帧尺寸、动画状态
└── spritesheet.webp        8x9 或 v2 8x11 帧网格，每帧 192x208 像素（或 .png）

原生渲染器支持九种状态行：idle、running-right、running-left、waving、jumping、failed、waiting、running 和 review。Codex 及受支持的编码代理会将其活动钩子映射到这些状态。v2 8x11 图集为消费客户端额外保留了两行。

贡献

- 提交宠物： petdex.dev/submit 或 npx petdex submit 。
- 列出你的项目： 打开一个 Built with Petdex issue。
- 修复 bug 或添加功能： 阅读 CONTRIBUTING.md，然后打开一个 PR。
- 来逛逛： Discord 有用于发布（#wip、#ship-or-sink）、反馈（#cli-feedback）和展示（#showcase）的频道。

宠物知识产权与下架

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

许可证

源代码采用 MIT 许可证。宠物资产归其提交者所有，遵循其选择声明的任何许可证。

由 Crafter Station 制作。
负责人：@RaillyHugo。