koishi-plugin-image-prompt 2.0.0 → 2.0.2

package/lib/index.d.ts

@@ -18,6 +18,12 @@ export declare const usage = "\n---\n\n\u6B64\u63D2\u4EF6\u76F4\u63A5\u8C03\u752
  * @param attempt 第几次重试（从 0 开始）
  */
 export declare function computeRetryDelay(status: any, retryAfter: number | undefined, baseInterval: number, attempt: number): number;
+/**
+ * 从接口抛出的错误里挖出「到底为什么失败」。
+ * koishi 的 http 错误对 5xx 往往只留一句状态文本（"Internal Server Error"），
+ * 真正的病根（比如上游 ECONNREFUSED、模型负载过高）藏在响应体里，得自己捞出来。
+ */
+export declare function httpErrorText(error: any): string;
 /** 从任意文本里挖出第一个 JSON 对象（容忍代码块围栏和前后废话） */
 export declare function extractJsonObject(raw: string | null | undefined): any | null;
 /**

package/lib/index.js

@@ -46,6 +46,7 @@ __export(src_exports, {
   extractServerMessage: () => extractServerMessage,
   extractTextToRender: () => extractTextToRender,
   fitImageSize: () => fitImageSize,
+  httpErrorText: () => httpErrorText,
   inject: () => inject,
   isPassiveReplyError: () => isPassiveReplyError,
   isRetryableStatus: () => isRetryableStatus,
@@ -136,12 +137,23 @@ Agent \u6307\u4EE4\u6A21\u677F\u53EF\u7528\u5360\u4F4D\u7B26\uFF1A{command} \u63
 var logger = new import_koishi.Logger(name);
 function computeRetryDelay(status, retryAfter, baseInterval, attempt) {
   const base = baseInterval > 0 ? baseInterval : 1e3;
-  if (status === 429 || status === 503) {
+  const worthBackoff = status === 429 || status === 503 || typeof status === "number" && status >= 500 || status === 0;
+  if (worthBackoff) {
     if (retryAfter && retryAfter > 0) return retryAfter;
     return Math.min(base * Math.pow(2, attempt), 3e4);
   }
   return base;
 }
+function httpErrorText(error) {
+  if (!error) return "\u672A\u77E5\u539F\u56E0";
+  const data = error?.response?.data ?? error?.data ?? error?.response;
+  const upstream = typeof data === "string" ? data : data?.error?.message ?? data?.message ?? data?.msg;
+  let text = String(error?.message || error?.toString?.() || "\u672A\u77E5\u539F\u56E0").trim();
+  if (typeof upstream === "string" && upstream.trim() && !text.includes(upstream.trim())) {
+    text = `${text}\uFF5C\u63A5\u53E3\u8FD4\u56DE\uFF1A${upstream.trim().slice(0, 200)}`;
+  }
+  return text;
+}
 function extractJsonObject(raw) {
   if (!raw) return null;
   let text = String(raw).trim();
@@ -1519,6 +1531,7 @@ function apply(ctx, config) {
     await bot.sendMessage(channelId, body, guildId);
   }
   const agentHistories = /* @__PURE__ */ new Map();
+  let agentUrlWarned = false;
   function agentHistoryKey(session) {
     return `${session.platform}:${session.channelId || session.userId || ""}`;
   }
