baoyu-image-gen 首次配置完全指南：从 EXTEND.md 交互问答到默认模型选型

baoyu-image-gen 首次配置完全指南从 EXTEND.md 交互问答到默认模型选型【免费下载链接】baoyu-skills项目地址: https://gitcode.com/gh_mirrors/ba/baoyu-skills导读baoyu-image-gen是 baoyu-skills 仓库中的 AI 图像生成技能它通过统一的 CLI 封装了 Google、OpenAI、Azure OpenAI、OpenRouter、DashScope通义万象、Z.AIGLM-Image、MiniMax、Replicate、Jimeng、Seedream 与 Agnes 等十余家图像生成 API。本指南围绕其配置文档 first-time-setup.md 展开完整讲解技能首次运行时如何通过 AskUserQuestion 交互式收集默认服务商 默认模型 默认质量 保存位置并生成EXTEND.md偏好文件同时结合 main.ts 源码与 main.test.ts 测试从底层揭示这些偏好是如何被加载、解析与合并生效的。读完本文你将掌握该技能从零配置到一键出图的完整初始化链路并能为每个服务商正确选配默认模型。一、先理解为什么必须有首次配置这一关baoyu-image-gen将用户偏好固化在一个名为EXTEND.md的 YAML 前置元数据文件中。它承载了默认服务商default_provider、默认质量default_quality、默认宽高比default_aspect_ratio、默认图像尺寸default_image_size、OpenAI 兼容网关方言default_image_api_dialect、各服务商默认模型default_model以及批处理并发参数batch等关键配置。其完整字段定义见 preferences-schema.md。在 SKILL.md 的 Step 0: Load Preferences ⛔ BLOCKING 中明确规定在EXTEND.md存在之前图像生成是被阻塞的。也就是说首次配置不是可选项而是生成动作的前置门槛。运行时按以下路径顺序查找配置文件先命中者优先路径作用域.baoyu-skills/baoyu-image-gen/EXTEND.md项目级当前项目${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-image-gen/EXTEND.mdXDG 配置目录$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md用户主目录所有项目对应到源码loadExtendConfig 会依次尝试读取这三处路径并解析 YAML frontmatter若文件不存在则继续向后探测全部失败时返回空配置。源码中还隐藏着一个向后兼容细节旧版本技能名为baoyu-imagine若新路径不存在而旧路径.baoyu-skills/baoyu-imagine/EXTEND.md存在运行时会自动将其重命名迁移到新路径见 main.test.ts 的 loadExtendConfig renames legacy EXTEND.md 测试若新旧路径同时存在则保留两者并优先使用新路径。二、首次配置的两种触发场景根据 first-time-setup.md 的 Overview配置流程仅在以下两种情况下被触发未找到任何EXTEND.md→ 执行完整配置服务商 模型 偏好。找到了EXTEND.md但default_model.[当前服务商]为 null→ 仅询问模型。其完整流程可用下图概括No EXTEND.md found EXTEND.md found, model null │ │ ▼ ▼ ┌─────────────────────┐ ┌──────────────────────┐ │ AskUserQuestion │ │ AskUserQuestion │ │ (full setup) │ │ (model only) │ └─────────────────────┘ └──────────────────────┘ │ │ ▼ ▼ ┌─────────────────────┐ ┌──────────────────────┐ │ Create EXTEND.md │ │ Update EXTEND.md │ └─────────────────────┘ └──────────────────────┘ │ │ ▼ ▼ Continue Continue在源码层面detectProvider 与getModelForProvider共同构成了模型为空则回退的链路getModelForProvider的优先级是CLI--model→ EXTEND.mddefault_model.[provider]→ 环境变量 → 服务商内置默认模型。当default_model.[provider]为 null 时用户将看到仅询问模型的简化流程当连 EXTEND.md 都不存在时才会触发完整问答。三、Flow 1无 EXTEND.md 的完整配置完整配置要求使用 AskUserQuestion或其他运行时等价的用户输入工具并且尽可能把所有问题合并到一次调用中若工具仅支持单问题则按优先级逐个询问。交互语言使用用户输入的语言或已保存的语言偏好。以下是原文档规定的完整问题清单及其选项设计。问题 1默认服务商Default Providerheader: Provider question: Default image generation provider? options: - label: Google (Recommended) description: Gemini multimodal - high quality, reference images, flexible sizes - label: OpenAI description: GPT Image 2 - latest OpenAI image model, reference-image workflows - label: Azure OpenAI description: Azure-hosted GPT Image deployments with resource-specific routing - label: OpenRouter description: Router for Gemini/FLUX/OpenAI-compatible image models - label: DashScope description: Alibaba Cloud - Qwen-Image, strong Chinese/English text rendering - label: Z.AI description: GLM-image, strong poster and text-heavy image generation - label: MiniMax description: MiniMax image generation with subject-reference character workflows - label: Replicate description: Curated Replicate image families - nano-banana-2, Seedream, and Wan image models - label: Agnes description: Sapiens AI Agnes - optimized for high information density, complex layouts, reference-image support补充说明该选项列表仅覆盖了完整配置中面向主流 API Key 型服务商的选项。从 main.ts 与 types.ts 看Provider 联合类型还包括jimeng即梦、seedream豆包与codex-cli通过本地codex exec调用 Codex 订阅无需OPENAI_API_KEY。其中codex-cli永远不会被自动选择必须显式在 EXTEND.md 中设置default_provider: codex-cli或通过--provider codex-cli指定——这一定义可在 SKILL.md 的 Provider Selection 一节中得到印证。问题 2默认 Google 模型仅在用户选择了 Google 或未显式指定服务商自动探测时展示header: Google Model question: Default Google image generation model? options: - label: gemini-3-pro-image (Recommended) description: Highest quality, best for production use - label: gemini-3.1-flash-image description: Fast generation, good quality, lower cost - label: gemini-3-flash-preview description: Fast generation, balanced quality and speed问题 2b默认 OpenRouter 模型仅在用户选择了 OpenRouter 时展示header: OpenRouter Model question: Default OpenRouter image generation model? options: - label: google/gemini-3.1-flash-image (Recommended) description: Best general-purpose OpenRouter image model with reference-image workflows - label: google/gemini-2.5-flash-image-preview description: Fast Gemini preview model on OpenRouter - label: black-forest-labs/flux.2-pro description: Strong text-to-image quality through OpenRouter问题 2c默认 Azure Deployment部署名仅在用户选择了 Azure OpenAI 时展示。注意 Azure 的特殊性这里询问的是部署名而非底层模型族名header: Azure Deploy question: Default Azure image deployment name? options: - label: gpt-image-2 (Recommended) description: Use if your Azure deployment uses the GPT Image 2 model name - label: gpt-image-1.5 description: Previous GPT Image deployment name - label: gpt-image-1 description: Earlier GPT Image deployment name问题 2d默认 MiniMax 模型仅在用户选择了 MiniMax 时展示header: MiniMax Model question: Default MiniMax image generation model? options: - label: image-01 (Recommended) description: Best default, supports aspect ratios and custom width/height - label: image-01-live description: Faster variant, use aspect ratio instead of custom size问题 2e默认 Z.AI 模型仅在用户选择了 Z.AI 时展示header: Z.AI Model question: Default Z.AI image generation model? options: - label: glm-image (Recommended) description: Best default for posters, diagrams, and text-heavy images - label: cogview-4-250304 description: Legacy Z.AI image model on the same endpoint问题 3默认质量Qualityheader: Quality question: Default image quality? options: - label: 2k (Recommended) description: 2048px - covers, illustrations, infographics - label: normal description: 1024px - quick previews, drafts2k是全局默认值在 main.ts 中main()会在合并配置后执行if (!mergedArgs.quality) mergedArgs.quality 2k。质量预设与各服务商实际尺寸的映射关系Google imageSize / OpenAI size / OpenRouter size / Replicate resolution可参见 SKILL.md 的 Quality Presets 表格normal对应 1K/1024px2k对应 2K/2048px。问题 4保存位置header: Save question: Where to save preferences? options: - label: Project (Recommended) description: .baoyu-skills/ (this project only) - label: User description: ~/.baoyu-skills/ (all projects)四、保存位置与 EXTEND.md 模板保存位置对照表选择路径作用域Project.baoyu-skills/baoyu-image-gen/EXTEND.md当前项目User$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md所有项目EXTEND.md 模板完整配置流程结束后写入的文件遵循如下 frontmatter 结构--- version: 1 default_provider: [selected provider or null] default_quality: [selected quality] default_aspect_ratio: null default_image_size: null default_image_api_dialect: null default_model: google: [selected google model or null] openai: null azure: [selected azure deployment or null] openrouter: [selected openrouter model or null] dashscope: null zai: [selected Z.AI model or null] minimax: [selected minimax model or null] replicate: null agnes: null ---关于default_image_api_dialect的特殊规则如果用户选择了OpenAI但其端点实际是 OpenAI 兼容网关、背后代理的是其他图像模型族那么当用户明确确认该网关期望宽高比size 元数据分辨率时应保存default_image_api_dialect: ratio-metadata否则保持null即默认的openai-native。这两种方言的区别详见 SKILL.md 的 OpenAI-Compatible Gateway Dialects 一节openai-native像素级size如1536x1024 OpenAI 原生质量字段ratio-metadata宽高比size如16:9metadata.resolution1K|2K|4Kmetadata.orientation。值得指出的是该方言仅作用于文生图参考图编辑edit场景仍需openai-native或具备一等编辑能力的服务商。五、Flow 2EXTEND.md 存在、但模型为空的仅模型流程当EXTEND.md已存在但default_model.[当前服务商]为 null 时不再重复完整问答而是只针对当前服务商询问一个模型问题。原文档按服务商给出了各自的默认选项。Google 模型选择header: Google Model question: Choose a default Google image generation model? options: - label: gemini-3-pro-image (Recommended) description: Highest quality, best for production use - label: gemini-3.1-flash-image description: Fast generation, good quality, lower cost - label: gemini-3-flash-preview description: Fast generation, balanced quality and speedOpenAI 模型选择header: OpenAI Model question: Choose a default OpenAI image generation model? options: - label: gpt-image-2 (Recommended) description: Latest GPT Image model, flexible sizes up to 4K, high-fidelity image inputs - label: gpt-image-1.5 description: Previous GPT Image model - label: gpt-image-1 description: Earlier GPT Image modelAzure 部署选择header: Azure Deploy question: Choose a default Azure image deployment name? options: - label: gpt-image-2 (Recommended) description: Use when your Azure deployment name matches the GPT Image 2 model - label: gpt-image-1.5 description: Use when your Azure deployment name matches the GPT Image 1.5 model - label: gpt-image-1 description: Use when your Azure deployment name matches GPT-image-1Azure 配置要点在baoyu-image-gen中Azure 的--model/default_model.azure应填写Azure 部署名而不是底层模型族名如果部署名是自定义的就把确切的部署名保存到default_model.azure例如测试用例中的image-prod见 main.test.ts。OpenRouter 模型选择header: OpenRouter Model question: Choose a default OpenRouter image generation model? options: - label: google/gemini-3.1-flash-image (Recommended) description: Recommended for image output and reference-image edits - label: google/gemini-2.5-flash-image-preview description: Fast preview-oriented image generation - label: black-forest-labs/flux.2-pro description: High-quality text-to-image through OpenRouterDashScope 模型选择header: DashScope Model question: Choose a default DashScope image generation model? options: - label: qwen-image-2.0-pro (Recommended) description: Best DashScope model for text rendering and custom sizes - label: qwen-image-2.0 description: Faster 2.0 variant with flexible output size - label: qwen-image-max description: Legacy Qwen model with five fixed output sizes - label: qwen-image-plus description: Legacy Qwen model, same current capability as qwen-image - label: wan2.7-image-pro description: Wan 2.7 Pro — supports up to 4K text-to-image and reference-image editing - label: wan2.7-image description: Wan 2.7 base — faster generation, up to 2K, supports reference-image editing - label: z-image-turbo description: Legacy DashScope model for compatibility - label: z-image-ultra description: Legacy DashScope model, higher quality but slowerDashScope 配置要点可结合 dashscope.md 加深理解需要自定义--size、非常规宽高比如21:9或强中文/英文文字渲染时优先选择qwen-image-2.0-proqwen-image-max/qwen-image-plus/qwen-image仅支持五个固定尺寸1664*928、1472*1104、1328*1328、1104*1472、928*1664wan2.7-image-pro与wan2.7-image是 DashScope 中仅有的两个支持--ref的模型参考图编辑或多图融合必须选其一最多支持 9 张参考图baoyu-image-gen中的quality是兼容性预设并非 DashScope 原生参数——它只是把normal/2k映射到各模型族的尺寸表属于实现层面的选择而非 API 保证。Z.AI 模型选择header: Z.AI Model question: Choose a default Z.AI image generation model? options: - label: glm-image (Recommended) description: Current flagship image model with better text rendering and poster layouts - label: cogview-4-250304 description: Legacy model on the sync image endpointZ.AI 配置要点海报、图表以及中英文文字密集版式优先选择glm-imagebaoyu-image-gen对 Z.AI 目前仅暴露文生图能力参考图尚未接入该服务商Z.AI 的同步图像 API 返回可下载的图片 URL运行时下载后保存到本地。Replicate 模型选择header: Replicate Model question: Choose a default Replicate image generation model? options: - label: google/nano-banana-2 (Recommended) description: Current default for general Replicate image generation in baoyu-image-gen - label: bytedance/seedream-4.5 description: Replicate Seedream 4.5 with validated local size/ref guardrails - label: bytedance/seedream-5-lite description: Replicate Seedream 5 Lite with validated local size/ref guardrails - label: wan-video/wan-2.7-image-pro description: Replicate Wan 2.7 Image Pro with 4K text-to-image supportMiniMax 模型选择header: MiniMax Model question: Choose a default MiniMax image generation model? options: - label: image-01 (Recommended) description: Best general-purpose MiniMax image model with custom width/height support - label: image-01-live description: Lower-latency MiniMax image model using aspect ratiosMiniMax 配置要点image-01是最稳妥的默认选择支持官方aspect_ratio取值以及文档化的自定义width/height输出尺寸用户更看重生成速度、且可以接受基于宽高比的尺寸时再选择image-01-liveMiniMax 主体参考subject reference目前使用subject_reference[].type character官方文档建议使用小于 10MB 的 JPG/JPEG/PNG 正面人像参考图。六、更新 EXTEND.md增量写入而非全量覆盖用户完成模型选择后按以下步骤更新配置读取已有的 EXTEND.md若default_model:段已存在 → 仅更新当前服务商对应的键若default_model:段缺失 → 补充完整段default_model: google: [value or null] openai: [value or null] azure: [value or null] openrouter: [value or null] dashscope: [value or null] zai: [value or null] minimax: [value or null] replicate: [value or null] agnes: [value or null]关键原则只设置用户所选服务商的模型其余键保持原值或 null绝不覆盖其他服务商的既有配置。从源码层面看这一增量语义与 parseSimpleYaml 的解析器一致它按缩进逐行解析default_model下各服务商键未出现的键默认为 nullExtendConfig.default_model在 types.ts 中预置了全部 12 个服务商键的 null 默认值。而 mergeConfig 遵循CLI 参数 EXTEND.md 环境变量 内置默认的合并优先级只填充 CLI 中缺失的值——测试 main.test.ts 明确验证了CLI 传入 provider 时不会被子 EXTEND.md 的default_provider: google覆盖这一行为。七、配置完成之后配置流程收尾阶段依次执行按需创建目录源码中 ensureDir 负责递归建目录并对 Bun 在 Windows 上mkdir(recursive)误抛 EEXIST 的问题做了兼容处理写入/更新带 frontmatter 的 EXTEND.md向用户确认Preferences saved to [path]继续进入图像生成流程。此后每次生成前运行时都会加载该文件并把默认值合并进 CLI 参数。一个典型的后续调用示例完整命令集见 usage-examples.md# 直接使用 EXTEND.md 中的默认服务商与模型出图 bun scripts/main.ts --prompt A cinematic landscape --image out.png --ar 16:9 # 指定服务商与模型优先级高于 EXTEND.md bun scripts/main.ts --prompt A cat --image out.png --provider dashscope --model qwen-image-2.0-pro # 参考图编辑 bun scripts/main.ts --prompt Make blue --image out.png --ref source.png每次生成时运行时会打印当前生效的Using [provider] / [model]以及切换模型的提示--model id | EXTEND.md default_model.[provider] | env PROVIDER_IMAGE_MODEL——这从侧面印证了配置优先级链路的完整闭环。八、相关资源若需深入了解可继续阅读当前仓库中的以下文件first-time-setup.md首次配置流程的权威定义本文主体来源preferences-schema.mdEXTEND.md 完整字段参考含batch.max_workers与各服务商provider_limits的默认并发/启动间隔SKILL.md技能总览包含 CLI 选项表、环境变量表、Provider 选择优先级、质量预设与参考图身份保持最佳实践usage-examples.md覆盖所有服务商与批处理模式的完整命令示例main.ts配置加载、解析、合并与批处理限流的核心实现main.test.ts对 YAML 解析、旧配置迁移、合并优先级、服务商探测等行为的自动化验证dashscope.md 等references/providers/下各服务商专题文档模型族、尺寸规则与限制的深入说明。【免费下载链接】baoyu-skills项目地址: https://gitcode.com/gh_mirrors/ba/baoyu-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考