le-gpt-image v1.0：无 Key GPT Image 生图工坊——复用本机 Codex ChatGPT 登录直连内部图像通道（token 自动刷新/原子写回），generate+edit+check 零依赖 CLI + 提示词手艺参考；协议参考 codex-imagegen-cli(Apache-2.0)、方法论参考 GPT-Image2-Skill(MIT)；本机实测生图 38.8s、改图 45.4s 通过

2026-10-06 21:56:37 +08:00
parent 3af717a76d
commit d430d3847d
5 changed files with 1117 additions and 7 deletions
@@ -0,0 +1,103 @@
+---
+name: le-gpt-image
+description: >
+  用 GPT Image 生成或编辑图片：海报、封面、插画、UI mockup、信息图配图、文章插图、表情包、风格迁移改图。
+  复用本机 Codex CLI 的 ChatGPT 登录凭证（~/.codex/auth.json），不需要 OpenAI API Key，
+  走 Codex 内部图像通道，消耗的是 ChatGPT 订阅额度。
+  当用户说「画一张图」「生成一张…的图」「做张海报/封面/头图」「帮文章配图」「把这张图的背景换成…」
+  「按这张图的风格重画」「GPT Image 生图」时使用；拿到图像需求但没指明工具、而本机已登录 Codex 时也触发。
+  不要用于：视频生成、需要 API 计费与发票的正式生产管线、要求 gpt-image-2.5-flare/sunburst 专属能力的任务
+  （那是 API 通道专属模型，无 Key 走不了）、未登录 Codex 的机器。
+---
+
+# le-gpt-image
+
+用 GPT Image 生图与改图，凭证复用本机 Codex 登录，全程无 API Key。额度来自 ChatGPT 订阅——把每次生成当作在花用户的订阅用量，高成本操作先确认。
+
+## 核心原则
+
+- **无 Key 通道。** 凭证只读 `~/.codex/auth.json`（ChatGPT 登录态），token 临过期由脚本自动刷新并原子写回；任何情况下不打印、不外发 token。
+- **执行只走脚本。** 生图一律调 `scripts/gpt_image.py`，不现场写 HTTP/SDK 代码；判断放参考（提示词手艺读 [references/prompt-craft.md](references/prompt-craft.md)），调用走 CLI。
+- **尺寸是建议值。** 实测 Codex 通道不严格遵循请求尺寸（请求 1024x1024 可能返回 1374x1145）；要精确画布时在交付说明里报告实际尺寸，必要时用改图/裁剪兜底。
+- **失败即停。** 401 刷新失败、配额不足、内容策略拒绝：如实报告并停，不换参数偷跑重试。
+
+## 能力边界
+
+| 能力 | 说明 |
+|---|---|
+| 文生图 | `generate`，prompt + 尺寸 + 质量 |
+| 改图 | `edit`，1–5 张参考图 + 指令；多图可做融合/参考绘制 |
+| 风格迁移 | `edit --style-image`：内容取 `--image`，画风取 `--style-image` |
+| 通道 | native（默认，GPT Image 直连，即 Codex 内部同款）；responses（备用，走推理模型强制图像工具） |
+| 质量 | `auto / low / medium / high`（无 xhigh/max——那是 API 通道档位） |
+| 背景 | `auto / opaque`；**不支持透明背景**（当前通道限制） |
+| 张数 | `--n` 逐张请求，输出文件名加 `-1..-n` 后缀 |
+
+单张耗时实测 40–60 秒；脚本默认超时 300 秒，429 限流自动退避重试（最多 4 次）。
+
+## 工作流
+
+1. **接单**：明确用途（海报/封面/插画/配图…）、主体、需出现的文字（逐字）、比例倾向。据 [references/prompt-craft.md](references/prompt-craft.md) 对应分节起草英文 prompt（图像模型对英文 prompt 更稳；图内文字保持用户原文）。
+2. **停点确认**（回合终止契约）：出现以下任一情况，展示「最终 prompt + 尺寸/质量/张数 + 输出路径」后**立即结束回合**，不得再发起任何工具调用；用户确认或给修改意见后再继续——
+   - 实质改写或补写了用户给的描述（用户只说「画只猫」而你扩写了一整段场景）；
+   - `--n > 1` 或 4k 尺寸（成倍消耗额度）；
+   - 要编辑不可再生的原图（用户仅有的一份照片/扫描件）——先确认输出另存、不覆盖。
+   用户明确说「直接生成」、或需求已完整（明确描述 + 默认参数 + 单张）时跳过停点，直接生成。
+3. **生成与交付**：调 CLI，stdout 末行即输出路径。交付时报告：路径 + 实际尺寸 + 关键参数，另附一条可选的改进建议（换质量档/调 prompt），不自动追加生成变体。
+
+## CLI 速查
+
+```bash
+SKILL/scripts/gpt_image.py check                          # 看凭证：模式/套餐/token 余量
+SKILL/scripts/gpt_image.py generate \
+  --prompt "A minimalist poster for a tea shop, warm beige palette, the text \"好茶慢慢喝\" centered" \
+  --size portrait --quality high --out poster.png
+SKILL/scripts/gpt_image.py edit \
+  --image photo.png --prompt "Change the background to snowy mountains, keep the person unchanged" \
+  --out photo-new.png
+SKILL/scripts/gpt_image.py edit \
+  --image content.png --style-image ink.png --out styled.png      # 风格迁移
+```
+
+| 参数 | 取值 | 说明 |
+|---|---|---|
+| `--prompt` / `--prompt-file` | 文本 / 路径 | 生图或改图指令（edit 配 `--style-image` 时可选） |
+| `--out` | 路径 | 缺省 `fig/YYYYMMDD-HHMMSS-<slug>.png`；存在须加 `--force` 才覆盖 |
+| `--size` | 见下表 | 缺省 `auto` |
+| `--quality` | `auto/low/medium/high` | 草稿 low，成品 high |
+| `--n` | 整数 | 逐张请求，文件名加后缀 |
+| `--backend` | `native/responses` | native 默认；responses 为备用通道 |
+| `--image` | 路径，可重复 | edit 输入图，1–5 张（Pillow 在位时自动压至最长边 1536 的 WebP） |
+| `--style-image` | 路径 | edit 的风格参考图 |
+| `--dry-run` | 开关 | 只打印请求（凭证打码）不联网，排障首选 |
+
+### 尺寸速查
+
+| 别名 | 像素 | 适用 |
+|---|---|---|
+| `1k` / `square` | 1024x1024 | 默认方图、社交媒体 |
+| `portrait` | 1024x1536 | 海报、封面、手机壁纸 |
+| `landscape` | 1536x1024 | 文章头图、横幅 |
+| `wide` | 1536x640 | 超宽 banner |
+| `tall` | 1024x2048 | 长图、竖版故事 |
+| `2k` / `4k` | 2048x2048 / 3840x2160 | 印刷、大屏（高额度，先停点确认） |
+
+也接受 `WIDTHxHEIGHT`（须 16 倍数、最长边 ≤3840、宽高比 1:3–3:1）。**记住服务端可能自行调整尺寸**，交付时以实际输出为准。
+
+## 故障排查
+
+| 现象 | 处置 |
+|---|---|
+| 未找到凭证文件 / auth_mode 不是 chatgpt | 指引用户在本机跑 `codex login` 选 ChatGPT 登录；Codex 需文件凭证存储（config.toml `cli_auth_credentials_store = "file"`） |
+| 刷新令牌失败（HTTP 4xx） | refresh_token 已失效，指引用户重新 `codex login`；不要反复重试 |
+| HTTP 429 | 脚本自动退避重试；重试仍失败则告知用户订阅图像额度已到限，建议稍后再试或降 quality/尺寸 |
+| 尺寸不符警告 | 属正常（服务端建议值行为），按实际尺寸交付 |
+| 网络请求失败 | 检查代理（chatgpt.com 需可达）；脚本遵循 `https_proxy` 等环境变量 |
+| native 通道 404/失效 | 内部接口无稳定性契约；切 `--backend responses` 试试，并在交付时说明 |
+
+## 安全边界
+
+- 凭证只读 `auth.json`，刷新写回仅限该文件；绝不打印 token、不把凭证带进生成参数。
+- 输出只落在用户指定目录或当前目录 `fig/`；覆盖已存在文件必须显式 `--force`。
+- 生成内容遵守平台内容政策；收到拒绝时如实转达，不换措辞绕过。
+- 每张图都消耗 ChatGPT 订阅额度：不擅自生成变体对比、不批量跑图，多张先停点确认。