hatch-pet

Hatch Pet

OpenDesign 集成。 这是未经修改的 Codex hatch-pet 技能， 随项目存放在 skills/hatch-pet/ 下，供任何 OpenDesign Agent 运行。技能完成打包后，生成的 spritesheet.webp（位于 ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/ 下）可通过 Settings → General → Pets → Import Codex sprite 导入 浮动宠物伙伴。导入流程会自动检测 8×9 / 192×208 图集，并让用户选择播放哪一行动画（待机、向右奔跑、挥手等）。

概述

根据一个概念、一张或多张参考图，或两者兼有，创建兼容 Codex 的动画宠物。此技能负责宠物专属的提示词规划、动画行、帧提取、图集几何、QA、预览和打包。视觉生成由 $imagegen 负责。

面向用户的输入均为可选项。如果用户未提供宠物名称，则根据概念或参考文件名推断；如果无法推断，则选择一个简短且合适的名称。如果用户未提供描述，则根据概念或参考图推断。如果用户未提供参考图，则先根据文本生成基础宠物，再将其用作每一行动画的规范参考图。

生成委派

所有常规视觉生成都使用 $imagegen。

生成基础美术、行条或修复行之前，请加载并遵循已安装的图像生成技能：

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

常规流程中不要直接调用 Image API。让 $imagegen 自行选择优先使用内置方式的流程及其 CLI 回退规则。如果 $imagegen 表示回退方式需要确认，请先征求用户同意再继续。

从此技能调用 $imagegen 时，将生成的宠物提示词作为权威视觉规范传入。不要将其包装进通用的 $imagegen 共享提示词架构中，也不要添加额外的润色、主视觉、照片、产品或插画风格增强。宠物提示词应简洁、专用于精灵图并以数字宠物为导向；只添加输入图像的角色标签以及用户提出的必要约束。

此技能的脚本仅用于确定性工作：准备提示词和清单、导入选定的 $imagegen 输出、提取帧、验证行、合成最终图集、创建 QA 媒体以及打包。

严格限制：不得使用本地 Python/Pillow 脚本、SVG、画布、HTML/CSS 或其他原生代码绘图方式来创建、绘制、平铺、扭曲、镜像或合成宠物视觉内容，以替代 $imagegen。常规宠物流程最多需要 10 项视觉生成任务：1 项基础宠物任务，加 9 项行条任务。唯一例外是 running-left：只有在生成并目视检查 running-right，且明确确认可以安全镜像后，才可通过镜像 running-right 派生。如果不适合镜像，则应使用 $imagegen 按常规方式生成 running-left 行。如果这些调用成本过高、受阻或不可用，请停止并说明阻碍，不要在本地伪造行条。

不得通过编辑 imagegen-jobs.json、将文件复制到 decoded/，或编写用于填充行输出的辅助脚本，将视觉任务标记为已完成。选定内置 $imagegen 输出时，请使用 record_imagegen_result.py；仅在文档说明的次级回退方案中使用 generate_pet_images.py。确定性脚本只能处理已生成的视觉输出。

只有基础任务可以仅使用提示词。通过 $imagegen 生成的每项行条任务都必须使用 imagegen-jobs.json 中列出的输入图像，包括基础任务记录后创建的规范基础参考图。任何未附带参考图的行生成都视为无效。

Codex 数字宠物风格

默认宠物美术风格应与 Codex 应用内置的数字宠物一致：小巧、接近像素画风的吉祥物，紧凑的 Q 版比例，敦实且清晰易辨的轮廓，粗重的深色 1-2 px 描边，明显的阶梯状／像素边缘，有限的配色，平涂赛璐璐阴影，简单而富有表现力的面部，以及细小的四肢。即使参考图更加精细、复杂或写实，生成的宠物也应简化为这种风格。

不要生成精致插画、绘画质感渲染、动漫主视觉图、3D 渲染、光亮的应用图标风格、写实的毛发或材质纹理、柔和渐变、高细节抗锯齿或复杂细小配饰。比此风格更精细的参考图，应先简化为统一风格，再生成各帧。

透明背景与特效

宠物帧会被处理成透明的 192x208 单元格，因此生成的每个像素都必须属于宠物精灵图，或属于可以干净移除的色键背景。优先通过姿势、表情和轮廓变化来表现状态，而不是添加装饰性特效。

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

