petdex

3.9kStar183Fork26Issue10Watching

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

crafter-stationcrafter-station
·crafter-station/petdex.git·petdex.dev
语言
TypeScript
License
MIT
分支
main
claude-codeclerkclicodexdeveloper-toolsdrizzle-ormdsh-pluginmascot

安装

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

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

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 默认值

安装方式

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 模板申请下架
返回插件目录