baoyu-image-gen

图像生成（AI SDK）

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

用户输入工具

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

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

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

脚本目录

{baseDir} = 此 SKILL.md 所在目录。下方所有 scripts/... 路径均相对于 {baseDir}。主脚本：{baseDir}/scripts/main.ts。批处理负载辅助脚本：{baseDir}/scripts/build-batch.ts。解析 ${BUN_X}：优先使用 bun；否则使用 npx -y bun；否则建议运行 brew install oven-sh/bun/bun。

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

任何图像生成开始前都必须完成此步骤——在 EXTEND.md 存在之前，生成操作会被阻止。

按顺序检查以下路径；命中第一个即停止：

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

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

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

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.5-flare

# Codex CLI (uses logged-in Codex subscription — no OPENAI_API_KEY required; requires `codex` on PATH)
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider codex-cli --ar 16:9

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

# Build a batch file from outline.md + prompts/ (e.g. baoyu-article-illustrator output)
${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

保持参考图中的主体身份

当用户希望保留参考图中的人物或物体时：

• 优先使用少量经过筛选的现有参考图（通常为 2–4 张），而不是大量图片；体积达数 MB 的大型参考图可能导致流式服务商不稳定。
• 在提示词中明确说明这些参考图中的主体是同一个，并要求输出使用该主体的身份。避免冗长、泛泛的面部特征描述，因为这可能导致模型合成一个长相相似的新人物。
• 除非用户明确要求，否则不要将新生成的输出用作参考图；生成的参考图会加剧身份偏移。
• 如果结果过于精致或像网红风格，请减少风格化参考图，并添加明确的反美化限制（不瘦脸、不放大眼睛、不浓妆、不拍商业旅行大片、不做过度磨皮）。
• 如果希望主体看起来更年轻或年长，请保留面部特征，通过服装、姿势、场景和造型来体现年龄；不要要求模型改变面部身份。

选项

选项	描述
--prompt <text>、-p	提示词文本
--promptfiles <files...>	从文件中读取提示词（拼接后使用）
--image <path>	输出图像路径（单图模式下必需）
--batchfile <path>	用于多图生成的 JSON 批处理文件
--jobs <count>	批处理模式下的工作线程数（默认：自动，最大值取自配置，内置默认值为 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.5-* 和 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、AGNES_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；对 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 ms）
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 不是 OpenAI API 密钥

--provider openai --model gpt-image-2.5-flare 使用标准的 OpenAI Images API（/v1/images/generations 或 /v1/images/edits），并且需要 OPENAI_API_KEY。Codex 或 ChatGPT 桌面端登录属于不同的授权，不能直接替代 OPENAI_API_KEY；请勿将 Codex OAuth 令牌粘贴到 OPENAI_API_KEY 中，也不要只设置 OPENAI_BASE_URL 指向 Codex 后端。

如果用户想在没有 OpenAI API 密钥的情况下使用其 Codex 订阅 / GPT Image 2 授权，请改用 Codex 原生后端，而不是此技能的 openai 提供方：

• 在 Codex 运行时中：使用原生的 imagegen 技能/工具。
• 在已安装并登录 codex CLI 的非 Codex 运行时中：使用 baoyu-image-gen --provider codex-cli（首选——它能提供与其他提供方相同的重试 / 缓存 / 批处理流程）。该提供方会启动捆绑的 scripts/codex-imagegen/main.ts；独立调用方可在上游的 packages/baoyu-codex-imagegen/src/main.ts 中找到相同代码。
• 在带有原生 image_generate 工具的 Hermes 运行时中：将该工具用作备用方案，并说明参考图像是直接传入，还是根据提取的特征重建。

请勿修改现有的 openai 提供方，使其暗中使用 Codex OAuth。首选的 Codex-CLI 路径是专用的 codex-cli 提供方，它有自己的身份验证（Codex 登录）、路由（codex exec）、请求格式和测试。请参阅 references/codex-oauth-vs-openai-api-key.md。

模型解析

以下优先级（从高到低）适用于每个提供商：

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

对于 OpenAI，内置默认值为 gpt-image-2.5-flare（速度快、延迟最低）。gpt-image-2.5-sunburst 是能力最强的变体，适用于复杂场景和精细编辑；也可以通过 --model 或 OPENAI_IMAGE_MODEL 选择 gpt-image-2、gpt-image-1.5、gpt-image-1 以及带日期的 GPT Image 快照（例如 gpt-image-2.5-flare-2026-09-08、gpt-image-2-2026-04-21）。

对于 Google，内置默认值为 gemini-3-pro-image。gemini-3.1-flash-image 是速度更快、成本更低的选项，而 gemini-3.1-flash-lite-image 成本最低——它只生成 1K 输出，因此 --quality 2k / --imageSize 2K|4K 会被限制为 1K，并显示警告。

对于 DashScope，内置默认值为 qwen-image-2.0-pro；qwen-image-3.0-pro 是最新的旗舰型号，且使用相同的尺寸规则。

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

EXTEND.md 的优先级高于环境变量：如果 EXTEND.md 设置了 default_model.google: "gemini-3-pro-image"，而环境变量设置了 GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image，则以 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
Codex CLI（封装内置的 scripts/codex-imagegen/；Codex 登录，无需 OPENAI_API_KEY）	references/providers/codex-cli.md
Agnes（agnes-image-2.5-flash、支持参考图像）	references/providers/agnes.md

提供商选择

1. 提供了 --ref，但未提供 --provider → 自动选择 Google → OpenAI → Azure → OpenRouter → Replicate → Seedream → MiniMax → Agnes（MiniMax 的主体参考更专注于角色／肖像一致性）
2. 指定了 --provider → 使用该提供商（如果提供了 --ref，则必须是 google/openai/azure/openrouter/replicate/seedream/minimax/codex-cli/agnes）
3. 仅存在一个 API 密钥 → 使用该提供商
4. 存在多个密钥 → 默认优先级：Google → OpenAI → Azure → OpenRouter → DashScope → Z.AI → MiniMax → Replicate → Jimeng → Seedream → Agnes
5. codex-cli 永远不会自动选择——在 EXTEND.md 中设置 default_provider: codex-cli，或传入 --provider codex-cli。它会通过捆绑的 scripts/codex-imagegen/main.ts TS 入口文件（使用 bun 运行）启动 codex exec，并使用用户的 Codex 订阅（无需 OPENAI_API_KEY）。要求 PATH 中有 codex，且已通过 codex login 登录。

质量预设

预设	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.5-* 和 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.5-* 和 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）	批量生成——使用 {baseDir}/scripts/build-batch.ts 组装负载	大纲和提示词文件已包含所需的全部内容

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

并行行为：

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

错误处理

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

Codex image2 回退

如果 --provider openai --model gpt-image-2.5-flare 因缺少 OPENAI_API_KEY 而失败，但当前运行时具有原生图像生成后端，或仓库级 codex-imagegen 封装器可用，请改用该路径，而不是让用户一直等待。请明确说明回退方式是真正的参考图像生成，还是仅根据提取的视觉特征通过文本提示词进行重建。参见 references/codex-image2-fallback.md。

参考资料

文件	内容
references/usage-examples.md	跨提供商和批处理模式的扩展 CLI 示例
references/codex-oauth-vs-openai-api-key.md	为什么 Codex/ChatGPT OAuth 的 image2 权益无法通过 baoyu-image-gen 的标准 OpenAI API 密钥提供商使用
references/codex-image2-fallback.md	缺少 OpenAI API 凭据但 Codex/原生图像生成可用时的实用回退行为
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/providers/agnes.md	Agnes (agnes-image-2.5-flash) 的尺寸、参考图和限制
references/config/preferences-schema.md	EXTEND.md 架构
references/config/first-time-setup.md	首次设置流程

扩展支持

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