image-use

image-use — Agent 技能

这是一个独立的 Python CLI，可通过用户现有的订阅生成图像——默认使用 ChatGPT，备用使用 Codex，也可按需使用 Gemini。（之前名为 chatgpt-imagegen；该命令仍可作为 image-use 的别名使用。）无需 API 密钥、网络服务或额外配置。它有两个 OpenAI 后端，使用不同的用量额度——通过 --backend 选择——此外还有两个可选的 Google/Gemini 后端，供同时订阅了 Gemini 的用户使用。

后端

后端	接入方式	用量额度	需要	速度
web	通过 chrome-use（之前名为 agent-browser-stealth；较旧的安装版本会将同一个二进制文件显示为 agent-browser/abs）驱动用户已登录的 ChatGPT 浏览器，并在普通聊天中生成图像——与在应用中输入内容使用的是同一界面。它通过真实 Chrome 连接，从而通过 Cloudflare 和普通/无头客户端无法完成的 sentinel 工作量证明。	ChatGPT 对话——不会消耗按量计费的 Codex 用量额度。适用于任何账户，包括免费版（受每日图像上限限制）。	已安装 chrome-use，并且其扩展已连接到一个已登录 chatgpt.com 的 Chrome。	约 30–60 秒；每次运行的聊天都会归入一个 ChatGPT 项目（默认为 imagegen，会自动创建），而不是散落在聊天记录中。
codex	向 chatgpt.com/backend-api/codex/responses 发送无头 POST 请求，使用 image_generation 工具，并复用 ~/.codex/auth.json。	Codex 用量（按量计费——这是用户通常想省着用的额度）。	codex login（会写入 ~/.codex/auth.json）。	快速；无需浏览器，也不会留下聊天记录。

默认值为 auto（--backend auto，或 IMAGE_USE_BACKEND）：它会优先尝试 web，以节省 Codex 用量额度；只有在 web 不可用时才回退到 codex——也就是未安装 chrome-use、浏览器无法访问，或尚未登录 chatgpt.com。未完成设置的两种情况会分别处理：

• 浏览器未登录 / 缺少 chrome-use → auto 会回退到 codex（并向 stderr 输出一行提示），除非设置了 --require-project。必需模式会停止，且不会读取 Codex 凭据。如果普通 auto 模式下 codex 也未设置，则会退出并指出这两种修复方式。
• codex 未登录（不存在 ~/.codex/auth.json）→ auto 仍会使用 web；只有在备用时才会用到 codex。

如果 web 可访问，但提交后生成本身失败，auto 不会回退到 codex——因为那会消耗 auto 模式旨在保护的额度。在普通 auto 模式下，它会报错，并提示你使用 --backend codex 重新运行，以使用 Codex 用量路径；必需项目模式则会停止，但不会给出该建议。使用 --backend web 或 --backend codex 可强制指定单个后端。

Gemini 后端（选择加入 — auto 从不选择它们）

适用于也拥有 Google/Gemini 订阅的用户。两者使用的是 Google 账号，而非 OpenAI 账号。

后端	接口	需求	速度
gemini	通过 chrome-use 操作已登录 gemini.google.com 的浏览器 — 相当于 web 的浏览器版本。	chrome-use，以及一个已登录付费订阅 Google 账号的 Chrome 配置文件。	~11–24 秒
agy	无头运行 Antigravity CLI（agy）— 相当于 codex。	agy 位于 PATH 中。默认传入 --dangerously-skip-permissions，因为无头 agy 无法请求工具权限；如果用户自行维护 permissions.allow 规则，可通过 --no-agy-yolo 选择退出。	~14–25 秒

它们的配额彼此独立 — 这是实测结果，并非假设：agy 返回了 "Image generation model quota (gemini-3.1-flash-image) has been exhausted (429)"，而几秒后，使用同一个 Google 账号运行 --backend gemini 却成功了。因此，两者确实可以互为备用，而且其中一个报配额错误时，会在错误消息中提到另一个。

auto 永远不会选择它们。 这是刻意设计的：它们使用不同的厂商和账号，输出也有调用方能察觉的差异。需要使用时，请按名称指定。

推荐之前值得了解的行为：

• 可见水印。 gemini 的文生图结果带有 Gemini 的“闪光”字形，固定在距右下角 65 px 处（在 5 次 1024×559 运行中测得的位置完全一致）。图生图结果没有水印。agy 结果没有可见标记。
• 两者的输出无论如何都会带有不可见水印。 agy 输出带有 Google 签名的 C2PA 清单，其自身描述为 "Applied imperceptible SynthID watermark"。SynthID 信号位于像素中，经过任何重新编码后都会保留。
• 当前版本的 chrome-use 会让 gemini 保留 C2PA 清单。 Gemini 使用 blob: src 渲染结果，而页面内的 fetch() 仍无法读取它；现在，chrome-use download-url 会在页面内解析 blob 并将原始字节写入磁盘，因此签名清单得以保留。旧版 chrome-use 会直接拒绝 blob:，只能重新编码 canvas — 这条路径仍是备用方案，依然会剥除元数据；如果不得不使用这条路径，运行时会打印说明并指出需要升级。agy 会复制文件，因此其清单始终保留。
• --size 在 gemini 中控制宽高比，而非像素数。 聊天界面没有尺寸控件，因此会用文字请求宽高比 — 而且确实会遵循：请求正方形返回 1024×1024，请求 3:2 返回 1024×687，请求 2:3 返回 687×1024。无法固定的是绝对分辨率。如果没有指定，Gemini 默认使用 16:9，因此后端总会请求某种比例（当 --size 为 auto 时请求正方形）。实际尺寸会写入运行元数据。
• 会自动选择专用图像模型。 生成前，后端会将输入框切换到 Gemini 的图像工具，该工具会报告“使用 Nano Banana 2 生成” — 否则提示词会由当前启用的聊天模型回答（观察到的是 Flash-Lite）。尽力而为：如果菜单位置变了，运行会继续使用聊天默认模型，而不会失败。--no-gemini-image-tool 会跳过此尝试。它不会移除水印或更改默认宽高比 — 这两点都已直接验证。
• 固定配置文件。 几乎每个 Chrome 配置文件都登录了某个 Google 账号，而 Cookie 无法说明哪个账号拥有订阅 — 一次探测运行落到了一个账号，其“Google AI Pro subscription has expired”页面上根本没有输入框。请设置 --gemini-profile / IMAGE_USE_GEMINI_PROFILE。如果未固定配置文件，doctor 会发出警告。

