hatch-pet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hatch Pet

孵化宠物

Overview

概述

Create a Codex-compatible animated pet from a concept, one or more reference images, or both. This skill owns pet-specific prompt planning, animation rows, frame extraction, atlas geometry, QA, previews, and packaging. It delegates visual generation to

$imagegen

User-facing inputs are optional. If the user omits a pet name, infer one from the concept or reference filenames; if that is not possible, choose a short appropriate name. If the user omits a description, infer one from the concept or references. If the user omits reference images, generate the base pet from text first, then use that base as the canonical reference for every animation row.

从概念设计、一张或多张参考图像，或两者结合创建兼容Codex的动画宠物。本技能负责宠物专属的提示词规划、动画行、帧提取、图集几何设计、QA验证、预览和打包工作，将视觉生成任务委托给

$imagegen

。

用户提供的输入为可选项。若用户未提供宠物名称，可从概念设计或参考文件名中推断；若无法推断，则选择一个简短合适的名称。若用户未提供描述，同样从概念设计或参考素材中推断。若用户未提供参考图像，则先通过文本生成基础宠物形象，再将该基础形象作为所有动画行的标准参考。

Generation Delegation

生成委托

Use

$imagegen

for all normal visual generation.

Before generating base art, row strips, or repair rows, load and follow the installed image generation skill:

text

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

Do not call the Image API directly for the normal path. Let

$imagegen

choose its own built-in-first path and its own CLI fallback rules. If

$imagegen

says a fallback requires confirmation, ask the user before continuing.

When invoking

$imagegen

from this skill, pass the generated pet prompt as the authoritative visual spec. Do not wrap it in the generic

$imagegen

shared prompt schema and do not add extra polish, hero-art, photo, product, or illustration-style augmentation. Pet prompts should stay terse, sprite-specific, and digital-pet oriented; only add role labels for input images and any essential user constraint.

Use this skill's scripts for deterministic work only: preparing prompts and manifests, ingesting selected

$imagegen

outputs, extracting frames, validating rows, composing the final atlas, creating QA media, and packaging.

Hard boundary: do not create, draw, tile, warp, mirror, or synthesize pet visuals with local Python/Pillow scripts, SVG, canvas, HTML/CSS, or other code-native art as a substitute for

$imagegen

. For a normal pet run, expect up to 10 visual generation jobs: 1 base pet plus 9 row-strip jobs. The only exception is

running-left

, which may be derived by mirroring

running-right

only after

running-right

has been generated, visually inspected, and explicitly approved as safe to mirror. If mirroring is not appropriate, generate

running-left

as a normal grounded

$imagegen

row. If those calls are too expensive, blocked, or unavailable, stop and explain the blocker instead of fabricating row strips locally.

Do not mark visual jobs complete by editing

imagegen-jobs.json

, copying files into

decoded/

, or writing helper scripts that populate row outputs. Use

record_imagegen_result.py

for selected built-in

$imagegen

outputs, or

generate_pet_images.py

only for the documented secondary fallback. The deterministic scripts may only process already-generated visual outputs.

Only the base job may be prompt-only. Every row-strip job generated through

$imagegen

must use the input images listed in

imagegen-jobs.json

, including the canonical base reference created after the base job is recorded. Treat any row generation without attached grounding images as invalid.

所有常规视觉生成任务均使用

$imagegen

完成。

在生成基础原画、行条带或修复行之前，加载并遵循已安装的图像生成技能规则：

text

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

常规流程中请勿直接调用图像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/

目录或编写辅助脚本填充行输出来标记视觉任务完成。请使用

record_imagegen_result.py

处理选定的内置

$imagegen

输出，或仅在文档记录的二级回退场景下使用

generate_pet_images.py

。确定性脚本仅可处理已生成的视觉输出。

仅基础任务可仅使用提示词生成。通过

$imagegen

生成的每个行条带任务必须使用

imagegen-jobs.json

中列出的输入图像，包括基础任务完成后创建的标准基础参考图。任何未附加基础图像的行生成均视为无效。

Codex Digital Pet Style

Codex数字宠物风格

