justcyl image-gen-kapibala
通过 Kapibala 提供的 OpenAI 兼容 Images API 生成/编辑位图图片。本 skill 只有 CLI 一条路径（没有内置图片生成工具可用），默认模型 gpt-image-2。
前置条件
~/.zshrc.local 中需要：
export KAPIBALA_API_KEY="..."
export KAPIBALA_BASE_URL="https://kapibala.asia/v1" # 可省略，脚本内置此默认值
Preflight 检查：
[ -n "$KAPIBALA_API_KEY" ] && echo ok || echo "缺少 KAPIBALA_API_KEY，请检查 ~/.zshrc.local 是否已 source"
若缺失，提示用户在 ~/.zshrc.local 添加上面的 export 行并重开终端 / source ~/.zshrc.local，不要替用户猜测或编造 key。
脚本用 uv run 执行，依赖（openai、pillow）已在脚本头部的 # /// script 内联声明，无需提前安装。
When to use
- 生成新图片（概念图、产品图、封面、hero image）
- 基于参考图生成新图（风格/构图/氛围参考）
- 编辑已有图片（局部重绘、背景替换、去除元素、透明背景抠图）
- 一次产出多张候选图供挑选
When not to use
- 已有可编辑的 SVG/矢量图标体系，应直接编辑源文件而非生成位图
- 简单形状、图表、示意图更适合用 SVG/HTML/CSS/canvas 直接实现
- 用户明确要求确定性的代码原生输出
Decision tree
先判断两件独立的事：
- 意图：新生成，还是编辑已有图片？
- 用户提供图片仅作风格/构图/主体参考 → 视为
generate - 用户想在保留部分内容的前提下修改已有图片 → 视为
edit - 未提供图片 → 视为
generate
- 用户提供图片仅作风格/构图/主体参考 → 视为
- 执行策略：单张，还是多张/批量？
- 多个不同的资产用多次独立的
generate调用或generate-batch的多个 job，不要用--n代替——--n只用于同一个 prompt 出多个变体
- 多个不同的资产用多次独立的
Workflow
- 判断 generate / edit，判断单张 / 批量
- 收集输入：prompt、精确文字（逐字）、约束/禁止项、参考图或编辑目标图路径
- 判断输出是预览用还是要落地到当前项目；落地时确定目标路径
- 按下方"结构化 prompt 模板"整理 prompt；用户 prompt 已经很具体时只做规范化，不要额外加内容
- 调用脚本（见"用法"）
- 检查输出：主体、风格、构图、文字准确性、约束是否满足
- 需要修正时每次只改一处，重新生成并复查
- 汇报：最终保存路径、最终使用的 prompt/prompt 集合、使用的模型和关键参数（size/quality）
用法
生成：
uv run <skill-dir>/scripts/generate_image.py generate \
--prompt "a minimal hero image of a ceramic coffee mug, soft studio lighting" \
--out path/to/output.png \
[--model gpt-image-2] [--size 1536x1024] [--quality high] [--n 1]
编辑（--image 可重复传入多张）：
uv run <skill-dir>/scripts/generate_image.py edit \
--prompt "change only the background to a warm sunset gradient; keep the product unchanged" \
--image path/to/source.png \
--out path/to/edited.png
批量（JSONL，每行一个 job，字符串或 {"prompt": "...", "out": "...", ...} 对象均可）：
uv run <skill-dir>/scripts/generate_image.py generate-batch \
--input jobs.jsonl \
--out-dir output/imagegen/batch/
先用 --dry-run 预览最终请求体和输出路径，确认无误再正式执行。
--out 已存在文件默认不覆盖，需要覆盖用 --force；需要额外一份缩略图用 --downscale-max-dim <px>。
参数速查
| 参数 | 说明 |
|---|---|
--model |
默认 gpt-image-2 |
--size |
auto 或 WIDTHxHEIGHT；gpt-image-2 见下方尺寸规则 |
--quality |
low/medium/high/auto；草稿用 low，终稿用 high/auto |
--background |
transparent/opaque/auto；gpt-image-2 不支持 transparent |
--n |
同一 prompt 的变体数（1-10） |
--out / --out-dir |
单文件路径 / 批量输出目录 |
--input-fidelity |
仅 edit 支持，gpt-image-2 不支持此参数（固定高保真） |
gpt-image-2 尺寸规则
size 为 auto 或满足以下全部约束的 WIDTHxHEIGHT：
- 最长边
<= 3840px - 宽高都是
16px的倍数 - 长边:短边
<= 3:1 - 总像素在
655,360到8,294,400之间
常用尺寸：1024x1024（方形快稿）、1536x1024/1024x1536（横/竖版）、2048x2048（2K 方形）、3840x2160/2160x3840（4K 横/竖）。
结构化 prompt 模板
Use case: <场景，如 product-mockup / ui-mockup / illustration-story>
Primary request: <用户核心诉求>
Scene/background: <环境/背景>
Subject: <主体>
Style/medium: <照片/插画/3D 等>
Composition/framing: <构图>
Lighting/mood: <光线与氛围>
Color palette: <配色>
Materials/textures: <材质>
Text (verbatim): "<需要出现的精确文字>"
Constraints: <必须保留的内容>
Avoid: <禁止出现的内容>
只保留有帮助的字段，不要为了凑格式硬填。脚本内置 --use-case/--scene/--subject/... 等参数会自动拼成上述结构（默认开启，--no-augment 关闭）。
编辑任务务必显式列出不变量，例如 "change only the background; keep the product and its edges unchanged"，每轮迭代都重复一遍以减少漂移。
Troubleshooting
- 报错缺少
KAPIBALA_API_KEY：检查~/.zshrc.local是否配置并已source，不要代替用户猜测 key - 429 / 超时：
generate-batch内置指数退避重试（--max-attempts，默认 3 次）；单张generate/edit失败需手动重试 - 输出已存在报错：加
--force覆盖，或换路径