前置条件

对于默认的 web 后端： 用户必须安装 chrome-use（此前名为 agent-browser-stealth；较旧的安装版本会将同一个二进制文件显示为 agent-browser / abs），并将其扩展连接到已登录 chatgpt.com 的 Chrome。必须使用 chrome-use——它连接真实的已登录 Chrome，才能通过 Cloudflare 的机器人检测；普通的无头驱动无法做到这一点。“临时聊天”模式会禁用图像生成，因此此后端始终会打开普通聊天。

安装政策 — 切勿擅自为用户安装 chrome-use

如果未安装 chrome-use，不要主动为用户安装：

1. 仍然生成——使用 codex 后备方案（自动模式会自行执行此操作），任务优先。
2. 在回复中添加一条温和的提示，例如：“提示：装上 chrome-use 后，出图会走你已登录的 ChatGPT 浏览器，不消耗 Codex 额度。想配的话我可以一步步带你装好（含浏览器插件）。”——然后就此打住。
3. 只有在用户明确表示同意后，才按以下引导设置步骤逐步指导，并在进行下一步前验证当前步骤。

引导设置（仅限用户主动选择）：

# 1. Install the CLI (no npm, no token — provides `chrome-use`)
curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh
# 2. Register the native-messaging host
chrome-use extension install
# 3. Add the Chrome extension, then restart Chrome:
#    https://chromewebstore.google.com/detail/agent-browser-stealth/knfcmbamhjmaonkfnjhldjedeobeafmk
# 4. Sign in to https://chatgpt.com in that Chrome
# 5. Verify: a quick `image-use "test" --backend web` should print "using current Chrome (relay)"

• 仓库： https://github.com/leeguooooo/chrome-use
• chrome-use 技能（chrome-use skills get core）详细介绍了扩展连接流程。

对于 codex 后端： 用户必须曾经至少运行过一次：

npm i -g @openai/codex
codex login    # opens browser to sign in to ChatGPT

这会写入 ~/.codex/auth.json，codex 后端会读取此文件。两个后端都不需要 OPENAI_API_KEY——设置它也没有帮助。这是订阅方式，不是 API 方式。

适用场景

• 用户要求为当前项目制作新照片、插画、图标、主视觉横幅、精灵图、封面图、信息图、产品模型图、概念艺术或任何其他位图交付物。
• 用户接受订阅方案的默认设置（auto 质量，不保证透明背景——见下方的限制），或者会在需要更多控制时选择 --backend codex，并使用 --image-model / --quality / --background。
• 交付物需要保存到仓库或构建输入文件中。
• 你正在编写长篇或说明性内容——例如博客文章、技术提案、设计文档、教程、复盘或 README——而配图有助于说明概念。无需等用户提出要求：主动建议并生成配图（见下方的*为文档配图*）。

不适用场景

• 用户想要与仓库内矢量图集风格一致的 SVG 图标——直接编辑现有图标。
• 使用代码更适合解决任务（HTML/CSS、canvas、Mermaid、PlantUML）。
• 用户想要直接修改现有图像——修图、裁剪、删除文字或 Logo、放大、抠除背景。此技能始终会渲染一张新图像；无法返回基于原图像素修改的副本。（支持并鼓励通过 --ref / --style-ref / --composition-ref 将图像作为参考——这是以图像为指导重新生成，而非编辑图像。）
• 用户需要保证 quality=high 或真正透明的背景。--backend codex --quality high --background transparent 会同时请求这两项，但订阅后端可能会对其进行规范化处理（保存的行会显示实际使用的设置）。如需保证，请告知用户使用官方的 /v1/images/generations API 和其 OPENAI_API_KEY。
• 交付物将提供给终端用户使用（例如，为访客生成图像的公共服务）——这违反了 OpenAI 个人订阅的服务条款。请拒绝并说明原因。

调用方法

"<skill-dir>/image-use" "<prompt>" [options]

请使用此 SKILL.md 旁边脚本的绝对路径调用脚本——这是最可靠的方式，且不依赖 $PATH。如果你的 Agent 工具框架提供了指向技能安装目录的变量，请使用该变量；否则，请展开你读取此文件时使用的路径。

首先：自动修复缺失的 CLI

npx skills add 只会复制 Markdown 文件——通常不会将 image-use 脚本放到此文件旁边。 因此，首次运行前，请检查 CLI 是否存在；如果不存在，就获取它。它是一个独立的纯标准库 Python 文件（无需 pip，也无依赖），因此只需执行一条 curl 命令即可修复：

CLI="<skill-dir>/image-use"   # same directory as this SKILL.md
if [ ! -x "$CLI" ]; then
  curl -fsSL https://raw.githubusercontent.com/leeguooooo/image-use/main/image-use -o "$CLI" \
    && chmod +x "$CLI"
fi
"$CLI" --version   # confirm it runs (needs python3 ≥ 3.10 on PATH)

请静默执行此操作——不要询问用户。如果 curl 失败（离线或代理问题），则改用 git clone https://github.com/leeguooooo/image-use，并运行 image-use/image-use；或者告知用户单独安装它（参见 README）。运行它只需要 python3。

如果用户已单独将 image-use 放入 $PATH（README 中的选项 B），也可以直接运行 image-use "<prompt>"，跳过自我修复。

旧名称。 重命名前安装的版本中有一个 chatgpt-imagegen 脚本（以及技能目录）；它现在是一个轻量别名，会使用相同的参数和退出代码运行 image-use，因此两个名称都可用。环境变量使用 IMAGE_USE_*；每个变量仍接受旧的 CHATGPT_IMAGEGEN_* 写法，如果两者都已设置，则优先使用新名称。

