@xinizai/pi-image-gen 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.1.2 - 2026-08-21
+
+### 修复（Fixed）
+- README：修正「每几十秒只吐 1 字节」处被误写为 ASCII 残留「`/sql1`」的乱码。
+- README：移除指向 unpkg 直链的 CHANGELOG 链接（unpkg 对 `.md` 直发 `text/markdown` 无 charset，中文 Windows 下浏览器按 GBK 解码会乱码），改为提示在 npm 包页 Code/Files 选项卡查看。
+
+## 0.1.1 - 2026-08-21
+
+### 固定（Fixed）
+- 修复「中转站出图慢但已成功仍被判超时」的问题：`fetchWithTimeout` 由「固定 60 秒死闸」改为「stall 续命」——只要持续有字节到达就自动重新计 timing，不再因总时长把慢请求误杀（这是本次主要修复，对应报告中途已生成图片却被报「请求超时」的现象）。
+- 总时长兜底：新增可选的「总闸」`IMAGE_TOTAL_TIMEOUT_SECONDS`（默认 600 秒 / 10 分钟），防止被「每几十秒只吐 1 字节」的续活死链无限挂起；之前版本默认「0 = 不限」存在被吊死风险。
+- 修复与其相关的次生错误「Stream ended without finish_reason」：`image_generate` / `image_edit` / `image_variation` 在失败时不再向 pi 主程序 `throw`，改为返回结构化文本，避免主程序因异常触发流式重试对话导致的断流报错。
+- 修复 `responseFormat=auto` 时硬塞 `response_format: "url"` 导致某些中转站绕一圈下载、变慢且易撞超时的问题；新版本在 `auto` 模式下不再发送该字段，让服务端用它最快/最顺手的方式回。
+
+### 变更（Changed）
+- `responseFormat` 兼容性重试方向与策略调整：当服务端明确拒绝 `response_format` 字段时，再带 800 毫秒退避做一次无费用重试（auto 模式补 `url`，显式 `url`/`b64_json` 模式改为不发字段），避免对可能已计费的出图请求做无意义重发。
+- 图片下载与生成请求超时解耦：新增 `IMAGE_DOWNLOAD_TIMEOUT_SECONDS`（默认 60 秒）独立计时，避免下载阶段与生成阶段计时叠加误杀。
+- 超时/网络错误文案改为温和提示「中转站可能其实已经生成，请稍后重试或检查输出目录」，不再误报「未生成成功」。
+
+### 新增（Added）
+- 新增环境变量 `IMAGE_TOTAL_TIMEOUT_SECONDS`（总时长上限，默认 600 秒）。
+- 新增环境变量 `IMAGE_DOWNLOAD_TIMEOUT_SECONDS`（图片下载独立超时，默认 60 秒）。
+- 新增 CHANGELOG 文件。
+
+---
+
+## 0.1.0 - 初次发布
+
+- 通用 OpenAI-compatible 图片生成扩展，自动模型发现、能力识别、`/image-config` 面板管理。

package/README.md

@@ -4,6 +4,22 @@
 
 > 第一版重点支持 OpenAI-compatible API：`GET /models`、`POST /images/generations`、`POST /images/edits`、`POST /images/variations`。其它 Provider 通过 Adapter 架构预留。
 
+## 最新更新（0.1.2）
+
+- **文档修复**：上版 README 里「每几十秒只吐 1 字节」被误写为 ASCII 残留「`/sql1`」，已修正为正常中文。
+- **文档修复**：去掉 README 中指向 unpkg 直链的 CHANGELOG 链接——unpkg 对 `.md` 直发 `text/markdown` 不含 charset 在中文 Windows 下会乱码；改提示「在 npm 包页 Code/Files 选项卡查看 CHANGELOG」。
+
+---
+
+## 历史更新（0.1.1）
+
+- **修复**：中转站出图慢但已成功返回仍被判“请求超时”的问题 —— 超时改为“stall 续命”（只要持续有字节到达就自动续期），不再用固定 60 秒死闸误杀慢请求。
+- **修复**：连带报错 `Stream ended without finish_reason` —— 失败时不再向 pi 主程序抛异常，避免主程序触发流式重试导致的断流。
+- **修复**：`responseFormat=auto` 不再硬塞 `response_format: "url"`，让中转站用它最快的方式回，出图更稳更快。
+- **新增**：总时长兜底环境变量 `IMAGE_TOTAL_TIMEOUT_SECONDS`（默认 600 秒）防被「每几十秒只吐 1 字节」的续活死链无限挂起；图片下载独立超时 `IMAGE_DOWNLOAD_TIMEOUT_SECONDS`（默认 60 秒）。
+
+完整的更新记录见包内 `CHANGELOG.md`（在 npm 包页「Code」/ Files 选项卡查看，避免 unpkg 直链因无 charset 显示乱码）。
+
 ## 功能
 
 - 通过唯一用户入口 `/image-config` 管理多个跨项目共享的 Provider（环境变量仍可作为兼容 fallback）
