hatch-pet

Hatch Pet

概述

根据创意概念、品牌视觉元素、公司/潜在客户名称、一张或多张参考图（或上述任意组合输入），创建兼容 Codex 的动态桌面宠物。该工作流一方面保留了 hatch-pet 在图集几何结构、校验、视觉 QA 和打包方面的确定性流水线，另一方面采用精炼且针对特定状态的 Prompt 提示词，并支持任何符合宠物安全规范的视觉风格。

用户端输入均为可选。如果用户未指定宠物名称，可根据创意概念、品牌、公司或参考图片文件名进行推导；若无法推导，则选择一个短小亲切的名字。如果用户未提供描述，可从概念或参考图中提炼。如果用户未提供参考图，先根据文本生成基础宠物图（Base Pet），再将该基础图作为后续每一行动画列的标准参考基准（Canonical Reference）。

图像生成委派

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

在生成基础原画（Base Art）、行精灵条（Row Strip）或修复行之前，必须先加载并遵循已安装的图像生成 Skill：

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

请勿直接调用 Image API、图像 CLI 或任何其他图像生成途径。应当让 $imagegen 自行决定优先内置路径及降级兜底规则。如果 $imagegen 提示某种降级方案需要确认，请先询问用户再继续。

调用 $imagegen 时，请将生成的宠物 Prompt 作为权威视觉规范传入。宠物 Prompt 应保持简短精炼、聚焦特定状态、面向精灵图生产，并严格基于列出的输入参考图。长篇的策略与 QA 规则应留在本 Skill 和确定性审查脚本中，切勿将其硬套展开到每一个图像 Prompt 里面。也不要把 Prompt 包裹进通用的 $imagegen 共享 Prompt Schema 中。

本 Skill 内置的脚本仅用于确定性的图像处理工作：准备布局指南与 Prompt、镜像经审核通过的 running-left（向左跑）、提取单帧、校验行有效性、拼合最终图集，以及生成 Contact Sheet（对照表）与动态预览等 QA 媒体文件。主 Agent（Parent）负责的 Shell/jq 步骤则用于处理 Manifest 清单更新、打包与清理工作。

存储管控

内置的 $imagegen 路径会将生成的 PNG 字节写入调用它的 Rollout 记录中，即使它同时会在 ${CODEX_HOME:-$HOME/.codex}/generated_images 下保存文件。后续删除文件虽能节省文件系统空间，但无法缩减已写入的 Rollout 体积。因此，必须保持图像生成的隔离与受控：

• 每个视觉生成任务使用单独的轻量 Worker。切勿把多个基础图/行任务批量塞给同一个 Worker。
• Worker 最终回复中只能返回 selected_source=... 与 qa_note=...；绝对不能包含 Markdown 图片预览、Base64 编码或额外的视觉附件。
• 主 Agent（Parent）切勿以视觉方式逐一打开生成的 PNG 文件。每个任务依靠 Worker 进行 QA，主 Agent 仅需检查最终生成的 Contact Sheet 对照图。
• 将选中的生成结果复制到 decoded/ 目录后，如果原始文件保存在 ${CODEX_HOME:-$HOME/.codex}/generated_images 中，请将其删除，并尽可能清理已空出的生成目录。
• 对于存储敏感的全量运行任务，若存在可用条件，可询问用户是否切换到 $imagegen CLI 降级路径。该路径虽然需要本地 API 凭据并需用户显式确认，但能避免将内置图像 Data Payload 直接嵌进 Rollout 事件中。

品牌调研挖掘

如果用户只提供了品牌、公司、产品或意向客户名称，而没有给具体的形象描述或参考图，请在准备宠物任务前先运行一个轻量级的调研挖掘（Discovery）子 Agent。调研 Worker 必须通过网络搜索获取信息，且优先使用官方渠道（如品牌官网、产品页、文档、关于页、新闻发布页或品牌指南页）。只有当官方页面信息过于单薄时，才参考可靠的二手来源。搜索范围要精准收敛：只需提取出视觉风格和个性线索即可，无需写成一份市场调研报告。

