hatch-pet

Hatch Pet

概覽

無論是概念想法、品牌意象、公司/潛在客戶名稱、一張或多張參考圖片，或是上述任何組合，都能用來建立相容於 Codex 的動態寵物。此工作流程保留了 hatch-pet 確定性管線中關於圖集幾何構造（atlas geometry）、驗證、視覺 QA 及打包的處理機制，同時採用簡潔且針對特定狀態的 Prompt，並支援任何符合「寵物安全規範」的視覺風格。

使用者輸入的各項參數皆為選填。若使用者未提供寵物名稱，可從概念、品牌、公司或參考圖片檔名推導出適當名稱；若無法推導，請選擇一個簡短友善的名稱。若未提供描述，則從概念或參考圖中推斷。若未提供參考圖片，請先透過純文字生成基礎寵物圖像（base pet），並以此基礎圖像作為後續每個動畫動作橫排（row）的標準參考基準。

生成委派

所有常規的視覺生成工作皆應使用 $imagegen。

在生成基礎美術圖（base art）、動作橫排條（row strips）或修復橫排之前，請先載入並遵循已安裝的圖像生成 Skill：

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

切勿直接呼叫 Image API、圖像 CLI 或任何其他圖像生成管道。請讓 $imagegen 自行決定其內建優先機制與備援（fallback）規則。若 $imagegen 提示備援方案需要確認，請先詢問使用者再繼續。

呼叫 $imagegen 時，請將生成的寵物 Prompt 作為權威性的視覺規格說明。寵物 Prompt 應保持簡潔、針對特定狀態、以精靈圖製作為導向，並基於所列出的輸入圖片。較長且複雜的規範與 QA 規則應保留在本 Skill 及確定性審查腳本中，而非硬塞進每個圖像 Prompt 裡。請勿將 Prompt 包裹在通用的 $imagegen 共用 Prompt 結構中。

僅在進行確定性圖像處理時使用本 Skill 的腳本：準備版面指南與 Prompt、鏡射已核可的 running-left、擷取影格、驗證動作橫排、合成最終圖集，以及建立對照表（contact-sheet）與動態預覽 QA 媒體。主流程的 Shell/jq 步驟則負責處理 Manifest 更新、打包及清理工作。

儲存容量控制

內建的 $imagegen 路徑即便將檔案寫入 ${CODEX_HOME:-$HOME/.codex}/generated_images 下，也會將生成的 PNG 位元組存在呼叫它的 rollout 中。日後刪除檔案雖然能減少檔案系統容量，但無法縮減已經寫入的 rollout 體積。因此圖像生成過程必須保持獨立與受控：

• 每個視覺任務使用單一輕量生成 worker，切勿將多個基礎/動作橫排任務打包交給同一個 worker。
• Worker 的最終回應僅能回傳 selected_source=... 與 qa_note=...；不得包含 Markdown 圖片預覽、base64 或額外的視覺附件。
• 主 Agent（parent）不必親自開啟檢視每一張生成的 PNG。請利用 worker 對各任務進行 QA，並僅檢查最終的對照圖（contact sheet）。
• 將選定的生成結果複製到 decoded/ 後，若原圖存放在 ${CODEX_HOME:-$HOME/.codex}/generated_images 中，請將其從該處刪除，並在可能的情況下清理空出來的生成目錄。
• 針對空間敏感的全量執行任務，若可使用 $imagegen CLI 備援方案，請詢問使用者是否切換。該管道雖然需要本機 API 金鑰與使用者明確確認，但能避免內建圖片資料嵌入到 rollout 事件中。

品牌探索

若使用者提供的是品牌、公司、產品或潛在客戶名稱，而非具體的頭像描述或參考圖片，請在準備寵物執行任務之前，先執行輕量級的探索 subagent。探索 worker 必須使用網路搜尋，並優先參考官方來源，例如品牌官網、產品頁面、文件、關於我們頁面、新聞稿頁面或品牌識別頁面。僅在官方頁面資訊過於單薄時，才使用具公信力的二次來源。搜尋範圍應保持精準：足以擷取視覺與性格特徵即可，無需撰寫完整的市場研究報告。

當使用者已經提供具體的吉祥物/頭像描述或參考圖片時，除非使用者明確要求進行品牌研究，否則請跳過品牌探索。

探索 Worker 的職責：