@@ -74,7 +90,9 @@ $env:IMAGE_API_KEY="sk-xxxx"
 export IMAGE_MODEL=gpt-image-1                 # fallback 或显式默认文生图模型
 export IMAGE_EDIT_MODEL=gpt-image-1            # 默认编辑模型
 export IMAGE_VARIATION_MODEL=dall-e-2          # 默认变体模型
-export IMAGE_TIMEOUT_SECONDS=60
+export IMAGE_TIMEOUT_SECONDS=60              # stall 超时：只要持续有字节到达就自动续期
+export IMAGE_TOTAL_TIMEOUT_SECONDS=600        # 总时长上限（默认 10 分钟），防被续活死链无限挂起
+export IMAGE_DOWNLOAD_TIMEOUT_SECONDS=60    # 图片下载独立超时（与生成请求解耦）
 export IMAGE_CACHE_TTL_SECONDS=600
 export IMAGE_OUTPUT_DIR=/path/to/generated
 export IMAGE_MAX_RESPONSE_BYTES=8000000

package/dist/core/global-config.js

@@ -113,6 +113,8 @@ export class GlobalConfigStore {
             responseFormat: provider.responseFormat ?? "auto",
             providerType: provider.providerType,
             timeoutMs: Number(env.IMAGE_TIMEOUT_SECONDS ?? 60) * 1000,
+            totalTimeoutMs: Number(env.IMAGE_TOTAL_TIMEOUT_SECONDS ?? 600) * 1000,
+            downloadTimeoutMs: Number(env.IMAGE_DOWNLOAD_TIMEOUT_SECONDS ?? 60) * 1000,
             cacheTtlMs: Number(env.IMAGE_CACHE_TTL_SECONDS ?? 600) * 1000,
             outputDir: env.IMAGE_OUTPUT_DIR ? resolve(env.IMAGE_OUTPUT_DIR) : resolve(homedir(), ".pi", "agent", "generated"),
             maxResponseBytes: Number(env.IMAGE_MAX_RESPONSE_BYTES ?? 8_000_000),

package/dist/index.js

@@ -1,7 +1,7 @@
 import { Type } from "@earendil-works/pi-ai";
 import { configErrorText, configText, createService, deleteProvider, discoverProviderCandidate, modelsText, providerStatus, providersText, resultText, saveProviderWithDiscovery, setDefaultProvider, updateProvider } from "./tools/shared.js";
 import { GlobalConfigStore } from "./core/global-config.js";
-import { maskApiKey } from "./core/errors.js";
+import { maskApiKey, ImageGenError } from "./core/errors.js";
 import { ModelRegistry } from "./core/model-registry.js";
 const OutputFormat = Type.Union([Type.Literal("png"), Type.Literal("jpeg"), Type.Literal("jpg"), Type.Literal("webp")]);
 export default function imageGenExtension(pi) {
@@ -26,7 +26,9 @@ export default function imageGenExtension(pi) {
                 return { content: [{ type: "text", text: resultText("图片生成", await (await createService(params.provider)).generate(params, signal)) }], details: {} };
             }
             catch (e) {
-                throw new Error(configErrorText(e));
+                // 不 throw：避免 pi 主程序因异常触发流式重试对话出现 "Stream ended without finish_reason"。
+                // timeout/network_error 时图片可能其实已出，提示用户检查输出目录。
+                return { content: [{ type: "text", text: softFailureText(e) }], details: {} };
             }
         },
     });
@@ -49,7 +51,7 @@ export default function imageGenExtension(pi) {
                 return { content: [{ type: "text", text: resultText("图片编辑", await (await createService(params.provider)).edit(params, signal)) }], details: {} };
             }
             catch (e) {
-                throw new Error(configErrorText(e));
+                return { content: [{ type: "text", text: softFailureText(e) }], details: {} };
             }
         },
     });
@@ -70,7 +72,7 @@ export default function imageGenExtension(pi) {
                 return { content: [{ type: "text", text: resultText("图片变体", await (await createService(params.provider)).variation(params, signal)) }], details: {} };
             }
             catch (e) {
-                throw new Error(configErrorText(e));
+                return { content: [{ type: "text", text: softFailureText(e) }], details: {} };
             }
         },
     });
@@ -487,4 +489,15 @@ async function saveProviderWithoutDiscovery(input, store) {
         await store.setDefaultProvider(provider.id);
     return [`提供商已保存：${provider.name} (${provider.id})`, `默认模型：${provider.defaultModel ?? "未设置"}`, "模型发现：未执行，已手动指定模型。"].join("\n");
 }
+function softFailureText(e) {
+    const isSoft = e instanceof ImageGenError && (e.code === "timeout" || e.code === "network_error");
+    const base = configErrorText(e);
+    if (!isSoft)
+        return `图片生成请求未成功完成。\n原因：${base}`;
+    return [
+        "图片生成请求被中断（超时/网络），但中转站可能其实已经生成，请稍后重试或检查输出目录。",
+        `原因：${base}`,
+        "提示：生成慢时可调大 IMAGE_TIMEOUT_SECONDS，或设置 IMAGE_TOTAL_TIMEOUT_SECONDS 给一个更宽松的总时长上限。",
+    ].join("\n");
+}
 //# sourceMappingURL=index.js.map

