generate-image

需要 GEMINI_API_KEY 环境变量和 uv 包管理器。

工作流

1. 理解 — 确定模式（t2i、i2i、多参考图），收集参数（模型、宽高比、分辨率、输出路径）。如果提示词要求精确执行（特定姿势、不对称构图、精确裁切），默认使用 --batch 3 或 --batch 4，并告知用户这一点——图像生成具有随机性，精确指令在每个随机种子下的成功率约为 50%。完成条件：模式、参数和批次大小均已明确。
2. 撰写提示词 — 默认使用能够表达意图的最简提示词：t2i 使用叙述性文字；i2i／多参考图使用参考内容块加最简指令。对匹配模式始终应用 Core 检查清单。只有遇到已知难点——细节／几何保真度较高的图像——或批次结果出现偏差时，才启用 Escalation toolkit；此时只添加针对偏差属性的特定约束，而不是整套工具。对简单编辑施加过多约束，会像对复杂任务描述不足一样降低效果。完成条件：提示词已撰写，满足 Core 项目；只有在特征或观察到的偏差足以证明其合理时，才添加升级工具。
3. 确认 — 向用户展示确切的提示词、输入图像（如有）、模型、分辨率、宽高比和批次大小。征求确认。完成条件：用户已批准。
4. 生成 — 使用确认后的参数运行脚本。完成条件：图像已保存并显示。
5. 迭代 — 展示结果，并在提供改进建议前，根据意图评估结果。按模式依次评估：t2i — 主体正确性、构图、风格保真度。i2i 编辑 — 更改的元素符合预期，其他内容未变。多参考图合成 — 第一，主要迁移属性与其来源参考图匹配（对于细节图，检查构造几何特征——宽度、边缘形状、数量、角度）；第二，次要一致性（身份、环境）得到保持；第三，场景布置（光照、构图、取景）符合预期。根据任务确定哪项最重要。当一致性超过约 75% 时，从批次中挑选最佳图像，而不是反复调整提示词。完成条件：用户满意或决定继续其他事项。

默认输出与日志记录

用户未指定位置时，将图像保存到：

~/Documents/generated images/

每张生成的图像都会附带一个 .md 文件，记录所用提示词和模型（例如，logo.png → logo.md）。

收集参数（宽高比、分辨率）时，提供指定自定义输出位置的选项。

核心提示词原则

用叙述方式描写场景，而非罗列关键词。 Gemini 的语言模型能够充分理解散文的语义——叙述式提示词可以表达空间关系、氛围和意图，而用逗号分隔的标签无法做到。标签式提示词会丢失构图含义，生成的结果也会很普通。

Bad:  "cat, wizard hat, magical, fantasy, 4k, detailed"

Good: "A fluffy orange tabby sits regally on a velvet cushion, wearing an ornate
       purple wizard hat embroidered with silver stars. Soft candlelight illuminates
       the scene from the left. The mood is whimsical yet dignified."

正面描述，切勿使用否定表达。 提示词中提到的每个概念都会让输出偏向该概念——即使前面加了“不是”“没有”或“不要”。无论词语的肯定或否定含义如何，扩散模型都会以这些词元为条件。若要排除 X，可以 (a) 指定一个承担相同作用的正面替代项，或 (b) 限定提示词的范围，让 X 无处出现。

Bad:   "A clean studio backdrop. No warm tones, no cream, no beige, no tan."
Good:  "A clean cool-neutral gray studio backdrop with subtle blue undertones."

Bad:   "A headshot with no harsh shadows on the face, no distracting background."
Good:  "A headshot on a clean neutral gray backdrop, even soft frontal fill light
        that flatters the face."

这条规则适用于此技能中的所有内容——t2i 提示词、i2i 指令、参考图角色描述和构图指示。

明确指出来源——让参考对象毫无歧义。 提示词中的每个元素都应对应到具体来源：“Image 2 中的男人”，而不是“这个男人”；“Image 3 中的衬衫”，而不是“这件衬衫”。模糊的指代会绑定到模型权重最高的来源，而这个来源不一定是正确的。重点不是过度描述——参考图已经展示的内容无需重新描述。关键是让每个指代都准确对应到唯一来源。

一个实用公式：[主体] 在 [情境] 中做 [动作]。[相机/构图]。[光线]。[风格]。[限制条件]。 并非每个提示词都需要包含所有元素——根据意图调整细节。如果用户有明确构想，就给出具体描述；如果用户在探索，则保持开放（提供大致方向，让模型决定细节）。若不清楚，请先询问。

高级提示词技巧

高度具体：准确说明数量、位置和属性。“三颗红苹果摆成三角形，放在木桌上”比“桌子上有些苹果”效果更好。每个含糊的词都会给模型留下一分可任意填补的空间。

情境与意图：说明用途。“咖啡品牌落地页的主视觉图”和“一张咖啡照片”会生成不同结果，即使视觉主体相同，因为意图会影响构图、氛围和取景。

分步指令：对于复杂场景，将提示词拆分为循序渐进的指令。“先呈现一片广阔的沙漠。将一个独自行走的人物放在画面下方三分之一处，行进方向为从左到右。在人物身后，一场巨大的沙尘暴从右侧逼近。”

