baoyu-image-gen

图像生成（AI SDK）

基于官方 API 的图像生成。支持 OpenAI、Google、DashScope（阿里通义万象）、Replicate 和 xheai（中转站）提供商。

脚本目录

Agent 执行：

1. SKILL_DIR = 此 SKILL.md 文件所在目录
2. 脚本路径 = ${SKILL_DIR}/scripts/main.ts

步骤 0：加载偏好设置 ⛔ 阻塞

重要：必须先完成此步骤，才能生成任何图像。请勿跳过或延后。

检查 EXTEND.md 是否存在（优先级：项目 → 用户）：

test -f .baoyu-skills/baoyu-image-gen/EXTEND.md && echo "project"
test -f "$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md" && echo "user"

结果	操作
找到	加载、解析并应用设置。如果 default_model.[provider] 为 null → 仅询问模型（流程 2）
未找到	⛔ 运行首次设置（references/config/first-time-setup.md）→ 保存 EXTEND.md → 然后继续

重要：如果未找到，必须在生成任何图像前使用 AskUserQuestion 完成完整设置（提供商 + 模型 + 质量 + 保存位置）。创建 EXTEND.md 前禁止生成图像。

路径	位置
.baoyu-skills/baoyu-image-gen/EXTEND.md	项目目录
$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md	用户主目录

EXTEND.md 支持：默认提供商 | 默认质量 | 默认宽高比 | 默认图像尺寸 | 默认模型

架构：references/config/preferences-schema.md

用法

# ⚠️ 长prompt用 --promptfiles 或双引号包裹，避免换行解析错误
# 推荐: npx -y bun "${SKILL_DIR}/scripts/main.ts" -p "长prompt" --image out.png
# 或:   npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles prompt.txt --image out.png

# Basic
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image cat.png

# With aspect ratio
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9

# High quality
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k

# From prompt files
npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png

# With reference images (Google multimodal or OpenAI edits)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png

# With reference images (explicit provider/model)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make blue" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png

# Specific provider
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider openai

# DashScope (阿里通义万象)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope

# Replicate (google/nano-banana-pro)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate

# Replicate with specific model
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate --model google/nano-banana

# xheai (中转站 - 兼容 OpenAI 格式)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider xheai

# xheai with nano-banana-2
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider xheai --model nano-banana-2

选项

选项	描述
--prompt <text>, -p	提示词文本
--promptfiles <files...>	从文件读取提示词（拼接）
--image <path>	输出图像路径（必需）
--provider google|openai|dashscope|replicate|xheai	强制指定提供商（默认：自动检测）
--model <id>, -m	模型 ID（Google：gemini-3-pro-image-preview、gemini-3.1-flash-image-preview；OpenAI：gpt-image-1.5；xheai：gemini-3.1-flash-image-preview、nano-banana-2）
--ar <ratio>	宽高比（例如，16:9、1:1、4:3）
--size <WxH>	尺寸（例如，1024x1024）
--quality normal|2k	质量预设（默认：2k）
--imageSize 1K|2K|4K	Google 的图像尺寸（默认：根据质量设置）
--ref <files...>	参考图像。Google 多模态（gemini-3-pro-image-preview、gemini-3-flash-preview、gemini-3.1-flash-image-preview）和 OpenAI 编辑（GPT Image 模型）支持此选项。如果未指定提供商：优先 Google，其次 OpenAI
--n <count>	图像数量
--json	JSON 输出

环境变量

变量	描述
OPENAI_API_KEY	OpenAI API 密钥（当 OPENAI_BASE_URL 指向 xheai.cc 时也用于 xheai）
GOOGLE_API_KEY	Google API 密钥
DASHSCOPE_API_KEY	DashScope API 密钥（阿里云）
REPLICATE_API_TOKEN	Replicate API 令牌
OPENAI_IMAGE_MODEL	OpenAI/xheai 模型覆盖设置
GOOGLE_IMAGE_MODEL	Google 模型覆盖设置
DASHSCOPE_IMAGE_MODEL	DashScope 模型覆盖设置（默认：z-image-turbo）
REPLICATE_IMAGE_MODEL	Replicate 模型覆盖设置（默认：google/nano-banana-pro）
OPENAI_BASE_URL	自定义 OpenAI 端点（设置为 https://api.xheai.cc 以使用 xheai）
GOOGLE_BASE_URL	自定义 Google 端点
DASHSCOPE_BASE_URL	自定义 DashScope 端点
REPLICATE_BASE_URL	自定义 Replicate 端点
DEBUG_ENV	设置为 1 可启用环境变量加载和提供商检测的调试输出

