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

package/dist/src/api.d.ts

@@ -2,6 +2,20 @@
  * QQ Bot API 鉴权和请求封装
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
+/** API 请求错误，携带 HTTP status code 和业务错误码 */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly 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;
 /** 出站消息元信息（结构化存储，不做预格式化） */
 export interface OutboundMeta {
@@ -25,7 +39,6 @@ type OnMessageSentCallback = (refIdx: string, meta: OutboundMeta) => void;
 export declare function onMessageSent(callback: OnMessageSentCallback): void;
 /**
  * 初始化 API 配置
- * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
  */
 export declare function initApiConfig(options: {
     markdownSupport?: boolean;
@@ -64,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;
@@ -108,6 +131,94 @@ export interface UploadMediaResponse {
     ttl: number;
     id?: string;
 }
+/** 分片信息 */
+export interface UploadPart {
+    /** 分片索引（从 1 开始） */
+    index: number;
+    /** 预签名上传链接 */
+    presigned_url: string;
+}
+/** 申请上传响应 */
+export interface UploadPrepareResponse {
+    /** 上传任务 ID */
+    upload_id: string;
+    /** 分块大小（字节） */
+    block_size: number;
+    /** 分片列表（含预签名链接） */
+    parts: UploadPart[];
+    /** 上传并发数（由服务端控制，可选，不返回时使用客户端默认值） */
+    concurrency?: number;
+    /** upload_part_finish 特定错误码的重试超时时间（秒），由服务端控制，客户端上限 10 分钟 */
+    retry_timeout?: number;
+}
+/** 完成文件上传响应（与 UploadMediaResponse 一致） */
+export interface MediaUploadResponse {
+    /** 文件 UUID */
+    file_uuid: string;
+    /** 文件信息（用于发送消息），是 InnerUploadRsp 的序列化 */
+    file_info: string;
+    /** 文件信息过期时长（秒） */
+    ttl: number;
+}
+/** 申请上传时的文件哈希信息 */
+export interface UploadPrepareHashes {
+    /** 整个文件的 MD5（十六进制） */
+    md5: string;
+    /** 整个文件的 SHA1（十六进制） */
+    sha1: string;
+    /** 文件前 10002432 Bytes 的 MD5（十六进制）；文件不足该大小时为整文件 MD5 */
+    md5_10m: string;
+}
+/**
+ * 申请上传（C2C）
+ * POST /v2/users/{user_id}/upload_prepare
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param fileType - 业务类型（1=图片, 2=视频, 3=语音, 4=文件）
+ * @param fileName - 文件名
+ * @param fileSize - 文件大小（字节）
+ * @param hashes - 文件哈希信息（md5, sha1, md5_10m）
+ * @returns 上传任务 ID、分块大小、分片预签名链接列表
+ */
+export declare function c2cUploadPrepare(accessToken: string, userId: string, fileType: MediaFileType, fileName: string, fileSize: number, hashes: UploadPrepareHashes): Promise<UploadPrepareResponse>;
+/**
+ * 完成分片上传（C2C）
+ * POST /v2/users/{user_id}/upload_part_finish
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param uploadId - 上传任务 ID
+ * @param partIndex - 分片索引（从 1 开始）
+ * @param blockSize - 分块大小（字节）
+ * @param md5 - 分片数据的 MD5（十六进制）
+ */
+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
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param uploadId - 上传任务 ID
+ * @returns 文件信息（file_uuid, file_info, ttl）
+ */
+export declare function c2cCompleteUpload(accessToken: string, userId: string, uploadId: string): Promise<MediaUploadResponse>;
+/**
+ * 申请上传（Group）
+ * POST /v2/groups/{group_id}/upload_prepare
+ */
+export declare function groupUploadPrepare(accessToken: string, groupId: string, fileType: MediaFileType, fileName: string, fileSize: number, hashes: UploadPrepareHashes): Promise<UploadPrepareResponse>;
+/**
+ * 完成分片上传（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, retryTimeoutMs?: number): Promise<void>;
+/**
+ * 完成文件上传（Group）
+ * POST /v2/groups/{group_id}/files
+ */
+export declare function groupCompleteUpload(accessToken: string, groupId: string, uploadId: string): Promise<MediaUploadResponse>;
 export declare function uploadC2CMedia(accessToken: string, openid: string, fileType: MediaFileType, url?: string, fileData?: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
 export declare function uploadGroupMedia(accessToken: string, groupOpenid: string, fileType: MediaFileType, url?: string, fileData?: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
 export declare function sendC2CMediaMessage(accessToken: string, openid: string, fileInfo: string, msgId?: string, content?: string, meta?: OutboundMeta): Promise<MessageResponse>;
@@ -153,4 +264,19 @@ export declare function startBackgroundTokenRefresh(appId: string, clientSecret:
  */
 export declare function stopBackgroundTokenRefresh(appId?: string): void;
 export declare function isBackgroundTokenRefreshRunning(appId?: string): boolean;
+import type { StreamMessageRequest, StreamMessageResponse } from "./types.js";
+/**
+ * 发送流式消息（C2C 私聊）
+ *
+ * 流式协议：
+ * - 首次调用时不传 stream_msg_id，由平台返回
+ * - 后续分片携带 stream_msg_id 和递增 msg_seq
+ * - input_state="1" 表示生成中，"10" 表示生成结束（终结状态）
+ *
+ * @param accessToken - access_token
+ * @param openid - 用户 openid
+ * @param req - 流式消息请求体
+ * @returns 流式消息响应
+ */
+export declare function sendC2CStreamMessage(accessToken: string, openid: string, req: StreamMessageRequest): Promise<StreamMessageResponse>;
 export {};

package/dist/src/api.js

@@ -5,6 +5,26 @@
 import os from "node:os";
 import { computeFileHash, getCachedFileInfo, setCachedFileInfo } from "./utils/upload-cache.js";
 import { sanitizeFileName } from "./utils/platform.js";
+// ============ 自定义错误 ============
+/** API 请求错误，携带 HTTP status code 和业务错误码 */
+export class ApiError extends Error {
+    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";
+    }
+}
 const API_BASE = "https://api.sgroup.qq.com";
 const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
 // ============ Plugin User-Agent ============
@@ -26,7 +46,6 @@ export function onMessageSent(callback) {
 }
 /**
  * 初始化 API 配置
- * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
  */
 export function initApiConfig(options) {
     currentMarkdownSupport = options.markdownSupport === true;
@@ -248,17 +267,18 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
                 : res.status === 429
                     ? "请求过于频繁，已被限流"
                     : `开放平台返回 HTTP ${res.status}`;
-            throw new Error(`${statusHint}（${path}），请稍后重试`);
+            throw new ApiError(`${statusHint}（${path}），请稍后重试`, res.status, path);
         }
         // JSON 错误响应
         try {
             const error = JSON.parse(rawBody);
-            throw new Error(`API Error [${path}]: ${error.message ?? rawBody}`);
+            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 Error && parseErr.message.startsWith("API Error"))
+            if (parseErr instanceof ApiError)
                 throw parseErr;
-            throw new Error(`API Error [${path}] HTTP ${res.status}: ${rawBody.slice(0, 200)}`);
+            throw new ApiError(`API Error [${path}] HTTP ${res.status}: ${rawBody.slice(0, 200)}`, res.status, path);
         }
     }
     // 成功响应但不是 JSON（极端异常情况）
@@ -297,6 +317,132 @@ async function apiRequestWithRetry(accessToken, method, path, body, maxRetries =
     }
     throw lastError;
 }
+// ============ 完成上传重试（无条件，任何错误都重试） ============
+const COMPLETE_UPLOAD_MAX_RETRIES = 2;
+const COMPLETE_UPLOAD_BASE_DELAY_MS = 2000;
+/**
+ * 完成上传专用重试：无条件重试所有错误（包括 4xx、5xx、网络错误、超时等）
+ * 分片上传完成接口的失败往往是平台侧异步处理未就绪，重试通常能成功
+ */
+async function completeUploadWithRetry(accessToken, method, path, body) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= COMPLETE_UPLOAD_MAX_RETRIES; attempt++) {
+        try {
+            return await apiRequest(accessToken, method, path, body);
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < COMPLETE_UPLOAD_MAX_RETRIES) {
+                const delay = COMPLETE_UPLOAD_BASE_DELAY_MS * Math.pow(2, attempt);
+                console.warn(`[qqbot-api] CompleteUpload attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 200)}`);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+    }
+    throw lastError;
+}
+// ============ 分片完成重试 ============
+/** 普通错误最大重试次数 */
+const PART_FINISH_MAX_RETRIES = 2;
+const PART_FINISH_BASE_DELAY_MS = 1000;
+/**
+ * 需要持续重试的业务错误码集合
+ * 当 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 {
+            await apiRequest(accessToken, method, path, body);
+            return;
+        }
+        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)}`);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+    }
+    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;
@@ -405,6 +551,68 @@ export var MediaFileType;
     MediaFileType[MediaFileType["VOICE"] = 3] = "VOICE";
     MediaFileType[MediaFileType["FILE"] = 4] = "FILE";
 })(MediaFileType || (MediaFileType = {}));
+/**
+ * 申请上传（C2C）
+ * POST /v2/users/{user_id}/upload_prepare
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param fileType - 业务类型（1=图片, 2=视频, 3=语音, 4=文件）
+ * @param fileName - 文件名
+ * @param fileSize - 文件大小（字节）
+ * @param hashes - 文件哈希信息（md5, sha1, md5_10m）
+ * @returns 上传任务 ID、分块大小、分片预签名链接列表
+ */
+export async function c2cUploadPrepare(accessToken, userId, fileType, fileName, fileSize, hashes) {
+    return apiRequest(accessToken, "POST", `/v2/users/${userId}/upload_prepare`, { file_type: fileType, file_name: fileName, file_size: fileSize, md5: hashes.md5, sha1: hashes.sha1, md5_10m: hashes.md5_10m });
+}
+/**
+ * 完成分片上传（C2C）
+ * POST /v2/users/{user_id}/upload_part_finish
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param uploadId - 上传任务 ID
+ * @param partIndex - 分片索引（从 1 开始）
+ * @param blockSize - 分块大小（字节）
+ * @param md5 - 分片数据的 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）
+ * POST /v2/users/{user_id}/files
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param uploadId - 上传任务 ID
+ * @returns 文件信息（file_uuid, file_info, ttl）
+ */
+export async function c2cCompleteUpload(accessToken, userId, uploadId) {
+    return completeUploadWithRetry(accessToken, "POST", `/v2/users/${userId}/files`, { upload_id: uploadId });
+}
+/**
+ * 申请上传（Group）
+ * POST /v2/groups/{group_id}/upload_prepare
+ */
+export async function groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes) {
+    return apiRequest(accessToken, "POST", `/v2/groups/${groupId}/upload_prepare`, { file_type: fileType, file_name: fileName, file_size: fileSize, md5: hashes.md5, sha1: hashes.sha1, md5_10m: hashes.md5_10m });
+}
+/**
+ * 完成分片上传（Group）
+ * POST /v2/groups/{group_id}/upload_part_finish
+ */
+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）
+ * POST /v2/groups/{group_id}/files
+ */
+export async function groupCompleteUpload(accessToken, groupId, uploadId) {
+    return completeUploadWithRetry(accessToken, "POST", `/v2/groups/${groupId}/files`, { upload_id: uploadId });
+}
 export async function uploadC2CMedia(accessToken, openid, fileType, url, fileData, srvSendMsg = false, fileName) {
     if (!url && !fileData)
         throw new Error("uploadC2CMedia: url or fileData is required");
@@ -619,3 +827,33 @@ async function sleep(ms, signal) {
         }
     });
 }
