Codex 桌宠包、CLI 与 API 文档

文档范围： 本指南覆盖已发布的 codexpetdb CLI、V1 与 V2 桌宠包格式，以及 CodexPetDB 公开 API。以下命令和限制已于 2026-07-25 对照生产环境 Discovery、 CLI 实现和 API 契约核验。

当你需要安装已通过审核的桌宠、准备自己的桌宠进入审核，或读取公开 Catalog 数据时，可以从本页开始。浏览和安装不要求登录；只有提交或编辑桌宠时需要登录。

安装已验证的 Codex 桌宠

第一次安装桌宠时，可以先阅读下载与安装教程，再回到这里查看完整 CLI、包格式与 API 参考。

CLI 要求 Node.js 20 或更高版本。偶尔使用时可以直接通过 npx 运行，经常使用时可以全局安装。

node --version
npx codexpetdb list
npx codexpetdb install a-tom

petdb list 会输出当前公开桌宠的 slug。安装时必须使用其中一个完整 slug；上例使用的是本文核验时已经公开的桌宠。

安装成功后，桌宠位于 $CODEX_HOME/pets/<pet-slug>。使用默认 CODEX_HOME 时，上例目录为 ~/.codex/pets/a-tom/，其中包含 pet.json 和一个 spritesheet。

安装不需要账号。CLI 会读取服务 Discovery 和公开 Pet Catalog，从受信任的资源 origin 下载已批准的 ZIP，并在替换目标目录前校验 Content-Type、字节长度、 SHA-256、ZIP 结构和 manifest ID。如果想先预览再安装，可以浏览桌宠图鉴。

需要长期使用时，可以全局安装：

npm install --global codexpetdb
petdb version
petdb install a-tom

petdb 与 codexpetdb 两个 binary 名称完全等价。

创建有效的桌宠包

可下载包命名为 <pet-slug>.zip，根目录固定只包含两个文件：

<pet-slug>.zip
├── pet.json
└── spritesheet.webp

spritesheet 也可以是 spritesheet.png，文件名必须与 pet.json.spritesheetPath 完全一致。poster.webp 是站内展示用派生文件，不属于下载包。

最小 manifest 应包含桌宠身份、用户可见信息和 spritesheet 路径：

{
  "id": "my-pet",
  "displayName": "My Pet",
  "description": "A calm companion for focused work.",
  "spritesheetPath": "spritesheet.webp",
  "formatVersion": 2
}

项目	V1	V2
Spritesheet 尺寸	`1536 × 1872`	`1536 × 2288`
标准行数	`9`	`11`
支持的图片类型	PNG 或 WebP	PNG 或 WebP
透明通道	必须	必须

如果 manifest 中包含 formatVersion、rows、states 或 neutralDirections，这些字段必须与检测到的图片格式一致。可以先按照 Hatch Pet 指南创建 spritesheet 和 manifest，再回到本页完成校验与提交。

提交前完成校验

CLI 会在上传前进行本地校验；服务器仍会独立校验上传对象，确认无误后才接受新的 revision。

检查项	要求
`pet.json`	UTF-8 JSON object；canonicalize 后不超过 64 KiB
`id`	合法且未保留的 pet slug
`displayName`	非空；最多 100 个字符
`description`	非空；最多 1,000 个字符
`spritesheetPath`	必须是 `spritesheet.png` 或 `spritesheet.webp`
Spritesheet	非空；不超过 10 MiB
图片内容	扩展名匹配 PNG/WebP 文件签名，并包含 alpha 透明通道
路径	不得包含绝对路径、盘符路径或 `..` 路径穿越

提交目录时，应让 pet.json 与 spritesheet 位于同一目录。提交 ZIP 时，两个文件必须位于压缩包根目录。

npx codexpetdb login
npx codexpetdb submit ./my-pet

CLI 也接受单个 ZIP，或直接子目录分别为独立桌宠包的父目录。非交互环境必须传入 --yes。提交成功后，CLI 会输出新的 pending revision ID 和成功/失败汇总。

理解审核与修订状态

提交桌宠不会立刻公开：

CLI 创建 upload session，并上传通过校验的 manifest、spritesheet 和生成的 poster。
Finalize upload 会创建不可变的 pending revision。
自动或人工审核期间，pending 文件保持私有。
审核通过后，该 revision 才成为公开 active revision。Pending edit 不会改变当前已发布的 revision。

编辑自己拥有的桌宠时，应创建新 revision，不会覆盖 active 文件：

npx codexpetdb edit my-pet --description "A quieter companion."
npx codexpetdb edit my-pet --zip ./my-pet.zip

如果更习惯浏览器流程，可以使用桌宠提交页。页面会先执行客户端校验以便快速反馈，但服务器始终是最终校验边界。

读取公开 Catalog 与 API

不要硬编码服务 origin，应先读取 Discovery：

curl -fsS 'https://codexpetdb.com/.well-known/codexpetdb.json'

它会声明当前公开 API base URL、资源 origin、Catalog、文档地址和受支持 CLI。静态 Catalog 是读取当前已批准桌宠与集合最直接的机器入口：

curl -fsS 'https://cdn.codexpetdb.com/catalogs/v1/pets.json'
curl -fsS 'https://cdn.codexpetdb.com/catalogs/v1/collections.json'

需要筛选、排序、分页或详情响应时，使用 JSON API：

curl -fsS \
  'https://codexpetdb.com/api/v1/pub/pets?kind=creature&sort=hot&limit=10'

Query	可接受值	默认值
`kind`	`creature`、`object`、`character`、`all`	`all`
`sort`	`hot`、`newest`	`hot`
`limit`	`1` 到 `50`	`30`
`cursor`	上一页返回的不透明 cursor	无

列表响应包含 items、请求元数据和 pageInfo。当 pageInfo.hasNextPage 为 true 时，应把 pageInfo.nextCursor 原样作为下一次请求的 cursor。无效请求、限流与服务异常使用 application/problem+json，结构遵循 RFC 9457 Problem Details。

排查常见失败

现象	可能的边界	处理方式
Node 版本错误	Runtime 低于 Node 20	运行 `node --version` 并升级 Node
找不到 pet slug	当前公开 Catalog 中没有该 slug	运行 `petdb list` 并复制完整 slug
完整性或校验失败（退出码 `4`）	包字节、结构、manifest 或图片没有通过检查	阅读错误字段，并与上方校验表逐项对照
文件系统失败（退出码 `5`）	目标不存在、只读或无法替换	检查 `CODEX_HOME` 与目录权限，然后重试
认证失败（退出码 `6`）	Submit/edit session 缺失或过期	先运行 `petdb logout`，再运行 `petdb login`
HTTP 或服务失败	网络、限流或服务器响应异常	加 `--debug` 重试，查看状态码和脱敏后的响应内容

--debug 不会输出 Bearer token，响应内容最多保留 16 KiB。HTTP 请求成功，或失败时没有收到 HTTP 响应，都不会产生 debug record。

事实来源、维护与责任边界

本页依据 Web 产品契约和公开 CLI 使用的同一组事实维护。需要当前机器可读信息时，请优先使用：

CLI 公开维护，便于社区审阅。CodexPetDB Web 应用与数据库保持私有，因此本文不会把整个产品描述为开源。CLI 问题请提交到 CLI Issue Tracker；站点或账号问题请联系 support@codexpetdb.com。