Default pet art should match the Codex app's built-in digital pets: small pixel-art-adjacent mascots with compact chibi proportions, chunky readable silhouettes, thick dark 1-2 px outlines, visible stepped/pixel edges, limited palettes, flat cel shading, simple expressive faces, and tiny limbs. Even if the reference art is more detailed, complex or realistic, the generated pet should be simplified into this style.

Do NOT generate polished illustration, painterly rendering, anime key art, 3D rendering, glossy app-icon treatment, realistic fur or material texture, soft gradients, high-detail antialiasing, and complex tiny accessories. References that are more detailed than this should be simplified into the house style before row generation.

默认宠物原画应匹配Codex应用的内置数字宠物风格：小型像素艺术风格的吉祥物，具有紧凑的Q版比例、清晰易读的粗轮廓、1-2像素的深色粗线条、可见的阶梯/像素边缘、有限的调色板、平涂赛璐珞阴影、简单生动的面部表情和小巧的四肢。即使参考素材更精细、复杂或写实，生成的宠物也应简化为该风格。

请勿生成精致插画、绘画风格渲染、动漫关键帧、3D渲染、光泽应用图标效果、写实毛发或材质纹理、柔和渐变、高细节抗锯齿以及复杂的小配饰。比该风格更精细的参考素材应在生成行条带前简化为官方风格。

Transparency And Effects

透明度与特效

Pet rows are processed into transparent 192x208 cells, so every generated pixel must either belong to the pet sprite or be cleanly removable chroma-key background. Prefer pose, expression, and silhouette changes over decorative effects.

Allowed effects must satisfy all of these conditions:

The effect is state-relevant and helps explain the animation.
The effect is physically attached to, touching, or overlapping the pet silhouette, not floating nearby.
The effect is inside the same frame slot as the pet and does not create a separate sprite component.
The effect is opaque, hard-edged, pixel-style, and uses non-chroma-key colors.
The effect is small enough to remain readable at 192x208 without clutter.

Examples of allowed effects: a tear touching the face, a small smoke puff touching the box or head, or tiny stars overlapping the pet during a failed/dizzy reaction.

Avoid these by default because they usually break transparent-background cleanup or component extraction:

wave marks, motion arcs, speed lines, action streaks, afterimages, blur, or smears
detached stars, loose sparkles, floating punctuation, floating icons, falling tear drops, separated smoke clouds, or loose dust
cast shadows, contact shadows, drop shadows, oval floor shadows, floor patches, landing marks, impact bursts, glow, halo, aura, or soft transparent effects
text, labels, frame numbers, visible grids, guide marks, speech bubbles, thought bubbles, UI panels, code snippets, checkerboard transparency, white backgrounds, black backgrounds, or scenery
chroma-key-adjacent colors in the pet, prop, effects, highlights, or shadows
stray pixels, disconnected outline bits, speckle/noise, cropped body parts, overlapping poses, or any pose that crosses into a neighboring frame slot

State-specific guidance:

```
waving
```
: show the wave through paw pose only. Do not draw wave marks, motion arcs, lines, sparkles, or symbols around the paw.
```
jumping
```
: show vertical motion through body position only. Do not draw shadows, dust, landing marks, impact bursts, bounce pads, or floor cues.
```
failed
```
: tears, attached smoke puffs, or attached stars are allowed if they obey the allowed-effects rules; do not use red X marks, floating symbols, detached smoke, detached stars, or separate tear droplets.
```
review
```
: show focus through lean, blink, eyes, head tilt, or paw position. Do not add magnifying glasses, papers, code, UI, punctuation, or symbols unless that prop already exists in the base pet identity.
```
running-right
```
,
```
running-left
```
, and
```
running
```
: show locomotion through body, limb, and prop movement only. Do not draw speed lines, dust clouds, floor shadows, or motion trails.

宠物行将被处理为192x208像素的透明单元格，因此每个生成的像素要么属于宠物精灵，要么是可干净移除的绿幕背景。优先通过姿势、表情和轮廓变化来表现，而非装饰性特效。

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

特效与状态相关，有助于解释动画含义
特效附着于、接触或重叠宠物轮廓，而非悬浮在附近
特效与宠物位于同一帧插槽内，不创建单独的精灵组件
特效为不透明、硬边缘、像素风格，且使用非绿幕颜色
特效足够小，在192x208分辨率下保持清晰且不杂乱

