gpt-image-2

name	gpt-image-2
description	生成**装饰 / 叙事类位图插画**（题图、概念氛围图、绘本 / 场景感插画）的图像生成技能。基于 GPT Image 2，可在 3 种环境下使用：(A) Garden 本地模式，通过 OpenAI 兼容接口直接出图并落盘；(B) Host-Native 模式，把渲染好的 prompt 交给宿主 Agent 自带的图像工具出图；(C) Advisor 模式，宿主无图像工具时退化为高质量 prompt 顾问。产出的是**非精确的装饰 / 叙事位图**；对几何精确、可无损缩放的技术图（数据图表、结构图、示意图等），调用方应改用矢量工具，本 Skill 不负责。

GPT Image 2 · 装饰 / 叙事插画

这是一个聚焦型图像技能，专注生成装饰 / 叙事类插画——题图、概念氛围图、绘本 / 场景感插画等非精确的装饰 / 叙事位图。在 3 种运行环境下都能用，但行为差异显著，第一步必须先确定当前运行模式。

适用边界

• 适用：装饰 / 叙事 / 情绪类插画（位图 PNG 即可，不要求几何精确）。
• 不适用：任何要求几何精确、可无损缩放、承载数据 / 结构正确性的技术图（数据图表、系统结构图、流程 / 示意图、需要精确对齐的图解）。这类图应交给矢量工具（TikZ / mermaid / draw.io 等）——位图无法随文档任意缩放，也画不准精确结构。
• 具体哪些图归本 Skill、哪些走矢量工具，由调用方（domain 配置）决定；本 Skill 只提供"出装饰位图"这一能力。通用判据：只要图承载正确性 / 精确性，就不该用本 Skill。

它只做两类图像任务：

• 生成图片：POST /images/generations
• 编辑图片：POST /images/edits

本文件保留：运行模式、技能结构、环境变量、保存 / 命名规则、模板索引、模式感知工作流。详细模板全部放在 references/，分层组织：

• 一级：分类目录
• 二级：单模板 Markdown 文件

运行模式（必读，做任何事之前先确定）

本 Skill 自带一个轻量探测脚本，先跑一次，再根据结果决定怎么干活：

node skills/gpt-image-2/scripts/check-mode.js
# 想拿结构化结果给上层程序用：
node skills/gpt-image-2/scripts/check-mode.js --json

输出会给出 mode = A / A? / B-or-C 以及 recommendation。三个模式定义如下：

Mode A · Garden 本地生图

触发条件：环境变量 ENABLE_GARDEN_IMAGEGEN 为真（1 / true / yes / on）且 存在 OPENAI_API_KEY。

行为：完整端到端跑通"选模板 → 写 prompt → 调用脚本 → 出图落盘"。

• 用 scripts/generate.js 文本生图、scripts/edit.js 编辑现有图。
• prompt 默认落盘到 garden-gpt-image-2/prompt/、图片落盘到 garden-gpt-image-2/image/。
• 这是最强的模式：你是图像工具的"持有者"。

Mode B · Host-Native 委托宿主出图

触发条件：未启用 Garden（ENABLE_GARDEN_IMAGEGEN 未设置 / 为假），但当前宿主 Agent 自带图像生成工具或图像 MCP。

典型识别信号（你应该自检）：

• 你的工具集里出现 image_generation / imagegen / dalle / nano_banana / mcp__*image* / make_image / 类似名字
• 用户在 ChatGPT / Codex / Gemini / Cursor 等支持原生出图的客户端中调用本 Skill
• 用户显式说"用你自己的工具出图"

行为：本 Skill 退化成提示词工程指引——

1. 仍按"选模板 → 填字段 → 渲染最终 prompt"的流程走。
2. 不要调用 node scripts/generate.js（没有 API key、必失败）。
3. 直接调用宿主自带的图像工具，把渲染好的 prompt 作为输入。
4. 如用户希望可顺手把 prompt 文件保存到 garden-gpt-image-2/prompt/，但图片去向由宿主决定，不强制。

