图像生成 (image-generation)

通过单一 CLI 网关，实现图像生成、创建图片、根据文本描述绘图或生成视觉内容——支持异步轮询和自动下载。

该技能采用单一聚合网关后端模式。本地仅需一个 API 密钥，而多个模型在网关后端进行聚合。CLI 封装了完整的异步流程：提交任务 -> 轮询 task_status（小写）-> 获取 data.images。后端平台为固定实现选择，不支持配置为其他提供商。如需使用其他平台，请发布独立的技能。

设计目标是为常见工作流提供流畅自动化支持，包括单图生成、多文件提示词、带参考图的图生图、批量任务、默认参数扩展（EXTEND defaults）以及可复用的风格预设。完整的网关对齐说明详见 [references/weryai-platform.md](references/weryai-platform.md)。

安全与范围

• 网络连接：本技能通过 HTTPS（https://api.weryai.com）调用 WeryAI 网关。
• 认证方式：使用 IMAGE_GEN_API_KEY。密钥不会被打印。仅在用户显式运行 npm run setup -- --persist-api-key 时才可能持久化保存。
• 参考图像：必须为公共 URL（推荐使用 https://）。http:// 可能可用但存在安全隐患。本地文件路径和 data: URL 均被拒绝。
• 无任意 shell 执行：生成运行环境不会执行任意 shell 命令。
• 文件写入：输出图像及可选本地配置将保存至 .image-skills/image-generation/（项目目录）和/或 ~/.image-skills/image-generation/（用户主目录）。

当前网关协议（WeryAI）

更多字段映射、模型查找指引及故障排查流程请参见 [references/weryai-platform.md](references/weryai-platform.md)。

第零步：首次触发就绪检查

当此技能在项目或环境中首次被触发时，代理不应直接进入模型选择或生成阶段。必须首先完成以下步骤：

1. 静默检查本地就绪状态：运行 npm run ensure-ready -- --project . --workflow <workflow>
2. 若运行时依赖缺失：向用户提议代表其安装这些依赖
3. **若 IMAGE_GEN_API_KEY 缺失**：告知用户图像生成需要 API 密钥，并提供机会立即配置
4. 仅在确认就绪且 API 密钥已解决后，方可继续至模型选择、提示词澄清或生成阶段

访问令牌：仅使用 **IMAGE_GEN_API_KEY**。该密钥也可存放在 .image-skills/image-generation/.env 文件中，格式为 IMAGE_GEN_API_KEY=...。用户授权后，代理可通过运行以下命令将其持久化保存：

npm run setup -- --project . --workflow <workflow> --persist-api-key

（若密钥已在环境变量中，或由代理代为写入本地文件，而非要求用户手动编辑文件）

首次使用就绪检查：在新的 OpenClaw 或本地实例中首次运行生成任务前，代理必须执行：

npm run ensure-ready -- --project . --workflow <workflow>

此就绪步骤不可跳过。它会检查本地工具链，读取本地诊断报告，并在缺少本地脚本依赖时自动执行 bootstrap。

首次触发用户行为：

• 若依赖缺失：询问是否允许安装，然后静默安装
• 若 IMAGE_GEN_API_KEY 缺失：告知用户图像生成需要 API 密钥，并提供由代理代为写入 .image-skills/image-generation/.env 的选项
• 不应在就绪检查前要求用户调试环境
• 不应在就绪和密钥未解决前要求用户选择模型
• 将 API 密钥视为敏感信息：优先代表用户写入本地文件，绝不回显密钥，也不在常规进度消息中包含密钥

**EXTEND.md** 为可选文件，可用于存放默认模型、质量、宽高比及批量任务工作线程限制等配置。

test -f .image-skills/image-generation/EXTEND.md && echo project
test -f "$HOME/.image-skills/image-generation/EXTEND.md" && echo user

初始化时的默认模型：若尚未配置模型，则初始化该技能时默认使用 Nano Banana 2（GEMINI_3_1_FLASH_IMAGE），并通知用户当前已设为默认。同时提醒用户可随时切换至其他模型。

模型选择逻辑：初始化后，以下任一来源提供活动默认模型：