• 特效与状态相关，并有助于说明动画。
• 特效应与宠物轮廓物理连接、接触或重叠，不得漂浮在旁边。
• 特效应位于与宠物相同的帧槽内，且不得构成独立的精灵图组件。
• 特效应为不透明、边缘清晰的像素风格，并使用非色键颜色。
• 特效应足够小，能够在 192x208 尺寸下清晰辨认，且不显杂乱。

允许的特效示例：接触面部的泪滴、接触盒子或头部的一小团烟雾，或宠物在失败／眩晕反应期间与其重叠的微小星星。

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

• 波浪标记、运动弧线、速度线、动作拖影、残影、模糊或涂抹效果
• 脱离主体的星星、零散闪光、漂浮的标点、漂浮图标、下落的泪滴、分离的烟云或散落的灰尘
• 投影、接触阴影、投射阴影、椭圆形地面阴影、地面色块、着陆标记、撞击爆发效果、发光、光环、灵气或柔和的透明特效
• 文字、标签、帧编号、可见网格、辅助标记、对话气泡、思考气泡、UI 面板、代码片段、棋盘格透明背景、白色背景、黑色背景或场景
• 宠物、道具、特效、高光或阴影中接近色键的颜色
• 游离像素、断开的描边碎片、斑点／噪点、被裁切的身体部位、相互重叠的姿势，或任何跨入相邻帧槽的姿势

特定状态指南：

• waving：仅通过爪子的姿势表现挥手。不要在爪子周围绘制波浪标记、运动弧线、线条、闪光或符号。
• jumping：仅通过身体位置表现垂直运动。不要绘制阴影、灰尘、着陆标记、撞击爆发效果、弹跳垫或地面提示。
• failed：如果遵守允许的特效规则，可以使用泪滴、连接主体的烟团或连接主体的星星；不要使用红色 X 标记、漂浮符号、分离的烟雾、脱离主体的星星或独立的泪滴。
• review：通过前倾、眨眼、眼神、歪头或爪子的位置表现专注。除非该道具已属于基础宠物形象，否则不要添加放大镜、纸张、代码、UI、标点或符号。
• running-right、running-left 和 running：仅通过身体、四肢和道具的移动表现运动。不要绘制速度线、尘云、地面阴影或运动轨迹。

宠物命名

如果用户没有提供宠物名称，且对话情境自然合适，请询问用户宠物的名称。如果询问会拖慢直接执行的请求，请从宠物概念、参考图或性格中选择一个简短合适的名称，然后始终使用该名称作为显示名称，并以此作为软件包文件夹名称的来源。

内置风格示例：

• Codex - 最初的 Codex 伙伴。
• Dewey - 一只整洁的小鸭，陪伴你度过平静的工作日。
• Fireball - 充满热情，适合快速迭代。
• Rocky - 差异内容变多时，稳如磐石。
• Seedy - 为新想法萌发的小小绿芽。
• Stacky - 均衡的堆栈，助力深度工作。
• BSOD - 一只小小的蓝屏捣蛋鬼。
• Null Signal - 来自虚空的寂静信号。

可见的进度计划

每次制作宠物时，都要保留一份可见的检查清单，让用户了解进度。开始前创建检查清单，一次只激活一个步骤，并在每个步骤完成后更新清单。

创建检查清单前，尽可能确定宠物名称。有用户提供的名称时就使用该名称；否则根据概念或参考资料推断一个简短合适的名称。如果名称太长、尚未确定，或不适合用于友好的检查清单，请改用 your pet。

普通宠物制作流程使用以下检查清单，并将 <Pet> 替换为宠物名称或 your pet：

1. 为 <Pet> 做好准备。
2. 构思 <Pet> 的主要外观。
3. 设想 <Pet> 的姿势。
4. 孵化 <Pet>。

各步骤含义如下：