+/**
+ * 发送流式消息（C2C 私聊）
+ *
+ * 流式协议：
+ * - 首次调用时不传 stream_msg_id，由平台返回
+ * - 后续分片携带 stream_msg_id 和递增 msg_seq
+ * - input_state="1" 表示生成中，"10" 表示生成结束（终结状态）
+ *
+ * @param accessToken - access_token
+ * @param openid - 用户 openid
+ * @param req - 流式消息请求体
+ * @returns 流式消息响应
+ */
+export async function sendC2CStreamMessage(accessToken, openid, req) {
+    const path = `/v2/users/${openid}/stream_messages`;
+    const body = {
+        input_mode: req.input_mode,
+        input_state: req.input_state,
+        content_type: req.content_type,
+        content_raw: req.content_raw,
+        event_id: req.event_id,
+        msg_id: req.msg_id,
+        msg_seq: req.msg_seq,
+        index: req.index,
+    };
+    if (req.stream_msg_id) {
+        body.stream_msg_id = req.stream_msg_id;
+    }
+    return apiRequest(accessToken, "POST", path, body);
+}

package/dist/src/channel.d.ts

@@ -1,4 +1,4 @@
-import { type ChannelPlugin } from "openclaw/plugin-sdk";
+import { type ChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { ResolvedQQBotAccount } from "./types.js";
 /** QQ Bot 单条消息文本长度上限 */
 export declare const TEXT_CHUNK_LIMIT = 5000;

package/dist/src/channel.js

@@ -1,4 +1,4 @@
-import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk";
+import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk/core";
 import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId } from "./config.js";
 import { sendText, sendMedia } from "./outbound.js";
 import { startGateway } from "./gateway.js";
