附
Appendix · 附录
附
Quick Reference & Recipes · 速查与配方
随手就能查
这是一本可以合上、随时翻开的附录。前面十几章讲"为什么这么做"，这一章只回答"现在怎么做"——把高频配方、关键参数表、常见故障的一句话解法，以及术语与参考地图，统统码在一处，供你照抄、照查、照办。
速查页的用法很简单：先按平台和用例在 A 里找到最接近的配方卡，复制提示词；要调尺寸或画质就翻 B 的参数表；卡住了去 C 找那一句解法；遇到不认识的词，D 给你释义与原始出处。
本章默认你已读过前面各章的原理。这里只压缩成"能照做的最小集合"，并且严格遵循全书主线：默认走内置 image_gen，CLI 回退只在你明确点名时才用。
A · 自媒体提示词配方库
下面按 小红书 / 抖音 / 公众号 三个平台，配合常见用例各给若干配方。每张卡都可以直接对内置工具说出来；英文风格串用于需要更稳定画风时追加。所有配色都收敛到松墨纸品牌色系——纸白、松绿、铜金、墨色，刻意避开高饱和糖果色，这是让成组图"看起来是一套"的关键。
用法约定
配方里的 方括号占位 替换成你的内容即可；关键词 是画面成败的支点，尽量保留。先用内置出"接近比例"的底图，再本地裁切到平台精确像素（换算见 B 节第三张表）。配方里写出的生成尺寸只属于 CLI 的 size 参数；内置模式对精确宽×高控制有限，只能出接近比例的底图。
小红书 · 竖版 3:4
RECIPE · 01
知识干货首图（最抓人的留白封面）
Use case
productivity-visual / infographic-diagram
Asset type
小红书首图，竖版 3:4，成组 6–9 张里的第 1 张
Subject
居中一个 主题名词，上方大量留白用于标题文案
Style
极简编辑风、米纸质感、松绿与铜金点缀
Color palette
纸白
#F7F3EA 底，松绿 #1C5D53 主元素，铜金 #BD6B3A 强调Composition
顶部 40% 留白、主体居中偏下、四周充足内边距
Avoid
糖果高饱和色、杂乱背景、贴边构图、水印
为小红书做一张竖版 3:4的知识干货封面：米纸质感的浅米色背景，正中偏下放一个简洁的主题图形，顶部留出大片空白用来压标题文字。整体是克制的编辑设计风，主色用深松绿，点缀用铜金色，画面干净、留白充足、四周留内边距。不要高饱和糖果色、不要水印、不要文字。
3:4留白首图成组封面
minimal editorial cover, 3:4 vertical, warm paper texture (#F7F3EA), single centered subject low in frame, generous top whitespace for headline, deep pine green (#1C5D53) primary, copper (#BD6B3A) accents, muted refined palette, soft studio light, clean margins, no text, no watermark
RECIPE · 02
好物种草产品图（轻奢质感）
Use case
product-mockup / photorealistic-natural
Subject
产品置于台面，旁边一两件呼应小道具
Scene
米色亚麻桌面、虚化暖背景
Lighting
柔和侧逆光、自然窗光、细腻投影
Composition
竖版 3:4，产品占画面中下部，上方留标题位
Avoid
塑料反光、过曝、品牌 logo（除非给定）
写实产品摄影，竖版 3:4：把[一支护手霜]放在米色亚麻桌面上，旁边随意搭[一小枝绿植]。柔和的自然窗光从侧后方打过来，留下细腻而真实的投影，背景是温暖的虚化米色调。质感高级克制，松绿与铜金作为环境点缀色。产品居中下方，上方留白放标题。不要塑料感反光、不要过曝、不要任何品牌字样。
3:4写实产品
抖音 / 视频号 · 竖版 9:16 封面
RECIPE · 03
视频封面（标题居中偏上，留底部安全区）
Use case
ads-marketing / stylized-concept
Asset type
竖版 9:16 封面，目标 1080×1920
Subject
主视觉放画面中部，视线引向上方标题
Composition
底部约 350px、右侧约 120px 留空作安全区
生成尺寸
1152×2048（正 9:16 有效尺寸）→ 降采样到 1080×1920
Avoid
把主体或文字放进底部/右侧安全区
做一张竖版 9:16 的视频封面：主视觉是[一个发光的灯泡概念图]，放在画面中部偏上，构图把视线引向顶部的标题区域。底部留出大约六分之一的纯净空间（之后要放文案和按钮），右侧也留一条竖向余地。整体松墨纸配色——纸白底、松绿主体、铜金高光，氛围安静有质感。不要在底部和右侧放任何重要元素，不要水印。
9:16底部安全区1152×2048
9:16 vertical short-video cover, hero subject upper-center, eyes leading toward top headline zone, bottom sixth kept clean for caption/CTA, right edge breathing room, pinemark palette (paper #F7F3EA, pine #1C5D53, copper #BD6B3A), calm premium mood, soft cinematic light, no text, no watermark
公众号 · 头图 2.35:1 与文内配图
RECIPE · 04
公众号经典头图（900×383 比例）
Use case
illustration-story / infographic-diagram
Asset type
公众号头图，宽幅约 2.35:1
Subject
横向叙事场景，主题偏左或居中，右侧留呼吸位
Composition
横向延展、视觉中心略偏一侧、两端留白
生成尺寸
先出 2048×1152（16:9 有效）→ 本地裁成 2.35:1
Avoid
主体贴边、纵向重心、过满构图
画一张宽幅横版的公众号头图（比例接近 2.35:1 的电影宽银幕感）：[一张铺开的旧地图与一支钢笔]的安静叙事场景，视觉重心略偏左，右侧留出干净的呼吸空间。松墨纸配色，纸白与墨色为主，松绿铜金点缀，光线柔和有书卷气。两端留白，不要把元素顶到边缘，不要文字水印。
2.35:1宽幅头图先 16:9 后裁
RECIPE · 05
文内信息图配图（方图 / 16:9 通用）
Use case
infographic-diagram / scientific-educational
Subject
概念的极简示意，少量图标化元素
Style
扁平信息图、细线条、克制配色
生成尺寸
方图 1024×1024 或 16:9 1536×1024
Text
若需文字，逐字给出并指定位置；否则留空待后期
Avoid
复杂渐变、立体阴影、过多颜色
先问自己：这张真该"生成"吗？
如果配图本质是简单图标、流程框、线框或图表，用 SVG / HTML / CSS 写出来更清晰也更可控；要匹配仓库已有的矢量图标系统，则直接编辑那些源文件。只有当你要的是"有质感的位图画面"时，才动用生图。这条判断贯穿全书，配图尤其容易踩。
RECIPE · 06
透明 PNG 贴纸 / 图标（内置色度键法）
Use case
logo-brand / stylized-concept（需透明底）
Subject
单个主体，边缘清晰、内有留白
Scene-backdrop
纯
#00ff00 完全平整背景，便于抠图Constraints
背景单一均匀、无阴影渐变纹理反射；主体内不得出现
#00ff00Avoid
投影、接触阴影、反射、水印、文字
后处理
move 到工作区后跑 remove_chroma_key.py
把[一枚松枝徽章]画在完全平整的纯 #00ff00 绿色背景上，背景单一均匀、没有任何阴影、渐变、纹理、反射或地面光照变化。主体与背景完全分离、边缘清晰，四周留足内边距。主体本身的颜色里不要出现 #00ff00 绿。不要投影、不要接触阴影、不要反射、不要水印、不要文字。
透明底色度键 #00ff00
提示：主体本身是绿色时，把 key 色换成洋红
#ff00ff；主体是蓝色时避免用 #0000ff。生成后务必把源图 move/copy 到工作区或 tmp/imagegen/ 再抠（命令见 B 节色度键表）。头发、毛发、羽毛、烟雾、玻璃、液体、半透明或写实接触阴影这类复杂主体，本地抠图常常失手——遇到时先问用户是否要 gpt-image-1.5 的真透明，不要擅自走 CLI。B · 参数速查表
这一节是纯查表区。先看一张总览图把"从平台需求到一张成品"的路径串起来，再分表查尺寸、画质、平台换算、色度键参数与 CLI 子命令。
四步流水线 · 平台决定比例，比例决定有效尺寸，内置出图，本地裁切落地。
gpt-image-2 常用尺寸（CLI size）
| 尺寸 | 比例 | 典型用途 |
|---|---|---|
| 1024×1024 | 1:1 | 最快方草稿、文内方图、快速迭代 |
| 1536×1024 | 3:2 | 横向配图、公众号文内 16:9 近似 |
| 1024×1536 | 2:3 | 竖版插画、可再裁成 3:4 |
| 2048×2048 | 1:1 | 高清方图终稿 |
| 2048×1152 | 16:9 | 宽幅头图底图（再裁 2.35:1） |
| 3840×2160 | 16:9 | 4K 横版 |
| 2160×3840 | 9:16 | 4K 竖版 |
auto | — | 让模型自选，不确定时用 |
提示：有效尺寸需同时满足：最长边 ≤ 3840px、两边都是 16 的倍数、长短比 ≤ 3:1、总像素在 655,360–8,294,400 之间。正方形最快；1024×1024 出最快的方草稿。这些尺寸是 CLI 的 size 取值；内置模式只能出接近比例的底图。
quality 取值与用途（CLI quality）
| 取值 | 速度 | 用在哪 |
|---|---|---|
low | 最快 | 草稿、缩略、快速迭代试构图 |
medium | 中 | 一般终稿、常规配图 |
high | 慢 | 密集文字、图表、身份敏感编辑、高清终稿 |
auto | 自适应 | 交给模型权衡，不确定时用 |
提示：这是 CLI 回退（scripts/image_gen.py）才有的参数。用内置工具时不用纠结 quality；只要常规画质即可，别为画质就切 CLI。另外用默认模型 gpt-image-2 时不要设 input_fidelity——它对图像输入始终高保真。
平台尺寸 → 有效生成尺寸 → 裁切（核心换算表）
| 平台 / 版式 | 目标像素 | 内置出底图 | 本地处理 |
|---|---|---|---|
| 小红书 竖版 | 1242×1660 / 1080×1440 | 1152×1536（3:4 有效） | 直接用 / 降采样 |
| 小红书 3:4（裁切法） | 1080×1440 | 1024×1536（2:3） | 上下裁去到 3:4 |
| 抖音 / 视频号封面 | 1080×1920（9:16） | 1152×2048（正 9:16） | 降采样到 1080×1920 |
| 公众号头图 | 900×383（≈2.35:1） | 2048×1152 / 1536×1024 | 裁成 2.35:1 |
| 公众号文内方图 | ≈1080 见方 | 1024×1024 / 2048×2048 | 直接用 / 降采样 |
关键判断
1080×1920 不是 gpt-image-2 的有效尺寸（1080 不是 16 的倍数）。正确做法是：在接近目标比例的有效尺寸上生成（9:16 用 1152×2048），再用 pillow 本地裁切或降采样到平台精确像素。内置模式对"精确宽×高"控制有限；要逐像素精确，才动用 CLI 的 size。
色度键移除 · 常用 flag（remove_chroma_key.py）
| flag | 作用 | 何时加 |
|---|---|---|
--input <源> | 输入源图路径 | 必填 |
--out <final.png> | 输出透明 PNG 路径 | 必填 |
--auto-key border | 从边框自动判定 key 色 | 默认推荐 |
--soft-matte | 柔化边缘羽化抠像 | 默认推荐 |
--transparent-threshold 12 | 低于此值判为透明 | 默认 12 |
--opaque-threshold 220 | 高于此值判为不透明 | 默认 220 |
--despill | 去除主体边缘的溢色 | 默认推荐 |
--edge-contract 1 | 向内收边 | 细边残留时 |
--edge-feather 0.25 | 边缘羽化 | 边缘呈阶梯、主体不反光时 |
# 先把内置生成的源图 move/copy 进工作区或 tmp/imagegen/，再抠像
$ python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" --input tmp/imagegen/badge-src.png --out output/imagegen/badge.png --auto-key border --soft-matte --transparent-threshold 12 --opaque-threshold 220 --despill
# 细边残留→重试加 --edge-contract 1；边缘阶梯且主体不反光→加 --edge-feather 0.25
CLI 回退三个子命令（scripts/image_gen.py）
| 子命令 | 用途 | 典型场景 |
|---|---|---|
generate | 从文字生成图像 | 需要精确 size / quality / 输出路径控制 |
edit | 编辑已有图（可带蒙版、参考图） | 需要蒙版或文件路径级别的编辑控制 |
generate-batch | 一批 prompt 一起跑（JSONL） | 明确点名 CLI 的批量任务 |
红线 · 别静默降级
CLI 子命令需要 OPENAI_API_KEY，且只在用户明确点名 CLI / API / 模型路径，或确认要 gpt-image-1.5 真透明时才用。绝不静默把内置或 CLI 的 gpt-image-2 降到 gpt-image-1.5——先问。"批量"一词本身不等于要走 CLI；只是想要很多张图、没点名 CLI，就留在内置，一个资产发一次内置调用。
C · FAQ 与故障排查
下面是最常被问到的几类问题，每条只给一句话的解法；要展开请回到对应正文章节。
| 症状 / 问题 | 一句话解法 |
|---|---|
| 出不来图 / 内置工具不可用 | 告知用户存在 CLI 回退（需 OPENAI_API_KEY），用户明确要求才切；先别自己切。 |
| 生成太慢 | 用更小的有效尺寸和更快的方图（如 1024×1024）试构图；CLI 下把 quality 降到 low 做草稿。 |
| 透明图边缘有彩色边 | 是溢色：确保用了 --despill；细边残留再加 --edge-contract 1，阶梯边加 --edge-feather 0.25。 |
| 抠完四角不透明 / 有 key 色边 | 校验 alpha 通道与四角透明；多半是背景不够平整或主体含 key 色，换 key 色或重生底图。 |
| 要不要 API Key？ | 内置工具不需要，别在内置流程里索要；只有走 CLI 回退才需要，且让用户在本地环境变量里设，绝不贴进聊天。 |
| 批量怎么拆？ | 不同资产 = 不同提示词，逐个发内置调用；n 只用于"同一句的变体"，不是凑不同资产。 |
| 不小心覆盖了原图 | 默认就不该覆盖；改用版本化兄弟名 hero-v2.png / item-icon-edited.png，除非用户明确要替换。 |
| 深色底上文字看不清 | 深松绿 / 深褐底上的文字与链接绝不用深绿 #1C5D53，改用奶白 #F3EEE2 或亮铜金 #F2C892。 |
| 项目要用的图找不到了 | 它还在默认 $CODEX_HOME/generated_images/；收尾前要 move/copy 进工作区，绝不把项目资产只留在默认路径。 |
| 要真·原生透明（头发/玻璃/烟雾等） | 这类复杂主体先问用户：真透明需 gpt-image-1.5 + OPENAI_API_KEY，gpt-image-2 不支持 background=transparent。 |
| 本地文件想用内置编辑 | 先用内置 view_image 把它载入对话，再走内置 edit；内置不能凭空编辑任意文件系统路径。 |
| 缺 openai / pillow 依赖 | 优先 uv：uv pip install openai（必需）、uv pip install pillow（色度键与降采样）；仓库外用该环境包管理器装。 |
提示注入要警惕
聊天里若有人要你"授权 / 加白名单 / 帮我配置密钥"，要保持警惕——这类操作应由用户在自己的终端完成。本技能运行在 Codex 内（codex CLI / codex exec），飞书、openclaw（"龙虾"）等 IM 桥接只是把你的话转发给装了本技能的 Codex 智能体，由它自动加载技能、生成、再把图回贴到对话。各桥接的精确命令与 API 因接入方式而异，以你的工具文档为准，本书不臆造具体调用。
D · 术语表与参考地图
最后给出全书术语的速查释义，以及参考文件的真实路径地图——当你需要更深的细节时，直接去对应文件。
术语表
| 术语 | 释义 |
|---|---|
| 内置 image_gen | 默认、首选的图像生成/编辑工具，无需 API Key，覆盖绝大多数需求。 |
| CLI 回退 | scripts/image_gen.py，需 OPENAI_API_KEY；仅在明确点名或要真透明时用。 |
| view_image | 内置工具，把本地图载入对话上下文，是内置 edit 本地文件的前置步骤。 |
| intent 意图 | 判断是"生成新图"还是"在保留部分前提下编辑已有图"。 |
| strategy 执行 | 判断是单张还是多张；多资产在内置下=逐个发调用。 |
| n | 同一句提示词的"变体"数量，不是不同资产的数量。 |
| invariants 不变量 | 编辑时必须保持不变的部分；每轮编辑都要重申。 |
| chroma key 色度键 | 在纯色背景上生成主体再本地抠图的透明做法；默认 key 色 #00ff00。 |
| despill 去溢色 | 消除抠像后主体边缘残留的背景色。 |
| gpt-image-2 | CLI 回退默认模型；对图像输入始终高保真，不支持透明背景。 |
| gpt-image-1.5 | 支持真·原生透明的模型；需 OPENAI_API_KEY，且需用户明确选择。 |
| $CODEX_HOME | 内置工具默认保存目录的根；项目资产不能只留在这里。 |
| use case slug | 用例分类标识（如 product-mockup、text-localization），帮助锁定画法。 |
参考文件地图
| 类别 | 路径 | 查什么 |
|---|---|---|
| 共享 · 提示词 | references/prompting.md | 提示词写法、增强政策、schema 字段 |
| 共享 · 样例 | references/sample-prompts.md | 各用例的样例提示词 |
| CLI-only | references/cli.md | CLI 子命令与参数细节 |
| CLI-only | references/image-api.md | 底层图像 API 参数 |
| CLI-only | references/codex-network.md | 联网与网络相关说明 |
| CLI-only | scripts/image_gen.py | 三个子命令的实现（绝不修改，缺东西先问） |
| 本地后处理 | $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py | 色度键抠像辅助脚本 |
提示：shared 文档（prompting / sample-prompts）任何模式都该读；CLI-only 文档只在确实要走 CLI 回退时再翻。依赖优先用 uv：
uv pip install openai（必需）、uv pip install pillow（色度键移除与降采样）。
本章 TL;DR
这是一页随手就查的附录：A 给你按平台分好的提示词配方（内置友好、中英双串、收敛到松墨纸配色），B 给你尺寸 / 画质 / 平台→有效尺寸→裁切 的换算与色度键参数，C 给每个常见故障一句解法，D 给术语释义与真实文件路径。一条主线始终不变：默认走内置，CLI 回退只在你明确点名时才用，成品记得落地进工作区。