minimal-agent 0.8.2 → 0.10.0

package/skills/ai-image/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ai-image
+description: 当用户说"生成图片"、"画一张图"、"配图"、"插画/插图"、"AI 生图"、"图生图"、"参考这张图改图/扩图/增强"或者你判断出客户实际上的要求等价于用AI生成或编辑图片时使用（OPENAI_IMAGE_* 配置那一路）。支持文生图和带输入图的图生图/参考图生成，支持指定宽高比。与 image-gen-openrouter（OPENROUTER_API_KEY）是两套独立机制，按用户配置选用，别混用。
+---
+
+# ai-image —— 文生图 / 图生图
+
+> 生图能力住在本技能的脚本 `scripts/generate.mjs`（零依赖、裸 fetch、自己落盘），
+> 走 `OPENAI_IMAGE_*` 配置。工作流批量生图优先用内核 `GenerateImage` 工具（无 Bash 120s 帽），
+> 手动调试或单张生成时用 Bash 调脚本即可。
+> 如果用户明确点名 OpenRouter / nano banana 且用 `OPENROUTER_API_KEY`，那是另一个技能
+> `image-gen-openrouter`（curl 版），别混用。
+
+## 怎么干
+
+用 **Bash 工具**跑本技能目录下的脚本（**用 node 跑，不是 bun**）：
+
+```bash
+node "<本技能目录>/scripts/generate.mjs" \
+  --prompt "A serene mountain lake at sunrise, soft mist, photorealistic, wide cinematic shot" \
+  --out ./assets/lake.png \
+  --aspect 16:9
+```
+
+图生图 / 参考图增强：
+
+```bash
+node "<本技能目录>/scripts/generate.mjs" \
+  --prompt "Extend this product photo into a clean 16:9 hero background, preserve the main product, premium soft light, no text, no logos" \
+  --input-image ./assets/source.png \
+  --out ./assets/source_enhanced.png \
+  --aspect 16:9
+```
+
+批量 PPT 配图不要让 agent 循环手写 Bash；在 workflow 中优先调用 `GenerateImage` 工具。手动调试时，
+让计划脚本读取 `img_plan.json` 确定性执行：
+
+```bash
+node "<本技能目录>/scripts/generate_from_plan.mjs" \
+  --plan ./build/img_plan.json \
+  --assets ./build/assets \
+  --timeout-ms 600000 \
+  --size 1K
+```
+
+- `<本技能目录>` = 系统提示「可用技能」列表里本技能（ai-image）后面给出的**绝对目录**，直接拼 `/scripts/generate.mjs` 或 `/scripts/generate_from_plan.mjs`。
+- 路径含空格时给整条路径加引号。
+- **调 Bash 时务必把 `timeout` 设成 `600000`（10 分钟）**：图像模型很慢（一张常要 1 分钟、重模型几分钟），
+  Bash 默认只给 120s，会把还没出图的进程当超时掐断。脚本运行时会往 stderr 打 `[ai-image] attempt k/N …` 进度，
+  看到它就说明在正常等待、不是卡死。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--prompt` | ✅ | 图片提示词。**英文通常效果更好**；用户给的是中文就保留，不要主动翻译。越具体（主体/风格/光线/构图/负空间）越好。 |
+| `--out` | ✅ | 落盘路径。绝对或相对（相对当前工作目录）。**建议 `.png` 后缀**。父目录自动创建。 |
+| `--aspect` | ⬜ | 宽高比，如 `16:9` / `9:16` / `4:5` / `1:1`。脚本会同时①发 provider 原生 `image_config.aspect_ratio`、②在提示词里追加构图提示，双保险。 |
+| `--size` | ⬜ | 分辨率档，如 `1K` / `2K` / `4K`（部分模型/端点支持；不支持则忽略）。 |
+| `--model` | ⬜ | 临时覆盖 `OPENAI_IMAGE_MODEL`（想换更快/更便宜的模型试一张时用）。 |
+| `--input-image` | ⬜ | 输入参考图，本地路径 / URL / data URL 均可。本地图片会转成 `data:image/...;base64,...`。用于图生图、扩图、换背景、比例修复、质感增强。 |
+
+成功后脚本在 stdout 打**一行**：`saved: <path> (model=<m>, bytes=<n>, aspect=<a>)`；失败信息走 stderr，退出码非 0。
+
+## 注意事项
+
+- **先确认配置**：脚本需要 `.env`/环境里有 `OPENAI_IMAGE_BASE_URL` / `OPENAI_IMAGE_API_KEY` / `OPENAI_IMAGE_MODEL`。
+  缺了脚本以**退出码 3** + 明确文案报错——如实转告用户补好配置再试，别瞎重试。
+- **协议自动选（无需关心）**：脚本支持两套生图协议并按 provider 自动切——OpenRouter 的多模态图模型走
+  `chat/completions`（图在 `message.images[]`，输入图作为 `image_url` 内容块）；OpenAI / Azure / **火山方舟 Seedream** 走官方 Images API
+  `images/generations`（图在 `data[0].b64_json`，输入图通过 `image` 扩展参数传入）。`OPENAI_IMAGE_PROVIDER ∈ {volces,volces-plan,ark,doubao,seedream,openai,azure}`
+  → images，其余 → chat；可用 `OPENAI_IMAGE_PROTOCOL=chat|images` 显式覆盖。用户只换 `.env` 即可切 provider，
+  调脚本的命令行参数完全不变。
+- **火山 Seedream 注意 base URL**：图片生成/图生图用 `https://ark.cn-beijing.volces.com/api/v3`；不要用聊天/识图的
+  `https://ark.cn-beijing.volces.com/api/coding/v3`。若开通了「流量包」套餐（`OPENAI_IMAGE_PROVIDER=volces-plan`），
+  base URL 改用 `https://ark.cn-beijing.volces.com/api/plan/v3`（按套餐计费，模型 ID 需与套餐支持列表一致，别混用 v3 端点否则产生套餐外费用）。
+- **图生图用途**：客户图比例不适合、主体太小、背景杂乱、需要扩成 16:9 hero、需要统一光影或增强清晰度时使用。不要把图生图当作结构图生成器；流程、架构、表格、模块图仍用 HTML/SVG/图表。
+- **速度取决于模型**：flash 类（如 `google/gemini-3.1-flash-image-preview`）约数十秒/张；重模型（如 `openai/gpt-5.4-image-2`）可达 ~3 分钟/张。生成期间耐心等其返回再发下一张；批量会成倍变慢，按需克制数量。
+- **鉴权失败**（401/403，退出码 1）：脚本返回「API key 可能失效/无权」诊断；转告用户检查 key，别重试烧钱。
+- **不要回显 API key**：脚本本身绝不打印 key；你转述错误时也别把 `OPENAI_IMAGE_API_KEY` 带出来。
+- **绿色版**：脚本随 `skills/` 分发到 exe 同级，但执行需机器装有 **Node**（与 ui-design 的 PPTX 导出脚本同样要求）。
+- **校验产物**：生成后可用 `Read`（offset=0 limit=1）触发二进制嗅探，或 `Bash` 看文件 size > 10KB 确认是真图。
+- 一次一张；多张就多次调用、每次换 `--out` 路径。
+
+## 关于宽高比（重要）
+
+`--aspect` 决定**生成图的构图**（主体摆放、负空间留给谁）。当生图是为了放进 PPT/网页的固定槽位时，
+**aspect 应贴合槽位的宽高比**——这样 CSS `object-fit:cover` 裁切最少、构图意图（如给文字留的净空）能保住。
+怎么按版面选 aspect 见 ui-design 的 `references/layout-composition.md`（图文混排方法论）。

