企业官网建设流程全解析

imagegen Skill 的 CLI 回退模式完全指南：scripts/image_gen.py 的生成、编辑与批量工作流

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

导读

本文是 Codex skills 仓库中 imagegen 技能（skills/.system/imagegen）的CLI 回退模式技术参考，讲解其核心脚本 scripts/image_gen.py 的三种子命令（generate、edit、generate-batch）的完整用法、全部参数、默认值、校验规则与实战配方。读完本文，你将掌握如何在显式选择 CLI 路径后，用一条条可复制的命令完成单张生成、图片编辑（含掩码与输入保真度）、以及基于 JSONL 文件的并发批量出图，并理解脚本内部的参数校验、提示词增强、输出路径与重试机制等底层实现。

使用前提：CLI 回退模式仅在用户显式要求使用scripts/image_gen.py替代内置image_gen工具时才启用。内置image_gen工具是默认路径且不需要OPENAI_API_KEY；CLI 回退模式的真实 API 调用则必须拥有网络访问能力与OPENAI_API_KEY，只有--dry-run不需要。

CLI 是什么：三种子命令与定位

根据 cli.md 的说明，scripts/image_gen.py是fallback CLI 模式（回退命令行模式）的专用脚本，提供三个子命令：

• generate：根据提示词生成一张新图片
• edit：编辑一张或多张已有图片
• generate-batch：从一个 JSONL 文件读取多个生成任务并批量执行

从源码看，脚本入口在 image_gen.py 的main()，使用argparse的subparsers注册三个子命令，且command参数为必选。默认模型为gpt-image-1.5（源码常量DEFAULT_MODEL，见 image_gen.py），并只接受gpt-image-*前缀的模型（GPT_IMAGE_MODEL_PREFIX，校验逻辑见 _validate_model）。脚本顶部的模块文档字符串也明确：它默认采用结构化提示词增强工作流，专用于 GPT Image 模型。

快速开始：环境变量与依赖安装

设置稳定的 CLI 路径

CLI 脚本位于$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py，默认CODEX_HOME为~/.codex。在任意仓库中都建议先固化路径变量：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}" export IMAGE_GEN="$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py"

安装依赖

按 SKILL.md 的依赖说明，本仓库优先使用uv管理依赖：

# 必需：OpenAI Python SDK（真实 API 调用） uv pip install openai # 可选：仅当需要降采样（downscale）时才需要 uv pip install pillow

在 uv 托管环境中，uv pip install ...是首选方式；若在仓库外使用已安装的技能，则用该环境的包管理器安装依赖。源码_dependency_hint()（image_gen.py）会在缺少包时给出同样的安装提示：先激活仓库所选环境（本地虚拟环境用source .venv/bin/activate），若项目声明了依赖则优先走项目的uv sync流程。

密钥与网络要求

_ensure_api_key()（image_gen.py）逻辑：真实调用前必须设置OPENAI_API_KEY环境变量，否则直接报错退出；dry-run 模式则仅给出警告继续执行。网络/沙箱相关注意事项见 codex-network.md：Codex 许多配置下默认禁止出网并要求审批，需要网络访问与审批策略同时配合（例如~/.codex/config.toml中设置approval_policy = "on-request"、sandbox_mode = "workspace-write"且[sandbox_workspace_write] network_access = true）。注意--ask-for-approval never只能抑制审批弹窗，并不能自行开启网络。

单张生成：从 Dry-run 到真实调用

Dry-run（无网络、无 API 密钥）

--dry-run不发起真实 API 调用，不要求openai包，也不要求网络：

python "$IMAGE_GEN" generate \ --prompt "Test" \ --out output/imagegen/test.png \ --dry-run

dry-run 会打印将要发送的 API 载荷（JSON）以及计算好的输出路径。源码中该逻辑位于 _print_request 与 _generate，端点标记为/v1/images/generations，同时会展示outputs与（若指定降采样）outputs_downscaled路径列表。仓库内的最终产物应放在output/imagegen/下。

真实生成

python "$IMAGE_GEN" generate \ --prompt "A cozy alpine cabin at dawn" \ --size 1024x1024 \ --out output/imagegen/alpine-cabin.png

源码中真实路径走client.images.generate(**payload)（image_gen.py），并在写入前先输出提示“Calling Image API (generation). This can take up to a couple of minutes.”（生成可能耗时数分钟）。返回结果从result.data[].b64_json解码为字节后写盘（见 _decode_write_and_downscale）。

编辑已有图片：edit 子命令

python "$IMAGE_GEN" edit \ --image input.png \ --prompt "Replace only the background with a warm sunset" \ --out output/imagegen/sunset-edit.png

edit调用 OpenAI 编辑端点/v1/images/edits（即client.images.edit(...)，见 image-api.md）。源码 _edit 中有几个关键实现细节：

