zenmux-image-generation

zenmux-image-generation

将用户的视觉意图转化为优化后的提示词，确认提示词和参数，然后通过 ZenMux 生成或编辑图像，并报告保存的文件。

在选择模型、优化提示词或刷新来源之前，先加载当前项目的配置。随附的 config.json.example 包含可移植的出厂默认值；用户偏好仅保存在项目的运行时目录中。

所有运行时文件都属于当前项目，位于 .context/zenmux-image-generation/ 下：

.context/zenmux-image-generation/
  .gitignore    # Ignores generated files; allows .gitignore and config.json in Git
  config.json   # User settings, copied from config.json.example only if absent
  refresh-state.json # Per-resource refresh attempts and successful updates
  output/       # Generated images
  prompts/      # Optimized prompts and generation parameters
  assets/       # Reference images copied/downloaded for this task, if needed
  references/   # Refreshed documentation, cookbooks, and model cache

辅助脚本会根据原始调用目录解析 Git 根目录（npm --prefix 时使用 INIT_CWD）；如果不在 Git 仓库中，则使用该调用目录。 请在用户的项目中运行命令。此技能可能安装在其他位置；必要时，请在脚本和 --prefix 参数中替换为其绝对路径。 现有用户参考图像可以保留原位。技能代码、锁定的依赖项和随附的离线参考资料都保留在技能目录中。

在编写任何提示词或下载资源之前，先初始化工作区：

node skills/zenmux-image-generation/scripts/workspace.mjs

此命令会打印运行时目录的绝对路径，创建其子目录和 .gitignore，并且仅在 config.json 不存在时将 config.json.example 复制为 config.json。 现有用户设置和忽略规则会得到保留。刷新参考资料和生成操作也会自动初始化工作区。 如果从项目子目录调用，请根据打印出的根目录解析提示词和缓存路径。

config.json 可以与项目一同提交。生成的图像、提示词文件、参考资料缓存和 refresh-state.json 会继续被忽略。

配置和提示词模式

读取生效设置（缺失字段会继承示例中的值，但不会改写用户设置）：

node skills/zenmux-image-generation/scripts/workspace.mjs --config

设置	出厂默认值	含义
generation.model	openai/gpt-image-2.5-flare	默认模型
generation.count	4	输出数量，范围为 1–10
generation.size	1024x1024	尺寸；仍会进行特定于模型的验证
generation.quality	medium	low、medium、high 或 auto
generation.outputFormat	png	png、jpeg 或 webp
prompt.mode	direct	direct 或 reference，详见步骤 5
refresh.autoUpdate	true	允许自动进行网络刷新
refresh.referencesIntervalHours	168	文档/教程集：每 7 天一次
refresh.modelsIntervalHours	24	模型目录：每天一次
refresh.retryIntervalMinutes	60	本地副本存在时，失败的刷新操作重试前的等待时间

优先级：用户的明确请求/CLI 标志 > 项目配置 > 示例默认值。 对模型或提示词模式的一次性请求仅应用于本次调用；只有在用户希望更改已保存的偏好时，才编辑项目配置。 绝不要将用户偏好写入共享示例或技能源文件。请将 API 密钥保存在配置文件之外的 ZENMUX_API_KEY 中。配置格式错误或无效时，会报告其路径并失败，不会覆盖文件；请修复配置，而不是静默使用默认值。

将 refresh.autoUpdate 设为 false，即可使用本地/随附来源，且不会自动发起网络请求。 间隔接受非负数；0 表示每次调用都刷新（失败的请求仍遵循重试延迟）。 对于用户明确请求的刷新，--force 会忽略两个间隔设置和 autoUpdate。

1. 准备运行环境并刷新来源

需要 Node.js 22 或更高版本；参考命令还需要 curl 和 jq。 每次克隆项目或依赖项发生变化后，安装一次锁定的依赖项：

npm ci --prefix skills/zenmux-image-generation

生成需要 ZENMUX_API_KEY。绝不要将密钥作为 CLI 参数，也不要打印密钥：