允许的特效示例：触碰脸部的眼泪、触碰身体或头部的小烟团、失败/眩晕反应时与宠物重叠的小星星。

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

波浪标记、运动弧线、速度线、动作条纹、残影、模糊或涂抹效果
分离的星星、散落的火花、悬浮标点、悬浮图标、掉落的泪珠、分离的烟团或散落的灰尘
投射阴影、接触阴影、下拉阴影、椭圆形地面阴影、地面斑块、着陆痕迹、冲击爆发、光晕、光环或柔和透明效果
文字、标签、帧编号、可见网格、引导标记、对话气泡、思考气泡、UI面板、代码片段、棋盘格透明、白色背景、黑色背景或场景元素
宠物、道具、特效、高光或阴影中与绿幕颜色相近的颜色
stray像素、断开的轮廓碎片、斑点/噪点、裁剪的身体部位、重叠姿势，或任何跨越相邻帧插槽的姿势

状态特定指南：

```
waving
```
：仅通过爪子姿势表现挥手，不要在爪子周围绘制波浪标记、运动弧线、线条、火花或符号
```
jumping
```
：仅通过身体位置表现垂直运动，不要绘制阴影、灰尘、着陆痕迹、冲击爆发、弹跳垫或地面提示
```
failed
```
：符合允许特效规则的眼泪、附着的烟团或附着的星星是允许的；请勿使用红色叉号、悬浮符号、分离的烟团、分离的星星或单独的泪珠
```
review
```
：通过倾斜身体、眨眼、眼神、头部倾斜或爪子位置表现专注，除非基础宠物形象中已有相关道具，否则不要添加放大镜、纸张、代码、UI、标点或符号
```
running-right
```
、
```
running-left
```
和
```
running
```
：仅通过身体、四肢和道具的移动表现运动，不要绘制速度线、灰尘云、地面阴影或运动轨迹

Pet Naming

宠物命名

Ask the user for a pet name when they have not provided one and only if the conversation naturally allows it. If asking would slow down a direct execution request, choose a short appropriate name from the pet concept, reference image, or personality, then use that name consistently as the display name and as the source for the package folder slug.

Good built-in style examples:

Codex - The original Codex companion.
Dewey - A tidy duck for calm workspace days.
Fireball - Hot path energy for fast iteration.
Rocky - A steady rock when the diff gets large.
Seedy - Small green shoots for new ideas.
Stacky - A balanced stack for deep work.
BSOD - A tiny blue-screen gremlin.
Null Signal - Quiet signal from the void.

当用户未提供宠物名称且对话场景自然时，可询问用户。若询问会直接影响执行请求的进度，则从宠物概念、参考图像或个性中选择一个简短合适的名称，并将其作为显示名称和包文件夹slug的来源统一使用。

优秀的内置风格示例：

Codex - 最初的Codex伙伴
Dewey - 适合平静工作环境的整洁鸭子
Fireball - 用于快速迭代的热路径能量体
Rocky - 应对大量差异时的稳定岩石
Seedy - 代表新想法的小绿芽
Stacky - 适合深度工作的平衡堆叠体
BSOD - 小型蓝屏小妖精
Null Signal - 来自虚空的安静信号

Visible Progress Plan

可见进度计划

For every pet run, keep a visible checklist so the user can see where the work is up to. Create the checklist before starting, keep one step active at a time, and update it as each step finishes.

Before creating the checklist, establish the pet name when possible. Use the user-provided name when available; otherwise infer a short appropriate name from the concept or references. If the name is too long, not settled, or not appropriate for a friendly checklist, use

your pet

instead.

Use this checklist for a normal pet run, replacing

<Pet>

with the pet's name or

your pet

Getting
```
<Pet>
```
ready.
Imagining
```
<Pet>
```
's main look.
Picturing
```
<Pet>
```
's poses.
Hatching
```
<Pet>
```
.

What each step means:

