@leoqlin/openclaw-qqbot 1.6.8-beta.2 → 1.6.8-beta.4

package/dist/src/api.js

@@ -850,7 +850,6 @@ async function sleep(ms, signal) {
         }
     });
 }
-import { StreamInputState } from "./types.js";
 /**
  * 发送流式消息（C2C 私聊）
  *
@@ -882,9 +881,5 @@ export async function sendC2CStreamMessage(accessToken, openid, req) {
     if (req.stream_msg_id) {
         body.stream_msg_id = req.stream_msg_id;
     }
-    // 仅终结分片触发引用回调，中间分片跳过
-    if (req.input_state === StreamInputState.DONE) {
-        return sendAndNotify(accessToken, "POST", path, body, { text: req.content_raw });
-    }
     return apiRequest(accessToken, "POST", path, body);
 }

package/dist/src/channel.js

@@ -1,6 +1,6 @@
 import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk/core";
 import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId, resolveRequireMention, resolveToolPolicy, resolveGroupConfig } from "./config.js";
-import { sendText, sendMedia } from "./outbound.js";
+import { sendText, sendMedia, resolveUserFacingMediaError } from "./outbound.js";
 import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
@@ -17,6 +17,16 @@ export function chunkText(text, limit) {
     const runtime = getQQBotRuntime();
     return runtime.channel.text.chunkMarkdownText(text, limit);
 }
+function buildChannelMediaError(result) {
+    const err = new Error(resolveUserFacingMediaError(result));
+    if (result.errorCode) {
+        err.code = result.errorCode;
+    }
+    if (result.qqBizCode !== undefined) {
+        err.qqBizCode = result.qqBizCode;
+    }
+    return err;
+}
 export const qqbotPlugin = {
     id: "qqbot",
     meta: {
@@ -264,18 +274,12 @@ export const qqbotPlugin = {
             const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
             console.log(`[qqbot:channel] sendMedia result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
             // 此 sendMedia 是框架 Channel Plugin 的标准出站接口，
-            // 用于非 gateway deliver 场景（如 API 直接发送、cron 等）。
-            // gateway 消息响应走的是 deliver 回调 → sendPlainReply，不经过此处。
-            // 框架拿到 error 后不一定会给用户发文字兜底，所以这里主动发一条。
+            // 由框架 deliver.js (deliverOutboundPayloads) 或 message-actions 调用。
+            // 当 throw Error 后，框架 pi-tool-definition-adapter 会将错误转化为
+            // tool 的 { status: "error" } 返回给 AI 模型，模型会自行生成错误回复给用户。
+            // 因此此处不应主动发送兜底文本，否则会与模型的回复重复。
             if (result.error) {
-                try {
-                    const fallbackResult = await sendText({ to, text: result.error, accountId, replyToId, account });
-                    console.log(`[qqbot:channel] sendMedia fallback text sent: messageId=${fallbackResult.messageId}, error=${fallbackResult.error ?? "none"}`);
-                }
-                catch (fallbackErr) {
-                    console.error(`[qqbot:channel] sendMedia fallback text failed: ${fallbackErr}`);
-                }
-                throw new Error(result.error);
+                throw buildChannelMediaError(result);
             }
             return {
                 channel: "qqbot",

package/dist/src/outbound-deliver.js

@@ -5,8 +5,8 @@
  * 1. parseAndSendMediaTags — 解析 <qqimg/qqvoice/qqvideo/qqfile/qqmedia> 标签并按顺序发送
  * 2. sendPlainReply — 处理不含媒体标签的普通回复（markdown 图片/纯文本+图片）
  */
-import { sendC2CMessage, sendGroupMessage, sendChannelMessage, sendC2CImageMessage, sendGroupImageMessage } from "./api.js";
-import { sendPhoto, sendMedia as sendMediaAuto } from "./outbound.js";
+import { sendC2CMessage, sendGroupMessage, sendChannelMessage, sendC2CImageMessage, sendGroupImageMessage, } from "./api.js";
+import { sendPhoto, sendMedia as sendMediaAuto, DEFAULT_MEDIA_SEND_ERROR, resolveUserFacingMediaError, } from "./outbound.js";
 import { chunkText, TEXT_CHUNK_LIMIT } from "./channel.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize } from "./utils/image-size.js";