@@ -40,6 +40,7 @@ export const qqbotPlugin = {
     },
     reload: { configPrefixes: ["channels.qqbot"] },
     // CLI onboarding wizard
+    // @ts-expect-error onboarding removed from ChannelPlugin type in 2026.3.23 but still supported at runtime
     onboarding: qqbotOnboardingAdapter,
     config: {
         listAccountIds: (cfg) => listQQBotAccountIds(cfg),
@@ -76,7 +77,7 @@ export const qqbotPlugin = {
         }),
         // 关键：解析 allowFrom 配置，用于命令授权
         resolveAllowFrom: ({ cfg, accountId }) => {
-            const account = resolveQQBotAccount(cfg, accountId);
+            const account = resolveQQBotAccount(cfg, accountId ?? undefined);
             const allowFrom = account.config?.allowFrom ?? [];
             console.log(`[qqbot] resolveAllowFrom: accountId=${accountId}, allowFrom=${JSON.stringify(allowFrom)}`);
             return allowFrom.map((entry) => String(entry));
@@ -201,28 +202,42 @@ export const qqbotPlugin = {
         sendText: async ({ to, text, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
             console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);
-            const account = resolveQQBotAccount(cfg, accountId);
+            const account = resolveQQBotAccount(cfg, accountId ?? undefined);
             initApiConfig({ markdownSupport: account.markdownSupport });
             console.log(`[qqbot:channel] sendText resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
             const result = await sendText({ to, text, accountId, replyToId, account });
             console.log(`[qqbot:channel] sendText result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
+            if (result.error)
+                throw new Error(result.error);
             return {
                 channel: "qqbot",
-                messageId: result.messageId,
-                error: result.error ? new Error(result.error) : undefined,
+                messageId: result.messageId ?? "",
             };
         },
         sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendMedia called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, mediaUrl=${mediaUrl?.slice(0, 80)}, text.length=${text?.length ?? 0}`);
-            const account = resolveQQBotAccount(cfg, accountId);
+            const account = resolveQQBotAccount(cfg, accountId ?? undefined);
             initApiConfig({ markdownSupport: account.markdownSupport });
             console.log(`[qqbot:channel] sendMedia resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
             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 后不一定会给用户发文字兜底，所以这里主动发一条。
+            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);
+            }
             return {
                 channel: "qqbot",
-                messageId: result.messageId,
-                error: result.error ? new Error(result.error) : undefined,
+                messageId: result.messageId ?? "",
             };
         },
     },
