Codex pets 指南

Codex pet pack 的包结构、安装步骤、校验规则和 OpenPets 资源策略。

包结构

Codex pet pack 是一个只包含运行时文件的文件夹，OpenPets 导出的结构固定为：

<pet-id>/
├── pet.json
└── spritesheet.webp

下载 ZIP 只保留这个顶层文件夹。OpenPets 会拒绝包含 ../、绝对路径或额外预览素材的 ZIP。

Manifest 基线

pet.json 描述 pet 身份与 spritesheet 契约：

{
  "id": "terminal-raccoon",
  "displayName": "Terminal Raccoon",
  "description": "A calm Codex companion for long review sessions.",
  "spritesheetPath": "spritesheet.webp",
  "version": "1.0.0",
  "frame": { "width": 192, "height": 208, "columns": 8, "rows": 9 }
}

OpenPets 默认使用 1536×1872 atlas，拆成 8×9 个 192×208 frame。Validator 会检查 manifest 结构、必需动画、图片类型、frame 范围和 ZIP entry。

Create 工作流

/create 是收费生成工作台，不是公开发布捷径。

选择 Text to Pet 或 Image to Pet。
确认 prompt 为原创或已授权。
服务端检查登录、credits、provider 状态和任务成本。
任务写入 ShipAny ai_task，并关联 OpenPets generation 记录。
Provider 结果先持久化到 R2，再进入导出。
Quality FAIL 阻止导出；WARN 和 PASS 可导出本地 draft ZIP。
AI draft 未经人工确认不会进入公开 Gallery。

真实 KIE 调用默认锁定，必须同时具备 Worker secret、provider mode 和预算授权。

安装已审核 pack

在 /pets 打开一个 reviewed pack。
下载 .codex-pet.zip。
解压到本地 Codex pets 目录。
确认文件夹内仍然只有 pet.json 和 spritesheet.webp。
在 Codex 设置或本地 pet picker 中选择该 pet。

资源策略

OpenPets 明确区分资源状态：

状态	含义	OpenPets 行为
reviewed seed	本地 pack，manifest、spritesheet、license note 和 ZIP 已验证	进入 Gallery 并提供下载
draft	用户或 AI 输出，已满足本地导出条件	只在 owner 工作流可见
index-only	外部公开 pet 页面，但未确认再分发授权	只外链，不镜像 ZIP 或 spritesheet
blocked	授权不清、安全性差或 IP 风险高	不作为 pack 展示

外部示例可以帮助发现资源，但除非明确验证再分发授权，OpenPets 不托管第三方资产。

常见问题

ZIP 有额外文件：重新构建，只保留一个 pet 文件夹。
Spritesheet 类型不对：导出为 spritesheet.webp；PNG 只作为中间素材。
动画 frame 校验失败：确认每个 frame index 都在 8×9 atlas 内。
Provider locked：配置 secret 和预算授权后才能 live generation。
Quality 为 FAIL：先修复 manifest 或图片；FAIL 输出不能下载。