@@ -154,7 +154,7 @@ export async function sendPlainReply(payload, replyText, event, actx, sendWithRe
                 });
                 if (result.error) {
                     log?.error(`${prefix} sendMedia(auto) error for ${mediaPath}: ${result.error}`);
-                    await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+                    await sendTextChunks(resolveUserFacingMediaError(result), event, actx, sendWithRetry, consumeQuoteRef);
                 }
                 else {
                     log?.info(`${prefix} Sent local media: ${mediaPath}`);
@@ -162,7 +162,7 @@ export async function sendPlainReply(payload, replyText, event, actx, sendWithRe
             }
             catch (err) {
                 log?.error(`${prefix} sendMedia(auto) failed for ${mediaPath}: ${err}`);
-                await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+                await sendTextChunks(DEFAULT_MEDIA_SEND_ERROR, event, actx, sendWithRetry, consumeQuoteRef);
             }
         }
     }
@@ -183,7 +183,7 @@ export async function sendPlainReply(payload, replyText, event, actx, sendWithRe
                     });
                     if (result.error) {
                         log?.error(`${prefix} Tool media forward error: ${result.error}`);
-                        await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+                        await sendTextChunks(resolveUserFacingMediaError(result), event, actx, sendWithRetry, consumeQuoteRef);
                     }
                     else {
                         log?.info(`${prefix} Forwarded tool media: ${mediaUrl.slice(0, 80)}...`);
@@ -191,7 +191,7 @@ export async function sendPlainReply(payload, replyText, event, actx, sendWithRe
                 }
                 catch (err) {
                     log?.error(`${prefix} Tool media forward failed: ${err}`);
-                    await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+                    await sendTextChunks(DEFAULT_MEDIA_SEND_ERROR, event, actx, sendWithRetry, consumeQuoteRef);
                 }
             }
         }