```
Getting <Pet> ready.
```
Choose or confirm the pet name, description, source images, and working folder.
```
Imagining <Pet>'s main look.
```
Generate the pet's main reference image. This is required for new pets, even when the user does not provide an image, because it becomes the visual source of truth.
```
Picturing <Pet>'s poses.
```
Create the pose rows, starting with
```
idle
```
and
```
running-right
```
to confirm the pet still looks consistent. Only mirror
```
running-left
```
if
```
running-right
```
clearly works when flipped.
```
Hatching <Pet>.
```
Turn the approved poses into the final pet files, review the contact sheet, previews, and validation results, fix any broken parts, save
```
pet.json
```
and
```
spritesheet.webp
```
into the pet folder, then tell the user where the pet and QA files were saved.

Only mark a step complete when the real file, image, or decision exists. If this is just a repair run, start from the first relevant step instead of restarting the whole checklist.

每次宠物生成运行时，保持可见的检查清单，让用户了解工作进度。开始前创建检查清单，一次仅激活一个步骤，并在每个步骤完成后更新。

创建检查清单前，尽可能确定宠物名称。优先使用用户提供的名称；否则从概念设计或参考素材中推断一个简短合适的名称。若名称过长、未确定或不适合友好的检查清单，则使用

your pet

替代。

常规宠物生成运行使用以下检查清单，将

<Pet>

替换为宠物名称或

your pet

：

准备
```
<Pet>
```
。
构思
```
<Pet>
```
的主形象。
设计
```
<Pet>
```
的姿势。
孵化
```
<Pet>
```
。

各步骤含义：

```
准备<Pet>
```
：选择或确认宠物名称、描述、源图像和工作文件夹。
```
构思<Pet>的主形象
```
：生成宠物的主参考图像。这是新宠物的必填项，即使用户未提供图像，因为它将成为视觉事实来源。
```
设计<Pet>的姿势
```
：创建姿势行，从
```
idle
```
和
```
running-right
```
开始，确认宠物形象保持一致。仅当
```
running-right
```
翻转后效果明显合适时，才镜像生成
```
running-left
```
。
```
孵化<Pet>
```
：将已批准的姿势转换为最终宠物文件，检查联系表、预览和验证结果，修复任何损坏部分，将
```
pet.json
```
和
```
spritesheet.webp
```
保存到宠物文件夹，然后告知用户宠物和QA文件的保存位置。

仅当实际文件、图像或决策已存在时，才标记步骤完成。若为修复运行，则从第一个相关步骤开始，而非重新启动整个检查清单。

Default Workflow

默认工作流

Prepare a pet run folder and imagegen job manifest:

bash

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

All arguments above are optional except any flags needed to express user constraints. For text-only requests, pass the concept through

--pet-notes

and omit

--reference

;

prepare_pet_run.py

will infer a name, description, chroma key, and output directory as needed.

Inspect the next ready
```
$imagegen
```
jobs:

bash

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

For each ready job, invoke
```
$imagegen
```
with:

the prompt file listed in
```
imagegen-jobs.json
```
every input image listed for the job, with its role label
the default built-in
```
image_gen
```
path unless
```
$imagegen
```
itself routes otherwise

The base job must complete first. If user references exist, the base job uses them. If no references exist, the base job may be prompt-only. After recording the base,

record_imagegen_result.py

writes

decoded/base.png

and

references/canonical-base.png

; all row jobs use the original references if present plus those canonical base images.

prepare_pet_run.py

also creates 9 row-specific layout guide images under

references/layout-guides/

, one per animation state. Row jobs attach the matching guide as a layout-only input so the model can follow the correct frame count, spacing, centering, and safe padding. Treat these guides as invisible construction references: the generated row strip must not include visible boxes, borders, center marks, labels, guide colors, or the guide background.

When generating row strips, keep the identity lock in the row prompt authoritative: do not redesign the pet, and preserve the same head shape, face, markings, palette, prop, outline weight, body proportions, and silhouette. A row that looks like a related but different pet is failed even if the deterministic geometry QA passes.

Generate and record

running-right

before deciding how to complete

running-left

. Inspect

running-right

against the base and references. If the pet is visually symmetric enough that a horizontal mirror preserves identity, prop placement, handedness, markings, lighting, text-free details, and direction semantics, derive

running-left

with:

bash

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>"

If there is any asymmetric side-specific marking, readable text, non-mirrored logo, handed prop, one-sided accessory, lighting cue, or direction-specific pose that would become wrong when flipped, do not mirror. Generate