Mode C · Advisor 纯提示词顾问

触发条件：未启用 Garden，且宿主 Agent 也没有任何图像生成工具。

行为：本 Skill 退化为"高质量 prompt 撰写顾问"——

1. 按"选模板 → 填字段 → 渲染最终 prompt"流程走，缺信息就问用户。
2. 把最终 prompt 直接打印给用户 + 保存一份到 garden-gpt-image-2/prompt/<task-slug>-<timestamp>.md。
3. 附一句简短的"如何使用"建议（如：丢进 ChatGPT / Midjourney / DALL·E / Sora / Nano Banana / 自己后端 / 第三方 GPT Image 2 网关）。
4. 不要假装出图成功。明确告知用户："已生成可直接复用的高质量 prompt，请用你的图像工具执行。"

模式决策表

条件	模式	调用脚本？	落盘 prompt？	落盘图片？
ENABLE_GARDEN_IMAGEGEN=1 + 有 KEY	A	✅ generate.js / edit.js	✅ 自动	✅ 自动
ENABLE_GARDEN_IMAGEGEN=1 但没 KEY	A?	❌（先要 KEY）	—	—
未启用 + 宿主有图像工具	B	❌（用宿主工具）	可选	由宿主决定
未启用 + 宿主无图像工具	C	❌	✅ 必须	❌（无法）

模式不确定时

• 如果你判断不清自己是 B 还是 C，直接问用户一句："是用你环境里的图像工具出图，还是只要我写好提示词？"
• Mode A 调脚本失败（401 / 网络 / 配额）→ 报错并询问"切到 B / C 吗？"

用户输入工具

当此技能需要向用户提问时，遵循以下规则：

1. 优先使用当前运行时提供的用户输入工具。
2. 如果没有对应工具，则用简短的纯文本编号问题提问。
3. 能合并的问题尽量一次问完。

技能结构

• scripts/check-mode.js：先跑这个，检测运行模式（A / B / C）
• scripts/generate.js：文本生图（仅 Mode A 使用）
• scripts/edit.js：基于原图 / 遮罩改图（仅 Mode A 使用）
• scripts/shared.js：共享请求、保存、环境变量读取逻辑
• references/：分层结构化提示词模板（A / B / C 三模式都用）

环境变量

按以下顺序读取配置：

1. CLI 参数
2. process.env
3. <cwd>/.env
4. <cwd>/.gateway.env
5. ~/.gateway.env

核心变量：

• ENABLE_GARDEN_IMAGEGEN — 模式开关。1 / true / yes / on 时启用 Mode A；未设置或其它值则进入 Mode B / C。
• OPENAI_API_KEY — Mode A 必需；B / C 不需要。
• OPENAI_BASE_URL — 默认 https://api.openai.com/v1，可指向第三方兼容网关。
• OPENAI_IMAGE_MODEL — 默认 gpt-image-2，可换成网关支持的型号（如 gpt-image-1 / dall-e-3）。

默认实现按 OpenAI 兼容接口工作，不写死任何第三方网关。

默认输出目录

如果用户没有明确指定输出路径，统一使用当前工作区下的：

• 提示词目录：garden-gpt-image-2/prompt/（A / B / C 三种模式都建议用，方便复用与版本管理）
• 图片目录：garden-gpt-image-2/image/（仅 Mode A 使用；Mode B 由宿主决定，Mode C 不产生图）

如果目录不存在，脚本（Mode A）必须自动创建；Mode B / C 在写 prompt 前手动 mkdir -p。

默认命名规则

如果用户没有明确指定文件名，脚本应自动生成与当前任务相关的文件名，并追加当前时间戳，避免重名。

命名规则：

• 提示词：garden-gpt-image-2/prompt/<task-slug>-<timestamp>.md
• 图片：garden-gpt-image-2/image/<task-slug>-<timestamp>.png

其中：