如果用户已经提供了具体的吉祥物/形象描述或参考图，除非用户明确要求进行品牌研究，否则跳过调研步骤。

调研 Worker 的主要职责：

• 在网上搜索 2~4 个相关数据源，优先采用官方页面
• 撰写一份自适应的 Markdown 简报，而不是机械地罗列字段
• 覆盖身份/品类、受众/使用场景、视觉系统、性格/基调、产品/领域元素、吉祥物转化线索、避雷禁忌（Avoidances）以及依据/置信度
• 对于从资料中推断出的吉祥物建议，需明确标注为“推断”
• 严禁复制 Logo、可读标识、UI 截图、标语或文本文字
• 结尾必须附带一个简短的 Generation handoff 交付章节，且仅包含 brand_name、brand_brief``avatar_seed``avoid 和 brand_sources 字段
• 不得在此阶段生成图像、创建运行文件夹或修改无关文件

使用如下调研 Worker 的 Prompt：

Research a brand for hatch-pet mascot creation.

Brand/product/prospect: <brand name>
User context: <short user request>
Output file: <absolute path to brand-discovery.md>

Use web search. Prefer official brand, product, docs, about, press, or brand pages. Use reputable secondary sources only if official sources are too thin. Write an adaptive markdown brief to the output file. Headings may flex by brand, but the brief must cover:
- identity/category: canonical name, product type, what it does
- audience/use context: who it serves and where it appears
- visual system: palette, shapes, line quality, materials, typography feel, iconography, patterns
- personality/tone: emotional traits, energy, formality, playfulness
- product/domain motifs: objects, workflows, verbs, metaphors, environments
- mascot translation cues: candidate forms, signature traits, props, what must read at pet size
- avoidances: logos/text, trademark-sensitive elements, misleading cues, competitor confusion, poor mascot fits
- evidence/confidence: source URLs plus notes where evidence is weak or inferred

Do not copy logos, readable marks, UI screenshots, slogans, or text. Clearly label mascot guidance that is inferred rather than directly sourced.

End the brief with a `Generation handoff` section containing exactly:
- brand_name=<canonical brand/product name>
- brand_brief=<one sentence, max 45 words, covering palette/tone/domain motifs/personality>
- avatar_seed=<short mascot-safe visual idea, no logo copying>
- avoid=<short comma-separated list>
- brand_sources=<comma-separated source URLs>

Return exactly:
brand_discovery_file=<absolute output file path>
brand_name=<canonical brand/product name>
brand_brief=<same compact sentence from Generation handoff>
avatar_seed=<same short seed from Generation handoff>
avoid=<same short avoid list from Generation handoff>
brand_sources=<same comma-separated URLs from Generation handoff>

主 Agent 应当在准备运行任务前保存该 Markdown 简报，随后将其作为 --brand-discovery-file 参数传递给 prepare_pet_run.py，同时附带 --brand-name、--brand-brief、多次重复的 --brand-source 参数；若用户未提供更好的形象描述，还要根据 avatar_seed 提取精炼的 --pet-notes 值。完整的简报保留用于人工复核，最终仅依靠简短的交接字段来塑造图像 Prompt。若无法使用网络搜索且用户仅给出了纯品牌名称，请在生成前先向用户询问品牌特征线索。

在正常的宠物生成流程中，预计最多包含 10 个视觉生成任务：1 个基础宠物任务 + 9 个动画行任务。目前 Codex 应用协议完整使用了全部 9 种状态：idle（待机）、running-right（向右跑）、running-left（向左跑）、waving（挥手）、jumping（跳跃）、failed（失败）、waiting（等待）、running（奔跑）和 review（审核）。其中唯一支持确定性视觉衍生的是 running-left——只有在 running-right 生成完成、通过视觉检查并被明确批准安全可镜像后，才能通过镜像翻转 running-right 来生成。若不适合镜像，则将 running-left 作为普通的基准参考 $imagegen 动画行来进行生成。