running-left

with

$imagegen

using its row prompt and all listed grounding images, including

decoded/running-right.png

as a gait reference.

For the built-in path, record the selected source image from

$CODEX_HOME/generated_images/.../ig_*.png

. Do not record files from the run directory,

tmp/

, hand-made fixtures, deterministic row folders, or post-processed copies as visual job sources.

After selecting a generated output for a job, ingest it:

bash

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

This copies the image to the exact decoded path expected by the deterministic pipeline and records source metadata in

imagegen-jobs.json

When all jobs are complete, finalize:

bash

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

Expected output:

text

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

Package output is written outside the run directory by default. If

CODEX_HOME

is set, use it; otherwise use

$HOME/.codex

text

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

Review

qa/contact-sheet.png

qa/review.json

final/validation.json

, and

qa/videos/

before accepting the pet.

Deterministic validation is necessary but not sufficient. Before calling the pet done, visually inspect the contact sheet for identity consistency. Block acceptance if any row changes species/body type, face, markings, palette, prop design, prop side unexpectedly, or overall silhouette.

准备宠物运行文件夹和imagegen任务清单：

bash

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

将根据需要推断名称、描述、绿幕颜色和输出目录。

检查下一个待处理的
```
$imagegen
```
任务：

bash

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

对每个待处理任务，调用
```
$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-left

之前，先生成并记录

running-right

。检查

running-right

与基础图像和参考素材是否一致。若宠物视觉上足够对称，水平镜像后能保持身份、道具位置、惯用手、标记、光照、无文本细节和方向语义，则通过以下命令生成

running-left

：

bash

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/

、手工制作的固定装置、确定性行文件夹或后处理副本的文件作为视觉任务源。

为任务选定生成输出后，导入该输出：

bash

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

中记录源元数据。

所有任务完成后，完成最终处理：

bash

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

预期输出：

text

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

。

text

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

在接受宠物之前，检查

qa/contact-sheet.png

、

qa/review.json

、

final/validation.json

和

qa/videos/

。

确定性验证是必要但不充分的。在标记宠物完成前，需视觉检查联系表以确认身份一致性。若任何行意外改变了物种/体型、面部、标记、调色板、道具设计、道具位置或整体轮廓，则拒绝接受。

Subagent Row Generation

子代理行生成

After the base job has been recorded and

references/canonical-base.png

exists, row-strip visual generation must use subagents unless the user explicitly says not to use subagents for this session. Before row generation, state that subagents are being used and which row jobs are being delegated. If subagents cannot be spawned because the current environment or tool policy blocks them, stop before row-strip generation, explain the blocker, and ask for explicit user direction before continuing sequentially.

The parent agent must own the manifest and package writes.

Default flow:

Parent runs
```
prepare_pet_run.py
```
.
Parent generates and records
```
base
```
.
Parent runs
```
pet_job_status.py
```
.
Parent spawns subagents for
```
idle
```
and
```
running-right
```
first as identity and gait checks.
Parent records the selected
```
idle
```
and
```
running-right
```
results returned by subagents.
Parent decides whether
```
running-left
```
is safe to derive by mirror; if not, parent treats it as a normal grounded row job delegated to a subagent.
Parent spawns subagents for every remaining non-derived row image-generation job.
Each subagent receives the row prompt and every listed input image path, invokes
```
$imagegen
```
, and returns only the selected
```
$CODEX_HOME/generated_images/.../ig_*.png
```
source path.
Parent alone runs
```
record_imagegen_result.py
```
,
```
derive_running_left_from_running_right.py
```
, repair queueing, finalization, QA, and packaging.

Subagent write boundary: do not let subagents edit

imagegen-jobs.json

, copy files into

decoded/

, run

record_imagegen_result.py

, run

derive_running_left_from_running_right.py

, run

finalize_pet_run.py

, or package the pet. This avoids manifest races and keeps provenance checks centralized.

Subagent handoff contract:

Give each subagent exactly one row job unless you are intentionally batching adjacent simple rows.
Include the row id, the absolute prompt file path, the full prompt text or an instruction to read that exact prompt file, and every input image path with its role label from
```
imagegen-jobs.json
```
.
Explicitly remind the subagent that the prompt's transparency and effects rules are mandatory: no detached effects, no wave marks for
```
waving
```
, no speed lines or dust for running rows, and only attached opaque sprite-like tears/smoke/stars when allowed by the state prompt.
Tell the subagent to inspect the generated candidate for frame count, identity consistency, clean flat chroma-key background, safe spacing, and forbidden detached effects before returning it.
Tell the subagent to return only the selected original
```
$CODEX_HOME/generated_images/.../ig_*.png
```
source path plus a one-sentence QA note. The parent decides whether to record or repair it.

Use this template for each subagent:

text

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>

No silent sequential fallback: if subagents cannot be used for row-strip visual generation, stop and ask for explicit user direction before continuing without them. Only an explicit user instruction such as "do not use subagents" or "run this sequentially" authorizes a normal sequential row-generation path. The final answer must report which row jobs were delegated to subagents and which, if any, were mirrored or repaired by the parent.

基础任务记录完成且

references/canonical-base.png

存在后，行条带视觉生成必须使用子代理，除非用户明确表示本次会话不使用子代理。行生成前，需说明将使用子代理以及哪些行任务将被委托。若当前环境或工具策略阻止生成子代理，则在行条带生成前停止操作，说明障碍，并在继续顺序执行前请求用户明确指示。

父代理必须负责清单和包的写入。

默认流程：

父代理运行
```
prepare_pet_run.py
```
。
父代理生成并记录
```
base
```
任务。
父代理运行
```
pet_job_status.py
```
。
父代理首先为
```
idle
```
和
```
running-right
```
生成子代理，作为身份和步态检查。
父代理记录子代理返回的选定
```
idle
```
和
```
running-right
```
结果。
父代理决定是否可安全通过镜像生成
```
running-left
```
；若不可，则将其视为正常的基础行任务委托给子代理。
父代理为所有剩余的非派生行图像生成任务生成子代理。
每个子代理接收行提示词和所有列出的输入图像路径，调用
```
$imagegen
```
，仅返回选定的
```
$CODEX_HOME/generated_images/.../ig_*.png
```
源路径。
仅父代理运行
```
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说明。父代理决定是否记录或修复该结果。