• <task-slug>：根据当前用户要求自动提取一个相关短名称
• <timestamp>：当前时间戳，例如 20260424-153045

示例：

• garden-gpt-image-2/prompt/ch01-opener-clock-scene-20260424-153045.md
• garden-gpt-image-2/image/ch01-opener-clock-scene-20260424-153045.png
• garden-gpt-image-2/prompt/section-interlude-mood-20260424-153102.md
• garden-gpt-image-2/image/section-interlude-mood-20260424-153102.png

Prompt 保存规则

模式	是否必须保存 prompt	说明
Mode A	✅ 必须	进入实际生成 / 编辑流程必落盘
Mode B	推荐	默认建议保存方便复用；用户说"不用"就略过
Mode C	✅ 必须	用户拿走 prompt 自己执行，不落盘等于白干

通用规则（适用三种模式）：

1. 如果用户显式给了 prompt 文件路径，可直接使用该文件作为输入。
2. 如果用户直接给的是文本 prompt，也要先把最终 prompt 保存到 garden-gpt-image-2/prompt/。
3. 如果用户显式指定了 --prompt-output，则尊重用户指定路径。
4. 否则使用默认命名规则自动保存。

图片保存规则（仅 Mode A）

1. 如果用户显式指定了 --image 或 --output，则尊重用户指定路径。
2. 否则默认保存到 garden-gpt-image-2/image/。
3. 文件名应和当前任务语义相关，并附加时间戳。

Mode B 由宿主图像工具决定保存方式；Mode C 不产生图片。

快速用法

0. 检测运行模式（任何任务的第一步）

node skills/gpt-image-2/scripts/check-mode.js

输出会告诉你当前是 Mode A / B / C，决定后续是否调用 generate.js / edit.js。下面 1~4 仅在 Mode A 下使用。

1. 文本生图（Mode A）

node skills/gpt-image-2/scripts/generate.js \
  --prompt "A cute baby sea otter" \
  --size 1024x1024 \
  --quality high

2. 用提示词文件生图（Mode A）

node skills/gpt-image-2/scripts/generate.js \
  --promptfile garden-gpt-image-2/prompt/poster-20260424-153045.md

3. 编辑已有图片（Mode A）

node skills/gpt-image-2/scripts/edit.js \
  --image assets/source.png \
  --prompt "Replace the background with a clean studio scene"

4. 带遮罩的局部编辑（Mode A）

node skills/gpt-image-2/scripts/edit.js \
  --image assets/source.png \
  --mask assets/mask.png \
  --prompt "Replace only the masked area with a glass vase"

5. Mode B / C 的"用法"

没有命令行入口——本 Skill 此时只是提示词工程指南：

• Mode B：渲染好最终 prompt → 调用宿主自带的 image_generation 类工具（参数中传入 prompt）→ 拿到图。
• Mode C：渲染好最终 prompt → 保存到 garden-gpt-image-2/prompt/<task-slug>-<timestamp>.md → 把内容直接展示给用户 → 提示用户在哪些图像工具中可以直接复用。

JSON 模板工作方式

当 references/ 中提供 JSON 模板时，按下面规则使用：

1. 先从 SKILL.md 找到最贴近的分类目录。
2. 再定位到具体模板文件。
3. 模板中的 {argument ...} 表示可替换参数。
4. 用户明确提供的值，直接填入。
5. 用户没有提供，但模板标了 default 的，默认可以先用默认值。
6. 如果缺失信息会显著影响结果，主动询问用户。
7. 用户也可以明确说“你随机生成”，这时可以保留默认值或在模板允许范围内合理随机化。

询问规则

当模板缺少关键变量时，不要笼统地问“你想要什么风格？”。应当根据模板字段精确提问。

例如直播 UI 模板缺少主体时，应优先问：

• 主播是谁？
• 用真人照片、名人名字、人物描述，还是完全随机生成？

缺少商品信息时应问：

• 商品名称是什么？
• 商品价格是否指定？
• 是否希望我自动补全评论和礼物内容？

