baoyu-imagine

图像生成（AI SDK）

基于官方 API 的图像生成。支持 OpenAI GPT Image 2、Azure OpenAI、Google、OpenRouter、DashScope（阿里通义万象）、Z.AI GLM-Image、MiniMax、Jimeng（即梦）、Seedream（豆包）和 Replicate。

用户输入工具

当此技能提示用户时，请按照以下工具选择规则（按优先级排序）：

1. 优先使用当前 Agent 运行时提供的内置用户输入工具，例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何等效工具。
2. 回退方案：如果没有此类工具，则输出带编号的纯文本消息，并请用户针对每个问题回复所选编号或答案。
3. 批量提问：如果工具支持每次调用提出多个问题，则将所有适用问题合并到一次调用中；如果只支持单问题，则按照优先级逐个提问。

下方的 AskUserQuestion 具体示例仅供参考；在其他运行时中请替换为本地等效工具。

脚本目录

{baseDir} = 此 SKILL.md 所在目录。主脚本：{baseDir}/scripts/main.ts。解析 ${BUN_X}：优先使用 bun；否则使用 npx -y bun；再否则建议运行 brew install oven-sh/bun/bun。

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

在生成任何图像之前，必须完成此步骤——在 EXTEND.md 存在之前，不得进行生成。

按以下顺序检查这些路径；使用第一个匹配项：

