awesome-codex-pet AGENTS.md

Awesome Codex Pet Agent Guide

本文件面向在本仓库内工作的 AI coding agents。

默认要求：

• 默认使用中文与用户沟通，除非用户明确要求英文。
• 优先做出可提交的仓库改动，而不是只停留在分析。
• 不要把过程产物混进最终 pet 包。

Pet Skill 版本

• $submit-codex-pet 是统一投稿入口：区分“请求社区制作”“制作或提交自己的宠物”和“高级 PR”，优先通过 GitHub API 操作，避免为了三个成品文件完整克隆大型素材仓库。
• $hatch-pet-v1 是仓库保留的旧版产线，输出 8x9、1536x1872 的 v1 spritesheet；维护现有仓库 pet 时使用它。
• $hatch-pet-v2 是从当前 Codex App 内置 skill 同步的 v2 产线，输出 8x11、1536x2288 的 spritesheet，并要求 pet.json.spriteVersionNumber: 2 与 16 个环视方向。
• 调用时必须显式选择版本。v1 与 v2 都可以收录，但 spriteVersionNumber、图集尺寸和实际行数必须匹配。

1. 项目是什么

awesome-codex-pet 是一个收集和分发 Codex 小宠物的仓库。

它同时承担三件事：

• 收录最终可安装的 pet 成品
• 生成 README 里的动作预览
• 提供无需 clone 仓库的一键安装方式

这个仓库不是宠物制作运行目录本身。制作过程中的参考图、QA 视频、调试文件、临时输出，可以保留在本地，但不应该成为 Git 跟踪内容。

2. 仓库里的真成品

每个 pet 目录只允许保留以下三个文件：

pets/<pet-slug>--<author-slug>/
├── submission.json
├── pet.json
└── spritesheet.webp

必须遵守：

• 目录名格式固定为 pet-slug--author-slug
• pet.json.id 必须与目录名完全一致
• pet.json.spritesheetPath 固定为 spritesheet.webp
• v1 的 spriteVersionNumber 可以省略或设为 1，spritesheet.webp 必须是 1536x1872 的 8x9 图集
• v2 必须设置 spriteVersionNumber: 2，spritesheet.webp 必须是 1536x2288 的 8x11 图集，最后两行包含 16 个环视方向
• spritesheet.webp 必须是最终运行时资源，不要放过程版

不要把这些文件放进 pets/<pet-id>/：

• qa/
• videos/
• *.mp4
• contact-sheet.png
• 参考图
• layout guides
• prompts
• decoded frames
• repair archive

3. 生成物与来源文件

仓库中允许在本地或 CI 生成的自动生成物主要有：

• assets/previews/<pet-id>/contact-sheet.png
• assets/previews/<pet-id>/gifs/*.gif
• README.md
• docs/zh-CN/README.md
• pets.json
• install-manifest.json

其中 assets/previews/<pet-id>/ 默认视为本地产物或部署产物，不作为长期 Git 跟踪内容。

这些文件不是手写维护优先项。除非只是极小文案修正，否则应优先修改生成脚本，再重新生成。

相关脚本：

• scripts/generate-pet-previews.py
• scripts/generate-readmes.mjs
• scripts/validate-pets.mjs
• scripts/install-pet.sh
• scripts/install-pet.ps1
• scripts/install-pet.mjs

4. 本地过程目录

以下内容允许存在于本地，但默认不应被 Git 跟踪：

• output/
• pets/*/qa/
• 本地缓存
• hatch-pet 运行目录

如果发现这些内容进入 git status，应优先通过 .gitignore 处理，而不是把它们并入提交。