通过正面约束进行排除：如果输出中必须不出现某种内容，不要用否定句提到它。可以指定正面替代项（用“干净的无品牌表面”代替“没有标志”），或限定场景，让不需要的元素无处出现（“桌上放着一台合上的笔记本电脑”，就不可能渲染出屏幕）。在“没有 X”中提到 X，只会增加 X 出现的可能性，而非降低。

相机控制：指定镜头类型（极近特写、中景、航拍）、镜头（鱼眼、长焦）和相机角度（低角度、鸟瞰、荷兰角），以精确控制构图。

使用参考图进行编辑时，应遵循不同的原则——请参阅 references/editing-guide.md。

---

编辑的关键原则

编辑提示词应直接指示要进行的更改，而不是描述场景。指出模型能看到的内容；只描述它看不到的内容。有意取舍——超出最低限度的每个形容词、颜色词或保留条款，都会与参考图像争夺注意力，降低保真度。可靠的结构是一个参考块加上一条 Replace 指令——动词的隐含范围会处理保留内容，无需添加停止条款。详见 editing-guide.md。

对于多参考图像（3 张以上），使用逐张参考图像角色分配：用一个句子为每张参考图像指定其特定作用（“Image 2 中的立面；Image 3 中的汽车；Image 1 中的天空和光线”）——参见 editing-guide.md 中的“逐张参考图像角色分配”。

名称可以直接唤起美学风格——提及“用 Kodak Portra 400 拍摄”，比描述温暖的肤色和柔和的高光更可靠地呈现其典型效果。

---

参考资料

编写提示词时加载相关参考资料（工作流第 2 步）：

• references/capability-patterns.md — 针对不同模式的技巧，涵盖写实场景、产品摄影、徽标、风格化插画、文本渲染和信息 grounding
• references/editing-guide.md — 编辑语法、参考块、指令结构、图像排序、语义遮罩、角色一致性
• references/style-reference.md — 命名美学风格词汇表（胶片、相机、工作室、艺术家、流派）

---

配置

模型选择

	Nano Banana（默认）	Nano Banana Pro
速度	快速，适合高吞吐量	较慢，质量更高
分辨率	0.5K、1K、2K、4K	1K、2K、4K
额外比例	1:4、4:1、1:8、8:1	—
思考模式	支持（minimal/low/medium/high）	不支持
图像搜索 grounding	支持	不支持
最多参考图像数	14	11（6 个物体 + 5 个角色）
文本渲染	高级	标准

大多数请求默认使用 Nano Banana。只有在用户明确要求最高质量，或需要进一步优化 Nano Banana 的结果时，才使用 Nano Banana Pro。

宽高比

两种模型均支持：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9
仅 Nano Banana 支持：1:4、4:1、1:8、8:1

分辨率

• 0.5K（约 512px）— 快速预览（仅 Nano Banana）
• 1K（约 1024px）— 默认，速度快
• 2K（约 2048px）— 高质量
• 4K（约 4096px）— 最高细节

默认值：1K 分辨率、批量数 1、宽高比根据底图自动检测（第一张输入图像；如果没有图像则为 1:1）。快速预览和迭代时使用 0.5K（仅 Nano Banana）。需要更高质量时使用 2K；仅在明确需要高细节时使用 4K。

思考模式（仅 Nano Banana）

Nano Banana 支持可控的思考级别，可提升对复杂提示词的理解：

• minimal（默认）— 速度最快，适用于简单明了的提示词
• low/medium — 适用于中等复杂场景的均衡推理
• high — 适用于复杂多元素构图、精准文本渲染或复杂空间布局的最高级别推理

当提示词涉及精确的空间关系、多个文本元素或详细的构图要求时，使用 --thinking high。对于 i2i 编辑，思考模式也有助于处理多参考图像构图（3 张以上）、在现有场景中精准放置文本或标志，以及元素定位至关重要的复杂空间编辑。

---

脚本用法

一个统一脚本可处理所有模式：t2i、i2i 和多参考图像构图。Nano Banana 是默认模型。

# Text-to-image (t2i) — uses Nano Banana by default
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "A serene mountain lake at dawn" --output landscape.png

# Nano Banana Pro model
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "A serene mountain lake at dawn" --output landscape.png --model pro

# Image-to-image editing (i2i)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Make it sunset colors" --input photo.png --output edited.png

# Multi-reference composition
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Combine the cat from image 1 with the background from image 2" --input cat.png --input background.png --output composite.png

# With options (aspect ratio, resolution, thinking, batch, grounding, format)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Logo for 'Acme Corp'" --output logo.png --aspect 1:1 --resolution 2K --thinking high

脚本选项

