# petdex

> Petdex 是 Codex 桌面应用的动画宠物伴侣公共图鉴与命令行工具，提供浏览、安装、提交和桌面浮动宠物能力。

## 元数据

- 作者: [@crafter-station](https://github.com/crafter-station)
- 仓库: <https://github.com/crafter-station/petdex.git>
- GitHub: [crafter-station/petdex](https://github.com/crafter-station/petdex)
- Star: 3,875
- 主语言: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- 主页: <https://petdex.dev>
- Topics: `claude-code`, `clerk`, `cli`, `codex`, `developer-tools`, `drizzle-orm`, `dsh-plugin`, `mascot`, `neon`, `nextjs`, `pixel-art`, `postgres`, `react`, `sprites`, `tailwindcss`, `vercel`
- Fork: 183
- Open Issues: 26
- 最后推送: 2026-08-17T11:45:35.000Z
- 加入目录: 2026-08-16T00:00:00.000Z

## 安装

```bash
dsh plugin --profile web add github:crafter-station/petdex
```

## 百科

## 一句话定位
Petdex 是 Codex（ChatGPT 桌面应用）的动画宠物伴侣公共图鉴与命令行工具，把"在屏幕上跑一只小动物陪伴写代码"做成可浏览、可安装、可社区贡献的内容生态。除了 DSH 安装入口外，它本身是一个独立的 Next.js Web 应用，配有 npm CLI、桌面浮窗 App 和 Discord 社区机器人。

## 核心能力
- 浏览已审批宠物的公共画廊，按 vibe、kind（creature/object/character）、sp 版本筛选
- 通过 CLI 一行命令把宠物装到本地 `~/.petdex/pets/<slug>/` 与 `~/.codex/pets/<slug>/`
- 提交新宠物：上传文件夹或 zip，自动跑 dHash 去重、AI 审核、配色/标签/声音生成
- 公开 HTTP manifest（v1 + v2），让第三方桌面客户端、可穿戴设备、SDK 拉取宠物清单
- 桌面浮窗 SDK 在屏幕上画一只像素宠物，根据编码代理的活动 hook 切换 idle/running/failed 等 9 个动画状态
- Discord 社区机器人：斜命令、自动角色、宠物审批通过后自动发到 #showcase 频道

## 技术实现
- **语言**: TypeScript（Web 主站 + CLI + 桌面原生 SDK 桥）+ Zig（桌面 SDK 内部 in-process hook server，监听 127.0.0.1:7777）
- **关键依赖**: Next.js 16.3.0、React 19.2.8、Drizzle ORM + Postgres（Neon）、Clerk OAuth、R2（资产）/ 阿里云 OSS（备选）、Upstash Redis（限流/缓存）、Vercel AI SDK（自动审核/打标/生成 ffmpeg 合成的声音）、Resend（邮件）、discord.js v14、@napi-rs/keyring（CLI 可选 keychain）
- **架构模式**: 单仓多包：根是 Next.js 主站；`packages/petdex-cli` 是 Bun 打包成单文件的 Node CLI；`packages/discord-bot` 是 discord.js；`packages/petdex-desktop-native` 是 Zig + 跨平台浮窗；主站通过 `/api/manifest`、`/api/cli/*`、`/api/submit` 三套路由分别服务 Web、CLI、提交场景
- **入口文件**: 主站 `src/app/[locale]/page.tsx`（首页）/ `src/app/api/manifest/route.ts`（公开 manifest 入口）；CLI 入口 `packages/petdex-cli/bin/petdex.ts`；Discord 机器人 `packages/discord-bot/src/bot.ts`

## 适用场景
Codex 桌面应用或 Claude Code 等编码代理的活跃用户，希望工作时有只小宠物陪伴、不想折腾复杂配置的人——一条命令装好、桌面 App 自动把代理活动翻译成宠物动画。以及想把自己画的像素宠物分享给整个社区的创作者，提交后会经过 AI 审核 + 人工审核双轨流程。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | >=20 | 仅 `packages/petdex-cli` 子包在 package.json 中声明 `engines.node`；根 Next.js 主站无显式 engines 字段 |
| DSH | 未声明 | 仓库不是 DSH 风格的 `dsh.bundle.patch` 注入插件，而是 petdex.dev 完整生态源码；`dsh plugin add` 在这里只是便捷入口 |
| 平台 | 跨平台 | 主站任意带浏览器的平台；CLI 在 macOS/Linux/Windows 均可（也可在 Bun 上跑）；桌面 App 原生支持 macOS、Linux、Windows |
| 原生模块 | `@napi-rs/keyring`（可选） | CLI 用它把 OAuth token 存进系统 keychain；缺它时 CLI 仍能跑但会降级到文件存储 |
| 系统依赖 | `ffmpeg` | 默认路径 `/opt/homebrew/bin/ffmpeg`，可通过 `FFMPEG_BIN` 覆盖，主要给宠物声音生成脚本用 |
| 外部服务 | Clerk / Neon 或本地 Postgres / R2 或阿里云 OSS / Upstash / Resend / OpenAI | 本地全栈开发用 `bun run dev:docker`（带 Docker/Podman）启动 Postgres + Redis 与共享 mock 默认值 |

## 安装方式
```bash
dsh plugin --profile web add github:crafter-station/petdex
```

## 配置项
本插件无需额外配置。`dsh plugin add` 安装的是宠物内容（落到 `~/.petdex/pets/` 与 `~/.codex/pets/`），不是 petdex.dev 站点本身；站点部署需要的全部环境变量（`DATABASE_URL`、`R2_*`、`CLERK_*`、`UPSTASH_*`、`RESEND_API_KEY`、`OPENAI_API_KEY`、`AI_GATEWAY_API_KEY`、`PETDEX_ADMIN_USER_IDS`、`PETDEX_ALL_PETS_PACK_URL`、`PETDEX_MANIFEST_V1_URL`、`PETDEX_MANIFEST_V2_URL` 等）只对想把 petdex.dev 跑起来自己托管的人有意义，不是安装插件要关心的内容。

## 常见问题

**Q: petdex 到底是 DSH 插件还是独立项目？**

A: 这个仓库本身是 petdex.dev 整套生态的源码（Next.js 主站 + npm CLI + Discord 机器人 + 桌面原生 SDK），并不像普通 DSH 插件那样通过 `dsh.bundle.patch` 注入宿主。`dsh plugin add` 在这里更像一个便捷入口，把宠物安装到本地 `~/.petdex/pets/` 和 `~/.codex/pets/`。

**Q: 一个宠物是什么文件结构？**

A: 每个宠物是一个文件夹，根下放 `pet.json`（描述名称/动画状态/帧尺寸）+ `spritesheet.webp` 或 `.png`，要求 8×9 帧网格（1536×1872）或 v2 的 8×11 网格（1536×2288）。v1/v2 由 `spriteVersionNumber` 字段区分，老的 8×9 是兼容回退。

**Q: 怎么把宠物装到 Codex 桌面应用？**

A: 先在 petdex.dev 浏览/复制 slug，然后跑 `npx -y petdex install <slug>`；或者用 Petdex 桌面 App（petdex.dev/download 下载）的设置面板一键连接 Claude Code/Codex 等代理并切换当前激活宠物。

**Q: CLI 和桌面应用各自管什么？**

A: CLI（npm 名 `petdex`）只管目录浏览、安装、提交和编辑已发布的元数据；钩子注入、更新、代理连接和当前激活宠物的切换都由桌面 App 的设置面板负责。v1.0.0 起 CLI 砍掉了 `init`/`hooks`/`select`/`desktop` 等子命令，全部改由桌面 App 接管。

**Q: 提交宠物有限制吗？**

A: 每个用户每天 10 次提交上限；slug 撞名会自动加后缀（`boba` → `boba-2`）；提交需要先 `petdex login`（浏览器 OAuth PKCE），CI/无头环境必须提前在本地完成登录。无 owner email 时不会发邮件通知，提交身份来自 Clerk 会话或 CLI bearer token。

**Q: 公开 API 能让第三方做什么？**

A: `petdex.dev/api/manifest`（v1，R2 重定向）和 `/api/manifest/v2`（v2）返回所有已审批宠物的 slug、精灵图 URL 和元数据，缓存 300 秒；`/api/manifest/full` 提供完整数据集。任何桌面客户端、可穿戴设备、SDK 都基于这两个 manifest + pet 包格式构建。

**Q: 怎么卸载一只宠物？**

A: 直接删除 `~/.petdex/pets/<slug>/` 与 `~/.codex/pets/<slug/` 两个目录即可；CLI 没有专门的 `uninstall` 命令。已审批过的宠物不会从宠物图鉴网站下架。

## 上手难度
入门 — 一行 `npx -y petdex install <slug>` 就能让 Codex 出现宠物，没有任何配置文件或环境变量要填；想参与提交或搭建本地站点时才进入下一档。

## 已知问题与限制
- `bun run dev:mock` 已废弃，执行后会立刻退出，仅供 mock 单测复用 `.env.mock`，不能拿来启动站点
- Codex 桌面应用里 `codex://pets/install` 链接解析器对未知 query 参数零容忍，且消费该链接的 modal 仍被 Statsig gate 关闭，因此即便链接拼对了也不会被触发；改动前必须读 `docs/chatgpt-pet-integration.md`
- 根目录下大量 `scripts/apply-*` / `scripts/backfill-*` 是真实数据库的一次性维护脚本（手动跑），不是常规 `bun run` 命令
- `bun run dev`（maintainer）需要 Clerk、Neon 或本地 Postgres、R2、Upstash、Resend、OpenAI、ElevenLabs 全套凭据；普通贡献者请走 `bun run dev:docker`
- 宠物是用户提交的粉丝艺术，Petdex 本身不主张 IP；权利方可在 GitHub issue 用 takedown 模板申请下架

---

本文档由 [deepseek-plugin.org](https://deepseek-plugin.org) 自动生成，对应 HTML 页面: [petdex](https://deepseek-plugin.org/plugins/crafter-station/petdex)
百度百科由 AI 生成 (模型: `MiniMax-M3`)