baoyu-image-gen

图像生成 (AI SDK)

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

用户输入工具选择规则

当此 Skill 需要向用户发起交互询问时，请遵循以下工具选择优先级：

优先使用当前 Agent 运行时暴露的内置交互工具——例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何同等工具。
降级方案：若不存在此类交互工具，请输出带编号的纯文本消息，并引导用户按编号回复对应的选项或答案。
批量合并：若工具支持单次调用询问多个问题，请将所有适用问题合并到单次调用中；若仅支持单问题询问，请按优先级顺序逐个发起。

下文提及的 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 → 仅针对模型发起询问。
未找到文件 → 运行首次初始化流程（参照 references/config/first-time-setup.md），通过 AskUserQuestion 收集 Provider + 模型 + 画质 + 保存路径。保存为 EXTEND.md 后方可继续。在此步骤完成前切勿直接生成图像。

旧版本兼容逻辑：若存在 .baoyu-skills/baoyu-imagine/EXTEND.md 且新路径不存在，运行时会自动将其重命名为 baoyu-image-gen。若两者同时存在，运行时将保持现状并优先使用新路径下的配置。

EXTEND.md 配置项说明：默认 Provider、默认画质、默认宽高比、默认图像尺寸、OpenAI 图像 API 方言、默认模型列表、批量 Worker 上限、特定 Provider 的并发限制。模式定义见：references/config/preferences-schema.md。

用法说明

以下为最小工作示例——完整示例（含针对各 Provider 的具体调用及批量生成模式）请参阅 references/usage-examples.md。

保持参考图特征一致性的 Prompt 编写规则

当用户希望在参考图（垫图）的基础上保留真实人物/角色/物体的特征时，切勿用一段漫长泛化的描述替代参考图。推荐使用简短、强约束的特征保持语言：

“请保持参考图中的人物/物体为同一身份/主体。切勿重新设计或生成外观相似的新主体。”
“仅改变场景、服装、姿态、光影、渲染风格和构图。严格保留参考图中的面部、身材比例、发型、核心配饰及整体身份特征。”
若使用多张参考图，请明确说明它们属于同一主体，应共同定义主体身份。

避坑指南：类似“东亚年轻女性、椭圆脸、明亮双眸……”这种冗长描述，容易导致模型去合成一个符合描述的新人，而非保持参考图中人物的特征。

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

# 指定宽高比与高画质
${BUN_X} {baseDir}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9 --quality 2k

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