export ZENMUX_API_KEY=...

每次调用开始时，运行刷新检查。只有资源的刷新间隔已到期时才下载，或者在没有刷新历史时运行一次。新鲜缓存会被复用，不会发出网络请求。在 direct 模式下，不会复制或下载提示词手册；API 文档仍可刷新：

bash skills/zenmux-image-generation/scripts/refresh_references.sh --quiet
# Only when the user requests an immediate update:
bash skills/zenmux-image-generation/scripts/refresh_references.sh --force
# One-off prompt-mode override, without editing config:
bash skills/zenmux-image-generation/scripts/refresh_references.sh --prompt-mode reference --quiet

每个成功下载的参考文件在 refresh-state.json 中都有自己的时间戳；即使另一个文件下载失败，未更改的文件也会跳过。尝试失败时会保留之前的本地副本，并延后重试。模型目录部分刷新不会被标记为完全成功。

如果用户指定了模型，请保留该模型。否则，除非明显适用简单默认值，否则列出当前图像模型：

bash skills/zenmux-image-generation/scripts/list_models.sh
# Machine-readable alternatives:
bash skills/zenmux-image-generation/scripts/list_models.sh --names-only
bash skills/zenmux-image-generation/scripts/list_models.sh --json

模型命令使用相同的已配置缓存间隔。到期时，它会合并来自 https://zenmux.ai/api/v1/models 和 https://zenmux.ai/api/vertex-ai/v1beta/models 的图像模型，按完全相同的 ID 去重，并更新项目本地缓存。两个目录可能会公开不同的模型。 部分失败时，会保留缓存中的其他模型并发出警告。离线时，会依次回退到项目缓存和捆绑的 references/zenmux-image-models.json。--snapshot 会返回完整的规范化模型记录，包括输出模态。对于明确请求的实时查询或模型不可用错误，请使用 list_models.sh --force。绝不要凭记忆编造模型 ID。

首先读取 .context/zenmux-image-generation/references/ 中刷新的文件； 如果没有可用的缓存副本，则使用同名的捆绑 references/ 文件。 以下参考路径相对于所选目录。

按以下顺序使用来源：

1. references/zenmux-openai-image-generation.md，用于了解 ZenMux OpenAI Images 协议和 TypeScript 示例。
2. references/zenmux-create-image-edit.md，用于编辑字段、遮罩、限制和请求格式。
3. references/openai-typescript-images-generate.md 或 references/openai-typescript-images-edit.md，用于了解当前的 OpenAI SDK 签名。
4. references/zenmux-image-generation.md，用于 Gemini/Vertex 兼容协议。
5. references/zenmux-generate-images.md，用于完整的 Vertex AI generateImages / editImage 参数映射。
6. references/google-gemini-image-generation.md，用于了解 Google 最新的原生 Interactions API，以及明确的 ZenMux 兼容边界。
7. 仅在 reference 模式下，使用 awesome-* 文件获取提示词灵感，绝不要将其作为 API 事实来源。

2. 明确意图

提取以下信息。只有缺失的信息会实质性影响结果时才提问，且最多提出三个有针对性的问题。

字段	默认值
主体和期望的更改	必填
风格、构图、光线、氛围	根据请求推断
参考图像	无
模型	generation.model
尺寸	generation.size
质量	generation.quality
数量	generation.count
输出格式	generation.outputFormat
图像中的精确文字	无
语义文件名前缀	简短的英文 kebab-case 概要

纵横比快捷选项：

• 竖版、手机壁纸、故事：1024x1536
• 横版、横幅、宽屏：1536x1024
• 方形、标志、图标、社交媒体帖子：1024x1024
• gpt-image-2 的 4K：3840x2160
• gpt-image-2 的 2K/QHD：2560x1440

按用户提供的顺序记录每个参考路径或 URL。接受本地路径、 file://、http(s):// 和 base64 图像数据 URL。在提示词元数据和提示词文本中， 将参考项依次编号为 [Image #1]、[Image #2] 等。 标志的顺序必须与此编号一致。