标志	短选项	说明
--prompt	-p	图像描述或编辑指令（必填）
--output	-o	输出文件路径（必填）
--input	-i	用于编辑或合成的输入图像（可重复，最多 14 张）
--model	-m	模型：nano-banana（默认）或 pro
--aspect	-a	宽高比（自动从基础图像 / 第一张输入图像检测，或设为 1:1）
--resolution	-r	输出分辨率：0.5K、1K、2K 或 4K（默认：自动检测或 1K）
--grounding	-g	启用 Google Search 网络检索
--image-grounding		启用图像搜索检索（仅限 Nano Banana，需与 --grounding 配合使用）
--thinking	-t	思考等级：minimal、low、medium、high（仅限 Nano Banana）
--quality	-q	输出压缩质量，范围为 1-100（仅限 JPEG）
--format	-f	输出格式：png（默认）或 jpeg
--batch	-b	生成多个变体：1-4（默认：1）
--json		将结果输出为 JSON，供 Agent 使用
--quiet		不显示进度信息（仍会打印 MEDIA 行）

如果未指定标志，脚本会自动检测输入图像的分辨率和宽高比，并在发送到 API 前自动调整过大的输入图像（>2048px）。

---

生成前检查清单

核心项目是最低要求——对所有匹配模式的提示词都要应用。升级工具包为可选项：对于简单的 t2i 和单元素编辑，可完全跳过。仅在遇到已知的难点特征（细节 / 几何结构保真度要求高的镜头）或批量生成结果出现偏差后再使用，并且只添加针对实际发生偏差属性的约束。每增加一项约束，都会降低其他所有内容的保真度，因此升级程度应取决于可能发生偏差的独立要素数量，而非提示词的雄心程度。

核心 — t2i（始终适用）

• 使用叙述式描述（而非关键词列表）？
• 始终采用正向表述——提示词中是否完全没有“no X” / “not X” / “do not X”之类的从句？
• 是否包含用于写实效果的相机 / 光线细节？
• 文本是否加引号，并描述了字体样式？（图像中含有文本时）
• 宽高比是否适合使用场景？
• 模型选择是否合适？（默认使用 Nano Banana；追求最高质量时使用 Nano Banana Pro）
• 是否为复杂提示词设置了思考等级？（仅限 Nano Banana）
• 批量大小是否符合精度需求？（对精确姿势 / 构图 / 非对称指令使用 --batch 3 或 --batch 4）

核心 — i2i / 多参考图（始终检查）

• 提示词开头是否有参考图说明块，为每张图片标注角色？
• 参考图角色是否仅作正向说明——列出每张参考图中要使用的内容，从不说明要忽略什么？（参见 editing-guide.md 中的 “Reference Block”）
• 是否采用最简指令模式？（参考图说明块 + 一条替换指令——不添加“其他内容一律不变”的停止条款，也不添加装饰性的保留条款）
• 指令全文是否采用正向表述？（任何地方都不使用否定表述，包括锁定和构图条款）
• 基础图是否排在 --input 的第一位（Image 1），且提示词中的标签与输入顺序一致？（角色标错会导致人物特征漂移）
• 每条提示词是否只做一项更改？（将相互冲突的指令拆分为连续多轮处理）
• 提取或转移元素时，是否逐一明确写出每个元素，而不是笼统地说“来自 Image X 的服装／物品”？
• 一张参考图中有需要保留的元素，而另一张参考图可能与之冲突？→ 主动添加 CRITICAL — [element]：明确指定来源参考图（“Image 1 是唯一的身份来源。Image 2 仅用于 [attribute]。”）。不要等到出现漂移才处理——不同角色之间的冲突会悄无声息地削弱文本指令。
• 是否避免使用与参考图冲突的颜色标签？（颜色词会覆盖视觉参考——参见 editing-guide）
• 基础图是否有可能干扰生成的多余配饰？（包、帽子、太阳镜可能会渗入输出）
• 参考图数量是否在模型限制内？（Nano Banana：14，Nano Banana Pro：11）
• 使用 3 张或更多参考图时，是否为每张参考图分配角色？（用一句话说明每张图片提供什么——参见 editing-guide.md 中的 “Per-Reference Role Assignment”）
• 对于写实人物照片，是否锁定了肤质和质感？（这是几乎普遍适用的 CRITICAL 部分——生成式模型容易将肤质处理得像塑料或经过修图）

升级工具包 — 仅在关键特征难以保持或观察到漂移时使用

• 某项属性（身份、光线／颜色、朝向、垂坠效果）在批次生成中发生漂移？在单独的 ## CRITICAL — 部分中锁定该具体属性，并采用正向表述——不要过度约束稳定属性。（参见 editing-guide.md 中的 “Constraint Locking with CRITICAL Sections”）
• 细节镜头的结构难以保持？通过逐项列举属性来锁定几何形状，而不是笼统地要求“完全匹配”。（参见 capability-patterns.md 中的 “Geometry Lock for Detail Shots”）
• 使用 Nano Banana + --thinking high，且有 3 张或更多参考图，但遵循度较弱？添加清单前置说明。（“Silently inventory the design-critical details: ...”）
• 同一组中的后续镜头？添加连续性声明。（“from the same set as Image N: same subject, same setting, same light”——参见 editing-guide.md 中的 “Continuity Assertion”）
• 营销活动中有已锁定的主视觉图？简化为双输入形式——将主视觉图作为组合来源，再加上单张新属性参考图。（参见 editing-guide.md 中的 “Single-Reference Collapse”）