用途
hatch-pet 用于从概念描述、一张或多张参考图片，或两者结合，制作与 Codex 兼容的动画宠物（animated pet）。它负责宠物专属的提示规划、动画行、帧提取、图集几何、质量检查（QA）、预览和打包，并把视觉生成部分委托给 imagegen 技能。
输入与命名
面向用户的输入都是可选的：未提供宠物名称时，从概念或参考文件名推断；无法推断时选择一个简短合适的名称。未提供描述时从概念或参考推断。未提供参考图片时，先生成基础宠物图，再将其作为所有动画行的规范参考。
生成分工
所有常规视觉生成都使用 imagegen。生成基础图、行动画条或修复行之前，需加载并遵循已安装的图像生成技能说明（路径为 ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md）。正常路径不直接调用 Image API，由 imagegen 自行选择内置优先路径及其 CLI 回退规则；若回退需要确认，应先询问用户。调用时将生成的宠物提示作为权威视觉规范传入，不套用通用共享提示结构，也不额外添加润色、主视觉、照片、产品图或插画风格修饰。
本技能的脚本仅用于确定性工作：准备提示与清单、收录选定的 imagegen 输出、提取帧、校验行、合成最终图集、创建 QA 素材和打包。硬性边界：不得用本地 Python/Pillow 脚本、SVG、canvas、HTML/CSS 或其他代码原生绘制替代 imagegen 生成宠物视觉。一次常规运行预计最多 10 个视觉生成任务：1 个基础宠物加 9 个行动画条；唯一例外是 running-left，可在 running-right 生成、目视检查并明确确认适合镜像后，通过水平镜像派生。
风格要求
默认宠物美术应匹配 Codex 应用内置数字宠物的风格：小尺寸、像素艺术风格吉祥物，紧凑 chibi 比例，厚重易读剪影，1-2 像素深色描边，可见阶梯/像素边缘，有限调色板，平涂赛璐璐着色，简单表情面孔和小巧四肢。即使参考图更复杂或写实，也应简化为该风格。不建议生成精细插画、绘画渲染、动漫主视觉、3D 渲染、光泽应用图标、真实毛发或材质、柔和渐变、高细节抗锯齿及复杂小配件。
透明度与特效
行动画条会被处理成透明 192x208 单元格，因此每个生成像素要么属于宠物精灵，要么是可干净移除的色键背景。优先通过姿势、表情和剪影变化表达，而非装饰特效。允许的特效需同时满足：与状态相关且帮助解释动画；物理上附着或重叠宠物剪影；位于同一帧槽内且不形成独立精灵组件；不透明、硬边、像素风格且使用非色键颜色；小到在 192x208 下仍可读。允许示例：触碰脸部的眼泪、接触箱子或头部的小烟团、失败/眩晕时与宠物重叠的小星星。默认避免波纹、动势弧线、速度线、残影、模糊、分离星星、漂浮图标、投影、地面阴影、发光、文字、网格、UI 面板、棋盘透明背景、白/黑背景与场景等。各状态另有具体指引，例如挥手只用爪子姿势表达，跳跃只用身体位置表达垂直运动。
使用方式与流程
- 运行 prepare_pet_run.py 准备运行文件夹与 imagegen 任务清单（参数含 --pet-name、--description、--reference、--output-dir、--pet-notes、--style-notes、--force；除表达用户约束所需的标志外均可选）。文本请求可仅传 --pet-notes 并省略 --reference。
- 用 pet_job_status.py 查看就绪任务，逐一调用 imagegen，传入清单中的提示文件、任务列出的每张输入图像及其角色标签。基础任务须先完成；有参考图时基础任务使用参考图，无参考图时可仅用提示。记录基础后脚本写出 decoded/base.png 与 references/canonical-base.png，所有行任务使用原始参考图加规范基础图。
- prepare_pet_run.py 还会在 references/layout-guides/ 下生成每个动画状态对应的布局参考图，作为不可见构建参考，生成结果不得包含可见框线、标记、标签或背景。
- 先生成并记录 running-right，再决定 running-left。若宠物视觉对称且水平镜像能保持身份、道具位置、标记、光照与方向语义，可用 derive_running_left_from_running_right.py 派生（需 --confirm-appropriate-mirror 与说明）；否则用 imagegen 生成。
- 用 record_imagegen_result.py 收录选定输出（--run-dir、--job-id、--source）。
- 全部完成后运行 finalize_pet_run.py --run-dir。产物包括 pet_request.json、imagegen-jobs.json、prompts/、decoded/、frames/frames-manifest.json、final/spritesheet.png、final/spritesheet.webp、final/validation.json、qa/contact-sheet.png、qa/review.json、qa/run-summary.json、qa/videos/*.mp4。包默认写入 ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/ 下的 pet.json 与 spritesheet.webp。
质量检查与修复
接受前需查看 contact-sheet、review.json、validation.json 与预览视频。确定性校验必要但不充分：若任一行改变物种/体型、面部、标记、调色板、道具设计或整体剪影，应拒绝。若包出现透明边缘的绿/青色键色残留，可用 cleanup_chroma_spill.py 做确定性清理（仅清除透明边缘附近的键色溢出色，不重绘），并可选 --sync-codex-pets 同步安装包；清理后应复查 JSON 报告（after_residual 通常应为 0）并重新目视检查。
子代理模式
基础任务记录且规范基础图存在后，行条生成须使用子代理，除非用户明确表示本会话不使用；使用前应说明并列出委托的行任务。若环境或工具策略无法启动子代理，应在行条生成前停止、说明阻塞并请求用户明确指示后再继续。父代理负责清单与包的写入。
限制
该技能依赖 imagegen 技能完成视觉生成；若图像生成调用过贵、被阻止或不可用，应停止并说明，而不是本地伪造行条。不得通过编辑清单或复制文件标记视觉任务完成。未在资料中说明具体收费、支持平台或其他使用效果。