@@ -356,7 +356,7 @@ async function sendPlainTextReply(textWithoutImages, imageUrls, mdMatches, bareU
                 const imgResult = await sendPhoto(imgMediaTarget, imageUrl);
                 if (imgResult.error) {
                     log?.error(`${prefix} Failed to send image: ${imgResult.error}`);
-                    await sendTextChunks(`发送图片失败：${imgResult.error}`, event, actx, sendWithRetry, consumeQuoteRef);
+                    await sendTextChunks(resolveUserFacingMediaError(imgResult), event, actx, sendWithRetry, consumeQuoteRef);
                 }
                 else {
                     log?.info(`${prefix} Sent image via sendPhoto: ${imageUrl.slice(0, 80)}...`);
@@ -364,7 +364,7 @@ async function sendPlainTextReply(textWithoutImages, imageUrls, mdMatches, bareU
             }
             catch (imgErr) {
                 log?.error(`${prefix} Failed to send image: ${imgErr}`);
-                await sendTextChunks(`发送图片失败：${imgErr}`, event, actx, sendWithRetry, consumeQuoteRef);
+                await sendTextChunks(DEFAULT_MEDIA_SEND_ERROR, event, actx, sendWithRetry, consumeQuoteRef);
             }
         }
         if (result.trim()) {

package/dist/src/outbound.d.ts

@@ -53,14 +53,29 @@ export interface MediaOutboundContext extends OutboundContext {
     /** 可选的 MIME 类型，优先于扩展名判断媒体类型 */
     mimeType?: string;
 }
+export declare const OUTBOUND_ERROR_CODES: {
+    readonly FILE_TOO_LARGE: "file_too_large";
+    readonly UPLOAD_DAILY_LIMIT_EXCEEDED: "upload_daily_limit_exceeded";
+};
+export declare const DEFAULT_MEDIA_SEND_ERROR = "\u53D1\u9001\u5931\u8D25\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002";
+export type OutboundErrorCode = typeof OUTBOUND_ERROR_CODES[keyof typeof OUTBOUND_ERROR_CODES];
 export interface OutboundResult {
     channel: string;
     messageId?: string;
     timestamp?: string | number;
     error?: string;
+    /** 稳定错误码，供上层按类型处理，避免依赖 error 文案 */
+    errorCode?: OutboundErrorCode;
+    /** QQ 开放平台业务错误码（如 upload_prepare 的 40093002） */
+    qqBizCode?: number;
     /** 出站消息的引用索引（ext_info.ref_idx），供引用消息缓存使用 */
     refIdx?: string;
 }
+/**
+ * 将媒体发送结果映射为可展示给用户的文案。
+ * 只对明确标记为可直接展示的错误码透传原文，其余统一走通用兜底。
+ */
+export declare function resolveUserFacingMediaError(result: Pick<OutboundResult, "error" | "errorCode" | "qqBizCode">): string;
 /** 媒体发送的目标上下文（从 deliver 回调或 sendText 中提取） */
 export interface MediaTargetContext {
     /** 目标类型 */

package/dist/src/outbound.js

@@ -5,7 +5,7 @@ import * as path from "path";
 import * as fs from "fs";
 import * as crypto from "crypto";
 import { decodeCronPayload } from "./utils/payload.js";
-import { getAccessToken, sendC2CMessage, sendChannelMessage, sendGroupMessage, sendProactiveC2CMessage, sendProactiveGroupMessage, sendC2CMediaMessage, sendGroupMediaMessage, MediaFileType, } from "./api.js";
+import { getAccessToken, sendC2CMessage, sendChannelMessage, sendGroupMessage, sendProactiveC2CMessage, sendProactiveGroupMessage, sendC2CMediaMessage, sendGroupMediaMessage, MediaFileType, UPLOAD_PREPARE_FALLBACK_CODE, } from "./api.js";
 import { isAudioFile, audioFileToSilkFile, waitForFile, shouldTranscodeVoice } from "./utils/audio-convert.js";
 import { fileExistsAsync, formatFileSize, getMaxUploadSize, getFileTypeName, getFileSizeAsync } from "./utils/file-utils.js";
 import { chunkedUploadC2C, chunkedUploadGroup, UploadDailyLimitExceededError } from "./utils/chunked-upload.js";
@@ -110,6 +110,29 @@ export function getMessageReplyConfig() {
         ttlHours: MESSAGE_REPLY_TTL / (60 * 60 * 1000),
     };
 }
+export const OUTBOUND_ERROR_CODES = {
+    FILE_TOO_LARGE: "file_too_large",
+    UPLOAD_DAILY_LIMIT_EXCEEDED: "upload_daily_limit_exceeded",
+};
+export const DEFAULT_MEDIA_SEND_ERROR = "发送失败，请稍后重试。";
+/**
+ * 将媒体发送结果映射为可展示给用户的文案。
+ * 只对明确标记为可直接展示的错误码透传原文，其余统一走通用兜底。
+ */
+export function resolveUserFacingMediaError(result) {
+    if (!result.error)
+        return DEFAULT_MEDIA_SEND_ERROR;
+    if (result.qqBizCode === UPLOAD_PREPARE_FALLBACK_CODE) {
+        return result.error;
+    }
+    switch (result.errorCode) {
+        case OUTBOUND_ERROR_CODES.FILE_TOO_LARGE:
+        case OUTBOUND_ERROR_CODES.UPLOAD_DAILY_LIMIT_EXCEEDED:
+            return result.error;
+        default:
+            return DEFAULT_MEDIA_SEND_ERROR;
+    }
+}
 /**
  * 解析目标地址
  * 格式：
@@ -375,7 +398,11 @@ sendMeta) {
     if (fileSize > maxSize) {
         const typeName = getFileTypeName(fileType);
         const limitMB = Math.round(maxSize / (1024 * 1024));
-        return { channel: "qqbot", error: `${typeName}过大（${formatFileSize(fileSize)}），超过了${limitMB}M，暂时不能通过QQ直接发给你。` };
+        return {
+            channel: "qqbot",
+            error: `${typeName}过大（${formatFileSize(fileSize)}），超过了${limitMB}M，暂时不能通过QQ直接发给你。`,
+            errorCode: OUTBOUND_ERROR_CODES.FILE_TOO_LARGE,
+        };
     }
     if (ctx.targetType === "c2c") {
         console.log(`${prefix} ${callerName}: c2c chunked upload (${formatFileSize(fileSize)})`);
@@ -397,7 +424,12 @@ sendMeta) {
                 const dir = path.dirname(err.filePath);
                 const name = path.basename(err.filePath);
                 const size = formatFileSize(err.fileSize);
-                return { channel: "qqbot", error: `QQBot每天发送文件有累计2G的限制，如果着急的话，可以直接来我的主机copy下载，文件目录\`${dir}/${name}\`（${size}）` };
+                return {
+                    channel: "qqbot",
+                    error: `QQBot每天发送文件有累计2G的限制，如果着急的话，可以直接来我的主机copy下载，文件目录\`${dir}/${name}\`（${size}）`,
+                    errorCode: OUTBOUND_ERROR_CODES.UPLOAD_DAILY_LIMIT_EXCEEDED,
+                    qqBizCode: UPLOAD_PREPARE_FALLBACK_CODE,
+                };
             }
             return { channel: "qqbot", error: `文件发送失败，请稍后重试。` };
         }
@@ -422,7 +454,12 @@ sendMeta) {
                 const dir = path.dirname(err.filePath);
                 const name = path.basename(err.filePath);
                 const size = formatFileSize(err.fileSize);
-                return { channel: "qqbot", error: `QQBot每天发送文件有累计2G的限制，如果着急的话，可以直接来我的主机copy下载，文件目录\`${dir}/${name}\`（${size}）` };
+                return {
+                    channel: "qqbot",
+                    error: `QQBot每天发送文件有累计2G的限制，如果着急的话，可以直接来我的主机copy下载，文件目录\`${dir}/${name}\`（${size}）`,
+                    errorCode: OUTBOUND_ERROR_CODES.UPLOAD_DAILY_LIMIT_EXCEEDED,
+                    qqBizCode: UPLOAD_PREPARE_FALLBACK_CODE,
+                };
             }
             return { channel: "qqbot", error: `文件发送失败，请稍后重试。` };
         }

package/dist/src/utils/media-send.js

@@ -7,7 +7,7 @@
 /* eslint-disable no-undef -- Buffer is a Node.js global */
 import { normalizeMediaTags } from "./media-tags.js";
 import { normalizePath } from "./platform.js";
-import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, sendMedia as sendMediaAuto, } from "../outbound.js";
+import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, sendMedia as sendMediaAuto, DEFAULT_MEDIA_SEND_ERROR, resolveUserFacingMediaError, } from "../outbound.js";
 /** 统一的媒体标签正则 — 匹配标准化后的 6 种标签 */
 export const MEDIA_TAG_REGEX = /<(qqimg|qqvoice|qqvideo|qqfile|qqmedia|img)>([^<>]+)<\/(?:qqimg|qqvoice|qqvideo|qqfile|qqmedia|img)>/gi;
 /** 创建一个新的全局标签正则实例（每次调用 reset lastIndex） */