3. 选择当前模型和协议

实时模型目录具有权威性。随附的快照已于 2026-09-12 从两个端点更新。可选项包括：

需求	建议模型
默认	项目配置中的 generation.model
较早的 OpenAI 替代选项	openai/gpt-image-1.5
其他新目录条目	openai/gpt-image-2.5-sunburst、meta/muse-image-1.0、x-ai/grok-imagine-image-2.0
通用 Nano Banana 默认选项	google/gemini-3.1-flash-image
延迟最低的 Nano Banana 选项	google/gemini-3.1-flash-lite-image
复杂的专业素材	google/gemini-3-pro-image
中文海报／产品设计	qwen/qwen-image-3.0-pro、bytedance/doubao-seedream-5.0-pro
照片级真实感或灵活的创意工作	bfl/flux-2-max、bfl/flux-2-flex、bfl/flux-2-pro
其他当前选项	klingai/kling-v3、sapiens-ai/agnes-image-2.1-flash、tencent/hy-image-v3.0、z-ai/glm-image

目录中存在某个模型，只能确认其模型 ID，不能确认其支持所有协议或参数。对于新模型，请根据 ZenMux 当前文档验证所选协议。在 gpt-image-2.5-flare 的自定义尺寸限制有明确文档说明之前，请使用预设尺寸；下方的 gpt-image-2 限制针对的是较早的模型。

按协议路由：

• openai/gpt-image-*、裸写的 gpt-image-* 和 chatgpt-image-latest 默认使用 scripts/generate-openai.ts 和 https://zenmux.ai/api/v1。
• 其他所有模型都使用 scripts/generate-gemini.ts 和 https://zenmux.ai/api/vertex-ai。
• 如果用户明确要求 OpenAI 模型使用 Gemini 协议，请遵照要求，使用 generate-gemini.ts。

Google 的 Gemini 直连 API 现在将 client.interactions.create 记载为其原生图像生成接口。ZenMux 尚未对此路由提供文档。通过 ZenMux 使用 Google Gemini 图像模型时，请继续使用 generateContent；使用其他所有图像模型时，请使用 generateImages / editImage。除非 ZenMux 明确宣布支持，否则不要向 ZenMux 发送 Interactions API 载荷。当前的 @google/genai SDK 会发出警告，指出 generateImages 已弃用，并将在不早于 2027-01-01 的下一个主版本中移除。请将该方法视为 ZenMux 兼容桥接方案，并在升级主版本 SDK 前重新查看 ZenMux 文档。

对于 gpt-image-2，自定义 WIDTHxHEIGHT 值的两条边都必须能被 16 整除，宽高比须介于 1:3 和 3:1 之间，总像素数须为 655,360-8,294,400。高于 2560x1440 的分辨率属于实验性分辨率；最大分辨率为 3840x2160。其他 OpenAI 图像模型应使用 auto、1024x1024、1536x1024 或 1024x1536。

4. 遵循 OpenAI 创建/编辑最佳实践

对于一次性生成或编辑，请使用 Images API。只有当用户的产品确实需要对话式、多轮图像状态时，才使用 Responses API；随附的辅助工具有意使用 Images API。

对于生成：

• 通过 TypeScript SDK 调用 client.images.generate。
• GPT Image 返回 b64_json；请解码并保存字节，不要进行转码。
• 如果模型允许，可在一次请求中使用 n 生成多个输出。
• transparent 背景需要 PNG 或 WebP。
• gpt-image-2 的透明 PNG/WebP 输出目前是预览功能。请使用 background=transparent 请求；仅要求输出 PNG 并不会创建 alpha 通道。
• output_compression 仅适用于 JPEG 或 WebP。

对于编辑：

• 调用 client.images.edit，并使用 SDK 的 toFile 辅助工具转换本地、远程或 data URL 字节。
• 最多提供 16 张输入图像，并保持其顺序。
• gpt-image-2 始终以高保真度处理图像输入，因此省略 input_fidelity。只有在身份保持很重要时，才对较早且支持该参数的 GPT Image 模型使用 input_fidelity=high。
• 蒙版作用于第一张输入图像。它必须是 PNG、小于 4 MB，且尺寸与第一张图像一致。完全透明的蒙版区域表示需要编辑的部分。
• 先说明所需更改，再明确列出所有必须保持不变的内容。