• --model 参数
• EXTEND.md 中的 default_model
• 环境变量 IMAGE_GEN_DEFAULT_MODEL

若以上均未设置，代理应先将本地默认模型初始化为 Nano Banana 2，告知用户当前工作区已默认使用该模型，并提醒用户可根据需要随时更换。详情请参见 [references/config/first-time-setup.md](references/config/first-time-setup.md)、[references/config/preferences-schema.md](references/config/preferences-schema.md) 及 [references/config/model-registry-schema.md](references/config/model-registry-schema.md)。

风格预设：[references/style-presets.md](references/style-presets.md)

模型优先级：

name: Image Generation

version: 1.0.5

description: 生成图像的技能，支持多种模型、风格和批量处理。

summary: 通过命令行工具生成高质量图像，支持提示词构建、风格选择、图像参考、批量任务及本地默认模型管理。

默认模型配置

--model → EXTEND.md default_model → IMAGE_GEN_DEFAULT_MODEL

若未指定模型

当用户请求图像生成但未配置任何模型（EXTEND.md、--model 和 IMAGE_GEN_DEFAULT_MODEL 均不存在）时：

不要要求用户阅读文档或手动修改配置文件。 请遵循 [references/config/first-time-setup.md](references/config/first-time-setup.md) § "模型选择 — 代理引导流程" 的指引：

1. 从本技能随附的初始模型注册表开始。若发现模型列表过时或所需模型缺失，静默执行刷新：

npm run discover-image-models -- --out .image-skills/image-generation/MODELS.json

1. 使用 Nano Banana 2（GEMINI_3_1_FLASH_IMAGE）初始化本地默认设置，并写入 EXTEND.md。
2. 告知用户当前默认模型已设为 Nano Banana 2，并明确提醒他们后续可随时切换至其他模型。
3. 继续进行提示澄清与图像生成流程。
4. 若用户立即要求更换模型，调用推荐流程：

npm run recommend-model -- --workflow <workflow> --role <role> --json

根据返回结果更新 EXTEND.md。

若工作流比通用单图更具体，优先使用角色感知的推荐类型，如 comic-page、comic-character-sheet、infographic-dense 或 article-framework，而非仅传递宽泛的工作流名称。

若用户后续提出更换模型，直接在 EXTEND.md 中更新，不得要求用户手动编辑。

若网关返回“模型不存在”或类似模型键错误，代理必须先从 WeryAI 文档中刷新模型信息，重新尝试推荐，再向用户询问平台侧信息。

请求不明确时的处理

当用户仅提供模糊想法，视觉描述仍较薄弱时，不要直接进入提示词编写阶段。应优先使用本地简报助手：

npm run build-visual-brief -- --workflow cover --topic "Habit systems"

通过其交互式问题菜单，至少询问以下内容：

1. 偏向写实风格还是插画风格？
2. 色温或配色方向？
3. 拍摄语言（特写、广角等）？
4. 构图模式？
5. 纵横比？
6. 文字密度？

将用户回答整合为最终提示词或工作流文件。

不要让用户独自去查阅文档。 若 CLI 因模型缺失失败，代理应完成此选择流程并重试。

工作流程

1. 首次触发时，运行就绪检查：验证依赖项，自动安装缺失的本地工具，确认 IMAGE_GEN_API_KEY 存在。
2. 确认已配置默认模型（通过 EXTEND.md 或环境变量），否则进入引导式模型选择流程。
3. 构建提示词：可直接输入文本（--prompt）或从多个文件组装（--promptfiles）。
4. 如适用，选择风格预设（--style）。
5. 执行 CLI 提交任务，轮询状态直至完成，并下载结果。
6. 生成多张图像时，启用批量模式（--batchfile），支持并行任务。

脚本说明

{baseDir} 是包含此文件的目录。${BUN_X} 为 bun 或 npx -y bun。

使用方式

# 示例；M 应由用户选择或由代理解析
M=<选定的模型键>

# 单图生成
${BUN_X} {baseDir}/scripts/main.ts --prompt "a cat" --image cat.png --ar 1:1 -m "$M"

