图像生成 (AI SDK)

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

脚本目录

代理执行流程：

1. {baseDir} = 此 SKILL.md 文件所在的目录
2. 脚本路径 = {baseDir}/scripts/main.ts
3. 解析 ${BUN_X} 运行时：如果已安装 bun → 使用 bun；如果 npx 可用 → 使用 npx -y bun；否则建议安装 bun

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

关键：此步骤必须在任何图像生成之前完成。切勿跳过或延迟。

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

# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-image-gen/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-image-gen/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md" && echo "user"

# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-image-gen/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-image-gen/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md") { "user" }

关键：如果未找到，在生成任何图像之前，必须使用 AskUserQuestion 完成完整的设置（提供商 + 模型 + 质量 + 保存位置）。在创建 EXTEND.md 之前，生成被阻塞。

EXTEND.md 支持配置：默认提供商 | 默认质量 | 默认宽高比 | 默认图像尺寸 | 默认模型 | 批量工作进程上限 | 提供商特定批量限制

模式：references/config/preferences-schema.md

使用方法

# 基础用法
${BUN_X} {baseDir}/scripts/main.ts --prompt "一只猫" --image cat.png

# 指定宽高比
${BUN_X} {baseDir}/scripts/main.ts --prompt "风景画" --image out.png --ar 16:9

# 高质量
${BUN_X} {baseDir}/scripts/main.ts --prompt "一只猫" --image out.png --quality 2k

# 从提示词文件读取
${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md content.md --image out.png

# 带参考图像（Google 多模态或 OpenAI 编辑）
${BUN_X} {baseDir}/scripts/main.ts --prompt "变成蓝色" --image out.png --ref source.png

# 带参考图像（显式指定提供商/模型）
${BUN_X} {baseDir}/scripts/main.ts --prompt "变成蓝色" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png

# 指定提供商
${BUN_X} {baseDir}/scripts/main.ts --prompt "一只猫" --image out.png --provider openai

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

# Replicate (google/nano-banana-pro)
${BUN_X} {baseDir}/scripts/main.ts --prompt "一只猫" --image out.png --provider replicate

# Replicate 指定模型
${BUN_X} {baseDir}/scripts/main.ts --prompt "一只猫" --image out.png --provider replicate --model google/nano-banana

# 批量模式，使用已保存的提示词文件
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json

# 批量模式，显式指定工作进程数
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4 --json

批量文件格式

{
  "jobs": 4,
  "tasks": [
    {
      "id": "主图",
      "promptFiles": ["prompts/hero.md"],
      "image": "out/hero.png",
      "provider": "replicate",
      "model": "google/nano-banana-pro",
      "ar": "16:9",
      "quality": "2k"
    },
    {
      "id": "图表",
      "promptFiles": ["prompts/diagram.md"],
      "image": "out/diagram.png",
      "ref": ["references/original.png"]
    }
  ]
}

promptFiles、image 和 ref 中的路径相对于批处理文件所在的目录进行解析。jobs 是可选的（会被 CLI 的 --jobs 覆盖）。也接受不带 jobs 包装器的顶级数组格式。

选项

环境变量

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

模型解析

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

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 为准。

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

• 显示：正在使用 [提供商] / [模型]
• 显示切换提示：切换模型：--model <ID> | EXTEND.md default_model.[provider] | 环境变量 <PROVIDER>_IMAGE_MODEL

Replicate 模型

支持的模型格式：

• 所有者/名称（推荐用于官方模型），例如 google/nano-banana-pro
• 所有者/名称:版本（社区模型，按版本），例如 stability-ai/sdxl:<版本>

示例：

# 使用 Replicate 默认模型
${BUN_X} {baseDir}/scripts/main.ts --prompt "一只猫" --image out.png --provider replicate

# 显式覆盖模型
${BUN_X} {baseDir}/scripts/main.ts --prompt "一只猫" --image out.png --provider replicate --model google/nano-banana

提供商选择

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

质量预设

Google imageSize：可使用 --imageSize 1K|2K|4K 覆盖

宽高比

支持的宽高比：1:1，16:9，9:16，4:3，3:4，2.35:1

• Google 多模态：使用 imageConfig.aspectRatio
• OpenAI：映射到最接近的支持尺寸
• Replicate：将 aspect_ratio 传递给模型；当提供了 --ref 但未指定 --ar 时，默认为 match_input_image

生成模式

默认：顺序生成。

批量并行生成：当 --batchfile 包含 2 个或更多待处理任务时，脚本会自动启用并行生成。

执行方式选择：

经验法则：

• 一旦提示词文件已保存，且任务是“生成所有这些图像”，优先使用批量而非子代理
• 仅当生成过程需要结合每张图像的思考、重写或不同的创意探索时，才使用子代理

并行行为：

• 默认工作进程数是自动的，受配置上限限制，内置默认值为 10
• 提供商特定的限流仅在批量模式下应用，内置默认值旨在提高吞吐量，同时避免明显的 RPM 突发
• 您可以使用 --jobs <数量> 覆盖工作进程数
• 每张图像最多自动重试 3 次
• 最终输出包括成功数、失败数以及每张图像的失败原因

错误处理

• 缺少 API 密钥 → 显示错误并给出设置说明
• 生成失败 → 每张图像最多自动重试 3 次
• 无效的宽高比 → 发出警告，使用默认值继续
• 不支持的提供商/模型使用参考图像 → 显示错误并给出修复提示

扩展支持

通过 EXTEND.md 进行自定义配置。有关路径和受支持选项，请参阅偏好设置部分。