hatch-pet

Hatch Pet

Open Design 整合。 這是未經修改的 Codex hatch-pet skill，
以 vendor 形式收錄於 skills/hatch-pet/ 之下，讓任何 Open Design agent 都能直接執行。在
skill 完成打包後，產生的 spritesheet.webp（部位於
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/）可透過
Settings → Pets → Import Codex sprite 匯入至桌面懸浮寵物小工具中。
匯入流程會自動偵測 8×9 / 192×208 的 atlas，並讓使用者選擇要播放哪一行動畫（idle、running-right、waving……）。

概觀（Overview）

從概念構想、一張或多張參考圖片（或兩者皆有），建立相容於 Codex 的動態寵物。本 skill 負責寵物專屬的提示詞規劃、動畫行数、影格擷取、atlas 幾何結構、QA、預覽與打包。視覺生成的部分則委派給 $imagegen。

使用者的輸入皆為選填。若使用者未提供寵物名稱，可從概念或參考圖的檔名推斷；若無法推斷，請選擇一個簡短合適的名稱。若使用者未提供描述，可從概念或參考圖推斷。若使用者未提供參考圖片，請先從文字生成基礎寵物，再將該基礎圖作為每一行動畫的權威參考圖。

委派生成（Generation Delegation）

一般視覺生成作業請一律使用 $imagegen。

在生成基礎美術圖、動畫行（row strips）或修復行之前，請先載入並遵守已安裝的圖像生成 skill：

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

在正常流程中，請勿直接呼叫 Image API。讓 $imagegen 自行選擇內建優先路徑及其 CLI 備用規則。若 $imagegen 表示備用路徑需要確認，請在繼續之前先詢問使用者。

當從本 skill 調用 $imagegen 時，請傳送生成的寵物提示詞作為權威視覺規格。請勿將其包裝在通用的 $imagegen 共用提示詞結構中，也不要加上額外的修飾、主視覺（hero-art）、照片、產品或插畫風格等增強描述。寵物提示詞應保持簡潔、針對精靈圖，並以電子寵物為導向；僅需為輸入影像加上角色標籤以及必要的用戶約束條件。

本 skill 的腳本僅用於確定性（deterministic）工作：準備提示詞與清單（manifests）、導入選定的 $imagegen 輸出、擷取影格、驗證動畫行、組裝最終 atlas、建立 QA 媒體以及打包。

硬性界限：切勿使用本地 Python/Pillow 腳本、SVG、canvas、HTML/CSS 或其他程式原生美術來替代 $imagegen 以建立、繪製、平鋪、扭曲、鏡像或合成寵物視覺效果。對於正常的寵物建立流程，預計最多有 10 個視覺生成任務：1 個基礎寵物加上 9 個動畫行任務。唯一的例外是 running-left，只有在 running-right 生成完成、經過視覺檢視且明確確認安全可鏡像後，才能透過鏡像 running-right 來衍生。若不適合鏡像，請將 running-left 作為正常的實體基準 $imagegen 動畫行來生成。若這些 API 調用費用太高、受阻或無法使用，請停止並說明阻礙原因，而不要在本地虛構生成動畫行。

請勿透過編輯 imagegen-jobs.json、複製檔案到 decoded/ 或編寫輔助腳本填入動畫行輸出的方式將視覺任務標記為完成。選定的內建 $imagegen 輸出請使用 record_imagegen_result.py，而 generate_pet_images.py 僅用於有紀錄的次要備用方案。確定性腳本只能處理已生成的視覺輸出。

只有基礎任務可以僅憑提示詞（prompt-only）。透過 $imagegen 生成的每個動畫行任務都必須使用 imagegen-jobs.json 中列出的輸入影像，包含在基礎任務記錄後建立的權威基礎參考圖。任何未附加基準影像的動畫行生成皆視為無效。

Codex 電子寵物風格（Codex Digital Pet Style）

預設的寵物美術應符合 Codex 應用程式的內建電子寵物風格：帶有 Q 版（chibi）比例的小型類像素風格吉祥物、厚重清晰的輪廓、粗暗的 1-2 px 邊框、清晰可見的階梯狀/像素邊緣、有限的調色盤、平面賽璐珞陰影、簡潔富表情的臉部以及細小的四肢。即使參考美術圖更精細、複雜或寫實，生成的寵物也應簡化為此風格。

請勿生成精緻插畫、繪畫風渲染、動漫主視覺圖、3D 渲染、光澤應用程式圖示效果、寫實毛髮或材質紋理、柔和漸層、高細節抗鋸齒以及複雜微小的配件。比此風格更複雜的參考圖，在生成動畫行之前應先簡化為官方風格（house style）。

透明度與特效（Transparency And Effects）

寵物動畫行會被處理為透明的 192x208 儲存格，因此生成的每個像素都必須屬於寵物精靈圖，或者是可乾淨清除的去背綠幕/藍幕背景（chroma-key background）。相較於裝飾性特效，應優先透過姿勢、表情和輪廓變化來呈現。

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