脚本将 URL 输出作为防御性后备方案，会验证返回图像的 magic bytes，使用超时/重试机制，且绝不会覆盖现有文件。

5. 优化并保存提示词

如果用户有一次性请求，则根据该请求确定模式；否则使用 prompt.mode。 调用模型负责优化提示词；此设置不会发送给图像 API，也不会触发额外的付费模型调用。

• direct（默认）： 根据用户请求、所提供的图像以及调用模型自身的判断进行优化。不要搜索、阅读或借用食谱或网络上的提示词示例。跳过下方的食谱搜索。仅在需要确认参数是否有效时查阅 API 文档；这些文档与提示词灵感来源不同。
• reference： 使用现有提示词食谱查找几个相关示例，然后根据用户意图进行调整。在提示词元数据中记录所用的食谱和条目。如果没有合适的示例，请说明改为直接优化，而不要声称使用了参考示例。

两种模式都接受用户提供的参考图像，保留编辑不变量，并使用相同的确认和生成流程。提示词参考模式仅控制示例提示词的检索。

在 reference 模式下，搜索相关食谱条目，但不要从头到尾阅读任何一本食谱：

rg -n '^### No\..*(poster|portrait|product|infographic)' \
  .context/zenmux-image-generation/references/awesome-gpt-image-2.md

OpenAI 相关示例使用 awesome-gpt-image-2.md，Gemini 相关示例使用 awesome-nano-banana-pro-prompts.md。调整其结构，而不是主题。

提示词顺序：