@@ -1770,7 +1783,10 @@ Negative prompt: ${String(args.negative_prompt).trim()}` : prompt;
           ok: res.ok,
           references: capped,
           ...unknown.length ? { unknown } : {},
-          ...res.ok ? { note: "\u56FE\u5DF2\u7ECF\u53D1\u5230\u7FA4\u91CC\u4E86\uFF0C\u56DE\u4E00\u53E5\u7B80\u77ED\u8BF4\u660E\u5373\u53EF\uFF0C\u4E0D\u8981\u518D\u95EE\u300C\u8FD8\u8981\u6211\u505A\u4EC0\u4E48\u300D" } : { error: res.error === "invalidimage" ? "\u8FD9\u4E9B\u53C2\u8003\u56FE\u4E00\u5F20\u90FD\u4E0B\u8F7D\u4E0D\u4E0B\u6765\uFF0C\u68C0\u67E5\u94FE\u63A5\u8FD8\u80FD\u4E0D\u80FD\u8BBF\u95EE" : "\u7ED8\u56FE\u63A5\u53E3\u6CA1\u6709\u8FD4\u56DE\u56FE\u7247" }
+          ...res.ok ? res.queued ? { queued: true, note: "\u7ED8\u56FE\u4EFB\u52A1\u5DF2\u6392\u8FDB\u540E\u53F0\u961F\u5217\uFF0C\u8FD8\u6CA1\u6709\u753B\u5B8C\u3002\u8BF7\u544A\u8BC9\u7528\u6237\u300C\u5DF2\u7ECF\u6392\u4E0A\u961F\uFF0C\u753B\u597D\u540E\u4F1A\u5728\u8FD9\u91CC\u901A\u77E5\u300D\uFF0C\u4E0D\u8981\u8BF4\u5DF2\u7ECF\u753B\u597D\u6216\u5DF2\u7ECF\u53D1\u51FA\u56FE\u7247" } : { sent: true, note: "\u56FE\u5DF2\u7ECF\u53D1\u5230\u7FA4\u91CC\u4E86\uFF0C\u56DE\u4E00\u53E5\u7B80\u77ED\u8BF4\u660E\u5373\u53EF\uFF0C\u4E0D\u8981\u518D\u95EE\u300C\u8FD8\u8981\u6211\u505A\u4EC0\u4E48\u300D" } : {
+            error: res.error === "invalidimage" ? "\u8FD9\u4E9B\u53C2\u8003\u56FE\u4E00\u5F20\u90FD\u4E0B\u8F7D\u4E0D\u4E0B\u6765\uFF0C\u68C0\u67E5\u94FE\u63A5\u8FD8\u80FD\u4E0D\u80FD\u8BBF\u95EE" : `\u7ED8\u56FE\u63A5\u53E3\u8FD9\u6B21\u6CA1\u51FA\u56FE\uFF1A${(res.reason || "\u672A\u77E5\u539F\u56E0").slice(0, 160)}`,
+            note: "\u5982\u5B9E\u544A\u8BC9\u7528\u6237\u8FD9\u6B21\u6CA1\u753B\u51FA\u6765\u3001\u53EF\u80FD\u662F\u4EC0\u4E48\u539F\u56E0\uFF0C\u5E76\u5EFA\u8BAE\u7A0D\u540E\u518D\u8BD5\u6216\u6362\u4E2A\u6A21\u578B\uFF0C\u4E0D\u8981\u8BF4\u5DF2\u7ECF\u753B\u597D\u4E86"
+          }
         });
       }
     }
@@ -1802,6 +1818,10 @@ Negative prompt: ${String(args.negative_prompt).trim()}` : prompt;
       const model = agentCfg.model || selector.model || "Qwen/Qwen2.5-7B-Instruct";
       const url = agentCfg.baseUrl || selector.baseUrl || config.baseUrl;
       const apiKey = agentCfg.apiKey || selector.apiKey || config.apiKey;
+      if (!agentCfg.baseUrl && !selector.baseUrl && !agentUrlWarned) {
+        agentUrlWarned = true;
+        ctx.logger.warn("Agent \u7528\u7684\u662F\u7ED8\u56FE\u63A5\u53E3\u5730\u5740\uFF08\u300CAI \u6A21\u578B\u63A5\u53E3 \u2192 \u5BF9\u8BDD\u63A5\u53E3\u5730\u5740\u300D\u7559\u7A7A\u4E86\uFF09\u3002\u7ED8\u56FE\u6A21\u578B\u4E0D\u4F1A\u804A\u5929\u4E5F\u4E0D\u4F1A\u8C03\u5DE5\u5177\uFF0C\u8BF7\u5728\u300CAI \u6A21\u578B\u63A5\u53E3\u300D\u6216\u300CAgent \u914D\u7F6E\u300D\u91CC\u5355\u72EC\u586B\u4E00\u4E2A\u652F\u6301\u5DE5\u5177\u8C03\u7528\u7684\u5BF9\u8BDD\u6A21\u578B\u5730\u5740");
+      }
       const timeout = (agentCfg.timeout || selector.timeout || 60) * 1e3;
       const temperature = typeof agentCfg.temperature === "number" ? agentCfg.temperature : typeof selector.temperature === "number" ? selector.temperature : 0.3;
       const maxTokens = typeof agentCfg.maxTokens === "number" ? agentCfg.maxTokens : 8e3;