• 特效與狀態相關，且有助於說明動畫。
• 特效在物理上附著於、接觸到或重疊於寵物輪廓，而非浮動在附近。
• 特效位於與寵物相同的影格位置內，且不會建立獨立的精靈圖組件。
• 特效為不透明、硬邊緣、像素風格，且使用非去背背景色。
• 特效足夠小，能在 192x208 解析度下保持清晰可讀而不顯雜亂。

允許特效的範例：接觸臉部的眼淚、接觸箱子或頭部的微小煙霧，或在失敗/暈眩反應中重疊在寵物身上的微小星星。

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

• 揮手痕跡、動態弧線、速度線、動作條紋、殘影、模糊或抹痕
• 分離的星星、零散的火花、浮動標點符號、浮動圖示、掉落的淚滴、分離的煙霧雲或零散的灰塵
• 投射陰影、接觸陰影、落影（drop shadows）、橢圓形地面陰影、地面區塊、著陸痕跡、衝擊爆裂、光暈、光環、靈氣或柔和透明效果
• 文字、標籤、影格編號、可見網格、引導標記、對話框、思考框、UI 面板、程式碼片段、棋盤格透明背景、白色背景、黑色背景或背景風光
• 寵物、道具、特效、亮部或陰影中出現接近去背背景色的顏色
• 雜點像素、斷開的輪廓碎片、斑點/雜訊、裁切的身體部位、重疊的姿勢，或任何跨入相鄰影格位置的姿勢

特定狀態指導方針：

• waving：僅透過爪子姿勢來展現揮手動作。切勿在爪子周圍繪製揮手痕跡、動態弧線、線條、火花或符號。
• jumping：僅透過身體位置展現垂直運動。切勿繪製陰影、灰塵、著陸痕跡、衝擊爆裂、彈跳墊或地面提示。
• failed：若符合允許特效的規則，允許使用眼淚、附著的煙霧或附著的星星；請勿使用紅色 X 標記、浮動符號、分離的煙霧、分離的星星或獨立的淚滴。
• review：透過前傾、眨眼、眼神、頭部傾斜或爪子位置展現專注。除非該道具已存在於基礎寵物特徵中，否則請勿添加放大鏡、紙張、程式碼、UI、標點符號或符號。
• running-right、running-left 和 running：僅透過身體、四肢和道具移動展現移動感。請勿繪製速度線、塵土雲、地面陰影或動態軌跡。

寵物命名（Pet Naming）

當使用者未提供寵物名稱，且對話情境自然允許時，可詢問使用者寵物名稱。若詢問會延緩直接執行的請求，請從寵物概念、參考圖或性格中選擇一個簡短合適的名稱，並一致地將該名稱用作顯示名稱以及套件資料夾 slug 的來源。

良好官方風格範例：

• Codex - 原始的 Codex 伴侶。
• Dewey - 適合平靜工作日的整潔小鴨。
• Fireball - 適合快速迭代的高效能量。
• Rocky - 當程式碼比對（diff）變大時穩如泰山的石頭。
• Seedy - 代表新想法的小綠芽。
• Stacky - 適合深度工作的平衡堆疊。
• BSOD - 藍當畫面（藍屏）小藍魔。
• Null Signal - 來自虛空的靜謐訊號。

可視化進度計畫（Visible Progress Plan）

每次執行寵物任務時，請維護一份可視化的檢查清單，讓使用者瞭解工作進度。在開始前建立清單，一次保持一個步驟為活動狀態，並在每個步驟完成時及時更新。

在建立檢查清單前，盡可能確定寵物名稱。若使用者有提供名稱則直接使用；否則從概念或參考圖中推斷出簡短合適的名稱。若名稱太長、未定案或不適合用於友善的檢查清單，請改用 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 檔案的儲存位置。

只有當真正的檔案、影像或決策確定存在時，才將步驟標記為完成。如果這只是修復執行，請從第一個相關步驟開始，而非重新啟動整份檢查清單。

預設工作流程（Default Workflow）

1. 準備寵物任務資料夾與 imagegen 任務清單（manifest）：

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

上述所有參數皆為選填，除了用來表達使用者限制條件所需的標記（flags）。對於僅有文字的請求，請透過 --pet-notes 傳遞概念並省略 --reference；prepare_pet_run.py 會根據需要自動推斷名稱、描述、去背色（chroma key）及輸出目錄。

2. 檢查下一個已就緒的 $imagegen 任務：

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

3. 對於每個就緒的任務，調用 $imagegen，並帶入：

• imagegen-jobs.json 中列出的提示詞檔案
• 該任務列出的每張輸入影像及其角色標籤（role label）
• 預設內建的 image_gen 路徑，除非 $imagegen 本身路由至其他路徑