1. 场景/背景和构图
2. 主体及其动作
3. 材质、光线、色调、镜头/渲染风格
4. 需要时提供准确的引号内文案
5. [Image #N] 输入之间的编辑关系
6. 约束和不变量

编辑时，使用精确的指令，例如：“只更改 X。保留身份、姿势、几何形状、相机角度、光线、取景、背景以及所有未提及的细节。”每次后续编辑都重复列出不变量。

将提示词保存为：

.context/zenmux-image-generation/prompts/<YYYYMMDD-HHMMSS>-<short-slug>.md

使用以下格式，并填写本次调用的有效设置：

# Optimized prompt — <summary>

- **Prompt mode:** direct
- **Cookbook sources:** none
- **Model:** openai/gpt-image-2.5-flare
- **Size:** 1024x1536
- **Quality:** medium
- **Count:** 4
- **Output format:** png
- **Filename prefix:** launch-poster
- **References:** none
- **Created:** 2026-08-31 14:30 (Asia/Singapore)

---

<optimized prompt body>

向用户展示优化后的提示词和参数。未经用户确认，不要调用付费生成 API。如果用户要求进行小幅更改，请编辑同一个提示词文件。

6. 使用 TypeScript 生成

当配置选择 OpenAI 图像模型时，使用其配置的默认值生成（除非要有意覆盖本次调用的设置，否则省略标志）：

npm --prefix skills/zenmux-image-generation run generate:openai -- \
  --prompt-file ".context/zenmux-image-generation/prompts/<file>.md" \
  --filename-prefix "launch-poster"

使用 OpenAI 编辑图像，按顺序提供参考图并显式覆盖尺寸和质量：

npm --prefix skills/zenmux-image-generation run generate:openai -- \
  --prompt-file ".context/zenmux-image-generation/prompts/<file>.md" \
  --filename-prefix "outfit-edit" \
  --size "1024x1536" --quality "high" \
  --reference-image "/absolute/path/person.png" \
  --reference-image "https://example.com/jacket.webp"

对于带蒙版的编辑，添加 --mask-image "/absolute/path/mask.png"。对于较早的 GPT Image 模型，在支持时添加 --input-fidelity high。如需无损透明素材，添加 --background transparent --output-format png；如需体积更小的透明素材，则使用 WebP 并添加 --compression 85。

Gemini/Vertex 兼容模型：

npm --prefix skills/zenmux-image-generation run generate:gemini -- \
  --model "google/gemini-3.1-flash-image" \
  --prompt-file ".context/zenmux-image-generation/prompts/<file>.md" \
  --filename-prefix "campaign-poster" \
  --aspect-ratio "2:3" --image-size "1K"

TypeScript Gemini 助手涵盖 ZenMux 的两种协议形式：

• Google Gemini 图像模型使用 generateContent，或使用 --stream 调用 generateContentStream。它始终请求 TEXT 和 IMAGE，最多支持 14 张有序参考图，并使用 --aspect-ratio / --image-size 构建 imageConfig。
• 非 Google 模型使用 generateImages；存在参考图时使用 editImage。支持的 CLI 映射包括 --negative-prompt、--aspect-ratio、--image-size、--seed、--enhance-prompt、--person-generation、--safety-filter-level、--include-rai-reason、--add-watermark 和 --guidance-scale。
• 当有意通过 Gemini 协议调用 OpenAI 模型时，--size 和 --quality 是 OpenAI 直通字段。对于其他支持的 generateImages 提供方，--image-size 会映射为 sampleImageSize。
• ZenMux Vertex 协议不会映射 GPT Image 的 background 字段。要生成透明的 GPT Image 输出，请使用 generate-openai.ts。
• 省略 --aspect-ratio 和 --image-size 时，各提供方的默认值有所不同。有些提供方返回的 MIME 类型也可能与请求的不同；该助手会检测 PNG/JPEG/WebP 魔数并保存为相应扩展名。

--output-dir 为可选项，默认值为项目的 .context/zenmux-image-generation/output/。相对路径覆盖值相对于原始调用目录解析。仅当用户要求更改保存位置时才传入覆盖值；自动忽略规则已覆盖运行时工作区。

7. 适用于对象存储的文件名

每张保存的图像都使用以下确定性格式：

<semantic-prefix>-<model-slug>-<utc-millisecond-timestamp>-<8-hex-run-id>-<index>.<ext>

示例：

launch-poster-openai-gpt-image-2-5-flare-20260912t143012345z-a1b2c3d4-01.png

此命名规则刻意采取保守策略，以兼容 Supabase Storage、S3 兼容 API、CDN 和签名 URL：

• 文件名主体仅使用小写 ASCII：a-z、0-9 和 -
• 在 png、jpg 或 webp 前仅使用一个末尾的 .
• 不使用空格、Unicode、斜杠、反斜杠、控制字符、URL 保留标点、前导点或 .. 片段
• 使用 UTC 毫秒时间戳，以便按字典顺序排序
• 添加随机运行 ID 和输出索引，以避免并发运行时发生冲突
• 以独占方式创建文件，确保发生冲突时不会覆盖现有对象

始终传入简洁且具有语义的 --filename-prefix。如果省略，脚本会从提示词文件名推导前缀，并按相同规则进行清理。

8. 报告并迭代

成功时，脚本会输出 SUCCESS、OUTPUT_DIR、IMAGE_PATHS 和单行 RESULT_JSON。如果其他工具需要稳定的机器可读输出，请解析 RESULT_JSON。向用户返回可点击的绝对路径。

后续编辑时，将选定的图像保留为 [Image #1]，保存一份重述不变要求的新提示词，确认提示词后，再运行相应的编辑流程。

如果生成失败：

• 缺少依赖项：运行 npm ci --prefix skills/zenmux-image-generation。
• 模型不可用：重新运行 list_models.sh --force；使用精确的实时 ID。
• 尺寸无效：选择最接近的有效尺寸，同时保持宽高比。
• 参考图被拒绝：将其转换为 PNG/JPEG/WebP，并确保文件大小低于模型的输入限制。
• 提供方拒绝生成多个输出：使用 --n 1 循环调用，并保留相同的语义前缀；每次运行的 ID 都会确保文件名唯一。