doggy8088/imagegen-mai

Microsoft Foundry MAI-Image 圖像生成技能

為當前專案（例如網站素材、遊戲素材、UI 模型稿、產品模型稿、線框圖、標誌設計、逼真圖像或資訊圖表）透過 Microsoft Foundry 中的 MAI-Image 部署生成或編輯圖像。

在此檔案中，<skill-dir> 指的是包含此 SKILL.md 的目錄。

執行模式與規則

此技能使用目錄下的 CLI 工具 <skill-dir>/scripts/image_gen.js。AI 代理人主機並未為此工作流程提供內建的圖像生成或圖像檢視工具，因此請勿參考或嘗試使用不存在的內建工具。

CLI 提供三個子指令：

• generate
• edit
• generate-batch

規則：

• 對於一般的圖像生成和編輯請求，請使用 scripts/image_gen.js。
• CLI 僅支援 MAI-Image 系列模型。切勿將 GPT Image、DALL-E 或其他模型透過它進行路由。
• 預設部署為 IMAGEGEN_MAI_IMAGE_DEPLOYMENT，若未設定則為 MAI-Image-2.6-Flash。請勿在未經使用者明確同意的情況下，擅自切換到不同的部署。除非使用者已明確要求該模型，否則請先詢問使用者。
• MAI 圖像模型始終傳回不透明的 PNG。對於透明圖像，請使用下方的色鍵工作流程，並告知使用者去背是在本地端完成的。
• 單純的 batch 一詞並不需要使用 generate-batch。僅當多資產請求自然適合以 JSONL 批次方式呈現時，才使用 generate-batch；否則請單獨執行個別 CLI 指令。
• 即時 API 呼叫需要 MAI 憑證和網路存取。
• 請使用綁定的 scripts/image_gen.js 工作流程。請勿建立一次性的 SDK 執行器。
• 切勿修改 scripts/image_gen.js。如果缺少某些功能，請先詢問使用者再採取其他行動。

輸出政策：

• 將生成的資產直接寫入請求的路徑，或當使用者未指定路徑時，寫入 output/imagegen/。
• 如果圖像是要用於當前專案，請在完成前將最終選定的圖像儲存在工作區中。
• 除非使用者明確要求替換，否則請勿覆蓋現有資產；反之，請建立同系列但帶有版本號的檔名，例如 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.js

本地後處理輔助工具：

• <skill-dir>/scripts/remove_chroma_key.js：從生成的圖像中移除純色色鍵背景，並寫入帶有 alpha 通道的 PNG。建議使用自動鍵取樣、柔邊遮罩和去溢出處理，以獲得抗鋸齒邊緣。

使用時機

• 生成新圖像（概念藝術、產品照、封面、網站主圖、海報）
• 生成依賴當前真實世界資訊的新圖像（使用 --web-grounding）
• 編輯現有圖像（物體移除或替換、屬性變更、內繪修復、文字更新、光線或天氣變更、瑕疵清理）
• 將最多五張參考圖像結合成一個結果（產品、角色或品牌資產的一致性）
• 為單一任務產出多個資產或變體

不使用時機

• 擴充或匹配儲存庫中現有的 SVG/向量圖示集、標誌系統或插圖庫
• 建立適合直接用 SVG、HTML/CSS 或畫布產出的簡單形狀、圖表、線框圖或圖示
• 當原始檔案已存在可編輯的原生格式時，進行小幅的專案本地資產編輯
• 任何使用者明確希望輸出確定性程式碼原生結果，而非生成的點陣圖的任務
• 輸出尺寸超過約 1.5K（MAI-Image-2.6 上限為 2,359,296 像素，例如 1536x1536）；請告知使用者限制，而非在不告知的情況下放大

決策樹

思考兩個獨立的問題：

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

意圖：

