imagegen

图像生成技能

为当前项目生成或编辑图像（例如网站素材、游戏素材、UI 模型图、产品模型图、线框图、Logo 设计、照片级真实图像或信息图）。

顶层模式和规则

此技能恰好有两种顶层模式：

• 默认内置工具模式（首选）： 使用内置 image_gen 工具进行常规图像生成和编辑。无需 OPENAI_API_KEY。
• 备用 CLI 模式（仅限明确要求时）： 使用 scripts/image_gen.py CLI。仅在用户明确要求使用 CLI 方式时使用。需要 OPENAI_API_KEY。

仅在明确要求使用备用 CLI 时，CLI 才提供以下三个子命令：

• generate
• edit
• generate-batch

规则：

• 对所有常规图像生成和编辑请求，默认使用内置 image_gen 工具。
• 切勿自动切换到备用 CLI。
• 如果内置工具失败或不可用，告知用户存在备用 CLI，且需要 OPENAI_API_KEY。只有用户明确要求使用该备用方案后才能继续。
• 如果用户明确要求使用 CLI 模式，请使用随附的 scripts/image_gen.py 工作流。不要创建临时 SDK 执行脚本。
• 切勿修改 scripts/image_gen.py。如果缺少任何内容，请先询问用户，再进行其他操作。

内置模式的保存路径规则：

