gpt-image-2-skill

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<br/>gpt-image-2-skill"]
        APP["Desktop App<br/>Tauri + React"]
        WEB["Self-hosted Web<br/>Axum + React"]
        SKILL["Anthropic Skill<br/>Node wrapper"]
    end

    CORE["<b>gpt-image-2-core</b><br/>provider 适配 · 透明 PNG · 配置 · history · keyring · OAuth refresh"]

    subgraph Providers["三种 provider"]
        direction LR
        OAI["OpenAI<br/>gpt-image-2"]
        OAC["OpenAI-compatible<br/>--openai-api-base"]
        CDX["Codex<br/>~/.codex/auth.json"]
    end

    LEGACY[("$CODEX_HOME/gpt-image-2-skill/<br/>config.json · history.sqlite · legacy jobs/")]
    PRODUCT[("Product result library<br/>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