# 使用参考图（垫图）
${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png

# 指定特定 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

# Codex CLI（使用已登录的 Codex 订阅 — 无需 OPENAI_API_KEY；要求 PATH 中存在 `codex` 命令）
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider codex-cli --ar 16:9

# 批量生成模式
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4

# 从 outline.md + prompts/ 构建批量任务文件（例如 baoyu-article-illustrator 的输出）
${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 张），避免传入过多图片；数兆大小的大图容易引发流式 Provider 的连接不稳定。
在 Prompt 中明确强调所有参考图均为同一主体，生成结果必须继承该身份特征。避免使用冗长的面部特征描写，这反而会导致模型重新合成一个看似相似的新人。
除非用户明确要求，否则切勿将新生成的图片再作为参考图传入；生成图迭代参考会加剧特征漂移。
若生成结果过于精致或自带“网红感/滤镜感”，请减少风格化参考图，并加入明确的抗美化约束（禁止瘦脸、大眼、浓妆、商业旅拍风、过度磨皮）。
若需要改变主体的年龄感（变年轻/变老），应在保留面部特征的前提下，通过服装、姿态、场景及造型来表现年龄差异，不要直接要求模型修改面部身份特征。

参数选项

参数	说明
`--prompt <text>`, `-p`	Prompt 文本
`--promptfiles <files...>`	从文件读取 Prompt（多个文件会自动拼接）
`--image <path>`	输出图片路径（单图生成模式下必填）
`--batchfile <path>`	用于多图生成的 JSON 批量任务文件
`--jobs <count>`	批量模式下的 Worker 线程数（默认：自动，上限取配置值，内置默认值 10）
`--provider google\|openai\|azure\|openrouter\|dashscope\|zai\|minimax\|jimeng\|seedream\|replicate\|codex-cli\|agnes`	强制指定 Provider（默认：自动检测；`codex-cli` 绝不会被自动选中 — 必须通过 CLI 或 EXTEND.md 显式指定）
`--model <id>`, `-m`	模型 ID — 默认值与允许值请参阅各 Provider 参考文档
`--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 的图像尺寸（默认：根据 quality 推导）
`--imageApiDialect openai-native\|ratio-metadata`	OpenAI 兼容端点的 API 方言 — 对于预期接收宽高比 `size` 加 `metadata.resolution` 的网关，请使用 `ratio-metadata`
`--ref <files...>`	参考图。支持的 Provider/模型包括：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`。不支持的包括：即梦、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 Token
`JIMENG_ACCESS_KEY_ID`, `JIMENG_SECRET_ACCESS_KEY`	即梦（火山引擎）凭证
`ARK_API_KEY`	豆包 Seedream（火山引擎方舟 ARK）API 密钥
`<PROVIDER>_IMAGE_MODEL`	按 Provider 覆盖模型（`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 默认 Deployment
`<PROVIDER>_BASE_URL`	按 Provider 覆盖 Endpoint
`AZURE_API_VERSION`	Azure 图像 API 版本（默认 `2025-04-01-preview`）
`JIMENG_REGION`	即梦服务 Region（默认 `cn-north-1`）
`OPENAI_IMAGE_API_DIALECT`	`openai-native` \| `ratio-metadata`
`OPENROUTER_HTTP_REFERER`, `OPENROUTER_TITLE`	OpenRouter 归属信息（可选）
`BAOYU_IMAGE_GEN_MAX_WORKERS`	覆盖批量 Worker 上限
`BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY`	按 Provider 设置并发度（例如 `BAOYU_IMAGE_GEN_REPLICATE_CONCURRENCY`；针对 codex-cli 使用 `BAOYU_IMAGE_GEN_CODEX_CLI_CONCURRENCY`）
`BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS`	按 Provider 设置启动时间间隔（毫秒）
`BAOYU_CODEX_IMAGEGEN_BIN`	覆盖 `codex-cli` Provider 的 codex-imagegen 封装路径（默认：内置的 `scripts/codex-imagegen/main.ts`；支持 `.ts` 或旧版 `.sh`/二进制）
`BAOYU_CODEX_IMAGEGEN_CACHE_DIR`	为 `codex-cli` Provider 启用幂等缓存（默认关闭）
`BAOYU_CODEX_IMAGEGEN_TIMEOUT_MS`	`codex-cli` Provider 单次 `codex exec` 的超时时间（默认：300000 毫秒）
`BAOYU_CODEX_IMAGEGEN_RETRIES`	`codex-cli` Provider 遇到可重试错误时在 Wrapper 侧的重试次数（默认：2）
`BAOYU_CODEX_IMAGEGEN_LOG_FILE`	为 `codex-cli` Provider 追加 JSONL 诊断日志

配置加载优先级：命令行参数 > 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 Token 直接填入 OPENAI_API_KEY，或仅将 OPENAI_BASE_URL 修改为 Codex 后端地址。

若用户希望在未配置 OpenAI API 密钥的情况下，直接使用其 Codex 订阅 / GPT Image 2 权益，请路由至 Codex 原生后端，而非使用本 Skill 的 openai Provider：

在 Codex 运行时环境：直接使用原生的 imagegen Skill/工具。
在已安装并登录 codex CLI 的非 Codex 运行时环境：使用 baoyu-image-gen --provider codex-cli（推荐方案 — 该机制可提供与其他 Provider 完全一致的重试、缓存及批量处理流程）。该 Provider 会调用内置的 scripts/codex-imagegen/main.ts；独立调用者也可以在上游的 packages/baoyu-codex-imagegen/src/main.ts 找到相同代码。
在带有原生 image_generate 工具的 Hermes 运行时环境：可将该工具作为兜底方案，并说明参考图是直接透传还是根据提取出的特征重新构建的。

切勿将现有的 openai Provider 修改为静默读取 Codex OAuth。一等的 Codex-CLI 接入路径应统一使用专用的 codex-cli Provider，该……

你可能还喜欢

docker-expert

45Kdevops-cloud

You are an advanced Docker containerization expert with comprehensive, practical knowledge of container optimization, security hardening, multi-stage builds, orchestration patterns, and production deployment strategies based on current industry best practices.