@tencent-connect/openclaw-qqbot 1.5.7 → 1.6.0-alpha.2

package/src/gateway.ts

@@ -2,18 +2,22 @@ import WebSocket from "ws";
 import path from "node:path";
 import * as fs from "node:fs";
 import type { ResolvedQQBotAccount, WSPayload, C2CMessageEvent, GuildMessageEvent, GroupMessageEvent } from "./types.js";
-import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent } from "./api.js";
+import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, PLUGIN_USER_AGENT, sendProactiveC2CMessage, sendProactiveGroupMessage } from "./api.js";
 import { loadSession, saveSession, clearSession, type SessionState } from "./session-store.js";
-import { recordKnownUser, flushKnownUsers } from "./known-users.js";
+import { recordKnownUser, flushKnownUsers, listKnownUsers } from "./known-users.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, flushRefIndex, type RefAttachmentSummary } from "./ref-index-store.js";
+import { matchSlashCommand, getPluginVersion, type SlashCommandContext, type SlashCommandFileResult, type QueueSnapshot } from "./slash-commands.js";
+import { triggerUpdateCheck } from "./update-checker.js";
 import { startImageServer, isImageServerRunning, downloadFile, type ImageServerConfig } from "./image-server.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize, DEFAULT_IMAGE_SIZE } from "./utils/image-size.js";
 import { parseQQBotPayload, encodePayloadForCron, isCronReminderPayload, isMediaPayload, type CronReminderPayload, type MediaPayload } from "./utils/payload.js";
-import { convertSilkToWav, isVoiceAttachment, formatDuration, resolveTTSConfig, textToSilk, audioFileToSilkBase64, waitForFile, isAudioFile } from "./utils/audio-convert.js";
+import { convertSilkToWav, isVoiceAttachment, formatDuration, resolveTTSConfig, textToSilk } from "./utils/audio-convert.js";
 import { normalizeMediaTags } from "./utils/media-tags.js";
 import { checkFileSize, readFileAsync, fileExistsAsync, isLargeFile, formatFileSize } from "./utils/file-utils.js";
-import { getQQBotDataDir, isLocalPath as isLocalFilePath, looksLikeLocalPath, normalizePath, sanitizeFileName, runDiagnostics } from "./utils/platform.js";
+import { getQQBotDataDir, isLocalPath as isLocalFilePath, normalizePath, sanitizeFileName, runDiagnostics } from "./utils/platform.js";
+import { MSG, formatMediaErrorMessage } from "./user-messages.js";
+import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, sendMedia as sendMediaAuto, type MediaTargetContext } from "./outbound.js";
 
 /**
  * 通用 OpenAI 兼容 STT（语音转文字）
@@ -108,27 +112,9 @@ const INTENTS = {
   GROUP_AND_C2C: 1 << 25,            // 群聊和 C2C 私聊（需申请）
 };
 
-// 权限级别：从高到低依次尝试
-const INTENT_LEVELS = [
-  // Level 0: 完整权限（群聊 + 私信 + 频道）
-  {
-    name: "full",
-    intents: INTENTS.PUBLIC_GUILD_MESSAGES | INTENTS.DIRECT_MESSAGE | INTENTS.GROUP_AND_C2C,
-    description: "群聊+私信+频道",
-  },
-  // Level 1: 群聊 + 频道（无私信）
-  {
-    name: "group+channel",
-    intents: INTENTS.PUBLIC_GUILD_MESSAGES | INTENTS.GROUP_AND_C2C,
-    description: "群聊+频道",
-  },
-  // Level 2: 仅频道（基础权限）
-  {
-    name: "channel-only",
-    intents: INTENTS.PUBLIC_GUILD_MESSAGES | INTENTS.GUILD_MEMBERS,
-    description: "仅频道消息",
-  },
-];
+// 固定使用完整权限（群聊 + 私信 + 频道），不做降级
+const FULL_INTENTS = INTENTS.PUBLIC_GUILD_MESSAGES | INTENTS.DIRECT_MESSAGE | INTENTS.GROUP_AND_C2C;
+const FULL_INTENTS_DESC = "群聊+私信+频道";
 
 // 重连配置
 const RECONNECT_DELAYS = [1000, 2000, 5000, 10000, 30000, 60000]; // 递增延迟
@@ -235,27 +221,7 @@ function parseFaceTags(text: string): string {
   });
 }
 
-// ============ 媒体发送友好错误提示 ============
-
-/**
- * 将媒体上传/发送错误转为对用户友好的提示文案
- */
-function formatMediaErrorMessage(mediaType: string, err: unknown): string {
-  const msg = err instanceof Error ? err.message : String(err);
-  if (msg.includes("上传超时") || msg.includes("timeout") || msg.includes("Timeout")) {
-    return `抱歉，${mediaType}资源加载超时，可能是网络原因或文件太大，请稍后再试～`;
-  }
-  if (msg.includes("文件不存在") || msg.includes("not found") || msg.includes("Not Found")) {
-    return `抱歉，${mediaType}文件不存在或已失效，无法发送～`;
-  }
-  if (msg.includes("文件大小") || msg.includes("too large") || msg.includes("exceed")) {
-    return `抱歉，${mediaType}文件太大了，超出了发送限制～`;
-  }
-  if (msg.includes("Network error") || msg.includes("ECONNREFUSED") || msg.includes("ENOTFOUND")) {
-    return `抱歉，网络连接异常，${mediaType}发送失败，请稍后再试～`;
-  }
-  return `抱歉，${mediaType}发送失败了，请稍后再试～`;
-}
+// formatMediaErrorMessage 已移至 user-messages.ts 集中管理
 
 // ============ 内部标记过滤 ============
 
@@ -378,6 +344,49 @@ async function ensureImageServer(log?: GatewayContext["log"], publicBaseUrl?: st
   }
 }
 
+// ============ 启动问候语（首次安装/版本更新 vs 普通重启） ============
+
+// 模块级变量：进程生命周期内只有首次为 true
+// 区分 gateway restart（进程重启）和 health-monitor 断线重连
+let isFirstReadyGlobal = true;
+
+const STARTUP_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.json");
+
+/**
+ * 判断是否为首次安装或版本更新，返回对应的问候语。
+ * - 首次安装 / 版本变更 → "Haha，我的'灵魂'已上线，随时等你吩咐。"
+ * - 普通重启             → "我重新登上了，有事随时找我。"
+ */
+function getStartupGreeting(): string {
+  const currentVersion = getPluginVersion();
+  let isFirstOrUpdated = true;
+
+  try {
+    if (fs.existsSync(STARTUP_MARKER_FILE)) {
+      const data = JSON.parse(fs.readFileSync(STARTUP_MARKER_FILE, "utf8"));
+      if (data.version === currentVersion) {
+        isFirstOrUpdated = false;
+      }
+    }
+  } catch {
+    // 文件损坏或不存在，视为首次
+  }
+
+  // 更新 marker 文件
+  try {
+    fs.writeFileSync(STARTUP_MARKER_FILE, JSON.stringify({
+      version: currentVersion,
+      startedAt: new Date().toISOString(),
+    }) + "\n");
+  } catch {
+    // ignore
+  }
+
+  return isFirstOrUpdated
+    ? `Haha，我的'灵魂'已上线，随时等你吩咐。`
+    : `我重新登上了，有事随时找我。`;
+}
+
 /**
  * 启动 Gateway WebSocket 连接（带自动重连）
  * 支持流式消息发送
@@ -397,6 +406,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     }
   }
 
+  // 后台版本检查（detached 子进程，零阻塞）
+  triggerUpdateCheck(log);
+
   // 初始化 API 配置（markdown 支持）
   initApiConfig({
     markdownSupport: account.markdownSupport,
@@ -471,8 +483,46 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   let isConnecting = false; // 防止并发连接
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null; // 重连定时器
   let shouldRefreshToken = false; // 下次连接是否需要刷新 token
-  let intentLevelIndex = 0; // 当前尝试的权限级别索引
-  let lastSuccessfulIntentLevel = -1; // 上次成功的权限级别
+  // 使用模块级 isFirstReadyGlobal，确保只有进程级重启才发送问候语
+  // health-monitor 重连不会重新初始化为 true
+
+  /** 异步发送启动问候语（READY 或 RESUMED 时调用） */
+  const sendStartupGreetings = (trigger: "READY" | "RESUMED") => {
+    (async () => {
+      try {
+        const greeting = getStartupGreeting();
+        log?.info(`[qqbot:${account.accountId}] Sending startup greeting (trigger=${trigger}): "${greeting}"`);
+        const token = await getAccessToken(account.appId, account.clientSecret);
+        const users = listKnownUsers({ accountId: account.accountId, type: "c2c" });
+        for (const user of users) {
+          try {
+            await sendProactiveC2CMessage(token, user.openid, greeting);
+            log?.info(`[qqbot:${account.accountId}] Sent startup greeting to c2c:${user.openid}`);
+          } catch (err) {
+            log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to c2c:${user.openid}: ${err}`);
+          }
+          await new Promise(r => setTimeout(r, 500));
+        }
+        const groups = listKnownUsers({ accountId: account.accountId, type: "group" });
+        const sentGroups = new Set<string>();
+        for (const user of groups) {
+          const gid = user.groupOpenid;
+          if (!gid || sentGroups.has(gid)) continue;
+          sentGroups.add(gid);
+          try {
+            await sendProactiveGroupMessage(token, gid, greeting);
+            log?.info(`[qqbot:${account.accountId}] Sent startup greeting to group:${gid}`);
+          } catch (err) {
+            log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to group:${gid}: ${err}`);
+          }
+          await new Promise(r => setTimeout(r, 500));
+        }
+        log?.info(`[qqbot:${account.accountId}] Startup greetings sent (${users.length} c2c, ${sentGroups.size} groups)`);
+      } catch (err) {
+        log?.error(`[qqbot:${account.accountId}] Failed to send startup greetings: ${err}`);
+      }
+    })();
+  };
 
   // ============ P1-2: 尝试从持久化存储恢复 Session ============
   // 传入当前 appId，如果 appId 已变更（换了机器人），旧 session 自动失效