@@ -1890,17 +1910,24 @@ ${echo}` : echo);
             done: session.text("image-prompt.messages.bgdone"),
             failed: session.text("image-prompt.messages.failed"),
             error: session.text("image-prompt.messages.error")
+          },
+          /** 带上接口给的真实原因，用户一看就知道是模型那边的问题还是自己配置的问题 */
+          formatFailed: (reason) => {
+            const head = String(session.text("image-prompt.messages.failed") || "").replace(/[，,。]\s*$/, "");
+            if (!reason) return `${head}\u3002`;
+            const clean = String(reason).replace(/\s+/g, " ").trim();
+            return `${head}\uFF08${clean.slice(0, 120)}\uFF09`;
           }
         };
         const queued = enqueueDrawJob(snapshot, files);
         await sendNotice(session, `${session.text("image-prompt.messages.bgstart", [files.length])}${queued > 0 ? session.text("image-prompt.messages.bgqueue", [queued]) : ""}`);
-        return { ok: true };
+        return { ok: true, queued: true };
       }
-      const result = await generateFigureImage(files, text);
-      if (!result) return { ok: false, error: "failed" };
-      await saveToGallery(result, buildGalleryDescription(text, userInputText), commandName);
-      await sendResultImage(session, result, commandName);
-      return { ok: true, url: result };
+      const gen = await generateFigureImage(files, text);
+      if (!gen.url) return { ok: false, error: "failed", reason: gen.reason };
+      await saveToGallery(gen.url, buildGalleryDescription(text, userInputText), commandName);
+      await sendResultImage(session, gen.url, commandName);
+      return { ok: true, url: gen.url };
     }
     async function sendNotice(session, text) {
       const value = String(text ?? "").trim();
@@ -1961,7 +1988,7 @@ ${echo}` : echo);
       if (images.length === 0) return session.text("image-prompt.messages.needimages");
       const res = await drawWithFiles(session, cmdConfig, promptText, images, userInputText, { optimizeFailed });
       if (!res.ok) {
-        return res.error === "invalidimage" ? session.text("image-prompt.messages.invalidimage") : session.text("image-prompt.messages.failed");
+        return res.error === "invalidimage" ? session.text("image-prompt.messages.invalidimage") : res.reason ? `${String(session.text("image-prompt.messages.failed") || "").replace(/[，,。]\s*$/, "")}\uFF08${res.reason.replace(/\s+/g, " ").trim().slice(0, 120)}\uFF09` : session.text("image-prompt.messages.failed");
       }
     }
     let runningJobs = 0;
@@ -1989,14 +2016,14 @@ ${echo}` : echo);
       const send = (parts) => sendBotMessage(snapshot.bot, snapshot.channelId, parts, snapshot.guildId, snapshot.messageId);
       try {
         if (!isActive || !ctx.scope.isActive) return;
-        const result = await generateFigureImage(files, snapshot.promptText);
-        if (!result) {
-          await send([snapshot.texts.failed]);
+        const gen = await generateFigureImage(files, snapshot.promptText);
+        if (!gen.url) {
+          await send([snapshot.formatFailed ? snapshot.formatFailed(gen.reason) : snapshot.texts.failed]);
           return;
         }
-        await saveToGallery(result, buildGalleryDescription(snapshot.promptText, ""), snapshot.commandName);
+        await saveToGallery(gen.url, buildGalleryDescription(snapshot.promptText, ""), snapshot.commandName);
         await send([`${snapshot.texts.done}