• --image为action="append"参数，可重复传入多个图片，顺序有意义（多图编辑时需在提示词中按索引与角色描述每张图）。
• 文件校验_check_image_paths（image_gen.py）会检查文件存在性，并警告超过 50MB 的输入图。
• 若传--mask，脚本会检查掩码文件存在性，并提示“Mask should be a PNG with an alpha channel”（PNG 掩码为最佳实践），掩码同样受 50MB 上限约束。
• 编辑提示词中应重复不变式（如change only the background; keep the subject unchanged），以降低模型漂移（drift）。

质量、输入保真度与掩码（CLI 专属参数）

以下参数是显式 CLI 控制项，并非内置image_gen工具的参数：

python "$IMAGE_GEN" edit \ --image input.png \ --prompt "Change only the background" \ --quality high \ --input-fidelity high \ --out output/imagegen/background-edit.png

源码对应的白名单常量（image_gen.py）为ALLOWED_QUALITIES = {"low","medium","high","auto"}与ALLOWED_INPUT_FIDELITIES = {"low","high",None}，非法值会经_validate_quality/_validate_input_fidelity直接报错。注意 image-api.md 的模型差异说明：gpt-image-1与gpt-image-1-mini会保留全部输入图，但第一张图的纹理与细节最丰富；gpt-image-1.5以更高保真度保留前 5 张输入图。此外，掩码由提示词引导，精确形状不保证；高input_fidelity会显著增加输入 token 用量。

输出处理：路径、覆盖与降采样

• 临时 JSONL 输入与草稿文件放在tmp/imagegen/；最终产物放在output/imagegen/。
• 重跑会因目标文件已存在而失败，除非传入--force。源码在_decode_write_and_downscale中执行out_path.exists() and not force检查，命中即报 “Output already exists ... (use --force to overwrite)”。
• --out-dir会改变一次性命名规则：输出变为image_1.<ext>、image_2.<ext>……（见 _build_output_paths）。
• 降采样副本使用默认后缀-web，可用--downscale-suffix覆盖；若后缀不以-或_开头会自动补-（见_derive_downscale_path，image_gen.py）。
• 默认一次性输出路径为output/imagegen/output.png（源码常量DEFAULT_OUTPUT_PATH）。

降采样实现细节：_downscale_image_bytes（image_gen.py）依赖 Pillow，按--downscale-max-dim计算等比缩放（min(1.0, max_dim / max(w, h))），使用 LANCZOS 重采样；输出为 JPEG 时若原图带透明通道（RGBA/LA），会先以白色背景合成再转 RGB。

常见配方（Common Recipes）

配方一：带增强字段的生成

python "$IMAGE_GEN" generate \ --prompt "A minimal hero image of a ceramic coffee mug" \ --use-case "product-mockup" \ --style "clean product photography" \ --composition "wide product shot with usable negative space for page copy" \ --constraints "no logos, no text" \ --out output/imagegen/mug-hero.png

提示词增强是脚本的核心特性之一：--augment（默认开启，可用--no-augment关闭）会把--use-case、--scene、--subject、--style、--composition、--lighting、--palette、--materials、--text、--constraints、--negative等字段组织成结构化分节文本。实现见 _augment_prompt_fields：依次拼接Use case:、Primary request:、Scene/background:、Subject:、Style/medium:、Composition/framing:、Lighting/mood:、Color palette:、Materials/textures:、Text (verbatim): "..."、Constraints:、Avoid:各标签行，仅有值的字段才会出现。

配方二：生成 + 网页快速加载的降采样副本

python "$IMAGE_GEN" generate \ --prompt "A cozy alpine cabin at dawn" \ --size 1024x1024 \ --downscale-max-dim 1024 \ --out output/imagegen/alpine-cabin.png

配方三：JSONL 并发批量生成

mkdir -p tmp/imagegen output/imagegen/batch cat > tmp/imagegen/prompts.jsonl << 'EOF' {"prompt":"Cavernous hangar interior with a compact shuttle parked near the center","use_case":"stylized-concept","composition":"wide-angle, low-angle","lighting":"volumetric light rays through drifting fog","constraints":"no logos or trademarks; no watermark","size":"1536x1024"} {"prompt":"Gray wolf in profile in a snowy forest","use_case":"photorealistic-natural","composition":"eye-level","constraints":"no logos or trademarks; no watermark","size":"1024x1024"} EOF python "$IMAGE_GEN" generate-batch \ --input tmp/imagegen/prompts.jsonl \ --out-dir output/imagegen/batch \ --concurrency 5 rm -f tmp/imagegen/prompts.jsonl

批量模式要点（部分来自源码确认）：

