hatch-pet

Hatch Pet

Open Design 集成说明。 这是未经修改的 Codex hatch-pet Skill，
存放于 skills/hatch-pet/ 目录下，方便任意 Open Design Agent 运行。Skill
打包完成后，生成的 spritesheet.webp（存放在
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/ 下）可以通过 设置 → 宠物 → 导入 Codex 精灵 导入到悬浮宠物伴侣中。
导入流程会自动识别 8×9 / 192×208 图集网格，并允许用户选择要播放的动画行（待机 idle、向右跑 running-right、招手 waving 等）。

概述

从某个概念构想、一张或多张参考图片，或者两者结合，打造与 Codex 兼容的动态电子宠物。本 Skill 全权负责宠物专属的 Prompt 规划、动画行安排、帧提取、图集几何结构、QA 质检、预览以及打包导出，并将图像生成逻辑委托给 $imagegen。

用户输入的参数均为可选。若用户未提供宠物名称，可根据构想概念或参考图文件名进行推断；若无法推断，请选择一个简短合适的名称。若用户未提供描述，从构想或参考图推断。若用户未提供参考图片，先根据文本生成基础宠物图，并将其作为后续每一行动画生成的标准参考基准。

生成委托

所有常规图像生成均使用 $imagegen。

在生成基础原画、动画行序列图或修复行之前，先加载并遵循已安装的图像生成 Skill：

