grahama1970/imagegen

图像生成技能

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

顶级模式与规则

本技能精确包含两种顶级模式：

• 默认的内置工具模式（推荐）： 内置的 image_gen 工具，用于常规图像生成、编辑和简单的透明图像请求。无需 OPENAI_API_KEY。
• 回退的CLI模式： scripts/image_gen.py CLI。当用户明确要求使用CLI/API/模型路径时，或用户明确确认使用 gpt-image-1.5 的真实模型原生透明度回退后使用。需要 OPENAI_API_KEY。

在CLI回退模式下，CLI提供三个子命令：

• generate
• edit
• generate-batch

规则：

• 对于常规图像生成和编辑请求，默认使用内置的 image_gen 工具。
• 不要仅为了质量、大小或文件路径控制而切换到CLI回退模式。
• 如果用户明确要求透明图像/背景，首先坚持使用内置的 image_gen：提示使用平坦的可移除色度键背景，然后使用 $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py 本地移除。
• 切勿从内置 image_gen 或CLI gpt-image-2 静默切换到CLI gpt-image-1.5。将此视为模型/路径降级，并在执行前询问用户，除非用户已明确要求 gpt-image-1.5、scripts/image_gen.py 或CLI回退模式。
• 如果透明请求对于干净的色度键移除过于复杂、要求真实/原生透明度，或本地移除验证失败，则说明真实透明度需要CLI gpt-image-1.5 --background transparent --output-format png，因为 gpt-image-2 不支持 background=transparent，然后询问用户是否继续。仅在用户确认后运行CLI回退模式。
• 单独的 batch 一词并不意味着CLI回退。如果用户要求许多素材或批量生成素材，而没有明确要求CLI/API/模型控制，则坚持使用内置路径，并为每个请求的素材或变体发出一次内置调用。
• 如果内置工具失败或不可用，告知用户存在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

本地后处理辅助工具：

• $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py：从生成的图像中移除平坦的色度键背景，并写入带alpha通道的PNG/WebP。对于抗锯齿边缘，优先使用自动键采样、柔光和去溢色。

何时使用

• 生成新图像（概念艺术、产品照片、封面、网站主图）
• 使用一个或多个参考图像来生成新图像（用于风格、构图或氛围）
• 编辑现有图像（内绘画、光照或天气变换、背景替换、对象移除、合成、透明背景）
• 为一个任务生成多个素材或变体

何时不使用

• 扩展或匹配仓库中现有的SVG/矢量图标集、Logo系统或插画库
• 创建更适合直接在SVG、HTML/CSS或Canvas中生成的简单形状、图表、线框图或图标
• 当源文件已以可编辑的原生格式存在时，对项目本地素材进行小型编辑
• 任何用户明确希望输出确定性代码原生内容而非生成位图的任务

决策树

考虑两个独立的问题：

1. 意图： 这是新图像还是对现有图像的编辑？
2. 执行策略： 是一个素材还是多个素材/变体？

意图：

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

内置编辑语义：

• 内置编辑模式适用于对话上下文中已可见的图像，例如已附加的图像或线程中之前生成的图像。
• 如果用户想使用内置工具编辑本地图像文件，首先使用内置的 view_image 工具加载它，使图像在对话上下文中可见，然后继续执行内置编辑流程。
• 不要承诺通过内置工具进行任意文件系统路径编辑。
• 如果本地文件仍需直接的文件路径控制、遮罩或其他明确仅CLI可用的参数，则仅在用户要求时使用明确的CLI回退模式。
• 对于编辑，积极保持不变性，并默认以非破坏性方式保存。

执行策略：

• 在默认的内置路径中，通过为每个请求的素材或变体发出一次 image_gen 调用来生成多个素材或变体。
• 在CLI回退路径中，仅当用户明确选择了CLI模式且需要许多提示/素材时，才使用CLI的 generate-batch 子命令。
• 对于许多不同的素材，不要使用 n 作为单独提示的替代品。n 用于一个提示的变体；不同的素材需要不同的内置调用或不同的CLI generate-batch 作业。

假设用户想要一张新图像，除非他们明确要求更改现有图像。

工作流程

1. 决定顶级模式：默认为内置模式，包括简单的透明输出请求；仅当明确要求或用户明确确认透明输出回退时，才使用回退CLI模式。
2. 决定意图：generate 或 edit。
3. 决定输出是仅预览还是要被当前项目使用。
4. 决定执行策略：单个素材 vs 重复内置调用 vs CLI generate-batch。
5. 预先收集输入：提示、精确文本（逐字）、约束/避免列表以及任何输入图像。
6. 对于每个输入图像，明确标记其角色：
   • 参考图像
   • 编辑目标
   • 辅助插入/风格/合成输入
7. 如果编辑目标仅在本地文件系统上，且您坚持使用内置路径，请先使用 view_image 检查它，使图像在对话上下文中可用。
8. 如果用户要求的是照片、插画、精灵图、产品图像、横幅或其他明确的光栅风格素材，使用 image_gen，而不是用SVG/HTML/CSS占位符替代。如果请求是针对图标、Logo或UI图形，并且应与仓库中现有的原生SVG/矢量/代码素材匹配，则优先直接编辑这些素材。
9. 根据具体性增强提示：
   • 如果用户的提示已经很具体且详细，将其规范化为清晰的规格，无需添加创意要求。
   • 如果用户的提示比较通用，仅在能显著提高输出质量时，添加有品味的增强内容。