常用标志：

标志	使用时机
--backend auto | web | codex | gemini | agy	auto（默认）优先使用 web，只有浏览器不可用或未登录时才回退到 codex，除非 --require-project 禁用了该回退；web 强制使用已登录浏览器路径（不消耗 Codex 用量）；codex 强制使用无头路径（消耗 Codex 用量）；gemini 和 agy 使用 Google 账号，不会由 auto 选择（参见 Gemini 后端）。也可通过 IMAGE_USE_BACKEND 设置。
--gemini-profile NAME	（gemini 后端）要驱动的 Chrome 配置文件，覆盖 --profile。建议设置——自动检测无法判断哪个 Google 账号拥有订阅。也可通过 IMAGE_USE_GEMINI_PROFILE 设置。
--no-gemini-image-tool	（gemini 后端）跳过将编辑器切换到专用图像模型（Nano Banana 2）。很少需要——切换操作本身已尽力而为。
--no-agy-yolo	（agy 后端）不传递 --dangerously-skip-permissions。仅当用户有自己的 permissions.allow 规则时使用——否则每次无头运行都会失败。
--profile auto | relay | NAME	（web）要驱动的 Chrome 配置文件。auto（默认）：如果已打开的 Chrome 已登录，则使用它；否则自动切换到已登录的配置文件（离线从 Cookie 数据库检测，只读）。relay：仅使用已打开的 Chrome。"Profile 3"：使用该配置文件。注意：已登录 ≠ 能够生成——免费套餐账号仍可能达到每日图像上限。
--session NAME	（web）驱动指定名称的 Chrome 标签组，而非共享的 chatgpt-web 会话。很少需要：默认有意采用共享设置，让整台机器始终只保留一个 chatgpt.com 标签页。
--project NAME_OR_URL	（web）精确名称（不存在时创建，存在时复用），或现有 ChatGPT Project 着陆页 URL（https://chatgpt.com/g/g-p-<32-hex-id>/project，可带本地化路径段、查询参数或片段）。URL 会按 ID 直接打开，不会列出或创建；格式错误的 URL 会失败。默认值为 imagegen（也可通过 IMAGE_USE_PROJECT 设置，该变量也接受 URL）。--project "" 使用普通聊天。Project 失败时会发出警告，并继续使用普通聊天，除非设为必需。
--require-project	要求指定非空的 Project 目标，并在打开后及原生 Send 点击时的捕获保护中验证其身份。仅适用于 web/auto；禁用 Codex 回退，包括浏览器不可用时的回退。也可通过 IMAGE_USE_REQUIRE_PROJECT=1 设置。路由并不意味着保留记录：添加 --keep-conversation 以保留历史记录。发送前失败时会保留当前草稿；请检查草稿，并在下次运行前手动清空编辑器。
--no-require-project	在本次运行中覆盖必需模式的环境默认值，不更改导出的变量。恢复尽力而为的 Project 路由及常规后端/回退规则；允许使用 --project "" 或显式指定非 web 后端。是否保留记录仍是独立设置。
--keep-tab	（web）生成后保持 ChatGPT 标签页打开（默认会关闭）。便于调试。隐含 --keep-conversation。
--keep-conversation	（web）生成后保留 ChatGPT 对话。默认会删除（PATCH is_visible:false），因此运行不会留下历史记录——对话只会暂时归入该 Project。也可通过 IMAGE_USE_KEEP_CONVERSATION=1 设置。
-o PATH	知道文件应放在仓库中的哪个位置时，务必使用。
--model NAME	（仅限 codex）读取提示词并调用图像工具的驱动模型——不是图像模型（服务器使用自己的模型进行渲染，目前观察到的是 gpt-image-2-codex）。该模型会消耗按量计费的 Codex 额度，因此请选用速度快、价格实惠且可使用 Codex 账号的模型：默认值为 gpt-5.6-luna，可选 gpt-reserve、gpt-5.3-codex-spark。前沿编码模型（gpt-6-astra，……）只会白白消耗额度。不支持的模型会自动回退到 gpt-5.5。也可通过 IMAGE_USE_MODEL 设置。
--size 1024x1024	方形图标 / 徽标（已验证）
--size 1536x1024	横向主视觉横幅、社交卡片（已验证）
--size 1024x1536	竖版封面、移动端启动图（已验证）
--size 3840x2160 或类似尺寸	4K 横向图像（原样转发；后端可能拒绝——失败时回退到较小的已验证尺寸）
--format webp	生成更小的 Web 资源文件
--image-model MODEL	（仅限 codex）选择 GPT Image 模型：gpt-image-2.5-sunburst（精确编辑）或 gpt-image-2.5-flare（快速、高质量）；旧版 gpt-image-2 / gpt-image-1.5 / gpt-image-1 / gpt-image-1-mini 也可使用。不设置时使用后端自身的默认值。也可通过 IMAGE_USE_IMAGE_MODEL 设置。
--quality LEVEL	（仅限 codex）low | medium | high | xhigh | max——后两者需要 2.5 模型（--image-model）。这是一个请求，而非保证；保存时请查看工具打印的 quality= 进行验证。也可通过 IMAGE_USE_QUALITY 设置。
--background auto | transparent | opaque	（仅限 codex）透明背景需要 png/webp（不能使用 jpeg），且订阅路径可能会拒绝。也可通过 IMAGE_USE_BACKGROUND 设置。
--compression 0-100	（仅限 codex）jpeg/webp 输出压缩（对 png 无效）。也可通过 IMAGE_USE_COMPRESSION 设置。
--action auto | generate | edit	（仅限 codex）强制选择生成或编辑，而不是由模型决定；适用于使用 --ref 编辑。也可通过 IMAGE_USE_ACTION 设置。
--partial-images 1-3	（仅限 codex）将渐进式预览流式传输到进度时间线。也可通过 IMAGE_USE_PARTIAL_IMAGES 设置。
--style NAME	应用已保存的素材（样式片段和/或固定参考图像）。可重复指定——组合角色与样式，例如 --style mascot --style watercolor。参见 样式与素材。在本次运行中覆盖任何当前生效的默认素材组。
--no-style	本次运行跳过所有素材（文本和固定参考图像），即使用户设置了当前生效的默认素材也一样。
--quiet	在 Agent 环境中使用，确保标准输出中只有保存路径。进度仍会输出到标准错误（使用 --no-progress 可将其静默）。
--no-progress	完全静默标准错误中的进度时间线（错误仍会打印）。
--timeout SECONDS	总墙上时钟时间预算（默认值为 300）。生成大型/精细图像可能需要 2–3 分钟——如果遇到 timed out 错误，请调高此值。
--stall-timeout SECONDS	后端数据块之间允许的最长静默时间，超过后即判定为停滞（默认值为 120，且不会超过 --timeout）。降低此值可更快地判定挂起的流式后端失败；0 会禁用此空闲检查。Web 页面轮询使用总 --timeout。
-V、--version	打印 CLI 版本并退出。运行 image-use --version 可确认已安装的构建版本。