@@ -480,9 +530,7 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   if (savedSession) {
     sessionId = savedSession.sessionId;
     lastSeq = savedSession.lastSeq;
-    intentLevelIndex = savedSession.intentLevelIndex;
-    lastSuccessfulIntentLevel = savedSession.intentLevelIndex;
-    log?.info(`[qqbot:${account.accountId}] Restored session from storage: sessionId=${sessionId}, lastSeq=${lastSeq}, intentLevel=${intentLevelIndex}`);
+    log?.info(`[qqbot:${account.accountId}] Restored session from storage: sessionId=${sessionId}, lastSeq=${lastSeq}`);
   }
 
   // ============ 按用户并发的消息队列（同用户串行，跨用户并行） ============
@@ -575,6 +623,101 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     log?.info(`[qqbot:${account.accountId}] Message processor started (per-user concurrency, max ${MAX_CONCURRENT_USERS} users)`);
   };
 
+  // 获取队列状态快照（供斜杠指令使用）
+  const getQueueSnapshot = (senderPeerId: string): QueueSnapshot => {
+    let totalPending = 0;
+    for (const [, q] of userQueues) {
+      totalPending += q.length;
+    }
+    const senderQueue = userQueues.get(senderPeerId);
+    return {
+      totalPending,
+      activeUsers: activeUsers.size,
+      maxConcurrentUsers: MAX_CONCURRENT_USERS,
+      senderPending: senderQueue ? senderQueue.length : 0,
+    };
+  };
+
+  // 斜杠指令拦截：在入队前匹配插件级指令，命中则直接回复，不入队
+  const trySlashCommandOrEnqueue = async (msg: QueuedMessage): Promise<void> => {
+    const content = (msg.content ?? "").trim();
+    if (!content.startsWith("/")) {
+      enqueueMessage(msg);
+      return;
+    }
+
+    const receivedAt = Date.now();
+    const peerId = getMessagePeerId(msg);
+
+    const cmdCtx: SlashCommandContext = {
+      type: msg.type,
+      senderId: msg.senderId,
+      senderName: msg.senderName,
+      messageId: msg.messageId,
+      eventTimestamp: msg.timestamp,
+      receivedAt,
+      rawContent: content,
+      args: "",
+      channelId: msg.channelId,
+      groupOpenid: msg.groupOpenid,
+      accountId: account.accountId,
+      accountConfig: account.config,
+      queueSnapshot: getQueueSnapshot(peerId),
+    };
+
+    try {
+      const reply = await matchSlashCommand(cmdCtx);
+      if (reply === null) {
+        // 不是插件级指令，正常入队交给框架
+        enqueueMessage(msg);
+        return;
+      }
+
+      // 命中插件级指令，直接回复
+      log?.info(`[qqbot:${account.accountId}] Slash command matched: ${content}, replying directly`);
+      const token = await getAccessToken(account.appId, account.clientSecret);
+
+      // 解析回复：纯文本 or 带文件的结果
+      const isFileResult = typeof reply === "object" && reply !== null && "filePath" in reply;
+      const replyText = isFileResult ? (reply as SlashCommandFileResult).text : reply as string;
+      const replyFile = isFileResult ? (reply as SlashCommandFileResult).filePath : null;
+
+      // 先发送文本回复
+      if (msg.type === "c2c") {
+        await sendC2CMessage(token, msg.senderId, replyText, msg.messageId);
+      } else if (msg.type === "group" && msg.groupOpenid) {
+        await sendGroupMessage(token, msg.groupOpenid, replyText, msg.messageId);
+      } else if (msg.channelId) {
+        await sendChannelMessage(token, msg.channelId, replyText, msg.messageId);
+      } else if (msg.type === "dm") {
+        await sendC2CMessage(token, msg.senderId, replyText, msg.messageId);
+      }
+
+      // 如果有文件需要发送
+      if (replyFile) {
+        try {
+          const targetType = msg.type === "group" ? "group" : msg.type === "c2c" || msg.type === "dm" ? "c2c" : "channel";
+          const targetId = msg.type === "group" ? (msg.groupOpenid || msg.senderId) : msg.type === "c2c" || msg.type === "dm" ? msg.senderId : (msg.channelId || msg.senderId);
+          const mediaCtx: MediaTargetContext = {
+            targetType,
+            targetId,
+            account,
+            replyToId: msg.messageId,
+            logPrefix: `[qqbot:${account.accountId}]`,
+          };
+          await sendDocument(mediaCtx, replyFile);
+          log?.info(`[qqbot:${account.accountId}] Slash command file sent: ${replyFile}`);
+        } catch (fileErr) {
+          log?.error(`[qqbot:${account.accountId}] Failed to send slash command file: ${fileErr}`);
+        }
+      }
+    } catch (err) {
+      log?.error(`[qqbot:${account.accountId}] Slash command error: ${err}`);
+      // 出错时回退到正常入队
+      enqueueMessage(msg);
+    }
+  };
+
   abortSignal.addEventListener("abort", () => {
     isAborted = true;
     if (reconnectTimer) {
@@ -654,7 +797,7 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
 
       log?.info(`[qqbot:${account.accountId}] Connecting to ${gatewayUrl}`);
 
-      const ws = new WebSocket(gatewayUrl);
+      const ws = new WebSocket(gatewayUrl, { headers: { "User-Agent": PLUGIN_USER_AGENT } });
       currentWs = ws;
 
       const pluginRuntime = getQQBotRuntime();
@@ -900,13 +1043,8 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         const hasAsrReferFallback = voiceTranscriptSources.includes("asr");
         if (voiceTranscripts.length > 0) {
           voiceText = voiceTranscripts.length === 1
-            ? `${voiceTranscriptSources[0] === "asr" ? "[语音消息(ASR兜底，可能不准确)]" : "[语音消息]"} ${voiceTranscripts[0]}`
-            : voiceTranscripts.map((t, i) => {
-                const prefix = voiceTranscriptSources[i] === "asr"
-                  ? `[语音${i + 1}(ASR兜底，可能不准确)]`
-                  : `[语音${i + 1}]`;
-                return `${prefix} ${t}`;
-              }).join("\n");
+            ? `[语音消息] ${voiceTranscripts[0]}`
+            : voiceTranscripts.map((t, i) => `[语音${i + 1}] ${t}`).join("\n");
         }
 
         // 解析 QQ 表情标签，将 <faceType=...,ext="base64"> 替换为 【表情: 中文名】
@@ -1003,58 +1141,11 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
             + (asrPreview ? `, asr_preview="${asrPreview}${uniqueVoiceAsrReferTexts[0].length > 50 ? "..." : ""}"` : "")
           );
         }
-        let receivedMediaSection = "";
-        if (imageUrls.length > 0 || uniqueVoicePaths.length > 0 || uniqueVoiceUrls.length > 0) {
-          const mediaSections: string[] = [];
-          if (imageUrls.length > 0) {
-            const imageEntries = imageUrls.map((p, i) => `  - ${p} (${imageMediaTypes[i] || "unknown"})`);
-            mediaSections.push(`- 图片附件:\n${imageEntries.join("\n")}`);
-          }
-          if (uniqueVoicePaths.length > 0 || uniqueVoiceUrls.length > 0) {
-            const voiceEntries = [
-              ...uniqueVoicePaths.map((p) => `  - ${p} (local audio)`),
-              ...uniqueVoiceUrls.map((u) => `  - ${u} (remote audio)`),
-            ];
-            mediaSections.push(`- 语音附件:\n${voiceEntries.join("\n")}`);
-          }
-          receivedMediaSection = `\n${mediaSections.join("\n")}`;
-        }
-
         // AI 看到的投递地址必须带完整前缀（qqbot:c2c: / qqbot:group:）
         const qualifiedTarget = isGroupChat ? `qqbot:group:${event.groupOpenid}` : `qqbot:c2c:${event.senderId}`;
 
-        // 动态检测 TTS/STT 配置状态
+        // 动态检测 TTS 配置状态
         const hasTTS = !!resolveTTSConfig(cfg as Record<string, unknown>);
-        const hasSTT = !!resolveSTTConfig(cfg as Record<string, unknown>);
-
-        // 语音能力说明：<qqvoice> 标签本身只负责发送已有的音频文件，不依赖插件 TTS。
-        // TTS 只是生成音频文件的一种方式，框架侧的 TTS 工具（如 audio_speech）也能生成。
-        // 因此始终暴露 <qqvoice> 能力，但根据 TTS 状态给出不同的使用指引。
-        const ttsHint = hasTTS
-          ? `6. 🎤 插件 TTS 已启用: 如果你有 TTS 工具（如 audio_speech），可用它生成音频文件后用 <qqvoice> 发送`
-          : `6. ⚠️ 插件 TTS 未配置: 如果你有 TTS 工具（如 audio_speech），仍可用它生成音频文件后用 <qqvoice> 发送；若无 TTS 工具，则无法主动生成语音`;
-        const sttHint = hasSTT
-          ? `\n7. 插件侧 STT 已配置，用户发送的语音消息会尽量自动转录`
-          : `\n7. 插件侧 STT 未配置，插件不会自动转录语音消息`;
-        const asrFallbackHint = hasAsrReferFallback
-          ? `\n8. 本条消息包含平台返回的 asr_refer_text 兜底文本（低置信度）。理解用户意图时可参考，但如关键信息不明确应先追问确认。`
-          : "";
-        const voiceForwardHint = uniqueVoicePaths.length > 0 || uniqueVoiceUrls.length > 0
-          ? `\n9. 本条消息已附带语音文件路径/URL。若你具备 STT 能力（框架能力或 STT skill），优先直接转写音频；若无 STT 能力或转写失败，再使用 asr_refer_text（若存在）作为兜底。`
-          : "";
-        const voiceSection = `
-
-【发送语音 - 必须遵守】
-1. 发语音方法: 在回复文本中写 <qqvoice>本地音频文件路径</qqvoice>，系统自动处理
-2. 示例: "来听听吧！ <qqvoice>/tmp/tts/voice.mp3</qqvoice>"
-3. 支持格式: .silk, .slk, .slac, .amr, .wav, .mp3, .ogg, .pcm
-4. ⚠️ <qqvoice> 只用于语音文件，图片请用 <qqimg>；两者不要混用
-5. 发送语音时，不要重复输出语音中已朗读的文字内容；语音前后的文字应是补充信息而非语音的文字版重复
-${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
-
-        const voiceAsrSection = uniqueVoiceAsrReferTexts.length > 0
-          ? `\n- 语音ASR兜底文本:\n${uniqueVoiceAsrReferTexts.map((t, i) => `  ${i + 1}. ${t}`).join("\n")}`
-          : "";
 
         // 引用消息上下文
         let quotePart = "";
@@ -1066,46 +1157,46 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
           }
         }
 
-        const contextInfo = `你正在通过 QQ 与用户对话。
-
-【会话上下文】
-- 用户: ${event.senderName || "未知"} (${event.senderId})
-- 场景: ${isGroupChat ? "群聊" : "私聊"}${isGroupChat ? ` (群组: ${event.groupOpenid})` : ""}
-- 消息ID: ${event.messageId}
-- 投递目标: ${qualifiedTarget}${receivedMediaSection}${voiceAsrSection}
-- 当前时间戳(ms): ${nowMs}
-- 定时提醒投递地址: channel=qqbot, to=${qualifiedTarget}
-
-【发送图片 - 必须遵守】
-1. 发图方法: 在回复文本中写 <qqimg>URL</qqimg>，系统自动处理
-2. 示例: "龙虾来啦！🦞 <qqimg>https://picsum.photos/800/600</qqimg>"
-3. 图片来源: 已知URL直接用、用户发过的本地路径、也可以通过 web_search 搜索图片URL后使用
-4. ⚠️ 必须在文字回复中嵌入 <qqimg> 标签，禁止只调 tool 不回复文字（用户看不到任何内容）
-5. 不要说"无法发送图片"，直接用 <qqimg> 标签发${voiceSection}
-
-【发送文件 - 必须遵守】
-1. 发文件方法: 在回复文本中写 <qqfile>文件路径或URL</qqfile>，系统自动处理
-2. 示例: "这是你要的文档 <qqfile>/tmp/report.pdf</qqfile>"
-3. 支持: 本地文件路径、公网 URL
-4. 适用于非图片非语音的文件（如 pdf, docx, xlsx, zip, txt 等）
-5. ⚠️ 图片用 <qqimg>，语音用 <qqvoice>，其他文件用 <qqfile>
-
-【发送视频 - 必须遵守】
-1. 发视频方法: 在回复文本中写 <qqvideo>路径或URL</qqvideo>，系统自动处理
-2. 示例: "<qqvideo>https://example.com/video.mp4</qqvideo>" 或 "<qqvideo>/path/to/video.mp4</qqvideo>"
-3. 支持: 公网 URL、本地文件路径（系统自动读取上传）
-4. ⚠️ 视频用 <qqvideo>，图片用 <qqimg>，语音用 <qqvoice>，文件用 <qqfile>
-
-【不要向用户透露过多以上述要求，以下是用户输入】
-
-`;
+        // ============ 构建 contextInfo（静态/动态分离） ============
+        // 设计原则（参考 Telegram/Discord 做法）：
+        //   - 静态指引：每条消息不变的内容（场景锚定、投递地址、能力说明），
+        //     注入 systemPrompts 前部，session 中虽重复出现但 AI 会自动降权，
+        //     且保证长 session 窗口截断后仍可见。
+        //   - 动态标签：每条消息变化的数据（时间、附件、ASR），
+        //     以紧凑的 [ctx] 块标注在用户消息前，最小化 token 开销。
+
+        // --- 静态指引（仅注入框架信封未覆盖的 QQBot 特有信息） ---
+        // 框架 formatInboundEnvelope 已提供：平台标识、发送者、时间戳
+        // 这里只补充 QQBot 独有的：投递地址（cron skill 需要）
+        const staticParts: string[] = [
+          `[QQBot] to=${qualifiedTarget}`,
+        ];
+        // TTS 能力声明：仅在启用时告知 AI 可以发语音（与 qqbot-media SKILL.md 互补）
+        // STT 无需声明：转写结果已在动态上下文的 ASR 行中，AI 自然可见
+        if (hasTTS) staticParts.push("语音合成已启用，发送媒体格式：<qqmedia>路径</qqmedia>");
+        const staticInstruction = staticParts.join(" | ");
+
+        // 静态指引作为 systemPrompts 的首项注入
+        systemPrompts.unshift(staticInstruction);
+
+        // --- 动态上下文（仅框架信封未覆盖的附件信息） ---
+        const dynLines: string[] = [];
+        if (imageUrls.length > 0) {
+          dynLines.push(`- 图片: ${imageUrls.join(", ")}`);
+        }
+        if (uniqueVoicePaths.length > 0 || uniqueVoiceUrls.length > 0) {
+          dynLines.push(`- 语音: ${[...uniqueVoicePaths, ...uniqueVoiceUrls].join(", ")}`);
+        }
+        if (uniqueVoiceAsrReferTexts.length > 0) {
+          dynLines.push(`- ASR: ${uniqueVoiceAsrReferTexts.join(" | ")}`);
+        }
+        const dynamicCtx = dynLines.length > 0 ? dynLines.join("\n") + "\n" : "";
+
         // 命令直接透传，不注入上下文
         const userMessage = `${quotePart}${userContent}`;
         const agentBody = userContent.startsWith("/")
           ? userContent
-          : systemPrompts.length > 0 
-            ? `${contextInfo}\n\n${systemPrompts.join("\n")}\n\n${userMessage}`
-            : `${contextInfo}\n\n${userMessage}`;
+          : `${systemPrompts.join("\n")}\n\n${dynamicCtx}${userMessage}`;
         
         log?.info(`[qqbot:${account.accountId}] agentBody length: ${agentBody.length}`);
 
@@ -1230,7 +1321,8 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
           let hasResponse = false;
           let hasBlockResponse = false; // 是否收到了面向用户的 block 回复
           let toolDeliverCount = 0; // tool deliver 计数
-          const toolTexts: string[] = []; // 收集所有 tool deliver 文本（用于格式化展示）
+          const toolTexts: string[] = []; // 收集所有 tool deliver 文本
+          const toolMediaUrls: string[] = []; // 收集所有 tool deliver 媒体 URL
           let toolFallbackSent = false; // 兜底消息是否已发送（只发一次）
           const responseTimeout = 120000; // 120秒超时（2分钟，与 TTS/文件生成超时对齐）
           const toolOnlyTimeout = 60000; // tool-only 兜底超时：60秒内没有 block 就兜底
@@ -1239,19 +1331,45 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
           let timeoutId: ReturnType<typeof setTimeout> | null = null;
           let toolOnlyTimeoutId: ReturnType<typeof setTimeout> | null = null;
 
-          // 格式化 tool 兜底消息：极简，只展示工具原始参数
-          const formatToolFallback = (): string => {
-            if (toolTexts.length === 0) {
-              return "🔧 调用工具中…";
+          // tool-only 兜底：转发工具产生的实际内容（媒体/文本），而非生硬的提示语
+          const sendToolFallback = async (): Promise<void> => {
+            // 优先发送工具产出的媒体文件（TTS 语音、生成图片等）
+            if (toolMediaUrls.length > 0) {
+              log?.info(`[qqbot:${account.accountId}] Tool fallback: forwarding ${toolMediaUrls.length} media URL(s) from tool deliver(s)`);
+              const mediaTimeout = 45000; // 单个媒体发送超时 45s
+              for (const mediaUrl of toolMediaUrls) {
+                try {
+                  const result = await Promise.race([
+                    sendMediaAuto({
+                      to: qualifiedTarget,
+                      text: "",
+                      mediaUrl,
+                      accountId: account.accountId,
+                      replyToId: event.messageId,
+                      account,
+                    }),
+                    new Promise<{ channel: string; error: string }>((resolve) =>
+                      setTimeout(() => resolve({ channel: "qqbot", error: `Tool fallback media send timeout (${mediaTimeout / 1000}s)` }), mediaTimeout)
+                    ),
+                  ]);
+                  if (result.error) {
+                    log?.error(`[qqbot:${account.accountId}] Tool fallback sendMedia error: ${result.error}`);
+                  }
+                } catch (err) {
+                  log?.error(`[qqbot:${account.accountId}] Tool fallback sendMedia failed: ${err}`);
+                }
+              }
+              return;
             }
-            const recentTools = toolTexts.slice(-3);
-            const totalLen = recentTools.reduce((s, t) => s + t.length, 0);
-            if (totalLen > 1800) {
-              const last = recentTools[recentTools.length - 1]!;
-              return `🔧 调用工具中…\n\`\`\`\n${last.slice(0, 1500)}\n\`\`\``;
+            // 其次转发工具产出的文本
+            if (toolTexts.length > 0) {
+              const text = toolTexts.slice(-3).join("\n---\n").slice(0, 2000);
+              log?.info(`[qqbot:${account.accountId}] Tool fallback: forwarding tool text (${text.length} chars)`);
+              await sendErrorMessage(text);
+              return;
             }
-            const toolBlock = recentTools.join("\n---\n");
-            return `🔧 调用工具中…\n\`\`\`\n${toolBlock}\n\`\`\``;
+            // 既无媒体也无文本，静默处理（仅日志记录）
+            log?.info(`[qqbot:${account.accountId}] Tool fallback: no media or text collected from ${toolDeliverCount} tool deliver(s), silently dropping`);
           };
 
           const timeoutPromise = new Promise<void>((_, reject) => {
@@ -1285,7 +1403,41 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   if (toolText) {
                     toolTexts.push(toolText);
                   }
-                  log?.info(`[qqbot:${account.accountId}] Skipping tool result deliver #${toolDeliverCount} (intermediate, not user-facing), text length: ${toolText.length}`);
+                  // 收集工具产出的媒体 URL（TTS 语音、生成图片等），供 fallback 转发
+                  if (payload.mediaUrls?.length) {
+                    toolMediaUrls.push(...payload.mediaUrls);
+                  }
+                  if (payload.mediaUrl && !toolMediaUrls.includes(payload.mediaUrl)) {
+                    toolMediaUrls.push(payload.mediaUrl);
+                  }
+                  log?.info(`[qqbot:${account.accountId}] Collected tool deliver #${toolDeliverCount}: text=${toolText.length} chars, media=${toolMediaUrls.length} URLs`);
+
+                  // block 已先发送完毕，tool 后到的媒体立即转发（典型场景：AI 先流式输出文本再执行 TTS）
+                  if (hasBlockResponse && toolMediaUrls.length > 0) {
+                    log?.info(`[qqbot:${account.accountId}] Block already sent, immediately forwarding ${toolMediaUrls.length} tool media URL(s)`);
+                    const urlsToSend = [...toolMediaUrls];
+                    toolMediaUrls.length = 0;
+                    for (const mediaUrl of urlsToSend) {
+                      try {
+                        const result = await sendMediaAuto({
+                          to: qualifiedTarget,
+                          text: "",
+                          mediaUrl,
+                          accountId: account.accountId,
+                          replyToId: event.messageId,
+                          account,
+                        });
+                        if (result.error) {
+                          log?.error(`[qqbot:${account.accountId}] Tool media immediate forward error: ${result.error}`);
+                        } else {
+                          log?.info(`[qqbot:${account.accountId}] Forwarded tool media (post-block): ${mediaUrl.slice(0, 80)}...`);
+                        }
+                      } catch (err) {
+                        log?.error(`[qqbot:${account.accountId}] Tool media immediate forward failed: ${err}`);
+                      }
+                    }
+                    return;
+                  }
 
                   // 兜底已发送，不再续期
                   if (toolFallbackSent) {
@@ -1309,17 +1461,8 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                     if (!hasBlockResponse && !toolFallbackSent) {
                       toolFallbackSent = true;
                       log?.error(`[qqbot:${account.accountId}] Tool-only timeout: ${toolDeliverCount} tool deliver(s) but no block within ${toolOnlyTimeout / 1000}s, sending fallback`);
-                      const fallback = formatToolFallback();
                       try {
-                        await sendWithTokenRetry(async (token) => {
-                          if (event.type === "c2c") {
-                            await sendC2CMessage(token, event.senderId, fallback, event.messageId);
-                          } else if (event.type === "group" && event.groupOpenid) {
-                            await sendGroupMessage(token, event.groupOpenid, fallback, event.messageId);
-                          } else if (event.channelId) {
-                            await sendChannelMessage(token, event.channelId, fallback, event.messageId);
-                          }
-                        });
+                        await sendToolFallback();
                       } catch (sendErr) {
                         log?.error(`[qqbot:${account.accountId}] Failed to send tool-only fallback: ${sendErr}`);
                       }
@@ -1358,31 +1501,29 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                 let replyText = payload.text ?? "";
                 
                 // ============ 媒体标签解析 ============
-                // 支持四种标签:
-                //   <qqimg>路径</qqimg> 或 <qqimg>路径</img>  — 图片
-                //   <qqvoice>路径</qqvoice>                   — 语音
-                //   <qqvideo>路径或URL</qqvideo>                — 视频
-                //   <qqfile>路径</qqfile>                     — 文件
+                // 支持五种标签:
+                //   <qqimg>路径</qqimg>      — 图片
+                //   <qqvoice>路径</qqvoice>  — 语音
+                //   <qqvideo>路径或URL</qqvideo> — 视频
+                //   <qqfile>路径</qqfile>    — 文件
+                //   <qqmedia>路径或URL</qqmedia> — 自动识别（根据扩展名路由）
                 // 按文本中出现的位置统一构建发送队列，保持顺序
                 
                 // 预处理：纠正小模型常见的标签拼写错误和格式问题
                 replyText = normalizeMediaTags(replyText);
                 
-                const mediaTagRegex = /<(qqimg|qqvoice|qqvideo|qqfile)>([^<>]+)<\/(?:qqimg|qqvoice|qqvideo|qqfile|img)>/gi;
+                const mediaTagRegex = /<(qqimg|qqvoice|qqvideo|qqfile|qqmedia)>([^<>]+)<\/(?:qqimg|qqvoice|qqvideo|qqfile|qqmedia|img)>/gi;
                 const mediaTagMatches = [...replyText.matchAll(mediaTagRegex)];
                 
                 if (mediaTagMatches.length > 0) {
-                  const imgCount = mediaTagMatches.filter(m => m[1]!.toLowerCase() === "qqimg").length;
-                  const voiceCount = mediaTagMatches.filter(m => m[1]!.toLowerCase() === "qqvoice").length;
-                  const videoCount = mediaTagMatches.filter(m => m[1]!.toLowerCase() === "qqvideo").length;
-                  const fileCount = mediaTagMatches.filter(m => m[1]!.toLowerCase() === "qqfile").length;
-                  log?.info(`[qqbot:${account.accountId}] Detected media tags: ${imgCount} <qqimg>, ${voiceCount} <qqvoice>, ${videoCount} <qqvideo>, ${fileCount} <qqfile>`);
+                  const tagCounts = mediaTagMatches.reduce((acc, m) => { const t = m[1]!.toLowerCase(); acc[t] = (acc[t] ?? 0) + 1; return acc; }, {} as Record<string, number>);
+                  log?.info(`[qqbot:${account.accountId}] Detected media tags: ${Object.entries(tagCounts).map(([k, v]) => `${v} <${k}>`).join(", ")}`);
                   
                   // 构建发送队列
-                  const sendQueue: Array<{ type: "text" | "image" | "voice" | "video" | "file"; content: string }> = [];
+                  const sendQueue: Array<{ type: "text" | "image" | "voice" | "video" | "file" | "media"; content: string }> = [];
                   
                   let lastIndex = 0;
-                  const mediaTagRegexWithIndex = /<(qqimg|qqvoice|qqvideo|qqfile)>([^<>]+)<\/(?:qqimg|qqvoice|qqvideo|qqfile|img)>/gi;
+                  const mediaTagRegexWithIndex = /<(qqimg|qqvoice|qqvideo|qqfile|qqmedia)>([^<>]+)<\/(?:qqimg|qqvoice|qqvideo|qqfile|qqmedia|img)>/gi;
                   let match;
                   
                   while ((match = mediaTagRegexWithIndex.exec(replyText)) !== null) {
@@ -1444,7 +1585,10 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                     }
 
                     if (mediaPath) {
-                      if (tagName === "qqvoice") {
+                      if (tagName === "qqmedia") {
+                        sendQueue.push({ type: "media", content: mediaPath });
+                        log?.info(`[qqbot:${account.accountId}] Found auto-detect media in <qqmedia>: ${mediaPath}`);
+                      } else if (tagName === "qqvoice") {
                         sendQueue.push({ type: "voice", content: mediaPath });
                         log?.info(`[qqbot:${account.accountId}] Found voice path in <qqvoice>: ${mediaPath}`);
                       } else if (tagName === "qqvideo") {
@@ -1470,10 +1614,17 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   
                   log?.info(`[qqbot:${account.accountId}] Send queue: ${sendQueue.map(item => item.type).join(" -> ")}`);
                   
-                  // 按顺序发送
+                  // 按顺序发送（使用 Telegram 风格的统一媒体发送函数）
+                  const mediaTarget: MediaTargetContext = {
+                    targetType: event.type === "c2c" ? "c2c" : event.type === "group" ? "group" : "channel",
+                    targetId: event.type === "c2c" ? event.senderId : event.type === "group" ? event.groupOpenid! : event.channelId!,
+                    account,
+                    replyToId: event.messageId,
+                    logPrefix: `[qqbot:${account.accountId}]`,
+                  };
+
                   for (const item of sendQueue) {
                     if (item.type === "text") {
-                      // 发送文本
                       try {
                         await sendWithTokenRetry(async (token) => {
                           const ref = consumeQuoteRef();
@@ -1490,250 +1641,56 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                         log?.error(`[qqbot:${account.accountId}] Failed to send text: ${err}`);
                       }
                     } else if (item.type === "image") {
-                      // 发送图片（展开 ~ 路径）
-                      const imagePath = normalizePath(item.content);
-                      try {
-                        let imageUrl = imagePath;
-                        
-                        // 判断是本地文件还是 URL
-                        const isLocalPath = isLocalFilePath(imagePath);
-                        const isHttpUrl = imagePath.startsWith("http://") || imagePath.startsWith("https://");
-                        
-                        if (isLocalPath) {
-                          // 本地文件：转换为 Base64 Data URL
-                          if (!(await fileExistsAsync(imagePath))) {
-                            log?.error(`[qqbot:${account.accountId}] Image file not found: ${imagePath}`);
-                            await sendErrorMessage(`图片文件不存在: ${imagePath}`);
-                            continue;
-                          }
-                          
-                          // 文件大小校验
-                          const imgSizeCheck = checkFileSize(imagePath);
-                          if (!imgSizeCheck.ok) {
-                            log?.error(`[qqbot:${account.accountId}] ${imgSizeCheck.error}`);
-                            await sendErrorMessage(imgSizeCheck.error!);
-                            continue;
-                          }
-                          
-                          // 大文件进度提示
-                          if (isLargeFile(imgSizeCheck.size)) {
-                            try {
-                              await sendWithTokenRetry(async (token) => {
-                                const hint = `⏳ 正在上传图片 (${formatFileSize(imgSizeCheck.size)})...`;
-                                if (event.type === "c2c") {
-                                  await sendC2CMessage(token, event.senderId, hint, event.messageId);
-                                } else if (event.type === "group" && event.groupOpenid) {
-                                  await sendGroupMessage(token, event.groupOpenid, hint, event.messageId);
-                                }
-                              });
-                            } catch {}
-                          }
-                          
-                          const fileBuffer = await readFileAsync(imagePath);
-                          const base64Data = fileBuffer.toString("base64");
-                          const ext = path.extname(imagePath).toLowerCase();
-                          const mimeTypes: Record<string, string> = {
-                            ".jpg": "image/jpeg",
-                            ".jpeg": "image/jpeg",
-                            ".png": "image/png",
-                            ".gif": "image/gif",
-                            ".webp": "image/webp",
-                            ".bmp": "image/bmp",
-                          };
-                          const mimeType = mimeTypes[ext];
-                          if (!mimeType) {
-                            log?.error(`[qqbot:${account.accountId}] Unsupported image format: ${ext}`);
-                            await sendErrorMessage(`不支持的图片格式: ${ext}`);
-                            continue;
-                          }
-                          imageUrl = `data:${mimeType};base64,${base64Data}`;
-                          log?.info(`[qqbot:${account.accountId}] Converted local image to Base64 (size: ${formatFileSize(fileBuffer.length)})`);
-                        } else if (!isHttpUrl) {
-                          log?.error(`[qqbot:${account.accountId}] Invalid image path (not local or URL): ${imagePath}`);
-                          continue;
-                        }
-                        
-                        // 发送图片（传递原始本地路径以便 refIdx 缓存记录来源）
-                        const imgLocalPath = isLocalPath ? imagePath : undefined;
-                        await sendWithTokenRetry(async (token) => {
-                          if (event.type === "c2c") {
-                            await sendC2CImageMessage(token, event.senderId, imageUrl, event.messageId, undefined, imgLocalPath);
-                          } else if (event.type === "group" && event.groupOpenid) {
-                            await sendGroupImageMessage(token, event.groupOpenid, imageUrl, event.messageId);
-                          } else if (event.channelId) {
-                            // 频道使用 Markdown 格式（如果是公网 URL）
-                            if (isHttpUrl) {
-                              await sendChannelMessage(token, event.channelId, `![](${imagePath})`, event.messageId);
-                            } else {
-                              // 频道不支持富媒体 Base64
-                              log?.info(`[qqbot:${account.accountId}] Channel does not support rich media for local images`);
-                            }
-                          }
-                        });
-                        log?.info(`[qqbot:${account.accountId}] Sent image via <qqimg> tag: ${imagePath.slice(0, 60)}...`);
-                      } catch (err) {
-                        log?.error(`[qqbot:${account.accountId}] Failed to send image from <qqimg>: ${err}`);
-                        await sendErrorMessage(`图片发送失败，图片似乎不存在哦，图片路径：${imagePath}`);
+                      const result = await sendPhoto(mediaTarget, item.content);
+                      if (result.error) {
+                        log?.error(`[qqbot:${account.accountId}] sendPhoto error: ${result.error}`);
+                        await sendErrorMessage(formatMediaErrorMessage("图片", new Error(result.error)));
                       }
                     } else if (item.type === "voice") {
-                      // 发送语音文件（展开 ~ 路径）
-                      const voicePath = normalizePath(item.content);
+                      const uploadFormats = account.config?.audioFormatPolicy?.uploadDirectFormats ?? account.config?.voiceDirectUploadFormats;
+                      const transcodeEnabled = account.config?.audioFormatPolicy?.transcodeEnabled !== false;
+                      // 语音发送加外层超时保护，避免阻塞后续发送队列
+                      const voiceTimeout = 45000; // 45 秒（waitForFile 30s + 转码/上传 15s）
                       try {
-                        // 等待文件就绪（TTS 工具异步生成，文件可能还没写完）
-                        const fileSize = await waitForFile(voicePath);
-                        if (fileSize === 0) {
-                          log?.error(`[qqbot:${account.accountId}] Voice file not ready after waiting: ${voicePath}`);
-                          await sendErrorMessage(`语音生成失败，请稍后重试`);
-                          continue;
+                        const result = await Promise.race([
+                          sendVoice(mediaTarget, item.content, uploadFormats, transcodeEnabled),
+                          new Promise<{ channel: string; error: string }>((resolve) =>
+                            setTimeout(() => resolve({ channel: "qqbot", error: "语音发送超时，已跳过" }), voiceTimeout)
+                          ),
+                        ]);
+                        if (result.error) {
+                          log?.error(`[qqbot:${account.accountId}] sendVoice error: ${result.error}`);
+                          await sendErrorMessage(formatMediaErrorMessage("语音", new Error(result.error)));
                         }
-
-                        // 转换为 SILK 格式（QQ Bot API 语音只支持 SILK），支持配置直传格式跳过转换
-                        const uploadFormats = account.config?.audioFormatPolicy?.uploadDirectFormats ?? account.config?.voiceDirectUploadFormats;
-                        const silkBase64 = await audioFileToSilkBase64(voicePath, uploadFormats);
-                        if (!silkBase64) {
-                          const ext = path.extname(voicePath).toLowerCase();
-                          log?.error(`[qqbot:${account.accountId}] Voice conversion to SILK failed: ${ext} (${fileSize} bytes). Check [audio-convert] logs for details.`);
-                          await sendErrorMessage(`语音格式转换失败，请稍后重试`);
-                          continue;
-                        }
-                        log?.info(`[qqbot:${account.accountId}] Voice file converted to SILK Base64 (${fileSize} bytes)`);
-
-                        await sendWithTokenRetry(async (token) => {
-                          if (event.type === "c2c") {
-                            await sendC2CVoiceMessage(token, event.senderId, silkBase64!, event.messageId, undefined, voicePath);
-                          } else if (event.type === "group" && event.groupOpenid) {
-                            await sendGroupVoiceMessage(token, event.groupOpenid, silkBase64!, event.messageId);
-                          } else if (event.channelId) {
-                            await sendChannelMessage(token, event.channelId, `[语音消息暂不支持频道发送]`, event.messageId);
-                          }
-                        });
-                        log?.info(`[qqbot:${account.accountId}] Sent voice via <qqvoice> tag: ${voicePath.slice(0, 60)}...`);
                       } catch (err) {
-                        log?.error(`[qqbot:${account.accountId}] Failed to send voice from <qqvoice>: ${err}`);
+                        log?.error(`[qqbot:${account.accountId}] sendVoice unexpected error: ${err}`);
                         await sendErrorMessage(formatMediaErrorMessage("语音", err));
                       }
                     } else if (item.type === "video") {
-                      // 发送视频（支持公网 URL 和本地文件，展开 ~ 路径）
-                      const videoPath = normalizePath(item.content);
-                      try {
-                        const isHttpUrl = videoPath.startsWith("http://") || videoPath.startsWith("https://");
-
-                        // 本地视频大文件进度提示
-                        if (!isHttpUrl) {
-                          const vidCheck = checkFileSize(videoPath);
-                          if (vidCheck.ok && isLargeFile(vidCheck.size)) {
-                            try {
-                              await sendWithTokenRetry(async (token) => {
-                                const hint = `⏳ 正在上传视频 (${formatFileSize(vidCheck.size)})...`;
-                                if (event.type === "c2c") {
-                                  await sendC2CMessage(token, event.senderId, hint, event.messageId);
-                                } else if (event.type === "group" && event.groupOpenid) {
-                                  await sendGroupMessage(token, event.groupOpenid, hint, event.messageId);
-                                }
-                              });
-                            } catch {}
-                          }
-                        }
-
-                        await sendWithTokenRetry(async (token) => {
-                          if (isHttpUrl) {
-                            // 公网 URL
-                            if (event.type === "c2c") {
-                              await sendC2CVideoMessage(token, event.senderId, videoPath, undefined, event.messageId);
-                            } else if (event.type === "group" && event.groupOpenid) {
-                              await sendGroupVideoMessage(token, event.groupOpenid, videoPath, undefined, event.messageId);
-                            } else if (event.channelId) {
-                              await sendChannelMessage(token, event.channelId, `[视频消息暂不支持频道发送]`, event.messageId);
-                            }
-                          } else {
-                            // 本地文件：读取为 Base64
-                            if (!(await fileExistsAsync(videoPath))) {
-                              throw new Error(`视频文件不存在: ${videoPath}`);
-                            }
-                            // 文件大小校验
-                            const vidSizeCheck = checkFileSize(videoPath);
-                            if (!vidSizeCheck.ok) {
-                              throw new Error(vidSizeCheck.error!);
-                            }
-                            const fileBuffer = await readFileAsync(videoPath);
-                            const videoBase64 = fileBuffer.toString("base64");
-                            log?.info(`[qqbot:${account.accountId}] Read local video (${formatFileSize(fileBuffer.length)}): ${videoPath}`);
-
-                            if (event.type === "c2c") {
-                              await sendC2CVideoMessage(token, event.senderId, undefined, videoBase64, event.messageId, undefined, videoPath);
-                            } else if (event.type === "group" && event.groupOpenid) {
-                              await sendGroupVideoMessage(token, event.groupOpenid, undefined, videoBase64, event.messageId);
-                            } else if (event.channelId) {
-                              await sendChannelMessage(token, event.channelId, `[视频消息暂不支持频道发送]`, event.messageId);
-                            }
-                          }
-                        });
-                        log?.info(`[qqbot:${account.accountId}] Sent video via <qqvideo> tag: ${videoPath.slice(0, 60)}...`);
-                      } catch (err) {
-                        log?.error(`[qqbot:${account.accountId}] Failed to send video from <qqvideo>: ${err}`);
-                        await sendErrorMessage(formatMediaErrorMessage("视频", err));
+                      const result = await sendVideoMsg(mediaTarget, item.content);
+                      if (result.error) {
+                        log?.error(`[qqbot:${account.accountId}] sendVideoMsg error: ${result.error}`);
+                        await sendErrorMessage(formatMediaErrorMessage("视频", new Error(result.error)));
                       }
                     } else if (item.type === "file") {
-                      // 发送文件（展开 ~ 路径）
-                      const filePath = normalizePath(item.content);
-                      try {
-                        const isHttpUrl = filePath.startsWith("http://") || filePath.startsWith("https://");
-                        const fileName = sanitizeFileName(path.basename(filePath));
-
-                        // 本地文件大文件进度提示
-                        if (!isHttpUrl) {
-                          const fileCheck = checkFileSize(filePath);
-                          if (fileCheck.ok && isLargeFile(fileCheck.size)) {
-                            try {
-                              await sendWithTokenRetry(async (token) => {
-                                const hint = `⏳ 正在上传文件 ${fileName} (${formatFileSize(fileCheck.size)})...`;
-                                if (event.type === "c2c") {
-                                  await sendC2CMessage(token, event.senderId, hint, event.messageId);
-                                } else if (event.type === "group" && event.groupOpenid) {
-                                  await sendGroupMessage(token, event.groupOpenid, hint, event.messageId);
-                                }
-                              });
-                            } catch {}
-                          }
-                        }
-
-                        await sendWithTokenRetry(async (token) => {
-                          if (isHttpUrl) {
-                            // 公网 URL
-                            if (event.type === "c2c") {
-                              await sendC2CFileMessage(token, event.senderId, undefined, filePath, event.messageId, fileName);
-                            } else if (event.type === "group" && event.groupOpenid) {
-                              await sendGroupFileMessage(token, event.groupOpenid, undefined, filePath, event.messageId, fileName);
-                            } else if (event.channelId) {
-                              await sendChannelMessage(token, event.channelId, `[文件消息暂不支持频道发送]`, event.messageId);
-                            }
-                          } else {
-                            // 本地文件
-                            if (!(await fileExistsAsync(filePath))) {
-                              throw new Error(`文件不存在: ${filePath}`);
-                            }
-                            // 文件大小校验
-                            const flSizeCheck = checkFileSize(filePath);
-                            if (!flSizeCheck.ok) {
-                              throw new Error(flSizeCheck.error!);
-                            }
-                            const fileBuffer = await readFileAsync(filePath);
-                            const fileBase64 = fileBuffer.toString("base64");
-                            log?.info(`[qqbot:${account.accountId}] Read local file (${formatFileSize(fileBuffer.length)}): ${filePath}`);
-
-                            if (event.type === "c2c") {
-                              await sendC2CFileMessage(token, event.senderId, fileBase64, undefined, event.messageId, fileName, filePath);
-                            } else if (event.type === "group" && event.groupOpenid) {
-                              await sendGroupFileMessage(token, event.groupOpenid, fileBase64, undefined, event.messageId, fileName);
-                            } else if (event.channelId) {
-                              await sendChannelMessage(token, event.channelId, `[文件消息暂不支持频道发送]`, event.messageId);
-                            }
-                          }
-                        });
-                        log?.info(`[qqbot:${account.accountId}] Sent file via <qqfile> tag: ${filePath.slice(0, 60)}...`);
-                      } catch (err) {
-                        log?.error(`[qqbot:${account.accountId}] Failed to send file from <qqfile>: ${err}`);
-                        await sendErrorMessage(`文件发送失败: ${err}`);
+                      const result = await sendDocument(mediaTarget, item.content);
+                      if (result.error) {
+                        log?.error(`[qqbot:${account.accountId}] sendDocument error: ${result.error}`);
+                        await sendErrorMessage(formatMediaErrorMessage("文件", new Error(result.error)));
+                      }
+                    } else if (item.type === "media") {
+                      // qqmedia: 自动根据扩展名路由到 sendPhoto/sendVoice/sendVideoMsg/sendDocument
+                      const result = await sendMediaAuto({
+                        to: qualifiedTarget,
+                        text: "",
+                        mediaUrl: item.content,
+                        accountId: account.accountId,
+                        replyToId: event.messageId,
+                        account,
+                      });
+                      if (result.error) {
+                        log?.error(`[qqbot:${account.accountId}] sendMedia(auto) error: ${result.error}`);
+                        await sendErrorMessage(formatMediaErrorMessage("媒体", new Error(result.error)));
                       }
                     }
                   }
@@ -1755,7 +1712,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   if (payloadResult.error) {
                     // 载荷解析失败，发送错误提示
                     log?.error(`[qqbot:${account.accountId}] Payload parse error: ${payloadResult.error}`);
-                    await sendErrorMessage(`[QQBot] 载荷解析失败: ${payloadResult.error}`);
+                    await sendErrorMessage(MSG.PAYLOAD_PARSE_ERROR);
                     return;
                   }
                   
@@ -1808,12 +1765,12 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                         if (parsedPayload.source === "file") {
                           try {
                             if (!(await fileExistsAsync(imageUrl))) {
-                              await sendErrorMessage(`[QQBot] 图片文件不存在: ${imageUrl}`);
+                              await sendErrorMessage(MSG.IMAGE_NOT_FOUND);
                               return;
                             }
                             const imgSzCheck = checkFileSize(imageUrl);
                             if (!imgSzCheck.ok) {
-                              await sendErrorMessage(`[QQBot] ${imgSzCheck.error}`);
+                              await sendErrorMessage(MSG.IMAGE_SEND_FAILED);
                               return;
                             }
                             const fileBuffer = await readFileAsync(imageUrl);
@@ -1829,14 +1786,14 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                             };
                             const mimeType = mimeTypes[ext];
                             if (!mimeType) {
-                              await sendErrorMessage(`[QQBot] 不支持的图片格式: ${ext}`);
+                              await sendErrorMessage(MSG.IMAGE_FORMAT_UNSUPPORTED(ext));
                               return;
                             }
                             imageUrl = `data:${mimeType};base64,${base64Data}`;
                             log?.info(`[qqbot:${account.accountId}] Converted local image to Base64 (size: ${formatFileSize(fileBuffer.length)})`);
                           } catch (readErr) {
                             log?.error(`[qqbot:${account.accountId}] Failed to read local image: ${readErr}`);
-                            await sendErrorMessage(`[QQBot] 读取图片文件失败: ${readErr}`);
+                            await sendErrorMessage(MSG.IMAGE_SEND_FAILED);
                             return;
                           }
                         }
@@ -1875,13 +1832,13 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                         // TTS 语音发送：文字 → PCM → SILK → QQ 语音
                         try {
                           const ttsText = parsedPayload.caption || parsedPayload.path;
-                          if (!ttsText?.trim()) {
-                            await sendErrorMessage(`[QQBot] 语音消息缺少文本内容`);
-                          } else {
-                            const ttsCfg = resolveTTSConfig(cfg as Record<string, unknown>);
-                            if (!ttsCfg) {
-                              log?.error(`[qqbot:${account.accountId}] TTS not configured (channels.qqbot.tts in openclaw.json)`);
-                              await sendErrorMessage(`[QQBot] TTS 未配置，请在 openclaw.json 的 channels.qqbot.tts 中配置`);
+                            if (!ttsText?.trim()) {
+                              await sendErrorMessage(MSG.VOICE_MISSING_TEXT);
+                            } else {
+                              const ttsCfg = resolveTTSConfig(cfg as Record<string, unknown>);
+                              if (!ttsCfg) {
+                                log?.error(`[qqbot:${account.accountId}] TTS not configured (channels.qqbot.tts in openclaw.json)`);
+                                await sendErrorMessage(MSG.VOICE_NOT_AVAILABLE);
                             } else {
                               log?.info(`[qqbot:${account.accountId}] TTS: "${ttsText.slice(0, 50)}..." via ${ttsCfg.model}`);
                               const ttsDir = getQQBotDataDir("tts");
@@ -1894,7 +1851,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                                 } else if (event.type === "group" && event.groupOpenid) {
                                   await sendGroupVoiceMessage(token, event.groupOpenid, silkBase64, event.messageId);
                                 } else if (event.channelId) {
-                                  await sendChannelMessage(token, event.channelId, `[语音消息暂不支持频道发送] ${ttsText}`, event.messageId);
+                                  await sendChannelMessage(token, event.channelId, `${MSG.VOICE_CHANNEL_UNSUPPORTED}\n${ttsText}`, event.messageId);
                                 }
                               });
                               log?.info(`[qqbot:${account.accountId}] Voice message sent`);
@@ -1902,14 +1859,14 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                           }
                         } catch (err) {
                           log?.error(`[qqbot:${account.accountId}] TTS/voice send failed: ${err}`);
-                          await sendErrorMessage(`[QQBot] 语音发送失败: ${err}`);
+                          await sendErrorMessage(formatMediaErrorMessage("语音", err));
                         }
                       } else if (parsedPayload.mediaType === "video") {
                         // 视频发送：支持公网 URL 和本地文件
                         try {
                           const videoPath = normalizePath(parsedPayload.path ?? "");
                           if (!videoPath?.trim()) {
-                            await sendErrorMessage(`[QQBot] 视频消息缺少视频路径`);
+                            await sendErrorMessage(MSG.VIDEO_MISSING_PATH);
                           } else {
                             const isHttpUrl = videoPath.startsWith("http://") || videoPath.startsWith("https://");
                             log?.info(`[qqbot:${account.accountId}] Video send: "${videoPath.slice(0, 60)}..."`);
@@ -1922,7 +1879,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                                 } else if (event.type === "group" && event.groupOpenid) {
                                   await sendGroupVideoMessage(token, event.groupOpenid, videoPath, undefined, event.messageId);
                                 } else if (event.channelId) {
-                                  await sendChannelMessage(token, event.channelId, `[视频消息暂不支持频道发送]`, event.messageId);
+                                  await sendChannelMessage(token, event.channelId, MSG.VIDEO_CHANNEL_UNSUPPORTED, event.messageId);
                                 }
                               } else {
                                 // 本地文件：读取为 Base64
@@ -1942,7 +1899,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                                 } else if (event.type === "group" && event.groupOpenid) {
                                   await sendGroupVideoMessage(token, event.groupOpenid, undefined, videoBase64, event.messageId);
                                 } else if (event.channelId) {
-                                  await sendChannelMessage(token, event.channelId, `[视频消息暂不支持频道发送]`, event.messageId);
+                                  await sendChannelMessage(token, event.channelId, MSG.VIDEO_CHANNEL_UNSUPPORTED, event.messageId);
                                 }
                               }
                             });
@@ -1970,7 +1927,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                         try {
                           const filePath = normalizePath(parsedPayload.path ?? "");
                           if (!filePath?.trim()) {
-                            await sendErrorMessage(`[QQBot] 文件消息缺少文件路径`);
+                            await sendErrorMessage(MSG.FILE_MISSING_PATH);
                           } else {
                             const isHttpUrl = filePath.startsWith("http://") || filePath.startsWith("https://");
                             const fileName = sanitizeFileName(path.basename(filePath));
@@ -1983,7 +1940,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                                 } else if (event.type === "group" && event.groupOpenid) {
                                   await sendGroupFileMessage(token, event.groupOpenid, undefined, filePath, event.messageId, fileName);
                                 } else if (event.channelId) {
-                                  await sendChannelMessage(token, event.channelId, `[文件消息暂不支持频道发送]`, event.messageId);
+                                  await sendChannelMessage(token, event.channelId, MSG.FILE_CHANNEL_UNSUPPORTED, event.messageId);
                                 }
                               } else {
                                 if (!(await fileExistsAsync(filePath))) {
@@ -2000,7 +1957,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                                 } else if (event.type === "group" && event.groupOpenid) {
                                   await sendGroupFileMessage(token, event.groupOpenid, fileBase64, undefined, event.messageId, fileName);
                                 } else if (event.channelId) {
-                                  await sendChannelMessage(token, event.channelId, `[文件消息暂不支持频道发送]`, event.messageId);
+                                  await sendChannelMessage(token, event.channelId, MSG.FILE_CHANNEL_UNSUPPORTED, event.messageId);
                                 }
                               }
                             });
@@ -2012,7 +1969,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                         }
                       } else {
                         log?.error(`[qqbot:${account.accountId}] Unknown media type: ${(parsedPayload as MediaPayload).mediaType}`);
-                        await sendErrorMessage(`[QQBot] 不支持的媒体类型: ${(parsedPayload as MediaPayload).mediaType}`);
+                        await sendErrorMessage(MSG.UNSUPPORTED_MEDIA_TYPE);
                       }
                       
                       // 记录活动并返回
@@ -2025,20 +1982,20 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                     } else {
                       // 未知的载荷类型
                       log?.error(`[qqbot:${account.accountId}] Unknown payload type: ${(parsedPayload as any).type}`);
-                      await sendErrorMessage(`[QQBot] 不支持的载荷类型: ${(parsedPayload as any).type}`);
+                      await sendErrorMessage(MSG.UNSUPPORTED_PAYLOAD_TYPE);
                       return;
                     }
                   }
                 }
                 
                 // ============ 非结构化消息：简化处理 ============
-                // 📝 设计原则：JSON payload (QQBOT_PAYLOAD) 是发送本地图片的唯一方式
-                // 非结构化消息只处理：公网 URL (http/https) 和 Base64 Data URL
                 const imageUrls: string[] = [];
+                const localMediaToSend: string[] = []; // 本地路径走 sendMedia 自动路由
                 
                 /**
-                 * 检查并收集图片 URL（仅支持公网 URL 和 Base64 Data URL）
-                 * ⚠️ 本地文件路径必须使用 QQBOT_PAYLOAD JSON 格式发送
+                 * 收集媒体 URL/路径
+                 * - 公网 URL / Base64 Data URL → 图片处理管线
+                 * - 本地文件路径 → sendMedia 自动路由（根据扩展名识别类型）
                  */
                 const collectImageUrl = (url: string | undefined | null): boolean => {
                   if (!url) return false;
@@ -2058,24 +2015,13 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                     return true;
                   }
                   
-                  // ⚠️ 本地文件路径不再在此处处理，应使用对应的 <qqXXX> 标签
+                  // 本地文件路径：走 sendMedia 自动路由
                   if (isLocalFilePath(url)) {
-                    const ext = path.extname(url).toLowerCase();
-                    const VIDEO_EXTS = [".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".wmv"];
-                    let suggestedTag = "qqimg";
-                    let mediaDesc = "图片";
-                    if (isAudioFile(url)) {
-                      suggestedTag = "qqvoice";
-                      mediaDesc = "语音";
-                    } else if (VIDEO_EXTS.includes(ext)) {
-                      suggestedTag = "qqvideo";
-                      mediaDesc = "视频";
-                    } else if (![".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"].includes(ext)) {
-                      suggestedTag = "qqfile";
-                      mediaDesc = "文件";
+                    if (!localMediaToSend.includes(url)) {
+                      localMediaToSend.push(url);
+                      log?.info(`[qqbot:${account.accountId}] Collected local media for auto-routing: ${url}`);
                     }
-                    log?.info(`[qqbot:${account.accountId}] 💡 Local path detected in non-structured message (not sending): ${url}`);
-                    log?.info(`[qqbot:${account.accountId}] 💡 Hint: Use <${suggestedTag}>${url}</${suggestedTag}> tag to send local ${mediaDesc}`);
+                    return true;
                   }
                   return false;
                 };
@@ -2101,24 +2047,12 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                       // 公网 URL：收集并处理
                       imageUrls.push(url);
                       log?.info(`[qqbot:${account.accountId}] Extracted HTTP image from markdown: ${url.slice(0, 80)}...`);
-                    } else if (looksLikeLocalPath(url)) {
-                      // 本地路径：根据文件类型给出正确的标签提示
-                      const ext = path.extname(url).toLowerCase();
-                      const VIDEO_EXTS = [".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".wmv"];
-                      let suggestedTag = "qqimg";
-                      let mediaDesc = "图片";
-                      if (isAudioFile(url)) {
-                        suggestedTag = "qqvoice";
-                        mediaDesc = "语音";
-                      } else if (VIDEO_EXTS.includes(ext)) {
-                        suggestedTag = "qqvideo";
-                        mediaDesc = "视频";
-                      } else if (![".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"].includes(ext)) {
-                        suggestedTag = "qqfile";
-                        mediaDesc = "文件";
+                    } else if (isLocalFilePath(url)) {
+                      // 本地路径：走 sendMedia 自动路由
+                      if (!localMediaToSend.includes(url)) {
+                        localMediaToSend.push(url);
+                        log?.info(`[qqbot:${account.accountId}] Collected local media from markdown for auto-routing: ${url}`);
                       }
-                      log?.info(`[qqbot:${account.accountId}] 💡 Local path detected in non-structured message (not sending): ${url}`);
-                      log?.info(`[qqbot:${account.accountId}] 💡 Hint: Use <${suggestedTag}>${url}</${suggestedTag}> tag to send local ${mediaDesc}`);
                     }
                   }
                 }
@@ -2267,7 +2201,14 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                     }
                   }
                 } else {
-                  // ============ 普通文本模式：使用富媒体 API 发送图片 ============
+                  // ============ 普通文本模式：使用 sendPhoto 发送图片（内置 URL fallback） ============
+                  const imgMediaTarget: MediaTargetContext = {
+                    targetType: event.type === "c2c" ? "c2c" : event.type === "group" ? "group" : "channel",
+                    targetId: event.type === "c2c" ? event.senderId : event.type === "group" ? event.groupOpenid! : event.channelId!,
+                    account,
+                    replyToId: event.messageId,
+                    logPrefix: `[qqbot:${account.accountId}]`,
+                  };
                   // 从文本中移除所有图片相关内容
                   for (const match of mdMatches) {
                     textWithoutImages = textWithoutImages.replace(match[0], "").trim();
@@ -2282,20 +2223,15 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   }
                   
                   try {
-                    // 发送图片（通过富媒体 API）
+                    // 发送图片（通过 sendPhoto，内置 URL 直传 → 下载 fallback）
                     for (const imageUrl of imageUrls) {
                       try {
-                        await sendWithTokenRetry(async (token) => {
-                          if (event.type === "c2c") {
-                            await sendC2CImageMessage(token, event.senderId, imageUrl, event.messageId);
-                          } else if (event.type === "group" && event.groupOpenid) {
-                            await sendGroupImageMessage(token, event.groupOpenid, imageUrl, event.messageId);
-                          } else if (event.channelId) {
-                            // 频道暂不支持富媒体，发送文本 URL
-                            await sendChannelMessage(token, event.channelId, imageUrl, event.messageId);
-                          }
-                        });
-                        log?.info(`[qqbot:${account.accountId}] Sent image via media API: ${imageUrl.slice(0, 80)}...`);
+                        const imgResult = await sendPhoto(imgMediaTarget, imageUrl);
+                        if (imgResult.error) {
+                          log?.error(`[qqbot:${account.accountId}] Failed to send image: ${imgResult.error}`);
+                        } else {
+                          log?.info(`[qqbot:${account.accountId}] Sent image via sendPhoto: ${imageUrl.slice(0, 80)}...`);
+                        }
                       } catch (imgErr) {
                         log?.error(`[qqbot:${account.accountId}] Failed to send image: ${imgErr}`);
                       }
@@ -2320,6 +2256,58 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   }
                 }
 
+                // 发送 localMediaToSend 中收集到的本地媒体（由 payload.mediaUrl 或 markdown 本地路径触发）
+                if (localMediaToSend.length > 0) {
+                  log?.info(`[qqbot:${account.accountId}] Sending ${localMediaToSend.length} local media via sendMedia auto-routing`);
+                  for (const mediaPath of localMediaToSend) {
+                    try {
+                      const result = await sendMediaAuto({
+                        to: qualifiedTarget,
+                        text: "",
+                        mediaUrl: mediaPath,
+                        accountId: account.accountId,
+                        replyToId: event.messageId,
+                        account,
+                      });
+                      if (result.error) {
+                        log?.error(`[qqbot:${account.accountId}] sendMedia(auto) error for ${mediaPath}: ${result.error}`);
+                      } else {
+                        log?.info(`[qqbot:${account.accountId}] Sent local media: ${mediaPath}`);
+                      }
+                    } catch (err) {
+                      log?.error(`[qqbot:${account.accountId}] sendMedia(auto) failed for ${mediaPath}: ${err}`);
+                    }
+                  }
+                }
+
+                // ============ 转发 tool 阶段收集的媒体（TTS 语音、生成图片等） ============
+                // block 回复已发送，但 tool deliver 阶段收集的媒体 URL 未被发送（tool deliver 只收集不发送）。
+                // 此处主动转发，避免工具产出的媒体被静默丢弃。
+                if (toolMediaUrls.length > 0) {
+                  log?.info(`[qqbot:${account.accountId}] Forwarding ${toolMediaUrls.length} tool-collected media URL(s) after block deliver`);
+                  for (const mediaUrl of toolMediaUrls) {
+                    try {
+                      const result = await sendMediaAuto({
+                        to: qualifiedTarget,
+                        text: "",
+                        mediaUrl,
+                        accountId: account.accountId,
+                        replyToId: event.messageId,
+                        account,
+                      });
+                      if (result.error) {
+                        log?.error(`[qqbot:${account.accountId}] Tool media forward error: ${result.error}`);
+                      } else {
+                        log?.info(`[qqbot:${account.accountId}] Forwarded tool media: ${mediaUrl.slice(0, 80)}...`);
+                      }
+                    } catch (err) {
+                      log?.error(`[qqbot:${account.accountId}] Tool media forward failed: ${err}`);
+                    }
+                  }
+                  // 清空已转发的 URL，避免 tool-only 兜底重复发送
+                  toolMediaUrls.length = 0;
+                }
+
                 pluginRuntime.channel.activity.record({
                   channel: "qqbot",
                   accountId: account.accountId,
@@ -2337,9 +2325,9 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                 // 发送错误提示给用户，显示完整错误信息
                 const errMsg = String(err);
                 if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
-                  await sendErrorMessage("⚠️ AI 服务认证失败，API Key 可能无效，请联系管理员检查配置。");
+                  await sendErrorMessage(MSG.AI_AUTH_ERROR);
                 } else {
-                  await sendErrorMessage(`⚠️ AI 处理出错: ${errMsg.slice(0, 500)}`);
+                  await sendErrorMessage(MSG.AI_PROCESS_ERROR);
                 }
               },
             },