每个子代理使用以下模板：

text

为本次孵化宠物运行生成`<row-id>`行。

运行目录：<absolute run dir>
提示词文件：<absolute prompt file>
输入图像：
- <absolute path> — <role>
- <absolute path> — <role>

严格按照行提示词执行，包括透明度和伪影规则。仅使用`$imagegen`；请勿使用本地脚本绘制、平铺、编辑或合成精灵。

返回前，视觉检查：
- 符合要求的精确帧数
- 与标准基础图像一致的宠物身份
- 干净平整的绿幕背景
- 完整、分离、无裁剪的姿势
- 无禁止的分离特效或跨插槽伪影

请勿编辑清单、复制到decoded目录、记录结果、镜像行、完成最终处理、修复或打包。仅返回：
selected_source=/absolute/path/to/$CODEX_HOME/generated_images/.../ig_*.png
qa_note=<one sentence>

无静默顺序回退：若无法使用子代理进行行条带视觉生成，则停止操作并请求用户明确指示后再继续无代理顺序执行。只有用户明确指令（如“不要使用子代理”或“顺序执行”）才授权使用常规顺序行生成路径。最终结果必须报告哪些行任务委托给了子代理，以及哪些（若有）由父代理镜像或修复。

Repair Workflow

修复工作流

If finalization stops because row QA failed, queue targeted repair jobs:

bash

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

Then repeat the

$imagegen

generation and

record_imagegen_result.py

ingest loop for each reopened row job. Regenerate the smallest failing scope: the failed row, not the whole sheet.

For identity repairs, use the canonical base image, original references, contact sheet, and exact row failure note as grounding context. Repair only the failed row while preserving the canonical pet identity.

若最终处理因行QA失败而停止，则排队进行针对性修复任务：

bash

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

然后对每个重新打开的行任务重复

$imagegen

生成和

record_imagegen_result.py

导入循环。仅重新生成最小的失败范围：失败的行，而非整个精灵表。

