@tencent-connect/openclaw-qqbot 1.6.7 → 1.7.0-alpha.0

package/dist/src/gateway.js

@@ -1,14 +1,15 @@
 import WebSocket from "ws";
 import path from "node:path";
 import fs from "node:fs";
-import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, PLUGIN_USER_AGENT, acknowledgeInteraction, getApiPluginVersion } from "./api.js";
+import { MSG_TYPE_QUOTE } from "./types.js";
+import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, getPluginUserAgent, acknowledgeInteraction, getApiPluginVersion, setApiLogger } from "./api.js";
 import { loadSession, saveSession, clearSession } from "./session-store.js";
 import { recordKnownUser, flushKnownUsers } from "./known-users.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { isGroupAllowed, resolveGroupName, resolveGroupPrompt, resolveHistoryLimit, resolveGroupPolicy, resolveGroupConfig, resolveIgnoreOtherMentions, resolveMentionPatterns } from "./config.js";
 import { qqbotPlugin, stripMentionText, detectWasMentioned } from "./channel.js";
 import { recordPendingHistoryEntry, buildPendingHistoryContext, buildMergedMessageContext, clearPendingHistory, formatAttachmentTags, formatMessageContent, toAttachmentSummaries, } from "./group-history.js";
-import { setRefIndex, getRefIndex, formatRefEntryForAgent, flushRefIndex } from "./ref-index-store.js";
+import { setRefIndex, getRefIndex, formatRefEntryForAgent, formatMessageReferenceForAgent, flushRefIndex } from "./ref-index-store.js";
 import { matchSlashCommand, getFrameworkVersion, parseFrameworkDateVersion } from "./slash-commands.js";
 import { createMessageQueue } from "./message-queue.js";
 import { triggerUpdateCheck } from "./update-checker.js";