@@ -2357,7 +2345,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
             }
             if (!hasResponse) {
               log?.error(`[qqbot:${account.accountId}] No response within timeout`);
-              await sendErrorMessage("⏳ 已收到，正在处理中…");
+              await sendErrorMessage(MSG.TIMEOUT_HINT);
             }
           } finally {
             // 清理 tool-only 兜底定时器
@@ -2369,13 +2357,12 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
             if (toolDeliverCount > 0 && !hasBlockResponse && !toolFallbackSent) {
               toolFallbackSent = true;
               log?.error(`[qqbot:${account.accountId}] Dispatch completed with ${toolDeliverCount} tool deliver(s) but no block deliver, sending fallback`);
-              const fallback = formatToolFallback();
-              await sendErrorMessage(fallback);
+              await sendToolFallback();
             }
           }
         } catch (err) {
           log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
-          await sendErrorMessage(`⚠️ 消息处理失败: ${String(err).slice(0, 500)}`);
+          await sendErrorMessage(MSG.GENERIC_ERROR);
         }
       };
 
@@ -2406,7 +2393,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                 sessionId,
                 lastSeq,
                 lastConnectedAt: lastConnectTime,
-                intentLevelIndex: lastSuccessfulIntentLevel >= 0 ? lastSuccessfulIntentLevel : intentLevelIndex,
+                intentLevelIndex: 0,
                 accountId: account.accountId,
                 savedAt: Date.now(),
                 appId: account.appId,
