baoyu-image-gen实战：配置图像后端与可追溯的批量生成

baoyu-image-gen 是图像生成执行层：接收提示词和参考图，选择提供商与模型，把结果保存为文件。它可以被封面、配图、漫画等技能调用，但不会自动替这些上层技能完成文章分析、分镜或版式策划。

本文基于固定提交源码核对；案例为操作示例，非付费服务或账号实测。没有安装依赖、设置凭证或调用图像服务；源码列出的模型名称也不代表当前账号一定有权访问。

一、场景与边界

适合单张文生图、基于参考图的修改，以及从已定稿提示词批量生成图片。源码包含 OpenAI、Azure、Google、OpenRouter、DashScope、Z.AI、MiniMax、Jimeng、Seedream、Replicate、Agnes 等提供商，还包含专用 codex-cli 路径。

“统一入口”不表示能力完全相同。模型在尺寸、参考图、数量和接口语义上有差异；指定画幅后有的会映射到最接近的支持尺寸，不能承诺每个平台精确返回相同像素。参考图尤其依赖具体模型，不应只看提供商名字。

源码明确区分 OpenAI API 与 Codex/ChatGPT 订阅登录。openai 提供商需要 OPENAI_API_KEY；桌面登录或 OAuth 令牌不能直接当 API Key。要走已有 Codex 订阅能力，应使用运行时原生图像能力，或明确选择已登录 Codex CLI 的专用路径，不能改写 API 提供商去暗中复用另一类认证。

二、前置依赖与按需安装

需要支持 Skills、能够调用脚本的 Agent，Bun 运行环境或可使用 npx -y bun 的 Node.js 环境，以及用户合法拥有的服务凭证。只准备计划和提示词时，不必先购买所有提供商服务。

经 README 核实的安装入口：

1	npx skills add jimliu/baoyu-skills --skill baoyu-image-gen --agent codex

Claude Code 用户可将 codex 替换为 claude-code。

只选择 baoyu-image-gen 即可；不必为了单张图片安装全部视觉技能。此命令未锁定本文提交。固定源码可将完整目录复制到 Codex 项目的 .agents/skills/baoyu-image-gen/，保留脚本和提供商参考文档。

配置凭证时不要把真实 Key 放进教程、提示词、聊天公开记录或提交仓库的文件。项目级 .baoyu-skills/.env 与用户级 ~/.baoyu-skills/.env 是源码支持的环境配置位置，公开仓库中应排除秘密文件。

三、输入输出与已核实入口

单图输入为直接提示词或多个提示词文件，可带参考图片；单图模式要求输出图片路径。多个提示词文件会拼接成一份输入，不自动对应多张图片。批量生成则使用批量任务 JSON，每项应有自己的提示词与输出路径。

以下形式来自技能源码，仅展示，不执行：

1	bun C:/path/to/baoyu-image-gen/scripts/main.ts --promptfiles C:/work/prompts/01.md --image C:/work/output/01.png --ar 16:9 --quality normal

这里 --ar 是本后端画幅参数，不应把上层技能的 --aspect 随意搬过来。--quality 接受 normal 或 2k，并不是任意质量数字。当前示例没有硬编码提供商，应在执行前由已确认偏好或显式选择决定；教程更推荐通过 Agent 报告最终配置，再由用户确认。

批量入口经源码确认是 --batchfile 和 --jobs；scripts/build-batch.ts 可从大纲与提示词目录构造任务文件。不要手写一套未经核实的 JSON 字段，把用户交给现有 helper 或让 Agent读取当前参考格式后生成。

四、可复制的 Agent 请求

请使用 baoyu-image-gen，为我已经保存的三份提示词准备生成任务。
先检查 EXTEND.md、可用提供商和各模型的参考图能力，不展示密钥值。
使用我明确确认的提供商与模型，输出前报告 provider、model、画幅、质量和文件路径。
本轮先核对输入文件并准备批量清单，不调用服务。
不要把 Codex/ChatGPT 登录态当成 OPENAI_API_KEY，不自动更换认证方式。
我确认后再生成，先按较低并发运行，成功项不要无故重复生成。
失败时报告具体任务和原因，不发布图片，不上传无关文件。