循环动画

使用 image-use animate "<motion prompt>" 生成固定镜头的八帧循环动画。它会生成一张 4×2 精灵图，按确定性方式裁剪，检查主体是否有明显偏移，并默认输出动画 WebP。添加 --also-gif 可同时生成两种格式，或使用 --animation-format gif 仅生成 GIF。源精灵图会保存在输出文件旁边；--keep-frames 还会保留全部八张裁剪后的 PNG。

动画后处理是可选的，不会影响普通图像生成。它需要 magick（ImageMagick）；此外，WebP 还需要 img2webp（libwebp）。进行实际动画生成前，运行 image-use doctor，查看这些工具和生成后端是否已就绪。

脚本在所有模式下都只将保存路径输出到 stdout；易读的进度时间线和任何错误都会输出到 stderr，因此 OUT=$(image-use "..." --quiet) 只会捕获路径，同时你仍能看到时间线。每行时间线都会标注经过的秒数（[ 12.3s] generating），让运行缓慢的情况一目了然，卡住时也能轻松发现。

样式与素材

素材是存储在 ~/.config/chatgpt-imagegen/styles.json 中、可命名并重复使用的外观设置（遵循 $XDG_CONFIG_HOME）。每个素材都包含一个文本片段和/或固定的参考图像，以及一个 kind：

• --kind style（默认）——一种视觉美学风格（线条、调色板、纹理）。其参考图会告诉模型：“匹配这种风格，不要照搬内容。”
• --kind character——一个反复出现的主体（吉祥物、角色）。其参考图会告诉模型：“忠实地再现这个角色作为主体。”

这样，用户就可以固定一次自己的卡通角色或品牌风格，然后重复使用——无需每次都重新传入 --ref。除非用户主动启用，否则生成行为不会改变（开箱即用时没有默认设置）。

固定与复用：

• 从图像文件固定一个角色：image-use style add mascot "a round orange fox named Pip" --kind character --ref a.png --ref b.png（多个角度 → 一致性更好）。图像会复制到素材库，因此即使移动或删除原文件，素材仍会保留。
• 固定刚刚喜欢的图像：image-use style add mascot --from-last --kind character（style add-ref mascot --from-last 也适用）。流程：生成 → 喜欢 → 固定 → 复用。
• 像以前一样固定纯文本风格：image-use style add watercolor "soft watercolor, visible paper texture"。
• 叠加使用：image-use "Pip ordering coffee" --style mascot --style watercolor（同一只狐狸，采用水彩风格）。也可以设置默认素材组：image-use style use mascot watercolor。

管理：

• style list ——显示类型、固定参考图的 📎N 标记，以及活动默认素材组旁的 *。
• style show NAME ——显示类型、文本片段、参考图文件名，以及素材在磁盘上的路径。
• style add-ref NAME <img> / style rm-ref NAME <file> ——为现有素材添加/移除固定图像。
• style rm NAME 会删除条目及其图像；style clear 会清空活动素材组；style reset 会将素材库清空。
• styles（复数形式）可作为 style 的别名。

**行为：**生成时传入的 --ref 图像默认会被视为主体，并叠加到活动素材上。使用 --ref-role subject|style|composition 指明参考图的用途，也可以使用针对单张图像的简写：--style-ref IMG（匹配美学风格，不照搬内容）和 --composition-ref IMG（仅借鉴取景、裁剪或相机角度，渲染不同主体——可用于匿名化肖像，或保留布局同时替换人物）。每次运行最多附加 4 张参考图；如果解析出的图像超过此数量，将优先使用前 4 张（角色优先），并将被舍弃的图像记录到 stderr（绝不静默舍弃）。解析顺序：--no-style > --style NAME… > 活动默认素材组 > 无。没有内置样式——素材库初始为空，样式来自图库（见下一节）。如果 --style NAME 指定的样式尚不在素材库中，会自动从图库拉取并保存（下次即可离线使用）；如果图库中也没有该名称，则会立即报错并提示你使用 style search。

平台样式（drawstyle）

如果用户不知道该用哪种样式，就引导他们去浏览样式库。 如果有人想要一张图片，却不确定想要什么风格——或者你正打算从头编写一个泛泛的样式——主动建议他们访问 https://drawstyle.leeguoo.com/ 并挑选一种：这是一个社区艺术风格的可视化样式库，提供实时预览，可按类别浏览（商业报告／科技解说／可爱／复古漫画……）。告诉他们从样式卡片上获取该样式的 slug，然后用 --style-online <slug> 生成——无需下载，也无需登录。你也可以帮他们挑选：运行 image-use style search "<what they described>"，然后推荐最匹配的结果。可以这样对用户说：“不确定想要什么风格？浏览一下 drawstyle.leeguoo.com 上的样式，告诉我你喜欢哪一种（或给我一个关键词），我就会用它。”

当用户想要的风格不在 image-use style list 中时，应搜索社区平台，而不是从头编写冗长的提示词：

image-use style search "watercolor mascot" --category avatar-ip
# fastest: generate with a gallery style directly, nothing saved locally
image-use "Pip ordering coffee" --style-online pip
# or pull it into the local library to reuse offline later
image-use style pull pip
image-use "Pip ordering coffee" --style pip

