---

name: figforge-gen description: Use when user requests image generation, image editing, text-to-image (文生图), image editing (改图), 修改图片, 编辑图片, "使用 gpt-image-2", or invokes /figforge-gen. Calls gpt-image-2 via CLIProxyAPI. argument-hint: <自然语言需求> allowed-tools: [Bash, Read]

figforge-gen

调用 CLIProxyAPI 上的 gpt-image-2 完成文生图与改图。支持自动触发与 /figforge-gen ... 手动调用。

资源

• references/fields.md — 字段定义、自然语言映射、LLM 推断规则、timeout 规则(权威单一来源)
• references/api-config.md — API 配置优先级、原子性约束、预检流程
• scripts/figforge_gen.py — 接口调用脚本
• scripts/choose_python.sh — 探测可用 Python 3.11+

手动调用时需求即 $ARGUMENTS:

/figforge-gen 生成一张透明背景的猫咪头像,1024x1024,png
/figforge-gen 把 ./input.png 改成水彩风,保留主体,输出 webp

任务分类

• 文生图:生成图片、文生图、画一张图、用 gpt-image-2 生成
• 改图:修改图片、编辑图片、改图、把这张图改成...

同时出现图片来源(本地路径/URL/data URL)与修改意图 → 按改图处理。

必填字段与追问

缺字段时先问,不执行:

| 任务 | 缺什么 | 追问话术 | |------|--------|----------| | 文生图 | prompt | 请补充图片提示词,例如你想生成什么画面。 | | 改图 | 图片来源 | 请提供要编辑的图片来源:1)本地路径 2)图片 URL / data URL | | 改图 | prompt | 请补充修改要求,例如你想把图片改成什么效果。 |

字段提取

优先级:用户明确字段值 > 自然语言明确要求 > LLM 保守推断 > 脚本默认值。

完整映射表与推断规则见 references/fields.md。要点:

• 用途明显时(头像/壁纸/海报/banner/logo...)可保守推断 size、quality、background、output_format、n、input_fidelity
• 信心不足 → 省略,使用脚本默认值,不要为可选字段反复追问
• model、moderation、partial_images、output_compression 默认不推断
• 推断出的字段只作为接口参数,不要从原始 prompt 中删除对应语义

直接从终端调用 scripts/figforge_gen.py 时,脚本不会自己推断;只有通过本 skill 由 LLM 整理参数时才发生这些推断。

执行步骤

1. 确定 task_cwd 与输出目录

task_cwd = 用户当前打开的项目/工作区目录。不是 skill 安装目录、脚本目录、$CODEX_HOME、~/.codex/generated_images/。

默认输出目录 <task_cwd>/figforge-gen/。用户指定其他目录时,相对路径按 task_cwd 解析。

--out-dir 是本地保存参数,不进入 API payload。

2. 探测 Python

python_cmd=$(bash "<skill-dir>/scripts/choose_python.sh") || { echo "未找到可用 Python 3.11+"; exit 1; }

$python_cmd 可能含多个词(如 uv run --python 3.12 python)。在 zsh -lc 中使用时,先用 python_argv=(${=python_cmd}) 拆成 argv,再用 "${python_argv[@]}" 调用。

3. API 配置预检(每次会话首次调用前)

zsh -lc 'source ~/.zshrc >/dev/null 2>&1 || true; cd "<task-cwd>" || exit 1; python_cmd=$(bash "<skill-dir>/scripts/choose_python.sh") || { echo "未找到可用 Python 3.11+"; exit 1; }; python_argv=(${=python_cmd}); "${python_argv[@]}" "<skill-dir>/scripts/figforge_gen.py" --show-config'

只检查输出 JSON 的 ok、source、base_url、model、token_present。不要打印、读取、复制或拼接完整 token。

预检失败处理与配置原子性约束见 references/api-config.md。

4. 计算 timeout

按 references/fields.md 的 timeout 规则,根据 size × n 决定本次 Bash 工具调用的 timeout 参数:

• 单张基准:总像素 ≥ 8,000,000(4k 级) → 900000(15 分钟);其余 / auto / 无法解析 → 600000(10 分钟)
• 实际 timeout = 单张基准 × n(脚本对 n 串行调用,必须按张累加)
• 超过 Bash 工具上限时取上限即可

5. 调用脚本

文生图:

zsh -lc 'source ~/.zshrc >/dev/null 2>&1 || true; cd "<task-cwd>" || exit 1; python_cmd=$(bash "<skill-dir>/scripts/choose_python.sh") || { echo "未找到可用 Python 3.11+"; exit 1; }; python_argv=(${=python_cmd}); "${python_argv[@]}" "<skill-dir>/scripts/figforge_gen.py" --mode generate --prompt "..." --out-dir "<task-cwd>/figforge-gen"'

改图:加 --mode edit --image "..."(可选 --mask)。

按已提取字段附加可选参数: --size --quality --background --output-format --n --moderation --output-compression --partial-images --input-fidelity --no-stream --model --api-base --api-key --api-key-env --config

--no-stream 仅在用户明确要求非流式或 Responses 端点不可用排查时使用。

结果输出

脚本成功返回 {"ok": true, "paths": [...], "used_params": {...}},向用户输出:

图片已生成, 图片路径: <路径>
实际使用的关键参数: model=..., size=..., quality=..., output_format=..., n=..., stream=..., out_dir=...

多张图片列出全部路径。

脚本失败返回 {"ok": false, "error": "..."},向用户输出:

生成失败: <简短错误原因>

注意事项

• 缺必填字段不要猜测
• 不要为可选字段做冗长说明
• 改图支持本地路径、URL、data URL
• 不要为接口添加未定义的自定义字段
• 调用完成后优先返回结果,不要输出多余解释