image-generation

图像生成技能

为博客文章、文档和技术文章生成插图。工作流会根据提供方进行选择：

1. 优先使用 Codex 内置路径 —— 当前 Agent 为 Codex 且可使用内置的 image_gen 工具时，直接使用该工具。此路径不需要 OPENAI_API_KEY。
2. OpenAI API 回退 —— 在 Codex 之外，或内置工具不可用时，如果存在 OPENAI_API_KEY，则使用本地脚本。
3. Gemini 回退 —— 如果 OpenAI API 生成不可用或失败，则使用同一脚本搭配 GEMINI_API_KEY 和现有的 Gemini 图像模型。

仅在需要时加载特定提供方的参考资料：

• Codex 内置路径：references/codex-built-in.md
• OpenAI API 回退：references/openai-api.md
• Gemini 回退：references/gemini-api.md

使用场景

• 用户要求生成插图、图表、概念图、文章配图或文档配图
• 用户正在撰写文章，需要通过视觉方式解释概念或工作流
• 用户明确要求生成栅格图像

第 1 步：确定图像需求

生成前，只需确认必要的信息：

1. 插画内容 —— 概念、架构、流程或场景
2. 语言 —— 提示词和图像中的文本默认使用英语。只有用户明确要求时才使用其他语言
3. 保存位置 —— 参见下文的“输出路径”
4. 风格／颜色偏好 —— 如果用户有具体需求，则按其要求处理；否则使用默认风格

第 2 步：选择提供方路径

路径 A：Codex 内置

在以下情况下使用此路径：

• 当前 Agent 为 Codex
• 可使用内置的 image_gen 工具
• 用户未明确要求通过 API／CLI 执行

阅读 references/codex-built-in.md，使用内置工具生成图像，然后在图像属于项目时，将最终图像移动或复制到工作区。

路径 B：脚本自动回退

在以下情况下使用此路径：

• 当前 Agent 不是 Codex
• 内置工具不可用
• 用户明确要求通过 API／CLI 执行

运行：

python <skill-root>/scripts/generate_image.py \
  --prompt "your prompt here" \
  --output "/path/to/save/image.png"

脚本默认使用 --provider auto：

1. 如果设置了 OPENAI_API_KEY，则尝试使用 OpenAI API
2. 如果 OpenAI API 失败或未配置，且设置了 GEMINI_API_KEY，则尝试使用 Gemini
3. 如果两项凭据都不可用，则报告缺失的环境变量

第 3 步：编写提示词

默认风格前缀

除非使用 --style-prefix 或 --no-style，脚本会自动添加以下风格前缀：

使用简洁、现代的配色方案和柔和的色调。采用极简扁平插画风格，具有清晰的视觉层次。整体专业、精致，适合技术博客文章。避免写实渲染。避免过多渐变或阴影。

对于 Codex 内置路径，除非用户要求其他风格，否则请在提示词中直接加入相同的风格指导。

提示词编写指南

• 明确描述视觉元素、它们之间的关系和布局
• 对于技术概念：描述各个组件及其连接方式
• 对于架构图：列出各层／组件，并说明数据流方向
• 对于流程图：描述各个步骤和流程方向
• 如果图像中需要文字标签，请明确写出标签内容，并保持简短
• 默认使用英语；只有在用户要求时才使用其他语言

示例提示词

架构图：

A system architecture diagram showing: User sends query to an API Gateway,
which routes to a Vector Database labeled "Milvus" and a generation service.
The Vector Database returns relevant documents, which are combined with the
original query and sent to the generation service for final response generation.
Arrows show data flow direction. Each component is a rounded rectangle with
an icon and label.

概念插画：

A visual comparison of keyword search vs semantic search. Left side shows
keyword search with exact word matching and highlighted matching words.
Right side shows semantic search with a brain icon understanding meaning
and connecting related concepts with dotted lines. A dividing line separates
the two approaches.

第 4 步：参数

默认参数

参数	默认值	备注
提供方	脚本中为 auto；可用时优先使用 Codex 内置功能	依次优先使用 Codex 内置功能、OpenAI API，然后是 Gemini
OpenAI 模型	gpt-image-2	用作脚本回退方案
Gemini 模型	gemini-3.1-flash-image	用作脚本回退方案
宽高比	16:9	横向，适合文章插图
图片尺寸	1K	在质量和成本之间取得良好平衡
风格	简约、干净、柔和色调	由脚本自动添加前缀
语言	英语	提示词和图片内文字

脚本选项

--provider          auto, openai, gemini
--model             Provider model ID for the selected provider
--openai-model      OpenAI model ID, default gpt-image-2
--gemini-model      Gemini model ID, default gemini-3.1-flash-image
--aspect-ratio      1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 9:16, 16:9, 21:9, etc.
--image-size        512, 1K, 2K, 4K
--openai-quality    low, medium, high, auto
--style-prefix      Custom style prefix
--no-style          Skip default style prefix

何时更改默认值

场景	更改方式
提高最终素材的质量	--image-size 2K 或 --openai-quality high
人像／竖版图片	--aspect-ratio 3:4 或 --aspect-ratio 9:16
方形图片	--aspect-ratio 1:1
用户有自己的风格	--style-prefix "your style" 或 --no-style
非英语内容	使用目标语言编写提示词

步骤 5：确定输出路径

按以下优先顺序操作：

优先级 1：当前对话中的上下文

如果用户正在处理某个特定的 Markdown 文件或文章：

1. 查找 .md 文件中的图片引用，确认文章中现有图片的存放位置
2. 将新图片保存在与现有图片相同的目录中
3. 使用能体现图片内容且符合现有命名惯例的文件名

示例：如果文章中有 ![](images/architecture-overview.png)，请将图片保存到同一个 images/ 目录中。

优先级 2：项目图片目录

如果没有特定的文章上下文，但正在处理某个项目：

1. 查找现有图片目录：images/、assets/、static/、img/、figures/
2. 将图片保存在最合适的现有目录中
3. 如果不存在这样的目录，请在项目根目录或相关内容目录下创建 images/ 目录

优先级 3：回退方案

如果没有明确的项目上下文：

1. 保存到当前工作目录
2. 使用描述性文件名：concept-name-illustration.png

步骤 6：验证结果

生成图片后：

1. 读取图片文件，目视确认图片符合用户的要求
2. 如果结果不理想，请改进提示词，并针对性调整后重新生成一次
3. 如果要将图片插入 Markdown 文件，请建议使用以下 Markdown 语法：![alt text](relative/path/to/image.png)
4. 报告所用的提供方路径，以及最终文件的保存位置