• 如果使用者想要修改現有圖像同時保留其部分內容，則將請求視為 edit。
• 如果使用者提供圖像作為風格、構圖、氛圍或主體的參考，並希望將它們反映在結果中，請使用帶有這些圖像作為參考的 edit（MAI 生成 API 不接受圖像）。
• 如果使用者未提供任何圖像，請將請求視為 generate。

編輯語義：

• CLI 編輯模式透過重複的 --image 旗標接受一到五個本地的 PNG 或 JPEG 檔案。
• 如果使用者提供來自對話的附加圖像或參考，若環境支援，請先將其儲存到本地；否則請向使用者索取本地檔案路徑。
• 圖像順序是有意義的，因此請在提示中為每個圖像標記索引和角色。
• 對於編輯，請積極保留不變項，並預設以非破壞性方式儲存。
• MAI-Image-2 和 MAI-Image-2e 不支援編輯功能，CLI 會阻止此操作；請使用 MAI-Image-2.5 或 MAI-Image-2.6 部署進行編輯。

執行策略：

• 當 JSONL 批次處理是最清晰的工作流程時，對多個提示/資產使用 CLI generate-batch 子指令。
• MAI API 每次請求僅傳回一張圖像，且沒有 n 參數。對於變體，請使用不同的 out 名稱執行單獨的指令或單獨的批次作業。
• 速率限制較低（例如，Tier 1 的 MAI-Image-2.6-Flash 每分鐘 6 個請求）。請將 --concurrency 保持為預設值 2，除非使用者知道自己的配額。

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

工作流程

1. 決定 CLI 子指令：generate、edit 或 generate-batch。
2. 決定輸出是預覽專用還是要被當前專案使用。
3. 決定執行策略：單一資產 vs 重複 CLI 指令 vs CLI generate-batch。
4. 預先收集輸入：提示、確切文字（一字不差）、限制/避免清單、目標尺寸或長寬比，以及任何輸入圖像。
5. 對於每個輸入圖像，明確標記其角色：
   • 參考圖像
   • 編輯目標
   • 輔助插入/風格/合成的輸入
6. 如果使用者要求的是照片、插圖、精靈圖、產品圖、橫幅或其他明確的點陣圖風格資產，請使用此技能，而非替換為 SVG/HTML/CSS 佔位符。如果請求的是圖示、標誌或 UI 圖形，且應匹配儲存庫中現有的 SVG/向量/程式碼資產，則首選直接編輯這些資產。
7. 根據具體程度增強提示：
   • 如果使用者的提示已經很具體且詳細，請將其標準化為清晰的規格，不要添加創意要求。
   • 如果使用者的提示很籠統，僅在能實質改善輸出品質時，才添加恰到好處的增強。
8. 選擇尺寸。對於已知目標使用 --size WIDTHxHEIGHT，或當應由構圖決定時使用 --auto-aspect-ratio（MAI-Image-2.6 系列）。當提示依賴於當前真實世界的實體、地點或事件時，添加 --web-grounding（MAI-Image-2.6 系列）。
9. 使用預設部署執行 scripts/image_gen.js。
10. 對於透明輸出的請求，請遵循下方的色鍵工作流程。
11. 檢查輸出並驗證：主體、風格、構圖、文字準確性以及不變項/避免項目。
12. 進行單一目標變更來疊代，然後重新檢查。
13. 對於預覽專用工作，請寫入 output/imagegen/，除非使用者要求不同的位置。
14. 對於專案綁定工作，請將成品寫入工作區，並更新任何使用到的程式碼或參考。
15. 對於批次或多資產請求，請在使用者明確要求僅保留預覽輸出之前，將每個請求的最終交付物都保存在工作區中。除非被要求，否則不需要保留已拋棄的變體。
16. 使用 CLI 文件來了解部署、尺寸、auto_aspect_ratio、web_grounding、輸出路徑和網路設定。
17. 始終回報任何工作區綁定資產的最終儲存路徑，以及最終的提示或提示集。

透明圖像請求

MAI 圖像模型始終傳回不透明的 PNG，並且沒有透明背景的選項。使用色鍵來源圖像和本地移除來製作透明資產。