• Getting <Pet> ready. 选择或确认宠物名称、描述、源图像和工作文件夹。
• Imagining <Pet>'s main look. 生成宠物的主要参考图像。对于新宠物，此步骤不可省略，即使用户没有提供图像也一样，因为它将作为视觉上的事实依据。
• Picturing <Pet>'s poses. 创建姿势行，先从 idle 和 running-right 开始，以确认宠物的外观仍保持一致。只有在翻转 running-right 后效果明显不错时，才镜像制作 running-left。
• Hatching <Pet>. 将获批的姿势制作成最终宠物文件，检查联系表、预览和验证结果，修复所有损坏的部分，将 pet.json 和 spritesheet.webp 保存到宠物文件夹，然后告知用户宠物文件和 QA 文件的保存位置。

只有在实际文件、图像或决策确实存在后，才能将相应步骤标记为完成。如果只是进行修复，请从第一个相关步骤开始，而不是重新开始整个检查清单。

默认工作流

1. 准备宠物运行文件夹和 imagegen 作业清单：

SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/hatch-pet"
python "$SKILL_DIR/scripts/prepare_pet_run.py" \
  --pet-name "<Name>" \
  --description "<one sentence>" \
  --reference /absolute/path/to/reference.png \
  --output-dir /absolute/path/to/run \
  --pet-notes "<stable pet description>" \
  --style-notes "<style notes>" \
  --force

除表达用户约束所需的标志外，以上参数均为可选项。对于纯文本请求，通过 --pet-notes 传入概念，并省略 --reference；prepare_pet_run.py 会根据需要推断名称、描述、色度键和输出目录。

2. 检查下一个已就绪的 $imagegen 作业：

python "$SKILL_DIR/scripts/pet_job_status.py" --run-dir /absolute/path/to/run

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

• imagegen-jobs.json 中列出的提示词文件
• 作业列出的所有输入图像及其角色标签
• 默认内置的 image_gen 路径，除非 $imagegen 自行选择其他路径

必须先完成基础作业。如果用户提供了参考图，基础作业应使用这些参考图。如果没有参考图，基础作业可以仅使用提示词。记录基础作业后，record_imagegen_result.py 会写入 decoded/base.png 和 references/canonical-base.png；所有行作业都会使用原始参考图（如有）以及这些规范化基础图像。

prepare_pet_run.py 还会在 references/layout-guides/ 下创建 9 张针对各行的布局指南图，每种动画状态一张。行作业会将匹配的指南作为仅供布局使用的输入，以便模型遵循正确的帧数、间距、居中方式和安全留白。将这些指南视为不可见的构图参考：生成的行条带中不得出现可见的方框、边框、中心标记、标签、指南颜色或指南背景。

生成行条带时，必须以行提示词中的身份锁定要求为准：不得重新设计宠物，并须保留相同的头部形状、面部、斑纹、配色、道具、轮廓线粗细、身体比例和剪影。即使确定性几何 QA 检查通过，只要某一行看起来像是相关但不同的宠物，也应判定为失败。

先生成并记录 running-right，再决定如何完成 running-left。检查 running-right 与基础图像及参考图是否一致。如果宠物在视觉上足够对称，水平镜像后仍能保留身份、道具位置、惯用侧、斑纹、光照、不含文字的细节以及方向语义，则使用以下方式生成 running-left：

python "$SKILL_DIR/scripts/derive_running_left_from_running_right.py" \
  --run-dir /absolute/path/to/run \
  --confirm-appropriate-mirror \
  --decision-note "<why mirroring preserves this pet's identity>"

如果存在任何不对称的侧边斑纹、可读文字、不可镜像的徽标、需区分左右手的道具、单侧配饰、光照特征或镜像后会出错的方向性姿势，则不要镜像。使用 $imagegen，通过该行的提示词和所有列出的参照图像生成 running-left，包括作为步态参考的 decoded/running-right.png。

对于内置路径，请记录来自 $CODEX_HOME/generated_images/.../ig_*.png 的所选源图像。不得将运行目录、tmp/、手工制作的测试素材、确定性行文件夹或后处理副本中的文件记录为视觉作业源文件。

4. 为作业选定生成结果后，将其导入：

python "$SKILL_DIR/scripts/record_imagegen_result.py" \
  --run-dir /absolute/path/to/run \
  --job-id <job-id> \
  --source /absolute/path/to/generated-output.png

这会将图像复制到确定性流水线所需的准确解码路径，并在 imagegen-jobs.json 中记录源元数据。

