codex-pet-generator-skill

简体中文 | English

codex-pet-generator 是一个专门用来生成 Codex 桌面宠物的 skill。

上传一张参考图，Codex 就可以根据这个 skill 生成符合 Codex pet 规范的动画 spritesheet 和 pet.json。

示例展示

下面是从单张参考图生成 Codex pet spritesheet 的示例。

图 1：生成结果

图 2：参考图

这个 Skill 做什么

codex-pet-generator 会指导 Codex 完成以下工作：

• 根据用户提供的角色、宠物、头像或 mascot 参考图生成绿色背景源 sprite sheet。
• 使用 scripts/build_spritesheet.py 去除绿色背景、裁切每帧、居中角色并导出标准尺寸。
• 生成 Codex pet 所需的 spritesheet.webp 和 pet.json。
• 校验输出尺寸、透明通道、帧方向、状态间角色大小一致性和边缘裁切问题。

最终产物默认是一个名为 myPet 的文件夹：

myPet/
├── pet.json
└── spritesheet.webp

如果运行构建脚本时添加 --png，还会额外生成 spritesheet.png 作为调试预览。

Skill 目录结构

codex-pet-generator/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── build_spritesheet.py

安装到 Codex

推荐在本地开发时使用软链接，这样你修改仓库里的 skill 后，Codex 读取到的也是最新版本：

mkdir -p "$HOME/.codex/skills"
ln -s "$(pwd)/codex-pet-generator" "$HOME/.codex/skills/codex-pet-generator"

如果你更希望复制安装：

mkdir -p "$HOME/.codex/skills"
cp -R ./codex-pet-generator "$HOME/.codex/skills/codex-pet-generator"

安装后，重启 Codex 桌面端，或者新开一个会话，让 skill 列表重新加载。

如何使用

在 Codex 中上传一张参考图，然后明确点名这个 skill：

使用 $codex-pet-generator，根据这张参考图生成一个 Codex pet 包，输出目录叫 myPet。

也可以指定 metadata：

使用 $codex-pet-generator，根据这张参考图生成 Codex pet。
pet id 用 yellow-rabbit，displayName 用 Yellow Rabbit，kind 用 animal。

如果已经有一张绿色背景源图，也可以直接运行脚本：

python3 ~/.codex/skills/codex-pet-generator/scripts/build_spritesheet.py \
  --source spritesheet-source.png \
  --out-dir myPet \
  --pet-id yellow-rabbit \
  --display-name "Yellow Rabbit" \
  --description "A cheerful yellow rabbit Codex pet." \
  --kind animal \
  --png

如果还没有安装 skill，也可以在仓库根目录直接把脚本路径换成 ./codex-pet-generator/scripts/build_spritesheet.py。

脚本依赖 Python 3 和 Pillow。如果当前 Python 环境没有 Pillow，需要先安装：

python3 -m pip install pillow

输出规格

spritesheet.webp 必须满足：

• 尺寸：1536x1872
• 网格：8 列 x 9 行
• 单元格：192x208
• 背景：透明
• 每行最多 8 帧
• 每个 cell 内角色完整可见、居中、不能贴边
• 每个状态行里的主体角色大小应保持一致，不能某个状态明显变小或变大

行顺序固定为：

1. idle
2. run right
3. run left
4. waving
5. jumping
6. failed
7. waiting
8. running
9. review

pet.json 格式：

{
  "id": "yellow-rabbit",
  "displayName": "Yellow Rabbit",
  "description": "A cheerful yellow rabbit Codex pet.",
  "spritesheetPath": "spritesheet.webp",
  "kind": "animal"
}

spritesheetPath 必须保持为 "spritesheet.webp"。

构建脚本默认使用 --scale-mode normalized，会按每个状态行的主体角色 bbox 计算统一目标尺寸，避免不同状态之间忽大忽小。脚本会打印 row_scale、body_width_range 和 body_height_range。如果你想恢复旧逻辑，让每一行独立放大到自己的最大安全尺寸，可以显式传入：

--scale-mode fit-row

让生成后的 Pet 在 Codex 中生效

Codex 会从 $CODEX_HOME/pets 读取自定义 pet；如果没有设置 CODEX_HOME，默认就是 $HOME/.codex/pets。

把生成好的 myPet 目录复制进去：

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME/pets"
cp -R ./myPet "$CODEX_HOME/pets/myPet"

目录放好后应该是：

~/.codex/pets/myPet/
├── pet.json
└── spritesheet.webp

然后重启 Codex 桌面端，或者打开 pet 选择器/新会话让 Codex 重新扫描 pets。pet 通常会以 pet.json 里的 displayName 显示。

如果没有生效，优先检查：

• ~/.codex/pets/myPet/pet.json 是否存在。
• ~/.codex/pets/myPet/spritesheet.webp 是否存在。
• pet.json 里的 spritesheetPath 是否正好是 "spritesheet.webp"。
• spritesheet.webp 是否为 1536x1872。
• Codex 是否已经重启或重新扫描。