grahama1970/imagegen

影像生成技能

為當前專案生成或編輯影像（例如網站素材、遊戲素材、UI 模型、產品模型、線框圖、標誌設計、逼真影像或資訊圖表）。

頂層模式與規則

此技能有兩種頂層模式：

• 預設內建工具模式（首選）： 內建 image_gen 工具，用於一般影像生成、編輯與簡單的透明背景請求。無需 OPENAI_API_KEY。
• 備用 CLI 模式： scripts/image_gen.py CLI。僅在使用者明確要求 CLI/API/模型路徑，或在使用者明確確認使用 gpt-image-1.5 進行真正的模型原生透明度備用方案後使用。需要 OPENAI_API_KEY。

在 CLI 備用模式中，CLI 提供三個子命令：

• generate
• edit
• generate-batch

規則：

• 預設使用內建 image_gen 工具處理一般影像生成與編輯請求。
• 不要為了普通的品質、尺寸或檔案路徑控制而切換到 CLI 備用模式。
• 如果使用者明確要求透明影像/背景，應先停留在內建 image_gen：提示使用平坦的可移除色度鍵背景，然後使用安裝在 $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py 的輔助工具在本地端移除背景。
• 切勿在未經使用者同意的情況下，從內建 image_gen 或 CLI gpt-image-2 切換到 CLI gpt-image-1.5。除非使用者已明確要求使用 gpt-image-1.5、scripts/image_gen.py 或 CLI 備用模式，否則將其視為模型/路徑降級，並在執行前詢問使用者。
• 如果透明背景請求對於單純的色度鍵去除來說過於複雜，或使用者要求真正的/原生透明度，或本地端去除驗證失敗，應說明真正的透明度需要使用 CLI gpt-image-1.5 --background transparent --output-format png，因為 gpt-image-2 不支援 background=transparent，然後詢問是否繼續。僅在使用者確認後才執行 CLI 備用方案。
• 「批次」一詞本身不代表 CLI 備用模式。如果使用者要求大量素材或要求批次生成素材，但沒有明確要求 CLI/API/模型控制，則應停留在內建路徑，並為每個要求的素材或變體發出一次內建工具呼叫。
• 如果內建工具失敗或無法使用，告知使用者有 CLI 備用方案，且需要 OPENAI_API_KEY。僅在使用者明確要求該備用方案時才繼續執行。
• 如果使用者明確要求 CLI 模式，則使用隨附的 scripts/image_gen.py 工作流程。不要自行建立一次性 SDK 執行器。
• 切勿修改 scripts/image_gen.py。如有缺少功能，請先詢問使用者再執行其他操作。

內建儲存路徑政策：

