Files

T

starmen1265 830128d812 docs(ai-art): codex生图工作规范与双通道说明

2026-06-21 23:28:59 +08:00

15 KiB

Raw Blame History

codex 生图工作规范（用 ChatGPT Plus 订阅额度）

让日常 AI 生图走 Codex CLI 内置 image_gen 工具，消耗 ChatGPT Plus 会员的订阅额度，不按张计费。创建时间：2026-06-20 · 配套现有 tools/image_gen.py（apiyi 通道，降级为兜底）

0. TL;DR

日常生图默认走 codex 通道（订阅额度，不花钱），apiyi 仅作兜底。
codex 内置 image_gen 用的就是 gpt-image-2——和 apiyi 同一个模型，质量一致。
执行方式（重要）：codex exec 由用户在自己的终端（PowerShell）运行。Claude Code 的安全分类器会硬拦 codex exec --dangerously-bypass-approvals-and-sandbox（"Create Unsafe Agents"，不可配置放行），所以 Claude 不能自动跑这条命令。分工：用户终端跑 codex 生图 → Claude 读结果并完成捞图 / 命名 / 写 .meta.json 收尾。
完整复用 现有 prompts/*.txt、STYLE_SEED_EN 风格种子、生成结果/ 命名规则、.meta.json。
命令模板记一句话：codex exec --dangerously-bypass-approvals-and-sandbox -C <dir> -o <lastmsg.txt> "<prompt>"（用户终端执行）

1. 背景：为什么多了这条通道

	codex 通道（新增·默认）	apiyi 通道（原有·兜底）
模型	`gpt-image-2`（Codex 内置 image_gen 工具）	`gpt-image-2`（apiyi 中转）
计费	ChatGPT Plus 订阅额度，不按张计费	按张计费，约 0.04–0.05 元/张
需要 API Key	❌ 不需要 `OPENAI_API_KEY`	✅ 需要 `APIYI_API_KEY`
文生图	✅	✅
多参考融合	✅ 最多 5 张	✅（`images.edit`，apiyi 支持度不稳）
编辑	✅	❌（现有工具未封装）
透明背景	⚠️ gpt-image-2 不支持，需 chroma-key 变通	⚠️ 同
限额	ChatGPT Plus 约 40–50 张 / 3 小时滚动窗口	无（按张付费）
附加成本	每张额外消耗 ~30k Codex agent token	无
执行者	用户在终端跑 codex exec（Claude 收尾）	Claude 直接跑 `python tools/image_gen.py`
自动化程度	半自动（生图执行步手动）	全自动

为什么 codex 通道是"半自动"：Claude Code 的 auto mode 分类器把 codex exec --dangerously-bypass-approvals-and-sandbox 判为"创建不安全自主 agent"，是硬安全规则、任何 settings 配置都放行不了（allow:["Bash"]、bypassPermissions 都无效）。所以生图这一步必须由人在终端按一下回车；Claude 承担其余所有工作（组装 prompt、捞图、命名、写 meta）。

何时用哪个：

默认 → codex（省钱，生图步在终端手动跑）。
撞 429 限额 / 需真·透明背景 / 要 Claude 全自动批量 → apiyi 兜底。

2. 前置自检（本机已实测通过 ✅）

# codex 可执行绝对路径（codex 不在默认 PATH，见下一节）
CODEX="/c/Users/starm/.codex/packages/standalone/current/bin/codex.exe"

"$CODEX" --version            # → codex-cli 0.141.0 ✅
"$CODEX" login status         # → "Logged in using ChatGPT" ✅（走订阅，非 API 计费）
"$CODEX" features list | grep image_generation   # → image_generation  stable  true ✅
grep auth_mode ~/.codex/auth.json                # → "auth_mode": "chatgpt", ✅

解读：auth_mode=chatgpt = 走 ChatGPT OAuth 订阅额度；若显示 api_key 则是按张计费，需 codex login 重新用 ChatGPT 登录。

3. codex 怎么调（重要：PATH 问题）

本机 codex 是 standalone 安装，不在默认 PATH。二进制在：

~/.codex/packages/standalone/current/bin/codex.exe        # current 是指向当前版本的软链接
# 即 C:\Users\starm\.codex\packages\standalone\current\bin\codex.exe

用户在 PowerShell 里调用（推荐先赋变量，命令更短）：

$CODEX    = "$env:USERPROFILE\.codex\packages\standalone\current\bin\codex.exe"
$RESEARCH = "E:\MiceCola\work\ChildHood\ai-art-research"
& $CODEX --version          # 验证能跑

若你已把 codex 加进 PATH，可直接用 codex 代替 & $CODEX。 Claude（git bash）做收尾时用 /c/Users/starm/.codex/packages/standalone/current/bin/codex.exe 这个路径形式。

4. Codex 通道 SOP（协作模式）

协作流程：

① Claude 组装 prompt（注入风格种子 / 读 prompts/ 文件）
② 用户在 PowerShell 跑 codex exec（生图，写到 -o 文件 + 默认目录）
③ Claude 读 -o 文件取路径 → copy + 按命名规则 rename → 写 .meta.json

4.1 用户终端执行的命令模板（PowerShell）

$CODEX    = "$env:USERPROFILE\.codex\packages\standalone\current\bin\codex.exe"
$RESEARCH = "E:\MiceCola\work\ChildHood\ai-art-research"

& $CODEX exec `
  --enable image_generation `
  --dangerously-bypass-approvals-and-sandbox `
  --skip-git-repo-check `
  -C $RESEARCH `
  -o "$RESEARCH\.codex_lastmsg.txt" `
  "<见 4.2 / 4.3 / 4.4 各场景的 prompt>"

四个不可省的 flag：

--enable image_generation —— 关键：codex exec 默认不启用图像生成 feature，会话里不会暴露内置 image_gen 工具（agent 会报"当前会话没有 image_gen 工具"）。codex features list 的 stable=true 只代表"受支持"，不代表"已启用"；必须用此 flag，或在 ~/.codex/config.toml 的 [features] 写 image_generation = true 才真正启用。
--dangerously-bypass-approvals-and-sandbox —— 不加会被默认沙箱断网（Could not resolve host: api.openai.com）。
-C/--cd 指向 ai-art-research —— 让 Codex 能直接读 prompts/、参考图/，也便于落盘。
--skip-git-repo-check —— 该目录不是 git 仓库根，跳过检查。

捞图利器 -o：把 Codex 最后一条消息（含生成图路径）写到 .codex_lastmsg.txt，Claude 读它取路径——比从 stdout 自然语言里正则捞可靠得多。（也可用 --json 输出 JSONL 事件流解析。）

prompt 里必带的一句（防止 Codex 跑偏去写脚本、走 API 变回计费）：

「用 Codex 内置的 image_gen 工具直接生成，不要写任何 Python/Node 脚本，不要使用 OPENAI_API_KEY 或外部 Images API。生成完成后告诉我图片的完整文件路径。」

4.2 文生图（对应 `image_gen.py -g`）

Codex 的 prompt 由 Claude 组装：STYLE_SEED_EN + 用户内容（自动加风格前缀，与现有脚本一致）。把下面整段作为 4.1 模板里的 <prompt>：

用 Codex 内置的 image_gen 工具（gpt-image-2）直接生成 1 张图。
不要写任何 Python/Node 脚本，不要使用 OPENAI_API_KEY 或外部 Images API。
Prompt: 3D low-poly game art, flat cel-shaded with solid color blocks, bright warm-cool balanced saturated palette, soft diffused lighting with subtle shadows, simplified geometric forms with clean edges, low-angle third-person perspective, nostalgic warm summer atmosphere, <用户内容或 prompts/xxx.txt 的内容>
尺寸: 1024x1024   质量: medium
生成完成后，告诉我图片的完整文件路径。

风格种子原文见 tools/image_gen.py 的 STYLE_SEED_EN（不要手抄，Claude 直接引用）。 prompts/*.txt（如 居民楼-好楼房-标准单元-楼型1.txt）由 Claude 读取后整段作为「<用户内容>」注入，再由用户复制完整命令到终端跑。

4.3 双参考融合（对应 `image_gen.py --fuse`）

Codex 会用内置 view_image 加载本地图再融合。多图按 Image 1 / Image 2 /… 引用：

用 Codex 内置的 image_gen 工具（gpt-image-2）直接生成 1 张图，不要写脚本、不要用 API key。
参考图（已在工作目录下，请用 view_image 加载）：
- Image 1（风格参考）: ./参考图/游戏截图/深夏时光01.png —— 只取它的画法与色调，不要它的日本小镇内容
- Image 2（内容参考）: ./参考图/真实场景/城郊小卖部.jpg —— 取它的场景布局与建筑结构
要求：用 Image 1 的美术风格呈现 Image 2 的场景；保持千禧年中国城郊风貌，温暖怀旧夏日午后。
尺寸: 1024x1024   质量: medium
生成完成后，告诉我图片的完整文件路径。

中文融合模板可复用 tools/image_gen.py 的 DEFAULT_FUSION_PROMPT。支持最多 5 张参考图（风格 1 + 内容 N）。迭代编辑时每次复述不变量（"只改 X，保持 Y 不变"）以减少漂移。实测提示：Codex agent 对"先 view_image 再融合"一般正确执行；若融合没生效，把参考图 copy 进 --cd 目录用相对路径重试。

4.4 编辑（现有工具未覆盖，codex 通道的能力增强）

用 Codex 内置的 image_gen 工具编辑已有图片，不要写脚本、不要用 API key。
编辑目标（用 view_image 加载）: ./生成结果/双参考融合/好楼房/xxx.png
改动：只把背景天空换成傍晚暖光，保持建筑本身、比例、画风完全不变。
生成完成后，告诉我新图片的完整文件路径。

4.5 捞图 + 命名落盘 + 写 meta（Claude 收尾，严格复用现有规则）

用户在终端跑完 4.1 命令后，告诉 Claude"跑完了"，由 Claude 做以下收尾（用户也可自己按规则手动落盘）：

取路径：读 -o 指定的 ai-art-research/.codex_lastmsg.txt，提取生成图完整路径；取不到就 glob ~/.codex/generated_images/ 下最新 ig_*.png。
落盘：copy 成现有命名格式（与 image_gen.py 的 save_result() 完全一致）：
- 路径：ai-art-research/生成结果/<子目录>/<时间戳>_gpt-image-2_<模式>.png
- 时间戳：datetime.now().strftime("%y%m%d-%H%M%S")，如 260620-213000
- 模式 slug：gen / calib / fusion / test（沿用 _MODE_SLUG）
- 子目录：文生图 / 风格校准 / 双参考融合/<分类> / 测试
写 .meta.json（同名），在原 schema 上新增 backend 字段标记来源：

{
  "model": "gpt-image-2",
  "backend": "codex",
  "prompt": "<完整 prompt，含风格种子>",
  "mode": "text_to_image",
  "style_prefix_used": true,
  "size": "1024x1024",
  "quality": "medium",
  "timestamp": "<ISO>"
}

融合场景的 meta 另含 "style_reference" / "content_references"（参考图路径数组），与现有 --fuse 产物一致。

.codex_lastmsg.txt 是临时文件，读完即可删（ai-art-research/ 整目录已被项目 .ignore 屏蔽，不进 git）。

5. apiyi 兜底 SOP

触发条件（任一满足即切 apiyi，且这条通道 Claude 可全自动跑）：

Codex 报 429 / 限额提示（Plus 约 40–50 张/3h 窗口）。
需要真·透明背景（gpt-image-2 不支持）。
需要 Claude 全自动批量（不想手动跑终端）与 100% 确定性输出。

切法：直接用现有脚本（backend 标 apiyi）：

cd /e/MiceCola/work/ChildHood/ai-art-research
python tools/image_gen.py -g "千禧年中国城郊的小卖部门口"          # 文生图
python tools/image_gen.py --fuse -s 参考图/游戏截图/深夏时光01.png \
                                     -c 参考图/真实场景/城郊小卖部.jpg   # 双参考融合
python tools/image_gen.py --fuse -s style.png -c photo.jpg -pf prompts/居民楼-好楼房-标准单元-楼型1.txt

现有脚本未写 backend 字段；用 apiyi 通道时，Claude 在产物 .meta.json 里补 "backend": "apiyi" 以区分来源。详见 README.md。

6. gpt-image-2 约束清单（codex 与 apiyi 通用）

尺寸：边长必须是 16 的倍数；最大边 ≤ 3840px；长短边比 ≤ 3:1；总像素 655,360 ~ 8,294,400。
常用合规尺寸：1024x1024（默认·最快）/ 1536x1024（横）/ 1024x1536（竖）/ 2048x2048（2K）/ 2048x1152 / 3840x2160（4K）。
透明背景：gpt-image-2 不支持 background=transparent。
- 建筑/立面图用不到，无影响。
- 将来道具抠图若需透明：① codex 通道走 chroma-key 绿幕 + 本地 $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py 去背景；② 或 fallback 到 apiyi / gpt-image-1.5。
限额：ChatGPT Plus 约 40–50 张/3 小时（动态，OpenAI 不公布固定值）；批量出建筑变体时分批，撞限额切 apiyi。

7. 常见故障

现象	原因	处理
`Could not resolve host: api.openai.com`	没加 `--dangerously-bypass-approvals-and-sandbox`，默认沙箱断网	加上该 flag
Codex 自己写起了 Python/Node 脚本	prompt 没明示"用内置工具、不要写脚本"	在 prompt 开头加那句强制约束
生成了图但找不到文件	Codex 存到默认 `~/.codex/generated_images/<session>/ig_*.png`	读 `-o` 的 lastmsg 取路径，或 glob 该目录最新文件
429 / 限额	撞 Plus 3h 窗口	切 apiyi 兜底
`auth_mode: api_key`	codex 当前走 API 计费	`codex login` 重新用 ChatGPT OAuth 登录
融合没用到参考图	Codex 没 view_image 加载	把参考图 copy 进 `--cd` 目录，用相对路径 + 明确 `Image 1/2` 引用重试
agent 报"当前会话没有 image_gen 工具"	`codex exec` 默认未启用 image_generation feature	命令加 `--enable image_generation`（或在 `~/.codex/config.toml` 的 `[features]` 写 `image_generation = true`）
Claude 说"我不能跑 codex"	auto mode 分类器硬拦（设计如此）	这是预期行为；由用户在终端跑该命令，Claude 做收尾

8. 复用资产清单（不要另起炉灶）

资产	位置	怎么用
风格种子	`tools/image_gen.py` → `STYLE_SEED_EN`	文生图 prompt 前缀，Claude 引用注入
Prompt 模板（14 个）	`prompts/*.txt`	Claude 读取整段作为生图内容/融合 prompt
融合中文模板	`tools/image_gen.py` → `DEFAULT_FUSION_PROMPT`	双参考融合场景的 prompt 骨架
命名规则	`tools/image_gen.py` → `save_result()` / `_MODE_SLUG`	`<时间戳>_gpt-image-2_<模式>.png` + 同名 `.meta.json`
参考图库（230 张）	`参考图/游戏截图`、`参考图/真实场景`、`参考图/美术风格`	融合的输入
输出目录	`生成结果/{文生图,风格校准,双参考融合/<分类>,测试}`	codex 产物落这里，与 apiyi 产物混排，靠 meta 的 `backend` 区分

9. 与主项目的关系

本规范是 ai-art-research/ 工具链的一部分，独立于 UE5 工程。
项目根 CLAUDE.md 的「## AI 生图」一节指向本文件：默认走 codex 通道（用户终端执行 + Claude 收尾），apiyi 兜底。
ai-art-research/ 被项目 .ignore 屏蔽，不进 ripgrep/Glob 检索；操作需用显式路径（本文件所有命令均用绝对/相对显式路径）。

15 KiB Raw Blame History Unescape Escape