10. 默认使用内置的 image_gen 工具。
11. 对于透明输出请求，遵循下面的透明图像指导：使用内置 image_gen 在平坦的色度键背景上生成，将选定的输出复制到工作区或 tmp/imagegen/，运行已安装的 $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py 辅助工具，并在使用前验证alpha结果。如果此路径看起来不合适或失败，请在使用CLI gpt-image-1.5 之前询问用户。
12. 检查输出并验证：主体、风格、构图、文本准确性以及不变性/避免项。
13. 通过一次有针对性的更改进行迭代，然后重新检查。
14. 对于仅预览的工作，内联渲染图像；底层文件可以保留在默认的 $CODEX_HOME/generated_images/... 路径下。
15. 对于项目相关的工作，将选定的产物移动或复制到工作区中，并更新任何使用的代码或引用。切勿将项目引用的素材仅保留在默认的 $CODEX_HOME/generated_images/... 路径下。
16. 对于批量或多素材请求，除非用户明确要求仅预览输出，否则将请求的每个可交付物最终版本持久化保存在工作区中。除非要求，否则丢弃的变体无需保留。
17. 如果用户明确选择或确认CLI回退模式，则使用仅回退模式的文档来处理模型、质量、大小、input_fidelity、遮罩、输出格式、输出路径和网络设置。
18. 始终报告任何绑定到工作区的素材的最终保存路径，以及最终提示或提示集，以及使用了内置工具还是回退CLI模式。

透明图像请求

透明图像请求仍然首先使用内置 image_gen。由于内置工具不提供真正的透明背景控制，请创建可移除的色度键源图像，然后将键颜色本地转换为alpha通道。

默认顺序：

1. 使用内置 image_gen 在完全平坦的纯色色度键背景上生成请求的主体。
2. 选择一个不太可能出现在主体中的键颜色：默认 #00ff00，对绿色主体使用 #ff00ff，对蓝色主体避免使用 #0000ff。
3. 生成后，将选定的源图像从 $CODEX_HOME/generated_images/... 移动或复制到工作区或 tmp/imagegen/。
4. 运行已安装的辅助工具路径，而不是项目相对脚本路径：

   python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
     --input <source> \
     --out <final.png> \
     --auto-key border \
     --soft-matte \
     --transparent-threshold 12 \
     --opaque-threshold 220 \
     --despill
   

5. 验证输出具有alpha通道、透明角、合理的主体覆盖和没有明显的键颜色边缘。如果仍有薄边缘残留，使用 --edge-contract 1 重试一次；仅当边缘明显呈阶梯状且主体不反光或反光时，才使用 --edge-feather 0.25。
6. 如果素材是项目绑定的，则将最终的alpha PNG/WebP保存到项目中。切勿将项目引用的透明素材仅保存在 $CODEX_HOME/* 下。

像这样提示透明请求：

在完全平坦的纯色 #00ff00 色度键背景上创建请求的主体，以便进行背景移除。
背景必须是一种均匀的颜色，无阴影、渐变、纹理、反射、地平面或光照变化。
保持主体与背景完全分离，边缘清晰，填充充足。
不要在主体中使用 #00ff00。
无投射阴影、无接触阴影、无反射、无水印、无文字，除非明确要求。

不要自动使用CLI gpt-image-1.5 --background transparent --output-format png 代替色度键处理。当用户要求真实/原生透明度、本地移除验证失败、或请求的图像复杂时（如头发、毛皮、羽毛、烟雾、玻璃、液体、半透明材料、反射物体、软阴影、真实产品接地，或主体颜色与所有实际键颜色冲突），请先询问用户。

使用简洁的确认信息：

这很可能需要真正的原生透明度。默认的内置路径使用色度键背景加本地移除，但真正的透明度需要CLI回退模式，使用 gpt-image-1.5，因为 gpt-image-2 不支持 background=transparent。它还需要 OPENAI_API_KEY。我是否应该使用该CLI回退模式？

提示增强

将用户提示重新格式化为结构化、面向生产的规格。使用户的目标更清晰、更可操作，但不要盲目添加细节。

将此视为提示塑形指导，而非封闭的架构。仅使用有帮助的几行，并在能显著提高清晰度时添加简短的额外标签行。

具体性策略

根据用户提示的具体性来决定增加多少增强内容：

• 如果提示已经很具体且详细，保留该具体性并仅规范化/结构化。
• 如果提示是通用的，仅当能显著改善结果时，可以添加有品味的增强内容。

允许的增强：

• 构图或取景提示
• 润色水平或预期用途提示
• 实用的布局指导
• 支持所述请求的合理场景具体性

不允许的增强：

• 请求中未暗示的额外角色或物体
• 不隐含的品牌名称、标语、调色板或叙事节奏
• 除非周边布局支持，否则任意指定侧面放置位置

用例

……[为翻译而截断]