制作一个自定义 Pet，需要让同一角色在待机、工作、等待和转头时保持一致。本文以灰原哀学习伙伴为例，记录角色设计、动画修复、图集校验，以及向读者分享成果时需要说明的细节。
整理与官方资料核对日期：2026-09-17。本文保留案例中的 Codex 产品称呼；当前官方 Pets 页面以 ChatGPT 桌面应用介绍桌面入口，实际菜单以安装版本为准。文件与视觉检查结果来自既有制作记录，本次文章整理未复测 Pet，应用内显示仍待验证。
1. 适用范围
本文介绍自定义 Codex Pet 的制作流程，包括角色设计、动画生成、方向检查、图集合成、打包和安装验证。文档以灰原哀 Pet 项目的制作记录为例，记录从角色母版到安装验证的完整过程。
案例使用本地 hatch-pet v2 流程。文中的图集尺寸、目录结构和配置示例对应该项目，不代表所有版本或使用端的统一要求。开始制作前，制作者应让 Codex 读取当前环境中的技能说明，确认目标版本、图集规格及安装位置。桌面端与网页端的资源要求应分别确认。
案例中的动画与文件检查已完成，安装副本已验证；应用界面中的实际加载效果尚未确认。
2. 工具与输入材料
案例使用内置图像生成工具制作角色和动作，使用 hatch-pet 配套脚本进行图像提取、对齐、透明背景处理、图集合成及格式检查。
制作前需要明确以下输入：
| 输入 | 说明 |
|---|---|
| 角色描述或参考图 | 确定外观、服装、配色和可辨识特征 |
| 画风与比例 | 例如 Q 版、像素风，或其他适合小尺寸显示的风格 |
| 动作要求 | 明确待机、工作、等待等状态的表现方式与动作幅度 |
| 目标环境 | 确认应用版本、可用图像工具及当前 Pet 格式 |
| 验收要求 | 明确需要交付的预览、检查报告、安装文件及应用内验证结果 |
官方 Pets 文档提供通过设置中的 Create pet 入口创建自定义 Pet 的流程；具体入口以所安装的版本为准。该入口会加载配套制作技能。制作完成后，需要返回 Pet 设置刷新列表并选择新角色。具体流程见官方 Pets 文档。1
3. 确定角色母版
3.1 生成静态候选图
制作流程首先生成静态候选图，由制作者确认角色外观，再进入动画阶段。候选图需要完整呈现角色，并保留动作所需的画面空间。
灰原哀案例采用紧凑的 Q 版比例，保留茶棕短发、冷静神情和深色外套。动作设计围绕学习、思考和检查代码的场景展开。
候选图检查包括：
- 缩小后，脸部、四肢和主要轮廓是否仍然清楚。
- 发型、服装和配色是否符合角色设定。
- 头部、手部与鞋子是否完整，没有贴近裁切边界。
- 轮廓附近是否存在背景残留或明显光晕。
3.2 固定母版与外观约束
候选图确认后，生成统一的角色母版。后续动作应持续引用同一母版，并保持发型、服装、头身比例和配色一致。
该案例沿用候选 B 的外观，并将母版作为各组动画的共同参考。原始参考图、候选图和母版分别保留，便于后续复查与修改。
4. 生成并检查状态动画
4.1 按状态定义动作
动作要求应描述可观察的变化，例如眨眼、抬头、手臂摆动和轻微起跳。仅使用“自然”“生动”等描述，难以形成明确的检查标准。
灰原哀案例的待机动作采用轻微呼吸与眨眼，思考和检查动作保持克制，等待动作通过眼神及头部变化表达状态。具体状态名称、排列和帧数以当前制作规范为准。
各组动画生成后，先输出预览，再检查角色外观与动作连续性。对于非对称发型、服装或道具，左右动作需要单独判断是否能够镜像生成。该案例分别生成左右跑动，避免水平翻转改变发型特征。
4.2 检查跨状态一致性
动画检查需要覆盖单组循环和不同状态之间的切换。
| 检查项 | 观察内容 |
|---|---|
| 角色尺寸 | 状态切换时是否突然放大或缩小 |
| 身体比例 | 头部、躯干和四肢的比例是否发生无意变化 |
| 脚底基准 | 待机与动作结束后的落脚位置是否协调 |
| 裁切 | 头发、手部和鞋子是否超出单格边界 |
| 循环衔接 | 最后一帧回到第一帧时是否出现突变 |
| 外观稳定性 | 相邻帧中的服装、表情和轮廓是否保持一致 |
案例中，首版跳跃动画的落地人物高度约为 153 像素，待机人物高度约为 198 像素。格式检查未发现问题，但动画预览中存在明显的比例变化。
修复时重新生成整组跳跃动作，采用小幅起跳，并重新检查落地与待机的衔接。该案例说明，图像尺寸和文件格式符合要求，仍不足以确认动画观感合格。
5. 制作多方向注视
案例采用的 v2 流程包含 16 个注视方向。生成前需要统一方向定义，明确左右均以观看者看到的画面为准。
| 方向标记 | 对应方向 |
|---|---|
000 |
向上 |
090 |
画面右侧 |
180 |
向下 |
270 |
画面左侧 |
在该流程中，000 表示向上。四个主要方向确认后，再生成中间角度，并按规定顺序检查完整循环。
人形角色的注视动作应由眼睛、头部和颈部协同完成。双脚与下半身保持稳定，眼睛先转向目标，头部轻微跟随，上半身仅作必要调整。整体旋转人物会同时改变身体姿态，不适合代替单纯的视线变化。
案例中，首版后半圈方向图将部分应朝画面左上方的姿态生成为朝右侧。修复时重新生成对应整行，并再次检查方向含义与连续播放效果。
方向验收应同时检查单格和连续预览。单格用于判断角色是否朝向目标区域，连续预览用于发现反向、跳变和不协调的过渡。相邻方向差异细微时，检查记录应保留这一限制。
6. 合成图集并处理透明边缘
Spritesheet 是按固定网格排列动画帧的图像文件。应用根据格式约定读取对应位置，因此行列顺序、单格尺寸和透明通道需要与目标格式一致。
本案例的交付规格如下：
| 项目 | 规格 |
|---|---|
| 格式版本 | spriteVersionNumber: 2 |
| 图集排列 | 8 列 × 11 行 |
| 单格尺寸 | 192 × 208 像素 |
| 图集总尺寸 | 1536 × 2288 像素 |
| 图片格式 | 带透明通道的 WebP |
| 内容 | 9 个标准动作状态、16 个注视方向及中性姿态格 |
该规格对应本地案例。网页端上传要求应另行查阅官方 Pets 文档1，不能直接套用桌面制作文件。
案例生成阶段使用青色背景 #00FFFF，后续由脚本去除背景并清理边缘残色。透明处理完成后，需要将角色分别置于浅色和深色背景上检查，观察头发、衣领、手指等位置是否存在残色、光晕或误删。
背景去除颜色应结合角色配色选择，避免与角色主体颜色重合。
7. 打包与安装
案例的核心交付文件为：
haibara-study-companion/
├── pet.json
└── spritesheet.webp
以下配置基于案例整理，描述字段改为客观表述：
{
"id": "haibara-study-companion",
"displayName": "灰原哀 · Haibara",
"description": "用于学习与代码检查场景的灰原哀角色。",
"spriteVersionNumber": 2,
"spritesheetPath": "spritesheet.webp"
}
创建其他角色时，需要修改标识、显示名称和描述，并确认图像路径与实际文件一致。配置声明的版本需要与图集内容匹配。
该案例安装在 Windows 用户目录下的 .codex/pets/haibara-study-companion。其他环境的路径由实际配置决定，安装前应先确认。安装过程中还应检查目标目录是否已有同名角色，避免覆盖现有文件。
安装后，需要校验目标目录内的副本，确认其内容与交付文件一致。原始参考图、母版、生成提示词、预览及检查报告应保留在制作目录中，便于后续修改。
8. 验收与完成状态
验收分为文件、视觉和应用三个层面。
| 层面 | 检查内容 | 本案例记录 |
|---|---|---|
| 文件检查 | 配置、图集尺寸、透明通道、路径及安装副本一致性 | 已通过 |
| 视觉检查 | 标准动作、角色比例、方向含义、连续性和透明边缘 | 已通过，保留少数相邻方向变化细微的记录 |
| 应用检查 | 列表识别、实际加载、显示尺寸和状态切换 | 尚未验证 |
制作者应在应用中刷新 Pet 列表，选择新角色，观察实际显示与动作切换。检查报告应分别记录三个层面的结果，避免将文件校验通过视为应用内效果已经确认。
9. 制作任务描述示例
以下内容为根据案例整理的任务描述，可由制作者补充角色信息后提交给 Codex，并非原始对话的逐字记录。
任务：制作一个用于 Codex 的自定义 Pet。
角色输入：
- 角色描述或参考图：由制作者提供。
- 画风与比例：由制作者指定。
- 动作气质与幅度：由制作者指定。
执行要求：
1. 读取当前环境中的 hatch-pet 规范，确认格式版本、图集要求和安装位置。
2. 先生成静态候选图，由制作者选定后建立统一母版。
3. 依据母版生成各状态动画，保持发型、服装、比例和角色大小一致。
4. 输出各状态预览，检查尺寸变化、裁切、脚底位置及循环衔接。
5. 如目标格式支持多方向注视，先确认上下左右，再检查完整方向序列。
6. 检查透明边缘，并在浅色与深色背景上复核。
7. 合成图集、生成配置，交付安装包、预览和检查报告。
8. 分别说明文件检查、视觉检查和应用检查的完成情况。
10. 分享 Pet 前需要补齐的发布信息
10.1 区分格式版本与发布版本
pet.json 中的 spriteVersionNumber: 2 表示图集格式，不是作品的第 2 次发布。作品另用 v1.0.0、v1.0.1 等标记交付版本，例如 haibara-study-companion-v1.0.0.zip；这里的版本号只是首次发布的命名示例，尚未表示已经发布。
每次分享时，至少记录以下内容：
| 信息 | 本案例应如何填写 |
|---|---|
| 角色标识 | haibara-study-companion |
| 显示名称 | 灰原哀 · Haibara |
| 格式 | 本案例为 v2，WebP 图集尺寸为 1536 × 2288 |
| 发布版本与日期 | 在实际上传时填写，不把文章整理日期当作已发布证据 |
| 兼容环境 | 填写实际测试的操作系统和应用版本；目前没有已复核的版本号 |
| 检查结果 | 分别记录文件、视觉和应用内检查，不合并为笼统的“全部通过” |
| 已知限制 | 应用内加载尚未验证，少数相邻注视方向变化细微 |
| 文件完整性 | 对实际发布 ZIP 计算 SHA-256，并将结果与下载链接放在一起 |
桌面端制作的自定义 Pet 保存在本机，不会自动同步到网页端；网页端使用独立的上传要求。不要把本案例 ZIP 或 v2 图集写成“所有端通用”。1
10.2 准备可独立使用的安装包
对外分享时，建议保持一个明确的顶层目录，避免读者解压后分不清哪些文件应安装：
haibara-study-companion-v1.0.0.zip
└── haibara-study-companion/
├── pet.json
├── spritesheet.webp
└── README.txt
其中 README.txt 应说明作品版本、格式版本、测试环境、安装目录确认方法、刷新与选择步骤、已知问题和素材来源。动画预览和检查报告可单独提供，避免把整份制作目录、私人对话或本机绝对路径打入安装包。
发布页面应分别展示一张角色预览、一段状态动画和一段方向动画。静态图集是供程序读取的素材，不会因为以 WebP 格式保存就自动在网页中播放整套动作；文章中的动画演示需要另行导出。
当前文章没有附带实际图片或 ZIP，因此暂不提供下载入口。补齐文件、验证解压内容并计算校验值后，再加入真实链接。
10.3 读者安装与更新
- 先核对下载包说明中的应用版本与格式要求，再解压检查
pet.json和spritesheet.webp是否位于同一角色目录。 - 确认当前应用实际使用的 Pet 目录。本案例历史安装位置为 Windows 用户目录中的
.codex/pets/haibara-study-companion，不是所有环境都固定使用此位置。 - 如果目标目录已有同名 Pet，先把旧目录备份到 Pet 扫描目录之外，再放入新版本，避免新旧配置与图集混用。
- 返回应用的 Pet 设置，刷新列表并选择新角色；具体入口以当前版本为准。1
- 检查角色是否出现、尺寸是否合适、动作是否裁切，以及真实状态切换是否正常。仅能在文件浏览器打开 WebP 不算应用验收完成。
- 更新失败时，移出新目录、恢复旧目录，再刷新选择。记录应用版本和错误现象，便于复现。
10.4 发布说明与后续修订
首次分享可以使用如下说明，发布前应将待填项替换为真实结果：
名称：灰原哀 · Haibara
作品版本：待填写
发布日期：待填写
适用环境：待填写实际测试的操作系统与应用版本
格式：spriteVersionNumber 2，1536 × 2288 WebP
安装包：待补充真实下载链接
SHA-256：待对最终 ZIP 计算
验证：文件与视觉结果来自既有制作记录；应用内显示待验证
已知问题：少数相邻注视方向变化细微
更新内容：待填写本次实际变更
发布后修改动作、配置或兼容性说明时，应更新作品版本及变更记录。文件名包含版本号，便于读者区分下载内容；旧链接继续保留多久，则在发布页明确说明。
素材来源与使用说明应随交付包提供。本文是灰原哀角色的个人制作案例，不宣称为官方角色包；博客仓库的 MIT 许可证不应被直接用作角色形象或第三方参考素材的授权说明。
11. 资料与记录
案例依据为原草稿所引用的项目 README、交付配置、制作汇总及修复记录。本文沿用这些历史结果，未重新执行动画生成、安装或应用内验证。