模板索引

本 Skill 只保留装饰 / 叙事插画相关的模板。按任务只读取最贴近的具体模板文件，不要一次性全读整个 references/。

1. 方法论总文档

先读：

• references/prompt-writing.md

适用于：

• 你还没决定怎么构造 prompt
• 你需要判断哪些字段该问、哪些字段可默认、哪些字段可随机
• 你需要把一次插画需求抽象成可复用写法

2. Scenes & Illustrations (references/scenes-and-illustrations/)

装饰 / 叙事插画的模板目录——氛围 + 故事 + 情绪类插画。当前已落地：

• picture-book-scene.md — 童书 / 绘本内页 / 节日卡片风（题图首选：把抽象概念拟人化 / 场景化，温暖易亲近）
• concept-scene.md — 电影感概念大场景 / key art（用于开篇、章节之间的过场大图）
• healing-scene.md — 治愈系日常 / 季节场景插画（用于轻松的旁白页、配图氛围）
• minimalist-mood-scene.md — 极简留白氛围图 / 文学性配图（用于引言、致谢、结尾留白）

选择策略：题图 / 概念拟人化用 picture-book-scene；过场大图用 concept-scene；轻松旁白氛围用 healing-scene；引言 / 结尾留白用 minimalist-mood-scene。所有这些都是装饰性位图，不承载正确性——凡是要画对精确结构的图，交给矢量工具（见"适用边界"）。

提示词工作流（模式感知）

无论 A / B / C，前 6 步是共用的；区别只在第 7-8 步如何"出图"。

1. 跑 check-mode.js 确定模式（A / B / C）。
2. 判断任务是生图还是改图。
3. 识别它属于哪个分类目录（参考下方"模板索引"）。
4. 只读取对应的具体模板文件，不要一次读整个 references/。
5. 严格遵循模板格式：scenes-and-illustrations/ 下的插画模板多用「结构化自然语言 + 参数」混合形式（强行 JSON 会限制创作自由）；按模板原样使用即可。
6. 把用户输入映射到模板参数；关键信息不足时主动发起有针对性的澄清问题。

到此 prompt 已渲染好。下面按模式分叉：

7-A. Mode A：把最终 prompt 保存到 garden-gpt-image-2/prompt/，调用 scripts/generate.js 或 scripts/edit.js，图片落到 garden-gpt-image-2/image/。 7-B. Mode B：把最终 prompt 直接传给宿主的图像工具调用；按需保存 prompt 副本到 garden-gpt-image-2/prompt/。 7-C. Mode C：把最终 prompt 保存到 garden-gpt-image-2/prompt/<task-slug>-<timestamp>.md，并把完整 prompt 在对话中展示给用户，附一句简短的"如何使用 / 推荐工具"建议。

8. 任务结束后用一句话告诉用户：当前模式是什么、prompt 落在哪、图（如有）落在哪。

重要约束

通用：

• 模板文件中的 JSON 是提示词结构模板，不是 API 请求体模板。
• 三种模式下，最终交给图像模型的都是"渲染后的 prompt 字符串"——可以是拍平的 JSON、可以是结构化自然语言段落，按模板原样使用。
• 除非用户明确要求，否则不要把 SKILL.md 里的"模式说明"复制到最终 prompt 里——那是给 Agent 看的元信息。

仅 Mode A 适用：

• 生成脚本使用 JSON body
• 编辑脚本使用 multipart form data
• 响应优先按 data[0].b64_json 解析，也兼容 data[0].url
• 除非上游接口明确要求，不额外引入特殊 query 参数

何时提问

只在这些信息缺失且会显著影响结果时提问：

• 没有 prompt 目标
• 改图时没有原图
• 主体身份或视觉类型决定结果走向
• 商品 / 价格 / 文案 / UI 文本是画面核心组成部分
• 用户同时表达了多个互相冲突的目标

除此之外，优先自己做合理默认并继续执行。