baoyu-image-gen

Image Generation (AI SDK)

官方基於 API 的圖片生成工具。支援 OpenAI GPT Image 2、Azure OpenAI、Google、OpenRouter、DashScope（阿里通義萬相）、Z.AI GLM-Image、MiniMax、即夢（Jimeng）、豆包（Seedream）、Replicate 與 Agnes。

User Input Tools

當此 Skill 需要向使用者提問時，請遵循以下工具選擇規則（按優先順序）：

1. 優先使用內建工具：優先使用當前 agent runtime 提供的內建使用者輸入工具 — 例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何同等工具。
2. 備用方案：若不存在此類工具，請輸出帶有編號的純文字訊息，並要求使用者針對每個問題回覆所選的編號或答案。
3. 批次提問：若工具支援單次呼叫提出多個問題，請將所有適用問題整合至單次呼叫中；若僅支援單一問題，請依優先順序逐一提問。

下方具體的 AskUserQuestion 參考僅為範例 — 在其他 runtime 中請替換為當地的同等工具。

Script Directory

{baseDir} = 本 SKILL.md 所在的目錄。下方所有 scripts/... 路徑皆相對於 {baseDir}。主要指令碼：{baseDir}/scripts/main.ts。批次 Payload 輔助工具：{baseDir}/scripts/build-batch.ts。解析 ${BUN_X} 順序：優先使用 bun；其次為 npx -y bun；若皆無則建議 brew install oven-sh/bun/bun。

Step 0: Load Preferences ⛔ BLOCKING

步驟 0：載入偏好設定 ⛔ 阻塞性步驟

此步驟必須在任何圖片生成前完成 — 在 EXTEND.md 存在之前，圖片生成程序將被阻塞。

請依序檢查以下路徑；以第一個找到的檔案為準：