@@ -283,7 +283,6 @@ export async function executeSendQueue(queue, ctx, options = {}) {
         }
     };
     for (const item of queue) {
-        const FALLBACK_MSG = "发送失败，请稍后重试。";
         try {
             if (item.type === "text") {
                 if (options.skipInterTagText) {
@@ -303,7 +302,7 @@ export async function executeSendQueue(queue, ctx, options = {}) {
                 const result = await sendPhoto(mediaTarget, item.content);
                 if (result.error) {
                     log?.error(`${prefix} sendPhoto error: ${result.error}`);
-                    await sendFallbackText(FALLBACK_MSG);
+                    await sendFallbackText(resolveUserFacingMediaError(result));
                 }
             }
             else if (item.type === "voice") {
@@ -318,26 +317,26 @@ export async function executeSendQueue(queue, ctx, options = {}) {
                     ]);
                     if (result.error) {
                         log?.error(`${prefix} sendVoice error: ${result.error}`);
-                        await sendFallbackText(FALLBACK_MSG);
+                        await sendFallbackText(resolveUserFacingMediaError(result));
                     }
                 }
                 catch (err) {
                     log?.error(`${prefix} sendVoice unexpected error: ${err}`);
-                    await sendFallbackText(FALLBACK_MSG);
+                    await sendFallbackText(DEFAULT_MEDIA_SEND_ERROR);
                 }
             }
             else if (item.type === "video") {
                 const result = await sendVideoMsg(mediaTarget, item.content);
                 if (result.error) {
                     log?.error(`${prefix} sendVideoMsg error: ${result.error}`);
-                    await sendFallbackText(FALLBACK_MSG);
+                    await sendFallbackText(resolveUserFacingMediaError(result));
                 }
             }
             else if (item.type === "file") {
                 const result = await sendDocument(mediaTarget, item.content);
                 if (result.error) {
                     log?.error(`${prefix} sendDocument error: ${result.error}`);
-                    await sendFallbackText(FALLBACK_MSG);
+                    await sendFallbackText(resolveUserFacingMediaError(result));
                 }
             }
             else if (item.type === "media") {
@@ -351,13 +350,13 @@ export async function executeSendQueue(queue, ctx, options = {}) {
                 });
                 if (result.error) {
                     log?.error(`${prefix} sendMedia(auto) error: ${result.error}`);
-                    await sendFallbackText(FALLBACK_MSG);
+                    await sendFallbackText(resolveUserFacingMediaError(result));
                 }
             }
         }
         catch (err) {
             log?.error(`${prefix} executeSendQueue: failed to send ${item.type}: ${err}`);
-            await sendFallbackText(FALLBACK_MSG);
+            await sendFallbackText(DEFAULT_MEDIA_SEND_ERROR);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leoqlin/openclaw-qqbot",
-  "version": "1.6.8-beta.2",
+  "version": "1.6.8-beta.4",
   "publishConfig": {
     "access": "public"
   },
@@ -37,7 +37,7 @@
     "postbuild": "node -e \"const fs=require('fs'),p=require('path'),ext=p.join(require('os').homedir(),'.openclaw/extensions/openclaw-qqbot');if(fs.existsSync(ext)&&!fs.lstatSync(ext).isSymbolicLink()){const d=p.join(ext,'dist'),pr=p.join(ext,'preload.cjs');fs.cpSync('dist',d,{recursive:true});fs.copyFileSync('preload.cjs',pr);console.log('[postbuild] synced to',ext)}\"",
     "dev": "tsc --watch",
     "prepack": "npm install --omit=dev",
-    "postinstall": ""
+    "postinstall": "node scripts/postinstall-link-sdk.js 2>/dev/null || true"
   },
   "dependencies": {
     "mpg123-decoder": "^1.0.3",

package/src/api.ts

@@ -1276,9 +1276,5 @@ export async function sendC2CStreamMessage(
   if (req.stream_msg_id) {
     body.stream_msg_id = req.stream_msg_id;
   }
-  // 仅终结分片触发引用回调，中间分片跳过
-  if (req.input_state === StreamInputState.DONE) {
-    return sendAndNotify(accessToken, "POST", path, body, { text: req.content_raw });
-  }
   return apiRequest<MessageResponse>(accessToken, "POST", path, body);
 }

package/src/channel.ts

@@ -8,7 +8,7 @@ import {
 
 import type { ResolvedQQBotAccount } from "./types.js";
 import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId, resolveRequireMention, resolveToolPolicy, resolveGroupConfig } from "./config.js";
-import { sendText, sendMedia } from "./outbound.js";
+import { sendText, sendMedia, resolveUserFacingMediaError } from "./outbound.js";
 import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
@@ -28,6 +28,17 @@ export function chunkText(text: string, limit: number): string[] {
   return runtime.channel.text.chunkMarkdownText(text, limit);
 }
 
+function buildChannelMediaError(result: Parameters<typeof resolveUserFacingMediaError>[0]): Error {
+  const err = new Error(resolveUserFacingMediaError(result));
+  if (result.errorCode) {
+    (err as Error & { code?: string }).code = result.errorCode;
+  }
+  if (result.qqBizCode !== undefined) {
+    (err as Error & { qqBizCode?: number }).qqBizCode = result.qqBizCode;
+  }
+  return err;
+}
+
 export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
   id: "qqbot",
   meta: {
@@ -283,17 +294,12 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
       const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
       console.log(`[qqbot:channel] sendMedia result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
       // 此 sendMedia 是框架 Channel Plugin 的标准出站接口，
-      // 用于非 gateway deliver 场景（如 API 直接发送、cron 等）。
-      // gateway 消息响应走的是 deliver 回调 → sendPlainReply，不经过此处。
-      // 框架拿到 error 后不一定会给用户发文字兜底，所以这里主动发一条。
+      // 由框架 deliver.js (deliverOutboundPayloads) 或 message-actions 调用。
+      // 当 throw Error 后，框架 pi-tool-definition-adapter 会将错误转化为
+      // tool 的 { status: "error" } 返回给 AI 模型，模型会自行生成错误回复给用户。
+      // 因此此处不应主动发送兜底文本，否则会与模型的回复重复。
       if (result.error) {
-        try {
-          const fallbackResult = await sendText({ to, text: result.error, accountId, replyToId, account });
-          console.log(`[qqbot:channel] sendMedia fallback text sent: messageId=${fallbackResult.messageId}, error=${fallbackResult.error ?? "none"}`);
-        } catch (fallbackErr) {
-          console.error(`[qqbot:channel] sendMedia fallback text failed: ${fallbackErr}`);
-        }
-        throw new Error(result.error);
+        throw buildChannelMediaError(result);
       }
       return {
         channel: "qqbot" as const,

package/src/outbound-deliver.ts

@@ -7,8 +7,20 @@
  */
 
 import type { ResolvedQQBotAccount } from "./types.js";
-import { sendC2CMessage, sendGroupMessage, sendChannelMessage, sendC2CImageMessage, sendGroupImageMessage } from "./api.js";
-import { sendPhoto, sendMedia as sendMediaAuto, type MediaTargetContext } from "./outbound.js";
+import {
+  sendC2CMessage,
+  sendGroupMessage,
+  sendChannelMessage,
+  sendC2CImageMessage,
+  sendGroupImageMessage,
+} from "./api.js";
+import {
+  sendPhoto,
+  sendMedia as sendMediaAuto,
+  DEFAULT_MEDIA_SEND_ERROR,
+  resolveUserFacingMediaError,
+  type MediaTargetContext,
+} from "./outbound.js";
 import { chunkText, TEXT_CHUNK_LIMIT } from "./channel.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize } from "./utils/image-size.js";
@@ -217,13 +229,13 @@ export async function sendPlainReply(
         });
         if (result.error) {
           log?.error(`${prefix} sendMedia(auto) error for ${mediaPath}: ${result.error}`);
-          await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+          await sendTextChunks(resolveUserFacingMediaError(result), event, actx, sendWithRetry, consumeQuoteRef);
         } else {
           log?.info(`${prefix} Sent local media: ${mediaPath}`);
         }
       } catch (err) {
         log?.error(`${prefix} sendMedia(auto) failed for ${mediaPath}: ${err}`);
-        await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+        await sendTextChunks(DEFAULT_MEDIA_SEND_ERROR, event, actx, sendWithRetry, consumeQuoteRef);
       }
     }
   }
@@ -245,13 +257,13 @@ export async function sendPlainReply(
           });
           if (result.error) {
             log?.error(`${prefix} Tool media forward error: ${result.error}`);
-            await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+            await sendTextChunks(resolveUserFacingMediaError(result), event, actx, sendWithRetry, consumeQuoteRef);
           } else {
             log?.info(`${prefix} Forwarded tool media: ${mediaUrl.slice(0, 80)}...`);
           }
         } catch (err) {
           log?.error(`${prefix} Tool media forward failed: ${err}`);
-          await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+          await sendTextChunks(DEFAULT_MEDIA_SEND_ERROR, event, actx, sendWithRetry, consumeQuoteRef);
         }
       }
     }
@@ -261,6 +273,7 @@ export async function sendPlainReply(
 
 // ============ 内部辅助函数 ============
 
+
 /** 发送文本分块（共用逻辑） */
 async function sendTextChunks(
   text: string,
@@ -441,13 +454,13 @@ async function sendPlainTextReply(
         const imgResult = await sendPhoto(imgMediaTarget, imageUrl);
         if (imgResult.error) {
           log?.error(`${prefix} Failed to send image: ${imgResult.error}`);
-          await sendTextChunks(`发送图片失败：${imgResult.error}`, event, actx, sendWithRetry, consumeQuoteRef);
+          await sendTextChunks(resolveUserFacingMediaError(imgResult), event, actx, sendWithRetry, consumeQuoteRef);
         } else {
           log?.info(`${prefix} Sent image via sendPhoto: ${imageUrl.slice(0, 80)}...`);
         }
       } catch (imgErr) {
         log?.error(`${prefix} Failed to send image: ${imgErr}`);
-        await sendTextChunks(`发送图片失败：${imgErr}`, event, actx, sendWithRetry, consumeQuoteRef);
+        await sendTextChunks(DEFAULT_MEDIA_SEND_ERROR, event, actx, sendWithRetry, consumeQuoteRef);
       }
     }
 

package/src/outbound.ts

@@ -17,6 +17,7 @@ import {
   sendC2CMediaMessage,
   sendGroupMediaMessage,
   MediaFileType,
+  UPLOAD_PREPARE_FALLBACK_CODE,
 } from "./api.js";
 import { isAudioFile, audioFileToSilkFile, waitForFile, shouldTranscodeVoice } from "./utils/audio-convert.js";
 import { fileExistsAsync, formatFileSize, getMaxUploadSize, getFileTypeName, getFileSizeAsync } from "./utils/file-utils.js";
@@ -166,15 +167,48 @@ export interface MediaOutboundContext extends OutboundContext {
   mimeType?: string;
 }
 
+export const OUTBOUND_ERROR_CODES = {
+  FILE_TOO_LARGE: "file_too_large",
+  UPLOAD_DAILY_LIMIT_EXCEEDED: "upload_daily_limit_exceeded",
+} as const;
+
+export const DEFAULT_MEDIA_SEND_ERROR = "发送失败，请稍后重试。";
+
+export type OutboundErrorCode = typeof OUTBOUND_ERROR_CODES[keyof typeof OUTBOUND_ERROR_CODES];
+
 export interface OutboundResult {
   channel: string;
   messageId?: string;
   timestamp?: string | number;
   error?: string;
+  /** 稳定错误码，供上层按类型处理，避免依赖 error 文案 */
+  errorCode?: OutboundErrorCode;
+  /** QQ 开放平台业务错误码（如 upload_prepare 的 40093002） */
+  qqBizCode?: number;
   /** 出站消息的引用索引（ext_info.ref_idx），供引用消息缓存使用 */
   refIdx?: string;
 }
 
+/**
+ * 将媒体发送结果映射为可展示给用户的文案。
+ * 只对明确标记为可直接展示的错误码透传原文，其余统一走通用兜底。
+ */
+export function resolveUserFacingMediaError(result: Pick<OutboundResult, "error" | "errorCode" | "qqBizCode">): string {
+  if (!result.error) return DEFAULT_MEDIA_SEND_ERROR;
+
+  if (result.qqBizCode === UPLOAD_PREPARE_FALLBACK_CODE) {
+    return result.error;
+  }
+
+  switch (result.errorCode) {
+    case OUTBOUND_ERROR_CODES.FILE_TOO_LARGE:
+    case OUTBOUND_ERROR_CODES.UPLOAD_DAILY_LIMIT_EXCEEDED:
+      return result.error;
+    default:
+      return DEFAULT_MEDIA_SEND_ERROR;
+  }
+}
+
 /**
  * 解析目标地址
  * 格式：
@@ -511,7 +545,11 @@ async function chunkedUploadAndSend(
   if (fileSize > maxSize) {
     const typeName = getFileTypeName(fileType);
     const limitMB = Math.round(maxSize / (1024 * 1024));
-    return { channel: "qqbot", error: `${typeName}过大（${formatFileSize(fileSize)}），超过了${limitMB}M，暂时不能通过QQ直接发给你。` };
+    return {
+      channel: "qqbot",
+      error: `${typeName}过大（${formatFileSize(fileSize)}），超过了${limitMB}M，暂时不能通过QQ直接发给你。`,
+      errorCode: OUTBOUND_ERROR_CODES.FILE_TOO_LARGE,
+    };
   }
 
   if (ctx.targetType === "c2c") {
@@ -537,7 +575,12 @@ async function chunkedUploadAndSend(
         const dir = path.dirname(err.filePath);
         const name = path.basename(err.filePath);
         const size = formatFileSize(err.fileSize);
-        return { channel: "qqbot", error: `QQBot每天发送文件有累计2G的限制，如果着急的话，可以直接来我的主机copy下载，文件目录\`${dir}/${name}\`（${size}）` };
+        return {
+          channel: "qqbot",
+          error: `QQBot每天发送文件有累计2G的限制，如果着急的话，可以直接来我的主机copy下载，文件目录\`${dir}/${name}\`（${size}）`,
+          errorCode: OUTBOUND_ERROR_CODES.UPLOAD_DAILY_LIMIT_EXCEEDED,
+          qqBizCode: UPLOAD_PREPARE_FALLBACK_CODE,
+        };
       }
       return { channel: "qqbot", error: `文件发送失败，请稍后重试。` };
     }