package/dist/providers/openai-compatible.js

@@ -41,8 +41,9 @@ export class OpenAICompatibleProvider {
         return models;
     }
     async generate(params, signal) {
-        // auto 优先 URL（便于流式/CDN 服务），仅在服务端明确拒绝时降级为 b64_json。
-        const responseFormat = this.config.responseFormat === "b64_json" ? "b64_json" : "url";
+        // auto：不发送 response_format 字段，让服务商用它最快/最顺手的方式返回；
+        // 仅当用户显式选择 url 或 b64_json 时才发送字段。
+        const responseFormat = this.config.responseFormat === "b64_json" || this.config.responseFormat === "url" ? this.config.responseFormat : undefined;
         const caps = params.modelCapabilities;
         const body = compact({ model: params.model, prompt: params.prompt, size: caps?.supportsSize === false ? undefined : params.size, quality: caps?.supportsQuality === false ? undefined : params.quality, n: caps?.supportsMultipleImages === false ? 1 : params.n ?? 1, response_format: responseFormat, output_format: params.output_format, aspect_ratio: caps?.supportsAspectRatio === false ? undefined : params.aspect_ratio });
         const json = await this.postImage("/images/generations", body, "生成图片", signal);
@@ -77,12 +78,24 @@ export class OpenAICompatibleProvider {
         const isForm = body instanceof FormData;
         let response = await this.request("POST", path, isForm ? body : JSON.stringify(body), action, signal, isForm ? undefined : "application/json");
         let detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
-        // 不同 OpenAI-compatible 服务对 response_format 的支持不一致；仅在服务端明确拒绝该字段时做一次无费用重试。
+        // 不同 OpenAI-compatible 服务对 response_format 的支持不一致；
+        // auto 模式默认不发字段，若服务端反而要求字段，尝试补上 url；
+        // 若用户明确 url/b64_json 而服务端拒绝该值，则降级为不发字段或交换为另一值。
         const jsonBody = !isForm && typeof body === "object" && body !== null && !ArrayBuffer.isView(body) && !(body instanceof ArrayBuffer) && !(body instanceof Blob) && !(body instanceof URLSearchParams) ? body : undefined;
-        if (!response.ok && this.config.responseFormat !== "url" && this.config.responseFormat !== "b64_json" && jsonBody?.response_format === "url" && isResponseFormatError(detail)) {
-            const retryBody = { ...jsonBody, response_format: "b64_json" };
-            response = await this.request("POST", path, JSON.stringify(retryBody), action, signal, "application/json");
-            detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
+        if (!response.ok && jsonBody && isResponseFormatError(detail)) {
+            if (jsonBody.response_format === undefined) {
+                const retryBody = { ...jsonBody, response_format: "url" };
+                await sleep(800, signal);
+                response = await this.request("POST", path, JSON.stringify(retryBody), action, signal, "application/json");
+                detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
+            }
+            else {
+                const retryBody = { ...jsonBody };
+                delete retryBody.response_format;
+                await sleep(800, signal);
+                response = await this.request("POST", path, JSON.stringify(retryBody), action, signal, "application/json");
+                detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
+            }
         }
         if (!response.ok)
             throw errorFromStatus(response.status, action, detail);
@@ -101,7 +114,8 @@ export class OpenAICompatibleProvider {
                 init.body = body;
             if (signal !== undefined)
                 init.signal = signal;
-            return await fetchWithTimeout(`${this.config.baseUrl}${path}`, init, this.config.timeoutMs);
+            // stall 超时 + 可选总超时：慢中转站只要持续吐字节就不被换杀。
+            return await fetchWithTimeout(`${this.config.baseUrl}${path}`, init, this.config.timeoutMs, { stallMs: this.config.timeoutMs, totalMs: this.config.totalTimeoutMs ?? 0 });
         }
         catch (e) {
             if (e instanceof ImageGenError)
@@ -142,7 +156,7 @@ export class OpenAICompatibleProvider {
                 }
                 const imageUrl = resolveImageUrl(rawUrl, this.config.baseUrl);
                 const authorization = isSameOrigin(imageUrl, this.config.baseUrl) ? `Bearer ${this.config.apiKey}` : undefined;
-                const saved = await downloadImage(imageUrl, this.config.outputDir, this.config.timeoutMs, this.config.maxDownloadBytes, authorization);
+                const saved = await downloadImage(imageUrl, this.config.outputDir, this.config.downloadTimeoutMs ?? this.config.timeoutMs, this.config.maxDownloadBytes, authorization, { totalMs: this.config.totalTimeoutMs ?? 0 });
                 images.push({ path: saved.path, url: imageUrl, mimeType: saved.mimeType, index });
             }
         }
@@ -154,7 +168,7 @@ export class OpenAICompatibleProvider {
 async function resolveImageInput(input, config, signal) {
     if (/^https?:\/\//i.test(input)) {
         const authorization = isSameOrigin(input, config.baseUrl) ? `Bearer ${config.apiKey}` : undefined;
-        const saved = await downloadImage(input, config.outputDir, config.timeoutMs, config.maxDownloadBytes, authorization);
+        const saved = await downloadImage(input, config.outputDir, config.downloadTimeoutMs ?? config.timeoutMs, config.maxDownloadBytes, authorization, { totalMs: config.totalTimeoutMs ?? 0 });
         const local = await loadLocalImage(saved.path);
         return local;
     }
@@ -189,7 +203,17 @@ function extractImageValue(value) {
     return undefined;
 }
 function isResponseFormatError(detail) {
-    return Boolean(detail && /response_format|b64_json|base64.*format/i.test(detail));
+    return Boolean(detail && /response_format|b64_json|base64.*format|unsupported.*param|unrecognized.*param/i.test(detail));
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new ImageGenError("network_error", "请求已取消。", "重新发起操作即可。 "));
+            return;
+        }
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => { clearTimeout(t); reject(new ImageGenError("network_error", "请求已取消。", "重新发起操作即可。 ")); }, { once: true });
+    });
 }
 function isSameOrigin(imageUrl, baseUrl) {
     try {

package/dist/utils/config.js

@@ -54,6 +54,11 @@ export function readConfig(env = process.env) {
         responseFormat: "auto",
         providerType: "openai-compatible",
         timeoutMs: Number(env.IMAGE_TIMEOUT_SECONDS ?? 60) * 1000,
+        // stall 超时之上再叠加一个“无脑继续等”的兜底：默认 0 = 不限总时长。
+        // 出图慢的中转站只要持续吐字节就不会被掐断。
+        totalTimeoutMs: Number(env.IMAGE_TOTAL_TIMEOUT_SECONDS ?? 600) * 1000,
+        // 图片下载与生成请求解耦，独立计时；默认与生成一致以免误杀。
+        downloadTimeoutMs: Number(env.IMAGE_DOWNLOAD_TIMEOUT_SECONDS ?? 60) * 1000,
         cacheTtlMs: Number(env.IMAGE_CACHE_TTL_SECONDS ?? 600) * 1000,
         outputDir,
         maxResponseBytes: Number(env.IMAGE_MAX_RESPONSE_BYTES ?? 8_000_000),

package/dist/utils/download.js

@@ -16,22 +16,70 @@ export function assertSafeHttpUrl(raw) {
         throw new ImageGenError("invalid_image", "图片 URL 目标地址不安全。", "不能访问 localhost、内网地址或云元数据地址。 ");
     return url;
 }
-export async function fetchWithTimeout(url, init, timeoutMs) {
+/**
+ * stall 超时：只要持续有字节到达就自动续期，只有“无任何字节”超过 stallMs 才超时。
+ * totalMs（>0 时为绝对上限，0 表示不限总时长）：真死链兜底。
+ * 实现：拿到响应后由本函数亲自驱动 body 读取，边读边续 stall；不重新包装 ReadableStream，
+ * 避免 node 18 下 “包装流 + AbortController” 在 Windows 上的 libuv 崩溃。
+ */
+export async function fetchWithTimeout(url, init, timeoutMs, opts) {
+    const stallMs = opts?.stallMs ?? timeoutMs;
+    const totalMs = opts?.totalMs ?? 0;
+    const onProgress = opts?.onProgress;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let stallTimer;
+    let totalTimer;
+    const armStall = () => {
+        clearTimeout(stallTimer);
+        stallTimer = setTimeout(() => controller.abort(), stallMs);
+    };
+    armStall();
+    if (totalMs > 0)
+        totalTimer = setTimeout(() => controller.abort(), totalMs);
     try {
         const signal = init.signal ? AbortSignal.any([init.signal, controller.signal]) : controller.signal;
-        return await fetch(url, { ...init, signal });
+        const response = await fetch(url, { ...init, signal });
+        // 首字节已到，续命一次
+        armStall();
+        const body = response.body;
+        if (!body) {
+            if (onProgress)
+                onProgress(0);
+            return response;
+        }
+        // 亲自驱动读取：边读边续 stall，避免慢流被整体总时长误杀；读完拼回完整 body。
+        const reader = body.getReader();
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                armStall();
+                total += value.byteLength;
+                if (onProgress)
+                    onProgress(value.byteLength);
+                chunks.push(value);
+            }
+        }
+        reader.releaseLock();
+        const buffer = Buffer.concat(chunks.length ? chunks : []);
+        return new Response(buffer, { headers: response.headers, status: response.status, statusText: response.statusText });
     }
     catch (e) {
-        if (controller.signal.aborted)
-            throw new ImageGenError("timeout", "请求超时。", "稍后重试或增大 IMAGE_TIMEOUT_SECONDS。 ");
+        if (controller.signal.aborted) {
+            const totalHit = totalMs > 0;
+            throw new ImageGenError("timeout", totalHit ? "请求超时（已达总时长上限）。" : "请求超时。", "稍后重试，或增大 IMAGE_TIMEOUT_SECONDS / IMAGE_TOTAL_TIMEOUT_SECONDS。 ");
+        }
         if (e instanceof Error && e.name === "AbortError")
             throw new ImageGenError("network_error", "请求已取消。", "重新发起操作即可。 ");
         throw new ImageGenError("network_error", "网络请求失败。", e instanceof Error ? e.message : "检查网络连接。 ");
     }
     finally {
-        clearTimeout(timer);
+        clearTimeout(stallTimer);
+        if (totalTimer)
+            clearTimeout(totalTimer);
     }
 }
 export async function readResponseTextLimited(response, maxBytes) {
@@ -81,7 +129,8 @@ function rejectHtml(buffer) {
     if (prefix.startsWith("<!doctype html") || prefix.startsWith("<html") || prefix.startsWith("<head") || prefix.startsWith("<body"))
         throw new ImageGenError("invalid_image", "下载内容不是图片，可能是鉴权页或错误页面。", "检查 Provider 图片 URL 和权限。 ");
 }
-export async function downloadImage(url, outputDir, timeoutMs, maxBytes, authorization) {
+export async function downloadImage(url, outputDir, stallMs, maxBytes, authorization, opts) {
+    const totalMs = opts?.totalMs ?? 0;
     let target = assertSafeHttpUrl(url);
     if (await resolvesToPrivateHost(target.hostname))
         throw new ImageGenError("invalid_image", "图片 URL 解析到不安全的内网地址。", "不能访问 localhost、内网地址或云元数据地址。 ");
@@ -91,7 +140,7 @@ export async function downloadImage(url, outputDir, timeoutMs, maxBytes, authori
         const init = { method: "GET", redirect: "manual" };
         if (authorization && target.origin === origin)
             init.headers = { Authorization: authorization };
-        response = await fetchWithTimeout(target.toString(), init, timeoutMs);
+        response = await fetchWithTimeout(target.toString(), init, stallMs, { stallMs, totalMs });
         if (![301, 302, 303, 307, 308].includes(response.status))
             break;
         const location = response.headers.get("location");
@@ -136,4 +185,4 @@ export async function downloadImage(url, outputDir, timeoutMs, maxBytes, authori
     const path = await saveImageBuffer(content, outputDir, detected.ext);
     return { path, mimeType };
 }
-//# sourceMappingURL=download.js.map
+//# sourceMappingURL=download.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xinizai/pi-image-gen",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Universal Pi Agent image generation extension with OpenAI-compatible provider discovery.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
     "dist",
     "src",
     "README.md",
+    "CHANGELOG.md",
     "package.json"
   ],
   "scripts": {

package/src/core/global-config.ts

@@ -111,6 +111,8 @@ export class GlobalConfigStore {
       responseFormat: provider.responseFormat ?? "auto",
       providerType: provider.providerType,
       timeoutMs: Number(env.IMAGE_TIMEOUT_SECONDS ?? 60) * 1000,
+      totalTimeoutMs: Number(env.IMAGE_TOTAL_TIMEOUT_SECONDS ?? 600) * 1000,
+      downloadTimeoutMs: Number(env.IMAGE_DOWNLOAD_TIMEOUT_SECONDS ?? 60) * 1000,
       cacheTtlMs: Number(env.IMAGE_CACHE_TTL_SECONDS ?? 600) * 1000,
       outputDir: env.IMAGE_OUTPUT_DIR ? resolve(env.IMAGE_OUTPUT_DIR) : resolve(homedir(), ".pi", "agent", "generated"),
       maxResponseBytes: Number(env.IMAGE_MAX_RESPONSE_BYTES ?? 8_000_000),

package/src/core/types.ts

@@ -51,6 +51,10 @@ export interface ImageGenConfig {
   responseFormat: ImageResponseFormat;
   providerType: "openai-compatible";
   timeoutMs: number;
+  /** stall 超时之上再叠加一个“无脑继续等”的兜底；0 = 不限总时长。 */
+  totalTimeoutMs: number;
+  /** 图片下载独立超时，避免与生成请求计时叠加误杀。 */
+  downloadTimeoutMs: number;
   cacheTtlMs: number;
   outputDir: string;
   maxResponseBytes: number;

package/src/index.ts

@@ -2,7 +2,7 @@ import { Type } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { configErrorText, configText, createService, deleteProvider, discoverProviderCandidate, modelsText, providerStatus, providersText, resultText, saveProviderWithDiscovery, setDefaultProvider, updateProvider } from "./tools/shared.js";
 import { GlobalConfigStore } from "./core/global-config.js";
-import { maskApiKey } from "./core/errors.js";
+import { maskApiKey, ImageGenError } from "./core/errors.js";
 import { ModelRegistry } from "./core/model-registry.js";
 import type { DiscoveryResult, StoredProviderConfig } from "./core/types.js";
 
@@ -27,7 +27,7 @@ export default function imageGenExtension(pi: ExtensionAPI): void {
     }),
     async execute(_id, params, signal) {
       try { return { content: [{ type: "text", text: resultText("图片生成", await (await createService(params.provider)).generate(params, signal)) }], details: {} }; }
-      catch (e) { throw new Error(configErrorText(e)); }
+      catch (e) { return { content: [{ type: "text", text: softFailureText(e) }], details: {} }; }
     },
   });
 
@@ -47,7 +47,7 @@ export default function imageGenExtension(pi: ExtensionAPI): void {
     }),
     async execute(_id, params, signal) {
       try { return { content: [{ type: "text", text: resultText("图片编辑", await (await createService(params.provider)).edit(params, signal)) }], details: {} }; }
-      catch (e) { throw new Error(configErrorText(e)); }
+      catch (e) { return { content: [{ type: "text", text: softFailureText(e) }], details: {} }; }
     },
   });
 
@@ -65,7 +65,7 @@ export default function imageGenExtension(pi: ExtensionAPI): void {
     }),
     async execute(_id, params, signal) {
       try { return { content: [{ type: "text", text: resultText("图片变体", await (await createService(params.provider)).variation(params, signal)) }], details: {} }; }
-      catch (e) { throw new Error(configErrorText(e)); }
+      catch (e) { return { content: [{ type: "text", text: softFailureText(e) }], details: {} }; }
     },
   });
 
