@tencent-connect/openclaw-qqbot 1.6.6-alpha.1 → 1.6.6-alpha.3

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.6.6`
+### 🚀 Current Version: `v1.6.5`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -46,7 +46,6 @@ Scan to join the QQ group chat
 | 📝 **Markdown** | Full Markdown formatting support |
 | 🛠️ **Commands** | Native OpenClaw command integration |
 | 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |
-| 📦 **Large File Support** | Auto chunked upload for large files (parallel upload with retry), up to 100 MB |
 
 ---
 
@@ -130,7 +129,7 @@ This capability depends on OpenClaw cron scheduling and proactive messaging. If
 >
 > **QQBot**: *(sends a .txt file)*
 
-AI can send files directly. Any format, up to 100MB. Large files are automatically chunked and uploaded in parallel.
+AI can send files directly. Any format, up to 20MB.
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
 

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.6`
+### 🚀 当前版本： `v1.6.5`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -41,7 +41,6 @@
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
 | 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
-| 📦 **大文件支持** | 大文件自动分片并行上传，最大支持 100 MB |
 
 ---
 
@@ -125,7 +124,7 @@ AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg
 >
 > **QQBot**：*（发送 .txt 文件）*
 
-AI 可直接发送文件。任意格式，最大 100MB。大文件自动分片并行上传。
+AI 可直接发送文件。任意格式，最大 20MB。
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
 

package/dist/src/api.d.ts

@@ -2,11 +2,19 @@
  * QQ Bot API 鉴权和请求封装
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
-/** API 请求错误，携带 HTTP status code */
+/** API 请求错误，携带 HTTP status code 和业务错误码 */
 export declare class ApiError extends Error {
     readonly status: number;
     readonly path: string;
-    constructor(message: string, status: number, path: string);
+    /** 业务错误码（回包中的 code / err_code 字段），不一定存在 */
+    readonly bizCode?: number | undefined;
+    /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
+    readonly bizMessage?: string | undefined;
+    constructor(message: string, status: number, path: string, 
+    /** 业务错误码（回包中的 code / err_code 字段），不一定存在 */
+    bizCode?: number | undefined, 
+    /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
+    bizMessage?: string | undefined);
 }
 export declare const PLUGIN_USER_AGENT: string;
 /** 出站消息元信息（结构化存储，不做预格式化） */