5. 所有作业完成后，进行最终处理：

python "$SKILL_DIR/scripts/finalize_pet_run.py" \
  --run-dir /absolute/path/to/run

预期输出：

run/
  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。

${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
  pet.json
  spritesheet.webp

在接受该宠物之前，请检查 qa/contact-sheet.png、qa/review.json、final/validation.json 和 qa/videos/。

确定性验证是必要条件，但并非充分条件。在确认宠物完成之前，请目视检查联系表，确保身份一致。如果任何一行改变了物种／体型、面部、斑纹、配色、道具设计、道具所在侧（非预期）或整体剪影，则不得接受。

子代理行生成

记录基础任务且 references/canonical-base.png 存在后，除非用户明确表示本次会话不要使用子代理，否则行条带视觉生成必须使用子代理。在生成行之前，说明将使用子代理，以及要委派哪些行任务。如果当前环境或工具策略阻止启动子代理，请在行条带生成前停止，解释阻碍，并在按顺序继续之前征求用户明确指示。

父 Agent 必须负责清单和软件包写入。

默认流程：

1. 父 Agent 运行 prepare_pet_run.py。
2. 父 Agent 生成并记录 base。
3. 父 Agent 运行 pet_job_status.py。
4. 父 Agent 首先为 idle 和 running-right 启动子代理，将其作为身份和步态检查。
5. 父 Agent 记录子代理返回的已选 idle 和 running-right 结果。
6. 父 Agent 判断是否可以安全地通过镜像派生 running-left；如果不行，父 Agent 将其视为常规的接地行任务并委派给子代理。
7. 父 Agent 为所有其余非派生的行图像生成任务启动子代理。
8. 每个子代理接收行提示词和所有列出的输入图像路径，调用 $imagegen，并且仅返回已选的 $CODEX_HOME/generated_images/.../ig_*.png 源路径。
9. 只有父 Agent 可以运行 record_imagegen_result.py、derive_running_left_from_running_right.py、修复排队、最终化、QA 和打包。

子代理写入边界：不得让子代理编辑 imagegen-jobs.json、将文件复制到 decoded/、运行 record_imagegen_result.py、运行 derive_running_left_from_running_right.py、运行 finalize_pet_run.py 或打包宠物。这样可以避免清单竞争，并将来源检查集中处理。

子代理交接约定：

• 除非有意将相邻的简单行合并处理，否则每个子代理只分配一个行任务。
• 提供行 ID、提示词文件的绝对路径、完整提示词文本或要求其读取该确切提示词文件的指示，以及 imagegen-jobs.json 中列出的每个输入图像路径及其角色标签。
• 明确提醒子代理，提示词中的透明度和效果规则是强制要求：不得有分离的效果；waving 不得有波浪标记；跑步行不得有速度线或灰尘；只有状态提示词允许时，才可使用附着的不透明精灵风格眼泪／烟雾／星星。
• 告诉子代理检查生成的候选图像，确认帧数、身份一致性、干净纯色的色键背景、安全间距，以及不存在被禁止的分离效果，然后再返回结果。
• 告诉子代理只返回已选原始 $CODEX_HOME/generated_images/.../ig_*.png 源路径，以及一句 QA 说明。由父 Agent 决定是否记录或修复。

对每个子代理使用此模板：

Generate the `<row-id>` row for this hatch-pet run.

Run dir: <absolute run dir>
Prompt file: <absolute prompt file>
Input images:
- <absolute path> — <role>
- <absolute path> — <role>

Read and follow the row prompt exactly, including the Transparency and artifact rules. Use `$imagegen` only; do not use local scripts to draw, tile, edit, or synthesize sprites.

Before returning, visually check:
- exact requested frame count
- same pet identity as the canonical base
- clean flat chroma-key background
- complete, separated, unclipped poses
- no forbidden detached effects or slot-crossing artifacts

Do not edit manifests, copy into decoded, record results, mirror rows, finalize, repair, or package. Return only:
selected_source=/absolute/path/to/$CODEX_HOME/generated_images/.../ig_*.png
qa_note=<one sentence>

不得静默回退为顺序执行：如果无法使用子代理进行行条带视觉生成，请停止并征求用户明确指示，然后再决定是否不使用子代理继续。只有诸如“不要使用子代理”或“按顺序运行”之类的明确用户指示，才允许采用常规的顺序行生成流程。最终答复必须报告委派给子代理的行任务，以及父 Agent 镜像派生或修复的任何任务。

修复工作流

如果最终化因行 QA 失败而停止，请将有针对性的修复任务加入队列：

python "$SKILL_DIR/scripts/queue_pet_repairs.py" \
  --run-dir /absolute/path/to/run

然后，对每个重新开放的行任务重复 $imagegen 生成和 record_imagegen_result.py 导入循环。只重新生成失败的最小范围：失败的行，而不是整张图。

对于身份修复，请使用规范基础图像、原始参考图、联系表和确切的行失败说明作为依据。只修复失败的行，同时保持规范宠物身份不变。

次级图像生成回退方案

scripts/generate_pet_images.py 是此技能的次级回退方案。

仅当当前环境中未安装 $imagegen 系统技能或无法调用它时才使用。正常创建宠物时应将视觉生成任务交给 $imagegen，因为 $imagegen 负责优先使用内置功能的图像生成策略及其自身的 CLI 回退行为。

只有在解释无法使用 $imagegen 的原因后，才能运行次级回退方案：

python "$SKILL_DIR/scripts/generate_pet_images.py" \
  --run-dir /absolute/path/to/run \
  --model gpt-image-2 \
  --states all

次级回退方案需要 OPENAI_API_KEY。

规则

• 保持 $imagegen 为主要生成层。
• 只要所选路径支持参考图，就始终将参考图附加到 $imagegen 并使其可见。
• 对每个行条带任务，都附加该行的 references/layout-guides/<state>.png 图像，且仅将其用作布局指南；不得接受复制指南图像像素的输出。
• 父 Agent 记录基础图像后，应使用子 Agent 生成行条带视觉内容。父 Agent 可以生成基础图像，但除非用户明确表示本次会话不使用子 Agent，否则行条带任务应交由子 Agent 处理。
• 每项常规视觉任务都使用 $imagegen 生成：基础图像，以及所有未经明确批准、可通过镜像派生的 running-left 行条带。
• 只有基础任务可以仅通过提示词生成；每个行任务都必须附加其指定的图像依据。
• 先委派 running-right，然后仅在视觉检查确认镜像处理不会改变身份特征和语义时，才镜像生成 running-left；否则，应将 running-left 作为常规的、有图像依据的 $imagegen 行任务委派。
• 缺少 $imagegen 输出时，绝不能用本地绘制、平铺、变换或代码生成的行条带替代。
• 绝不能手动修改 imagegen-jobs.json，谎称视觉任务已完成。
• 不要依赖生成的图像来保证图集几何尺寸精确；请使用此技能的确定性脚本。
• 使用 pet_request.json 中存储的色度键；不要强制使用固定的绿幕背景。
• 确保所有行中的宠物轮廓、面部、材质、配色和道具保持一致。
• 在每个基础图像、行条带和修复任务的提示词中，都遵守上述透明度和特效规则。
• 即使 qa/review.json 和 final/validation.json 没有错误，视觉身份特征发生偏移也必须视为阻塞问题。
• 联系表中出现裁切的参考图、重复平铺、白色单元格背景或非精灵图碎片时，必须判定为失败。
• 出现禁止的脱离主体特效、邻近色度键的杂色、阴影、光晕、涂抹、灰尘、落地标记、波纹标记、速度线或运动轨迹时，必须判定该行失败。
• qa/review.json 中的错误必须视为阻塞问题。警告则需要进行视觉检查。

验收标准

• 最终图集为 PNG 或 WebP 格式，尺寸为 1536x1872，支持透明度，并基于 192x208 的单元格。
• 已使用的单元格不得为空，未使用的单元格必须完全透明。
• 图集应遵循 references/animation-rows.md 中的行数和帧数。
• 除非明确跳过，否则必须生成联系表和预览视频。
• qa/review.json 中不得有错误。
• 逐行检查确认动画循环足够完整，可用于 Codex 应用。
• 对于自定义宠物，${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/pet.json 和 ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/spritesheet.webp 必须一并暂存。