chatgpt-pets 🐾

让会呼吸、会回应、会朝你看来的桌宠，住进 ChatGPT / Codex。

基于统一 v2 图集规范的开源动画桌宠合集。每只桌宠都是一个轻量、自包含、可直接安装的角色包。

快速安装 · 浏览桌宠 · 查看 v2 规范 · 贡献桌宠

首发桌宠 · 李慕婉（Li Muwan）
Q 版仙侠少女，一袭冰蓝汉服。

待机 idle

挥手 waving

跳跃 jumping

失败 failed

评审 review

Important

本仓库只接受 v2 桌宠：1536×2288、8×11 图集，并在 pet.json 中声明 "spriteVersionNumber": 2。v1 图集只能用于迁移，不能提交或安装。

从这里开始

你的目标	前往
立即安装桌宠	快速开始
浏览现有角色	可用桌宠
制作自己的桌宠	添加新桌宠
查询图集尺寸与状态映射	v2 图集规范
了解 AI 生成约定	AGENTS.md

快速开始

1. 安装

把 pets/ 下的桌宠复制到 Codex 桌宠目录。默认目录是 ~/.codex/pets/；Windows 使用 %USERPROFILE%\.codex\pets\。

macOS / Linux

# 安装仓库中的全部桌宠
./scripts/install.sh

# 或只安装李慕婉
mkdir -p ~/.codex/pets
cp -r pets/li-muwan ~/.codex/pets/

Windows（PowerShell）

# 安装仓库中的全部桌宠
./scripts/install.ps1

# 或只安装李慕婉
Copy-Item -Recurse pets/li-muwan $HOME/.codex/pets/

Note

如果设置了 CODEX_HOME，请安装到 $CODEX_HOME/pets/。

2. 启用

重启 ChatGPT / Codex，或刷新桌宠选择器，然后选择新安装的桌宠。idle 第一帧也会作为“减少动效”模式下的静态姿势。

可用桌宠

桌宠	风格	图集版本	状态
李慕婉	Q 版仙侠少女 · 冰蓝汉服	v2	✅ 可用 · PetDex
期待你的作品	—	—	🛠 提案中

完整图集和分状态动画预览位于 gallery/。用于重新生成的源美术位于 references/。

桌宠如何工作

桌宠渲染在透明 WebView 浮层上。ChatGPT / Codex 使用九种状态动画表现待机、执行、等待、失败和评审等行为，并用 16 个方向帧让角色看向交互目标。

每个可分发桌宠包只有两个文件：

• spritesheet.webp：透明的 v2 1536×2288 图集。
• pet.json：桌宠名称、描述、图集路径与版本声明。

应用只读取 pets/<pet-id>/。桌宠不能依赖 gallery/、references/、docs/ 或 scripts/ 中的文件。

v2 图集规范

项目	固定值
格式	带 alpha 通道的 WebP；也接受 PNG
画布	1536 × 2288 像素
网格	8 列 × 11 行
单格	192 × 208 像素
标准动画	前 9 行，共 57 帧
注视方向	后 2 行，共 16 帧
清单版本	"spriteVersionNumber": 2

前九行对应标准状态：

行	状态	帧数	用途
0	idle	6	平静呼吸与眨眼；第一帧也是静态姿势
1	running-right	8	向右移动
2	running-left	8	向左移动
3	waving	4	打招呼或引起注意
4	jumping	5	纵向小跳
5	failed	8	阻塞、失败或取消时的反应
6	waiting	6	等待用户输入或确认
7	running	6	原地执行任务，不是字面跑步
8	review	6	专注评审已完成产出

最后两行存放注视方向：

行	列 0–7 的角度
9	000°、022.5°、045°、067.5°、090°、112.5°、135°、157.5°
10	180°、202.5°、225°、247.5°、270°、292.5°、315°、337.5°

角度按顺时针计算，000° 表示向上看。完整的帧时长、身份规则与校验要求见 桌宠图集规范。

仓库结构

chatgpt-pets/
├── pets/                  可分发的桌宠包；应用只读取这里
│   └── li-muwan/
│       ├── pet.json
│       └── spritesheet.webp
├── gallery/               总览图与动画预览
├── references/            源美术与角色参考
├── docs/                  图集规范与贡献指南
├── scripts/               安装辅助脚本
├── AGENTS.md              AI 智能体工作约定
└── README.md

添加新桌宠

推荐使用 hatch-pet v2 工作流：

1. 把干净参考图放入 references/<pet-id>/。
2. 生成基础姿势、九行动画和 16 个注视方向。
3. 去除色键并检查黑、白、中性背景下的轮廓。
4. 合成并校验 v2 8×11 图集。
5. 写入 pets/<pet-id>/，生成总览图和九个预览 GIF。

完整流程与文件清单见 添加新桌宠。AI 智能体开始工作前还必须阅读 AGENTS.md。

重新生成桌宠

每个桌宠的源美术和标准参考保存在 references/<pet-id>/。除图像生成外，提取、合成和校验流程应保持确定性。

如果只有一行动画不合格，只重新生成并替换该行。不要重做整个桌宠。大型中间产物不会提交到 Git，详见 .gitignore。

贡献桌宠

提交 PR 前，请确认：

• 图集是 v2 1536×2288、8×11，并通过校验。
• 57 个状态动画帧和 16 个注视方向帧齐全。
• 透明像素没有 RGB 残影，轮廓没有色键溢色。
• pet.json 包含数字 "spriteVersionNumber": 2。
• pets/<pet-id>/ 只有 pet.json 和 spritesheet.webp。
• gallery/<pet-id>/contact-sheet.png 与九个预览 GIF 齐全。
• 你拥有源美术的使用权，并按需要注明原作者。

完整约定见 添加新桌宠 和 AI 智能体工作指南。

许可证

MIT © chatgpt-pets 贡献者。

个别桌宠可能基于拥有独立版权的角色。references/ 中的源美术只为透明度与可复现性保留；版权方如需调整或移除，请提交 issue 联系维护者。