codex-image
透過使用者的 ChatGPT 訂閱，使用 GPT Image 生成與編輯圖片。輸出存放在 ./generated_images/（或透過 --out-dir / --out 指定）。
執行方式
所有操作皆透過一個腳本進行。請解析包含此 SKILL.md 的絕對目錄路徑（您的代理程式會在技能載入時公告該目錄——以下以 <skill-dir> 表示），然後執行：
bash "<skill-dir>/scripts/generate.sh" "<提示詞>" [參數]
切勿直接呼叫相對路徑的 scripts/generate.sh：您的工作目錄是使用者的專案，而非技能的安裝位置（安裝位置因代理而異——可能是 ~/.claude/skills/、~/.agents/skills/、~/.opencode/skills/、專案內的 .claude/skills/ 等）。
腳本會自動檢查以下需求：
python3≥ 3.10 需在 PATH 中（除此之外僅需 bash 與標準 Python 函式庫）。- Pillow——僅用於
--format webp和--transparent-mode chroma。 預設不安裝；若使用這些參數，腳本會快速失敗並提示安裝指令（python3 -m pip install 'Pillow>=10'）。一般的--transparent不需要它。首次使用這兩種功能前請先提及此前提。 - Codex CLI 需已登入。若未登入，腳本會以
Run: codex login結束——請將此訊息轉達給使用者，不要自行處理驗證。
執行 bash "<skill-dir>/scripts/generate.sh" --help 可查看所有參數；在自訂參數前請先查閱。如果主代理支援型別化斜線指令，/codex-image "<提示詞>" --參數 是給使用者使用的簡寫，等同於此腳本呼叫。
此腳本是機械式的——它不做語意路由。連續處理、批次決策與去背分派是您的職責，需根據對話內容進行。
GPT Image 2.5
OpenAI 提供 gpt-image-2.5-sunburst 用於精確編輯，以及 gpt-image-2.5-flare 用於更快的日常生成。若要指定模型，請傳入 --image-model <模型ID>；省略則保留 Codex Responses 的預設選擇。此參數在訂閱傳輸層上仍屬實驗性質：2026-09-08 的即時檢查曾請求兩種變體，但兩者的回應都回報為 gpt-image-2-codex。請勿僅因請求成功就宣稱有 2.5 升級。舊的回應別名或 C2PA 版本 2.0 也不代表使用了較新權重：OpenAI 在 2.5 公告中發布的圖片同樣帶有該來源版本。當回報的模型與請求不同或缺失時，腳本會發出警告；請在 sidecar 檔案中分別檢查 image_model 與 requested_image_model。--orchestrator 是用於選擇呼叫圖片工具的主線模型，而非 Sunburst 或 Flare。請勿使用此參數：腳本會自動使用帳號列表中最新的 Sol 層級模型（gpt-<版本>-sol），因此已淘汰的模型不會導致故障。請求會根據 Codex 自身設定將 Codex 送往何處：可能是自訂的 model_provider（如代理）、openai_base_url 中繼站，或 chatgpt.com。
請參閱 GPT Image 2.5 相容性 以了解已驗證的傳輸行為與官方來源。公開 API 支援模型選擇、xhigh/max 及透明度，並不代表在 Codex Responses 上有相同行為。
連續處理
當請求是修改前一輪立即生成的圖片（「調暗一點」、「加頂帽子」、「增加對比度」）時，請傳入 --from-last——腳本會自動重複使用上一次生成的結果（記錄在 ~/.codex-image/last.json），因此您無需從對話記錄中還原路徑。
若要編輯特定檔案或較舊的生成結果，請傳入 --input <路徑|網址>（可重複使用；最多合併 16 個參考，包含 --from-last；這是技能的參考上限）。
當請求是全新的主題時——即使語氣是「現在做一個……」——請不要傳入任何參數，直接從頭生成。如果您猜錯且使用者說「不，我指的是新的」，請重新執行且不帶參考。
使用者僅提供作為風格、構圖或氛圍參考的圖片是生成的參考，而非編輯目標——透過 --input 傳入，但將提示詞敘述為新圖（「以圖 2 的風格」）。混合多個輸入時，請在提示詞中為每個圖標註索引與角色（「圖 1：編輯目標，圖 2：風格參考」）。
生成後：先查看，再回報
在告知使用者完成之前，請先檢視儲存的圖片檔案，並檢查是否符合要求：主體、構圖、任何逐字呈現的文字、以及使用者提出的所有限制。若有不足，請透過 --from-last 進行一次有針對性的修改，並重申不可偏離的不變項。不要將多項修正疊加在一次重新執行中，也不要回報您尚未檢視過的路徑。
儲存紀律：輸出預設為 ./generated_images/。如果圖片最終要放入使用者的專案中，請將其複製或移動到正確位置（並更新任何引用它的程式碼）——不要將專案資產遺留在暫存目錄中。切勿覆蓋使用者未要求取代的既有資產；應改為寫入版本化檔案（例如 hero-v2.png）。
透明圖片
當使用者想要透明背景時，請加上 --transparent。就是這樣——不需要分派決策、不需要 Pillow、也不需要您安排後處理步驟。
腳本會直接要求模型提供 alpha 通道：它會發送 background: "auto" 並在提示詞中附加一句話，後端會回傳 RGBA 格式。請勿傳入 --background transparent；該值會被此後端拒絕（docs/adr/0001-request-transparency-in-the-prompt.md 說明了原因，以及為什麼顯而易見的「修正」是錯的）。
如果您自行測試後端並看到 "Transparent background is not supported for this model." 的訊息，請不要斷定透明度不可用。 該 400 錯誤是參數被拒絕，而非功能不可用。只要在提示詞中要求，模型就會回傳真實的 alpha 通道，這就是 --transparent 所做的。那些聲明原生透明度需要 gpt-image-1.5 或 OPENAI_API_KEY 的建議是 0.2.0 版之前的舊資訊，而且是錯誤的；如果您讀到這些，表示您安裝的技能已過時。請檢查此檔案中的 metadata.version——應為 0.2.0 或更高版本。
撰寫提示詞時有兩點需要注意：
- 描述主體，而非場景。 提示詞勝過參數。「陽光工作室中木桌上的馬克杯」可能會渲染出整個工作室，而非只隔離馬克杯。請命名主體及其材質，不要提及周圍環境。
- 不要自行添加禁令。 後綴部分刻意不禁止任何事物。如果使用者要求加上陰影，就讓他們加上——它會被渲染到 alpha 通道中並正確合成。自行添加「無陰影、無背景」會覆蓋使用者的意圖。
生成後，請檢視檔案並確認 alpha 通道確實存在。當結果無 alpha 或完全不透明時，腳本會透過 stderr 發出警告；請將此視為重新執行的信號，並進行一次有針對性的修改，通常是移除場景描述語言。
備援方案階梯，僅在原生結果不理想時使用（已在實心主體上驗證；毛髮、玻璃、煙霧與半透明物體尚未測試）：
| 升級步驟 | 操作 |
|---|---|
| 重新提示 | 移除場景/背景描述，僅命名主體 |
| 提升品質 | 使用 --quality medium 處理細緻邊緣與小文字 |
| Chroma | 使用 --transparent-mode chroma（需 Pillow）——您可控制關鍵色板 |
| Adobe MCP | 使用 --transparent-mode chroma --bg-tool=none，然後呼叫此工作階段可用的任何 Adobe 去背工具（尋找名稱包含 remove_background 的 MCP 工具），並以 alpha 結果覆寫檔案。適用於半透明物體的最佳選項 |
Chroma 邊緣修復：細微邊緣 → --edge-contract 1；霧面主體上的階梯狀邊緣 → --edge-feather 0.25。更深入的失敗模式：請參閱 references/transparent-image-tips.md。
品質、成本與時間控管
- 預設為
--quality high；low、medium、high、xhigh、max和auto皆為接受的請求。草稿請從low開始。Codex Responses 可能會覆蓋品質設定；請在 sidecar 或--verbose輸出中檢查resolved_quality，然後再宣稱送達了何種等級。 - 生成次數會計入使用者的 ChatGPT 方案限制。延遲時間因模型、提示詞、品質與服務負載而異。
- 在為單一請求生成超過 3 張圖片之前，請先與使用者確認。
- 切勿無限迴圈。「很多」/「一整組」→ 選取一個合理的預設值（4）並提供繼續的選項。
- 後端回傳 HTTP 429 時立即停止，不要重試。
常見工作流程
# 單次生成
bash "<skill-dir>/scripts/generate.sh" "雨夜中的黃色計程車"
# 延續上一次生成
bash "<skill-dir>/scripts/generate.sh" "現在加上蒸騰的熱氣" --from-last
# 編輯指定的參考圖片
bash "<skill-dir>/scripts/generate.sh" "把它變成藍色" --input ./mug.png
# 透明背景（來自模型的原生 alpha，不需 Pillow）
bash "<skill-dir>/scripts/generate.sh" "一個咖啡馬克杯" --transparent
# 透明背景，加上使用者要求的陰影（保留在 alpha 中）
bash "<skill-dir>/scripts/generate.sh" "一個帶有柔和投影的咖啡馬克杯" --transparent
# Chroma 備援方案，當原生結果不理想時（需 Pillow）
bash "<skill-dir>/scripts/generate.sh" "一個玻璃罐" --transparent --transparent-mode chroma
# 不同尺寸 / 格式 / 品質
bash "<skill-dir>/scripts/generate.sh" "英雄橫幅" --size 2048x1152 --format webp --quality low
權杖編輯（安全性）
絕對不要列印或記錄使用者的 access_token、id_token、refresh_token 或任何 Authorization: Bearer ... 標頭。技能的 Python 模組會自動編輯；您不得透過自行讀取 ~/.codex/auth.json 或在錯誤訊息中回顯權杖來破壞此保護。
不應呼叫的時機
- 向量圖形、SVG、ASCII 藝術或 LaTeX 圖表 → 請使用專用的向量或圖表工具。
- 使用者明確要求使用不同的模型或產品（DALL-E、Stable Diffusion、Midjourney）→ 請遵循其意願。
對於正式的標誌/品牌製作——可以呼叫，但請設定合理期望：應先生成探索性方案，再透過單次修改的 --from-last 迭代來優化，而非承諾一次到位（相關範本請參閱 references/prompting-cookbook.md）。
參考資料
若需更深入的資訊，請從 <skill-dir>/references/ 中閱讀：
api-recipe.md——標準請求主體、標頭、被拒絕的欄位、透明度機制、SSE 解析prompting-cookbook.md——提示詞基礎 + 使用案例範本（標誌、產品照、UI 模型、資訊圖表）transparent-image-tips.md——原生透明度的運作方式、何時會遇到問題，以及 Chroma 備援方案
儲存庫層級上下文：CONTEXT.md（詞彙表——三種傳輸層定義於此）與 docs/adr/（為什麼透明度是透過提示詞而非參數請求）。