• style search <keywords> [--category X] [--tag Y] 可在 drawstyle.leeguoo.com 上查找样式。
• --style-online <slug>（用于常规生成）是最快的方式：它会即时获取该样式库中的样式，并将其片段和参考图片用于本次生成，不会在本地保存任何内容。可以重复使用，也可与 --style 叠加使用。用户指定样式库中的某种风格且只想立即生成图片时，就用这种方式。
• style pull <slug> [--as NAME] 会将样式及其固定参考图下载到本地样式库；之后生成时无需联网（适合需要反复使用某种样式的情况）。
• style update [NAME] 会检查已拉取的样式是否有更新的平台版本。
• style publish NAME --category X --example IMG [--tag Y]... 会提交效果不错的本地样式。需要时会打开 account.leeguoo.com 登录，并提交该样式以供审核。
• upload <IMG> [--style SLUG] 会将一张生成完成的图片上传到某种样式的作品图库（drawstyle.leeguoo.com/en/s/<slug>/generations）——无需登录，每个文件不超过 5 MB，每台机器每天（UTC）限 10 张。该命令会输出公开的 /img/… URL、图库链接和剩余配额。这是独立命令，不是生成标志——除非用户提出要求，否则绝不上传。

主动提议发布效果不错的样式。 如果你制作出一种效果良好、可重复使用的样式——或者用户说生成的风格很棒，之后还想再次使用——就建议将其分享到样式库，让其他人（以及用户未来的自己）只需运行一条命令就能 style pull。发布只需一行命令（最近一次生成的图片会成为示例图片）：

image-use style publish mystyle --category cute --from-last

上传前会显示摘要，并提供审核进度链接。注意：发布需要进行一次浏览器登录（会自动打开浏览器并缓存令牌）；style search 和 style pull 无需登录。未经用户同意，不要发布——先提出建议，再等他们确认。

展示作品成果（作品图库）——仅在用户提出要求时。 上传是一个由用户主动发起的独立步骤；生成过程绝不会自行发布任何内容。用户要求将作品与某种样式一同分享时，运行 image-use upload <IMG> --style <slug>（无需登录，文件不超过 5 MB——超出限制的文件会先通过 sips 缩小一次，之后若仍超限则会明确报错；每台机器每天（UTC）限 10 张）。该命令会输出公开的 /img/… URL、样式的图库链接和剩余配额；网站管理员之后可能会将该图片设为封面。不要自动上传，也不要在生成任务中加入上传操作——先提出建议，等用户明确同意后再上传。

旧版本的 styles.json 文件（仅含文本条目）仍然可用，并会在下次修改时自动升级。

保存路径策略

1. 始终保存到工作区，绝不要保存到 /tmp、$HOME 或 ~/.codex/...。
2. 如果用户指定了目标路径，通过 -o 传入。
3. 如果用户没有指定，选择一个合适的子目录：assets/、public/、static/、docs/img/、web/img/、assets/brand/ 等。只有在没有更合适的目录时，才默认使用 assets/generated/。
4. 除非用户要求，否则不要覆盖现有文件。使用 -o 时，脚本会静默覆盖；不使用 -o 时，会自动编号（name.png、name-2.png）。
5. 保存后，将最终路径告知用户。

工作流

1. 澄清提示词，确保足以写出 1–3 句话：主题、风格、构图、氛围和限制。用户的提示词已经具体时，不要过度补充。
2. 根据用途选择尺寸和格式（见上表）。
3. 在工作区内选择输出路径。
4. 运行 image-use "<prompt>" -o <path> --size <wxh> --quiet。
5. 如果可以，检查生成结果（例如使用 view_image 工具或读取文件）。如果结果明显不对，只针对提示词做一次修改后重新生成——不要盲目循环（每次调用都会消耗订阅额度）。
6. 报告保存路径以及最终使用的提示词。

为文档配图

撰写文档、博客文章、技术提案、设计文档或其他长篇说明内容时，主动为关键概念配图——无需用户提出要求。流程如下：

1. 先简要说明计划。 用一两行说明图片将放在哪里，以及每张图描绘什么（例如：“我会添加两张图：(1) 请求→SSE 流程，(2) 令牌刷新路径。”）。然后开始生成——无需等待批准；这份计划让读者有机会提出调整。
2. 为每张图分派一个后台子 Agent。 每个子 Agent 都通过 --quiet -o <path> 运行 CLI，使标准输出仅包含保存路径；在图片生成期间继续撰写正文，并在图片生成后将其嵌入。使用你自己的 Agent/任务工具，将其作为后台任务启动——每个任务生成一张图，绝不阻塞写作。
3. 并行度取决于用户使用的后端——不要擅自更改。 遵循用户指定的 --backend / IMAGE_USE_BACKEND（默认值为 auto）。使用 web 后端时，并发数为 1——后台图片任务会排队并逐一生成（仍然可行：任务在后台运行，且不会消耗 Codex 用量）。使用 codex 时，最多可并行生成 4 张，但每张都会计入按量计费的 Codex 用量额度。选择消耗哪个后端由用户决定，而不是你。
4. 选择适合文档语气的风格。 没有默认插画风格，也没有内置风格——风格来自图库。对于轻松或博客风格的说明文，doodle 图库风格很合适——刻意采用粗略画风，同时准确呈现内容（--style doodle 会自动拉取该风格）。对于中文文章中的概念图（把判断、流程或隐喻转化为一张令人印象深刻的图片），xiaohei 风格很合适——白色背景、手绘黑色墨线，由一个小黑角色演绎这一概念（--style xiaohei）。对于精致的规格文档，选择更简洁的风格或自己定义的风格（参见 Styles & assets）。不确定哪种风格合适？浏览社区图库 https://drawstyle.leeguoo.com/（或使用 style search），并通过 --style-online <slug> 使用图库风格，或通过 --style <slug> 保留该风格。 若要在文档的多张图中保持同一角色或视觉风格，将其固定为资源，并与 --style 叠加使用。
5. 不要过度配图。 每个主要概念最多配一张图；绝不要为了装饰而配图；也绝不要反复生成同一张图的“变体”——这只会白白消耗订阅额度。如果图片效果不对，修改一次提示词后重新生成，不要大量反复尝试。