对于身份修复，使用标准基础图像、原始参考素材、联系表和精确的行失败说明作为基础上下文。仅修复失败的行，同时保留标准宠物身份。

Secondary Image Generation Fallback

二级图像生成回退

scripts/generate_pet_images.py

is a secondary fallback for this skill.

Use it only when the installed

$imagegen

system skill is unavailable or cannot be invoked in the current environment. Normal pet creation should delegate visual generation to

$imagegen

, because

$imagegen

owns the built-in-first image generation policy and its own CLI fallback behavior.

Run the secondary fallback only after explaining why

$imagegen

cannot be used:

bash

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

The secondary fallback requires

OPENAI_API_KEY

scripts/generate_pet_images.py

是本技能的二级回退方案。

仅当已安装的

$imagegen

系统技能不可用或无法在当前环境中调用时，才使用该方案。常规宠物创建应将视觉生成委托给

$imagegen

，因为

$imagegen

拥有内置优先的图像生成策略及自身的CLI回退行为。

仅在说明

$imagegen

无法使用的原因后，才可运行二级回退：

bash

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

二级回退需要

OPENAI_API_KEY

。

Rules

规则

Keep
```
$imagegen
```
as the primary generation layer.
Keep reference images attached/visible for
```
$imagegen
```
whenever the chosen path supports references.
Attach the row's
```
references/layout-guides/<state>.png
```
image to every row-strip job as a layout-only guide, and do not accept outputs that copy guide pixels.
Use subagents for row-strip visual generation after the parent records the base image. The parent may generate the base, but row-strip jobs belong to subagents unless the user explicitly says not to use subagents for this session.
Generate every normal visual job with
```
$imagegen
```
: base plus all row strips that are not explicitly approved
```
running-left
```
mirror derivations.
Treat only the base job as eligible for prompt-only generation; every row job must attach its listed grounding images.
Delegate
```
running-right
```
first, then mirror
```
running-left
```
only when visual inspection confirms a mirror preserves identity and semantics; otherwise delegate
```
running-left
```
as a normal grounded
```
$imagegen
```
row.
Never substitute locally drawn, tiled, transformed, or code-generated row strips for missing
```
$imagegen
```
outputs.
Never manually mutate
```
imagegen-jobs.json
```
to claim a visual job completed.
Do not rely on generated images for exact atlas geometry; use this skill's deterministic scripts.
Use the chroma key stored in
```
pet_request.json
```
; do not force a fixed green screen.
Keep the pet's silhouette, face, materials, palette, and props consistent across all rows.
Enforce the transparency and effects rules above in every base, row, and repair prompt.
Treat visual identity drift as a blocker even when
```
qa/review.json
```
and
```
final/validation.json
```
have no errors.
Treat a contact sheet that shows cropped references, repeated tiles, white cell backgrounds, or non-sprite fragments as failed.
Treat forbidden detached effects, chroma-key-adjacent artifacts, shadows, glows, smears, dust, landing marks, wave marks, speed lines, or motion trails as failed rows.
Treat
```
qa/review.json
```
errors as blockers. Warnings require visual review.

将
```
$imagegen
```
作为主要生成层。
只要所选路径支持参考图像，就保持参考图像附加/可见给
```
$imagegen
```
。
为每个行条带任务附加该行的
```
references/layout-guides/<state>.png
```
图像作为仅布局引导，且不接受复制引导像素的输出。
父代理记录基础图像后，使用子代理进行行条带视觉生成。父代理可生成基础图像，但行条带任务属于子代理，除非用户明确表示本次会话不使用子代理。
所有常规视觉任务均使用
```
$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
```
中的错误视为障碍。警告需要视觉检查。

Acceptance Criteria

验收标准

Final atlas is PNG or WebP,
```
1536x1872
```
, transparent-capable, and based on
```
192x208
```
cells.
Used cells are non-empty and unused cells are fully transparent.
Atlas follows the row/frame counts in
```
references/animation-rows.md
```
.
Contact sheet and preview videos have been produced unless explicitly skipped.
```
qa/review.json
```
has no errors.
Row-by-row review confirms the animation cycles are complete enough for the Codex app.

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

and

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

are staged together for custom pets.

最终图集为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