---
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` 等环境变量 |
| `Remote end closed connection` / 403 含 `cf-mitigated: challenge` | 代理出口 IP 被 Cloudflare 风控（凭证无辜，`check` 仍正常）。请用户在代理 App 切换节点（优先美/日原生 IP）后重试；重试前勿反复硬撞 |
| native 通道 404/失效 | 内部接口无稳定性契约；切 `--backend responses` 试试，并在交付时说明 |

## 安全边界

- 凭证只读 `auth.json`，刷新写回仅限该文件；绝不打印 token、不把凭证带进生成参数。
- 输出只落在用户指定目录或当前目录 `fig/`；覆盖已存在文件必须显式 `--force`。
- 生成内容遵守平台内容政策；收到拒绝时如实转达，不换措辞绕过。
- 每张图都消耗 ChatGPT 订阅额度：不擅自生成变体对比、不批量跑图，多张先停点确认。