• 在網路上搜尋 2-4 個相關來源，優先選擇官方頁面
• 撰寫具適應性的 Markdown 簡報，而非硬性填寫固定的欄位資料
• 涵蓋身份/類別、受眾/使用場景、視覺系統、性格/基調、產品/領域意象、吉祥物轉化提示、應避免事項以及證據/信心度
• 將從來源推斷出的吉祥物指導原則明確標示為推斷
• 避免複製 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 簡報，接著將其傳遞給 prepare_pet_run.py 作為 --brand-discovery-file，並附帶 --brand-name、--brand-brief、重複的 --brand-source，以及在使用者未提供更佳頭像描述時，根據 avatar_seed 帶入簡潔的 --pet-notes 數值。完整的簡報供複查使用；僅需將精簡交接欄位用於構建 Prompt。若無法使用網路搜尋且使用者僅提供空泛的品牌名稱，請在生成前先詢問品牌視覺特徵。

標準的寵物生成流程最多包含 10 個視覺生成任務：1 個基礎寵物（base pet）加上 9 個動作橫排任務（row-strip jobs）。目前 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 中列出的輸入圖片（包含選定基礎輸出複製後所建立的標準基礎參考圖）。任何未附帶參考對照圖片的橫排生成皆視為無效。

符合寵物安全規範的風格

預設風格為 auto：從使用者的 Prompt 與參考圖推斷寵物的風格，並在所有動作橫排中保持該風格。若使用者指定了特定風格，請照辦。支援的風格預設集包含 pixel、plush、clay、sticker、flat-vector、3d-toy、painterly、brand-inspired 及 auto。

只要符合寵物安全規範，任何風格皆可接受：

• 整體剪影精巧緊湊，能在 192x208 網格中清晰辨識
• 所有橫排中的臉部、比例、材質、配色與道具保持一致
• 背景為乾淨且易於去除的去背色（chroma-key background）
• 細節足夠大，能在寵物尺寸下清晰閱讀
• 不含文字、標籤、UI 或可辨識的 Logo（除非使用者明確提供經授權的參考美術圖並指定要求）

非像素風格同樣屬於一等公民。絨毛玩偶、黏土、貼紙、向量圖、3D 玩具、手繪吉祥物、水墨及品牌啟發風格，只要滿足圖集與可讀性限制，皆應予以接受。

透明度與特效

寵物橫排會被處理成透明的 192x208 網格，因此生成的每個像素都必須屬於寵物精靈本身，或是能乾淨去除的去背背景。優先採用姿勢、表情與剪影的變化，而非裝飾性特效。

程序化點陣圖管線負責維護透明度不變性（transparency invariant）：完全透明的像素都會經過正規化，確保不會殘留隱藏的 RGB 餘色，若導出的檔案違反該不變性，圖集驗證必須判定失敗。切勿接受視覺上不一致的輸出，進而掩蓋彩色光暈或透明像素殘留的問題。

允許的特效必須同時滿足以下所有條件：

• 特效與狀態相關，且有助於解釋動畫動作。
• 特效在物理上附著於、接觸到或重疊在寵物的剪影上，而非懸浮在附近。
• 特效位於與寵物相同的影格插槽（frame slot）內，不會產生獨立的精靈圖組件。
• 特效為不透明，邊緣足夠清晰利於乾淨擷取，且使用的顏色非去背背景色。
• 特效體積足夠小，在 192x208 尺寸下依然清晰可讀且不顯雜亂。

預設應避免以下情況，因為它們通常會破壞透明背景清理或組裝擷取：

• 聲波痕跡、運動弧線、速度線、動作軌跡、殘影、模糊或塗抹感
• 分離的星星、零散的火花、懸浮的標點符號、懸浮的圖示、掉落的眼淚、分離的煙霧或散落的灰塵
• 投射陰影、接觸陰影、落影、橢圓形地面陰影、地面區塊、著陸痕跡、衝擊爆裂、光暈、輪廓光、氣場或柔和的半透明效果
• 文字、標籤、影格編號、可見網格、輔助線痕跡、對話框、思考氣泡、UI 面板、程式碼片段、棋盤格透明背景、純白背景、純黑背景或背景道具景色
• 在寵物、道具、特效、高光或陰影中出現與去背色相近的顏色
• 雜點像素、斷開的輪廓碎片、斑點/雜訊、裁切到的身體部位、重疊姿勢，或任何超出相鄰影格插槽邊界的姿勢

針對特定狀態的指導原則：

• idle：保持平靜且不令人分心。僅使用微幅呼吸、輕微眨眼、小