-`, await buildResultImagePart(result)]);
+`, await buildResultImagePart(gen.url)]);
       } catch (error) {
         ctx.logger.error(`[${snapshot.commandName}] \u540E\u53F0\u7ED8\u56FE\u5931\u8D25:`, error);
         try {
@@ -2551,18 +2578,20 @@ ${lines.join("\n")}`]);
         return await sendChatRequest(requestBody);
       } catch (error) {
         ctx.logger.error(`\u751F\u6210\u56FE\u7247\u65F6\u53D1\u751F\u9519\u8BEF: ${error}`);
-        return null;
+        return { url: null, reason: String(error?.message || error) };
       }
     }
     async function sendChatRequest(requestBody) {
       let retryCount = 0;
-      while (retryCount <= config.maxRetries) {
+      const maxAttempts = (config.maxRetries ?? 0) + 1;
+      let lastReason = "";
+      while (retryCount < maxAttempts) {
         if (!isActive || !ctx.scope.isActive) {
           ctx.logger.info("\u63D2\u4EF6\u5DF2\u5378\u8F7D\uFF0C\u505C\u6B62\u91CD\u8BD5");
-          return null;
+          return { url: null, reason: lastReason };
         }
         try {
-          logInfo2(`\u53D1\u9001\u8BF7\u6C42\u5230 ${config.baseUrl}\uFF0C\u7B2C ${retryCount + 1} \u6B21\u5C1D\u8BD5`);
+          logInfo2(`\u53D1\u9001\u8BF7\u6C42\u5230 ${config.baseUrl}\uFF0C\u7B2C ${retryCount + 1}/${maxAttempts} \u6B21\u5C1D\u8BD5`);
           const headers = {
             "Content-Type": "application/json"
           };
@@ -2578,35 +2607,35 @@ ${lines.join("\n")}`]);
               if (markdownMatch && markdownMatch[1]) {
                 const imageUrl = markdownMatch[1];
                 logInfo2(`\u6210\u529F\u83B7\u53D6\u56FE\u7247URL: ${imageUrl}`);
-                return imageUrl;
+                return { url: imageUrl };
               }
             }
           }
