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

2026-06-21 23:28:59 +08:00
parent a37dfa505a
commit 830128d812
3 changed files with 267 additions and 0 deletions
@@ -125,3 +125,8 @@ ai-art-research/.env
 *.swo
 *~
 temp.txt
+
+# ==============================
+# AI 生图 — codex 运行残留（codex exec -o 输出，每次覆盖，不入库）
+# ==============================
+ai-art-research/.codex_lastmsg.txt
@@ -30,3 +30,13 @@
 - 分支: `develop/`
 - 提交: `<type>(<scope>): <中文描述>`，subject ≤ 50 字符
 - UE5: 蓝图与 C++ 分开提交；.uasset/.umap commit message 必须写清内容
+
+---
+
+## AI 生图
+
+- **默认走 Codex 通道**（ChatGPT Plus 订阅额度，不按张计费），完整流程见 [`ai-art-research/codex生图工作规范.md`](ai-art-research/codex生图工作规范.md)。该通道为**协作模式**：`codex exec` 由**用户在终端执行**，Claude 负责组装 prompt 与捞图/命名/写 meta 收尾——Claude Code 的安全分类器会硬拦 `codex exec --dangerously-bypass-approvals-and-sandbox`（“Create Unsafe Agents”，不可配置放行），无法自动跑。
+- **apiyi 兜底**（`tools/image_gen.py`，按张计费）：撞 ~40–50 张/3h 限额 / 需真透明背景 / 需 Claude 全自动批量时使用；这条通道 Claude 可全自动跑。
+- **必须复用现有资产**：`ai-art-research/prompts/*.txt`、`tools/image_gen.py` 的 `STYLE_SEED_EN` 风格种子、`生成结果/` 命名规则（`<时间戳>_gpt-image-2_<模式>.png` + 同名 `.meta.json`，新增 `backend: codex|apiyi` 字段）。
+- codex 不在默认 PATH，执行路径：`~/.codex/packages/standalone/current/bin/codex.exe`（命令模板：`codex exec --enable image_generation --dangerously-bypass-approvals-and-sandbox -C ai-art-research -o <lastmsg> "<prompt>"`，prompt 内须明示“用内置 image_gen 工具、不要写脚本/不要用 API key”）。
+- ⚠️ `ai-art-research/` 被项目 `.ignore` 屏蔽，不进 ripgrep/Glob 检索；操作需用显式路径。
@@ -0,0 +1,252 @@
+# codex 生图工作规范（用 ChatGPT Plus 订阅额度）
+
+> 让日常 AI 生图走 **Codex CLI 内置 `image_gen` 工具**，消耗 ChatGPT Plus 会员的订阅额度，**不按张计费**。
+> 创建时间：2026-06-20 · 配套现有 [`tools/image_gen.py`](./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. 前置自检（本机已实测通过 ✅）
+
+```bash
+# 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 里调用**（推荐先赋变量，命令更短）：
+
+```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）
+
+```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**：
+1. `--enable image_generation` —— **关键**：`codex exec` 默认不启用图像生成 feature，会话里不会暴露内置 `image_gen` 工具（agent 会报"当前会话没有 image_gen 工具"）。`codex features list` 的 `stable=true` 只代表"受支持"，不代表"已启用"；必须用此 flag，或在 `~/.codex/config.toml` 的 `[features]` 写 `image_generation = true` 才真正启用。
+2. `--dangerously-bypass-approvals-and-sandbox` —— 不加会被默认沙箱断网（`Could not resolve host: api.openai.com`）。
+3. `-C/--cd` 指向 `ai-art-research` —— 让 Codex 能直接读 `prompts/`、`参考图/`，也便于落盘。
+4. `--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`](./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`](./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 做以下收尾**（用户也可自己按规则手动落盘）：
+
+1. **取路径**：读 `-o` 指定的 `ai-art-research/.codex_lastmsg.txt`，提取生成图完整路径；取不到就 glob `~/.codex/generated_images/` 下最新 `ig_*.png`。
+2. **落盘**：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`）
+   - 子目录：`文生图` / `风格校准` / `双参考融合/<分类>` / `测试`
+3. **写 `.meta.json`**（同名），在原 schema 上**新增 `backend` 字段**标记来源：
+
+```json
+{
+  "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 可全自动跑）：
+1. Codex 报 **429 / 限额**提示（Plus 约 40–50 张/3h 窗口）。
+2. 需要**真·透明背景**（gpt-image-2 不支持）。
+3. 需要 **Claude 全自动批量**（不想手动跑终端）与 100% 确定性输出。
+
+切法：直接用现有脚本（`backend` 标 `apiyi`）：
+
+```bash
+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`](./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`](../CLAUDE.md) 的「## AI 生图」一节指向本文件：默认走 codex 通道（用户终端执行 + Claude 收尾），apiyi 兜底。
+- `ai-art-research/` 被项目 `.ignore` 屏蔽，不进 ripgrep/Glob 检索；操作需用显式路径（本文件所有命令均用绝对/相对显式路径）。