package/skills/ai-image/scripts/generate.mjs

@@ -0,0 +1,497 @@
+#!/usr/bin/env node
+/**
+ * ============================================================
+ *  skills/ai-image/scripts/generate.mjs
+ *  —— OpenAI 兼容「AI 文生图」CLI（零依赖、裸 fetch、落盘）
+ * ------------------------------------------------------------
+ *  做一件事：把一句提示词（可选带一张参考图）发给 OpenAI 兼容的图像模型，拿回 base64
+ *  图片解码成二进制写到磁盘。供 ai-image 技能 / ppt 工作流用 Bash 调用：
+ *
+ *    node <技能目录>/scripts/generate.mjs \
+ *        --prompt "a serene mountain lake at dawn, cinematic" \
+ *        --out ./build/assets/img_1.png \
+ *        --aspect 16:9
+ *
+ *    node <技能目录>/scripts/generate.mjs \
+ *        --prompt "extend this product photo into a clean 16:9 hero background, no text" \
+ *        --input-image ./build/assets/src_1.png \
+ *        --out ./build/assets/enhanced_src_1.png \
+ *        --aspect 16:9
+ *
+ *  为什么是脚本不是内置工具？
+ *    - 内置工具（Write）只能写文本，写不了二进制；而把生图做成「基础工具」
+ *      和文件读写不是一个层级、且与本技能职责重叠。统一收进技能脚本 =
+ *      单一真相源（删掉了原 src/llm/imageClient.ts + GenerateImage 工具）。
+ *    - 技能脚本随 skills/ 在 dev / npm / 绿色版三形态都被分发、用 node 跑，
+ *      与 ui-design 的 export_pptx_from_html.mjs 同款（PPT 流程本就依赖 Node）。
+ *
+ *  两套协议（按 provider / OPENAI_IMAGE_PROTOCOL 自动选，见 resolveProtocol）：
+ *    A) chat —— OpenRouter 的多模态模型（gemini / gpt-image 系）走 chat 协议：
+ *       POST /chat/completions，请求加 `modalities:["image","text"]`，模型把图片塞进
+ *       `choices[0].message.images[].image_url.url`（base64 data URL）返回。
+ *    B) images —— OpenAI 官方「Images API」标准格式（OpenAI / Azure / 火山方舟 Seedream）：
+ *       POST /images/generations，请求是 `{model,prompt,size,response_format,watermark,image?}`，
+ *       图片在 `data[0].b64_json`（base64）或 `data[0].url`（需再下载）返回。
+ *    为什么两套都要：二者覆盖不同生态——只留 images 会丢掉 OpenRouter（它的图模型只走 chat）；
+ *    只留 chat 又用不了火山 Seedream 这类标准 Images API。按 provider 自动选 = 换 .env 即可切。
+ *
+ *  比例（aspect）三层保险：
+ *    1. image_config.aspect_ratio / image_size —— OpenRouter 原生参数（端点支持就生效）；
+ *    2. 提示词里追加一句构图提示（端点忽略 image_config 时的软引导）；
+ *    3. 真正的 PPT 几何由 ui-design 的 HTML 槽位 + CSS object-fit 决定（兜底）。
+ *
+ *  零依赖：fetch / Buffer / AbortSignal 都是 Node 20+ 内置。
+ *  退出码：0 成功；1 生成失败；2 参数错；3 缺环境变量。全程不回显 API key。
+ * ============================================================
+ */
+
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+
+// ============================================================
+//  1. 解析命令行参数（支持 `--flag value` 与 `--flag=value` 两种写法）
+// ============================================================
+
+/** 把 process.argv 解析成 { prompt, out, aspect, size, model, input-image }。 */
+function parseArgs(argv) {
+  const out = {};
+  const keys = new Set(['prompt', 'out', 'aspect', 'size', 'model', 'input-image', 'dry-run-request']);
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (!tok.startsWith('--')) continue;
+    const body = tok.slice(2);
+    const eq = body.indexOf('=');
+    let key;
+    let val;
+    if (eq !== -1) {
+      key = body.slice(0, eq);
+      val = body.slice(eq + 1);
+    } else {
+      key = body;
+      val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : '';
+    }
+    if (keys.has(key)) out[key] = val;
+  }
+  return out;
+}
+
+/** stderr 打印（诊断信息不污染 stdout 的机器友好 summary）。 */
+function err(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+
+function mimeFromPath(path) {
+  const ext = extname(path || '').toLowerCase();
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.png') return 'image/png';
+  if (ext === '.gif') return 'image/gif';
+  if (ext === '.webp') return 'image/webp';
+  return 'application/octet-stream';
+}
+
+async function imageInputToUrl(input) {
+  if (!input) return undefined;
+  if (/^https?:\/\//i.test(input) || input.startsWith('data:image/')) return input;
+  const st = await stat(input);
+  const maxBytes = 10 * 1024 * 1024;
+  if (st.size > maxBytes) {
+    throw new Error(`输入图片超过 10MB：${input} (${st.size} bytes)`);
+  }
+  const buf = await readFile(input);
+  return `data:${mimeFromPath(input)};base64,${buf.toString('base64')}`;
+}
+
+// ============================================================
+//  2. 配置（OPENAI_IMAGE_* 命名空间，独立于聊天 LLM）
+// ============================================================
+
+/**
+ * 读环境变量得到 provider 配置；缺任一必需项返回 null（调用方据此优雅报错）。
+ *   OPENAI_IMAGE_BASE_URL / OPENAI_IMAGE_API_KEY / OPENAI_IMAGE_MODEL  —— 必需
+ *   OPENAI_IMAGE_TIMEOUT_MS（默认 240s）/ OPENAI_IMAGE_MAX_RETRIES（默认 3）—— 可选
+ */
+function loadProvider(modelOverride) {
+  const baseURL = process.env.OPENAI_IMAGE_BASE_URL;
+  const apiKey = process.env.OPENAI_IMAGE_API_KEY;
+  const model = modelOverride || process.env.OPENAI_IMAGE_MODEL;
+  if (!baseURL || !apiKey || !model) return null;
+  return { baseURL, apiKey, model };
+}
+
+// 单次尝试超时：默认 240s（覆盖「1 分钟甚至更久」的慢渲染）。注意上游若用 Bash 工具调本脚本，
+// Bash 默认只给 120s——必须显式把 Bash 的 timeout 设到 ~600s，否则本脚本的超时/重试来不及生效
+// 进程就被 OS 杀掉。240s × 2 次尝试 ≈ 480s，落在 Bash 10 分钟上限内，能在被杀前自己返回干净错误。
+const TIMEOUT_MS = (() => {
+  const v = Number(process.env.OPENAI_IMAGE_TIMEOUT_MS);
+  // 成本不计、最大努力生图：单次默认放宽到 600s（原 240s 偏紧，大分辨率慢渲染易超时降级）；env 可覆盖。
+  return Number.isFinite(v) && v > 0 ? v : 600_000;
+})();
+
+const MAX_ATTEMPTS = (() => {
+  const v = Number(process.env.OPENAI_IMAGE_MAX_RETRIES);
+  return Number.isFinite(v) && v >= 1 ? Math.floor(v) : 3;
+})();
+
+// ============================================================
+//  3. 重试 / 退避 / data URL 解码（精简自原 imageClient.ts）
+// ============================================================
+
+/** 可重试状态码：408/425/429/5xx（其余 4xx 重试无意义）。 */
+function isRetryable(status) {
+  return status === 408 || status === 425 || status === 429 || (status >= 500 && status < 600);
+}
+
+/** 鉴权错误：明确告知 key 失效/无权，不浪费重试。 */
+function isAuthError(status) {
+  return status === 401 || status === 403;
+}
+
+/** 指数退避：0.5s → 1s → 2s …，封顶 8s，±15% 抖动。 */
+function backoffMs(attempt) {
+  const base = Math.min(500 * 2 ** (attempt - 1), 8_000);
+  return Math.round(base * (0.85 + Math.random() * 0.3));
+}
+
+/** Retry-After 头（秒），封顶 60s；无效返回 undefined。 */
+function parseRetryAfter(resp) {
+  const h = resp.headers.get('retry-after');
+  if (!h) return undefined;
+  const sec = Number.parseFloat(h);
+  if (!Number.isFinite(sec) || sec < 0) return undefined;
+  return Math.min(sec * 1000, 60_000);
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** 解析 `data:<mime>;base64,<payload>` → Buffer（兼容无 mime / 非 base64）。 */
+function dataUrlToBuffer(dataUrl) {
+  const comma = dataUrl.indexOf(',');
+  if (!dataUrl.startsWith('data:') || comma === -1) {
+    throw new Error(`不是合法的 data URL（应以 "data:" 开头并含 ","）：${dataUrl.slice(0, 64)}…`);
+  }
+  const header = dataUrl.slice(5, comma);
+  const payload = dataUrl.slice(comma + 1);
+  const isB64 = /;base64/i.test(header);
+  return isB64
+    ? Buffer.from(payload, 'base64')
+    : Buffer.from(decodeURIComponent(payload), 'utf8');
+}
+
+/** 从 message.images[] 抽第一个可用 data URL（兼容 {image_url:{url}} 与 {url}）。 */
+function firstImageUrl(message) {
+  const images = message?.images;
+  if (!Array.isArray(images)) return undefined;
+  for (const item of images) {
+    const url = item?.image_url?.url ?? item?.url;
+    if (typeof url === 'string' && url.length > 0) return url;
+  }
+  return undefined;
+}
+
+/** 从 Images API 的 `data[0]` 抽图：优先 b64_json（base64），否则 url（需再下载）。 */
+function firstImageFromData(data) {
+  const item = Array.isArray(data?.data) ? data.data[0] : undefined;
+  if (!item) return undefined;
+  if (typeof item.b64_json === 'string' && item.b64_json.length > 0) {
+    return { kind: 'b64', value: item.b64_json };
+  }
+  if (typeof item.url === 'string' && item.url.length > 0) {
+    return { kind: 'url', value: item.url };
+  }
+  return undefined;
+}
+
+// ============================================================
+//  3.5 协议选择 + 按协议组装请求 / 取图 / 降级（chat vs images 双栈）
+// ============================================================
+
+/**
+ * 选协议：OPENAI_IMAGE_PROTOCOL 显式优先（chat|images），否则按 OPENAI_IMAGE_PROVIDER 静态查表推断。
+ * 原生 Images API 那一类（OpenAI/Azure/火山方舟 Seedream）→ images；其余（含 OpenRouter、未设）→ chat。
+ * 纯确定性映射 + 可显式覆盖，不是 LLM 猜测。
+ */
+function resolveProtocol() {
+  const explicit = (process.env.OPENAI_IMAGE_PROTOCOL || '').trim().toLowerCase();
+  if (explicit === 'chat' || explicit === 'images') return explicit;
+  const provider = (process.env.OPENAI_IMAGE_PROVIDER || '').trim().toLowerCase();
+  const IMAGES_PROVIDERS = new Set(['volces', 'volces-plan', 'ark', 'doubao', 'seedream', 'openai', 'azure']);
+  return IMAGES_PROVIDERS.has(provider) ? 'images' : 'chat';
+}
+
+/**
+ * Images API 的 size 归一化：火山 Seedream 只认 `2k/3k/4k`（小写）或 `WIDTHxHEIGHT`，**没有 1k 档**。
+ * - 显式 `WxH` 原样透传；
+ * - 档位统一小写；`1k`（如 ppt.yaml 写死的 `--size 1K`）抬到 `2k`（PPT 清晰度足够、是该模型的下限）；
+ * - 其余非法值交给 400 降级（去掉 size 走默认 2048×2048）兜底。
+ */
+function normalizeImagesSize(size) {
+  if (!size) return '2k';
+  if (/^\d+x\d+$/i.test(size)) return size;
+  const lower = size.toLowerCase();
+  return lower === '1k' ? '2k' : lower;
+}
+
+/** 按协议组装 { url, body, kind }。kind 用于后续取图/降级分派。 */
+function buildRequest(protocol, provider, args, aspectHint, inputImageUrl) {
+  const base = provider.baseURL.replace(/\/$/, '');
+  if (protocol === 'images') {
+    const body = {
+      model: provider.model,
+      prompt: args.prompt + aspectHint, // aspect 在 images 路径只能靠 prompt 软引导
+      size: normalizeImagesSize(args.size),
+      response_format: 'b64_json', // 直接拿 base64，省一次 url 下载；端点不支持时回退 url
+      watermark: false, // PPT 配图不要水印
+    };
+    if (inputImageUrl) {
+      // 火山/BytePlus Seedream 的统一生成/编辑接口在 /images/generations 上通过 image 传参考图。
+      // 多数 OpenAI 兼容网关也接受同名扩展参数；若端点不支持，会走 400 显性失败，避免静默变成纯文生图。
+      body.image = inputImageUrl;
+    }
+    return { url: `${base}/images/generations`, body, kind: 'images' };
+  }
+  // chat（默认，向后兼容 OpenRouter 多模态）
+  const body = {
+    model: provider.model,
+    messages: [{ role: 'user', content: args.prompt + aspectHint }],
+    modalities: ['image', 'text'],
+  };
+  if (inputImageUrl) {
+    body.messages[0].content = [
+      { type: 'text', text: args.prompt + aspectHint },
+      { type: 'image_url', image_url: { url: inputImageUrl } },
+    ];
+  }
+  if (args.aspect || args.size) {
+    body.image_config = {};
+    if (args.aspect) body.image_config.aspect_ratio = args.aspect;
+    if (args.size) body.image_config.image_size = args.size;
+  }
+  return { url: `${base}/chat/completions`, body, kind: 'chat' };
+}
+
+/** 从 200 响应里按协议取图，返回 {kind,value} 或 undefined（undefined → 当「200 无图」可重试）。 */
+function extractImage(kind, data) {
+  return kind === 'images'
+    ? firstImageFromData(data)
+    : (() => {
+        const url = firstImageUrl(data?.choices?.[0]?.message);
+        return url ? { kind: 'dataurl', value: url } : undefined;
+      })();
+}
+
+/**
+ * 400 优雅降级：去掉端点可能不认的可选参数，原地 mutate body。
+ * 返回降级动作文案（用于日志）；无可去参数返回 null（调用方据此判定 400 不可救）。
+ */
+function degradeBody(kind, body) {
+  if (kind === 'images') {
+    if (body.size === undefined) return null;
+    delete body.size; // 走默认 2048×2048
+    return '去掉 size 参数走默认尺寸重发';
+  }
+  if (!body.image_config) return null;
+  delete body.image_config;
+  return '去掉比例参数重发（aspect 改由提示词软引导）';
+}
+
+/** 把取到的图片源解码/下载成 Buffer。dataurl/b64 本地解码；url 再发一次 GET。 */
+async function srcToBuffer(src, timeoutMs) {
+  if (src.kind === 'dataurl') return dataUrlToBuffer(src.value);
+  if (src.kind === 'b64') return Buffer.from(src.value, 'base64');
+  // src.kind === 'url'：response_format=url 时图片是个外链，下载回来。
+  const resp = await fetch(src.value, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!resp.ok) throw new Error(`下载图片 URL 失败 [${resp.status} ${resp.statusText}]`);
+  return Buffer.from(await resp.arrayBuffer());
+}
+
+// ============================================================
+//  4. 主流程
+// ============================================================
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  // —— 参数校验 ——
+  if (!args.prompt || !args.out) {
+    err('用法：node generate.mjs --prompt "<英文提示词>" --out <路径> [--aspect 16:9] [--size 2K] [--input-image <路径或URL>] [--model <id>]');
+    err('错误：--prompt 和 --out 均为必填。');
+    process.exit(2);
+  }
+
+  // —— provider ——
+  const provider = loadProvider(args.model);
+  if (!provider) {
+    err('错误：未配置图片生成（缺少环境变量 OPENAI_IMAGE_BASE_URL / OPENAI_IMAGE_API_KEY / OPENAI_IMAGE_MODEL）。');
+    process.exit(3);
+  }
+
+  // —— 组装请求（按协议分派 chat / images）——
+  // aspect 软引导：拼一句构图提示（端点忽略原生比例参数时仍有作用，两套协议共用）。
+  const protocol = resolveProtocol();
+  const aspectHint = args.aspect ? `\n\n(Compose for a ${args.aspect} aspect ratio.)` : '';
+  let inputImageUrl;
+  try {
+    inputImageUrl = await imageInputToUrl(args['input-image']);
+  } catch (e) {
+    err(`错误：读取输入图片失败：${e?.message ?? e}`);
+    process.exit(2);
+  }
+  const { url, body, kind } = buildRequest(protocol, provider, args, aspectHint, inputImageUrl);
+
+  if (args['dry-run-request'] !== undefined) {
+    process.stdout.write(JSON.stringify({
+      url,
+      kind,
+      body,
+      hasInputImage: Boolean(inputImageUrl),
+    }, null, 2) + '\n');
+    process.exit(0);
+  }
+
+  const headers = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${provider.apiKey}`,
+  };
+  let payload = JSON.stringify(body);
+
+  // —— 开跑诊断（stderr，绝不打 key / 不打 baseURL 全文，只打 host）——
+  const host = (() => {
+    try { return new URL(url).host; } catch { return '(unknown host)'; }
+  })();
+  err(
+    `[ai-image] protocol=${kind} model=${provider.model} aspect=${args.aspect ?? 'n/a'} size=${args.size ?? 'n/a'} ` +
+      `input=${inputImageUrl ? 'yes' : 'no'} → POST ${host}（单次超时 ${Math.round(TIMEOUT_MS / 1000)}s，最多 ${MAX_ATTEMPTS} 次）`,
+  );
+
+  // —— 带重试的 POST ——
+  let resp;
+  let data; // 解析后的 JSON（成功路径在循环内填）
+  let imgSrc; // 取到的图片源 {kind,value}（循环内填）
+  let lastErr;
+  let degraded = false; // 是否已为「端点拒绝可选参数」做过去参降级
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    const t0 = Date.now();
+    err(`[ai-image] attempt ${attempt}/${MAX_ATTEMPTS}：发送请求…`);
+    try {
+      resp = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: payload,
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+    } catch (e) {
+      // 超时 / 网络错 → 可重试
+      const secs = ((Date.now() - t0) / 1000).toFixed(1);
+      lastErr = new Error(`网络错误 [${e?.name ?? 'NetworkError'}]：${e?.message ?? e}`);
+      err(`[ai-image] attempt ${attempt} 网络错/超时（${secs}s）：${e?.name ?? 'NetworkError'} ${e?.message ?? e}`);
+      if (attempt >= MAX_ATTEMPTS) break;
+      await sleep(backoffMs(attempt));
+      continue;
+    }
+
+    const secs = ((Date.now() - t0) / 1000).toFixed(1);
+    if (resp.ok) {
+      // 200 后**就地解析取图**：解析失败 / 「200 但无图」都视为可重试——模型偶发只回文本
+      // （message.images 为空），此前这种情况硬退出 1，逼上游 agent 自己重发；现在脚本内重试。
+      try {
+        data = await resp.json();
+      } catch (e) {
+        lastErr = new Error(`响应不是合法 JSON：${e?.message ?? e}`);
+        err(`[ai-image] attempt ${attempt} 收到 200（${secs}s）但 JSON 解析失败，将退避重试：${e?.message ?? e}`);
+        if (attempt >= MAX_ATTEMPTS) break;
+        await sleep(backoffMs(attempt));
+        continue;
+      }
+      imgSrc = extractImage(kind, data);
+      if (imgSrc) {
+        err(`[ai-image] attempt ${attempt} 收到 200（${secs}s），已取到图片。`);
+        break;
+      }
+      lastErr = new Error('返回 200 但未包含任何图片（message.images / data[] 为空）');
+      err(
+        `[ai-image] attempt ${attempt} 收到 200（${secs}s）但响应无图片，将退避重试。` +
+          `响应片段：${JSON.stringify(data).slice(0, 200)}`,
+      );
+      if (attempt >= MAX_ATTEMPTS) break;
+      await sleep(backoffMs(attempt));
+      continue;
+    }
+
+    const errText = await resp.text().catch(() => '');
+    if (isAuthError(resp.status)) {
+      // 鉴权失败：响亮失败，绝不回显 key 本身
+      err(`错误：图片生成鉴权失败 [${resp.status} ${resp.statusText}]——API key 可能失效/过期/无权访问该模型。`);
+      err(`请检查 .env 的 OPENAI_IMAGE_API_KEY / OPENAI_IMAGE_BASE_URL / OPENAI_IMAGE_MODEL。`);
+      err(`原始错误：${errText.slice(0, 300)}`);
+      process.exit(1);
+    }
+    // 400 优雅降级：端点可能不认可选参数（chat 的 image_config / images 的 size）、直接回 400。
+    // 去掉该参数重发一次（aspect 仍靠 prompt 软引导 + 导出端 object-fit 兜底几何）。
+    // 镜像聊天 client.ts「provider 拒绝大 max_tokens 就去掉重发」的既有降级范式。
+    if (resp.status === 400 && !degraded) {
+      const action = degradeBody(kind, body);
+      if (action) {
+        degraded = true;
+        payload = JSON.stringify(body);
+        err(
+          `[ai-image] attempt ${attempt} 端点拒绝参数 [400]（${secs}s），${action}。` +
+            `原始错误：${errText.slice(0, 200)}`,
+        );
+        continue; // 直接用新 payload 重发，不退避
+      }
+    }
+    if (!isRetryable(resp.status)) {
+      err(`错误：图片生成请求失败 [${resp.status} ${resp.statusText}]：${errText.slice(0, 300)}`);
+      process.exit(1);
+    }
+    lastErr = new Error(`[${resp.status} ${resp.statusText}]：${errText.slice(0, 300)}`);
+    err(`[ai-image] attempt ${attempt} 失败 [${resp.status} ${resp.statusText}]（${secs}s），将退避重试。`);
+    if (attempt >= MAX_ATTEMPTS) break;
+    await sleep(parseRetryAfter(resp) ?? backoffMs(attempt));
+  }
+
+  // 重试用尽仍无图：响亮失败。区分「始终 200 但无图」与「网络/HTTP 失败」两类诊断。
+  if (!imgSrc) {
+    if (resp && resp.ok) {
+      err(`错误：返回成功但始终未包含图片（重试 ${MAX_ATTEMPTS} 次，images/data[] 一直为空）。`);
+      err(
+        kind === 'images'
+          ? `请确认模型 "${provider.model}" 支持 /images/generations 且能返回 b64_json/url。`
+          : `请确认模型 "${provider.model}" 支持图像输出、且端点接受 modalities=["image","text"]。`,
+      );
+      if (data) err(`最后响应片段：${JSON.stringify(data).slice(0, 400)}`);
+    } else {
+      err(`错误：图片生成失败（重试 ${MAX_ATTEMPTS} 次后仍未成功）：${lastErr?.message ?? '未知错误'}`);
+    }
+    process.exit(1);
+  }
+
+  // —— 解码（dataurl/b64 本地解码；url 再下载）落盘 ——
+  let buffer;
+  try {
+    buffer = await srcToBuffer(imgSrc, TIMEOUT_MS);
+  } catch (e) {
+    err(`错误：图片解码/下载失败：${e?.message ?? e}`);
+    process.exit(1);
+  }
+
+  try {
+    await mkdir(dirname(args.out), { recursive: true });
+    await writeFile(args.out, buffer);
+  } catch (e) {
+    err(`错误：写入文件失败（${args.out}）：${e?.message ?? e}`);
+    process.exit(1);
+  }
+
+  // —— 机器友好 summary（仅这一行进 stdout，便于上游 capture/regex）——
+  process.stdout.write(
+    `saved: ${args.out} (model=${provider.model}, bytes=${buffer.length}, aspect=${args.aspect ?? 'n/a'})\n`,
+  );
+  process.exit(0);
+}
+
+main().catch((e) => {
+  // 兜底：任何未预期异常都响亮失败，不回显 key
+  err(`错误：未预期异常：${e?.message ?? e}`);
+  process.exit(1);
+});