@@ -2432,16 +2419,13 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   },
                 }));
               } else {
-                // 新连接，发送 Identify
-                // 如果有上次成功的级别，直接使用；否则从当前级别开始尝试
-                const levelToUse = lastSuccessfulIntentLevel >= 0 ? lastSuccessfulIntentLevel : intentLevelIndex;
-                const intentLevel = INTENT_LEVELS[Math.min(levelToUse, INTENT_LEVELS.length - 1)];
-                log?.info(`[qqbot:${account.accountId}] Sending identify with intents: ${intentLevel.intents} (${intentLevel.description})`);
+                // 新连接，发送 Identify，始终使用完整权限
+                log?.info(`[qqbot:${account.accountId}] Sending identify with intents: ${FULL_INTENTS} (${FULL_INTENTS_DESC})`);
                 ws.send(JSON.stringify({
                   op: 2,
                   d: {
                     token: `QQBot ${accessToken}`,
-                    intents: intentLevel.intents,
+                    intents: FULL_INTENTS,
                     shard: [0, 1],
                   },
                 }));
@@ -2463,30 +2447,41 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
               if (t === "READY") {
                 const readyData = d as { session_id: string };
                 sessionId = readyData.session_id;
-                // 记录成功的权限级别
-                lastSuccessfulIntentLevel = intentLevelIndex;
-                const successLevel = INTENT_LEVELS[intentLevelIndex];
-                log?.info(`[qqbot:${account.accountId}] Ready with ${successLevel.description}, session: ${sessionId}`);
+                log?.info(`[qqbot:${account.accountId}] Ready with ${FULL_INTENTS_DESC}, session: ${sessionId}`);
                 // P1-2: 保存新的 Session 状态
                 saveSession({
                   sessionId,
                   lastSeq,
                   lastConnectedAt: Date.now(),
-                  intentLevelIndex,
+                  intentLevelIndex: 0,
                   accountId: account.accountId,
                   savedAt: Date.now(),
                   appId: account.appId,
                 });
                 onReady?.(d);
+
+                // 仅 startGateway 后的首次 READY 才发送上线通知
+                // ws 断线重连（resume 失败后重新 Identify）产生的 READY 不发送
+                if (!isFirstReadyGlobal) {
+                  log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (reconnect READY, not first startup)`);
+                } else {
+                  isFirstReadyGlobal = false;
+                  sendStartupGreetings("READY");
+                } // end isFirstReady
               } else if (t === "RESUMED") {
                 log?.info(`[qqbot:${account.accountId}] Session resumed`);
+                // RESUMED 也属于首次启动（gateway restart 通常走 resume）
+                if (isFirstReadyGlobal) {
+                  isFirstReadyGlobal = false;
+                  sendStartupGreetings("RESUMED");
+                }
                 // P1-2: 更新 Session 连接时间
                 if (sessionId) {
                   saveSession({
                     sessionId,
                     lastSeq,
                     lastConnectedAt: Date.now(),
-                    intentLevelIndex: lastSuccessfulIntentLevel >= 0 ? lastSuccessfulIntentLevel : intentLevelIndex,
+                    intentLevelIndex: 0,
                     accountId: account.accountId,
                     savedAt: Date.now(),
                     appId: account.appId,
@@ -2502,8 +2497,8 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                 });
                 // 解析引用索引
                 const c2cRefs = parseRefIndices(event.message_scene?.ext);
-                // 使用消息队列异步处理，防止阻塞心跳
-                enqueueMessage({
+                // 斜杠指令拦截 → 不匹配则入队
+                trySlashCommandOrEnqueue({
                   type: "c2c",
                   senderId: event.author.user_openid,
                   content: event.content,
@@ -2523,7 +2518,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   accountId: account.accountId,
                 });
                 const guildRefs = parseRefIndices((event as any).message_scene?.ext);
-                enqueueMessage({
+                trySlashCommandOrEnqueue({
                   type: "guild",
                   senderId: event.author.id,
                   senderName: event.author.username,
@@ -2546,7 +2541,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   accountId: account.accountId,
                 });
                 const dmRefs = parseRefIndices((event as any).message_scene?.ext);
-                enqueueMessage({
+                trySlashCommandOrEnqueue({
                   type: "dm",
                   senderId: event.author.id,
                   senderName: event.author.username,
@@ -2568,7 +2563,7 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
                   accountId: account.accountId,
                 });
                 const groupRefs = parseRefIndices(event.message_scene?.ext);
-                enqueueMessage({
+                trySlashCommandOrEnqueue({
                   type: "group",
                   senderId: event.author.member_openid,
                   content: event.content,
@@ -2594,25 +2589,15 @@ ${ttsHint}${sttHint}${asrFallbackHint}${voiceForwardHint}`;
 
             case 9: // Invalid Session
               const canResume = d as boolean;
-              const currentLevel = INTENT_LEVELS[intentLevelIndex];
-              log?.error(`[qqbot:${account.accountId}] Invalid session (${currentLevel.description}), can resume: ${canResume}, raw: ${rawData}`);
+              log?.error(`[qqbot:${account.accountId}] Invalid session (${FULL_INTENTS_DESC}), can resume: ${canResume}, raw: ${rawData}`);
               
               if (!canResume) {
                 sessionId = null;
                 lastSeq = null;
                 // P1-2: 清除持久化的 Session
                 clearSession(account.accountId);
-                
-                // 尝试降级到下一个权限级别
-                if (intentLevelIndex < INTENT_LEVELS.length - 1) {
-                  intentLevelIndex++;
-                  const nextLevel = INTENT_LEVELS[intentLevelIndex];
-                  log?.info(`[qqbot:${account.accountId}] Downgrading intents to: ${nextLevel.description}`);
-                } else {
-                  // 已经是最低权限级别了
-                  log?.error(`[qqbot:${account.accountId}] All intent levels failed. Please check AppID/Secret.`);
-                  shouldRefreshToken = true;
-                }
+                shouldRefreshToken = true;
+                log?.info(`[qqbot:${account.accountId}] Will refresh token and retry with full intents (${FULL_INTENTS_DESC})`);
               }
               cleanup();
               // Invalid Session 后等待一段时间再重连