image-generation · diff
git:20260329.09a3d48 to v26.29.14
107 added, 44 removed. Audit A to A.
---
name: image-generation
- description: AI 图片生成。通过 OpenAI/Gemini 兼容 API 生成图片，支持多 provider 配置。当用户提到"生成图片"、"画图"、"封面图"、"配图"、"生成封面"、"AI生图"时使用。
- argument-hint: "[prompt] [-p provider] [-e endpoint] [-m model] [-s size] [-o output]"
+ version: 26.29.14
+ description: AI 图片生成与编辑。使用统一 CLI 调用 OpenAI Images、Google Gemini 原生图片 API、火山方舟 Seedream，支持多参考图、mask、批量生成、透明背景后处理，以及 Seedream 5.0 Pro 点选/框选式连续交互编辑。当用户提到生成图片、画图、封面图、配图、AI 生图、改图、修图、参考图编辑、Gemini 生图、Seedream 或交互编辑时使用。
+ argument-hint: "generate|edit|interactive [prompt] [-p provider] [-e endpoint] [-m model]"
allowed-tools: Bash(uv run *), Read, Grep, Glob, Edit
---
- 你是一个 AI 图片生成助手。帮助用户通过多种 AI 图片生成 API 生成图片。
+ # Image Generation
- ## 路径约定
+ 通过一个严格配置的 CLI 生成或编辑位图。不要按模型名称猜协议，不要绕过配置 allowlist，也不要把远端 `/models` 返回的未配置模型视为可调用。
- - `{SKILL_DIR}` = 本文件所在目录
- - `{SCRIPTS_DIR}` = `{SKILL_DIR}/scripts`
+ ## 路径
- ## 支持的功能
+ - `{SKILL_DIR}`：本文件所在目录
+ - `{SCRIPTS_DIR}`：`{SKILL_DIR}/scripts`
+ - CLI 前缀：`uv run --project {SCRIPTS_DIR} imggen`
- 1. **列出 provider**：查看已配置的图片生成服务
- 2. **获取模型列表**：从 API 动态获取可用模型
- 3. **生成图片**：根据文字描述生成图片
+ ## 必须遵守
- ## CLI 命令
+ 1. 优先使用本 skill 的 CLI 路径完成图片生成与编辑。
+ 2. adapter 仅由 `provider/endpoint` 配置决定，只能是 `openai`、`gemini`、`seedream`。
+ 3. 调用模型前，必须在所选 endpoint 的 `models.<exact-model-id>` 表中命中；未命中立即停止。
+ 4. 每个 endpoint 独立配置 `adapter`、`base_url`、`api_key`/`api_key_env` 和模型 allowlist。禁止跨 endpoint 借用凭据或静默回退。
+ 5. 只发送模型 policy 中明确声明的 capability。CLI 的显式参数不受支持时必须报错，不能丢弃。
+ 6. `imggen models` 仅用于诊断远端可见性；远端可见但本地未配置的模型仍然被阻止。
+ 7. 不输出、记录或回显 key。需要新 key、base URL 或模型授权时，请用户修改配置。
- 所有命令使用 `uv run --project {SCRIPTS_DIR} imggen` 前缀。
+ 配置结构和迁移方式见 [references/configuration.md](references/configuration.md)，adapter/模型差异见 [references/capability-matrix.md](references/capability-matrix.md)。
+ ## 工作流
+
+ ### 1. 判断操作
+
+ - 纯文字新建图片：`generate`
+ - 一张或多张参考图上的语义修改：`edit`
+ - OpenAI alpha mask 局部修改：`edit --mask`
+ - Seedream 5.0 Pro 点选/框选并连续迭代：`interactive`
+ - 多个独立生成任务：`generate-batch`
+ - 纯色背景转透明：`chroma-key`
+
+ 编辑前先查看参考图，确认用户指的是哪一侧、哪个主体或哪块区域。若目标清楚，直接执行；只有会实质改变结果的缺失信息才需要询问。
+
+ ### 2. 选择 endpoint 和模型
+
```bash
- # 列出已配置的 provider 及端点
uv run --project {SCRIPTS_DIR} imggen list
+ uv run --project {SCRIPTS_DIR} imggen models -p primary -e seedream
+ ```
- # 从 API 获取可用模型列表
- uv run --project {SCRIPTS_DIR} imggen models
- uv run --project {SCRIPTS_DIR} imggen models -p apiyi -e openai
- uv run --project {SCRIPTS_DIR} imggen models -p apiyi -e gemini
+ 用户未指定时使用配置默认值。若默认模型没有本次操作或参数所需 capability，选择同一 endpoint allowlist 中明确支持的模型；不能自行切换 endpoint。
- # 生成图片（默认 provider 的首个端点）
- uv run --project {SCRIPTS_DIR} imggen generate "一只可爱的猫咪"
- # 指定 provider + endpoint + model
- uv run --project {SCRIPTS_DIR} imggen generate "封面图：科技风格" -p apiyi -e openai -m gpt-image-1 -s 1024x1024 -o ./cover.png
- ```
+ ### 3. 准备 prompt
- ## 工作流
+ 保留用户意图、人物身份和必须不变的内容。编辑 prompt 要同时写清：
- 当用户要求生成图片时：
+ - 要改变什么；
+ - 在哪里改变；
+ - 哪些内容必须保持不变；
+ - 构图、相机、光线、材质和文字要求。
- ### 第一步：理解需求
+ CLI 默认把 prompt 和 `--scene/--subject/--style/...` 组织成结构化段落；原样发送时使用 `--no-augment`。完整字段见 [references/prompting.md](references/prompting.md)。
- - 确认用户想要的图片内容、风格、尺寸
- - 若用于博客封面图，默认尺寸 900x383（微信公众号封面比例 2.35:1）
- - 若用户未指定 provider/model，使用默认配置
+ ### 4. 先验证，再调用
- ### 第二步：优化 prompt
+ 高成本或复杂请求可先 `--dry-run`。dry-run 仍会执行配置、模型、文件和 capability 校验，但不会发网络请求或写图片。
- 将用户的中文描述优化为更详细的英文 prompt（大多数模型对英文 prompt 效果更好），同时保留原始意图。若用户明确要求使用中文 prompt，则保持原样。
+ ```bash
+ uv run --project {SCRIPTS_DIR} imggen generate \
+ --prompt "夜雨中的末日都市屋顶" \
+ -p primary -e openai -m gpt-image-1.5 \
+ --size 1536x1024 --quality high --output-format png \
+ --out ./roof.png --dry-run
+ ```
- ### 第三步：生成图片
+ ### 5. 生成或编辑
- 使用 CLI 命令生成图片。示例：
+ ```bash
+ # 生成
+ uv run --project {SCRIPTS_DIR} imggen generate "电影感末日城市" \
+ -p primary -e openai -m gpt-image-1.5 \
+ --size 1536x1024 --quality high -o ./city.png
+ # 多参考图语义编辑；--image 可重复
+ uv run --project {SCRIPTS_DIR} imggen edit \
+ --prompt "保留人物身份和服装，只调整腿部姿态" \
+ --image ./scene.png --image ./character-sheet.png \
+ -p primary -e gemini -m gemini-3-pro-image-preview \
+ --aspect-ratio 9:16 --image-size 2K -o ./edited.png
+
+ # OpenAI mask 编辑
+ uv run --project {SCRIPTS_DIR} imggen edit \
+ --prompt "只替换透明 mask 区域" --image ./input.png --mask ./mask.png \
+ -p primary -e openai -m gpt-image-1.5 -o ./masked.png
+ ```
+
+ `--out` 已存在时默认拒绝覆盖；明确覆盖才加 `--force`。`--downscale-max-dim` 会在原图之外生成带 `-small` 后缀的缩略副本。
+
+ ### 6. Seedream 5.0 Pro 交互编辑
+
+ 交互坐标必须是官方 `0–999` 坐标。已经是归一化坐标时直接传 `--point X,Y` 或 `--bbox X1,Y1,X2,Y2`；从展示像素坐标转换时同时传 `--canvas-size WIDTHxHEIGHT`。
+
```bash
- uv run --project {SCRIPTS_DIR} imggen generate "A cute cat sitting on a stack of books, digital art style, warm lighting" -p apiyi -m gpt-image-1 -s 1024x1024 -o /tmp/cat.png
+ # 创建会话并执行第一轮
+ uv run --project {SCRIPTS_DIR} imggen interactive start \
+ --session ./outputs/edit-session.json --image ./input.png \
+ --bbox 320,480,760,900 --canvas-size 1080x1440 \
+ --prompt "将框内手提包替换为黑色手枪套" \
+ -p primary -e seedream -m doubao-seedream-5-0-pro-260628
+
+ # 下一轮自动以上一轮成功产物作为参考图
+ uv run --project {SCRIPTS_DIR} imggen interactive edit \
+ --session ./outputs/edit-session.json --point 520,640 --canvas-size 1080x1440 \
+ --prompt "把此处金属扣改成暗红色"
+
+ # 状态查看与失败恢复
+ uv run --project {SCRIPTS_DIR} imggen interactive show --session ./outputs/edit-session.json
+ uv run --project {SCRIPTS_DIR} imggen interactive retry --session ./outputs/edit-session.json
```
- ### 第四步：确认结果
+ 可先在 `interactive start` 末尾追加 `--dry-run` 验证坐标、模型与 capability；dry-run 不创建 session。
- - 告知用户图片已生成及保存路径
- - 若用于博客，建议合适的存放路径（如 `static/uploads/{year}/`）
+ 会话固定 provider/endpoint/model，记录每轮输入、标注、引用图、参数、输出与失败信息；禁止中途换 endpoint。详细协议见 [references/seedream-interactive.md](references/seedream-interactive.md)。
- ## Provider 类型
+ ### 7. 批量与透明背景
- 支持两种 API 格式：
+ ```bash
+ uv run --project {SCRIPTS_DIR} imggen generate-batch \
+ --input ./jobs.jsonl --out-dir ./outputs --concurrency 3 \
+ -p primary -e openai -m gpt-image-1.5
- - **openai**：兼容 OpenAI Images API（`/v1/images/generations`），也支持通过 Chat Completions 生图的模型（如 gpt-image-1）
- - **gemini**：兼容 Google Gemini API（`/v1beta/models/{model}:generateContent`），支持多模态输出
+ uv run --project {SCRIPTS_DIR} imggen chroma-key \
+ --input ./green.png --out ./transparent.png \
+ --auto-key corners --soft-matte --despill
+ ```
- ## 配置
+ JSONL、重试、输出与全部参数见 [references/cli.md](references/cli.md)。
- 配置文件位于项目根目录的 `agent_config.toml`，在 `[image-generation]` 命名空间下。详见 `{SKILL_DIR}/agent_config.example.toml`。
+ ## 交付
- ## 技术实现
+ 完成后报告 adapter、endpoint、模型、输出绝对路径和已执行的关键约束。若生成了图片，在支持本地媒体展示的客户端中显示最终图片。不要泄露凭据，也不要声称未实际验证的 provider 功能可用。
- 详见 [reference.md](reference.md)。
+ 技术实现索引见 [reference.md](reference.md)。