${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md

在正常流程中，请勿直接调用 Image API。让 $imagegen 自行选择内置优先路径及其 CLI 回退规则。如果 $imagegen 提示回退方案需要确认，请在继续之前先询问用户。

从本 Skill 调用 $imagegen 时，将生成的宠物 Prompt 作为权威视觉规范传入。不要将其包裹在通用 $imagegen 共享 Prompt 范式中，也不要额外添加修图、主视觉图（hero-art）、摄影、产品图或插画风增强修饰。宠物 Prompt 应保持精炼、面向精灵图与数字宠物风格；仅添加输入图像的角色标签以及任何必需的用户约束。

本 Skill 的脚本仅用于确定性工作：准备 Prompt 与任务清单（manifest）、接收选定的 $imagegen 输出、提取单帧、校验动画行、拼装最终图集、生成 QA 媒体以及打包。

硬性边界：切勿使用本地 Python/Pillow 脚本、SVG、Canvas、HTML/CSS 或其他代码原生绘图替代 $imagegen 来创建、绘制、平铺、扭曲、镜像或合成宠物视觉效果。对于一次正常的宠物生成，预计最多包含 10 个视觉生成任务：1 个基础宠物图 + 9 个动画行序列图任务。唯一的例外是 running-left（向左跑）：仅在 running-right（向右跑）生成完毕、经人工检查并明确确认可以安全镜像翻转后，才允许通过翻转 running-right 派生。若不适合镜像，则应将 running-left 作为普通的以参考图为基础的 $imagegen 任务进行生成。若这些生成调用消耗过高、被阻断或不可用，请直接停止并说明原因，切勿在本地凭空伪造动画行序列图。

切勿通过修改 imagegen-jobs.json、将文件复制到 decoded/ 或编写填充行产物的辅助脚本来将视觉任务标记为已完成。选定的 $imagegen 内置产物请使用 record_imagegen_result.py 进行记录，或者仅在符合文档说明的二级回退策略时使用 generate_pet_images.py。确定性脚本只允许处理已经生成的视觉产物。

只有基础任务允许仅凭借 Prompt 生成。通过 $imagegen 生成的每一个动画行序列图任务，都必须使用 imagegen-jobs.json 中列出的输入图像，包括基础任务记录后创建的标准基础参考图。任何未附加基准参考图的动画行生成，均视为无效操作。

Codex 电子宠物画风

默认的宠物画风应与 Codex App 内置的电子宠物保持一致：小巧的 Q 版比例像素风吉祥物、体积感强且辨识度高的剪影、粗实清晰的 1-2px 暗色外轮廓、肉眼可见的阶梯/像素边缘、受限的配色方案、平涂赛璐珞阴影、简单且有表现力的面部以及微型四肢。即使参考图更精致、复杂或写实，也必须将其简化收拢为这种风格。

切勿生成精细插画、水彩/油画质感渲染、动漫主视觉图、3D 渲染、亮面 App 图标处理、逼真皮毛或材质纹理、柔和渐变、高细节抗锯齿以及复杂的微型饰品。比此规范更复杂的参考图，在生成动画行之前必须先简化收拢为本画风。

透明度与视觉特效

宠物动画行会被切分处理为透明的 192x208 单元格，因此生成的每一个像素点必须要么属于宠物精灵图本身，要么是可被干净抠除的绿幕/抠像背景（chroma-key）。相比装饰性特效，应优先通过姿态、表情和剪影变化来表现动画。

允许使用的特效必须同时满足以下所有条件：

• 特效与当前状态强相关，有助于直观表达动画含义。
• 特效紧贴、接触或重叠在宠物剪影上，而不是悬浮在附近。
• 特效位于与宠物相同的单帧格内，不会形成独立的精灵组件。
• 特效是不透明、硬边缘、像素风的，且使用的是非抠像背景色。
• 特效足够小，在 192x208 尺寸下清晰易读而不杂乱。

允许使用的特效示例：紧贴面部的眼泪、紧贴箱子或头部的一小缕烟雾、或者宠物在失败/眩晕反应中重叠在身上的微型小星星。

默认应避免以下元素，因为它们通常会破坏透明背景清理或组件提取：

• 挥手波纹、动作弧线、速度线、动态尾迹、残影、模糊或涂抹效果
• 分离的星星、散乱闪光、悬浮标点符号、悬浮图标、掉落的泪珠、分离的云朵或散落的灰尘
• 投射阴影、接触阴影、外发光/落影、椭圆形地面阴影、地面印痕、着陆标记、冲击波、光晕、气场或柔和半透明特效
• 文字、标签、帧编号、可见网格、参考线、对话气泡、心理气泡、UI 面板、代码片段、棋盘格透明背景、纯白背景、纯黑背景或背景场景
• 宠物、道具、特效、高光或阴影中使用了与抠像颜色过于接近的相近色
• 杂像素、断裂的轮廓碎片、噪点斑点、截断的身体部位、重叠交错的姿态，或任何跨越到相邻帧格区域的姿态

特定状态指南：

• waving（招手）：仅通过爪子的姿势变化表达招手动作。不要在爪子周围绘制挥手线、动作弧线、线条、闪光或符号。
• jumping（跳跃）：仅通过身体的位置移动表达垂直跃动。不要绘制阴影、灰尘、着陆痕迹、冲击波、弹簧垫或地面提示。
• failed（失败）：只要符合允许特效的规则，允许使用眼泪、紧贴的烟雾或紧贴的星星；不要使用红色的 X 标记、悬浮符号、分离的烟雾、分离的星星或独立的泪珠颗粒。
• review（评审）：通过身体倾斜、眨眼、眼神方向、歪头或爪子摆放来展现专注感。除非基础宠物设定中本来就包含对应道具，否则不要额外添加放大镜、纸张、代码、UI 界面、标点或符号。
• running-right（向右跑）、running-left（向左跑）与 running（跑步）：仅通过身体、四肢和道具的运动来表现奔跑动作。不要绘制速度线、烟尘云、地面阴影或运动拖尾。

宠物命名

当用户未提供宠物名称时，仅在对话流程自然顺畅的前提下询问用户。如果询问会拖慢直接执行的节奏，可根据宠物概念、参考图或性格特点挑选一个简短恰当的名字，并在后续作为显示名称以及打包文件夹 slug 保持统一使用。

内置风格的优秀命名示例：

• Codex - 经典的 Codex 悬浮宠物伴侣。
• Dewey - 一只爱整洁的小鸭子，陪你度过平静的工作日。
• Fireball - 充斥着火热能量，助你快速迭代。
• Rocky - 当 Diff 变得巨长时，像岩石一样稳重可靠。
• Seedy - 萌发新灵感与新想法的小绿芽。
• Stacky - 为深度工作而生、结构平衡的叠叠乐。
• BSOD - 蓝屏死机造型的微型小恶魔。
• Null Signal - 来自虚无空间的安静信号。

实时进度计划

对于每次宠物生成流程，保持一个可见的任务清单，以便用户清楚看到当前进度。在开始前创建清单，每次只保持一个步骤处于激活状态，并在每个步骤完成时及时更新。

在创建清单前，尽可能先确定宠物名称。如果用户指定了名称则直接使用；否则从概念或参考图推断一个简短合适的名称。如果名称太长、尚未确定或不适合放在亲切的清单中，则统一使用 your pet（你的宠物）。

在标准的宠物生成流程中使用以下清单，将 <Pet> 替换为宠物名称或 your pet：

1. Getting <Pet> ready.
2. Imagining <Pet>'s main look.
3. Picturing <Pet>'s poses.
4. Hatching <Pet>.

各步骤含义说明：

• Getting <Pet> ready. 确定或确认宠物名称、描述、源图片与工作目录。
• Imagining <Pet>'s main look. 生成宠物的主参考图。即使用户没有提供图片，新宠物也必须执行此步，因为这是后续视觉效果的终极标准（Source of Truth）。
• Picturing <Pet>'s poses. 制作各姿态行，从 idle（待机）和 running-right（向右跑）开始，以确认宠物外观的一致性。只有在 running-right 翻转后依然表现良好的情况下，才采用镜像方式导出 running-left。
• Hatching <Pet>. 将确认通过的姿态转换为最终的宠物文件，审查检验图版（contact sheet）、预览效果及校验结果，修复破损部分，将 pet.json 与 spritesheet.webp 保存到宠物目录，最后告知用户宠物与 QA 文件的保存路径。

只有当对应的真实文件、图像或决策真正落地时，才可将步骤标记为完成。如果本次仅为修复任务（repair run），直接从第一个相关步骤开始即可，无需重新跑一遍完整清单。

默认工作流

1. 准备宠物运行目录与 imagegen 任务清单（manifest）：

SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/hatch-pet"
python "$SKILL_DIR/scripts/prepare_pet_run.py" \
  --pet-name "<Name>" \
  --description "<一句话描述>" \
  --reference /绝对路径/到/参考图.png \
  --output-dir /绝对路径/到/运行目录 \
  --pet-notes "<稳定的宠物特征描述>" \
  --style-notes "<画风标注>" \
  --force

除为了表达用户限制所需传入的 Flag 外，上述所有参数均为可选。对于纯文本请求，通过 --pet-notes 传入概念说明，并省略 --reference；prepare_pet_run.py 将根据需要自动推断名称、描述、抠像颜色和输出目录。

2. 检查下一步待执行的 $imagegen 作业：

python "$SKILL_DIR/scripts/pet_job_status.py" --run-dir /绝对路径/到/运行目录

3. 对于每个就绪的作业，使用以下内容调用 $imagegen：

• imagegen-jobs.json 中列出的 Prompt 文件
• 为该作业列出的每张输入图像及其角色标签（role label）
• 默认内置的 image_gen 路径，除非 $imagegen 本身路由到其他路径

<!-- truncated for translation batch; full body continues in source -->