gpt-image-2-skill

Language: 中文 | English

一个 Rust core 跑四种入口的 GPT Image 2 工具链。CLI、桌面 App、自托管 Docker Web、可安装 Skill 共用同一份 provider 适配层、透明 PNG 流水线、配置与本地历史,统一以 agent-first 的 JSON stdout + JSONL stderr 协议输出结果。

目录

• 架构
• 项目定位
• 快速开始
• 运行时矩阵
• Provider 矩阵
• 核心能力
• 图像生成与编辑
• 透明 PNG 流水线
• Agent 协议
• 配置与密钥
• 桌面 App
• Docker Web 自托管
• Skill 集成
• Cloudflare Worker relay
• 仓库结构
• 本地开发
• 发布与分发
• 文档
• 许可证

架构

graph TB
    subgraph Surfaces["四种入口"]
        direction LR
        CLI["CLI

gpt-image-2-skill"]
        APP["Desktop App

Tauri + React"]
        WEB["Self-hosted Web

Axum + React"]
        SKILL["Anthropic Skill

Node wrapper"]
    end

    CORE["<b>gpt-image-2-core</b>

provider 适配 · 透明 PNG · 配置 · history · keyring · OAuth refresh"]

    subgraph Providers["三种 provider"]
        direction LR
        OAI["OpenAI

gpt-image-2"]
        OAC["OpenAI-compatible

--openai-api-base"]
        CDX["Codex

~/.codex/auth.json"]
    end

    LEGACY[("$CODEX_HOME/gpt-image-2-skill/

config.json · history.sqlite · legacy jobs/")]
    PRODUCT[("Product result library

App data / Docker /data/gpt-image-2/jobs")]

    SKILL --> CLI
    CLI --> CORE
    APP --> CORE
    APP -. "HTTP transport" .-> WEB
    WEB --> CORE

    CORE --> OAI
    CORE --> OAC
    CORE --> CDX

    CLI --> LEGACY
    SKILL --> LEGACY
    APP --> PRODUCT
    WEB --> PRODUCT
    PRODUCT -. "read old outputs" .-> LEGACY

gpt-image-2-core 是单一权威实现:provider 路由、/images/generations 与 /images/edits multipart、Codex image_generation SSE、401 触发的 OAuth refresh、retry、config.json 解析、Keychain/file/env 三源凭据解析、SQLite history、结果存储上传、本地透明 PNG chroma + dual-background 抠图与多 profile 验证全部住在 core 里。CLI 是其薄壳,Tauri sidecar 直接复用同版本二进制,Docker Web 把 core 包成 Axum HTTP 服务,Skill 通过 Node wrapper 调到 CLI。CLI/Skill 继续使用 $CODEX_HOME/gpt-image-2-skill/;桌面 App 和 Docker Web 的新生成结果进入产品结果库,旧 jobs 目录仅作为兼容读取来源。

项目定位

• Agent-first 协议 — 每条命令都返回统一 JSON envelope (ok / error.code / data),进度事件以 JSONL 形式走 stderr,错误码可机读。包括 request create raw 转发出口,允许 agent 在协议没覆盖的场景下直接打 OpenAI 或 Codex 上游。
• 三 provider 同接口 — OPENAI_API_KEY / OpenAI-compatible base URL / Codex auth.json 走完全相同的命令面;切 provider 不改命令形状,只换 --provider,Codex 401 自动 refresh 一次再重试。
• 透明 PNG 是终端交付 — transparent generate / transparent extract / transparent verify 把 controlled-matte 生成、本地 chroma 与 dual-background 抠图、9 种 profile 化质量门绑成完整流水线;不依赖 provider native --background transparent。
• 结果库 / 一码多端 — CLI/Skill 保持轻工具形态,输出路径由命令控制;桌面 App 和 Docker Web 管理自己的产品结果库,同时保留旧 $CODEX_HOME/gpt-image-2-skill/jobs 的兼容读取。服务端运行时还可以把生成结果异步上传到多个存储目标,再带着 outputs[].uploads[] 触发通知。

快速开始

挑跟你身份相符的一条路径开始,其余命令在下面的核心能力里就近展示。

我是 agent 调用方 — CLI + JSON

cargo install gpt-image-2-skill --locked
# 或 brew install wangnov/tap/gpt-image-2-skill
# 或 npm install --global gpt-image-2-skill

OPENAI_API_KEY=sk-... gpt-image-2-skill --json --json-events \
  images generate \
  --prompt "A studio product photo of a red apple on transparent background" \
  --out ./apple.png \
  --background transparent --format png --size 2K

--json 打印结构化结果到 stdout,--json-events 把进度事件以 JSONL 形式打到 stderr。两者独立,可单独使用。

我是桌面用户 — Homebrew Cask

brew install --cask wangnov/tap/gpt-image-2

或从 GitHub Releases 下载对应平台安装包。macOS DMG 通过 Developer ID 签名并完成 Apple notarization,App 内置 Tauri 自动更新器。详见桌面 App。

我是开发者要嵌入或自托管 — Skill / Docker Web

# 把 Skill 装到 Anthropic skills CLI / Claude Code
npx skills add https://github.com/Wangnov/gpt-image-2-skill --skill gpt-image-2-skill

# 或者起一个本地 Docker Web 服务
docker build -t gpt-image-2-web .
mkdir -p "$HOME/.local/share/gpt-image-2" \
  "$HOME/.local/share/gpt-image-2-codex/gpt-image-2-skill" \
  "$HOME/.codex/gpt-image-2-skill/jobs"
docker run --rm -p 8787:8787 \
  -v "$HOME/.local/share/gpt-image-2:/data/gpt-image-2" \
  -v "$HOME/.local/share/gpt-image-2-codex:/data/codex" \
  -v "$HOME/.codex/gpt-image-2-skill/jobs:/data/codex/gpt-image-2-skill/jobs:ro" \
  -v "$HOME/.codex/auth.json:/data/codex/auth.json:ro" \
  gpt-image-2-web

详见 Skill 集成 和 Docker Web 自托管。

运行时矩阵

brew install wangnov/tap/gpt-image-2-skill

npm install -g gpt-image-2-skill

cargo binstall gpt-image-2-skill | $CODEX_HOME/gpt-image-2-skill/ | agent 直调、CI、脚本编排 | | 桌面 App (Tauri) | brew install --cask wangnov/tap/gpt-image-2

或 GitHub Releases DMG / NSIS / AppImage / deb / rpm | 配置/历史暂用 $CODEX_HOME/gpt-image-2-skill/;新结果默认进系统 App 数据目录;导出默认到 ~/Downloads/GPT Image 2 | 桌面用户;sidecar 调本地 CLI,可切换 HTTP 后端模式 | | Docker Web (Axum) | docker build -t gpt-image-2-web . | 新结果默认 /data/gpt-image-2/jobs;旧 /data/codex/gpt-image-2-skill/jobs 可只读兼容 | 自托管、远程访问、内网共享 | | Skill | npx skills add https://github.com/Wangnov/gpt-image-2-skill --skill gpt-image-2-skill | 复用调到的 CLI 的 $CODEX_HOME | Claude Code、Anthropic skills CLI | | Rust crate | gpt-image-2-core = "0.4" | 调用方决定 | 嵌入第三方 Rust 工程,自定义 surface |

$CODEX_HOME 默认为 ~/.codex/,可由环境变量覆盖。CLI/Skill 继续按命令参数输出;桌面 App 和 Docker Web 把“结果库”和“导出文件夹”分开,避免把内部 jobs 目录误当作用户下载目录。

结果存储与第三方集成

桌面 App(Tauri sidecar)和 Docker Web 会在生图成功后先写入产品结果库,再异步上传结果文件,最后派发通知/webhook。上传状态写入 history.sqlite,任务历史会返回 storage_status 以及每个输出的 uploads[] 记录;在 cloud_primary 下,历史预览、复制、导出和编辑引用会优先用本地缓存,缺失时从 Origin 回读,显式 fallback 时才读 Archive。通知/webhook 的 job.storage 会区分 origin 与 archives。静态 Web 只保存当前浏览器数据,不会保存远端存储密钥,也不会执行服务端上传。

支持的目标类型:

全局配置通过 storage.pipeline 选择四种归档策略,把"原图位置(Origin)"和"异步归档目标(Archives)"分开:

任务请求仍可独立传 storage_targets 和 fallback_targets,这两份列表会被并入当次任务的 archives(去重,不影响 Origin)。

托管部署如果只是想提供默认值,应设置 storage.policy.managed = true 且 allow_user_overrides = true;UI 会显示"管理员默认值",但用户仍可调整模式、Origin 和 Archive。删除本地历史/缓存只影响本地 result library、trash 和 SQLite 记录,不会删除远端 Origin/Archive 对象。

老 config(storage.default_targets / storage.fallback_targets / storage.fallback_policy)在加载时会自动迁移到 pipeline,无需手工修改。注意一项行为变化:旧 fallback_policy = on_failure 同时配置 default_targets + fallback_targets 的用户,迁移后两个列表会全部成为 archives 并每次都跑(不再是"主失败才跑 fallback"),这是一次性多上传一份。

输出级/目标级并发由 upload_concurrency 和 target_concurrency 控制。cloud_primary 可用 cleanup.mode = after_archive_success | by_age | by_size 清理本地缓存;清理只删除本地 cache,不会隐式删除远端对象。远端 HTTP/S3/WebDAV 上传默认拒绝 loopback/private/link-local 等非公网地址并禁用重定向;SFTP 必须配置服务器 SHA256 host key 指纹。

Provider 矩阵

选择策略 (--provider <value>):

• openai / codex — 强制走对应 provider。
• auto(默认)— 优先用配置中的 default_provider,否则按 OpenAI → Codex 自动 fallback。
• <name> — 解析配置中已注册的命名 provider。

实际命中的 provider 会在 doctor 输出的 provider_selection.resolved 里报告。

核心能力

图像生成与编辑

# 用 OpenAI-compatible base
OPENAI_API_KEY=sk-... gpt-image-2-skill --json \
  --provider openai --openai-api-base https://api.duckcoding.ai/v1 \
  images generate \
  --prompt "A polished geometric app logo on transparent background" \
  --out ./logo.png --background transparent --format png --size 2K

# 用 Codex auth.json
gpt-image-2-skill --json --json-events \
  --provider codex \
  images generate \
  --prompt "A glossy red apple sticker on transparent background" \
  --out ./apple.png

# 参考图编辑(OpenAI multipart)
gpt-image-2-skill --json --json-events \
  images edit \
  --prompt "Refine this logo, keep transparency, and improve visibility on dark backgrounds" \
  --ref-image ./logo.png \
  --out ./logo-edit.png \
  --background transparent --format png --size 1024x1024

支持的输入 / 输出参数:

• --format png|jpeg|webp,--quality high|medium|low|auto,--compression,--input-fidelity(OpenAI only)
• --ref-image 最多 16 张,--mask(OpenAI only)
• --size:2K → 2048x2048,4K → 3840x2160,4K 竖版 → 2160x3840,方图高分辨率上限 2880x2880,自定义 WIDTHxHEIGHT 须满足:边都是 16 的倍数、最大边长 3840、最大总像素 8294400、最大长宽比 3:1
• 默认 retry 3 次,Codex 401 自动 refresh 一次后重试;--retries、--retry-delay-seconds、--request-timeout-seconds 可调

透明 PNG 流水线

不依赖 provider native --background transparent(Codex 尤其不可靠)。流水线分三步:生成 controlled matte 源图 → 本地抠图 → profile 化质量门验证。

# 端到端:从 prompt 生成最终透明 PNG(默认 chroma)
gpt-image-2-skill --json --json-events \
  --provider codex \
  transparent generate \
  --prompt "A glossy red apple sticker, centered, no text, no frame" \
  --out ./apple-transparent.png --size 2K --quality high

# Chroma:已知颜色单背景源图,自动采样 matte
gpt-image-2-skill --json \
  transparent extract --method chroma \
  --input ./source-magenta.png --matte-color auto \
  --out ./asset.png --strict

# Dual-background:玻璃 / 流光 / 烟雾等半透明素材
gpt-image-2-skill --json \
  transparent extract --method dual \
  --dark-image ./glow-black.png --light-image ./glow-white.png \
  --out ./glow-transparent.png --profile glow --strict

# 交付前的最终质量门
gpt-image-2-skill --json \
  transparent verify \
  --input ./apple-transparent.png \
  --expected-matte-color '#00ff00' \
  --profile product --strict

Profile(--profile,验证用)— 决定质量门严格度:

Material preset(--material,chroma extract 用)— 调 chroma threshold / softness / spill_suppression:standard / soft-3d / flat-icon / sticker / glow,手动 flag 可继续覆盖。

Verify 输出关键字段:passed、alpha_min/alpha_max、transparent_ratio、partial_pixels、checkerboard_detected、touches_edge、stray_pixel_count、matte_residue_score、halo_score、transparent_rgb_scrubbed、alpha_health_score、residue_score、quality_score、failure_reasons、warnings。完整字段表见 skills/gpt-image-2-skill/references/transparent-png.md。

Agent 协议

统一 JSON envelope — 每条命令成功返回结构化结果,失败返回:

{
  "ok": false,
  "error": {
    "code": "transparent_verification_failed",
    "message": "...",
    "detail": { "...": "optional" }
  }
}

主要错误码:runtime_unavailable / invalid_command / invalid_argument / unsupported_option / auth_missing / auth_parse_failed / refresh_failed / network_error / http_error / invalid_body_json / transparent_verification_failed / transparent_input_mismatch。

JSONL 进度事件(--json-events,stderr)— multipart_prepared、retry_started、Codex SSE 增量等,详见 skills/gpt-image-2-skill/references/json-events.md。

控制台命令:

```bash

环境健康检查 — provider 选择、retry policy、运行时版本

gpt-image-2-skill --json doctor

检查所有 provider 的凭据可用性

gpt-image-2-skill --json auth ins