@@ -338,6 +339,10 @@ export async function startGateway(ctx) {
     // 后台版本检查（供 /bot-version、/bot-upgrade 指令被动查询）
     triggerUpdateCheck(log);
     // 初始化 API 配置（markdown 支持）
+    // 将框架 log 注入 api 模块，统一日志输出
+    if (log) {
+        setApiLogger(log);
+    }
     initApiConfig({
         markdownSupport: account.markdownSupport,
     });
@@ -586,7 +591,7 @@ export async function startGateway(ctx) {
             log?.info(`[qqbot:${account.accountId}] ✅ Access token obtained successfully`);
             const gatewayUrl = await getGatewayUrl(accessToken);
             log?.info(`[qqbot:${account.accountId}] Connecting to ${gatewayUrl}`);
-            const ws = new WebSocket(gatewayUrl, { headers: { "User-Agent": PLUGIN_USER_AGENT } });
+            const ws = new WebSocket(gatewayUrl, { headers: { "User-Agent": getPluginUserAgent() } });
             currentWs = ws;
             const pluginRuntime = getQQBotRuntime();
             // 群历史消息缓存：非@消息写入此 Map，被@时一次性注入上下文后清空
@@ -679,26 +684,50 @@ export async function startGateway(ctx) {
                 let userContent = voiceText
                     ? (parsedContent.trim() ? `${parsedContent}\n${voiceText}` : voiceText) + attachmentInfo
                     : parsedContent + attachmentInfo;
+                // 统一处理 <@member_openid> → @username / 移除 @bot mention
+                if (event.type === "group" && event.mentions?.length) {
+                    userContent = stripMentionText(userContent, event.mentions) ?? userContent;
+                }
+                else if (event.mentions?.length) {
+                    for (const m of event.mentions) {
+                        if (m.member_openid && m.username) {
+                            userContent = userContent.replace(new RegExp(`<@${m.member_openid}>`, "g"), `@${m.username}`);
+                        }
+                    }
+                }
                 // ============ 引用消息处理 ============
                 let replyToId;
                 let replyToBody;
                 let replyToSender;
                 let replyToIsQuote = false;
-                // 1. 查找被引用消息
+                // 引用消息处理：优先使用本地 refIndex 缓存（同步、已处理），缓存未命中时从 msg_elements[0] 获取
+                // refMsgIdx 已由 parseRefIndices 在引用消息类型时合并了 msg_elements[0].msg_idx 的优先级
                 if (event.refMsgIdx) {
                     const refEntry = getRefIndex(event.refMsgIdx);
+                    replyToId = event.refMsgIdx;
+                    replyToIsQuote = true;
                     if (refEntry) {
-                        replyToId = event.refMsgIdx;
+                        // 缓存命中：直接使用已处理好的内容（同步，无需再下载附件）
                         replyToBody = formatRefEntryForAgent(refEntry);
                         replyToSender = refEntry.senderName ?? refEntry.senderId;
-                        replyToIsQuote = true;
-                        log?.info(`[qqbot:${account.accountId}] Quote detected: refMsgIdx=${event.refMsgIdx}, sender=${replyToSender}, content="${replyToBody.slice(0, 80)}..."`);
+                        log?.info(`[qqbot:${account.accountId}] Quote detected via refMsgIdx cache: refMsgIdx=${event.refMsgIdx}, sender=${replyToSender}, content="${replyToBody.slice(0, 80)}..."`);
+                    }
+                    else if (event.msgType === MSG_TYPE_QUOTE) {
+                        // 缓存未命中且为引用消息类型，从 msg_elements[0] 获取被引用消息内容
+                        const refElement = event.msgElements?.[0];
+                        if (refElement) {
+                            const refData = { content: refElement.content ?? "", attachments: refElement.attachments };
+                            replyToBody = await formatMessageReferenceForAgent(refData, { appId: account.appId, peerId, cfg, log });
+                            log?.info(`[qqbot:${account.accountId}] Quote detected via msg_elements[0] (cache miss): id=${replyToId}, sender=${replyToSender ?? "unknown"}, content="${(replyToBody ?? "").slice(0, 80)}..."`);
+                        }
+                        else {
+                            // 引用消息但 msg_elements 为空：AI 只能知道"用户引用了一条消息"
+                            log?.info(`[qqbot:${account.accountId}] Quote detected (MSG_TYPE_QUOTE) but no msg_elements: refMsgIdx=${event.refMsgIdx}`);
+                        }
                     }
                     else {
-                        log?.info(`[qqbot:${account.accountId}] Quote detected but refMsgIdx not in cache: ${event.refMsgIdx}`);
-                        replyToId = event.refMsgIdx;
-                        replyToIsQuote = true;
-                        // 缓存未命中时 replyToBody 为空，AI 只能知道"用户引用了一条消息"
+                        // 缓存未命中且非引用消息类型：AI 只能知道"用户引用了一条消息"
+                        log?.info(`[qqbot:${account.accountId}] Quote detected but no cache and msgType=${event.msgType} (not quote): refMsgIdx=${event.refMsgIdx}`);
                     }
                 }
                 // 2. 缓存当前消息自身的 msgIdx（供将来被引用时查找）
@@ -880,7 +909,7 @@ export async function startGateway(ctx) {
                             limit: historyLimit,
                             entry: {
                                 sender: senderForHistory,
-                                body: parseFaceTags(event.content),
+                                body: userContent,
                                 timestamp: new Date(event.timestamp).getTime(),
                                 messageId: event.messageId,
                                 attachments: historyAttachments,
@@ -907,7 +936,7 @@ export async function startGateway(ctx) {
                             limit: historyLimit,
                             entry: {
                                 sender: senderForHistory,
-                                body: parseFaceTags(event.content),
+                                body: userContent,
                                 timestamp: new Date(event.timestamp).getTime(),
                                 messageId: event.messageId,
                                 attachments: historyAttachments,
@@ -938,17 +967,6 @@ export async function startGateway(ctx) {
                     groupSystemPrompt = [baseHint, behaviorPrompt].filter(Boolean).join("\n");
                 }
                 const mergedCount = event._mergedCount;
-                // 将 <@member_openid> 替换为 @username（使用 mentions 适配器）
-                if (event.type === "group" && event.mentions?.length) {
-                    userContent = stripMentionText(userContent, event.mentions) ?? userContent;
-                }
-                else if (event.mentions?.length) {
-                    for (const m of event.mentions) {
-                        if (m.member_openid && m.username) {
-                            userContent = userContent.replace(new RegExp(`<@${m.member_openid}>`, "g"), `@${m.username}`);
-                        }
-                    }
-                }
                 // 群消息 user prompt 带上发送者昵称（合并消息已内嵌发送者前缀，不再重复添加）
                 const isMergedMsg = mergedCount && mergedCount > 1;
                 const senderPrefix = (event.type === "group" && !isMergedMsg)
@@ -1204,9 +1222,9 @@ export async function startGateway(ctx) {
                         const useStreaming = shouldUseStreaming(account, targetType);
                         log?.info(`[qqbot:${account.accountId}] Streaming ${useStreaming ? "enabled" : "disabled"} for ${targetType} message from ${event.senderId}`);
                         let streamingController = null;
-                        /** 创建一个新的 StreamingController 实例（用于初始创建和回复边界时重建） */
-                        const createStreamingController = () => {
-                            const ctrl = new StreamingController({
+                        if (useStreaming) {
+                            log?.info(`[qqbot:${account.accountId}] Streaming mode enabled for ${targetType} target`);
+                            streamingController = new StreamingController({
                                 account,
                                 userId: event.senderId,
                                 replyToMsgId: event.messageId,
@@ -1224,20 +1242,7 @@ export async function startGateway(ctx) {
                                     },
                                     log,
                                 },
-                                // 回复边界回调：终结旧 controller 后创建新的，用新回复文本继续流式
-                                onReplyBoundary: async (newReplyText) => {
-                                    log?.info(`[qqbot:${account.accountId}] Reply boundary: creating new StreamingController for new reply`);
-                                    const newCtrl = createStreamingController();
-                                    streamingController = newCtrl;
-                                    // 将新回复的初始文本交给新 controller 处理
-                                    await newCtrl.onPartialReply({ text: newReplyText });
-                                },
                             });
-                            return ctrl;
-                        };
-                        if (useStreaming) {
-                            log?.info(`[qqbot:${account.accountId}] Streaming mode enabled for ${targetType} target`);
-                            streamingController = createStreamingController();
                         }
                         const dispatchPromise = pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
                             ctx: ctxPayload,
@@ -1517,9 +1522,7 @@ export async function startGateway(ctx) {
                             if (timeoutId) {
                                 clearTimeout(timeoutId);
                             }
-                            if (!hasResponse) {
-                                log?.error(`[qqbot:${account.accountId}] No response within timeout`);
-                            }
+                            log?.error(`[qqbot:${account.accountId}] Dispatch failed: ${err}${!hasResponse ? " (no response received)" : ""}`);
                         }
                         finally {
                             // 清理 tool-only 兜底定时器
@@ -1718,7 +1721,7 @@ export async function startGateway(ctx) {
                                     accountId: account.accountId,
                                 });
                                 // 解析引用索引
-                                const c2cRefs = parseRefIndices(event.message_scene?.ext);
+                                const c2cRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
                                 // 斜杠指令拦截 → 不匹配则入队
                                 trySlashCommandOrEnqueue({
                                     type: "c2c",
@@ -1729,6 +1732,8 @@ export async function startGateway(ctx) {
                                     attachments: event.attachments,
                                     refMsgIdx: c2cRefs.refMsgIdx,
                                     msgIdx: c2cRefs.msgIdx,
+                                    msgElements: event.msg_elements,
+                                    msgType: event.message_type,
                                 });
                             }
                             else if (t === "AT_MESSAGE_CREATE") {
@@ -1740,7 +1745,7 @@ export async function startGateway(ctx) {
                                     nickname: event.author.username,
                                     accountId: account.accountId,
                                 });
-                                const guildRefs = parseRefIndices(event.message_scene?.ext);
+                                const guildRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
                                 trySlashCommandOrEnqueue({
                                     type: "guild",
                                     senderId: event.author.id,
@@ -1753,6 +1758,7 @@ export async function startGateway(ctx) {
                                     attachments: event.attachments,
                                     refMsgIdx: guildRefs.refMsgIdx,
                                     msgIdx: guildRefs.msgIdx,
+                                    msgType: event.message_type,
                                 });
                             }
                             else if (t === "DIRECT_MESSAGE_CREATE") {
@@ -1764,7 +1770,7 @@ export async function startGateway(ctx) {
                                     nickname: event.author.username,
                                     accountId: account.accountId,
                                 });
-                                const dmRefs = parseRefIndices(event.message_scene?.ext);
+                                const dmRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
                                 trySlashCommandOrEnqueue({
                                     type: "dm",
                                     senderId: event.author.id,
@@ -1776,6 +1782,7 @@ export async function startGateway(ctx) {
                                     attachments: event.attachments,
                                     refMsgIdx: dmRefs.refMsgIdx,
                                     msgIdx: dmRefs.msgIdx,
+                                    msgType: event.message_type,
                                 });
                             }
                             else if (t === "GROUP_AT_MESSAGE_CREATE") {
@@ -1788,7 +1795,7 @@ export async function startGateway(ctx) {
                                     groupOpenid: event.group_openid,
                                     accountId: account.accountId,
                                 });
-                                const groupRefs = parseRefIndices(event.message_scene?.ext);
+                                const groupRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
                                 trySlashCommandOrEnqueue({
                                     type: "group",
                                     senderId: event.author.member_openid,
@@ -1803,6 +1810,8 @@ export async function startGateway(ctx) {
                                     eventType: "GROUP_AT_MESSAGE_CREATE",
                                     mentions: event.mentions,
                                     messageScene: event.message_scene,
+                                    msgElements: event.msg_elements,
+                                    msgType: event.message_type,
                                 });
                             }
                             else if (t === "GROUP_MESSAGE_CREATE") {
@@ -1814,7 +1823,7 @@ export async function startGateway(ctx) {
                                     groupOpenid: event.group_openid,
                                     accountId: account.accountId,
                                 });
-                                const groupRefs = parseRefIndices(event.message_scene?.ext);
+                                const groupRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
                                 trySlashCommandOrEnqueue({
                                     type: "group",
                                     senderId: event.author.member_openid,
@@ -1830,6 +1839,8 @@ export async function startGateway(ctx) {
                                     eventType: "GROUP_MESSAGE_CREATE",
                                     mentions: event.mentions,
                                     messageScene: event.message_scene,
+                                    msgElements: event.msg_elements,
+                                    msgType: event.message_type,
                                 });
                             }
                             else if (t === "GROUP_ADD_ROBOT") {

package/dist/src/message-queue.d.ts

@@ -1,4 +1,5 @@
 import type { QueueSnapshot } from "./slash-commands.js";
+import type { MsgElement } from "./types.js";
 /**
  * 消息队列项类型（用于异步处理消息，防止阻塞心跳）
  */
@@ -42,6 +43,10 @@ export interface QueuedMessage {
         source?: string;
         ext?: string[];
     };
+    /** 消息元素列表，引用消息时 [0] 为被引用的原始消息 */
+    msgElements?: MsgElement[];
+    /** 消息类型，参见 MSG_TYPE_* */
+    msgType?: number;
     /** 群消息合并标记：记录合并了多少条原始消息 */
     _mergedCount?: number;
     /** 合并前的原始消息列表（用于 gateway 侧逐条格式化信封） */

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/ref-index-store.d.ts

@@ -55,6 +55,37 @@ export declare function getRefIndex(refIdx: string): RefIndexEntry | null;
  * 将引用消息内容格式化为人类可读的描述（供 AI 上下文注入）
  */
 export declare function formatRefEntryForAgent(entry: RefIndexEntry): string;
+/**
+ * 将 QQ 推送事件中的 message_reference 结构格式化为人类可读的描述（供 AI 上下文注入）
+ *
+ * 完整参考 gateway 中对当前消息的处理流程：
+ * 1. 调用 processAttachments 下载附件到本地、语音转录
+ * 2. 调用 formatVoiceText 格式化语音转录文本
+ * 3. 调用 parseFaceTags 解析 QQ 表情标签
+ * 4. 按 gateway 中 userContent 的拼接逻辑组合最终文本
+ */
+export declare function formatMessageReferenceForAgent(ref: {
+    content: string;
+    attachments?: Array<{
+        content_type: string;
+        url: string;
+        filename?: string;
+        height?: number;
+        width?: number;
+        size?: number;
+        voice_wav_url?: string;
+        asr_refer_text?: string;
+    }>;
+} | undefined, ctx: {
+    appId: string;
+    peerId?: string;
+    cfg: unknown;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}): Promise<string>;
 /**
  * 进程退出前强制 compact（确保数据一致性）
  */

package/dist/src/ref-index-store.js

@@ -16,6 +16,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { getQQBotDataDir } from "./utils/platform.js";
 import { formatAttachmentTags } from "./group-history.js";
+import { parseFaceTags, buildAttachmentSummaries } from "./utils/text-parsing.js";
+import { processAttachments, formatVoiceText } from "./inbound-attachments.js";
 // ============ 配置 ============
 const STORAGE_DIR = getQQBotDataDir("data");
 const REF_INDEX_FILE = path.join(STORAGE_DIR, "ref-index.jsonl");
@@ -226,7 +228,53 @@ export function formatRefEntryForAgent(entry) {
     if (attachmentDesc) {
         parts.push(attachmentDesc);
     }
-    return parts.join(" ") || "[空消息]";
+    return parts.join("\n");
+}
+/**
+ * 将 QQ 推送事件中的 message_reference 结构格式化为人类可读的描述（供 AI 上下文注入）
+ *
+ * 完整参考 gateway 中对当前消息的处理流程：
+ * 1. 调用 processAttachments 下载附件到本地、语音转录
+ * 2. 调用 formatVoiceText 格式化语音转录文本
+ * 3. 调用 parseFaceTags 解析 QQ 表情标签
+ * 4. 按 gateway 中 userContent 的拼接逻辑组合最终文本
+ */
+export async function formatMessageReferenceForAgent(ref, ctx) {
+    if (!ref)
+        return "";
+    // 处理附件（图片等）- 下载到本地供 openclaw 访问（参考 gateway 中 processAttachments 调用）
+    const processed = await processAttachments(ref.attachments, ctx);
+    const { attachmentInfo, voiceTranscripts, voiceTranscriptSources, attachmentLocalPaths } = processed;
+    // 语音转录文本注入（参考 gateway 中 formatVoiceText 调用）
+    const voiceText = formatVoiceText(voiceTranscripts);
+    // 解析 QQ 表情标签，将 <faceType=...,ext="base64"> 替换为 【表情: 中文名】
+    const parsedContent = parseFaceTags(ref.content ?? "");
+    // 最终组合（参考 gateway 中 userContent 的拼接逻辑）
+    const userContent = voiceText
+        ? (parsedContent.trim() ? `${parsedContent}\n${voiceText}` : voiceText) + attachmentInfo
+        : parsedContent + attachmentInfo;
+    // 构建附件摘要并通过 formatAttachmentTags 统一生成标签
+    // 与缓存命中路径 (formatRefEntryForAgent → formatAttachmentTags) 格式完全一致
+    const attSummaries = buildAttachmentSummaries(ref.attachments, attachmentLocalPaths);
+    if (attSummaries && voiceTranscripts.length > 0) {
+        let voiceIdx = 0;
+        for (const att of attSummaries) {
+            if (att.type === "voice" && voiceIdx < voiceTranscripts.length) {
+                att.transcript = voiceTranscripts[voiceIdx];
+                if (voiceIdx < voiceTranscriptSources.length) {
+                    att.transcriptSource = voiceTranscriptSources[voiceIdx];
+                }
+                voiceIdx++;
+            }
+        }
+    }
+    const attachmentDesc = formatAttachmentTags(attSummaries);
+    const parts = [];
+    if (userContent.trim())
+        parts.push(userContent.trim());
+    if (attachmentDesc)
+        parts.push(attachmentDesc);
+    return parts.join(" ");
 }
 /**
  * 进程退出前强制 compact（确保数据一致性）

package/dist/src/runtime.js

@@ -1,6 +1,9 @@
+import { setOpenClawVersion } from "./api.js";
 let runtime = null;
 export function setQQBotRuntime(next) {
     runtime = next;
+    // 将框架版本注入 User-Agent（runtime 注入后才能拿到准确版本）
+    setOpenClawVersion(next.version);
 }
 export function getQQBotRuntime() {
     if (!runtime) {