From 830128d812fd68f09f16e08032542378f977359c Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Sun, 21 Jun 2026 23:28:59 +0800 Subject: [PATCH] =?UTF-8?q?docs(ai-art):=20codex=E7=94=9F=E5=9B=BE?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E8=A7=84=E8=8C=83=E4=B8=8E=E5=8F=8C=E9=80=9A?= =?UTF-8?q?=E9=81=93=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 5 + CLAUDE.md | 10 ++ ai-art-research/codex生图工作规范.md | 252 +++++++++++++++++++++++++++ 3 files changed, 267 insertions(+) create mode 100644 ai-art-research/codex生图工作规范.md diff --git a/.gitignore b/.gitignore index d3a2653..6bf079c 100644 --- a/.gitignore +++ b/.gitignore @@ -125,3 +125,8 @@ ai-art-research/.env *.swo *~ temp.txt + +# ============================== +# AI 生图 — codex 运行残留（codex exec -o 输出，每次覆盖，不入库） +# ============================== +ai-art-research/.codex_lastmsg.txt diff --git a/CLAUDE.md b/CLAUDE.md index cc6fad3..6677683 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,3 +30,13 @@ - 分支: `develop/` - 提交: `(): <中文描述>`，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 ""`，prompt 内须明示“用内置 image_gen 工具、不要写脚本/不要用 API key”）。 +- ⚠️ `ai-art-research/` 被项目 `.ignore` 屏蔽，不进 ripgrep/Glob 检索；操作需用显式路径。 diff --git a/ai-art-research/codex生图工作规范.md b/ai-art-research/codex生图工作规范.md new file mode 100644 index 0000000..d977a18 --- /dev/null +++ b/ai-art-research/codex生图工作规范.md @@ -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 -o ""`（**用户终端执行**） + +--- + +## 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 模板里的 ``： + +``` +用 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": "" +} +``` + +融合场景的 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//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 检索；操作需用显式路径（本文件所有命令均用绝对/相对显式路径）。