-          const errorMsg = "\u54CD\u5E94\u4E2D\u672A\u627E\u5230\u56FE\u7247URL";
-          throw new Error(errorMsg);
+          throw new Error("\u54CD\u5E94\u4E2D\u672A\u627E\u5230\u56FE\u7247URL");
         } catch (error) {
           retryCount++;
-          const errorMessage = error.message || error.toString();
-          const statusCode = error.response?.status || 0;
-          logInfo2(`\u8BF7\u6C42\u5931\u8D25 (${retryCount}/${config.maxRetries}): ${errorMessage}`);
-          if (errorMessage.includes("insufficient_quota") || statusCode === 429) {
+          const reason = httpErrorText(error);
+          lastReason = reason;
+          const statusCode = error.response?.status || error.status || error.code || 0;
+          logInfo2(`\u8BF7\u6C42\u5931\u8D25\uFF08\u7B2C ${retryCount}/${maxAttempts} \u6B21\uFF09\uFF1A${reason}`);
+          if (reason.includes("insufficient_quota") || statusCode === 429) {
             ctx.logger.error("API \u914D\u989D\u4E0D\u8DB3\uFF0C\u505C\u6B62\u91CD\u8BD5");
-            return null;
+            return { url: null, reason };
           }
-          if (retryCount <= config.maxRetries) {
-            logInfo2(`\u7B49\u5F85 ${config.retryInterval}ms \u540E\u91CD\u8BD5`);
-            await (0, import_koishi.sleep)(config.retryInterval);
+          if (retryCount < maxAttempts) {
+            const delay = computeRetryDelay(statusCode, void 0, config.retryInterval, retryCount - 1);
+            logInfo2(`${delay}ms \u540E\u91CD\u8BD5`);
+            await (0, import_koishi.sleep)(delay);
             if (!isActive || !ctx.scope.isActive) {
               ctx.logger.info("\u63D2\u4EF6\u5DF2\u5378\u8F7D\uFF0C\u505C\u6B62\u91CD\u8BD5");
-              return null;
+              return { url: null, reason };
             }
           } else {
-            ctx.logger.error(`\u8FBE\u5230\u6700\u5927\u91CD\u8BD5\u6B21\u6570 (${config.maxRetries})\uFF0C\u6700\u540E\u9519\u8BEF: ${errorMessage}`);
-            return null;
+            ctx.logger.error(`\u5DF2\u91CD\u8BD5 ${maxAttempts} \u6B21\u4ECD\u5931\u8D25\uFF0C\u6700\u540E\u9519\u8BEF\uFF1A${reason}`);
           }
         }
       }
-      return null;
+      return { url: null, reason: lastReason };
     }
     function logInfo2(...args) {
       if (config.loggerinfo) {
@@ -2634,6 +2663,7 @@ ${lines.join("\n")}`]);
   extractServerMessage,
   extractTextToRender,
   fitImageSize,
+  httpErrorText,
   inject,
   isPassiveReplyError,
   isRetryableStatus,

package/package.json

@@ -1,28 +1,28 @@
-{
-  "name": "koishi-plugin-image-prompt",
-  "description": "多功能 AI 图像处理插件：Agent 模式把「查不查图库 / 要不要追问 / 什么时候开画」全交给模型自己决定，支持手办化、Coser 化、Minecraft 化等 47 种风格与自定义提示词",
-  "version": "2.0.0",
-  "main": "lib/index.js",
-  "typings": "lib/index.d.ts",
-  "files": [
-    "lib",
-    "src"
-  ],
-  "license": "GPL-3.0",
-  "keywords": [
-    "chatbot",
-    "koishi",
-    "plugin",
-    "手办化"
-  ],
-  "contributors": [
-    "maimai993 <3544815113@qq.com>"
-  ],
-  "homepage": "https://github.com/maimai993/koishi-plugin-image-prompt",
-  "bugs": {
-    "url": "https://github.com/maimai993/koishi-plugin-image-prompt/issues"
-  },
-  "peerDependencies": {
-    "koishi": "^4.18.7"
-  }
-}
+{
+  "name": "koishi-plugin-image-prompt",
+  "description": "多功能 AI 图像处理插件：Agent 模式把「查不查图库 / 要不要追问 / 什么时候开画」全交给模型自己决定，支持手办化、Coser 化、Minecraft 化等 47 种风格与自定义提示词",
+  "version": "2.0.2",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "GPL-3.0",
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "手办化"
+  ],
+  "contributors": [
+    "maimai993 <3544815113@qq.com>"
+  ],
+  "homepage": "https://github.com/maimai993/koishi-plugin-image-prompt",
+  "bugs": {
+    "url": "https://github.com/maimai993/koishi-plugin-image-prompt/issues"
+  },
+  "peerDependencies": {
+    "koishi": "^4.18.7"
+  }
+}

package/readme.md

@@ -460,6 +460,31 @@ max_tokens=8000  → finish_reason: stop,   content: "{...}", reasoning_tokens:
 每一轮的模型输出与工具调用都会写进日志，一眼就能看出是模型没调工具、
 还是调了但参数不对。
 
+### 🩺 排查「画不出来 / 接口报错」
+
+失败时插件会把**服务端返回的真实原因**原样带出来，先看这一句再决定怎么办：
+
+```
+[I] 请求失败（第 3/3 次）：Internal Server Error｜接口返回：connect ECONNREFUSED 192.168.0.85:20000
+```
+
+群里收到的失败消息里同样会带上这句。**这串东西不是乱码**，它通常直接说明问题在哪：
+
+| 看到的说法 | 含义 | 怎么办 |
+| --- | --- | --- |
+| `connect ECONNREFUSED <ip>:<端口>` | 中转站的后端节点没起来 / 挂了 | **跟接口提供方无关也不在你这边**，换模型或等它恢复 |
+| `当前模型负载较高` | 该模型现在挤，不是配置问题 | 换个负载均衡点的模型，或稍后再试 |
+| `Model Not Exist` | 模型名写错了 | 核对模型名（大小写也算） |
+| `Invalid API key` | 密钥不对或已过期 | 换密钥 |
+| `insufficient_quota` | 额度没了 | 充值后会立刻恢复，插件不会傻重试 |
+
+> 同一个中转站上**所有**绘图模型都报同一个 `ECONNREFUSED` 时，基本可以确定是对方整条链路挂了，
+> 换个模型名也没用，只能等它恢复。判断是否全挂：换 2~3 个不同的绘图模型各试一次，
+> 如果都指向同一个 IP 端口，就是服务端的问题。
+
+另外，`429 限流` 和 `5xx 服务端错误` 现在是**指数退避**重试（1s → 2s → 4s…），
+不再用固定间隔连着猛打 —— 对端真的在重启的时候，等久一点反而更容易成功。
+
 ### ❌ 不会重试的错误
 
 `400 / 401 / 403 / 404 / 422` 这类属于永久性错误（参数错、密钥错、地址错、模型不存在），

package/src/index.ts

@@ -81,13 +81,34 @@ const logger = new Logger(name)
  */
 export function computeRetryDelay(status: any, retryAfter: number | undefined, baseInterval: number, attempt: number): number {
   const base = baseInterval > 0 ? baseInterval : 1000
-  if (status === 429 || status === 503) {
+  // 429 限流、5xx 服务端错误、status=0（网络层就断了）都值得退避：
+  // 上游节点挂了的时候，固定间隔连着猛打四次只是徒增负担
+  const worthBackoff = status === 429 || status === 503 || (typeof status === 'number' && status >= 500) || status === 0
+  if (worthBackoff) {
     if (retryAfter && retryAfter > 0) return retryAfter
     return Math.min(base * Math.pow(2, attempt), 30000)
   }
   return base
 }
 
+/**
+ * 从接口抛出的错误里挖出「到底为什么失败」。
+ * koishi 的 http 错误对 5xx 往往只留一句状态文本（"Internal Server Error"），
+ * 真正的病根（比如上游 ECONNREFUSED、模型负载过高）藏在响应体里，得自己捞出来。
+ */
+export function httpErrorText(error: any): string {
+  if (!error) return '未知原因'
+  const data = error?.response?.data ?? error?.data ?? error?.response
+  const upstream = typeof data === 'string'
+    ? data
+    : data?.error?.message ?? data?.message ?? data?.msg
+  let text = String(error?.message || error?.toString?.() || '未知原因').trim()
+  if (typeof upstream === 'string' && upstream.trim() && !text.includes(upstream.trim())) {
+    text = `${text}｜接口返回：${upstream.trim().slice(0, 200)}`
+  }
+  return text
+}
+
 /** 从任意文本里挖出第一个 JSON 对象（容忍代码块围栏和前后废话） */
 export function extractJsonObject(raw: string | null | undefined): any | null {
   if (!raw) return null
@@ -1977,6 +1998,8 @@ export function apply(ctx: Context, config: CommandConfig) {
 
   // 每个频道最近几轮的对话（agent 记忆，只存纯文本，重启即失效）
   const agentHistories = new Map<string, any[]>()
+  /** 「agent 接口地址没单独配」这条警告只打一次，别刷屏 */
+  let agentUrlWarned = false
 
   function agentHistoryKey(session: Session): string {
     return `${session.platform}:${session.channelId || session.userId || ''}`
@@ -2301,8 +2324,16 @@ export function apply(ctx: Context, config: CommandConfig) {
           references: capped,
           ...(unknown.length ? { unknown } : {}),
           ...(res.ok
-            ? { note: '图已经发到群里了，回一句简短说明即可，不要再问「还要我做什么」' }
-            : { error: res.error === 'invalidimage' ? '这些参考图一张都下载不下来，检查链接还能不能访问' : '绘图接口没有返回图片' }),
+            ? (res.queued
+              // 后台绘图：这里只是排上队了，图还没开始画，绝不能让模型告诉用户「画好了」
+              ? { queued: true, note: '绘图任务已排进后台队列，还没有画完。请告诉用户「已经排上队，画好后会在这里通知」，不要说已经画好或已经发出图片' }
+              : { sent: true, note: '图已经发到群里了，回一句简短说明即可，不要再问「还要我做什么」' })
+            : {
+              error: res.error === 'invalidimage'
+                ? '这些参考图一张都下载不下来，检查链接还能不能访问'
+                : `绘图接口这次没出图：${(res.reason || '未知原因').slice(0, 160)}`,
+              note: '如实告诉用户这次没画出来、可能是什么原因，并建议稍后再试或换个模型，不要说已经画好了',
+            }),
         })
       }
     }
@@ -2348,6 +2379,12 @@ export function apply(ctx: Context, config: CommandConfig) {
       const model = agentCfg.model || selector.model || 'Qwen/Qwen2.5-7B-Instruct'
       const url = agentCfg.baseUrl || selector.baseUrl || config.baseUrl
       const apiKey = agentCfg.apiKey || selector.apiKey || config.apiKey
+      // agent 要用的是**对话**模型。接口地址一个都没填时会落到绘图接口上，
+      // 而绘图模型（gpt-image 之类）根本不会聊天/调工具，这里提前说清楚。
+      if (!agentCfg.baseUrl && !selector.baseUrl && !agentUrlWarned) {
+        agentUrlWarned = true
+        ctx.logger.warn('Agent 用的是绘图接口地址（「AI 模型接口 → 对话接口地址」留空了）。绘图模型不会聊天也不会调工具，请在「AI 模型接口」或「Agent 配置」里单独填一个支持工具调用的对话模型地址')
+      }
       const timeout = (agentCfg.timeout || selector.timeout || 60) * 1000
       const temperature = typeof agentCfg.temperature === 'number'
         ? agentCfg.temperature
@@ -2420,7 +2457,7 @@ export function apply(ctx: Context, config: CommandConfig) {
       imageUrls: string[],
       userInputText: string,
       options: { optimizeFailed?: boolean, requireInput?: boolean } = {}
-    ): Promise<{ ok: boolean, error?: string, url?: string }> {
+    ): Promise<{ ok: boolean, error?: string, url?: string, reason?: string, queued?: boolean }> {
       const commandName = cmdConfig.name
       const requireInput = options.requireInput !== false
       const files = await downloadFiles(imageUrls)
@@ -2466,18 +2503,26 @@ export function apply(ctx: Context, config: CommandConfig) {
             failed: session.text('image-prompt.messages.failed'),
             error: session.text('image-prompt.messages.error'),
           },
+          /** 带上接口给的真实原因，用户一看就知道是模型那边的问题还是自己配置的问题 */
+          formatFailed: (reason?: string) => {
+            const head = String(session.text('image-prompt.messages.failed') || '').replace(/[，,。]\s*$/, '')
+            if (!reason) return `${head}。`
+            const clean = String(reason).replace(/\s+/g, ' ').trim()
+            return `${head}（${clean.slice(0, 120)}）`
+          },
         }
         const queued = enqueueDrawJob(snapshot, files)
         await sendNotice(session, `${session.text('image-prompt.messages.bgstart', [files.length])}${queued > 0 ? session.text('image-prompt.messages.bgqueue', [queued]) : ''}`)
-        return { ok: true }
+        // 注意：这里是「排上队了」，不是「画好了」。别让上层当成已完成通知用户
+        return { ok: true, queued: true }
       }
 
-      const result = await generateFigureImage(files, text)
-      if (!result) return { ok: false, error: 'failed' }
+      const gen = await generateFigureImage(files, text)
+      if (!gen.url) return { ok: false, error: 'failed', reason: gen.reason }
 
-      await saveToGallery(result, buildGalleryDescription(text, userInputText), commandName)
-      await sendResultImage(session, result, commandName)
-      return { ok: true, url: result }
+      await saveToGallery(gen.url, buildGalleryDescription(text, userInputText), commandName)
+      await sendResultImage(session, gen.url, commandName)
+      return { ok: true, url: gen.url }
     }
 
     /** 发一条状态说明（支持的平台用 markdown，省得长文被拆） */
@@ -2557,7 +2602,9 @@ export function apply(ctx: Context, config: CommandConfig) {
       if (!res.ok) {
         return res.error === 'invalidimage'
           ? session.text('image-prompt.messages.invalidimage')
-          : session.text('image-prompt.messages.failed')
+          : res.reason
+            ? `${String(session.text('image-prompt.messages.failed') || '').replace(/[，,。]\s*$/, '')}（${res.reason.replace(/\s+/g, ' ').trim().slice(0, 120)}）`
+            : session.text('image-prompt.messages.failed')
       }
     }
     // ============ 后台绘图 ============
@@ -2590,13 +2637,13 @@ export function apply(ctx: Context, config: CommandConfig) {
 
       try {
         if (!isActive || !ctx.scope.isActive) return
-        const result = await generateFigureImage(files, snapshot.promptText)
-        if (!result) {
-          await send([snapshot.texts.failed])
+        const gen = await generateFigureImage(files, snapshot.promptText)
+        if (!gen.url) {
+          await send([snapshot.formatFailed ? snapshot.formatFailed(gen.reason) : snapshot.texts.failed])
           return
         }
-        await saveToGallery(result, buildGalleryDescription(snapshot.promptText, ''), snapshot.commandName)
-        await send([`${snapshot.texts.done}\n`, await buildResultImagePart(result)])
+        await saveToGallery(gen.url, buildGalleryDescription(snapshot.promptText, ''), snapshot.commandName)
+        await send([`${snapshot.texts.done}\n`, await buildResultImagePart(gen.url)])
       } catch (error) {
         ctx.logger.error(`[${snapshot.commandName}] 后台绘图失败:`, error)
         try {
@@ -3265,7 +3312,8 @@ export function apply(ctx: Context, config: CommandConfig) {
       return images
     }
 
-    async function generateFigureImage(files: any[], prompt: string): Promise<string | null> {
+    /** @returns 图片地址；失败时带回接口给的真实原因，方便直接告诉用户「是模型那边的毛病」 */
+    async function generateFigureImage(files: any[], prompt: string): Promise<{ url: string | null, reason?: string }> {
       try {
         const dataUrls: string[] = []
 
@@ -3344,22 +3392,24 @@ export function apply(ctx: Context, config: CommandConfig) {
         return await sendChatRequest(requestBody)
       } catch (error) {
         ctx.logger.error(`生成图片时发生错误: ${error}`)
-        return null
+        return { url: null, reason: String(error?.message || error) }
       }
     }
 
-    async function sendChatRequest(requestBody: any): Promise<string | null> {
+    async function sendChatRequest(requestBody: any): Promise<{ url: string | null, reason?: string }> {
       let retryCount = 0
+      const maxAttempts = (config.maxRetries ?? 0) + 1
+      let lastReason = ''
 
-      while (retryCount <= config.maxRetries) {
+      while (retryCount < maxAttempts) {
         // 在每次重试前检查上下文状态
         if (!isActive || !ctx.scope.isActive) {
           ctx.logger.info('插件已卸载，停止重试')
-          return null
+          return { url: null, reason: lastReason }
         }
 
         try {
-          logInfo(`发送请求到 ${config.baseUrl}，第 ${retryCount + 1} 次尝试`)
+          logInfo(`发送请求到 ${config.baseUrl}，第 ${retryCount + 1}/${maxAttempts} 次尝试`)
 
           const headers: Record<string, string> = {
             'Content-Type': 'application/json'
@@ -3381,40 +3431,41 @@ export function apply(ctx: Context, config: CommandConfig) {
               if (markdownMatch && markdownMatch[1]) {
                 const imageUrl = markdownMatch[1]
                 logInfo(`成功获取图片URL: ${imageUrl}`)
-                return imageUrl
+                return { url: imageUrl }
               }
             }
           }
 
-          const errorMsg = '响应中未找到图片URL'
-          throw new Error(errorMsg)
+          throw new Error('响应中未找到图片URL')
         } catch (error) {
           retryCount++
-          const errorMessage = error.message || error.toString()
-          const statusCode = error.response?.status || 0
+          const reason = httpErrorText(error)
+          lastReason = reason
+          const statusCode = error.response?.status || error.status || error.code || 0
 
-          logInfo(`请求失败 (${retryCount}/${config.maxRetries}): ${errorMessage}`)
+          logInfo(`请求失败（第 ${retryCount}/${maxAttempts} 次）：${reason}`)
 
           // 检查是否为配额不足错误
-          if (errorMessage.includes('insufficient_quota') || statusCode === 429) {
+          if (reason.includes('insufficient_quota') || statusCode === 429) {
             ctx.logger.error('API 配额不足，停止重试')
-            return null
+            return { url: null, reason }
           }
 
-          if (retryCount <= config.maxRetries) {
-            logInfo(`等待 ${config.retryInterval}ms 后重试`)
-            await sleep(config.retryInterval)
+          if (retryCount < maxAttempts) {
+            // 服务端错误/网络错误走指数退避，别用固定间隔猛打
+            const delay = computeRetryDelay(statusCode, undefined, config.retryInterval, retryCount - 1)
+            logInfo(`${delay}ms 后重试`)
+            await sleep(delay)
             if (!isActive || !ctx.scope.isActive) {
               ctx.logger.info('插件已卸载，停止重试')
-              return null
+              return { url: null, reason }
             }
           } else {
-            ctx.logger.error(`达到最大重试次数 (${config.maxRetries})，最后错误: ${errorMessage}`)
-            return null
+            ctx.logger.error(`已重试 ${maxAttempts} 次仍失败，最后错误：${reason}`)
           }
         }
       }
-      return null
+      return { url: null, reason: lastReason }
     }
 
     function logInfo(...args: any[]) {