順序：

1. 使用 scripts/image_gen.js generate（或對現有圖像使用 edit）將要求的主體放置在完全平坦的純色色鍵背景上。

2. 選擇一個不太可能出現在主體中的鍵色：預設為 #00ff00，對於綠色主體使用 #ff00ff，對於藍色主體避免使用 #0000ff。

3. 將色鍵來源圖像保留在工作區或 tmp/imagegen/ 中。

4. 執行綁定的輔助工具：

   node "<skill-dir>/scripts/remove_chroma_key.js" \
     --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 儲存在專案中。

像這樣提示色鍵請求：

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

色鍵去背不適合處理毛髮、絨毛、羽毛、煙霧、玻璃、液體、半透明材質、反射性物體和柔和的陰影。在為這些主體承諾乾淨的去背之前，請告知使用者此限制。

提示增強

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

將此視為提示塑形指導，而非封閉的架構。僅使用有幫助的行，並在能實質改善清晰度時，添加一個簡短的額外標籤行。

具體程度政策

使用使用者提示的具體程度來決定多少增強是適當的：

• 如果提示已經很具體且詳細，請保留該具體性，僅將其標準化/結構化。
• 如果提示很籠統，僅當能實質改善結果時，才添加恰到好處的增強。

允許的增強：

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

不允許的增強：

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

用例分類法（確切 slug）

將每個請求分類到以下一個類別中，並在提示和參考中保持 slug 一致。

生成：

• photorealistic-natural：具有真實紋理和自然光線的寫實/編輯風格生活場景。
• product-mockup：產品/包裝照、型錄圖像、商品概念。
• ui-mockup：應用程式/網站介面模型稿和線框圖；指定所需的保真度。
• infographic-diagram：具有結構化版面與文字的圖表/資訊圖表。
• scientific-educational：課堂講解、科學圖解及具有所需標籤與準確性限制的學習視覺。
• ads-marketing：活動概念與廣告創意，包含目標受眾、品牌定位、場景與確切標語/文案。
• productivity-visual：投影片、圖表、工作流程與數據密集的商業視覺。
• logo-brand：標誌/商標探索，向量友善。
• illustration-story：漫畫、童書藝術、敘事場景。
• stylized-concept：風格驅動的概念藝術、3D/風格化渲染。
• historical-scene：符合時代背景/世界知識的場景。

編輯：

• text-localization：翻譯/替換圖內文字，保留版面。
• identity-preserve：試穿、場景中人物；鎖定臉部/身體/姿勢。
• precise-object-edit：移除或替換特定元素（包括內部交換）。
• lighting-weather：僅變更時間/季節/氛圍。
• background-extraction：透過平坦色鍵背景加上本地移除工具 scripts/remove_chroma_key.js 進行乾淨去背。
• style-transfer：在變更主體/場景的同時套用參考風格。
• compositing：多圖插入/合併，並匹配光線/透視（最多五張圖像）。
• sketch-to-render：將素描/線稿轉換為逼真渲染。

共享提示架構

對兩個頂層模式使用以下標籤化規格作為共享提示骨架：

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <user's main prompt>
Input images: <Image 1: role; Image 2: role> (optional)
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <lighting + mood>
Color palette: <palette notes>
Materials/textures: <surface details>
Text (verbatim): "<exact text>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

注意：

• Asset type 和 Input images 是提示骨架，而非專用 CLI 旗標。
• Scene/backdrop 指的是視覺設定。
• 執行說明如尺寸、auto_aspect_ratio、web_grounding 和輸出路徑屬於 CLI 路徑，而非提示文字。

增強規則：

• 保持簡潔。
• 僅添加實質改善提示所需的細節。
• 對於編輯，明確列出不變項（「僅變更 X；保持 Y 不變」）。
• 如果缺少任何關鍵細節而阻礙成功，請提出問題；否則繼續進行。

範例

…

[為便於翻譯而截斷]