@@ -69,6 +77,16 @@ export declare function getNextMsgSeq(_msgId: string): number;
  * API 请求封装
  */
 export declare function apiRequest<T = unknown>(accessToken: string, method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
+/**
+ * 需要持续重试的业务错误码集合
+ * 当 upload_part_finish 返回这些错误码时，会以固定 1s 间隔持续重试直到成功或超时
+ */
+export declare const PART_FINISH_RETRYABLE_CODES: Set<number>;
+/**
+ * upload_prepare 接口命中此错误码时，使用回包中的 message 字段作为兜底文案发送给用户
+ * 而非走通用的"文件发送失败，请稍后重试"
+ */
+export declare const UPLOAD_PREPARE_FALLBACK_CODE = 40093002;
 export declare function getGatewayUrl(accessToken: string): Promise<string>;
 export interface MessageResponse {
     id: string;
@@ -128,6 +146,10 @@ export interface UploadPrepareResponse {
     block_size: number;
     /** 分片列表（含预签名链接） */
     parts: UploadPart[];
+    /** 上传并发数（由服务端控制，可选，不返回时使用客户端默认值） */
+    concurrency?: number;
+    /** upload_part_finish 特定错误码的重试超时时间（秒），由服务端控制，客户端上限 10 分钟 */
+    retry_timeout?: number;
 }
 /** 完成文件上传响应（与 UploadMediaResponse 一致） */
 export interface MediaUploadResponse {
@@ -171,7 +193,7 @@ export declare function c2cUploadPrepare(accessToken: string, userId: string, fi
  * @param blockSize - 分块大小（字节）
  * @param md5 - 分片数据的 MD5（十六进制）
  */
-export declare function c2cUploadPartFinish(accessToken: string, userId: string, uploadId: string, partIndex: number, blockSize: number, md5: string): Promise<void>;
+export declare function c2cUploadPartFinish(accessToken: string, userId: string, uploadId: string, partIndex: number, blockSize: number, md5: string, retryTimeoutMs?: number): Promise<void>;
 /**
  * 完成文件上传（C2C）
  * POST /v2/users/{user_id}/files
@@ -191,7 +213,7 @@ export declare function groupUploadPrepare(accessToken: string, groupId: string,
  * 完成分片上传（Group）
  * POST /v2/groups/{group_id}/upload_part_finish
  */
-export declare function groupUploadPartFinish(accessToken: string, groupId: string, uploadId: string, partIndex: number, blockSize: number, md5: string): Promise<void>;
+export declare function groupUploadPartFinish(accessToken: string, groupId: string, uploadId: string, partIndex: number, blockSize: number, md5: string, retryTimeoutMs?: number): Promise<void>;
 /**
  * 完成文件上传（Group）
  * POST /v2/groups/{group_id}/files

package/dist/src/api.js

@@ -6,14 +6,22 @@ import os from "node:os";
 import { computeFileHash, getCachedFileInfo, setCachedFileInfo } from "./utils/upload-cache.js";
 import { sanitizeFileName } from "./utils/platform.js";
 // ============ 自定义错误 ============
-/** API 请求错误，携带 HTTP status code */
+/** API 请求错误，携带 HTTP status code 和业务错误码 */
 export class ApiError extends Error {
     status;
     path;
-    constructor(message, status, path) {
+    bizCode;
+    bizMessage;
+    constructor(message, status, path, 
+    /** 业务错误码（回包中的 code / err_code 字段），不一定存在 */
+    bizCode, 
+    /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
+    bizMessage) {
         super(message);
         this.status = status;
         this.path = path;
+        this.bizCode = bizCode;
+        this.bizMessage = bizMessage;
         this.name = "ApiError";
     }
 }
@@ -264,7 +272,8 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
         // JSON 错误响应
         try {
             const error = JSON.parse(rawBody);
-            throw new ApiError(`API Error [${path}]: ${error.message ?? rawBody}`, res.status, path);
+            const bizCode = error.code ?? error.err_code;
+            throw new ApiError(`API Error [${path}]: ${error.message ?? rawBody}`, res.status, path, bizCode, error.message);
         }
         catch (parseErr) {
             if (parseErr instanceof ApiError)
@@ -332,10 +341,50 @@ async function completeUploadWithRetry(accessToken, method, path, body) {
     }
     throw lastError;
 }
-// ============ 分片完成重试（无条件，与 completeUpload 策略一致） ============
+// ============ 分片完成重试 ============
+/** 普通错误最大重试次数 */
 const PART_FINISH_MAX_RETRIES = 2;
 const PART_FINISH_BASE_DELAY_MS = 1000;
-async function partFinishWithRetry(accessToken, method, path, body) {
+/**
+ * 需要持续重试的业务错误码集合
+ * 当 upload_part_finish 返回这些错误码时，会以固定 1s 间隔持续重试直到成功或超时
+ */
+export const PART_FINISH_RETRYABLE_CODES = new Set([
+    40093001,
+]);
+/**
+ * upload_prepare 接口命中此错误码时，使用回包中的 message 字段作为兜底文案发送给用户
+ * 而非走通用的"文件发送失败，请稍后重试"
+ */
+export const UPLOAD_PREPARE_FALLBACK_CODE = 40093002;
+/** 特定错误码持续重试的默认超时（服务端未返回 retry_timeout 时的兜底） */
+const PART_FINISH_RETRYABLE_DEFAULT_TIMEOUT_MS = 2 * 60 * 1000;
+/** 特定错误码重试的固定间隔（1 秒） */
+const PART_FINISH_RETRYABLE_INTERVAL_MS = 1000;
+/**
+ * 判断错误是否命中"需要持续重试"的业务错误码
+ */
+function isRetryableBizCode(err) {
+    if (PART_FINISH_RETRYABLE_CODES.size === 0)
+        return false;
+    if (err instanceof ApiError && err.bizCode !== undefined) {
+        return PART_FINISH_RETRYABLE_CODES.has(err.bizCode);
+    }
+    return false;
+}
+/**
+ * 分片完成接口重试策略：
+ *
+ * 1. 命中 PART_FINISH_RETRYABLE_CODES 的错误码 → 每 1s 重试一次，直到成功或超时
+ *    超时时间 = min(API 返回的 retry_timeout, 10 分钟)
+ * 2. 其他错误 → 最多重试 PART_FINISH_MAX_RETRIES 次（与之前逻辑一致）
+ *
+ * 若持续重试超时或普通重试耗尽，抛出错误，调用方（chunkedUpload）
+ * 可据此中止后续分片上传。
+ *
+ * @param retryTimeoutMs - 持续重试的超时时间（毫秒），由 upload_prepare 返回的 retry_timeout 计算得出
+ */
+async function partFinishWithRetry(accessToken, method, path, body, retryTimeoutMs) {
     let lastError = null;
     for (let attempt = 0; attempt <= PART_FINISH_MAX_RETRIES; attempt++) {
         try {
@@ -344,6 +393,13 @@ async function partFinishWithRetry(accessToken, method, path, body) {
         }
         catch (err) {
             lastError = err instanceof Error ? err : new Error(String(err));
+            // 命中特定错误码 → 进入持续重试模式
+            if (isRetryableBizCode(err)) {
+                const timeoutMs = retryTimeoutMs ?? PART_FINISH_RETRYABLE_DEFAULT_TIMEOUT_MS;
+                console.warn(`[qqbot-api] PartFinish hit retryable bizCode=${err.bizCode}, entering persistent retry (timeout=${timeoutMs / 1000}s, interval=1s)...`);
+                await partFinishPersistentRetry(accessToken, method, path, body, timeoutMs);
+                return;
+            }
             if (attempt < PART_FINISH_MAX_RETRIES) {
                 const delay = PART_FINISH_BASE_DELAY_MS * Math.pow(2, attempt);
                 console.warn(`[qqbot-api] PartFinish attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 200)}`);
@@ -353,6 +409,40 @@ async function partFinishWithRetry(accessToken, method, path, body) {
     }
     throw lastError;
 }
+/**
+ * 特定错误码的持续重试模式
+ * 不限次数，仅受总超时时间约束，固定每 1 秒重试一次
+ */
+async function partFinishPersistentRetry(accessToken, method, path, body, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+    let lastError = null;
+    while (Date.now() < deadline) {
+        try {
+            await apiRequest(accessToken, method, path, body);
+            console.log(`[qqbot-api] PartFinish persistent retry succeeded after ${attempt} retries`);
+            return;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            // 如果不再是可重试的错误码，直接抛出（可能是其他类型的错误）
+            if (!isRetryableBizCode(err)) {
+                console.error(`[qqbot-api] PartFinish persistent retry: error is no longer retryable (bizCode=${err.bizCode ?? "N/A"}), aborting`);
+                throw lastError;
+            }
+            attempt++;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            const actualDelay = Math.min(PART_FINISH_RETRYABLE_INTERVAL_MS, remaining);
+            console.warn(`[qqbot-api] PartFinish persistent retry #${attempt}: bizCode=${err.bizCode}, retrying in ${actualDelay}ms (remaining=${Math.round(remaining / 1000)}s)`);
+            await new Promise(resolve => setTimeout(resolve, actualDelay));
+        }
+    }
+    // 超时
+    console.error(`[qqbot-api] PartFinish persistent retry timed out after ${timeoutMs / 1000}s (${attempt} attempts)`);
+    throw new Error(`upload_part_finish 持续重试超时（${timeoutMs / 1000}s, ${attempt} 次重试），中止上传`);
+}
 export async function getGatewayUrl(accessToken) {
     const data = await apiRequest(accessToken, "GET", "/gateway");
     return data.url;
@@ -487,8 +577,8 @@ export async function c2cUploadPrepare(accessToken, userId, fileType, fileName,
  * @param blockSize - 分块大小（字节）
  * @param md5 - 分片数据的 MD5（十六进制）
  */
-export async function c2cUploadPartFinish(accessToken, userId, uploadId, partIndex, blockSize, md5) {
-    await partFinishWithRetry(accessToken, "POST", `/v2/users/${userId}/upload_part_finish`, { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 });
+export async function c2cUploadPartFinish(accessToken, userId, uploadId, partIndex, blockSize, md5, retryTimeoutMs) {
+    await partFinishWithRetry(accessToken, "POST", `/v2/users/${userId}/upload_part_finish`, { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 }, retryTimeoutMs);
 }
 /**
  * 完成文件上传（C2C）
@@ -513,8 +603,8 @@ export async function groupUploadPrepare(accessToken, groupId, fileType, fileNam
  * 完成分片上传（Group）
  * POST /v2/groups/{group_id}/upload_part_finish
  */
-export async function groupUploadPartFinish(accessToken, groupId, uploadId, partIndex, blockSize, md5) {
-    await partFinishWithRetry(accessToken, "POST", `/v2/groups/${groupId}/upload_part_finish`, { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 });
+export async function groupUploadPartFinish(accessToken, groupId, uploadId, partIndex, blockSize, md5, retryTimeoutMs) {
+    await partFinishWithRetry(accessToken, "POST", `/v2/groups/${groupId}/upload_part_finish`, { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 }, retryTimeoutMs);
 }
 /**
  * 完成文件上传（Group）

package/dist/src/outbound-deliver.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(result.error, event, actx, sendWithRetry, consumeQuoteRef);
+                    await sendTextChunks("发送失败，请稍后重试。", 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(`发送媒体失败：${err}`, event, actx, sendWithRetry, consumeQuoteRef);
+                await sendTextChunks("发送失败，请稍后重试。", 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(result.error, event, actx, sendWithRetry, consumeQuoteRef);
+                        await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
                     }
                     else {
                         log?.info(`${prefix} Forwarded tool media: ${mediaUrl.slice(0, 80)}...`);
@@ -191,6 +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);
                 }
             }
         }

package/dist/src/outbound.js

@@ -8,7 +8,7 @@ import { decodeCronPayload } from "./utils/payload.js";
 import { getAccessToken, sendC2CMessage, sendChannelMessage, sendGroupMessage, sendProactiveC2CMessage, sendProactiveGroupMessage, sendC2CMediaMessage, sendGroupMediaMessage, MediaFileType, } 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 } from "./utils/chunked-upload.js";
+import { chunkedUploadC2C, chunkedUploadGroup, UploadPrepareFallbackError } from "./utils/chunked-upload.js";
 import { isLocalPath as isLocalFilePath, normalizePath, getQQBotMediaDir } from "./utils/platform.js";
 import { downloadFile } from "./image-server.js";
 import { parseMediaTagsToSendQueue, executeSendQueue } from "./utils/media-send.js";
@@ -393,6 +393,12 @@ sendMeta) {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             console.error(`${prefix} ${callerName}: c2c chunked upload failed: ${msg}`);
+            if (err instanceof UploadPrepareFallbackError) {
+                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: `文件发送失败，请稍后重试。` };
         }
     }
@@ -412,6 +418,12 @@ sendMeta) {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             console.error(`${prefix} ${callerName}: group chunked upload failed: ${msg}`);
+            if (err instanceof UploadPrepareFallbackError) {
+                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: `文件发送失败，请稍后重试。` };
         }
     }

package/dist/src/utils/chunked-upload.d.ts

@@ -13,6 +13,17 @@
  * 注意：N 个分片之间是并行的，但每个分片的"上传 + 完成"是串行的。
  */
 import { type MediaFileType, type MediaUploadResponse } from "../api.js";
+/**
+ * upload_prepare 返回特定错误码时抛出的错误
+ * 调用方根据携带的文件信息构造兜底文案发送给用户
+ */
+export declare class UploadPrepareFallbackError extends Error {
+    /** 触发错误的本地文件路径 */
+    readonly filePath: string;
+    /** 文件大小（字节） */
+    readonly fileSize: number;
+    constructor(filePath: string, fileSize: number, originalMessage: string);
+}
 /** 分片上传进度回调 */
 export interface ChunkedUploadProgress {
     /** 当前已完成分片数 */
@@ -28,8 +39,6 @@ export interface ChunkedUploadProgress {
 export interface ChunkedUploadOptions {
     /** 进度回调 */
     onProgress?: (progress: ChunkedUploadProgress) => void;
-    /** 最大并发数（默认 2） */
-    maxConcurrent?: number;
     /** 日志前缀 */
     logPrefix?: string;
 }

package/dist/src/utils/chunked-upload.js

@@ -14,10 +14,30 @@
  */
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
-import { c2cUploadPrepare, c2cUploadPartFinish, c2cCompleteUpload, groupUploadPrepare, groupUploadPartFinish, groupCompleteUpload, getAccessToken, } from "../api.js";
+import { ApiError, UPLOAD_PREPARE_FALLBACK_CODE, c2cUploadPrepare, c2cUploadPartFinish, c2cCompleteUpload, groupUploadPrepare, groupUploadPartFinish, groupCompleteUpload, getAccessToken, } from "../api.js";
 import { formatFileSize } from "./file-utils.js";
-/** 分片上传并发控制：最多同时上传 N 个分片 */
-const MAX_CONCURRENT_PARTS = 1;
+/**
+ * upload_prepare 返回特定错误码时抛出的错误
+ * 调用方根据携带的文件信息构造兜底文案发送给用户
+ */
+export class UploadPrepareFallbackError extends Error {
+    /** 触发错误的本地文件路径 */
+    filePath;
+    /** 文件大小（字节） */
+    fileSize;
+    constructor(filePath, fileSize, originalMessage) {
+        super(originalMessage);
+        this.name = "UploadPrepareFallbackError";
+        this.filePath = filePath;
+        this.fileSize = fileSize;
+    }
+}
+/** 分片上传默认并发数（服务端未返回 concurrency 时的兜底） */
+const DEFAULT_CONCURRENT_PARTS = 1;
+/** 分片上传并发上限（即使服务端返回更大的值也不超过此限制） */
+const MAX_CONCURRENT_PARTS = 10;
+/** partFinish 特定错误码重试超时上限（10 分钟），即使服务端 retry_timeout 更大也不超过此值 */
+const MAX_PART_FINISH_RETRY_TIMEOUT_MS = 10 * 60 * 1000;
 /** 单个分片上传超时（毫秒）— 5 分钟，兼容低带宽场景 */
 const PART_UPLOAD_TIMEOUT = 300_000;
 /** 单个分片上传最大重试次数 */
@@ -35,7 +55,6 @@ const PART_UPLOAD_MAX_RETRIES = 2;
  */
 export async function chunkedUploadC2C(appId, clientSecret, userId, filePath, fileType, options) {
     const prefix = options?.logPrefix ?? "[chunked-upload]";
-    const maxConcurrent = options?.maxConcurrent ?? MAX_CONCURRENT_PARTS;
     // 1. 读取文件信息
     const stat = await fs.promises.stat(filePath);
     const fileSize = stat.size;
@@ -48,12 +67,29 @@ export async function chunkedUploadC2C(appId, clientSecret, userId, filePath, fi
     // 3. 申请上传 → 获取 upload_id + block_size + 预签名链接
     const accessToken = await getAccessToken(appId, clientSecret);
     console.log(`${prefix} >>> Calling c2cUploadPrepare(fileType=${fileType}, fileName=${fileName}, fileSize=${fileSize}, md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m})`);
-    const prepareResp = await c2cUploadPrepare(accessToken, userId, fileType, fileName, fileSize, hashes);
+    let prepareResp;
+    try {
+        prepareResp = await c2cUploadPrepare(accessToken, userId, fileType, fileName, fileSize, hashes);
+    }
+    catch (err) {
+        // 命中特定错误码 → 携带文件信息抛出，由上层构造兜底文案
+        if (err instanceof ApiError && err.bizCode === UPLOAD_PREPARE_FALLBACK_CODE) {
+            console.warn(`${prefix} c2cUploadPrepare hit fallback code ${UPLOAD_PREPARE_FALLBACK_CODE}`);
+            throw new UploadPrepareFallbackError(filePath, fileSize, err.message);
+        }
+        throw err;
+    }
     console.log(`${prefix} <<< c2cUploadPrepare response:`, JSON.stringify(prepareResp));
     const { upload_id, parts } = prepareResp;
     // QQ 开放平台返回的 block_size 可能是字符串，需要转为数字
     const block_size = Number(prepareResp.block_size);
-    console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}`);
+    // 并发数：使用 API 返回的 concurrency，未返回则用默认值，且不超过上限
+    const maxConcurrent = Math.min(prepareResp.concurrency ? Number(prepareResp.concurrency) : DEFAULT_CONCURRENT_PARTS, MAX_CONCURRENT_PARTS);
+    // partFinish 特定错误码的重试超时：使用 API 返回的 retry_timeout（秒），上限 10 分钟
+    const retryTimeoutMs = prepareResp.retry_timeout
+        ? Math.min(Number(prepareResp.retry_timeout) * 1000, MAX_PART_FINISH_RETRY_TIMEOUT_MS)
+        : undefined;
+    console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}, concurrency=${maxConcurrent}, retryTimeout=${retryTimeoutMs ? retryTimeoutMs / 1000 + 's' : 'default'}`);
     // 4. 并行上传所有分片（带并发控制）
     let completedParts = 0;
     let uploadedBytes = 0;
@@ -73,7 +109,7 @@ export async function chunkedUploadC2C(appId, clientSecret, userId, filePath, fi
         // b. 通知开放平台分片上传完成（需要重新获取 token，避免长时间上传后 token 过期）
         const token = await getAccessToken(appId, clientSecret);
         console.log(`${prefix} >>> Calling c2cUploadPartFinish(upload_id=${upload_id}, partIndex=${partIndex}, blockSize=${length}, md5=${md5Hex})`);
-        await c2cUploadPartFinish(token, userId, upload_id, partIndex, length, md5Hex);
+        await c2cUploadPartFinish(token, userId, upload_id, partIndex, length, md5Hex, retryTimeoutMs);
         console.log(`${prefix} <<< c2cUploadPartFinish(partIndex=${partIndex}) done`);
         // 更新进度
         completedParts++;
@@ -112,7 +148,6 @@ export async function chunkedUploadC2C(appId, clientSecret, userId, filePath, fi
  */
 export async function chunkedUploadGroup(appId, clientSecret, groupId, filePath, fileType, options) {
     const prefix = options?.logPrefix ?? "[chunked-upload]";
-    const maxConcurrent = options?.maxConcurrent ?? MAX_CONCURRENT_PARTS;
     // 1. 读取文件信息
     const stat = await fs.promises.stat(filePath);
     const fileSize = stat.size;
@@ -125,12 +160,29 @@ export async function chunkedUploadGroup(appId, clientSecret, groupId, filePath,
     // 3. 申请上传
     const accessToken = await getAccessToken(appId, clientSecret);
     console.log(`${prefix} >>> Calling groupUploadPrepare(fileType=${fileType}, fileName=${fileName}, fileSize=${fileSize}, md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m})`);
-    const prepareResp = await groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes);
+    let prepareResp;
+    try {
+        prepareResp = await groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes);
+    }
+    catch (err) {
+        // 命中特定错误码 → 携带文件信息抛出，由上层构造兜底文案
+        if (err instanceof ApiError && err.bizCode === UPLOAD_PREPARE_FALLBACK_CODE) {
+            console.warn(`${prefix} groupUploadPrepare hit fallback code ${UPLOAD_PREPARE_FALLBACK_CODE}`);
+            throw new UploadPrepareFallbackError(filePath, fileSize, err.message);
+        }
+        throw err;
+    }
     console.log(`${prefix} <<< groupUploadPrepare response:`, JSON.stringify(prepareResp));
     const { upload_id, parts } = prepareResp;
     // QQ 开放平台返回的 block_size 可能是字符串，需要转为数字
     const block_size = Number(prepareResp.block_size);
-    console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}`);
+    // 并发数：使用 API 返回的 concurrency，未返回则用默认值，且不超过上限
+    const maxConcurrent = Math.min(prepareResp.concurrency ? Number(prepareResp.concurrency) : DEFAULT_CONCURRENT_PARTS, MAX_CONCURRENT_PARTS);
+    // partFinish 特定错误码的重试超时：使用 API 返回的 retry_timeout（秒），上限 10 分钟
+    const retryTimeoutMs = prepareResp.retry_timeout
+        ? Math.min(Number(prepareResp.retry_timeout) * 1000, MAX_PART_FINISH_RETRY_TIMEOUT_MS)
+        : undefined;
+    console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}, concurrency=${maxConcurrent}, retryTimeout=${retryTimeoutMs ? retryTimeoutMs / 1000 + 's' : 'default'}`);
     // 4. 并行上传所有分片（带并发控制）
     let completedParts = 0;
     let uploadedBytes = 0;
@@ -145,7 +197,7 @@ export async function chunkedUploadGroup(appId, clientSecret, groupId, filePath,
         await putToPresignedUrl(part.presigned_url, partBuffer, prefix, partNum, parts.length);
         const token = await getAccessToken(appId, clientSecret);
         console.log(`${prefix} >>> Calling groupUploadPartFinish(upload_id=${upload_id}, partIndex=${partIndex}, blockSize=${length}, md5=${md5Hex})`);
-        await groupUploadPartFinish(token, groupId, upload_id, partIndex, length, md5Hex);
+        await groupUploadPartFinish(token, groupId, upload_id, partIndex, length, md5Hex, retryTimeoutMs);
         console.log(`${prefix} <<< groupUploadPartFinish(partIndex=${partIndex}) done`);
         completedParts++;
         uploadedBytes += length;

package/dist/src/utils/media-send.d.ts

@@ -125,6 +125,7 @@ export declare function parseMediaTagsToSendQueue(text: string, log?: {
  *
  * 遍历 sendQueue，按类型调用对应的发送函数。
  * 文本项通过 onSendText 回调处理（不同场景的文本发送方式不同）。
+ * 媒体发送失败时，通过 onSendText 发送兜底文本通知用户。
  */
 export declare function executeSendQueue(queue: SendQueueItem[], ctx: MediaSendContext, options?: {
     /** 文本发送回调（每种场景的文本发送方式不同） */

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

@@ -221,11 +221,26 @@ export function parseMediaTagsToSendQueue(text, log) {
  *
  * 遍历 sendQueue，按类型调用对应的发送函数。
  * 文本项通过 onSendText 回调处理（不同场景的文本发送方式不同）。
+ * 媒体发送失败时，通过 onSendText 发送兜底文本通知用户。
  */
 export async function executeSendQueue(queue, ctx, options = {}) {
     const { mediaTarget, qualifiedTarget, account, replyToId, log } = ctx;
     const prefix = mediaTarget.logPrefix ?? `[qqbot:${account.accountId}]`;
+    /** 媒体发送失败时的兜底：通过 onSendText 发送错误文本给用户 */
+    const sendFallbackText = async (errorMsg) => {
+        if (!options.onSendText) {
+            log?.info(`${prefix} executeSendQueue: no onSendText handler, cannot send fallback text`);
+            return;
+        }
+        try {
+            await options.onSendText(errorMsg);
+        }
+        catch (fallbackErr) {
+            log?.error(`${prefix} executeSendQueue: fallback text send failed: ${fallbackErr}`);
+        }
+    };
     for (const item of queue) {
+        const FALLBACK_MSG = "发送失败，请稍后重试。";
         try {
             if (item.type === "text") {
                 if (options.skipInterTagText) {
@@ -245,6 +260,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);
                 }
             }
             else if (item.type === "voice") {
@@ -259,22 +275,26 @@ export async function executeSendQueue(queue, ctx, options = {}) {
                     ]);
                     if (result.error) {
                         log?.error(`${prefix} sendVoice error: ${result.error}`);
+                        await sendFallbackText(FALLBACK_MSG);
                     }
                 }
                 catch (err) {
                     log?.error(`${prefix} sendVoice unexpected error: ${err}`);
+                    await sendFallbackText(FALLBACK_MSG);
                 }
             }
             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);
                 }
             }
             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);
                 }
             }
             else if (item.type === "media") {
@@ -288,11 +308,13 @@ export async function executeSendQueue(queue, ctx, options = {}) {
                 });
                 if (result.error) {
                     log?.error(`${prefix} sendMedia(auto) error: ${result.error}`);
+                    await sendFallbackText(FALLBACK_MSG);
                 }
             }
         }
         catch (err) {
             log?.error(`${prefix} executeSendQueue: failed to send ${item.type}: ${err}`);
+            await sendFallbackText(FALLBACK_MSG);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.6.6-alpha.1",
+  "version": "1.6.6-alpha.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,7 +30,8 @@
     }
   },
   "scripts": {
-    "build": "tsc || true",
+    "prebuild": "node scripts/prebuild-stub.cjs",
+    "build": "tsc",
     "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",

package/scripts/prebuild-stub.cjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * prebuild-stub.cjs
+ *
+ * 在 openclaw peer 依赖未安装时（如独立开发环境），自动生成最小 stub 模块，
+ * 使 tsc 能正常编译。运行时 openclaw 会由宿主环境提供，stub 不会被使用。
+ *
+ * 如果 openclaw 已安装（如通过 postinstall-link-sdk 建立了 symlink），则跳过。
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const openclawDir = path.join(pluginRoot, "node_modules", "openclaw");
+
+// 如果 openclaw 已存在（真实安装或 symlink），则不覆盖
+if (fs.existsSync(path.join(openclawDir, "package.json"))) {
+  console.log("[prebuild-stub] openclaw already available, skipping stub generation");
+  process.exit(0);
+}
+
+console.log("[prebuild-stub] openclaw not found, generating type stubs...");
+
+// --- openclaw/package.json ---
+const pkgJson = {
+  name: "openclaw",
+  version: "0.0.0-stub",
+  description: "Auto-generated stub for build-time type checking",
+  main: "plugin-sdk/index.js",
+  types: "plugin-sdk/index.d.ts",
+  exports: {
+    "./plugin-sdk": {
+      types: "./plugin-sdk/index.d.ts",
+      default: "./plugin-sdk/index.js",
+    },
+    "./plugin-sdk/core": {
+      types: "./plugin-sdk/core.d.ts",
+      default: "./plugin-sdk/core.js",
+    },
+  },
+};
+
+// --- openclaw/plugin-sdk/index.d.ts ---
+const pluginSdkDts = `\
+// Auto-generated stub — provides minimal types for build-time compilation.
+// At runtime, the real openclaw package is used.
+
+export interface OpenClawPluginApi {
+  runtime: PluginRuntime;
+  registerChannel(opts: { plugin: any }): void;
+  registerTool(definition: any, options?: any): void;
+  [key: string]: any;
+}
+
+export interface PluginRuntime {
+  channel: { text: { chunkMarkdownText(text: string, limit: number): string[] } };
+  config: any;
+  [key: string]: any;
+}
+
+export interface OpenClawConfig {
+  channels?: { qqbot?: any; [key: string]: any };
+  [key: string]: any;
+}
+
+export interface ChannelPlugin<T = any> {
+  id: string;
+  meta?: any;
+  capabilities?: any;
+  reload?: any;
+  config?: {
+    listAccountIds?: (cfg: OpenClawConfig) => string[];
+    resolveAccount?: (cfg: OpenClawConfig, accountId?: string) => T;
+    defaultAccountId?: (cfg: OpenClawConfig) => string;
+    setAccountEnabled?: (opts: { cfg: OpenClawConfig; accountId: string; enabled: boolean }) => OpenClawConfig;
+    deleteAccount?: (opts: { cfg: OpenClawConfig; accountId: string }) => OpenClawConfig;
+    isConfigured?: (account: T) => boolean;
+    describeAccount?: (account: T) => any;
+    resolveAllowFrom?: (opts: { cfg: OpenClawConfig; accountId?: string | null }) => (string | number)[];
+    formatAllowFrom?: (opts: { allowFrom: Array<string | number> }) => string[];
+    [key: string]: any;
+  };
+  setup?: {
+    resolveAccountId?: (opts: { accountId?: string }) => string;
+    applyAccountName?: (opts: { cfg: OpenClawConfig; accountId: string; name: string }) => OpenClawConfig;
+    validateInput?: (opts: { input: any }) => string | null;
+    applyAccountConfig?: (opts: { cfg: OpenClawConfig; accountId: string; input: any }) => OpenClawConfig;
+    [key: string]: any;
+  };
+  messaging?: any;
+  outbound?: {
+    deliveryMode?: string;
+    chunker?: (text: string, limit: number) => string[];
+    chunkerMode?: string;
+    textChunkLimit?: number;
+    sendText?: (opts: { to: string; text: string; accountId?: string | null; replyToId?: string | null; cfg: OpenClawConfig }) => Promise<any>;
+    sendMedia?: (opts: { to: string; text?: string; mediaUrl?: string; accountId?: string | null; replyToId?: string | null; cfg: OpenClawConfig }) => Promise<any>;
+    [key: string]: any;
+  };
+  gateway?: {
+    startAccount?: (ctx: { account: T; abortSignal: AbortSignal; log: any; cfg: OpenClawConfig; setStatus: (s: any) => void; getStatus: () => any; [key: string]: any }) => Promise<void>;
+    logoutAccount?: (opts: { accountId: string; cfg: OpenClawConfig }) => Promise<any>;
+    [key: string]: any;
+  };
+  status?: {
+    defaultRuntime?: any;
+    buildChannelSummary?: (opts: { snapshot: any }) => any;
+    buildAccountSnapshot?: (opts: { account: any; runtime: any }) => any;
+    [key: string]: any;
+  };
+}
+
+export interface ChannelOnboardingAdapter {
+  [key: string]: any;
+}
+
+export interface ChannelOnboardingStatus {
+  [key: string]: any;
+}
+
+export interface ChannelOnboardingStatusContext {
+  [key: string]: any;
+}
+
+export interface ChannelOnboardingConfigureContext {
+  [key: string]: any;
+}
+
+export interface ChannelOnboardingResult {
+  [key: string]: any;
+}
+
+export function emptyPluginConfigSchema(): any;
+`;
+
+// --- openclaw/plugin-sdk/index.js ---
+const pluginSdkJs = `\
+// Auto-generated stub
+export function emptyPluginConfigSchema() { return {}; }
+`;
+
+// --- openclaw/plugin-sdk/core.d.ts ---
+const coreDts = `\
+// Auto-generated stub
+export { OpenClawConfig, ChannelPlugin } from "./index.js";
+
+export function applyAccountNameToChannelSection(opts: any): any;
+export function deleteAccountFromConfigSection(opts: any): any;
+export function setAccountEnabledInConfigSection(opts: any): any;
+`;
+
+// --- openclaw/plugin-sdk/core.js ---
+const coreJs = `\
+// Auto-generated stub
+export function applyAccountNameToChannelSection(opts) { return opts.cfg; }
+export function deleteAccountFromConfigSection(opts) { return opts.cfg; }
+export function setAccountEnabledInConfigSection(opts) { return opts.cfg; }
+`;
+
+// Write files
+const sdkDir = path.join(openclawDir, "plugin-sdk");
+fs.mkdirSync(sdkDir, { recursive: true });
+
+fs.writeFileSync(path.join(openclawDir, "package.json"), JSON.stringify(pkgJson, null, 2));
+fs.writeFileSync(path.join(sdkDir, "index.d.ts"), pluginSdkDts);
+fs.writeFileSync(path.join(sdkDir, "index.js"), pluginSdkJs);
+fs.writeFileSync(path.join(sdkDir, "core.d.ts"), coreDts);
+fs.writeFileSync(path.join(sdkDir, "core.js"), coreJs);
+
+console.log("[prebuild-stub] stub generated at node_modules/openclaw/");

package/src/api.ts

@@ -9,12 +9,16 @@ import { sanitizeFileName } from "./utils/platform.js";
 
 // ============ 自定义错误 ============
 
-/** API 请求错误，携带 HTTP status code */
+/** API 请求错误，携带 HTTP status code 和业务错误码 */
 export class ApiError extends Error {
   constructor(
     message: string,
     public readonly status: number,
     public readonly path: string,
+    /** 业务错误码（回包中的 code / err_code 字段），不一定存在 */
+    public readonly bizCode?: number,
+    /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
+    public readonly bizMessage?: string,
   ) {
     super(message);
     this.name = "ApiError";
@@ -320,8 +324,9 @@ export async function apiRequest<T = unknown>(
     }
     // JSON 错误响应
     try {
-      const error = JSON.parse(rawBody) as { message?: string; code?: number };
-      throw new ApiError(`API Error [${path}]: ${error.message ?? rawBody}`, res.status, path);
+      const error = JSON.parse(rawBody) as { message?: string; code?: number; err_code?: number };
+      const bizCode = error.code ?? error.err_code;
+      throw new ApiError(`API Error [${path}]: ${error.message ?? rawBody}`, res.status, path, bizCode, error.message);
     } catch (parseErr) {
       if (parseErr instanceof ApiError) throw parseErr;
       throw new ApiError(`API Error [${path}] HTTP ${res.status}: ${rawBody.slice(0, 200)}`, res.status, path);
@@ -413,16 +418,61 @@ async function completeUploadWithRetry(
   throw lastError!;
 }
 
-// ============ 分片完成重试（无条件，与 completeUpload 策略一致） ============
+// ============ 分片完成重试 ============
 
+/** 普通错误最大重试次数 */
 const PART_FINISH_MAX_RETRIES = 2;
 const PART_FINISH_BASE_DELAY_MS = 1000;
 
+/**
+ * 需要持续重试的业务错误码集合
+ * 当 upload_part_finish 返回这些错误码时，会以固定 1s 间隔持续重试直到成功或超时
+ */
+export const PART_FINISH_RETRYABLE_CODES: Set<number> = new Set([
+  40093001,
+]);
+
+/**
+ * upload_prepare 接口命中此错误码时，使用回包中的 message 字段作为兜底文案发送给用户
+ * 而非走通用的"文件发送失败，请稍后重试"
+ */
+export const UPLOAD_PREPARE_FALLBACK_CODE = 40093002;
+
+/** 特定错误码持续重试的默认超时（服务端未返回 retry_timeout 时的兜底） */
+const PART_FINISH_RETRYABLE_DEFAULT_TIMEOUT_MS = 2 * 60 * 1000;
+
+/** 特定错误码重试的固定间隔（1 秒） */
+const PART_FINISH_RETRYABLE_INTERVAL_MS = 1000;
+
+/**
+ * 判断错误是否命中"需要持续重试"的业务错误码
+ */
+function isRetryableBizCode(err: unknown): boolean {
+  if (PART_FINISH_RETRYABLE_CODES.size === 0) return false;
+  if (err instanceof ApiError && err.bizCode !== undefined) {
+    return PART_FINISH_RETRYABLE_CODES.has(err.bizCode);
+  }
+  return false;
+}
+
+/**
+ * 分片完成接口重试策略：
+ * 
+ * 1. 命中 PART_FINISH_RETRYABLE_CODES 的错误码 → 每 1s 重试一次，直到成功或超时
+ *    超时时间 = min(API 返回的 retry_timeout, 10 分钟)
+ * 2. 其他错误 → 最多重试 PART_FINISH_MAX_RETRIES 次（与之前逻辑一致）
+ * 
+ * 若持续重试超时或普通重试耗尽，抛出错误，调用方（chunkedUpload）
+ * 可据此中止后续分片上传。
+ * 
+ * @param retryTimeoutMs - 持续重试的超时时间（毫秒），由 upload_prepare 返回的 retry_timeout 计算得出
+ */
 async function partFinishWithRetry(
   accessToken: string,
   method: string,
   path: string,
   body?: unknown,
+  retryTimeoutMs?: number,
 ): Promise<void> {
   let lastError: Error | null = null;
 
@@ -433,6 +483,14 @@ async function partFinishWithRetry(
     } catch (err) {
       lastError = err instanceof Error ? err : new Error(String(err));
 
+      // 命中特定错误码 → 进入持续重试模式
+      if (isRetryableBizCode(err)) {
+        const timeoutMs = retryTimeoutMs ?? PART_FINISH_RETRYABLE_DEFAULT_TIMEOUT_MS;
+        console.warn(`[qqbot-api] PartFinish hit retryable bizCode=${(err as ApiError).bizCode}, entering persistent retry (timeout=${timeoutMs / 1000}s, interval=1s)...`);
+        await partFinishPersistentRetry(accessToken, method, path, body, timeoutMs);
+        return;
+      }
+
       if (attempt < PART_FINISH_MAX_RETRIES) {
         const delay = PART_FINISH_BASE_DELAY_MS * Math.pow(2, attempt);
         console.warn(`[qqbot-api] PartFinish attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 200)}`);
@@ -444,6 +502,51 @@ async function partFinishWithRetry(
   throw lastError!;
 }
 
+/**
+ * 特定错误码的持续重试模式
+ * 不限次数，仅受总超时时间约束，固定每 1 秒重试一次
+ */
+async function partFinishPersistentRetry(
+  accessToken: string,
+  method: string,
+  path: string,
+  body: unknown,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let attempt = 0;
+  let lastError: Error | null = null;
+
+  while (Date.now() < deadline) {
+    try {
+      await apiRequest<Record<string, unknown>>(accessToken, method, path, body);
+      console.log(`[qqbot-api] PartFinish persistent retry succeeded after ${attempt} retries`);
+      return;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      // 如果不再是可重试的错误码，直接抛出（可能是其他类型的错误）
+      if (!isRetryableBizCode(err)) {
+        console.error(`[qqbot-api] PartFinish persistent retry: error is no longer retryable (bizCode=${(err as ApiError).bizCode ?? "N/A"}), aborting`);
+        throw lastError;
+      }
+
+      attempt++;
+      const remaining = deadline - Date.now();
+
+      if (remaining <= 0) break;
+
+      const actualDelay = Math.min(PART_FINISH_RETRYABLE_INTERVAL_MS, remaining);
+      console.warn(`[qqbot-api] PartFinish persistent retry #${attempt}: bizCode=${(err as ApiError).bizCode}, retrying in ${actualDelay}ms (remaining=${Math.round(remaining / 1000)}s)`);
+      await new Promise(resolve => setTimeout(resolve, actualDelay));
+    }
+  }
+
+  // 超时
+  console.error(`[qqbot-api] PartFinish persistent retry timed out after ${timeoutMs / 1000}s (${attempt} attempts)`);
+  throw new Error(`upload_part_finish 持续重试超时（${timeoutMs / 1000}s, ${attempt} 次重试），中止上传`);
+}
+
 export async function getGatewayUrl(accessToken: string): Promise<string> {
   const data = await apiRequest<{ url: string }>(accessToken, "GET", "/gateway");
   return data.url;
@@ -644,6 +747,10 @@ export interface UploadPrepareResponse {
   block_size: number;
   /** 分片列表（含预签名链接） */
   parts: UploadPart[];
+  /** 上传并发数（由服务端控制，可选，不返回时使用客户端默认值） */
+  concurrency?: number;
+  /** upload_part_finish 特定错误码的重试超时时间（秒），由服务端控制，客户端上限 10 分钟 */
+  retry_timeout?: number;
 }
 
 /** 完成文件上传响应（与 UploadMediaResponse 一致） */
@@ -710,10 +817,12 @@ export async function c2cUploadPartFinish(
   partIndex: number,
   blockSize: number,
   md5: string,
+  retryTimeoutMs?: number,
 ): Promise<void> {
   await partFinishWithRetry(
     accessToken, "POST", `/v2/users/${userId}/upload_part_finish`,
     { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 },
+    retryTimeoutMs,
   );
 }
 
@@ -766,10 +875,12 @@ export async function groupUploadPartFinish(
   partIndex: number,
   blockSize: number,
   md5: string,
+  retryTimeoutMs?: number,
 ): Promise<void> {
   await partFinishWithRetry(
     accessToken, "POST", `/v2/groups/${groupId}/upload_part_finish`,
     { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 },
+    retryTimeoutMs,
   );
 }
 

package/src/outbound-deliver.ts

@@ -217,13 +217,13 @@ export async function sendPlainReply(
         });
         if (result.error) {
           log?.error(`${prefix} sendMedia(auto) error for ${mediaPath}: ${result.error}`);
-          await sendTextChunks(result.error, event, actx, sendWithRetry, consumeQuoteRef);
+          await sendTextChunks("发送失败，请稍后重试。", 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(`发送媒体失败：${err}`, event, actx, sendWithRetry, consumeQuoteRef);
+        await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
       }
     }
   }
@@ -245,12 +245,13 @@ export async function sendPlainReply(
           });
           if (result.error) {
             log?.error(`${prefix} Tool media forward error: ${result.error}`);
-            await sendTextChunks(result.error, event, actx, sendWithRetry, consumeQuoteRef);
+            await sendTextChunks("发送失败，请稍后重试。", 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);
         }
       }
     }

package/src/outbound.ts

@@ -20,7 +20,7 @@ import {
 } 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 } from "./utils/chunked-upload.js";
+import { chunkedUploadC2C, chunkedUploadGroup, UploadPrepareFallbackError } from "./utils/chunked-upload.js";
 import { isLocalPath as isLocalFilePath, normalizePath, getQQBotMediaDir } from "./utils/platform.js";
 import { downloadFile } from "./image-server.js";
 import { parseMediaTagsToSendQueue, executeSendQueue, type MediaSendContext } from "./utils/media-send.js";
@@ -533,6 +533,12 @@ async function chunkedUploadAndSend(
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`${prefix} ${callerName}: c2c chunked upload failed: ${msg}`);
+      if (err instanceof UploadPrepareFallbackError) {
+        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: `文件发送失败，请稍后重试。` };
     }
   }
@@ -556,6 +562,12 @@ async function chunkedUploadAndSend(
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`${prefix} ${callerName}: group chunked upload failed: ${msg}`);
+      if (err instanceof UploadPrepareFallbackError) {
+        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: `文件发送失败，请稍后重试。` };
     }
   }

package/src/utils/chunked-upload.ts

@@ -20,6 +20,8 @@ import {
   type UploadPrepareResponse,
   type UploadPrepareHashes,
   type MediaUploadResponse,
+  ApiError,
+  UPLOAD_PREPARE_FALLBACK_CODE,
   c2cUploadPrepare,
   c2cUploadPartFinish,
   c2cCompleteUpload,
@@ -30,8 +32,32 @@ import {
 } from "../api.js";
 import { formatFileSize } from "./file-utils.js";
 
-/** 分片上传并发控制：最多同时上传 N 个分片 */
-const MAX_CONCURRENT_PARTS = 1;
+/**
+ * upload_prepare 返回特定错误码时抛出的错误
+ * 调用方根据携带的文件信息构造兜底文案发送给用户
+ */
+export class UploadPrepareFallbackError extends Error {
+  /** 触发错误的本地文件路径 */
+  public readonly filePath: string;
+  /** 文件大小（字节） */
+  public readonly fileSize: number;
+
+  constructor(filePath: string, fileSize: number, originalMessage: string) {
+    super(originalMessage);
+    this.name = "UploadPrepareFallbackError";
+    this.filePath = filePath;
+    this.fileSize = fileSize;
+  }
+}
+
+/** 分片上传默认并发数（服务端未返回 concurrency 时的兜底） */
+const DEFAULT_CONCURRENT_PARTS = 1;
+
+/** 分片上传并发上限（即使服务端返回更大的值也不超过此限制） */
+const MAX_CONCURRENT_PARTS = 10;
+
+/** partFinish 特定错误码重试超时上限（10 分钟），即使服务端 retry_timeout 更大也不超过此值 */
+const MAX_PART_FINISH_RETRY_TIMEOUT_MS = 10 * 60 * 1000;
 
 /** 单个分片上传超时（毫秒）— 5 分钟，兼容低带宽场景 */
 const PART_UPLOAD_TIMEOUT = 300_000;
@@ -55,8 +81,6 @@ export interface ChunkedUploadProgress {
 export interface ChunkedUploadOptions {
   /** 进度回调 */
   onProgress?: (progress: ChunkedUploadProgress) => void;
-  /** 最大并发数（默认 2） */
-  maxConcurrent?: number;
   /** 日志前缀 */
   logPrefix?: string;
 }
@@ -81,7 +105,6 @@ export async function chunkedUploadC2C(
   options?: ChunkedUploadOptions,
 ): Promise<MediaUploadResponse> {
   const prefix = options?.logPrefix ?? "[chunked-upload]";
-  const maxConcurrent = options?.maxConcurrent ?? MAX_CONCURRENT_PARTS;
 
   // 1. 读取文件信息
   const stat = await fs.promises.stat(filePath);
@@ -98,13 +121,34 @@ export async function chunkedUploadC2C(
   // 3. 申请上传 → 获取 upload_id + block_size + 预签名链接
   const accessToken = await getAccessToken(appId, clientSecret);
   console.log(`${prefix} >>> Calling c2cUploadPrepare(fileType=${fileType}, fileName=${fileName}, fileSize=${fileSize}, md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m})`);
-  const prepareResp = await c2cUploadPrepare(accessToken, userId, fileType, fileName, fileSize, hashes);
+  let prepareResp: UploadPrepareResponse;
+  try {
+    prepareResp = await c2cUploadPrepare(accessToken, userId, fileType, fileName, fileSize, hashes);
+  } catch (err) {
+    // 命中特定错误码 → 携带文件信息抛出，由上层构造兜底文案
+    if (err instanceof ApiError && err.bizCode === UPLOAD_PREPARE_FALLBACK_CODE) {
+      console.warn(`${prefix} c2cUploadPrepare hit fallback code ${UPLOAD_PREPARE_FALLBACK_CODE}`);
+      throw new UploadPrepareFallbackError(filePath, fileSize, err.message);
+    }
+    throw err;
+  }
   console.log(`${prefix} <<< c2cUploadPrepare response:`, JSON.stringify(prepareResp));
   const { upload_id, parts } = prepareResp;
   // QQ 开放平台返回的 block_size 可能是字符串，需要转为数字
   const block_size = Number(prepareResp.block_size);
 
-  console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}`);
+  // 并发数：使用 API 返回的 concurrency，未返回则用默认值，且不超过上限
+  const maxConcurrent = Math.min(
+    prepareResp.concurrency ? Number(prepareResp.concurrency) : DEFAULT_CONCURRENT_PARTS,
+    MAX_CONCURRENT_PARTS,
+  );
+
+  // partFinish 特定错误码的重试超时：使用 API 返回的 retry_timeout（秒），上限 10 分钟
+  const retryTimeoutMs = prepareResp.retry_timeout
+    ? Math.min(Number(prepareResp.retry_timeout) * 1000, MAX_PART_FINISH_RETRY_TIMEOUT_MS)
+    : undefined;
+
+  console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}, concurrency=${maxConcurrent}, retryTimeout=${retryTimeoutMs ? retryTimeoutMs / 1000 + 's' : 'default'}`);
 
   // 4. 并行上传所有分片（带并发控制）
   let completedParts = 0;
@@ -131,7 +175,7 @@ export async function chunkedUploadC2C(
     // b. 通知开放平台分片上传完成（需要重新获取 token，避免长时间上传后 token 过期）
     const token = await getAccessToken(appId, clientSecret);
     console.log(`${prefix} >>> Calling c2cUploadPartFinish(upload_id=${upload_id}, partIndex=${partIndex}, blockSize=${length}, md5=${md5Hex})`);
-    await c2cUploadPartFinish(token, userId, upload_id, partIndex, length, md5Hex);
+    await c2cUploadPartFinish(token, userId, upload_id, partIndex, length, md5Hex, retryTimeoutMs);
     console.log(`${prefix} <<< c2cUploadPartFinish(partIndex=${partIndex}) done`);
 
     // 更新进度
@@ -188,7 +232,6 @@ export async function chunkedUploadGroup(
   options?: ChunkedUploadOptions,
 ): Promise<MediaUploadResponse> {
   const prefix = options?.logPrefix ?? "[chunked-upload]";
-  const maxConcurrent = options?.maxConcurrent ?? MAX_CONCURRENT_PARTS;
 
   // 1. 读取文件信息
   const stat = await fs.promises.stat(filePath);
@@ -205,13 +248,34 @@ export async function chunkedUploadGroup(
   // 3. 申请上传
   const accessToken = await getAccessToken(appId, clientSecret);
   console.log(`${prefix} >>> Calling groupUploadPrepare(fileType=${fileType}, fileName=${fileName}, fileSize=${fileSize}, md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m})`);
-  const prepareResp = await groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes);
+  let prepareResp: UploadPrepareResponse;
+  try {
+    prepareResp = await groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes);
+  } catch (err) {
+    // 命中特定错误码 → 携带文件信息抛出，由上层构造兜底文案
+    if (err instanceof ApiError && err.bizCode === UPLOAD_PREPARE_FALLBACK_CODE) {
+      console.warn(`${prefix} groupUploadPrepare hit fallback code ${UPLOAD_PREPARE_FALLBACK_CODE}`);
+      throw new UploadPrepareFallbackError(filePath, fileSize, err.message);
+    }
+    throw err;
+  }
   console.log(`${prefix} <<< groupUploadPrepare response:`, JSON.stringify(prepareResp));
   const { upload_id, parts } = prepareResp;
   // QQ 开放平台返回的 block_size 可能是字符串，需要转为数字
   const block_size = Number(prepareResp.block_size);
 
-  console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}`);
+  // 并发数：使用 API 返回的 concurrency，未返回则用默认值，且不超过上限
+  const maxConcurrent = Math.min(
+    prepareResp.concurrency ? Number(prepareResp.concurrency) : DEFAULT_CONCURRENT_PARTS,
+    MAX_CONCURRENT_PARTS,
+  );
+
+  // partFinish 特定错误码的重试超时：使用 API 返回的 retry_timeout（秒），上限 10 分钟
+  const retryTimeoutMs = prepareResp.retry_timeout
+    ? Math.min(Number(prepareResp.retry_timeout) * 1000, MAX_PART_FINISH_RETRY_TIMEOUT_MS)
+    : undefined;
+
+  console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}, concurrency=${maxConcurrent}, retryTimeout=${retryTimeoutMs ? retryTimeoutMs / 1000 + 's' : 'default'}`);
 
   // 4. 并行上传所有分片（带并发控制）
   let completedParts = 0;
@@ -232,7 +296,7 @@ export async function chunkedUploadGroup(
 
     const token = await getAccessToken(appId, clientSecret);
     console.log(`${prefix} >>> Calling groupUploadPartFinish(upload_id=${upload_id}, partIndex=${partIndex}, blockSize=${length}, md5=${md5Hex})`);
-    await groupUploadPartFinish(token, groupId, upload_id, partIndex, length, md5Hex);
+    await groupUploadPartFinish(token, groupId, upload_id, partIndex, length, md5Hex, retryTimeoutMs);
     console.log(`${prefix} <<< groupUploadPartFinish(partIndex=${partIndex}) done`);
 
     completedParts++;

package/src/utils/media-send.ts

@@ -335,6 +335,7 @@ export function parseMediaTagsToSendQueue(
  *
  * 遍历 sendQueue，按类型调用对应的发送函数。
  * 文本项通过 onSendText 回调处理（不同场景的文本发送方式不同）。
+ * 媒体发送失败时，通过 onSendText 发送兜底文本通知用户。
  */
 export async function executeSendQueue(
   queue: SendQueueItem[],
@@ -349,7 +350,21 @@ export async function executeSendQueue(
   const { mediaTarget, qualifiedTarget, account, replyToId, log } = ctx;
   const prefix = mediaTarget.logPrefix ?? `[qqbot:${account.accountId}]`;
 
+  /** 媒体发送失败时的兜底：通过 onSendText 发送错误文本给用户 */
+  const sendFallbackText = async (errorMsg: string): Promise<void> => {
+    if (!options.onSendText) {
+      log?.info(`${prefix} executeSendQueue: no onSendText handler, cannot send fallback text`);
+      return;
+    }
+    try {
+      await options.onSendText(errorMsg);
+    } catch (fallbackErr) {
+      log?.error(`${prefix} executeSendQueue: fallback text send failed: ${fallbackErr}`);
+    }
+  };
+
   for (const item of queue) {
+    const FALLBACK_MSG = "发送失败，请稍后重试。";
     try {
       if (item.type === "text") {
         if (options.skipInterTagText) {
@@ -370,6 +385,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);
         }
       } else if (item.type === "voice") {
         const uploadFormats =
@@ -390,19 +406,23 @@ export async function executeSendQueue(
           ]);
           if (result.error) {
             log?.error(`${prefix} sendVoice error: ${result.error}`);
+            await sendFallbackText(FALLBACK_MSG);
           }
         } catch (err) {
           log?.error(`${prefix} sendVoice unexpected error: ${err}`);
+          await sendFallbackText(FALLBACK_MSG);
         }
       } 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);
         }
       } 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);
         }
       } else if (item.type === "media") {
         const result = await sendMediaAuto({
@@ -415,10 +435,12 @@ export async function executeSendQueue(
         });
         if (result.error) {
           log?.error(`${prefix} sendMedia(auto) error: ${result.error}`);
+          await sendFallbackText(FALLBACK_MSG);
         }
       }
     } catch (err) {
       log?.error(`${prefix} executeSendQueue: failed to send ${item.type}: ${err}`);
+      await sendFallbackText(FALLBACK_MSG);
     }
   }
 }