• generate-batch必须传--out-dir，否则main()直接报错（image_gen.py）。
• --concurrency控制并发度，默认5（DEFAULT_CONCURRENCY），合法范围 1–25（image_gen.py）；实现基于asyncio.Semaphore。
• JSONL 每行一个任务，支持按任务覆盖：size、quality、background、output_format、output_compression、moderation、n、model、out，以及提示词增强字段（use_case、scene、subject、style、composition、lighting、palette、materials、text、constraints、negative）；也可放在fields子对象中。
• 每行还支持#注释行与空行跳过；任务可为字符串（仅 prompt）或 JSON 对象（见_normalize_job/_read_jobs_jsonl，image_gen.py）。单行 JSON 解析失败会报告具体行号，任务总数上限为 500（MAX_BATCH_JOBS）。
• 批量模式下，任务级out被当作--out-dir下的文件名处理（见_job_output_paths，image_gen.py）；未指定out时默认命名规则为{序号:03d}-{提示词slug}{扩展名}（slug 取提示词前 80 字符、小写并转连字符、最长 60 字符）。
• 单次批量还支持--n（同一提示词出多个变体）与--max-attempts（默认 3，合法范围 1–10）与--fail-fast。重试逻辑_generate_one_with_retries（image_gen.py）只对瞬时错误（429 限流、超时、连接重置）退避重试，退避时间优先取异常中的retry_after，否则按min(60, 2**attempt)指数退避；非瞬时错误直接抛出。--fail-fast开启时任一任务失败即终止并取消其余任务（image_gen.py）。

语义区分：--n是针对同一个提示词生成多个变体；generate-batch是针对许多不同提示词的批量。两者可组合使用。

CLI 参数速查与校验规则

支持的尺寸

1024x1024、1536x1024、1024x1536或auto（ALLOWED_SIZES，默认1024x1024）。

输出格式与透明背景

• --output-format：png（默认）、jpeg、webp；jpg会被归一化为jpeg（见_normalize_output_format，image_gen.py）。
• 透明背景（--background transparent）要求输出格式为png或webp，否则_validate_transparency直接报错（image_gen.py）。--background取值transparent|opaque|auto，它控制输出透明度行为，与提示词里描述的视觉场景/背景（scene/backdrop）不是一回事。

其他受支持的参数

--prompt-file（与--prompt二选一，_read_prompt会拒绝同时传入）、--output-compression（0–100，仅 jpeg/webp 有效）、--moderation（auto默认 /low）、--max-attempts、--fail-fast、--force、--no-augment、--n（1–10）。main()中还会统一校验：--n范围 1–10、--concurrency范围 1–25、--max-attempts范围 1–10、--output-compression范围 0–100、--downscale-max-dim >= 1、模型必须为gpt-image-*、尺寸与质量必须在白名单内（image_gen.py）。

边界与限制（来自 image-api.md）

• 输入图与掩码均需小于 50MB；编辑端点最多支持 16 张输入图。
• 大尺寸 + 高质量会显著增加延迟与成本；高input_fidelity会明显增加输入 token 用量。
• 本 CLI 面向 GPT Image 模型（gpt-image-1.5、gpt-image-1、gpt-image-1-mini），不要套用旧的非 GPT 图像模型行为；若某个选项不被所选模型支持导致失败，可去掉该选项后手动重试。
• 掩码为提示词引导，精确形状不保证。

使用护栏（Guardrails）

按 cli.md 的要求：

• 环境激活正确后，直接使用内置脚本（python "$IMAGE_GEN" ...），不要手写一次性 SDK 调用脚本。
• 不要创建一次性运行器（例如自建gen_images.py包装脚本），除非用户明确要求自定义包装。
• 绝不要修改scripts/image_gen.py。若发现缺失功能，先询问用户再做任何事（此规则同样写入 SKILL.md 与脚本头部文档）。

深入源码：三条执行链路

• generate 链路：_generate()（image_gen.py）→ 读取/增强提示词 → 组装 payload（model/prompt/n/size/quality/background/output_format/output_compression/moderation，空值剔除）→ 校验透明度 → 计算输出路径 → dry-run 打印请求或调用client.images.generate→ 解码b64_json写盘并可选降采样。
• edit 链路：_edit()（image_gen.py）→ 校验图片与掩码 → 组装 payload（额外含input_fidelity）→ 通过_FileBundle/_SingleFile上下文管理器以二进制模式打开输入文件（多图传列表、单图传单文件对象）→client.images.edit(**request)。
• batch 链路：_run_generate_batch()（image_gen.py）→ 读取 JSONL → 基础 payload + 任务级覆盖合并（_merge_non_null，任务字段优先、非空才覆盖）→ 按并发信号量调度 asyncio 任务 → 每任务独立重试与写盘。

此外，脚本把增强字段定义为 11 个可选参数（_fields_from_args，image_gen.py），批量模式下命令行字段作为“基础字段”与 JSONL 中任务级字段合并，任务级字段优先级更高——这解释了 cli.md 中“per-job overrides are supported”的实现原理。

关联参考文档

• API 参数速查（CLI 回退模式）：references/image-api.md
• 两种顶层模式共享的提示词示例：[references/sample-prompts.md
• 网络/沙箱说明（CLI 回退模式）：references/codex-network.md
• 共享提示词原则：references/prompting.md
• 技能主文档与依赖安装：SKILL.md
• 本 CLI 的实现源码：scripts/image_gen.py

需要再次强调：以上全部为fallback CLI 专属的执行控制面；quality、input_fidelity、显式掩码、background、output_format与输出路径等均不是内置image_gen工具的参数。正常使用请始终以内置image_gen工具为默认路径，仅在用户显式要求 CLI 模式时按本文操作。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills