generate-image

name	generate-image
description	调用 ZenMux 中转平台的 openai/gpt-image-2 模型生成 AI 图片（文生图）。当用户要求"生成图片/画一张图/AI画图/做张图/文生图/出图"，或需要把文字描述、提示词变成图片时，必须使用本技能，即使用户没明说"用 AI 生成"。流程为：设计提示词（确定主题/内容/主体元素/尺寸/清晰度，缺失项先用 AskUserQuestion 询问）→ 把完整提示词与参数展示给用户确认 → 确认后调用 scripts/generate_image.py 生成，保存到 AI_output 且文件名与内容相符 → 用视觉模型检查主体是否清晰无遮挡、文字是否完整 → 有问题告知用户，由用户决定是否重新生成。

生成 AI 图片（ZenMux · openai/gpt-image-2）

用 ZenMux 中转平台的 gpt-image-2 模型把文字描述生成成图片，保存到 AI_output/，并做视觉质检。

关键约束（硬性）

1. 模型固定 gpt-image-2，端点 POST https://zenmux.ai/api/v1/images/generations，认证 Authorization: Bearer $ZENMUX_API_KEY，base_url https://zenmux.ai/api/v1。
2. API Key：从环境变量 ZENMUX_API_KEY 读取。若环境无此变量，先向用户索取，绝不硬编码 key。
3. 生成一律走脚本 ${CLAUDE_SKILL_DIR}/scripts/generate_image.py（参数化、含尺寸校验、JSON 输出）。主程序不自己拼 HTTP 请求。
4. 返回是 b64_json：gpt-image-2 只返回 base64 图片、不返回 url，脚本自动解码落盘。
5. 生成必须经用户确认：提示词与参数先展示给用户，确认后才调脚本。

工作流程

1. 明确需求（缺失项用 AskUserQuestion 询问）

需确定：

• 内容 / 主题 / 主体元素：画什么、主体、风格、构图、色调、是否含文字。
• 尺寸 size：默认 1024x1024。常用 1024x1024(方) / 1536x1024(横) / 1024x1536(竖) / auto；也支持任意 WIDTHxHEIGHT（宽高均被 16 整除、比例 1:3~3:1）。
• 清晰度 quality：low/medium/high/auto，默认 auto；要高清选 high。
• 输出格式 / 背景：png(默认)/jpeg/webp；需透明背景选 png 或 webp 并设 --background transparent。 用户未明确的，用 AskUserQuestion 一次性问清（尺寸、清晰度、是否透明背景），不要自行臆断。

2. 构建并展示提示词

• 写出完整、具体、画面感强的提示词（主体 + 风格 + 构图 + 色调 + 细节）。AI 生图对"含文字"的指令要尽量给出确切的文字内容与位置。
• 把提示词全文 + size/quality/格式 列给用户看，请其确认或修改后再生成。

3. 用户确认后，调用脚本生成

python ${CLAUDE_SKILL_DIR}/scripts/generate_image.py \
  --prompt "<提示词>" \
  --size 1024x1024 --quality high \
  --output AI_output/<与内容相符的文件名>.png

• 文件名必须与内容相符（如 暑假计划海报.png、弹簧振子示意图.png），放 AI_output/，路径用正斜杠；从项目根目录运行。
• 脚本输出 JSON：{"ok":true,"path":...,"size":...,"usage":...} 或 {"ok":false,"error":...,"http_code":...,"retryable":...}，据此判断成败。

4. 视觉质检（生成后必做）

用 Read 读取刚生成的图片（Read 支持图片并做视觉理解），重点检查：

• 主体元素是否清晰，有无遮挡 / 变形 / 残缺；
• 文字是否完整 —— AI 生图常出现"文字生成一半、缺笔画、乱码"，务必逐字核对图中文字；
• 整体是否符合提示词意图。

5. 反馈与重生成决策

• 质检若发现问题（主体糊 / 遮挡 / 文字残缺 / 偏离提示词），如实告知用户具体问题，由用户决定是否重新生成（不擅自重生成）。
• 重生成时可微调提示词或参数（如加强文字指令、换 size/quality）。

size / quality 速查

• size：1024x1024(方) / 1536x1024(横) / 1024x1536(竖) / auto；任意 WxH 需 W、H 均被 16 整除、比例 1:3~3:1，最大 3840x2160（2560x1440 以上为实验性）。
• quality：low(快/省) / medium / high(最清晰) / auto。

常见错误

• HTTP 401/403：API Key 无效 / 欠费 / 配额用尽 → 请用户检查 Key 与余额。
• HTTP 422/400 报 size：尺寸不合规 → 改用标准尺寸或确保被 16 整除。
• HTTP 413：prompt 过长（>32000 字符）→ 精简提示词。
• HTTP 429：限流 → 稍后重试。
• 文字残缺 / 主体异常：调提示词重生成（需用户同意）。

参考资料

• ${CLAUDE_SKILL_DIR}/scripts/generate_image.py —— 生成脚本（参数见 --help）。
• ${CLAUDE_SKILL_DIR}/references/api-reference.md —— 完整 API 参数、size 规则、返回结构、错误码、计费。