## 什么是 Petdex Petdex 是三者协同运作的结合体： 1. **一个网络图库**，位于 [petdex.dev](https://petdex.dev)，社区在此提交、审查并展示采用 Codex 精灵图（sprite）格式的动画宠物。 2. **一个 CLI**，只需一条命令即可在你的机器上安装任何宠物，并将它们直接发送到 Codex。 3. **一个桌面应用**，可以在你的屏幕上悬浮显示宠物，并实时响应编码 agent 的活动。 每只宠物都是一个文件夹。每个文件夹都是一个图鉴条目。每个条目只需一个 `npx petdex install` 即可获取。 ## 快速开始 按照此清单操作，即可安装宠物、在 Codex 中显示并连接到桌面应用。 1. 安装一个已知的宠物： ``` npx petdex install boba ``` 你应该会看到包含 `pet.json` 和 spritesheet 的 `~/.codex/pets/boba/` 目录。 2. 初始化 Petdex Desktop 和 agent hooks： ``` npx petdex init ``` 这将下载桌面应用，启动它，并为受支持的 agent 配置 `/petdex`。 3. 打开 Codex，前往 **Settings → Appearance → Pets**，选择 **Boba**，然后点击 **Select**。在 Codex 内部使用 `/pet` 来唤醒宠物或将其隐藏。 4. 验证安装设置： ``` npx petdex doctor ``` 如果已安装 hooks，你也可以在受支持的 agent 内输入 `/petdex status`。 ## 对于普通用户 | 你想要... | 请执行此操作 | | --- | --- | | 浏览宠物 | 访问 [petdex.dev](https://petdex.dev) | | 安装宠物 | `npx petdex install ` | | 切换当前吉祥物 | `npx petdex select`（交互式选择器）或 `npx petdex select ` | | 运行桌面悬浮窗 | `npx petdex init`（下载 `.dmg` 并配置 Codex/Claude Code hooks） | | 制作宠物 | 在 Codex 内使用 `hatch-pet` 技能，或者使用 [Petdex 创建者工具](https://petdex.dev/create) 构建 | | 提交宠物 | `npx petdex submit ./my-pet/` 或通过网络提交器上传 | | 加入社区 | [Discord](https://discord.gg/byhubdyBTe) | 完整的 CLI 参考：[`packages/petdex-cli/README.md`](./packages/petdex-cli/README.md)。 ## 对于构建者 如果你想基于 Petdex 进行构建（例如桌面客户端、可穿戴设备、SDK、Discord 机器人等），你有两个稳定的切入点： - **HTTP API。** `petdex.dev/api/manifest` 会返回所有已批准宠物的 slug、spritesheet URL、动画状态和元数据。 - **宠物包格式。** 每个宠物都包含一个 `pet.json` 以及一个按 8×9 网格排列的 192×208 帧 `spritesheet.{webp,png}` 图片。 已经有 21 个开源和源代码可用的项目基于此进行构建。请查看 [petdex.dev/built-with](https://petdex.dev/built-with) 浏览目录，然后[通过 issue 模板提交你的项目](https://github.com/crafter-station/petdex/issues/new?template=built-with.yml)。 ## 架构 ``` crafter-station/petdex ├── src/ │ ├── app/[locale]/ Public site: gallery, /pets/, /collections, /built-with, /community, /create, /download, /submit, /u/, ... │ ├── app/api/cli/ CLI endpoints: OAuth config, submit (zip → presigned R2), 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` (auth, list, install, select, submit, hooks, init) │ ├── petdex-desktop/ Zig + WebKit floating mascot for macOS │ └── 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。
**CLI**：Bun + TypeScript，作为单个 npm 二进制文件发布。通过 Clerk OAuth + PKCE 进行授权。
**Desktop**：基于 [`vercel-labs/zero-native`](https://github.com/vercel-labs/zero-native) 分支的 Zig 构建，Node 中运行的 HTTP sidecar 用于处理 agent hooks。 ## 本地开发 支持两种方式。 | 目标 | 命令 | 环境配置 | | --- | --- | --- | | 本地全栈 | `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](http://localhost:3000)。完整指南请见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。 ## 宠物包格式 每只宠物都包含两个文件： ``` my-pet/ ├── pet.json Metadata: name, slug, tags, vibes, kind, frame size, animation states └── spritesheet.webp 9 rows × 8 cols = 72 frames of 192×208 px each (or .png) ``` 动画状态对应行：`idle`、`wave`、`run`、`failed`、`review`、`jump`、`extra1`、`extra2`。Codex 会将这些映射到其 agent 活动 hooks。循环时间默认为每个状态 6 帧，耗时 1100ms。 ## 宠物知识产权（IP）与下架处理 宠物均为用户提交的同人作品。Petdex 不主张任何底层 IP 的权利。如果你拥有某个角色的权利并希望移除该宠物，请提交[下架申请](https://github.com/crafter-station/petdex/issues/new?template=takedown.yml)，我们将在 48 小时内进行审核。 ## 许可证 源代码遵循 [MIT](./LICENSE) 协议。宠物资产归其提交者所有，并遵循他们选择声明的任何许可证。

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

标签：AI编程助手, MITM代理, SOC Prime, Web图库, 开发工具, 开发者体验, 搜索引擎查询, 桌面宠物, 自动化攻击, 请求拦截