@@ -566,7 +609,12 @@ async function chunkedUploadAndSend(
         const dir = path.dirname(err.filePath);
         const name = path.basename(err.filePath);
         const size = formatFileSize(err.fileSize);
-        return { channel: "qqbot", error: `QQBot每天发送文件有累计2G的限制，如果着急的话，可以直接来我的主机copy下载，文件目录\`${dir}/${name}\`（${size}）` };
+        return {
+          channel: "qqbot",
+          error: `QQBot每天发送文件有累计2G的限制，如果着急的话，可以直接来我的主机copy下载，文件目录\`${dir}/${name}\`（${size}）`,
+          errorCode: OUTBOUND_ERROR_CODES.UPLOAD_DAILY_LIMIT_EXCEEDED,
+          qqBizCode: UPLOAD_PREPARE_FALLBACK_CODE,
+        };
       }
       return { channel: "qqbot", error: `文件发送失败，请稍后重试。` };
     }

package/src/utils/media-send.ts

@@ -14,6 +14,8 @@ import {
   sendVideoMsg,
   sendDocument,
   sendMedia as sendMediaAuto,
+  DEFAULT_MEDIA_SEND_ERROR,
+  resolveUserFacingMediaError,
   type MediaTargetContext,
 } from "../outbound.js";
 import type { ResolvedQQBotAccount } from "../types.js";