选定视觉生成结果后，主 Agent 会将该图像精准复制到对应任务的 decoded/ 路径下，并在 imagegen-jobs.json 中标记任务完成。切勿编写自定义脚本去强行填充行输出，内置的确定性 Python 脚本只能用于处理已经生成的视觉产物。

只有基础任务（Base Job）可以仅凭 Prompt 生成。通过 $imagegen 生成的每一个动画行任务，都必须附带 imagegen-jobs.json 中列出的输入参考图（包含复制选定基础输出后创建的标准 Base 参考图）。任何未附带基准参考图的动画行生成均视为无效。

符合宠物安全规范的视觉风格

默认风格为 auto：即根据用户的 Prompt 和参考图自动推导宠物的画风，并在每一行动画中保持该风格的一致性。如果用户指定了风格，须严格遵循。支持的预设风格包括：pixel（像素）、plush（毛绒）、clay（黏土）、sticker（贴纸）、flat-vector（扁平矢量）、3d-toy（3D 玩具）、painterly（手绘/油画）、brand-inspired（品牌灵感）以及 auto（自动）。

只要满足“宠物安全”标准，任何画风均可接受：

• 全身剪影紧凑，在 192x208 的网格单元内清晰可辨
• 所有行中的五官、比例、材质、配色和道具保持高度一致
• 背景为干净可剔除的色键（Chroma-key）纯色背景
• 局部细节足够大，能在宠物缩放尺寸下清晰识别
• 严禁包含文字、标签、UI 或可读 Logo（除非用户明确提供了经过授权的参考原画并要求添加）

非像素风格同样是一等公民。只要满足图集规范与清晰度约束，毛绒、黏土、贴纸、矢量、3D 玩具、手绘吉祥物、水墨及品牌灵感等外观均应被正常采纳。

透明度与特效处理

宠物动画行最终会被切分为透明的 192x208 像素单元，因此生成的每一个像素要么属于宠物精灵本身，要么属于能被干净扣除的色键纯色背景。相比装饰性特效，应优先通过姿态、表情和剪影变化来展现动态。

确定性光栅流水线负责保障“透明度一致性”约束：变为完全透明的像素会被规范化重置，确保不会残留隐藏的 RGB 边缘杂色；若导出的文件违反该约束，图集校验必须报错拦截。绝不能靠妥协接纳视觉不一致的产物来掩盖彩色光晕或透明像素残留问题。

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

• 特效与当前状态密切相关，有助于解释动画意图。
• 特效必须物理依附、接触或覆盖在宠物剪影上，不得悬浮在旁边。
• 特效必须位于宠物的同一单帧网格内，不得形成独立的精灵组件。
• 特效必须是不透明且边缘硬朗的，以便干净提取，且不得使用与色键背景冲突的颜色。
• 特效体积要足够小，确保在 192x208 尺寸下清晰可见而不显得杂乱。

默认情况下应避免以下情况，因为它们通常会破坏透明背景的扣图或组件提取：

• 动态波浪线、运动弧线、速度线、动作尾迹、残影、模糊或抹痕
• 游离的星星、散落闪光、悬浮标点、悬浮图标、掉落的眼泪、分离的烟雾团或散落的尘埃
• 投影、接触阴影、落体阴影、椭圆地面阴影、地面贴图、落地点标记、冲击波、光晕、光环、气场或软透明特效
• 文字、标签、帧编号、可见网格线、参考线、对话框、心理活动泡泡、UI 面板、代码片段、棋盘格透明背景、纯白背景、纯黑背景或场景布景
• 宠物、道具、特效、高光或阴影中使用了与色键背景色相近的颜色
• 孤立像素、断裂的轮廓碎片、噪点/斑点、被裁切的身体部位、重叠的姿态，或任何跨越到邻近帧网格的姿态

特定状态说明指南：

• idle：保持安静且低干扰。仅使用细微的呼吸、轻微眨眼或微小动作。

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