oma-image

图像 Agent - 多供应商图像路由器

调度

目标

通过经过身份验证的多供应商路由生成图像和视觉素材，同时确保提示词清晰、支持参考图引导的再生成、控制成本，并生成可复现的输出清单。

意图特征

• 用户要求生成图像、视觉素材、插画、产品照片、概念艺术、模型图或 AI 艺术。
• 其他技能需要共享的图像生成基础设施。
• 用户提供参考图以生成新的变体，或要求比较不同供应商。

适用场景

• 生成图像、视觉素材、插画、产品照片、概念艺术
• 针对同一提示词比较多个图像模型的输出
• 在编辑器工作流中根据提示词生成图像（Claude Code、Codex、Gemini CLI）
• 其他需要图像生成基础设施的技能（共享调用）
• 根据提供的参考图中的主体、风格、光线或构图，再生成一张新图像

不适用场景

• 像素级编辑、蒙版、修复、移除对象、合成、裁剪、调整大小或格式转换 -> 超出范围；请使用图像编辑器或明确支持此类操作的工具。
• 生成视频或音频 -> 超出范围
• 根据结构化数据制作内嵌矢量图 / SVG -> 使用模板技能
• 简单的素材调整大小或格式转换 -> 使用专用图像库

预期输入

• 图像提示词或创意简报
• 可选的供应商、尺寸、质量、数量、输出目录和参考图
• Codex、Pollinations 或 Gemini 的身份验证 / 环境状态

预期输出

• .agents/results/images/ 或指定输出目录中的生成图像文件
• 包含提示词、供应商、模型和可复现性元数据的 manifest.json
• 使用 --vendor all 时生成的供应商比较结果

依赖项

• oma image generate CLI 和供应商身份验证
• Codex 图像生成、Pollinations API 或 Gemini API/CLI 策略
• resources/vendor-matrix.md、resources/prompt-tips.md 以及 .agents/oma-config.yaml 中的 image: 部分

控制流特性

• 根据提示词歧义、供应商身份验证、成本阈值、参考图引导的再生成支持、路径安全性以及安全 / 超时退出码进行分支处理
• 调用外部供应商 API/CLI
• 读取参考图并写入生成的图像及清单

结构流程

入口

1. 验证请求是否包含足够的主体、场景、风格、用途和宽高比信息。
2. 判断所提供的图像是用于生成新变体的参考图，还是对不受支持的像素 / 蒙版编辑的请求。
3. 检查身份验证、成本保护措施、输出路径和数量限制。

转换

• 如果无法推断主体或预期结果，则询问缺失的信息；否则使用合理的默认值继续。
• 如果请求使用 --vendor all，则要求所有指定供应商均可用。
• 如果请求是参考图引导的再生成，且所选供应商支持参考图，则自动传入参考图。
• 如果请求需要像素、蒙版、裁剪、调整大小或格式编辑，则在生成前停止，并说明不支持的操作及合适的编辑器方案。
• 如果预估成本超过保护阈值，则要求确认，除非已绕过此限制。

故障与恢复

• 如果缺少身份验证，则说明对应供应商所需的身份验证方式。
• 如果所选供应商不支持参考图，则拒绝请求并提供可操作的指导。
• 如果本地 CLI 版本过旧，则请用户运行 oma update。
• 如果生成超时或被阻止，则显示退出码和供应商状态。

退出

• 成功：输出目录中存在图像和清单。
• 部分成功：比较模式下部分供应商失败，并报告失败情况。
• 失败：未生成任何图像，并明确说明路由 / 成本 / 身份验证 / 安全方面的阻碍。

逻辑操作

工具和工具链

• oma image generate、oma image doctor、oma image vendor list
• Codex、Pollinations 和 Gemini 提供方路径
• 提示词技巧、提供方矩阵和图像配置

规范命令路径

oma image doctor
oma image generate "<prompt>" --vendor auto --size auto --quality auto --output json

使用参考图：

oma image generate --reference "<absolute-path>" --vendor codex "<prompt>"

资源范围

范围	资源目标
LOCAL_FS	参考图、生成的图像、清单
PROCESS	提供方 CLI 和图像路由命令
NETWORK	Pollinations/Gemini 或提供方 API
CREDENTIALS	提供方身份验证和 API 密钥

前置条件

• 提示词已充分明确，或用户已批准扩充提示词。
• 所需的提供方身份验证和输出权限均已具备。
• 使用参考路径时，该路径可访问。

效果和副作用

• 创建图像文件和清单。
• 可能调用收费或有速率限制的提供方 API。
• 可能读取附加图像或参考图。

防护措施

1. 明确需求：使用提供的细节和合理的创作默认值。只有当缺失的选择会实质性影响所请求的结果时才提问。如果生成已获授权，不要要求用户批准扩充后的提示词。
2. 根据身份验证情况进行分派：检测哪些提供方 CLI 可用，并且只运行可用的 CLI；使用 --vendor all 时，所有请求的提供方都必须可用（严格模式）。注意：antigravity 健康检查仅验证是否已安装（agy --version）——已登录状态失效的 agy 也会通过健康检查，并在生成时返回 agy 自身的错误。
3. 费用防护：执行预估费用 ≥ $0.20（可配置）的运行前先确认。--yes / OMA_IMAGE_YES=1 可跳过确认。根据所请求的结果选择生成方式，而不是依据是否出现某个关键词。非交互式上下文（Agent、CI——stdin 没有 TTY）：CLI 无法提示确认，因此达到或超过阈值的运行会以状态码 1 退出，并显示包含 --yes 的提示。使用 --dry-run 估算费用。复用现有的预算授权；否则，在使用 -y 重新运行前确认额外支出。
4. 路径安全：输出路径位于 $PWD 之外时，必须使用 --allow-external-output。
5. 可取消：SIGINT/SIGTERM 会中止正在进行的提供方调用和编排器。
6. 确定性输出：每次运行都会在图像旁写入 manifest.json，以便复现。
7. n 的最大值为 5：限制运行时长。
8. 退出代码与 oma search fetch 一致（0、1、2=安全问题、3=未找到、4=输入无效、5=需要身份验证、6=超时）。

创作需求

使用所请求的主体和约束。未指定时，推断场景、风格、光照和宽高比；保留明确指定的文本和参考意图。只有存在影响实质结果且尚未明确的选择时才提问。遇到不熟悉的图像类别时，阅读 resources/prompt-tips.md。

参考资料

• 提供方调用、参考图和输出布局：resources/invocation.md（仅限选定的提供方或参考图操作）。

配置

项目专属设置位于 .agents/oma-config.yaml 的 image: 部分，oma update 会保留这些设置。随附的默认值位于 CLI 中（cli/commands/image/config.ts 里的 DEFAULTS）——只写入你修改的键。CLI 不再读取旧版 config/image-config.yaml；迁移 022 会将你在该文件中修改过的内容移入 oma-config（如果从未编辑过该文件，则会将其删除）。 环境变量：OMA_IMAGE_DEFAULT_VENDOR、OMA_IMAGE_DEFAULT_OUT、OMA_IMAGE_YES、POLLINATIONS_API_KEY。

• 执行步骤（按选定任务遵循）：resources/execution-protocol.md
• 提供方矩阵：resources/vendor-matrix.md
• 提示词技巧：resources/prompt-tips.md
• 检查清单（交接前运行）：resources/checklist.md
• 上下文加载：../_shared/core/context-loading.md