@@ -410,7 +412,6 @@ export async function executeSendQueue(
   };
 
   for (const item of queue) {
-    const FALLBACK_MSG = "发送失败，请稍后重试。";
     try {
       if (item.type === "text") {
         if (options.skipInterTagText) {
@@ -431,7 +432,7 @@ export async function executeSendQueue(
         const result = await sendPhoto(mediaTarget, item.content);
         if (result.error) {
           log?.error(`${prefix} sendPhoto error: ${result.error}`);
-          await sendFallbackText(FALLBACK_MSG);
+          await sendFallbackText(resolveUserFacingMediaError(result));
         }
       } else if (item.type === "voice") {
         const uploadFormats =
@@ -452,23 +453,23 @@ export async function executeSendQueue(
           ]);
           if (result.error) {
             log?.error(`${prefix} sendVoice error: ${result.error}`);
-            await sendFallbackText(FALLBACK_MSG);
+            await sendFallbackText(resolveUserFacingMediaError(result));
           }
         } catch (err) {
           log?.error(`${prefix} sendVoice unexpected error: ${err}`);
-          await sendFallbackText(FALLBACK_MSG);
+          await sendFallbackText(DEFAULT_MEDIA_SEND_ERROR);
         }
       } else if (item.type === "video") {
         const result = await sendVideoMsg(mediaTarget, item.content);
         if (result.error) {
           log?.error(`${prefix} sendVideoMsg error: ${result.error}`);
-          await sendFallbackText(FALLBACK_MSG);
+          await sendFallbackText(resolveUserFacingMediaError(result));
         }
       } else if (item.type === "file") {
         const result = await sendDocument(mediaTarget, item.content);
         if (result.error) {
           log?.error(`${prefix} sendDocument error: ${result.error}`);
-          await sendFallbackText(FALLBACK_MSG);
+          await sendFallbackText(resolveUserFacingMediaError(result));
         }
       } else if (item.type === "media") {
         const result = await sendMediaAuto({
@@ -481,12 +482,12 @@ export async function executeSendQueue(
         });
         if (result.error) {
           log?.error(`${prefix} sendMedia(auto) error: ${result.error}`);
-          await sendFallbackText(FALLBACK_MSG);
+          await sendFallbackText(resolveUserFacingMediaError(result));
         }
       }
     } catch (err) {
       log?.error(`${prefix} executeSendQueue: failed to send ${item.type}: ${err}`);
-      await sendFallbackText(FALLBACK_MSG);
+      await sendFallbackText(DEFAULT_MEDIA_SEND_ERROR);
     }
   }
 }