@@ -392,3 +392,14 @@ async function saveProviderWithoutDiscovery(input: { name: string; baseUrl: stri
   if (input.setDefault) await store.setDefaultProvider(provider.id);
   return [`提供商已保存：${provider.name} (${provider.id})`, `默认模型：${provider.defaultModel ?? "未设置"}`, "模型发现：未执行，已手动指定模型。"].join("\n");
 }
+
+function softFailureText(e: unknown): string {
+  const isSoft = e instanceof ImageGenError && (e.code === "timeout" || e.code === "network_error");
+  const base = configErrorText(e);
+  if (!isSoft) return `图片生成请求未成功完成。\n原因：${base}`;
+  return [
+    "图片生成请求被中断（超时/网络），但中转站可能其实已经生成，请稍后重试或检查输出目录。",
+    `原因：${base}`,
+    "提示：生成慢时可调大 IMAGE_TIMEOUT_SECONDS，或设置 IMAGE_TOTAL_TIMEOUT_SECONDS 给一个更宽松的总时长上限。",
+  ].join("\n");
+}

package/src/providers/openai-compatible.ts

@@ -40,8 +40,9 @@ export class OpenAICompatibleProvider implements ImageProvider {
   }
 
   async generate(params: GenerateParams, signal?: AbortSignal): Promise<ImageOperationResult> {
-    // auto 优先 URL（便于流式/CDN 服务），仅在服务端明确拒绝时降级为 b64_json。
-    const responseFormat = this.config.responseFormat === "b64_json" ? "b64_json" : "url";
+    // auto：不发送 response_format 字段，让服务商用它最快/最顺手的方式返回；
+    // 仅当用户显式选择 url 或 b64_json 时才发送字段。
+    const responseFormat = this.config.responseFormat === "b64_json" || this.config.responseFormat === "url" ? this.config.responseFormat : undefined;
     const caps = params.modelCapabilities;
     const body = compact({ model: params.model, prompt: params.prompt, size: caps?.supportsSize === false ? undefined : params.size, quality: caps?.supportsQuality === false ? undefined : params.quality, n: caps?.supportsMultipleImages === false ? 1 : params.n ?? 1, response_format: responseFormat, output_format: params.output_format, aspect_ratio: caps?.supportsAspectRatio === false ? undefined : params.aspect_ratio });
     const json = await this.postImage("/images/generations", body, "生成图片", signal);
@@ -75,12 +76,23 @@ export class OpenAICompatibleProvider implements ImageProvider {
     const isForm = body instanceof FormData;
     let response = await this.request("POST", path, isForm ? body : JSON.stringify(body), action, signal, isForm ? undefined : "application/json");
     let detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
-    // 不同 OpenAI-compatible 服务对 response_format 的支持不一致；仅在服务端明确拒绝该字段时做一次无费用重试。
+    // 不同 OpenAI-compatible 服务对 response_format 的支持不一致；
+    // auto 模式默认不发字段，若服务端反而要求字段，尝试补上 url；
+    // 若用户明确 url/b64_json 而服务端拒绝该值，则降级为不发字段。
     const jsonBody = !isForm && typeof body === "object" && body !== null && !ArrayBuffer.isView(body) && !(body instanceof ArrayBuffer) && !(body instanceof Blob) && !(body instanceof URLSearchParams) ? body as Record<string, unknown> : undefined;
-    if (!response.ok && this.config.responseFormat !== "url" && this.config.responseFormat !== "b64_json" && jsonBody?.response_format === "url" && isResponseFormatError(detail)) {
-      const retryBody = { ...jsonBody, response_format: "b64_json" };
-      response = await this.request("POST", path, JSON.stringify(retryBody), action, signal, "application/json");
-      detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
+    if (!response.ok && jsonBody && isResponseFormatError(detail)) {
+      if (jsonBody.response_format === undefined) {
+        const retryBody = { ...jsonBody, response_format: "url" };
+        await sleep(800, signal);
+        response = await this.request("POST", path, JSON.stringify(retryBody), action, signal, "application/json");
+        detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
+      } else {
+        const retryBody = { ...jsonBody };
+        delete retryBody.response_format;
+        await sleep(800, signal);
+        response = await this.request("POST", path, JSON.stringify(retryBody), action, signal, "application/json");
+        detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
+      }
     }
     if (!response.ok) throw errorFromStatus(response.status, action, detail);
     const json = await parseJsonLimited(response, this.config.maxResponseBytes) as OpenAIImageResponse;
@@ -95,7 +107,7 @@ export class OpenAICompatibleProvider implements ImageProvider {
       const init: RequestInit = { method, headers };
       if (body !== undefined) init.body = body;
       if (signal !== undefined) init.signal = signal;
-      return await fetchWithTimeout(`${this.config.baseUrl}${path}`, init, this.config.timeoutMs);
+      return await fetchWithTimeout(`${this.config.baseUrl}${path}`, init, this.config.timeoutMs, { stallMs: this.config.timeoutMs, totalMs: this.config.totalTimeoutMs ?? 0 });
     } catch (e) {
       if (e instanceof ImageGenError) throw new ImageGenError(e.code, sanitizeSecret(e.message, this.config.apiKey), e.suggestion, e.status);
       throw e;
@@ -133,7 +145,7 @@ export class OpenAICompatibleProvider implements ImageProvider {
         }
         const imageUrl = resolveImageUrl(rawUrl, this.config.baseUrl);
         const authorization = isSameOrigin(imageUrl, this.config.baseUrl) ? `Bearer ${this.config.apiKey}` : undefined;
-        const saved = await downloadImage(imageUrl, this.config.outputDir, this.config.timeoutMs, this.config.maxDownloadBytes, authorization);
+        const saved = await downloadImage(imageUrl, this.config.outputDir, this.config.downloadTimeoutMs ?? this.config.timeoutMs, this.config.maxDownloadBytes, authorization, { totalMs: this.config.totalTimeoutMs ?? 0 });
         images.push({ path: saved.path, url: imageUrl, mimeType: saved.mimeType, index });
       }
     }
@@ -145,7 +157,7 @@ export class OpenAICompatibleProvider implements ImageProvider {
 async function resolveImageInput(input: string, config: ImageGenConfig, signal?: AbortSignal): Promise<{ name: string; buffer: Buffer; mimeType: string }> {
   if (/^https?:\/\//i.test(input)) {
     const authorization = isSameOrigin(input, config.baseUrl) ? `Bearer ${config.apiKey}` : undefined;
-    const saved = await downloadImage(input, config.outputDir, config.timeoutMs, config.maxDownloadBytes, authorization);
+    const saved = await downloadImage(input, config.outputDir, config.downloadTimeoutMs ?? config.timeoutMs, config.maxDownloadBytes, authorization, { totalMs: config.totalTimeoutMs ?? 0 });
     const local = await loadLocalImage(saved.path);
     return local;
   }
@@ -176,7 +188,15 @@ function extractImageValue(value: unknown): string | undefined {
 }
 
 function isResponseFormatError(detail?: string): boolean {
-  return Boolean(detail && /response_format|b64_json|base64.*format/i.test(detail));
+  return Boolean(detail && /response_format|b64_json|base64.*format|unsupported.*param|unrecognized.*param/i.test(detail));
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(new ImageGenError("network_error", "请求已取消。", "重新发起操作即可。 ")); return; }
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => { clearTimeout(t); reject(new ImageGenError("network_error", "请求已取消。", "重新发起操作即可。 ")); }, { once: true });
+  });
 }
 
 function isSameOrigin(imageUrl: string, baseUrl: string): boolean {

package/src/utils/config.ts

@@ -51,6 +51,8 @@ export function readConfig(env: NodeJS.ProcessEnv = process.env): ImageGenConfig
     responseFormat: "auto",
     providerType: "openai-compatible",
     timeoutMs: Number(env.IMAGE_TIMEOUT_SECONDS ?? 60) * 1000,
+    totalTimeoutMs: Number(env.IMAGE_TOTAL_TIMEOUT_SECONDS ?? 600) * 1000,
+    downloadTimeoutMs: Number(env.IMAGE_DOWNLOAD_TIMEOUT_SECONDS ?? 60) * 1000,
     cacheTtlMs: Number(env.IMAGE_CACHE_TTL_SECONDS ?? 600) * 1000,
     outputDir,
     maxResponseBytes: Number(env.IMAGE_MAX_RESPONSE_BYTES ?? 8_000_000),

package/src/utils/download.ts

@@ -11,18 +11,64 @@ export function assertSafeHttpUrl(raw: string): URL {
   return url;
 }
 
-export async function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response> {
+export interface FetchTimeoutOptions {
+  /** stall 超时（默认沿用 timeoutMs）：只要持续有字节到达就自动续期。 */
+  stallMs?: number;
+  /** 绝对总时长上限，0 表示不限。 */
+  totalMs?: number;
+  /** 每收到一段数据回调，便于上层判断“还在动”。 */
+  onProgress?: (bytes: number) => void;
+}
+
+/**
+ * stall 超时：只要持续有字节到达就自动续期，只有“无任何字节”超过 stallMs 才超时。
+ * totalMs（>0 时为绝对上限，0 表示不限总时长）：真死链兜底。
+ */
+export async function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number, opts?: FetchTimeoutOptions): Promise<Response> {
+  const stallMs = opts?.stallMs ?? timeoutMs;
+  const totalMs = opts?.totalMs ?? 0;
+  const onProgress = opts?.onProgress;
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let stallTimer: ReturnType<typeof setTimeout> | undefined;
+  let totalTimer: ReturnType<typeof setTimeout> | undefined;
+  const armStall = () => {
+    clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => controller.abort(), stallMs);
+  };
+  armStall();
+  if (totalMs > 0) totalTimer = setTimeout(() => controller.abort(), totalMs);
   try {
     const signal = init.signal ? AbortSignal.any([init.signal, controller.signal]) : controller.signal;
-    return await fetch(url, { ...init, signal });
+    const response = await fetch(url, { ...init, signal });
+    // 对带 body 的响应包装“边读边续期”，避免慢速流被整体总时长误杀。
+    if (response.body && onProgress) {
+      const rawBody = response.body;
+      const stream = new ReadableStream<Uint8Array>({
+        async start(controller2) {
+          const reader = rawBody.getReader();
+          try {
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) { controller2.close(); break; }
+              if (value) { armStall(); onProgress(value.byteLength); controller2.enqueue(value); }
+            }
+          } catch (e) { controller2.error(e); }
+          finally { reader.releaseLock(); }
+        },
+      });
+      return new Response(stream, { headers: response.headers, status: response.status, statusText: response.statusText });
+    }
+    return response;
   } catch (e) {
-    if (controller.signal.aborted) throw new ImageGenError("timeout", "请求超时。", "稍后重试或增大 IMAGE_TIMEOUT_SECONDS。 ");
+    if (controller.signal.aborted) {
+      const totalHit = totalMs > 0;
+      throw new ImageGenError("timeout", totalHit ? "请求超时（已达总时长上限）。" : "请求超时。", "稍后重试，或增大 IMAGE_TIMEOUT_SECONDS / IMAGE_TOTAL_TIMEOUT_SECONDS。 ");
+    }
     if (e instanceof Error && e.name === "AbortError") throw new ImageGenError("network_error", "请求已取消。", "重新发起操作即可。 ");
     throw new ImageGenError("network_error", "网络请求失败。", e instanceof Error ? e.message : "检查网络连接。 ");
   } finally {
-    clearTimeout(timer);
+    clearTimeout(stallTimer);
+    if (totalTimer) clearTimeout(totalTimer);
   }
 }
 