编写图示提示词

模糊的提示词只会生成毫无用处的图示。提示词应描述图示的内容，而不只是给它命名：

• 明确写出方框、箭头、标签、布局和关系——“架构图”太模糊；要说明图中有什么，以及各部分如何连接。
• 每个图示只包含一个主题、一个概念。将内容繁杂的图示拆分成两个。
• 在提示词中或通过 --style 明确指定所需风格。
• 对于 doodle 画廊风格，请记住，内容准确性胜过精致度——图示本就应该看起来粗糙且像手绘，但标签和结构仍必须清晰可读。

限制

• 图像质量和背景默认由后端决定。 --quality（low/medium/high/xhigh/max）和 --background transparent/opaque 是仅供 codex 使用的可选参数（web 和 gemini 界面没有此类控件，而且即使传入，CLI 也会发出警告）。xhigh/max 和透明背景需要 GPT Image 2.5 模型，因此请将它们与 --image-model gpt-image-2.5-sunburst（或 -flare）搭配使用。请将它们视为请求：据观察，Codex OAuth 路径会在服务端规范化模型、尺寸和质量，因此保存的行会打印后端实际使用的 model= / quality= / size=——请以此为准，而非命令行参数。如果用户需要保证 quality=high 或真正透明的 PNG，请引导他们使用自己的 OPENAI_API_KEY 调用官方 /v1/images/generations API。
• 在 codex 后端上，这些图像参数都不会保留下来。 服务端会直接重写工具——实测结果：model→gpt-image-2-codex，quality/size/background→auto，output_compression→100——因此 --image-model/--quality/--background/--compression 在此处实际上不起作用。CLI 现在会打印生效的 model= 和本次运行的 tokens=… (in … / out …)，并在请求的参数被重写时发出警告。在 codex 上，唯一重要的调节项是 --model（驱动模型）：快速、经济的 Codex 模型能降低按量计费的成本；使用前沿编码模型并不会改善图像效果。Token 成本主要由输入决定（提示词 + 样式片段，每次运行都会重新发送），因此样式内容庞大才是昂贵之处，而非图像本身。
• 生成一张图像通常需要 15–60 s，但尺寸较大或细节较多的图像偶尔需要 2–3 min。默认 --timeout 为 300 s，以应对这种情况；流式后端可能会在 --stall-timeout（默认 120 s）时限下提前失败。提交后，web 会等待两次连续页面读取确认出现新图像，或直到总时限结束。仅有助手文本或缺少 Stop 控件都不代表任务已结束。检测到速率限制对话框时会立即失败；如果没有图像或流式控件，检测到明确的英文配额/拒绝前缀时也会失败。此检测范围有限，并未涵盖所有措辞或语言：引用中的提及、含糊的重试文本及其他回复都会一直等待到超时。正文错误诊断会包含助手文本（最多 240 个字符）；超时诊断会在页面读取中断后保留最后一段非空文本。对于结果不确定的 web 运行，请在重试前检查原始对话。
• 各后端的并发上限（跨进程、使用 flock 槽位池；超出上限的运行会安全排队，等待者会打印 "waiting…"，且只有在获取槽位后才开始计算 --timeout）：web = 1（页面界面的速率限制很严格——会提示 "Too many requests"；此外还共用一个 Chrome），codex = 4（在 Plus 上实测安全，并设有上限以避免大规模并发触发账户限制）。可通过 IMAGE_USE_WEB_CONCURRENCY / IMAGE_USE_CODEX_CONCURRENCY 覆盖（0 = 不限）。提高 web 上限并不会让 web 运行并行：下文的跨工具 chatgpt.com 锁仍会让它们逐个运行。如需并行批量处理，请使用 --backend codex + shell & + wait；并行启动 web 运行是安全的，但会逐个执行。不要盲目循环生成“同一提示词的不同版本”——这只会浪费配额；请改为迭代调整提示词。
• 每台机器仅使用一个 chatgpt.com 标签页。 web 运行期间会在整个生成过程中获取位于 ~/.chatgpt-web.lock 的跨工具 advisory lock，并驱动一个名为 chatgpt-web 的稳定 chrome-use 会话，该会话与 chatgpt-use 共用。这并非只是为了整洁：只要账户中任何对话完成图像生成，ChatGPT 就会向每个已打开的 chatgpt.com 标签页推送 "Image created" 提示，因此第二个标签页可能会把其他对话的图像泄漏到你的运行中（issue #7）；两个进程共用同一个输入框时，其提示词也会拼接在一起。账户还会仅根据标签页数量实施速率限制。你编写的任何其他 chatgpt.com 自动化程序都应使用相同的锁和会话名称。
• 订阅配额与用户交互式使用 ChatGPT 共用。未经许可，请勿批量生成（持续超过每分钟 10 张图像）——否则会触及每日上限。

错误处理

**遇到任何“使用哪个后端／为什么网页无法正常工作”的故障时，第一步：**运行 image-use doctor。它会以只读方式报告 CLI 自身版本与 GitHub 最新发布版本的对比情况、每个后端是否已配置（codex 令牌；chrome-use 是否已安装及其版本；relay 是否已连接；已登录的 Chrome 配置文件），以及 auto 会选择哪一个——将含糊的“没有已登录的浏览器”转化为明确的检查清单。

更新通知见升级。