# 多文件拼接提示词
${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md user.md --image out.png --ar 16:9 -m "$M"

# 使用风格预设
${BUN_X} {baseDir}/scripts/main.ts --prompt "city nightscape" --style cinematic --image out.png --ar 16:9 -m "$M"

# 图像到图像转换（参考图）
${BUN_X} {baseDir}/scripts/main.ts --prompt "turn it into cyberpunk" --image out.png --ref src.png --ar 1:1 -m "$M"

# 设置质量 / 分辨率
${BUN_X} {baseDir}/scripts/main.ts --prompt "poster" --image poster.png --ar 16:9 --quality 2k -m "$M"
${BUN_X} {baseDir}/scripts/main.ts --prompt "poster" --image poster.png --ar 16:9 --imageSize 2K -m "$M"

# 当未指定 --ar 时，根据 --size 推断纵横比
${BUN_X} {baseDir}/scripts/main.ts --prompt "scene" --image scene.png --size 1280x720 -m "$M"

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

# 不保存下载的图像到磁盘
${BUN_X} {baseDir}/scripts/main.ts --prompt "abstract" --image dummy.png --ar 1:1 --no-download -m "$M"

# 干运行：预览请求；--image 可选
${BUN_X} {baseDir}/scripts/main.ts --prompt "test" --ar 1:1 -m "$M" --dry-run

批量任务 JSON 示例

{
  "jobs": 4,
  "tasks": [
    {
      "id": "hero",
      "promptFiles": ["prompts/hero.md"],
      "image": "out/hero.png",
      "model": "<来自网关文档的模型键>",
      "style": "editorial",
      "ar": "16:9",
      "quality": "2k",
      "use_web_search": false
    },
    {
      "id": "edit",
      "prompt": "turn it into watercolor",
      "image": "out/edit.png",
      "ref": ["assets/in.png"],
      "negative_prompt": "blurry",
      "webhook_url": "https://example.com/hook"
    }
  ]
}

路径相对于 批处理文件所在目录 解析。若存在 provider 字段，在单网关模式下会被忽略。任务级别可选字段包括：style、webhook_url、negative_prompt、resolution、use_web_search 和 caller_id。

主要选项

并发与重试机制

• 批量任务通过 --jobs 实现受控并发，支持环境变量覆盖，如 BASE_IMAGE_GEN_CONCURRENCY 和 BASE_IMAGE_GEN_START_INTERVAL_MS。
• 单个任务最多重试 3 次，但明显由参数错误或认证失败导致的问题不会重试。
• 批量任务的最大工作数来自 EXTEND.md 中的 batch.max_workers 或 BASE_IMAGE_MAX_WORKERS。

环境变量

支持的 .env 文件位置：

• <cwd>/.image-skills/.env
• $HOME/.image-skills/.env

已存在的环境变量不会被覆盖。

Agent 使用说明

1. 在新环境中首次使用时，请从本技能目录运行 npm run ensure-ready -- --project . --workflow <workflow>，即使直接调用 API 似乎正常也不可跳过。
2. 确保 IMAGE_GEN_API_KEY 可用，可通过环境变量或 .image-skills/.env 提供。
3. 若模型缺失，请在运行 CLI 前完成模型选择流程。
4. 单任务模式通常需要 --image，但 --dry-run 可省略。若存在 --ref，脚本将使用图像到图像接口。
5. 轮询行为规则：状态为 waiting / processing 时持续轮询；状态为 succeed 时使用 images 字段；状态为 failed 时检查 msg 字段。
6. 选定的模型标识符会输出到 stderr，便于调试。

生成过程中的用户反馈

• 生成开始前：告知用户即将执行的操作，包括正在使用的模型（例如：“正在使用模型 X 生成封面，预计约 30 秒”）。不得静默启动。
• 模型披露：生成开始时必须明确提及模型名称/标识符，帮助用户理解画质预期，并便于后续切换模型。
• 批量生成：估算总图像数量和大致耗时。图像生成完成后应逐步展示，不要等待全部完成才显示任何结果。
• 失败处理：不直接输出错误码。应将错误信息转化为用户可理解的解释，并提供解决方案建议（例如：“该模型暂时不可用——是否尝试其他模型？”）。
• 超时提示：若轮询时间超过预期，应主动通知用户（例如：“正在处理中，耗时较久，请稍候”），而非保持沉默。
• 生成完成：立即发送或展示生成的图像。不得仅输出文件名——用户必须看到实际图像。若平台支持文件发送，则发送文件；若支持内联渲染，则直接渲染；若均不支持，则提供下载链接。

交互规则（强制要求）

以上规则适用于所有用户交互，非可选建议，必须遵守。

技能：图像生成

版本：1.0.5

分块：4/4

1. 绝不向用户展示命令、文件路径、配置语法或模式细节。所有工具执行均静默进行。
2. 绝不要求用户编辑配置文件。代理将代为编写 EXTEND.md、MODELS.json 等配置文件。
3. 一次只提出一个问题。不要一次性列出所有选项维度。优先引导用户做出影响最大的选择。
4. 提供具体可选方案并附带描述，而非原始技术名称。若展示风格选项，请说明每种风格的实际视觉效果。
5. 启动生成时始终告知所用模型及预计耗时。
6. 交付结果时直接展示图像。绝不仅返回文件路径或文件名。若渠道支持发送图片文件，则直接发送文件；若支持内联显示，则以嵌入方式展示；若两者都不支持，则提供可点击的下载链接。仅返回如 output.png 这类裸文件名是不可接受的交付方式。
7. 在迭代时仅重新生成变更部分。不得重新启动整个流程。
8. 若工具缺失，应主动提议代为安装——绝不能暴露工具名称、PATH 错误或要求用户运行安装命令。详见“缺失工具”部分。
9. 默认使用 Nano Banana 2 模型，除非用户另有要求。当尚未配置默认模型时，初始化 GEMINI_3_1_FLASH_IMAGE（即 Nano Banana 2），告知用户该模型已设为本技能的默认值，并明确提醒其可随时切换至其他更适合的模型。
10. 以用户语言回复。匹配用户提问、状态更新、解释说明和交付消息所使用的语言，除非用户明确要求切换。
11. 首次触发时，优先执行就绪检查。在询问用户选择模型或开始生成前，先检查依赖项和 IMAGE_GEN_API_KEY 的状态。
12. 将 API 密钥视为敏感信息处理。主动为用户提供本地配置 IMAGE_GEN_API_KEY 的选项，避免要求用户在普通聊天中粘贴密钥，且绝不重复或引用密钥内容。

重跑行为

• 使用相同 --image 路径运行 main.ts 会覆盖原有输出文件。
• --batchfile 会重新处理批次中的所有任务；已完成的图像将被覆盖。
• --dry-run 不论先前状态如何，均不写入文件。
• 轮询已成功完成的 taskId 会返回缓存结果，不会重新生成。

完成标准

• IMAGE_GEN_API_KEY 已配置，且默认模型已在 EXTEND.md 中设定。
• CLI 生成有效的图像文件（或正确的 --dry-run 请求体）。
• 批量模式完成所有任务，并通过 --json 输出每项任务的状态。
• 失败任务包含用户可读的说明，而非仅错误码。
• 生成开始前向用户披露所用模型名称。

缺失工具

若当前环境同时无法使用 bun 和 npx：

1. 绝不向用户暴露工具名称或 PATH 错误。不得提及“bun”、“npx”、“PATH”或安装命令。
2. 以用户友好的方式提出安装建议。例如：“我需要设置一个小型运行环境来生成图像——现在安装可以吗？大约需要 30 秒。”
3. 获得用户同意后，静默执行 npm install -g bun 或平台对应的安装程序。以通俗语言报告安装成功或失败。
4. 若用户拒绝或安装失败，如实说明：“当前环境无法生成图像。您可联系管理员设置图像工具链，或尝试在其他环境中重试。”
5. 绝不要求用户自行安装工具或粘贴终端命令。

故障排查

参见 [references/weryai-platform.md](references/weryai-platform.md)。对于调用失败的情况，请将请求与响应与 [调用历史记录](https://weryai.com/api/history) 进行比对。