@@ -59,7 +105,12 @@ function rejectHtml(buffer: Buffer): void {
   if (prefix.startsWith("<!doctype html") || prefix.startsWith("<html") || prefix.startsWith("<head") || prefix.startsWith("<body")) throw new ImageGenError("invalid_image", "下载内容不是图片，可能是鉴权页或错误页面。", "检查 Provider 图片 URL 和权限。 ");
 }
 
-export async function downloadImage(url: string, outputDir: string, timeoutMs: number, maxBytes: number, authorization?: string): Promise<{ path: string; mimeType: string }> {
+export interface DownloadImageOptions {
+  totalMs?: number;
+}
+
+export async function downloadImage(url: string, outputDir: string, stallMs: number, maxBytes: number, authorization?: string, opts?: DownloadImageOptions): Promise<{ path: string; mimeType: string }> {
+  const totalMs = opts?.totalMs ?? 0;
   let target = assertSafeHttpUrl(url);
   if (await resolvesToPrivateHost(target.hostname)) throw new ImageGenError("invalid_image", "图片 URL 解析到不安全的内网地址。", "不能访问 localhost、内网地址或云元数据地址。 ");
   const origin = target.origin;
@@ -67,7 +118,7 @@ export async function downloadImage(url: string, outputDir: string, timeoutMs: n
   for (let redirects = 0; redirects <= 3; redirects += 1) {
     const init: RequestInit = { method: "GET", redirect: "manual" };
     if (authorization && target.origin === origin) init.headers = { Authorization: authorization };
-    response = await fetchWithTimeout(target.toString(), init, timeoutMs);
+    response = await fetchWithTimeout(target.toString(), init, stallMs, { stallMs, totalMs });
     if (![301, 302, 303, 307, 308].includes(response.status)) break;
     const location = response.headers.get("location");
     if (!location) throw new ImageGenError("invalid_image", "图片下载重定向缺少目标地址。", "检查 Provider 返回的图片 URL。 ");