症状	原因	解决方法
~/.codex/auth.json not found	Codex CLI 从未登录	告知用户运行 npm i -g @openai/codex && codex login
no ChatGPT OAuth access_token in ~/.codex/auth.json	文件中只有 API 密钥，没有订阅 OAuth 令牌	告知用户运行 codex login；文件中的 OPENAI_API_KEY 值不能替代订阅 OAuth 令牌
HTTP 400 requires a newer version of Codex	本地 codex CLI 已过时	告知用户运行 npm i -g @openai/codex@latest；脚本会从 ~/.codex/version.json 读取版本，该文件由 codex 在启动时更新
HTTP 401 / HTTP 403 然后刷新成功	令牌已过期，且刷新成功	无需操作——脚本已自动重试
refresh_token is no longer valid — run codex login again	刷新令牌已撤销或轮换	告知用户再次运行 codex login
stalled: the image backend sent no data for ~Ns (last phase: …)	在整个 --stall-timeout 空闲时段内都没有数据——后端已挂起或过载	重试；如果再次出现，请调高 --stall-timeout（以及 --timeout），或设置 --stall-timeout 0，以等待完整的 --timeout 时段。消息会指出发生停滞的阶段。
timed out: no image within the Ns total budget (last phase: …)	整个 --timeout 时限已耗尽——通常是因为图片确实很大	调高 --timeout（例如 --timeout 420）并重试
timed out after Ns waiting to confirm the image … The prompt was already submitted	（web）在原始时限内没有确认图片；这并不能证明请求失败	不要重新提交提示词。错误会指出会话：图片出现后，运行 image-use recover <that URL> -o PATH（添加 --quiet 可仅在标准输出中输出路径）。如果显示“仍在处理”，请一分钟后再试。需要 chatgpt/images chrome-use 适配器（chrome-use site update）。提交后，auto 不会回退到 Codex。
ChatGPT reported an image-generation limit / ChatGPT declined the image request	（web）非流式助手回复以可识别的英文配额或拒绝消息开头，且没有生成新的图片	查看附带的 ChatGPT said 文本，了解原因或重置时间；重试前检查已提交的会话。不要通过其他后端重新提交。
no image returned. events seen: ...	模型决定不调用工具	改写提示词，明确要求“使用 image_generation 工具来生成……”
HTTP 429	订阅触发了速率限制	等待几分钟；不要循环重试
warning: --format=X but FILE.Y has .Y extension	-o 的扩展名与 --format 不一致	修正路径或格式标志；文件确实会按指定格式写入
warning: project 'X' unavailable (…); using a plain chat	（web，未使用 --require-project）项目列表或创建 API 出现问题，或者项目页面的输入框未显示	无需处理——图片仍已生成，只是在顶层聊天中生成。如果再次出现，请检查目标项目；使用 --require-project 可在无法使用项目时停止，而不是降级处理
required project unavailable / required Project Send stopped	无法验证项目访问权限、路由或输入框状态	停止；检查 Project 链接、权限和保留的草稿。下次运行前，手动清除输入框中保留的文本；ChatGPT 可能会在新聊天中恢复草稿。不会回退到普通聊天或 Codex。对不确定是否已发送的请求绝不重复发送；重试前先检查会话。
chatgpt.com rate-limited this account ('Too many requests') …	（web）页面暂时阻止该账户发送过多请求	等待几分钟。检测到速率限制后，运行会停止，不会自动回退到 Codex；如果提示词已提交，请稍后检查会话——图片可能仍会在那里出现。不要循环重试
waiting for a free web/codex slot (max N concurrent …)	并行运行数超过后端并发上限	无需处理——空出名额后运行会自动开始；排队时间不会占用 --timeout

升级

当任何 image-use 命令输出 image-use X is available 时，告知用户并询问是否运行 image-use upgrade（该命令会更新 CLI 和此技能）。检查更新但不做任何更改： image-use upgrade --check（或 --json）。用户也可以直接说“升级 image-use” / “upgrade image-use”。 image-use update 和旧版 chatgpt-imagegen update 的作用相同。

如果此技能的来源无法通过 upgrade 更新：

• Claude Code 插件：claude plugin update image-use@leeguooooo-plugins
• 整个系列：curl -fsSL https://raw.githubusercontent.com/leeguooooo/plugins/main/upgrade-use-family.sh | sh

此通知会输出为一行 stderr，每天最多检查一次；设置 IMAGE_USE_NO_UPDATE_CHECK=1（或旧版 CHATGPT_IMAGEGEN_NO_UPDATE_CHECK，或适用于整个系列的 USE_NO_UPDATE_CHECK）可将其关闭。

内部机制（供维护者 / 调试使用）

Web 后端（run_web）

• 调用 chrome-use，操作以会话命名的 Chrome 标签组。
• 打开常规的 https://chatgpt.com/ 对话（临时聊天会禁用图像工具）。
• 在已通过身份验证的页面中解析指定的 ChatGPT Project（使用未公开的端点，通过实时探测确认）：GET /backend-api/gizmos/snorlax/sidebar 会列出项目（项目是 ID 为 g-p-… 的 gizmo）；POST /backend-api/projects {name, instructions} 会创建项目。已有的 Project URL 会绕过这两个端点，直接打开 https://chatgpt.com/g/<g-p-id>/project。失败时会发出警告，并默认降级为普通对话；--require-project 会将其视为致命错误，并阻止自动模式下的 Codex 回退。
• 使用 fill --stdin 粘贴内容，验证编辑器中的逻辑文本完全一致且每个引用文件均已完成上传，然后只点击一次“发送”。必需模式还会在上传引用文件 / 粘贴内容前检查 Project。它只标记当前文档的“发送”按钮；捕获监听器会在按钮原生点击期间重新检查路由、文本、上传文件、轮次和就绪状态。尝试结束后会移除标记和监听器；如果 CLI 意外退出，标记和监听器会在 30 秒后过期。多行 keyboard type 可能会将换行转换为不完整的提交。未确认的上传或已更改的文本会导致运行停止；对于不确定是否已发送的情况，只会观察，不会重放。现有草稿会保留。发送前失败时，旧模式会清除已粘贴的文本；必需模式会保留当前草稿，因为路由或所有权可能已更改。请先检查草稿，并在重试前手动清空编辑框。
• 通过 eval 轮询页面状态：等待流式输出 / 停止控件消失，并且出现一张全新的 <img>（src 匹配 estuary/content|files/download|oaiusercontent），且连续两次读取结果保持稳定。图像扫描范围限定为 main img（当前标签页自己的对话线程）——当另一个对话完成图像生成时，ChatGPT 会在任何打开的标签页中显示带有匹配缩略图的“图像已创建”提示；扫描整个文档会误取那个并行对话中的图像（问题 #7）。生成的 img 不在 [data-message-author-role="assistant"] 内，因此 <main> 是正确的扫描范围。
• 通过页面内的 fetch(src, {credentials:'include'}) 将字节下载为 base64，这样浏览器自身的会话 Cookie 就能授权访问已签名的资源 URL。令牌不会离开浏览器。 codex 后端（run_codex）
• 从 ~/.codex/auth.json 读取 access_token、account_id、refresh_token；从 ~/.codex/version.json 读取 version 标头。
• 向 https://chatgpt.com/backend-api/codex/responses 发送 POST 请求，包含 tools: [{"type": "image_generation"}]（以及用户选择启用的 model/quality/background/output_compression/action/partial_images 中的任意选项——未设置的选项会被省略），流式处理 SSE 响应，并对 image_generation_call 结果进行 Base64 解码。服务端会重写工具配置，并在 response.created 中报告实际生效的配置；CLI 会捕获该配置（以及 response.completed.usage），以打印真实的 model= 和 tokens=。默认驱动为 gpt-5.6-luna；如果模型不在账户允许列表中（GET /backend-api/codex/models?client_version=…），则会回退到 gpt-5.5，而不会导致运行失败。
• 收到 401/403 时，通过 https://auth.openai.com/oauth/token 自动刷新 OAuth 令牌（client_id=app_EMoamEEZ73f0CkXaXp7hrann）；刷新的令牌会写回 auth.json。