路径	范围
.baoyu-skills/baoyu-imagine/EXTEND.md	项目
${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-imagine/EXTEND.md	XDG
$HOME/.baoyu-skills/baoyu-imagine/EXTEND.md	用户主目录

• 找到 → 加载、解析并应用。如果 default_model.[provider] 为 null → 仅询问模型。
• 未找到 → 使用 AskUserQuestion 执行首次设置（references/config/first-time-setup.md），收集服务提供方、模型、质量和保存位置。保存 EXTEND.md，然后继续。完成前不得生成图像。

兼容旧版：如果 .baoyu-skills/baoyu-image-gen/EXTEND.md 存在且新路径不存在，运行时会将其重命名为 baoyu-imagine。如果两者都存在，运行时不会更改它们，并会使用新路径。

EXTEND.md 键：默认服务提供方、默认质量、默认纵横比、默认图像尺寸、OpenAI 图像 API 方言、默认模型、批处理工作线程上限、服务提供方专属批处理限制。架构：references/config/preferences-schema.md。

用法

最小可用示例——完整示例（包括各服务提供方的调用方式和批处理模式）请参阅 references/usage-examples.md。

# Basic
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png

# With aspect ratio and high quality
${BUN_X} {baseDir}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9 --quality 2k

# Prompt from files
${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md content.md --image out.png

# With reference image
${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png

# Specific provider
${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

# Batch mode
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4

选项

选项	描述
--prompt <text>, -p	提示词文本
--promptfiles <files...>	从文件中读取提示词（拼接）
--image <path>	输出图像路径（单图模式下必需）
--batchfile <path>	用于生成多张图像的 JSON 批处理文件
--jobs <count>	批处理模式下的工作线程数（默认：自动，最大值取自配置，内置默认值为 10）
--provider google|openai|azure|openrouter|dashscope|zai|minimax|jimeng|seedream|replicate	指定服务提供商（默认：自动检测）
--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 的端点方言——对于要求使用宽高比 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 输出

环境变量

变量	描述
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 令牌
JIMENG_ACCESS_KEY_ID, JIMENG_SECRET_ACCESS_KEY	Jimeng（即梦）Volcengine 凭据
ARK_API_KEY	Seedream（豆包）Volcengine 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）
AZURE_OPENAI_DEPLOYMENT（别名 AZURE_OPENAI_IMAGE_MODEL）	Azure 默认部署
<PROVIDER>_BASE_URL	按服务提供商覆盖端点
AZURE_API_VERSION	Azure 图像 API 版本（默认 2025-04-01-preview）
JIMENG_REGION	Jimeng 区域（默认 cn-north-1）
OPENAI_IMAGE_API_DIALECT	openai-native | ratio-metadata
OPENROUTER_HTTP_REFERER, OPENROUTER_TITLE	可选的 OpenRouter 归属信息
BAOYU_IMAGE_GEN_MAX_WORKERS	覆盖批处理工作线程上限
BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY	按服务提供商设置并发数（例如：BAOYU_IMAGE_GEN_REPLICATE_CONCURRENCY）
BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS	按服务提供商设置启动间隔

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

模型解析

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

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

对于 OpenAI，内置默认值为 gpt-image-2。仍可通过 --model 或 OPENAI_IMAGE_MODEL 选择 gpt-image-1.5、gpt-image-1 和 GPT Image 快照版本。

对于 Azure，--model / default_model.azure 指的是 Azure 部署名称。AZURE_OPENAI_DEPLOYMENT 是首选环境变量；AZURE_OPENAI_IMAGE_MODEL 作为向后兼容的别名保留。如果 Azure 部署以底层模型命名，请使用 gpt-image-2；否则请使用确切的自定义部署名称。

EXTEND.md 会覆盖环境变量：如果 EXTEND.md 设置了 default_model.google: "gemini-3-pro-image-preview"，而环境变量设置了 GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image-preview，则以 EXTEND.md 为准。

每次生成前显示模型信息：

• Using [provider] / [model]
• Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL

OpenAI 兼容网关方言

provider=openai 表示身份验证和路由入口点兼容 OpenAI。它并不保证上游图像 API 使用 OpenAI 原生语义。当网关要求使用其他线缆格式时，请在 EXTEND.md 中设置 default_image_api_dialect，或设置 OPENAI_IMAGE_API_DIALECT，或使用 --imageApiDialect：

• openai-native：像素 size（1536x1024）和 OpenAI 原生质量字段
• ratio-metadata：宽高比 size（16:9），以及 metadata.resolution（1K|2K|4K）和 metadata.orientation

OpenAI 原生 API 或严格克隆版本请使用 openai-native；对于 Gemini 或类似模型前的兼容网关，可尝试 ratio-metadata。当前限制：ratio-metadata 仅适用于文本生成图像；参考图像编辑仍需要使用 openai-native 或原生支持编辑的提供商。

提供商专属指南

每个提供商都有各自的特性（模型系列、尺寸规则、参考图支持、限制）。当用户选择相应提供商或询问非默认行为时，请查阅以下指南：

提供商	参考资料
DashScope（Qwen-Image 系列、自定义尺寸）	references/providers/dashscope.md
Z.AI（GLM-Image、cogview-4）	references/providers/zai.md
MiniMax（image-01、主体参考）	references/providers/minimax.md
OpenRouter（多模态模型、/chat/completions 流程）	references/providers/openrouter.md
Replicate（nano-banana、Seedream、Wan）	references/providers/replicate.md

提供商选择

1. 提供了 --ref 且未指定 --provider → 自动选择 Google → OpenAI → Azure → OpenRouter → Replicate → Seedream → MiniMax（MiniMax 的主体参考更专用于角色／肖像一致性）
2. 指定了 --provider → 使用该提供商（如果有 --ref，则必须是 google/openai/azure/openrouter/replicate/seedream/minimax）
3. 仅存在一个 API 密钥 → 使用对应的提供商
4. 存在多个密钥 → 默认优先级：Google → OpenAI → Azure → OpenRouter → DashScope → Z.AI → MiniMax → Replicate → Jimeng → Seedream

质量预设

预设	Google imageSize	OpenAI size	OpenRouter size	Replicate 分辨率	用途
normal	1K	目标 1024px	1K	1K	快速预览
2k（默认）	2K	目标 2048px	2K	2K	封面、插图、信息图

Google/OpenRouter 的 imageSize 可通过 --imageSize 1K|2K|4K 覆盖。

对于 OpenAI 原生 gpt-image-2，normal 对应 quality=medium，并选择接近请求宽高比的低延迟有效尺寸；2k 对应 quality=high 和 2048px 级别的尺寸，例如 2048x2048、2048x1152 或 1152x2048。如需有效的自定义尺寸或 4K 输出，请使用显式的 --size，例如 3840x2160。

宽高比

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

• Google 多模态：imageConfig.aspectRatio
• OpenAI：gpt-image-2 会针对请求的比例使用最接近的有效自定义尺寸；较早的 GPT Image 和 DALL·E 模型使用最接近的受支持固定尺寸
• OpenRouter：imageGenerationOptions.aspect_ratio；如果只提供 --size <WxH>，则会推断比例
• Replicate：行为因模型而异——google/nano-banana* 使用 aspect_ratio，bytedance/seedream-* 使用 Replicate 文档中说明的比例，Wan 2.7 会将 --ar 映射为具体的 size
• MiniMax：使用官方的 aspect_ratio 值；如果提供了 --size <WxH> 但未提供 --ar，则会为 image-01 发送 width/height

生成模式

默认：顺序生成。批量并行：当 --batchfile 包含 2 个或更多待处理任务时自动启用。

情况	首选方式	原因
一张图片，或 1–2 张简单图片	顺序生成	协调开销更低，更易调试
多张图片，且已有保存的提示词文件	批量（--batchfile）	重用已定稿的提示词，应用统一的限流和重试策略，吞吐量可预测
每张图片仍需单独推理、编写提示词或探索风格	子 Agent	任务仍处于探索阶段，每张图片都需要独立分析
输入为 outline.md + prompts/（例如来自 baoyu-article-illustrator）	批量——使用 scripts/build-batch.ts 组装载荷	大纲和提示词文件已包含所需的全部内容

经验法则：提示词文件保存后，如果任务变成“生成所有这些图片”，优先选择批量生成，而不是子 Agent。只有当生成过程需要结合逐张思考或不同方向的创意探索时，才使用子 Agent。

并行行为：

• 默认工作线程数为自动设置，受配置限制，内置默认值为 10
• 仅在批量模式下应用针对特定提供商的限流；默认设置经过调优，可提高吞吐量并避免 RPM 突增
• 使用 --jobs <count> 覆盖
• 每张图片最多重试 3 次
• 最终输出包含成功数、失败数以及每张图片失败的原因

错误处理

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

参考资料

文件	内容
references/usage-examples.md	跨提供商和批量模式的扩展 CLI 示例
references/providers/dashscope.md	DashScope 系列、尺寸和限制
references/providers/zai.md	Z.AI GLM-image / cogview-4
references/providers/minimax.md	MiniMax image-01 + 主体参考
references/providers/openrouter.md	OpenRouter 多模态流程
references/providers/replicate.md	Replicate 支持的系列和防护措施
references/config/preferences-schema.md	EXTEND.md 架构
references/config/first-time-setup.md	首次设置流程

扩展支持

通过 EXTEND.md 使用自定义配置。路径和架构请参阅步骤 0。