路徑	作用域
.baoyu-skills/baoyu-image-gen/EXTEND.md	專案 (Project)
${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-image-gen/EXTEND.md	XDG
$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md	使用者家目錄 (User home)

• 找到 → 載入、解析並套用。若 default_model.[provider] 為 null → 僅詢問模型。
• 未找到 → 使用 AskUserQuestion 執行首次設定 (references/config/first-time-setup.md)，以收集提供者 (provider) + 模型 (model) + 品質 (quality) + 儲存位置。儲存 EXTEND.md 後繼續。在此步驟完成前請勿生成圖片。

舊版相容性：若 .baoyu-skills/baoyu-imagine/EXTEND.md 存在而新路徑不存在，runtime 會將其重新命名為 baoyu-image-gen。若兩者皆存在，runtime 將保持原樣並使用新路徑。

EXTEND.md 鍵值：預設提供者、預設品質、預設寬高比、預設圖片尺寸、OpenAI 圖片 API 語法方言 (dialect)、預設模型、批次 Worker 上限、個別提供者的批次限制。Schema 參閱：references/config/preferences-schema.md。

Usage

最小可行範例 — 完整範例（包含各提供者的呼叫方式與批次模式）請參閱 references/usage-examples.md。

Identity-preserving reference prompts

當使用者希望從參考圖中保留真實人物/角色/物件的特徵時，切勿用長篇泛用的描述替換參考圖。請優先使用簡短、強力的身份保留用語：

• "Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject."
• "Only change scene, clothing, pose, lighting, rendering style, and composition. Keep the face/proportions/hair/key accessories/overall identity from the references."
• 若使用多張參考圖，請註明它們是同一主體，應共同定義其身份特徵。

常見陷阱：像 "young East Asian woman, oval face, clear eyes..." 這樣的長描述，可能會導致模型生成一個符合描述的新人物，而不是保留參考圖中的人物。

# 基本用法
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png

# 指定寬高比與高畫質
${BUN_X} {baseDir}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9 --quality 2k

# 從檔案讀取提示詞
${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md content.md --image out.png

# 帶有參考圖
${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png

# 指定提供者
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider dashscope --model qwen-image-2.0-pro

# OpenAI GPT Image 2
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openai --model gpt-image-2

# Codex CLI（使用已登入的 Codex 訂閱 — 不需要 OPENAI_API_KEY；PATH 中需有 `codex`）
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider codex-cli --ar 16:9

# 批次模式
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4

# 從 outline.md + prompts/ 建立批次檔案（例如 baoyu-article-illustrator 的輸出）
${BUN_X} {baseDir}/scripts/build-batch.ts --outline outline.md --prompts prompts --output batch.json --images-dir attachments
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4

Reference-Image Identity Preservation

當使用者希望保留參考圖中的人物/物件特徵時：

• 優先使用少而精選的現有來源參考圖（通常為 2–4 張），而非大量圖片；數 MB 的大型參考圖可能導致串流提供者不穩定。
• 提示詞中應強調參考圖為同一主體，且輸出必須使用該身份特徵。避免長篇泛用的面部特徵描述，以免模型生成新的相似人物。
• 切勿將新生成的圖片作為參考圖，除非使用者明確要求；生成圖作為參考會加劇特徵偏離 (drift)。
• 若生成結果過於精緻或帶有過度網紅感 (influencer-like)，請減少風格化參考圖，並加入明確的反美顏約束（不瘦臉、不放大眼睛、不濃妝、非商業旅遊街拍、不過度磨皮）。
• 若需要調整主體的視覺年齡（變年輕/變老），請保留面部特徵，並透過服飾、姿勢、場景與造型來展現年齡；切勿要求模型變更面部身份特徵。

Options

選項	說明
--prompt <text>, -p	提示詞文字
--promptfiles <files...>	從檔案讀取提示詞（會進行拼接）
--image <path>	輸出圖片路徑（單圖生成模式下為必填）
--batchfile <path>	用於多圖生成的 JSON 批次檔案
--jobs <count>	批次模式的 Worker 數量（預設：自動，最大值取自設定，內建預設值為 10）
--provider google|openai|azure|openrouter|dashscope|zai|minimax|jimeng|seedream|replicate|codex-cli|agnes	強制指定提供者（預設：自動偵測；codex-cli 絕不自動選擇 — 必須透過 CLI 或 EXTEND.md 指定）
--model <id>, -m	模型 ID — 預設值與可用值請參閱提供者參考文件
--ar <ratio>	寬高比（16:9、1:1、4:3 等）
--size <WxH>	明確指定尺寸（例如 1024x1024；對於 gpt-image-2，長寬必須為 16 的倍數，最大邊長 3840px，寬高比不超過 3:1）
--quality normal|2k	品質預設值（預設：2k）
--imageSize 1K|2K|4K	Google/OpenRouter 的圖片尺寸（預設：依據品質預設值）
--imageApiDialect openai-native|ratio-metadata	OpenAI 相容端點的 API 方言 — 若網關要求寬高比 size 加 metadata.resolution，請使用 ratio-metadata
--ref <files...>	參考圖片。支援的提供者包括 Google 多模態、OpenAI GPT Image 編輯、Azure OpenAI 編輯（僅 PNG/JPG）、OpenRouter 多模態模型、Replicate 支援的模型系列、MiniMax 主體參考、Seedream 5.0/4.5/4.0、DashScope wan2.7-image-pro/wan2.7-image。即夢 (Jimeng)、Seedream 3.0、SeedEdit 3.0 或 wan2.7-image* 系列之外的 DashScope 模型皆不支援
--n <count>	生成圖片數量。Replicate 要求 --n 1（單一輸出儲存語意）
--json	以 JSON 格式輸出

Environment Variables

變數	說明
OPENAI_API_KEY	OpenAI API 金鑰
AZURE_OPENAI_API_KEY	Azure OpenAI API 金鑰
OPENROUTER_API_KEY	OpenRouter API 金鑰
GOOGLE_API_KEY	Google API 金鑰
DASHSCOPE_API_KEY	DashScope API 金鑰
ZAI_API_KEY（別名 BIGMODEL_API_KEY）	Z.AI API 金鑰
MINIMAX_API_KEY	MiniMax API 金鑰
REPLICATE_API_TOKEN	Replicate API 金鑰 (Token)
JIMENG_ACCESS_KEY_ID, JIMENG_SECRET_ACCESS_KEY	即夢（Jimeng）火山引擎憑證
ARK_API_KEY	豆包（Seedream）火山引擎 ARK API 金鑰
<PROVIDER>_IMAGE_MODEL	個別提供者的模型覆蓋（OPENAI_IMAGE_MODEL、GOOGLE_IMAGE_MODEL、DASHSCOPE_IMAGE_MODEL、ZAI_IMAGE_MODEL/BIGMODEL_IMAGE_MODEL、MINIMAX_IMAGE_MODEL、OPENROUTER_IMAGE_MODEL、REPLICATE_IMAGE_MODEL、JIMENG_IMAGE_MODEL、SEEDREAM_IMAGE_MODEL、AGNES_IMAGE_MODEL）
AZURE_OPENAI_DEPLOYMENT（別名 AZURE_OPENAI_IMAGE_MODEL）	Azure 預設部署名稱
<PROVIDER>_BASE_URL	個別提供者的端點 (Endpoint) 覆蓋
AZURE_API_VERSION	Azure 圖片 API 版本（預設 2025-04-01-preview）
JIMENG_REGION	即夢區域（預設 cn-north-1）
OPENAI_IMAGE_API_DIALECT	openai-native | ratio-metadata
OPENROUTER_HTTP_REFERER, OPENROUTER_TITLE	可選的 OpenRouter 歸因資訊 (Attribution)
BAOYU_IMAGE_GEN_MAX_WORKERS	覆蓋批次 Worker 數量上限
BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY	個別提供者的並發限制（例如 BAOYU_IMAGE_GEN_REPLICATE_CONCURRENCY；codex-cli 請使用 BAOYU_IMAGE_GEN_CODEX_CLI_CONCURRENCY）
BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS	個別提供者的啟動間隔時間
BAOYU_CODEX_IMAGEGEN_BIN	覆蓋 codex-cli 提供者的 codex-imagegen 包裝腳本路徑（預設：隨附的 scripts/codex-imagegen/main.ts；支援 .ts 或舊版 .sh/二進位檔）
BAOYU_CODEX_IMAGEGEN_CACHE_DIR	啟用 codex-cli 提供者的冪等性快取（預設關閉）
BAOYU_CODEX_IMAGEGEN_TIMEOUT_MS	codex-cli 提供者每次嘗試 codex exec 的超時時間（預設：300000 毫秒）
BAOYU_CODEX_IMAGEGEN_RETRIES	codex-cli 提供者在遇到可重試錯誤時的包裝層重試次數（預設：2）
BAOYU_CODEX_IMAGEGEN_LOG_FILE	附加 codex-cli 提供者的 JSONL 診斷日誌

載入優先順序：CLI 參數 > EXTEND.md > 環境變數 > <cwd>/.baoyu-skills/.env > ~/.baoyu-skills/.env

Codex/ChatGPT OAuth is not an OpenAI API key

--provider openai --model gpt-image-2 使用標準的 OpenAI Images API（/v1/images/generations 或 /v1/images/edits），並且需要 OPENAI_API_KEY。Codex 或 ChatGPT 桌面版的登入屬於不同的權限，無法直接替換 OPENAI_API_KEY；請勿將 Codex OAuth token 直接貼入 OPENAI_API_KEY 中，或僅將 OPENAI_BASE_URL 設定為 Codex 後端。

若使用者希望在沒有 OpenAI API 金鑰的情況下使用其 Codex 訂閱 / GPT Image 2 權限，請透過 Codex 原生後端進行路由，而非使用此 Skill 的 openai 提供者：

• 在 Codex runtime 中：使用原生的 imagegen skill/tool。
• 在已安裝並登入 codex CLI 的非 Codex runtime 中：使用 baoyu-image-gen --provider codex-cli（推薦 — 這能提供與其他提供者相同的重試 / 快取 / 批次流程）。該提供者會衍生 (spawn) 隨附的 scripts/codex-imagegen/main.ts；獨立呼叫者亦可在上游 packages/baoyu-codex-imagegen/src/main.ts 找到相同程式碼。
• 在帶有原生 image_generate 工具的 Hermes runtime 中：使用該工具作為備用方案，並說明參考圖片是直接傳遞還是從提取的特徵中重構。

切勿修改現有的 openai 提供者使其隱式消耗 Codex OAuth。一等公民 (First-class) 的 Codex-CLI 路徑是專用的 codex-cli 提供者...

<!-- truncated for translation batch; full body continues in source -->