oil-icon

oil-icon

生成一组采用统一视觉风格的图标，并以透明 PNG 格式输出。

图像生成会以纯灰色背景生成一张 4×4 图，每次生成 16 个图标，有助于统一风格，但仍需逐个检查，然后将每个单元格切出并移除背景。

设计决策由 Agent 负责（采用哪种风格、配色和隐喻，是否匹配品牌）；图像生成和切图是机械步骤。

API Key 配置入口

需要外部服务凭据时，先阅读API Key 配置与业务读取：复用已有安全入口；本机缺少 Key 时，使用随附的固定页面，保存后通过业务包装入口读取。内置能力与纯本地流程不要求配置 Key。

工作流

1. 选择风格。 可以从 styles/ 中选择内置风格（见下表），也可以匹配用户的品牌：读取其项目的设计令牌和素材，推导出自定义风格规范——参见 reference/style-adaptation.md。将结果固定为一份与内置 JSON 具有相同字段的风格规范；后续批次复用同一规范，并检查生成偏差。
2. 列出图标。 将每个概念写成 名称 — 简短、具体的隐喻（例如 settlement — a wallet with a coin）。每个图标只表达一个清晰的想法；整组图标的细节程度要保持一致。默认每张 16 格；明确选择 9 格时，提示词使用 3×3，切图命令必须同时传 --grid 3。如果用户要求的准确数量少于 16，仍使用 4x4 / 16-cell sheet：将所需图标按行优先顺序放在前面，并明确要求其余格子保持空白灰色背景。
3. 编写提示词。 使用 style.preamble、风格的 construction 字段（作为简短指导）、锁定调色板的说明、编号隐喻和固定构图文本——参见 reference/prompt-template.md 和 reference/construction.md。
4. 生成图表。 按能力顺序选择图像提供方（见 reference/image-providers.md）——切勿假定 Codex 可用：
   1. 优先使用内置／宿主图像生成能力——如果运行中的 Agent 已有可调用的图像生成工具（包括 Codex 内置的 image_gen 工具或 imagegen skill），直接调用。不要仅为从其他进程使用 imagegen 而委托给外部 Codex CLI。
   2. Codex CLI 后备方案——仅当此 Agent 没有可调用的图像生成工具，且 Codex 可用时（从可用 Skill 清单定位 codex，或使用 PATH 中已有的 codex），才委托其生成。
   3. 外部 API 后备方案——仅当以上两种方案都不可用时，沿用用户已授权的供应商；缺少凭据时，按配置说明打开随附页面，不索要聊天中的 Key；对于 OpenAI Images，scripts/gen_image.py --prompt "…" --out raw/<style>.png 已可直接使用。 将每张生成的图表以纯灰色 #808080 背景保存或复制到 raw/<style>.png。内置 imagegen 可能会将图表保存在 $CODEX_HOME/generated_images/...；生成后，将选中的 PNG 移动或复制到任务输出的 raw/ 文件夹。同一张图更容易保持共同风格，但仍须逐个验收，不能把一次生成视为一致性保证；提供方只需将提示词转换为灰色背景 PNG。
5. 切图。 运行一次 scripts/setup.sh，然后运行： .venv/bin/python3 scripts/slice_icons.py <raw>.png <outdir> --mode <cutout> [--thresh N] [--grid 4] [--count N] 使用风格指定的 cutout 模式（纯色／硬边图使用 floodfill，柔和／3D／光泽／照片风格使用 rembg）。
6. 质量检查（必须）。 将切出的 PNG 合成到对比色背景上（例如洋红色），逐个检查图标是否存在：(a) 邻近单元格的碎片渗入；(b) 残留灰色；(c) 是否符合风格的 construction 要求——描边统一、圆角半径一致、细节程度匹配、共用部件、包含主题元素、透视统一，且强调色的视觉权重不超过定义性元素（线条风格中，强调色必须比描边更浅、更小）。对不合格的图标重新切图或生成——绝不能交付带有上方单元格图标碎片的图标。
7. 交付透明 PNG，并整理好文件结构和命名。

内置样式

样式	外观	抠图方式	适用场景
linear	单色线条／轮廓	floodfill	实用工具、设置
filled	单色实心字形	floodfill	移动端导航栏／标签栏
colorblock	大胆的扁平多色块	floodfill	儿童、创意
cartoon	贴纸风格卡通	rembg	游戏、娱乐
isometric	等距 3D 微缩模型	rembg	SaaS、仪表盘
render3d	光泽蓬松的 3D	rembg	奖励、引导流程
sticker	模切光泽乙烯基贴纸	rembg	社交、互动反馈
realistic	照片级真实的产品渲染图	rembg	电商、主视觉
animal-badge	徽章中的动物标志	rembg	头像、儿童

每个 styles/<name>.json 都包含前导提示、锁定的调色板、抠图模式、阈值、构建系统和适用场景。

关键规则（参见 reference/design-rules.md）

• 在规范中将调色板锁定为十六进制值——否则彩色样式每次运行都会出现偏差。
• 切勿制作黑色实心图标——可以使用近黑色／黑色作为细轮廓或线条，但绝不能让它成为一组图标中占主导的实心区域。如果品牌前景色是黑色，请仅将其用于线条；对于实心或双色调样式，请为主体选择中浅色的品牌色，并少量使用深色。
• 从真实的产品背景出发——当用户提供线上网站、截图、吉祥物、徽标或品牌素材时，首先基于该来源推导图标概念和构建方式。不要直接套用等距、双色调、3D 或色块等通用风格系列；这些只是最后应用的修饰，应在确定产品主题、真实导航和实际功能名称后再使用。
• 切片会去除相邻内容——切片器只保留每个单元格中居中的图标。
• 根据边缘类型选择抠图方式——平坦／硬边缘 → floodfill；柔和／3D／光泽／照片风格 → rembg。
• 设计的精致程度来自构建系统和品牌主题，而不是给通用图标集换色——每种样式的 construction 对象都编码了网格、描边、圆角、细节预算、共享部件和主题（参见 reference/construction.md）。严谨的系统最终需要使用矢量图；栅格图适用于方向探索和点缀图标。