baoyu-image-gen

图像生成（AI SDK）

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

脚本目录

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

用法

# 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

选项

选项	描述
--prompt <text>, -p	提示词文本
--promptfiles <files...>	从文件读取提示词（合并）
--image <path>	输出图像路径（必填）
--provider google|openai|dashscope|replicate	强制指定提供方（默认：google）
--model <id>, -m	模型 ID（Google：gemini-3-pro-image-preview、gemini-3.1-flash-image-preview；OpenAI：gpt-image-1.5）
--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 密钥
GOOGLE_API_KEY	Google API 密钥
DASHSCOPE_API_KEY	DashScope API 密钥（阿里云）
REPLICATE_API_TOKEN	Replicate API 令牌
OPENAI_IMAGE_MODEL	OpenAI 模型覆盖值
GOOGLE_IMAGE_MODEL	Google 模型覆盖值
DASHSCOPE_IMAGE_MODEL	DashScope 模型覆盖值（默认：z-image-turbo）
REPLICATE_IMAGE_MODEL	Replicate 模型覆盖值（默认：google/nano-banana-pro）
OPENAI_BASE_URL	自定义 OpenAI 端点
GOOGLE_BASE_URL	自定义 Google 端点
DASHSCOPE_BASE_URL	自定义 DashScope 端点
REPLICATE_BASE_URL	自定义 Replicate 端点

加载优先级：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 为准。

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. 有多个可用提供商 → 默认使用 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 使用自定义配置。路径和支持的选项请参阅 Preferences 部分。

OpenClaw 迁移说明

• 迁移模式：优先使用 OpenClaw 原生方式
• 保留的目录：
  • scripts：是
  • references：是
  • prompts：否
• 外部依赖：bun、external-ai-api
• 风险级别：中
• 检测到的环境变量：API、DASHSCOPE_API_KEY、DASHSCOPE_BASE_URL、GOOGLE_API_KEY、GOOGLE_BASE_URL、HOME、OPENAI_API_KEY、OPENAI_BASE_URL、REPLICATE_API_TOKEN、REPLICATE_BASE_URL
• 配置兼容性：保留原有 .baoyu-skills/<skill>/EXTEND.md 行为，并在需要时于运行时包装器中添加兼容 OpenClaw 的路径。

OpenClaw 预检

• 当脚本示例使用 npx -y bun ... 时，确认 bun 可用。
• 执行前确认已导出所需的 API 凭据。

检测到的环境变量：API、DASHSCOPE_API_KEY、DASHSCOPE_BASE_URL、GOOGLE_API_KEY、GOOGLE_BASE_URL、HOME、OPENAI_API_KEY、OPENAI_BASE_URL、REPLICATE_API_TOKEN、REPLICATE_BASE_URL

OpenClaw 失败回退

• 如果缺少运行时依赖，停止执行并返回准确的安装／设置命令。
• 如果 API 调用失败，建议使用显式的提供商／模型标志重试，并验证密钥权限范围。