• 在內建工具模式下，Codex 預設將生成的影像儲存在 $CODEX_HOME/* 下。
• 不要將 OS 暫存資料夾描述或依賴為預設的內建目的地。
• 不要描述或依賴內建 image_gen 工具上的目的地路徑參數（如果有的話）。如果需要特定位置，先生成，然後將選定的輸出從 $CODEX_HOME/generated_images/... 移動或複製過去。
• 內建模式下的儲存路徑優先順序：
  1. 如果使用者指定了目的地，則將選定的輸出移動或複製到該處。
  2. 如果影像用於當前專案，則在完成前將最終選定的影像移動或複製到工作區中。
  3. 如果影像僅用於預覽或腦力激盪，則內嵌顯示；底層檔案可以保留在預設的 $CODEX_HOME/* 路徑下。
• 切勿將專案中引用的素材僅保留在預設的 $CODEX_HOME/* 路徑下。
• 除非使用者明確要求替換，否則不要覆寫現有素材；否則應建立帶有版本編號的姊妹檔名，例如 hero-v2.png 或 item-icon-edited.png。

兩種模式共用的提示指引存放於 references/prompting.md 和 references/sample-prompts.md。

僅供 CLI 模式使用的備用文件/資源：

• references/cli.md
• references/image-api.md
• references/codex-network.md
• scripts/image_gen.py

本地端後處理輔助工具：

• $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py：從生成的影像中移除平坦的色度鍵背景，並寫出帶有 Alpha 通道的 PNG/WebP。偏好使用自動按鍵取樣、柔邊遮罩和去邊緣溢色，以獲得抗鋸齒邊緣。

使用時機

• 生成新影像（概念藝術、產品照、封面、網站主圖）
• 使用一張或多張參考影像的風格、構圖或氛圍來生成新影像
• 編輯現有影像（修補、燈光或天氣變換、背景更換、物體移除、合成、透明背景）
• 為一項任務製作多個素材或變體

不應使用的情況

• 擴展或比對儲存庫中現有的 SVG/向量圖示集、標誌系統或插圖庫
• 建立更適合直接以 SVG、HTML/CSS 或 Canvas 產生的簡單形狀、圖表、線框圖或圖示
• 當原始檔案已以可編輯的原生格式存在時，對小型專案本地素材進行編輯
• 任何使用者明確想要確定性的程式碼原生輸出而非生成的點陣圖的任務

決策樹

思考兩個獨立的問題：

1. 意圖： 這是新影像還是對現有影像的編輯？
2. 執行策略： 這是一個素材還是多個素材/變體？

意圖：

• 如果使用者想要修改現有影像並保留部分內容，則將請求視為編輯。
• 如果使用者僅提供影像作為風格、構圖、氛圍或主題的參考，則將請求視為生成。
• 如果使用者未提供任何影像，則將請求視為生成。

內建編輯語義：

• 內建編輯模式用於已存在於對話上下文中的影像，例如已附加的影像或稍早在執行緒中生成的影像。
• 如果使用者想要使用內建工具編輯本地影像檔案，請先使用內建 view_image 工具載入它，使影像在對話上下文中可見，然後再進行內建編輯流程。
• 不要承諾可以透過內建工具編輯任意的檔案系統路徑。
• 如果本地檔案仍然需要直接的路徑控制、遮罩或其他明確的 CLI 專用參數，則僅在使用者要求時才使用明確的 CLI 備用方案。
• 對於編輯，積極保留不變項，並預設以非破壞性方式儲存。

執行策略：

• 在內建預設路徑中，透過為每個要求的素材或變體發出一次 image_gen 呼叫來產生多個素材或變體。
• 在 CLI 備用路徑中，僅在使用者明確選擇 CLI 模式並需要大量提示/素材時，才使用 CLI 的 generate-batch 子命令。
• 對於許多不同的素材，不要使用 n 作為單獨提示的替代品。n 用於一個提示的變體；不同的素材需要不同的內建呼叫或不同的 CLI generate-batch 任務。

除非使用者明確要求更改現有影像，否則假設使用者想要一張新影像。

工作流程

1. 決定頂層模式：預設為內建模式，包括簡單的透明輸出請求；僅在明確要求或使用者確認透明輸出備用方案後才使用備用 CLI。
2. 決定意圖：generate 或 edit。
3. 決定輸出僅供預覽還是供當前專案使用。
4. 決定執行策略：單一素材 vs 重複內建呼叫 vs CLI generate-batch。
5. 預先收集輸入：提示、確切文字（逐字）、限制/避免清單以及任何輸入影像。
6. 對於每張輸入影像，明確標註其角色：
   • 參考影像
   • 編輯目標
   • 輔助插入/風格/合成輸入
7. 如果編輯目標僅在本地檔案系統上，且您停留在內建路徑上，請先使用 view_image 檢查它，以便影像在對話上下文中可用。
8. 如果使用者要求照片、插圖、精靈圖、產品圖、橫幅或其他明確的點陣風格素材，請使用 image_gen，而不是使用 SVG/HTML/CSS 佔位符替代。如果請求的是應與現有儲存庫原生 SVG/向量/程式碼素材相符的圖示、標誌或 UI 圖形，則優先直接編輯這些素材。
9. 根據具體程度增強提示：
   • 如果使用者的提示已經具體且詳細，則將其正規化為清晰的規格，不要添加創意要求。
   • 如果使用者的提示較為通用，則僅在能顯著提升輸出品質時添加適當的增強。
10. 預設使用內建 image_gen 工具。
11. 對於透明輸出請求，請遵循以下透明影像指引：先使用內建 image_gen 在平坦的色度鍵背景上生成，將選定的輸出複製到工作區或 tmp/imagegen/，執行已安裝的 $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py 輔助工具，並在使用前驗證 Alpha 結果。如果此路徑看起來不合適或失敗，請在使用前詢問是否切換到 CLI gpt-image-1.5。
12. 檢查輸出並驗證：主體、風格、構圖、文字準確性以及不變項/避免項目。
13. 透過單一的定向更改進行迭代，然後重新檢查。
14. 對於僅供預覽的工作，內嵌顯示影像；底層檔案可以保留在預設的 $CODEX_HOME/generated_images/... 路徑下。
15. 對於專案內的工作，將選定的成品移動或複製到工作區中，並更新任何消費代碼或參考。切勿將專案中引用的素材僅保留在預設的 $CODEX_HOME/generated_images/... 路徑下。
16. 對於批次或多素材請求，除非使用者明確要求僅保留預覽輸出，否則將每個要求的可交付最終成果持久保存到工作區中。除非被要求，否則不需要保留被捨棄的變體。
17. 如果使用者明確選擇或確認 CLI 備用方案，則使用僅限備用方案的文件來獲取模型、品質、尺寸、input_fidelity、遮罩、輸出格式、輸出路徑和網路設定。
18. 始終報告任何工作區繫結素材的最終儲存路徑，以及最終的提示或提示集，以及使用的是內建工具還是備用 CLI 模式。

透明影像請求

透明影像請求仍然首先使用內建 image_gen。因為內建工具不提供真正的透明背景控制，請建立可移除的色度鍵來源影像，然後在本地端將鍵顏色轉換為 Alpha 通道。

預設順序：

1. 使用內建 image_gen 在完全平坦的純色度鍵背景上生成所需的主體。
2. 選擇一個不太可能出現在主體中的鍵顏色：預設為 #00ff00，對於綠色主體使用 #ff00ff，對於藍色主體避免使用 #0000ff。
3. 生成後，將選定的來源影像從 $CODEX_HOME/generated_images/... 移動或複製到工作區或 tmp/imagegen/。
4. 執行已安裝的輔助工具路徑，而不是專案相對路徑的腳本：

   python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
     --input <source> \
     --out <final.png> \
     --auto-key border \
     --soft-matte \
     --transparent-threshold 12 \
     --opaque-threshold 220 \
     --despill
   

5. 驗證輸出是否具有 Alpha 通道、透明角落、合理的主體覆蓋範圍，以及沒有明顯的鍵顏色邊緣。如果殘留薄邊緣，使用 --edge-contract 1 重試一次；僅在邊緣明顯呈階梯狀且主體不反光或反射時使用 --edge-feather 0.25。
6. 如果素材是專案繫結的，則將最終的 Alpha PNG/WebP 儲存在專案中。切勿將專案中引用的透明素材僅保留在 $CODEX_HOME/* 下。

像這樣提示透明請求：

在完全平坦的純色 #00ff00 色度鍵背景上建立請求的主體，以便進行背景移除。
背景必須是單一均勻的顏色，沒有陰影、漸層、紋理、反射、地板平面或光線變化。
保持主體與背景完全分離，邊緣清晰，並留有充足的內距。
請勿在主體任何部分使用 #00ff00。
無投射陰影、無接觸陰影、無反射、無浮水印，除非明確要求，否則無文字。

不要自動使用 CLI gpt-image-1.5 --background transparent --output-format png 來代替色度鍵處理。在使用者要求真正的/原生透明度、本地端去除驗證失敗，或請求的影像複雜時（如頭髮、毛皮、羽毛、煙霧、玻璃、液體、半透明材質、反光物體、柔和陰影、逼真的產品接地，或與所有實際鍵顏色衝突的主體顏色），應先詢問使用者。

使用簡潔的確認訊息，例如：

這可能需要真正的原生透明度。預設的內建路徑使用色度鍵背景加本地端去除，但真正的透明度需要 CLI 備用方案搭配 gpt-image-1.5，因為 gpt-image-2 不支援 background=transparent。它還需要 OPENAI_API_KEY。我應該繼續使用那個 CLI 備用方案嗎？

提示增強

將使用者的提示重新格式化為結構化、面向生產的規格。使使用者的目標更清晰且更具可操作性，但不要盲目添加細節。

將其視為提示塑形指引，而非封閉的 schema。僅使用有幫助的部分，並在能顯著提升清晰度時添加一個簡短的額外標籤行。

具體程度政策

根據使用者提示的具體程度來決定多大程度的增強是合適的：

• 如果提示已經具體且詳細，則保留該具體性，僅進行正規化/結構化處理。
• 如果提示較為通用，則僅在能顯著改善結果時添加適當的增強。

允許的增強：

• 構圖或取景提示
• 精緻程度或預期用途提示
• 實用的版面指引
• 支援所述請求的合理場景具體性

不允許的增強：

• 請求未暗示的額外角色或物體
• 未暗示的品牌名稱、口號、調色板或敘事情節
• 任意的側邊特定放置，除非周圍版面支援

用例

… [為翻譯而截斷]