@@ -343,8 +358,8 @@ export const qqbotPlugin = {
             enabled: account?.enabled ?? false,
             configured: Boolean(account?.appId && account?.clientSecret),
             tokenSource: account?.secretSource,
-            running: runtime?.running ?? false,
-            connected: runtime?.connected ?? false,
+            running: Boolean(runtime?.running ?? false),
+            connected: Boolean(runtime?.connected ?? false),
             lastConnectedAt: runtime?.lastConnectedAt ?? null,
             lastError: runtime?.lastError ?? null,
             lastInboundAt: runtime?.lastInboundAt ?? null,

package/dist/src/config.js

@@ -52,17 +52,10 @@ export function resolveQQBotAccount(cfg, accountId) {
     let clientSecret = "";
     let secretSource = "none";
     if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
-        // 默认账户从顶层读取
+        // 默认账户从顶层读取（展开所有字段，避免遗漏新增配置项）
+        const { accounts: _accounts, ...topLevelConfig } = qqbot ?? {};
         accountConfig = {
-            enabled: qqbot?.enabled,
-            name: qqbot?.name,
-            appId: qqbot?.appId,
-            clientSecret: qqbot?.clientSecret,
-            clientSecretFile: qqbot?.clientSecretFile,
-            dmPolicy: qqbot?.dmPolicy,
-            allowFrom: qqbot?.allowFrom,
-            systemPrompt: qqbot?.systemPrompt,
-            imageServerBaseUrl: qqbot?.imageServerBaseUrl,
+            ...topLevelConfig,
             markdownSupport: qqbot?.markdownSupport ?? true,
         };
         appId = normalizeAppId(qqbot?.appId);