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

参考图身份保持

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

• 优先选用少量经过筛选的现有参考图（通常为 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	指定服务商（默认：自动检测）
--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

Codex/ChatGPT OAuth 不是 OpenAI API 密钥

--provider openai --model gpt-image-2 使用标准 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-cover-image），请使用仓库级 scripts/codex-imagegen.sh 包装脚本。从插件/仓库根目录解析其路径，并传入绝对提示词/输出/参考文件路径。
• 在 Hermes 运行时，如果有原生 image_generate 工具：将其用作回退方案，并说明参考图是直接传入，还是根据提取的特征重建。

请勿修改现有的 openai 提供方，使其悄悄使用 Codex OAuth。如果要为 baoyu-imagine 添加一流的 Codex OAuth 支持，请将其实现为独立提供方（例如 openai-codex），并为其配置独立的身份验证、路由、请求格式、文档和测试。请参阅 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。仍可通过 --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 次
• 宽高比无效 → 发出警告，并使用默认值继续
• 引用图片不受提供商或模型支持 → 返回错误并提供修复提示

Codex image2 回退方案

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

参考资料

文件	内容
references/usage-examples.md	跨提供商和批量模式的扩展 CLI 示例
references/codex-oauth-vs-openai-api-key.md	为什么无法通过 baoyu-imagine 的标准 OpenAI API 密钥提供商使用 Codex/ChatGPT OAuth 的 image2 权益
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/config/preferences-schema.md	EXTEND.md 架构
references/config/first-time-setup.md	首次设置流程

扩展支持

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