对于人物参考，可补充“参考图是同一主体，只改场景、姿势和风格，保留身份；不要用长段泛化外貌描述替代实际参考图”。上传前仍需确认图像使用权与隐私范围。

五、案例：三张已定稿文章配图

假设文章配图已经给出大纲和三份提示词，本技能只负责执行，不重新策划内容。

首先检查三份文件存在、输出路径互不冲突、引用的参考图确实可读。如果其中一份是修改人物照片，单独核对模型参考能力，不能让纯文生图模型默默改为“根据描述画一个相似的人”。

其次读取偏好。没有 EXTEND.md 时必须完成首次设置，收集提供商、模型、质量和保存位置。若选中的提供商默认模型仍为空，还需确认模型，不应直接把用户引向未知收费路径。

然后展示最终解析结果。模型优先级是当前参数、EXTEND.md 中 default_model、对应环境变量、内置默认值。例如用户改了环境变量却仍使用旧模型，通常是配置文件优先级更高，而不是环境变量“完全不支持”。

准备批量清单后，选择适合配额的并发，保留每项输出路径。单图默认顺序执行；批量文件有两个以上待执行任务时进入并行模式。源码内置总 worker 上限为十，但各提供商还有独立限流，jobs 大不意味着实际同时发出同样多请求。

最后查看成功数、失败数和逐项原因。后端每图最多尝试三次，属于同一任务的重试，不是额外三张候选图。上层技能也可能有自己的重试规则，应避免层层重试造成意外费用。输出后再检查实际像素、文字、构图和参考主体一致性。

六、配置示例与优先级

偏好按项目 .baoyu-skills/baoyu-image-gen/EXTEND.md、XDG 配置目录、用户 $HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md 查找，首个命中生效。以下是已核实 schema 的示意内容，不包含凭证：

---
version: 1
default_provider: google
default_quality: normal
default_aspect_ratio: "16:9"
default_model:
  google: "gemini-3-pro-image"
batch:
  max_workers: 4
  provider_limits:
    google:
      concurrency: 2
      start_interval_ms: 1100
---

模型名仅表示固定提交里列出的可配置值，正式使用前应核对账号和服务文档。质量 2k 是映射预设，不同模型不一定都支持相同分辨率。例如源码中的 Google 轻量图像模型会把不支持的高分辨率请求降到 1K 并警告。

配置优先级总体是命令行、偏好文件、环境变量、项目 .env、用户 .env。对于 Azure，模型字段实际是部署名，不一定等于基础模型 ID。对于 OpenAI 兼容网关，openai-native 与 ratio-metadata 两种接口方言有不同请求语义；后者只适用于文生图，不能推断参考图编辑也支持。

codex-cli 从不自动选择，必须由当前请求或偏好明确指定；它还需要 PATH 中存在并已合法登录的 Codex CLI。订阅是否覆盖本次能力，由实际账号权限决定，不承诺免费。

七、验收与排错

[ ] 提供商、模型与认证方式明确，未把 OAuth 当 API Key。
[ ] 提示词和参考图路径有效，输出文件没有相互覆盖。
[ ] 参考能力核实到具体模型，而非只核实提供商。
[ ] 并发与额度相符，报告了重试、成功和失败项。
[ ] 实际画幅、分辨率、中文文字与主体一致性通过检查。
[ ] 公开附件不含 Key、批量日志中的秘密或私人参考图。

缺少 API Key：先核对认证路线，不要复制其他应用令牌试错。改模型不生效：检查 EXTEND.md 是否覆盖环境变量。参考图报错：看提供商专门说明；源码表格和通用选择段存在个别能力口径差异，尤其 DashScope 特定模型应以该模型参考与实际实现再核对。网关尺寸错误：确认接口方言和编辑能力，不能无条件套用原生参数。限流：降低并发与增加启动间隔，不进行无限重试。

生成结果进入 Obsidian 或 Hexo 时，用普通 Markdown 相对图片路径，并确保发布链复制附件；提示词、配置与密钥不必随图片公开。