• 在内置工具模式下，Codex 默认将生成的图像保存到 $CODEX_HOME/*。
• 不要将操作系统临时目录描述为或依赖为内置工具的默认保存位置。
• 不要描述或依赖内置 image_gen 工具上的目标路径参数（如有）。如果需要保存到特定位置，请先生成图像，然后从 $CODEX_HOME/generated_images/... 移动或复制选定的输出。
• 内置模式下的保存路径优先级：
  1. 如果用户指定了目标位置，将选定的输出移动或复制到该位置。
  2. 如果图像用于当前项目，在完成前将最终选定的图像移动或复制到工作区。
  3. 如果图像仅用于预览或构思，直接内嵌渲染；底层文件可以保留在默认的 $CODEX_HOME/* 路径。
• 切勿让项目引用的素材只保留在默认的 $CODEX_HOME/* 路径下。
• 除非用户明确要求替换，否则不要覆盖现有素材；应创建带版本号的同级文件，例如 hero-v2.png 或 item-icon-edited.png。

两种模式共用的提示词指南位于 references/prompting.md 和 references/sample-prompts.md。

仅适用于备用 CLI 模式的文档和资源：

• references/cli.md
• references/image-api.md
• references/codex-network.md
• scripts/image_gen.py

适用场景

• 生成新图像（概念艺术、产品图、封面、网站主视觉）
• 使用一个或多个参考图像生成新图像，以参考其风格、构图或氛围
• 编辑现有图像（图像修复、光照或天气转换、背景替换、物体移除、合成、透明背景）
• 为一项任务制作大量素材或变体

不适用场景

• 扩展或匹配代码库中现有的 SVG/矢量图标集、Logo 系统或插画库
• 创建更适合直接使用 SVG、HTML/CSS 或 canvas 制作的简单形状、示意图、线框图或图标
• 源文件已有可编辑的原生格式，而只需对项目内素材进行小幅修改
• 用户明确需要确定性的原生代码输出，而非生成的位图

决策树

考虑两个不同的问题：

1. **意图：**这是要生成新图像，还是编辑现有图像？
2. **执行策略：**这是一个素材，还是多个素材／变体？

意图：

• 如果用户希望修改现有图像，同时保留其中的部分内容，则将请求视为编辑。
• 如果用户提供图像仅作为风格、构图、氛围或主题参考，则将请求视为生成。
• 如果用户未提供图像，则将请求视为生成。

内置编辑语义：

• 内置编辑模式适用于在对话上下文中已可见的图像，例如附加的图像或在当前对话线程中先前生成的图像。
• 如果用户希望使用内置工具编辑本地图像文件，请先使用内置的 view_image 工具加载该图像，使其在对话上下文中可见，然后再使用内置编辑流程。
• 不要承诺可以通过内置工具编辑任意文件系统路径中的图像。
• 如果仍需直接控制本地文件路径、蒙版或其他仅限 CLI 的参数，则仅在用户提出要求时使用显式 CLI 备用方案。
• 对于编辑，应尽可能严格地保留不变量，并默认以非破坏性方式保存。

执行策略：

• 在内置默认流程中，如需生成多个素材或变体，则每个请求的素材或变体都单独调用一次 image_gen。
• 在显式 CLI 备用流程中，仅当用户明确选择 CLI 模式且需要多个提示词／素材时，才使用 CLI 的 generate-batch 子命令。

除非用户明确要求修改现有图像，否则假设用户想要生成新图像。

工作流

1. 确定顶层模式：默认使用内置模式，只有在明确要求时才回退到 CLI。
2. 确定意图：generate 或 edit。
3. 确定输出仅用于预览，还是要供当前项目使用。
4. 确定执行策略：单个素材、重复调用内置工具，或使用 CLI generate-batch。
5. 提前收集输入：提示词、精确文本（逐字照用）、约束/避免事项列表，以及所有输入图像。
6. 明确标注每张输入图像的用途：
   • 参考图像
   • 编辑目标
   • 辅助插入/风格/合成输入
7. 如果编辑目标仅存在于本地文件系统，且你要使用内置模式，请先用 view_image 检查它，确保图像已出现在对话上下文中。
8. 如果用户要求照片、插画、精灵图、产品图像、横幅或其他明确的栅格风格素材，请使用 image_gen，而不是用 SVG/HTML/CSS 占位内容替代。如果用户需要的图标、徽标或 UI 图形应与仓库原生 SVG/矢量/代码素材保持一致，则优先直接编辑这些素材。
9. 根据具体程度扩充提示词：
   • 如果用户的提示词已经具体详尽，请将其规范为清晰的规格，不要添加创意要求。
   • 如果用户的提示词较为笼统，仅在能显著提升输出质量时才适度补充。
10. 默认使用内置 image_gen 工具。
11. 只有在用户明确选择 CLI 回退方案时，才使用仅适用于回退方案的文档，了解质量、input_fidelity、遮罩、输出格式、输出路径和网络设置。
12. 检查输出并进行验证：主体、风格、构图、文本准确性，以及不变量/避免事项。
13. 针对单个问题进行迭代调整，然后重新检查。
14. 对于仅用于预览的工作，在行内渲染图像；底层文件可保留在默认的 $CODEX_HOME/generated_images/... 路径。
15. 对于项目用途的工作，将选定素材移入或复制到工作区，并更新任何使用该素材的代码或引用。项目引用的素材绝不能只留在默认的 $CODEX_HOME/generated_images/... 路径。
16. 对于批量任务，除非用户明确要求保留弃用的变体，否则只将选定的最终版本保存在工作区。
17. 对于任何面向工作区的素材，始终报告最终保存路径、最终提示词，以及使用的是内置工具还是回退 CLI 模式。

提示词扩充

将用户提示词重新整理为结构化、面向生产的规格。让用户的目标更加清晰、可执行，但不要盲目添加细节。

将其视为提示词塑造指南，而非固定格式。只使用有帮助的条目；如果能显著提高清晰度，可添加一条简短的额外标注。

具体程度策略

根据用户提示词的具体程度决定扩充幅度：

• 如果提示词已经具体详尽，请保留其细节，只进行规范化和结构化。
• 如果提示词较为笼统，可在有助于显著改善结果时适度补充。

允许的扩充内容：

• 构图或取景提示
• 精修程度或用途提示
• 实用的布局指导
• 有助于实现用户所述请求的合理场景细节

不允许的扩充内容：

• 添加请求中未暗示的角色或物体
• 添加请求中未暗示的品牌名称、标语、调色板或叙事节点
• 添加周边布局不支持的任意单侧位置安排

用例分类（精确 slug）

将每个请求归入以下类别之一，并确保在提示词和引用中使用一致的 slug。

生成：

• photorealistic-natural — 具有真实质感和自然光线的随拍／编辑风格生活场景。
• product-mockup — 产品／包装照片、目录图片、周边商品概念。
• ui-mockup — 应用／网页界面模型和线框图；注明所需的保真度。
• infographic-diagram — 具有结构化布局和文字的图表／信息图。
• logo-brand — Logo／标志探索，适合矢量图。
• illustration-story — 漫画、儿童绘本艺术、叙事场景。
• stylized-concept — 风格驱动的概念艺术、3D／风格化渲染。
• historical-scene — 符合时代特征／世界知识的场景。

编辑：

• text-localization — 翻译／替换图像中的文字，同时保留布局。
• identity-preserve — 试穿、人物置于场景中；锁定面部／身体／姿势。
• precise-object-edit — 移除／替换特定元素（包括室内场景替换）。
• lighting-weather — 仅更改一天中的时段／季节／氛围。
• background-extraction — 透明背景／干净抠图。
• style-transfer — 在更改主体／场景的同时应用参考风格。
• compositing — 插入／合并多张图像，并匹配光线／透视。
• sketch-to-render — 将绘图／线稿转换为照片级真实渲染。

通用提示词架构

将以下带标签的规范用作两种顶层模式的通用提示词框架：

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <user's main prompt>
Input images: <Image 1: role; Image 2: role> (optional)
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <lighting + mood>
Color palette: <palette notes>
Materials/textures: <surface details>
Text (verbatim): "<exact text>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

注意：

• Asset type 和 Input images 是提示词框架，不是专用 CLI 标志。
• Scene/backdrop 指视觉场景。它不同于备用 CLI 的 background 参数，后者用于控制输出透明度行为。
• 仅备用模式的执行说明，如 Quality:、Input fidelity:、蒙版、输出格式和输出路径，仅适用于明确指定的 CLI 路径。不要将其视为内置 image_gen 工具参数。

扩充规则：

• 保持简短。
• 只添加对实质性改善提示词有帮助的细节。
• 对于编辑，明确列出不变项（仅更改 X；保持 Y 不变）。
• 如果缺少任何会阻碍成功的关键细节，请提问；否则直接继续。

示例

生成示例（主视觉图片）

Use case: product-mockup
Asset type: landing page hero
Primary request: a minimal hero image of a ceramic coffee mug
Style/medium: clean product photography
Composition/framing: wide composition with usable negative space for page copy if needed
Lighting/mood: soft studio lighting
Constraints: no logos, no text, no watermark

编辑示例（不变项）

Use case: precise-object-edit
Asset type: product photo background replacement
Primary request: replace only the background with a warm sunset gradient
Constraints: change only the background; keep the product and its edges unchanged; no text; no watermark

提示词最佳实践

• 按照场景／背景 -> 主体 -> 细节 -> 约束来组织提示词。
• 注明预期用途（广告、UI 模型、信息图），以确定模式和润色程度。
• 使用相机／构图术语来实现照片级真实感。
• 仅在用户明确要求矢量输出或非图像占位内容时，才使用 SVG／矢量替代图。
• 将准确文本用引号括起，并指定字体排印和位置。
• 对于难处理的词，逐字母拼写，并要求原样呈现。
• 对于多张输入图像，按索引引用图像，并说明应如何使用。
• 对于编辑，每次迭代都重复不变项，以减少偏差。
• 通过单次只更改一项的后续提示进行迭代。
• 如果提示词较笼统，只补充能带来实质帮助的细节。
• 如果提示词已经很详细，请对其进行规范化，而不是扩展。
• 仅对于明确指定的 CLI 备用模式，quality、input_fidelity、蒙版、输出格式和输出路径指南请参阅 references/cli.md 和 references/image-api.md。

两种模式通用的其他原则：references/prompting.md。 两种模式通用的可复制／粘贴规范：references/sample-prompts.md。

按素材类型提供的指南

素材类型模板（网站素材、游戏素材、线框图、Logo）已整合到 references/sample-prompts.md 中。

仅限备用 CLI 模式

临时文件和输出约定

这些约定仅适用于明确指定的 CLI 备用模式。它们不描述内置 image_gen 的输出行为。

• 中间文件（例如 JSONL 批次）使用 tmp/imagegen/；完成后将其删除。
• 将最终成品写入 output/imagegen/。
• 使用 --out 或 --out-dir 控制输出路径；文件名应保持稳定且具有描述性。

依赖项

本仓库优先使用 uv 管理依赖项。

必需的 Python 软件包：

uv pip install openai

仅用于缩小尺寸的可选依赖项：

uv pip install pillow

可移植性说明：

• 如果你在本仓库之外使用已安装的技能，请使用该环境的包管理器安装依赖项。
• 在由 uv 管理的环境中，uv pip install ... 仍是首选方式。

环境

• 进行实时 API 调用时，必须设置 OPENAI_API_KEY。
• 使用内置的 image_gen 工具时，不要向用户索要 OPENAI_API_KEY。
• 绝不要要求用户在聊天中粘贴完整密钥。请让他们在本地设置密钥，并在准备就绪后确认。

如果缺少密钥，请向用户提供以下步骤：

1. 在 OpenAI 平台界面创建 API 密钥：https://platform.openai.com/api-keys
2. 在其系统中将 OPENAI_API_KEY 设置为环境变量。
3. 如果需要，请提出为其操作系统或 shell 指导设置环境变量。

如果无法在此环境中安装，请告知用户缺少哪个依赖项，以及如何将其安装到当前环境中。

脚本模式说明

• CLI 命令与示例：references/cli.md
• API 参数快速参考：references/image-api.md
• CLI 模式的网络审批／沙盒设置：references/codex-network.md

参考资料索引

• references/prompting.md：适用于两种模式的通用提示词原则。
• references/sample-prompts.md：适用于两种模式的可复制粘贴提示词示例。
• references/cli.md：仅作备用，通过 scripts/image_gen.py 使用 CLI。
• references/image-api.md：仅作备用，API／CLI 参数参考。
• references/codex-network.md：仅作备用，CLI 模式的网络／沙盒故障排查。
• scripts/image_gen.py：仅作备用的 CLI 实现。除非用户明确选择 CLI 模式，否则不要加载或使用它。