加载优先级：CLI 参数 > EXTEND.md > 环境变量 > <cwd>/.baoyu-skills/.env > ~/.baoyu-skills/.env

跨平台路径：~/.baoyu-skills/.env 会自动解析为：

• Windows：C:\Users\<username>\.baoyu-skills\.env
• macOS：/Users/<username>/.baoyu-skills/.env
• Linux：/home/<username>/.baoyu-skills/.env

调试模式：设置 DEBUG_ENV=1 可查看已加载的 .env 文件以及检测到的 API 密钥：

DEBUG_ENV=1 npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image cat.png

模型解析

模型优先级（从高到低），适用于所有提供商：

1. CLI 标志：--model <id>
2. EXTEND.md：default_model.[provider]
3. 环境变量：<PROVIDER>_IMAGE_MODEL（例如，GOOGLE_IMAGE_MODEL）
4. 内置默认值

EXTEND.md 优先于环境变量。如果 EXTEND.md 中有 default_model.google: "gemini-3-pro-image-preview"，且环境变量中有 GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image-preview，则以 EXTEND.md 为准。

Agent 必须在每次生成前显示模型信息：

• 显示：Using [provider] / [model]
• 显示切换提示：Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL

Replicate 模型

支持的模型格式：

• owner/name（官方模型推荐使用），例如 google/nano-banana-pro
• owner/name:version（社区模型按版本指定），例如 stability-ai/sdxl:<version>

示例：

# Use Replicate default model
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate

# Override model explicitly
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate --model google/nano-banana

提供商选择

1. 提供了 --ref，但没有 --provider → 优先自动选择 Google，然后是 OpenAI，最后是 Replicate
2. 指定了 --provider → 使用该提供商（如果有 --ref，则必须是 google、openai 或 replicate）
3. 仅有一个可用的 API 密钥 → 使用对应的提供商
4. 有多个可用的 API 密钥 → 默认使用 Google

质量预设

预设	Google imageSize	OpenAI 尺寸	用途
normal	1K	1024px	快速预览
2k（默认）	2K	2048px	封面、插画、信息图

Google imageSize：可通过 --imageSize 1K|2K|4K 覆盖

宽高比

支持：1:1、16:9、9:16、4:3、3:4、2.35:1

• Google 多模态：使用 imageConfig.aspectRatio
• Google Imagen：使用 aspectRatio 参数
• OpenAI：映射到最接近的受支持尺寸

生成模式

默认：顺序生成（一次生成一张图像）。这可确保输出稳定，也便于调试。

并行生成：仅在用户明确要求并行／并发生成时使用。

模式	使用场景
顺序（默认）	常规使用、单张图像、小批量
并行	用户明确要求、大批量（10 张及以上）

并行设置（用户要求时）：

设置	值
建议并发数	4 个子 Agent
最大并发数	8 个子 Agent
用途	用户要求并行执行大批量生成时使用

Agent 实现（仅并行模式）：

# Launch multiple generations in parallel using Task tool
# Each Task runs as background subagent with run_in_background=true
# Collect results via TaskOutput when all complete

错误处理

• 缺少 API 密钥 → 报错并提供设置说明
• 生成失败 → 自动重试一次
• 无效的宽高比 → 发出警告，使用默认值继续
• 参考图像与不受支持的提供商／模型搭配 → 报错并提示修复方法（切换到 Google 多模态：gemini-3-pro-image-preview、gemini-3.1-flash-image-preview；或使用 OpenAI GPT Image 编辑功能）

扩展支持

通过 EXTEND.md 使用自定义配置。路径和支持的选项请参阅偏好设置部分。