最終圖片資產
<skill-dir> 是存放此 SKILL.md 的資料夾,<plugin-root> 則是其上兩層的資料夾。請在指令中將它們替換為實際路徑。(在 Claude Code 中,它們分別為 ${CLAUDE_SKILL_DIR} 與 ${CLAUDE_PLUGIN_ROOT}。)
輸入:單一資產或列表,例如「連續凍結圖示」或「每日任務 GDD 中的 6 個獎勵圖示」。輸出:PNG 檔案,存放於遊戲的資產路徑,並記錄其提示詞與模型。
請先閱讀 <plugin-root>/shared/conventions.md 與倉庫設定(美術章節)。
GI="<skill-dir>/scripts/gen_image.py" # 僅限 Python 3;絕不輸出金鑰
python3 "$GI" check # 檢查將使用的金鑰與模型,無費用(從遊戲倉庫執行)
python3 "$GI" generate --prompt "…" --out <file.png> [--size WxH] [--background transparent] [--ref <art.png> …] [--log <log.jsonl>]
0. 此專案是否啟用圖片生成?
讀取 config: Image generation:
on:前往步驟 1。off:不生成。使用現有美術或倉庫的佔位符模式,並在報告中列出仍需的資產(名稱、大小、用途)。不要再次詢問。not set或缺失:這是此專案的第一張圖片。執行check,然後使用提問工具詢問:- 如果找不到金鑰,問題會說明最終資產預設使用 OpenAI 的 GPT Image(最新版本,2 或更新),並且需要 API 金鑰。選項如下:
- 立即設定金鑰(推薦):顯示下方的設定步驟,等待使用者告知完成。然後再次執行
check。準備就緒後,寫入on。 - 不為此專案設定:寫入
off (opted out <YYYY-MM-DD>),並在沒有生成美術的情況下繼續。 - 現在不要:跳過這次的圖片,將欄位保留為
not set,並在下次再次詢問。
- 立即設定金鑰(推薦):顯示下方的設定步驟,等待使用者告知完成。然後再次執行
- 如果找到金鑰(在倉庫的
.env、環境變數中,或為另一個專案設定),問題會指出金鑰的來源以及check選擇的模型。如果check指出.env檔案受 git 追蹤,則警告金鑰已被提交,應輪替金鑰,並建議將其移出 git。選項包括:用於此專案(推薦,然後寫入on)、不為此專案(off)、以及現在不要。
- 如果找不到金鑰,問題會說明最終資產預設使用 OpenAI 的 GPT Image(最新版本,2 或更新),並且需要 API 金鑰。選項如下:
API 金鑰設定(向使用者顯示此步驟)
- 前往 platform.openai.com → API keys → Create new secret key。專案範圍的金鑰最佳。
- 確保 Billing 有餘額。GPT Image 模型可能還要求您驗證組織(Settings → Organization → General)。驗證後,存取權可能需要幾分鐘才能啟用。
- 在此機器上儲存金鑰。切勿將其貼入對話中。
- macOS(推薦):在終端機中執行此指令。它會詢問金鑰但不顯示,並將其儲存在鑰匙圈中:
security add-generic-password -U -a "$USER" -s gd-toolkit-openai -w - 僅此專案:將
OPENAI_API_KEY=…加入倉庫的.env或.env.local。請先檢查該檔案是否在.gitignore中。 - 任何地方:將
export OPENAI_API_KEY=…加入您的 shell 設定檔,例如~/.zshrc,然後開啟新的終端機。 - 或使用僅您可讀取的檔案:
~/.config/gd-toolkit/openai_api_key(chmod 600)。
- macOS(推薦):在終端機中執行此指令。它會詢問金鑰但不顯示,並將其儲存在鑰匙圈中:
- 完成時告訴我,我會進行檢查。此檢查無需費用。
鑰匙圈、shell 或設定檔中的金鑰適用於每個專案;.env 金鑰僅適用於其倉庫,且優先於鑰匙圈。每個專案可獨立選擇開啟/關閉。
1. 規劃資產
- 風格:讀取 config: Art style 並查看其列出的參考美術。將 1–4 個最接近的現有資產作為
--ref傳遞,使新美術與遊戲匹配。在每個提示詞中使用相同的詞語描述風格:調色板、線條粗細、陰影、攝影機角度和材質。 - 規格:每個資產的最終尺寸、格式、是否需要透明背景、檔案名稱和路徑(config: Assets dir,加上倉庫的命名模式)。
- 顯示清單,包含總數和模型,並在使用者確認後一次生成。一次確認即可涵蓋整個批次。
2. 生成
- 模型:
--model auto(預設)使用金鑰可用的最新 gpt-image 模型(版本 2 或更新),並偏好使用詳細變體進行最終美術。--fast(作為--prefer fast傳遞)僅用於草稿。如果 config: Image model 指定了模型,則使用--model傳遞它。 - 尺寸:以模型的最大正方形或最接近的長寬比生成,然後縮小到最終尺寸(macOS 上使用
sips -Z <px>)。絕不放大。 - 透明度:圖示、物品和精靈需要
--background transparent。如果輸出指出模型拒絕了該要求,則圖片將變為不透明:使用提示詞中指定的純色背景顏色重新生成,移除該顏色,並在報告中說明。 - 提示詞:描述主體,然後是風格區塊,然後是構圖(置中、留白、除非要求否則無文字)。除非資產需要文字,否則要求不要有文字、標誌或浮水印。
- 每次生成都記錄到 config: Art log(使用
--log)。切勿將中繼資料檔案放在出貨的資產旁邊。
3. 檢查每張圖片
在保留每張圖片之前,先查看它(使用縮小版以節省上下文)。如果圖片不符合風格參考、包含多餘文字或偽影、裁剪錯誤、或在遊戲中的最小尺寸下無法辨識,則重新生成(最多 3 次)。如果仍然失敗,則保留最佳的一張並標記它。
4. 報告
列出每個資產及其路徑、尺寸、模型和任何標記。同時提供仍需的資產(如果生成已關閉或跳過),以及日誌路徑。說明這些圖片是 AI 生成的,以便擁有者決定是否需要揭露,例如在商店列表等地方。