gemini-image-gen

name	gemini-image-gen
description	使用 Gemini 生成和编辑配图。支持手绘白板风、精致矢量图风、温馨卡通信息图等六种预设模板，项目可自定义模板覆盖默认值。当用户需要为文章、文档生成插图、配图、概念图，或基于已有图片进行编辑时使用。
allowed-tools	Read, Bash, Grep, Glob, Write

Gemini 配图生成与编辑

通过 Google Gemini API 生成和编辑文章配图，内置两种风格模板，项目可自定义扩展。

环境要求

脚本会自动从 ~/.zshrc、~/.zshenv、~/.bashrc、~/.profile 中读取 GEMINI_API_KEY，无需手动 source。代理也会自动探测本地 SOCKS5 端口（1080/7890/7891）。

如需手动配置：

# 必须：Gemini API Key（https://aistudio.google.com/apikey）
# 通常已在 ~/.zshrc 中设置，脚本会自动读取
export GEMINI_API_KEY='your-key'

# 可选：代理配置（脚本会自动探测本地 SOCKS5 端口）
# 不需要代理时设置为 none
export GEMINI_PROXY='none'

# 可选：模型选择（默认 gemini-3-pro-image-preview）
export GEMINI_MODEL='gemini-2.5-flash-image'

工作流程

第一步：确定模板

读取提示词模板，优先级从高到低：

1. 项目自定义：项目根目录的 .gemini-image-templates.yaml
2. Skill 默认：$SKILL_DIR/templates/default.yaml

# 检查项目是否有自定义模板
if [ -f ".gemini-image-templates.yaml" ]; then
  echo "使用项目自定义模板"
else
  echo "使用默认模板: $SKILL_DIR/templates/default.yaml"
fi

默认模板包含六种风格：

模板	名称	适用场景
template_a_handdrawn	手绘白板风	概念解释、前后对比、简单流程、一句话总结
template_b_vector	精致矢量图风	技术概念、工具介绍、系统关系、抽象概念具象化
template_c_4panel_comic	四格漫画	起承转合故事、流程展示、幽默段子、技术拟人化
warm-cartoon-multicolor	温馨卡通多彩版	流程说明、知识科普、产品介绍（白底+元素语义配色）
warm-cartoon-monotone	温馨卡通单色版	同上，单色调统一感（奶油底+主色调倾向）
warm-cartoon-minimal	温馨卡通极简版	同上，极简提示词让模型发挥（奶油底+超简表情）

第二步：选择模板 + 组装 prompt

根据配图内容选择合适的模板。从 YAML 中取出 style 各字段，拼接为完整 prompt：

[style.base]
[style.color]
[style.typography]
[style.text_quality]
[style.composition]
[style.resolution]

Scene ([default_aspect_ratio] aspect ratio):
[用户描述的具体画面内容]

Chinese labels: [需要出现的中文文字]

prompt 组装规则：

• style 各字段原样拼接，作为风格约束（所有同模板的图共享）
• Scene 部分根据每张图的具体内容填写
• Chinese labels 单独列出所有需要渲染的中文，短于 6 字为佳
• 宽高比写入 Scene 描述中（如 "4:3 aspect ratio"），因为 REST API 不支持 imageGenerationConfig 参数

第三步：调用生成脚本

# 生成新图片（指定输出路径）
bash $SKILL_DIR/scripts/gen-image.sh -o <output_path> "<prompt>"

# 生成新图片（不指定路径，默认保存到当前目录 ./generated-YYYYMMDD-HHMMSS.png）
bash $SKILL_DIR/scripts/gen-image.sh "<prompt>"

# 编辑已有图片
bash $SKILL_DIR/scripts/gen-image.sh -i <input_image> -o <output_path> "<prompt>"

脚本说明：

• -o 输出路径，支持任意 png/jpg 路径，目录不存在会自动创建。省略时默认保存到当前工作目录
• -i 输入图片路径（可选），用于基于已有图片进行编辑
• 最后一个参数是第二步组装好的完整 prompt 文本
• 成功时 stdout 输出文件路径和大小，失败时 stderr 输出错误信息
• 默认使用 gemini-3-pro-image-preview 模型（中文文字渲染最好）
• GEMINI_API_KEY 自动探测：脚本会自动从 ~/.zshrc 等配置文件中提取，无需手动 export
• 代理自动探测：脚本会自动检测本地 SOCKS5 端口（1080/7890/7891），无需手动配置

第四步：验证结果

生成后必须用 Read 工具查看图片，检查：

• 中文文字是否清晰、正确（无幻觉字符）
• 构图是否符合描述
• 风格是否与同批次其他图一致

如果中文有误，优先尝试：缩短文字（6字→2字）、换用更常见的词、调整文字位置到更空旷的区域。

批量生成示例

为一篇文章生成多张配图时的典型流程：

# 读取文章，找出所有 [配图建议: xxx] 标记
# 为每个标记选择模板、组装 prompt、调用脚本

STYLE_A="Hand-drawn whiteboard sketch illustration style. White background. Black ink hand-drawn line art..."
TEXT_RULES="CRITICAL: All Chinese characters must be sharp, crisp..."

# 配图1：手绘风
bash $SKILL_DIR/scripts/gen-image.sh -o ./images/01-concept.png "${STYLE_A} ${TEXT_RULES} Scene (4:3 aspect ratio): ..."

# 配图2：矢量风
bash $SKILL_DIR/scripts/gen-image.sh -o ./images/02-architecture.png "${STYLE_B} ${TEXT_RULES} Scene (4:3 aspect ratio): ..."

图片编辑

基于已有图片进行修改，用 -i 传入原图：

# 修改配色
bash $SKILL_DIR/scripts/gen-image.sh -i ./images/01-concept.png -o ./images/01-concept-v2.png "Change the accent color from red to blue, keep everything else the same"

# 添加元素
bash $SKILL_DIR/scripts/gen-image.sh -i ./images/02-arch.png -o ./images/02-arch-v2.png "Add a database icon on the right side connected with an arrow"

# 扩展画布
bash $SKILL_DIR/scripts/gen-image.sh -i ./hero.png -o ./hero-wide.png "Extend this image to 21:9 aspect ratio, expanding the background naturally on both sides"

编辑时的 prompt 不需要重复完整的风格模板，只需描述要做的修改。模型会保持原图的风格和内容，仅应用指定的变更。

项目自定义模板

在项目根目录创建 .gemini-image-templates.yaml，格式与默认模板一致：

# .gemini-image-templates.yaml
template_a_handdrawn:
  name: "我的手绘风"
  style:
    base: >
      ...自定义风格描述...
    color: >
      ...自定义配色...
    # 其他字段同默认模板结构
  default_aspect_ratio: "16:9"

# 可以添加更多自定义模板
template_c_custom:
  name: "品牌风格"
  style:
    base: >
      ...

已知限制

1. REST API 不支持 imageGenerationConfig：宽高比、分辨率只能写入 prompt 文本，模型大多数时候会遵守
2. 中文渲染非 100%：Gemini 3 Pro 在 4K 下约 94% 准确率，短文本好于长文本
3. 需要代理：国内直连 Gemini API 会报 User location is not supported，需走 SOCKS5
4. SynthID 水印：所有生成图片自动包含不可见的 SynthID 水印，无法关闭

模型选择建议

需求	推荐模型
中文文字清晰	gemini-3-pro-image-preview（默认）
快速迭代/草稿	gemini-2.5-flash-image
复杂场景/4K	gemini-3-pro-image-preview