--- name: "imagegen" description: "当任务需要 AI 创建的位图视觉效果（如照片、插图、纹理、精灵、模型或透明背景剪切）时，生成或编辑光栅图像。当 Codex 应该创建全新图像、转换现有图像或从参考中衍生视觉变体，且输出应该是位图资产而不是仓库原生代码或矢量时使用。当任务通过编辑现有 SVG/矢量/代码原生资产、扩展已建立的图标或徽标系统，或直接在 HTML/CSS/canvas 中构建视觉效果更好时，不要使用。" --- # 图像生成技能 为当前项目生成或编辑图像（例如网站资产、游戏资产、UI 模型、产品模型、线框、徽标设计、照片级真实感图像或信息图）。 ## 顶层模式和规则 此技能有两种顶层模式： - **默认内置工具模式（首选）**：用于正常图像生成和编辑的内置 `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/*` 下。 - 不要将 OS 临时目录描述或依赖为默认内置目标。 - 不要描述或依赖内置 `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/矢量图标集、徽标系统或插图库 - 创建简单的形状、图表、线框或图标，这些更适合直接在 SVG、HTML/CSS 或 canvas 中生成 - 当源文件已经以可编辑的原生格式存在时，对项目本地资产进行小的编辑 - 任何用户明显想要确定性代码原生输出而不是生成的位图的任务 ## 决策树 考虑两个独立的问题： 1. **意图**：这是新图像还是现有图像的编辑？ 2. **执行策略**：这是一个资产还是多个资产/变体？ 意图： - 如果用户想要修改现有图像同时保留其部分内容，将请求视为 **编辑**。 - 如果用户提供图像仅作为风格、构图、氛围或主题指导的参考，将请求视为 **生成**。 - 如果用户未提供图像，将请求视为 **生成**。 内置编辑语义： - 内置编辑模式适用于已在对话上下文中可见的图像，例如附加图像或线程早期生成的图像。 - 如果用户想要使用内置工具编辑本地图像文件，首先使用内置 `view_image` 工具加载它，使图像在对话上下文中可见，然后继续内置编辑流程。 - 不要承诺通过内置工具进行任意文件系统路径编辑。 - 如果本地文件仍需要直接文件路径控制、遮罩或其他仅 CLI 可用的参数，仅当用户要求时才使用显式 CLI 备用模式。 - 对于编辑，默认积极保留不变量并以非破坏性方式保存。 执行策略： - 在默认内置路径中，通过为每个请求的资产或变体发出一个 `image_gen` 调用来生成多个资产或变体。 - 在显式 CLI 备用路径中，仅当用户明确选择 CLI 模式并需要多个提示/资产时，才使用 CLI `generate-batch` 子命令。 除非用户明确要求更改现有图像，否则假设用户想要新图像。 ## 工作流程 1. 决定顶层模式：默认使用内置模式，仅当明确请求时才使用备用 CLI。 2. 决定意图：`生成` 或 `编辑`。 3. 决定输出是仅预览还是用于当前项目。 4. 决定执行策略：单个资产 vs 重复内置调用 vs 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 — 具有真实纹理和自然光线的 candid/编辑生活方式场景。 - product-mockup — 产品/包装照片、目录图像、商品概念。 - ui-mockup — 应用/网络界面模型和线框；指定所需的保真度。 - infographic-diagram — 具有结构化布局和文本的图表/信息图。 - logo-brand — 徽标/标记探索、矢量友好。 - illustration-story — 漫画、儿童书籍艺术、叙事场景。 - stylized-concept — 风格驱动的概念艺术、3D/风格化渲染。 - historical-scene — 时期准确/世界知识场景。 编辑： - text-localization — 翻译/替换图像内文本，保留布局。 - identity-preserve — 试穿、场景中的人；锁定面部/身体/姿势。 - precise-object-edit — 去除/替换特定元素（包括内部交换）。 - lighting-weather — 仅一天中的时间/季节/氛围变化。 - background-extraction — 透明背景 / 干净的剪切。 - style-transfer — 在更改主题/场景的同时应用参考风格。 - compositing — 多图像插入/合并，匹配照明/透视。 - sketch-to-render — 绘图/线条艺术到照片级真实感渲染。 ## 共享提示架构 使用以下标记规范作为两种顶层模式的共享提示脚手架： ```text 用例：<分类法 slug> 资产类型：<资产将在哪里使用> 主要请求：<用户的主要提示> 输入图像：<图像 1：角色；图像 2：角色>（可选） 场景/背景：<环境> 主题：<主要主题> 风格/媒介：<照片/插图/3D 等> 构图/取景：<宽/近/俯视；放置> 照明/情绪：<照明 + 情绪> 调色板：<调色板注释> 材料/纹理：<表面细节> 文本（逐字）："<精确文本>" 约束：<必须保留/必须避免> 避免：<负面约束> ``` 注意： - `资产类型` 和 `输入图像` 是提示脚手架，不是专用的 CLI 标志。 - `场景/背景` 指的是视觉设置。它与备用 CLI `background` 参数不同，后者控制输出透明度行为。 - 仅备用执行说明，如 `质量：`、`输入保真度：`、遮罩、输出格式和输出路径，仅属于显式 CLI 路径。不要将它们视为内置 `image_gen` 工具参数。 增强规则： - 保持简短。 - 仅添加需要实质性改善提示的细节。 - 对于编辑，明确列出不变量（"仅更改 X；保持 Y 不变"）。 - 如果任何关键细节缺失并阻止成功，请提问；否则继续。 ## 示例 ### 生成示例（主图像） ```text 用例：product-mockup 资产类型：着陆页主图像 主要请求：陶瓷咖啡杯的最小主图像 风格/媒介：干净的产品摄影 构图/取景：宽构图，必要时为页面副本留出可用的负空间 照明/情绪：柔和的工作室照明 约束：无徽标、无文本、无水印 ``` ### 编辑示例（不变量） ```text 用例：precise-object-edit 资产类型：产品照片背景替换 主要请求：仅用温暖的日落渐变替换背景 约束：仅更改背景；保持产品和其边缘不变；无文本；无水印 ``` ## 提示最佳实践 - 将提示构建为场景/背景 → 主题 → 细节 → 约束。 - 包括预期用途（广告、UI 模型、信息图）以设置模式和润色级别。 - 对于照片级真实感，使用相机/构图语言。 - 仅当用户明确要求矢量输出或非图像占位符时才使用 SVG/矢量替代。 - 引用精确文本并指定排版 + 放置。 - 对于棘手的单词，逐字母拼写并要求逐字渲染。 - 对于多图像输入，按索引引用图像并描述如何使用它们。 - 对于编辑，每次迭代都重复不变量以减少漂移。 - 使用单一更改后续进行迭代。 - 如果提示是通用的，仅添加会实质性帮助的额外细节。 - 如果提示已经详细，对其进行标准化而不是扩展它。 - 仅对于显式 CLI 备用模式，请参阅 `references/cli.md` 和 `references/image-api.md` 以获取 `quality`、`input_fidelity`、遮罩、输出格式和输出路径指导。 两种模式共享的更多原则：`references/prompting.md`。 两种模式共享的复制/粘贴规范：`references/sample-prompts.md`。 ## 按资产类型的指导 资产类型模板（网站资产、游戏资产、线框、徽标）在 `references/sample-prompts.md` 中合并。 ## 仅备用 CLI 模式 ### 临时和输出约定 这些约定仅适用于显式 CLI 备用模式。它们不描述内置 `image_gen` 输出行为。 - 使用 `tmp/imagegen/` 作为中间文件（例如 JSONL 批量）；完成后删除它们。 - 将最终工件写入 `output/imagegen/`。 - 使用 `--out` 或 `--out-dir` 控制输出路径；保持文件名稳定和描述性。 ### 依赖项 在此仓库中，首选 `uv` 进行依赖管理。 必需的 Python 包： ```bash uv pip install openai ``` 仅用于缩小的可选包： ```bash uv pip install pillow ``` 可移植性说明： - 如果您在此仓库外部使用已安装的技能，请使用其包管理器将依赖项安装到该环境中。 - 在 uv 管理的环境中，`uv pip install ...` 仍然是首选路径。 ### 环境 - 进行实时 API 调用时必须设置 `OPENAI_API_KEY`。 - 使用内置 `image_gen` 工具时，不要向用户询问 `OPENAI_API_KEY`。 - 永远不要要求用户在聊天中粘贴完整的密钥。要求他们在本地设置并准备好时确认。 如果缺少密钥，请为用户提供这些步骤： 1. 在 OpenAI 平台 UI 中创建 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 模式，否则不要加载或使用它。