网页端只能通过真实浏览器访问的原因：面向消费者的 backend-api/* 路径受三层机制保护——Cloudflare 边缘检查、哨兵工作量证明（sentinel/chat-requirements，以及页面内用于计算令牌的 sentinel/sdk.js），还有 Cloudflare Turnstile 令牌。实测结果表明：来自住宅 IP 的纯 Bearer 令牌请求可以通过 Cloudflare 边缘检查和 PoW（CF 基于 IP 信誉；PoW 类似 hashcash，可离线复现）——真正的拦截来自 Turnstile，这是无头客户端无法伪造的交互式令牌。而“只为获取 Turnstile 令牌借用浏览器，然后切换到无头模式”反而适得其反：令牌只能使用一次且有效期很短，因此每次请求都得打开浏览器。这就是网页后端要驱动真实登录浏览器的原因；唯一真正无需浏览器的途径是 codex 后端（会计入 Codex 用量）。

报告问题——你就是反馈渠道

此工具主要由其他人的 Agent调用，因此**维护者很少能直接看到故障——运行它的 Agent 是发现问题的主要途径。**遇到疑似工具缺陷时，请帮忙报告，而不是悄悄绕过问题。

• **值得报告的问题：**崩溃/回溯、理论上应该能用却无法工作的后端、错误或乱码输出、误导性/错误的错误消息、image-use doctor 判断一切正常但 web/chrome-use 失败，或与此 SKILL 描述相矛盾的行为。
• **不属于缺陷的问题（处理即可，无需提交）：**用户只是没有登录，或没有安装后端（这是设置问题——引导他们查看 doctor 和安装步骤）；或模型有意拒绝生成内容。
• **报告方式：**主动提出帮忙提交问题，或向用户提供可直接粘贴的报告，网址为 **https://github.com/leeguooooo/image-use/issues**。先搜索未关闭的问题，避免重复。请附上：
  • 运行的确切命令，
  • image-use -V（版本），
  • 完整的错误文本/异常输出，
  • image-use doctor 的输出。
• 提供复现步骤的 30 秒问题报告，远胜于悄悄绕过问题——这正是修复此工具的方式。

相关项目

• HTTP 网关姊妹项目（用于多应用/兼容 SDK 的用法）：https://github.com/leeguooooo/agent-cli-to-api

自定义 Codex Responses 提供方

使用 --backend codex --codex-provider current（或设置 IMAGE_USE_CODEX_PROVIDER=current）来选择 $CODEX_HOME/config.toml（默认路径为 ~/.codex/config.toml）中的顶层 model_provider。提供方名称 （例如 --codex-provider myrelay）会直接选择 [model_providers.myrelay]。 提供方模式需要 Python 3.11+；留空该选项或环境变量，可在 Python 3.10+ 上保留现有的 ChatGPT OAuth 后端。

model = "gpt-6-astra"
model_provider = "myrelay"
[model_providers.myrelay]
base_url = "https://relay.example"
wire_api = "responses"
requires_openai_auth = false
auth = { command = "/usr/local/bin/get-token", args = ["--name", "relay"], timeout_ms = 15000, refresh_interval_ms = 3600000 }

建议使用 auth.command；它也适用于桌面版 Codex，并且会避免将返回的令牌存入配置文件和环境变量。该命令和 args 会直接运行，不通过 shell；stdout 去除首尾空白后会作为 Bearer 令牌。 auth 必须是包含非空字符串 command 的表格。可选的 args 必须是字符串列表；timeout_ms 必须是正整数（默认值为 15000）；可选的字符串 cwd 用于设置工作目录。此一次性 CLI 会忽略 refresh_interval_ms，并在每个进程中针对每个提供方缓存命令的成功或失败结果。优先级为 env_key → auth.command → experimental_bearer_token；选定来源失败时不会回退。或者，设置 env_key = "MYRELAY_API_KEY" 并将令牌安全地注入进程环境；避免在配置中以明文形式使用 experimental_bearer_token。端点为 base_url.rstrip("/") + "/responses"；中继服务必须支持 Responses image_generation 工具。提供方模式不使用 ChatGPT OAuth 或账号 ID。 顶层 model 用于指定驱动程序的默认模型；--model（或 IMAGE_USE_MODEL）可覆盖它。支持静态 http_headers 和 env_http_headers（请求头名称 → 环境变量名称）；未设置的请求头环境变量会被跳过。image-use doctor --codex-provider current 会检查配置和令牌是否就绪，但不会显示令牌。