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

package/src/outbound.ts

@@ -21,10 +21,12 @@ import {
   sendC2CFileMessage,
   sendGroupFileMessage,
 } from "./api.js";
-import { isAudioFile, audioFileToSilkBase64, waitForFile } from "./utils/audio-convert.js";
+import { isAudioFile, audioFileToSilkBase64, waitForFile, shouldTranscodeVoice } from "./utils/audio-convert.js";
 import { normalizeMediaTags } from "./utils/media-tags.js";
 import { checkFileSize, readFileAsync, fileExistsAsync, isLargeFile, formatFileSize } from "./utils/file-utils.js";
-import { isLocalPath as isLocalFilePath, normalizePath, sanitizeFileName } from "./utils/platform.js";
+import { isLocalPath as isLocalFilePath, normalizePath, sanitizeFileName, getQQBotDataDir } from "./utils/platform.js";
+import { downloadFile } from "./image-server.js";
+import { MSG } from "./user-messages.js";
 
 // ============ 消息回复限流器 ============
 // 同一 message_id 1小时内最多回复 4 次，超过 1 小时无法被动回复（需改为主动消息）
@@ -163,6 +165,8 @@ export interface OutboundContext {
 
 export interface MediaOutboundContext extends OutboundContext {
   mediaUrl: string;
+  /** 可选的 MIME 类型，优先于扩展名判断媒体类型 */
+  mimeType?: string;
 }
 
 export interface OutboundResult {
@@ -233,6 +237,486 @@ function parseTarget(to: string): { type: "c2c" | "group" | "channel"; id: strin
   return { type: "c2c", id };
 }
 
+// ============ Telegram 风格的结构化媒体发送接口 ============
+// 类似 Telegram 的 sendPhoto / sendVoice / sendVideo / sendDocument，
+// 每种媒体类型一个独立函数，接收结构化参数，无需标签解析。
+// gateway.ts 的 deliver 回调和 sendText 共用这些函数，消除重复代码。
+
+/** 媒体发送的目标上下文（从 deliver 回调或 sendText 中提取） */
+export interface MediaTargetContext {
+  /** 目标类型 */
+  targetType: "c2c" | "group" | "channel";
+  /** 目标 ID */
+  targetId: string;
+  /** QQ Bot 账户配置 */
+  account: ResolvedQQBotAccount;
+  /** 被动回复消息 ID（可选） */
+  replyToId?: string;
+  /** 日志前缀（可选，用于区分调用来源） */
+  logPrefix?: string;
+}
+
+/** 从 OutboundContext 构建 MediaTargetContext */
+function buildMediaTarget(ctx: { to: string; account: ResolvedQQBotAccount; replyToId?: string | null }, logPrefix?: string): MediaTargetContext {
+  const target = parseTarget(ctx.to);
+  return {
+    targetType: target.type,
+    targetId: target.id,
+    account: ctx.account,
+    replyToId: ctx.replyToId ?? undefined,
+    logPrefix,
+  };
+}
+
+/** 获取已认证的 access token，失败时抛出异常 */
+async function getToken(account: ResolvedQQBotAccount): Promise<string> {
+  if (!account.appId || !account.clientSecret) {
+    throw new Error("QQBot not configured (missing appId or clientSecret)");
+  }
+  return getAccessToken(account.appId, account.clientSecret);
+}
+
+/** 判断是否应该对公网 URL 执行直传（不下载） */
+function shouldDirectUploadUrl(account: ResolvedQQBotAccount): boolean {
+  return account.config?.urlDirectUpload !== false; // 默认 true
+}
+
+/**
+ * sendPhoto — 发送图片消息（对齐 Telegram sendPhoto）
+ * 
+ * 支持三种来源：
+ * - 本地文件路径（自动读取转 Base64）
+ * - 公网 HTTP/HTTPS URL（urlDirectUpload=true 时先直传平台，失败自动下载重试；=false 时直接下载）
+ * - Base64 Data URL
+ */
+export async function sendPhoto(
+  ctx: MediaTargetContext,
+  imagePath: string,
+): Promise<OutboundResult> {
+  const prefix = ctx.logPrefix ?? "[qqbot]";
+  const mediaPath = normalizePath(imagePath);
+  const isLocal = isLocalFilePath(mediaPath);
+  const isHttp = mediaPath.startsWith("http://") || mediaPath.startsWith("https://");
+  const isData = mediaPath.startsWith("data:");
+
+  // urlDirectUpload=false 时，公网 URL 直接下载到本地再发送
+  if (isHttp && !shouldDirectUploadUrl(ctx.account)) {
+    console.log(`${prefix} sendPhoto: urlDirectUpload=false, downloading URL first...`);
+    const localFile = await downloadToFallbackDir(mediaPath, prefix, "sendPhoto");
+    if (localFile) {
+      return await sendPhoto(ctx, localFile);
+    }
+    return { channel: "qqbot", error: `下载失败: ${mediaPath.slice(0, 80)}` };
+  }
+
+  let imageUrl = mediaPath;
+
+  if (isLocal) {
+    if (!(await fileExistsAsync(mediaPath))) {
+      return { channel: "qqbot", error: MSG.IMAGE_NOT_FOUND };
+    }
+    const sizeCheck = checkFileSize(mediaPath);
+    if (!sizeCheck.ok) {
+      return { channel: "qqbot", error: sizeCheck.error! };
+    }
+    const fileBuffer = await readFileAsync(mediaPath);
+    const ext = path.extname(mediaPath).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) {
+      return { channel: "qqbot", error: MSG.IMAGE_FORMAT_UNSUPPORTED(ext) };
+    }
+    imageUrl = `data:${mimeType};base64,${fileBuffer.toString("base64")}`;
+    console.log(`${prefix} sendPhoto: local → Base64 (${formatFileSize(fileBuffer.length)})`);
+  } else if (!isHttp && !isData) {
+    return { channel: "qqbot", error: `不支持的图片来源: ${mediaPath.slice(0, 50)}` };
+  }
+
+  try {
+    const token = await getToken(ctx.account);
+    const localPath = isLocal ? mediaPath : undefined;
+
+    if (ctx.targetType === "c2c") {
+      const r = await sendC2CImageMessage(token, ctx.targetId, imageUrl, ctx.replyToId, undefined, localPath);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    } else if (ctx.targetType === "group") {
+      const r = await sendGroupImageMessage(token, ctx.targetId, imageUrl, ctx.replyToId);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    } else {
+      // 频道：仅支持公网 URL（Markdown 格式）
+      if (isHttp) {
+        const r = await sendChannelMessage(token, ctx.targetId, `![](${mediaPath})`, ctx.replyToId);
+        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+      }
+      console.log(`${prefix} sendPhoto: channel does not support local/Base64 images`);
+      return { channel: "qqbot" };
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+
+    // 公网 URL 直传失败（如 QQ 平台拉取海外域名超时/被墙）→ 插件自己下载 → Base64 重试
+    if (isHttp && !isData) {
+      console.warn(`${prefix} sendPhoto: URL direct upload failed (${msg}), downloading locally and retrying as Base64...`);
+      const retryResult = await downloadAndRetrySendPhoto(ctx, mediaPath, prefix);
+      if (retryResult) return retryResult;
+    }
+
+    console.error(`${prefix} sendPhoto failed: ${msg}`);
+    return { channel: "qqbot", error: msg };
+  }
+}
+
+/**
+ * sendPhoto 的 URL fallback：下载远程图片到本地 → 转 Base64 → 重试发送
+ * 解决 QQ 开放平台无法拉取某些公网 URL（如海外域名）的问题
+ */
+async function downloadAndRetrySendPhoto(
+  ctx: MediaTargetContext,
+  httpUrl: string,
+  prefix: string,
+): Promise<OutboundResult | null> {
+  try {
+    const downloadDir = getQQBotDataDir("downloads", "url-fallback");
+    const localFile = await downloadFile(httpUrl, downloadDir);
+    if (!localFile) {
+      console.error(`${prefix} sendPhoto fallback: download also failed for ${httpUrl.slice(0, 80)}`);
+      return null;
+    }
+
+    console.log(`${prefix} sendPhoto fallback: downloaded → ${localFile}, retrying as Base64`);
+    // 递归调用 sendPhoto，此时走本地文件路径
+    return await sendPhoto(ctx, localFile);
+  } catch (err) {
+    console.error(`${prefix} sendPhoto fallback error:`, err);
+    return null;
+  }
+}
+
+/**
+ * sendVoice — 发送语音消息（对齐 Telegram sendVoice）
+ * 
+ * 支持本地音频文件和公网 URL：
+ * - urlDirectUpload=true + 公网URL：先直传平台，失败后下载到本地再转码重试
+ * - urlDirectUpload=false + 公网URL：直接下载到本地再转码发送
+ * - 本地文件：自动转换为 SILK 格式后上传
+ * 
+ * 支持 transcodeEnabled 配置：禁用时非原生格式 fallback 到文件发送。
+ */
+export async function sendVoice(
+  ctx: MediaTargetContext,
+  voicePath: string,
+  /** 直传格式列表（跳过 SILK 转换），可选 */
+  directUploadFormats?: string[],
+  /** 是否启用转码（默认 true），false 时非原生格式直接返回错误 */
+  transcodeEnabled: boolean = true,
+): Promise<OutboundResult> {
+  const prefix = ctx.logPrefix ?? "[qqbot]";
+  const mediaPath = normalizePath(voicePath);
+  const isHttp = mediaPath.startsWith("http://") || mediaPath.startsWith("https://");
+
+  // 公网 URL 处理
+  if (isHttp) {
+    // urlDirectUpload=true: 先尝试直传平台
+    if (shouldDirectUploadUrl(ctx.account)) {
+      try {
+        const token = await getToken(ctx.account);
+        if (ctx.targetType === "c2c") {
+          const r = await sendC2CVoiceMessage(token, ctx.targetId, undefined, mediaPath, ctx.replyToId);
+          return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+        } else if (ctx.targetType === "group") {
+          const r = await sendGroupVoiceMessage(token, ctx.targetId, undefined, mediaPath, ctx.replyToId);
+          return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+        } else {
+          const r = await sendChannelMessage(token, ctx.targetId, MSG.VOICE_CHANNEL_UNSUPPORTED, ctx.replyToId);
+          return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`${prefix} sendVoice: URL direct upload failed (${msg}), downloading locally and retrying...`);
+      }
+    } else {
+      console.log(`${prefix} sendVoice: urlDirectUpload=false, downloading URL first...`);
+    }
+
+    // 下载到本地，然后走本地文件路径（含转码）
+    const localFile = await downloadToFallbackDir(mediaPath, prefix, "sendVoice");
+    if (localFile) {
+      return await sendVoiceFromLocal(ctx, localFile, directUploadFormats, transcodeEnabled, prefix);
+    }
+    return { channel: "qqbot", error: `下载失败: ${mediaPath.slice(0, 80)}` };
+  }
+
+  // 本地文件
+  return await sendVoiceFromLocal(ctx, mediaPath, directUploadFormats, transcodeEnabled, prefix);
+}
+
+/** 从本地文件发送语音（sendVoice 的内部辅助） */
+async function sendVoiceFromLocal(
+  ctx: MediaTargetContext,
+  mediaPath: string,
+  directUploadFormats: string[] | undefined,
+  transcodeEnabled: boolean,
+  prefix: string,
+): Promise<OutboundResult> {
+  // 等待文件就绪（TTS 异步生成，文件可能还没写完）
+  const fileSize = await waitForFile(mediaPath);
+  if (fileSize === 0) {
+    return { channel: "qqbot", error: MSG.VOICE_GENERATE_FAILED };
+  }
+
+  // 精细检测：是否需要转码
+  const needsTranscode = shouldTranscodeVoice(mediaPath);
+
+  // 转码已禁用但需要转码 → 提前 fallback
+  if (needsTranscode && !transcodeEnabled) {
+    const ext = path.extname(mediaPath).toLowerCase();
+    console.log(`${prefix} sendVoice: transcode disabled, format ${ext} needs transcode, returning error for fallback`);
+    return { channel: "qqbot", error: `语音转码已禁用，格式 ${ext} 不支持直传` };
+  }
+
+  try {
+    const silkBase64 = await audioFileToSilkBase64(mediaPath, directUploadFormats);
+    let uploadBase64 = silkBase64;
+
+    if (!uploadBase64) {
+      const buf = await readFileAsync(mediaPath);
+      uploadBase64 = buf.toString("base64");
+      console.log(`${prefix} sendVoice: SILK conversion failed, uploading raw (${formatFileSize(buf.length)})`);
+    } else {
+      console.log(`${prefix} sendVoice: SILK ready (${fileSize} bytes)`);
+    }
+
+    const token = await getToken(ctx.account);
+
+    if (ctx.targetType === "c2c") {
+      const r = await sendC2CVoiceMessage(token, ctx.targetId, uploadBase64, undefined, ctx.replyToId, undefined, mediaPath);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    } else if (ctx.targetType === "group") {
+      const r = await sendGroupVoiceMessage(token, ctx.targetId, uploadBase64, undefined, ctx.replyToId);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    } else {
+      const r = await sendChannelMessage(token, ctx.targetId, MSG.VOICE_CHANNEL_UNSUPPORTED, ctx.replyToId);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${prefix} sendVoice (local) failed: ${msg}`);
+    return { channel: "qqbot", error: msg };
+  }
+}
+
+/**
+ * sendVideoMsg — 发送视频消息（对齐 Telegram sendVideo）
+ * 
+ * 支持公网 URL（urlDirectUpload 控制直传或下载，失败自动 fallback）和本地文件路径。
+ */
+export async function sendVideoMsg(
+  ctx: MediaTargetContext,
+  videoPath: string,
+): Promise<OutboundResult> {
+  const prefix = ctx.logPrefix ?? "[qqbot]";
+  const mediaPath = normalizePath(videoPath);
+  const isHttp = mediaPath.startsWith("http://") || mediaPath.startsWith("https://");
+
+  // urlDirectUpload=false 时，公网 URL 直接下载到本地再发送
+  if (isHttp && !shouldDirectUploadUrl(ctx.account)) {
+    console.log(`${prefix} sendVideoMsg: urlDirectUpload=false, downloading URL first...`);
+    const localFile = await downloadToFallbackDir(mediaPath, prefix, "sendVideoMsg");
+    if (localFile) {
+      return await sendVideoFromLocal(ctx, localFile, prefix);
+    }
+    return { channel: "qqbot", error: `下载失败: ${mediaPath.slice(0, 80)}` };
+  }
+
+  try {
+    const token = await getToken(ctx.account);
+
+    if (isHttp) {
+      // 公网 URL：先尝试直传平台
+      if (ctx.targetType === "c2c") {
+        const r = await sendC2CVideoMessage(token, ctx.targetId, mediaPath, undefined, ctx.replyToId);
+        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+      } else if (ctx.targetType === "group") {
+        const r = await sendGroupVideoMessage(token, ctx.targetId, mediaPath, undefined, ctx.replyToId);
+        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+      } else {
+        const r = await sendChannelMessage(token, ctx.targetId, MSG.VIDEO_CHANNEL_UNSUPPORTED, ctx.replyToId);
+        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+      }
+    }
+
+    // 本地文件
+    return await sendVideoFromLocal(ctx, mediaPath, prefix);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+
+    // 公网 URL 直传失败 → 插件下载 → Base64 重试
+    if (isHttp) {
+      console.warn(`${prefix} sendVideoMsg: URL direct upload failed (${msg}), downloading locally and retrying as Base64...`);
+      const localFile = await downloadToFallbackDir(mediaPath, prefix, "sendVideoMsg");
+      if (localFile) {
+        return await sendVideoFromLocal(ctx, localFile, prefix);
+      }
+    }
+
+    console.error(`${prefix} sendVideoMsg failed: ${msg}`);
+    return { channel: "qqbot", error: msg };
+  }
+}
+
+/** 从本地文件发送视频（sendVideoMsg 的内部辅助） */
+async function sendVideoFromLocal(ctx: MediaTargetContext, mediaPath: string, prefix: string): Promise<OutboundResult> {
+  if (!(await fileExistsAsync(mediaPath))) {
+    return { channel: "qqbot", error: MSG.VIDEO_NOT_FOUND };
+  }
+  const sizeCheck = checkFileSize(mediaPath);
+  if (!sizeCheck.ok) {
+    return { channel: "qqbot", error: sizeCheck.error! };
+  }
+
+  const fileBuffer = await readFileAsync(mediaPath);
+  const videoBase64 = fileBuffer.toString("base64");
+  console.log(`${prefix} sendVideoMsg: local video (${formatFileSize(fileBuffer.length)})`);
+
+  try {
+    const token = await getToken(ctx.account);
+    if (ctx.targetType === "c2c") {
+      const r = await sendC2CVideoMessage(token, ctx.targetId, undefined, videoBase64, ctx.replyToId, undefined, mediaPath);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    } else if (ctx.targetType === "group") {
+      const r = await sendGroupVideoMessage(token, ctx.targetId, undefined, videoBase64, ctx.replyToId);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    } else {
+      const r = await sendChannelMessage(token, ctx.targetId, MSG.VIDEO_CHANNEL_UNSUPPORTED, ctx.replyToId);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${prefix} sendVideoMsg (local) failed: ${msg}`);
+    return { channel: "qqbot", error: msg };
+  }
+}
+
+/**
+ * sendDocument — 发送文件消息（对齐 Telegram sendDocument）
+ * 
+ * 支持本地文件路径和公网 URL（urlDirectUpload 控制直传或下载，失败自动 fallback）。
+ */
+export async function sendDocument(
+  ctx: MediaTargetContext,
+  filePath: string,
+): Promise<OutboundResult> {
+  const prefix = ctx.logPrefix ?? "[qqbot]";
+  const mediaPath = normalizePath(filePath);
+  const isHttp = mediaPath.startsWith("http://") || mediaPath.startsWith("https://");
+  const fileName = sanitizeFileName(path.basename(mediaPath));
+
+  // urlDirectUpload=false 时，公网 URL 直接下载到本地再发送
+  if (isHttp && !shouldDirectUploadUrl(ctx.account)) {
+    console.log(`${prefix} sendDocument: urlDirectUpload=false, downloading URL first...`);
+    const localFile = await downloadToFallbackDir(mediaPath, prefix, "sendDocument");
+    if (localFile) {
+      return await sendDocumentFromLocal(ctx, localFile, prefix);
+    }
+    return { channel: "qqbot", error: `下载失败: ${mediaPath.slice(0, 80)}` };
+  }
+
+  try {
+    const token = await getToken(ctx.account);
+
+    if (isHttp) {
+      // 公网 URL：先尝试直传平台
+      if (ctx.targetType === "c2c") {
+        const r = await sendC2CFileMessage(token, ctx.targetId, undefined, mediaPath, ctx.replyToId, fileName);
+        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+      } else if (ctx.targetType === "group") {
+        const r = await sendGroupFileMessage(token, ctx.targetId, undefined, mediaPath, ctx.replyToId, fileName);
+        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+      } else {
+        const r = await sendChannelMessage(token, ctx.targetId, MSG.FILE_CHANNEL_UNSUPPORTED, ctx.replyToId);
+        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+      }
+    }
+
+    // 本地文件
+    return await sendDocumentFromLocal(ctx, mediaPath, prefix);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+
+    // 公网 URL 直传失败 → 插件下载 → Base64 重试
+    if (isHttp) {
+      console.warn(`${prefix} sendDocument: URL direct upload failed (${msg}), downloading locally and retrying as Base64...`);
+      const localFile = await downloadToFallbackDir(mediaPath, prefix, "sendDocument");
+      if (localFile) {
+        return await sendDocumentFromLocal(ctx, localFile, prefix);
+      }
+    }
+
+    console.error(`${prefix} sendDocument failed: ${msg}`);
+    return { channel: "qqbot", error: msg };
+  }
+}
+
+/** 从本地文件发送文件（sendDocument 的内部辅助） */
+async function sendDocumentFromLocal(ctx: MediaTargetContext, mediaPath: string, prefix: string): Promise<OutboundResult> {
+  const fileName = sanitizeFileName(path.basename(mediaPath));
+
+  if (!(await fileExistsAsync(mediaPath))) {
+    return { channel: "qqbot", error: MSG.FILE_NOT_FOUND };
+  }
+  const sizeCheck = checkFileSize(mediaPath);
+  if (!sizeCheck.ok) {
+    return { channel: "qqbot", error: sizeCheck.error! };
+  }
+  const fileBuffer = await readFileAsync(mediaPath);
+  if (fileBuffer.length === 0) {
+    return { channel: "qqbot", error: `文件内容为空: ${mediaPath}` };
+  }
+  const fileBase64 = fileBuffer.toString("base64");
+  console.log(`${prefix} sendDocument: local file (${formatFileSize(fileBuffer.length)})`);
+
+  try {
+    const token = await getToken(ctx.account);
+    if (ctx.targetType === "c2c") {
+      const r = await sendC2CFileMessage(token, ctx.targetId, fileBase64, undefined, ctx.replyToId, fileName, mediaPath);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    } else if (ctx.targetType === "group") {
+      const r = await sendGroupFileMessage(token, ctx.targetId, fileBase64, undefined, ctx.replyToId, fileName);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    } else {
+      const r = await sendChannelMessage(token, ctx.targetId, MSG.FILE_CHANNEL_UNSUPPORTED, ctx.replyToId);
+      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${prefix} sendDocument (local) failed: ${msg}`);
+    return { channel: "qqbot", error: msg };
+  }
+}
+
+/**
+ * 通用辅助：下载远程文件到 fallback 目录
+ * 用于各 send* 函数的 URL 直传失败 fallback
+ */
+async function downloadToFallbackDir(httpUrl: string, prefix: string, caller: string): Promise<string | null> {
+  try {
+    const downloadDir = getQQBotDataDir("downloads", "url-fallback");
+    const localFile = await downloadFile(httpUrl, downloadDir);
+    if (!localFile) {
+      console.error(`${prefix} ${caller} fallback: download also failed for ${httpUrl.slice(0, 80)}`);
+      return null;
+    }
+    console.log(`${prefix} ${caller} fallback: downloaded → ${localFile}`);
+    return localFile;
+  } catch (err) {
+    console.error(`${prefix} ${caller} fallback download error:`, err);
+    return null;
+  }
+}
+
 /**
  * 发送文本消息
  * - 有 replyToId: 被动回复，1小时内最多回复4次
@@ -275,26 +759,27 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
   }
 
   // ============ 媒体标签检测与处理 ============
-  // 支持四种标签:
-  //   <qqimg>路径</qqimg> 或 <qqimg>路径</img>  — 图片
-  //   <qqvoice>路径</qqvoice>                   — 语音
-  //   <qqvideo>路径或URL</qqvideo>                — 视频
-  //   <qqfile>路径</qqfile>                     — 文件
+  // 支持五种标签:
+  //   <qqimg>路径</qqimg>      — 图片
+  //   <qqvoice>路径</qqvoice>  — 语音
+  //   <qqvideo>路径或URL</qqvideo> — 视频
+  //   <qqfile>路径</qqfile>    — 文件
+  //   <qqmedia>路径或URL</qqmedia> — 自动识别（根据扩展名路由）
   
   // 预处理：纠正小模型常见的标签拼写错误和格式问题
   text = normalizeMediaTags(text);
   
-  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 = text.match(mediaTagRegex);
   
   if (mediaTagMatches && mediaTagMatches.length > 0) {
     console.log(`[qqbot] sendText: Detected ${mediaTagMatches.length} media tag(s), processing...`);
     
     // 构建发送队列：根据内容在原文中的实际位置顺序发送
-    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(text)) !== null) {
@@ -356,7 +841,10 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
       }
 
       if (mediaPath) {
-        if (tagName === "qqvoice") {
+        if (tagName === "qqmedia") {
+          sendQueue.push({ type: "media", content: mediaPath });
+          console.log(`[qqbot] sendText: Found auto-detect media in <qqmedia>: ${mediaPath}`);
+        } else if (tagName === "qqvoice") {
           sendQueue.push({ type: "voice", content: mediaPath });
           console.log(`[qqbot] sendText: Found voice path in <qqvoice>: ${mediaPath}`);
         } else if (tagName === "qqvideo") {
@@ -382,13 +870,8 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
     
     console.log(`[qqbot] sendText: Send queue: ${sendQueue.map(item => item.type).join(" -> ")}`);
     
-    // 按顺序发送
-    if (!account.appId || !account.clientSecret) {
-      return { channel: "qqbot", error: "QQBot not configured (missing appId or clientSecret)" };
-    }
-    
-    const accessToken = await getAccessToken(account.appId, account.clientSecret);
-    const target = parseTarget(to);
+    // 按顺序发送（使用 Telegram 风格的统一媒体发送函数）
+    const mediaTarget = buildMediaTarget({ to, account, replyToId }, "[qqbot:sendText]");
     let lastResult: OutboundResult = { channel: "qqbot" };
     
     for (const item of sendQueue) {
@@ -396,7 +879,8 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
         if (item.type === "text") {
           // 发送文本
           if (replyToId) {
-            // 被动回复
+            const accessToken = await getToken(account);
+            const target = parseTarget(to);
             if (target.type === "c2c") {
               const result = await sendC2CMessage(accessToken, target.id, item.content, replyToId);
               recordMessageReply(replyToId);
@@ -411,7 +895,8 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
               lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
             }
           } else {
-            // 主动消息
+            const accessToken = await getToken(account);
+            const target = parseTarget(to);
             if (target.type === "c2c") {
               const result = await sendProactiveC2CMessage(accessToken, target.id, item.content);
               lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
@@ -425,214 +910,23 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
           }
           console.log(`[qqbot] sendText: Sent text part: ${item.content.slice(0, 30)}...`);
         } else if (item.type === "image") {
-          // 发送图片
-          const imagePath = item.content;
-          const isHttpUrl = imagePath.startsWith("http://") || imagePath.startsWith("https://");
-          
-          let imageUrl = imagePath;
-          
-          // 如果是本地文件路径，读取并转换为 Base64
-          if (!isHttpUrl && !imagePath.startsWith("data:")) {
-            if (!(await fileExistsAsync(imagePath))) {
-              console.error(`[qqbot] sendText: Image file not found: ${imagePath}`);
-              continue;
-            }
-            // 文件大小校验
-            const sizeCheck = checkFileSize(imagePath);
-            if (!sizeCheck.ok) {
-              console.error(`[qqbot] sendText: ${sizeCheck.error}`);
-              continue;
-            }
-            const fileBuffer = await readFileAsync(imagePath);
-            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] ?? "image/png";
-            imageUrl = `data:${mimeType};base64,${fileBuffer.toString("base64")}`;
-            console.log(`[qqbot] sendText: Converted local image to Base64 (size: ${formatFileSize(fileBuffer.length)})`);
-          }
-          
-          // 发送图片
-          if (target.type === "c2c") {
-            const result = await sendC2CImageMessage(accessToken, target.id, imageUrl, replyToId ?? undefined, undefined, isHttpUrl ? undefined : imagePath);
-            lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-          } else if (target.type === "group") {
-            const result = await sendGroupImageMessage(accessToken, target.id, imageUrl, replyToId ?? undefined);
-            lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-          } else if (isHttpUrl) {
-            // 频道使用 Markdown 格式（仅支持公网 URL）
-            const result = await sendChannelMessage(accessToken, target.id, `![](${imagePath})`, replyToId ?? undefined);
-            lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-          }
-          console.log(`[qqbot] sendText: Sent image via <qqimg> tag: ${imagePath.slice(0, 60)}...`);
+          lastResult = await sendPhoto(mediaTarget, item.content);
         } else if (item.type === "voice") {
-          // 发送语音文件
-          const voicePath = item.content;
-
-          // 等待文件就绪（TTS 工具异步生成，文件可能还没写完）
-          const fileSize = await waitForFile(voicePath);
-          if (fileSize === 0) {
-            console.error(`[qqbot] sendText: Voice file not ready after waiting: ${voicePath}`);
-            // 发送友好提示给用户
-            try {
-              if (target.type === "c2c") {
-                await sendC2CMessage(accessToken, target.id, "语音生成失败，请稍后重试", replyToId ?? undefined);
-              } else if (target.type === "group") {
-                await sendGroupMessage(accessToken, target.id, "语音生成失败，请稍后重试", replyToId ?? undefined);
-              }
-            } catch {}
-            continue;
-          }
-
-          // 转换为 SILK 格式（QQ Bot API 语音只支持 SILK）
-          const silkBase64 = await audioFileToSilkBase64(voicePath);
-          if (!silkBase64) {
-            const ext = path.extname(voicePath).toLowerCase();
-            console.error(`[qqbot] sendText: Voice conversion to SILK failed: ${ext} (${fileSize} bytes)`);
-            try {
-              if (target.type === "c2c") {
-                await sendC2CMessage(accessToken, target.id, "语音格式转换失败，请稍后重试", replyToId ?? undefined);
-              } else if (target.type === "group") {
-                await sendGroupMessage(accessToken, target.id, "语音格式转换失败，请稍后重试", replyToId ?? undefined);
-              }
-            } catch {}
-            continue;
-          }
-          console.log(`[qqbot] sendText: Voice converted to SILK (${fileSize} bytes)`);
-
-          if (target.type === "c2c") {
-            const result = await sendC2CVoiceMessage(accessToken, target.id, silkBase64, replyToId ?? undefined);
-            lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-          } else if (target.type === "group") {
-            const result = await sendGroupVoiceMessage(accessToken, target.id, silkBase64, replyToId ?? undefined);
-            lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-          } else {
-            const result = await sendChannelMessage(accessToken, target.id, `[语音消息暂不支持频道发送]`, replyToId ?? undefined);
-            lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-          }
-          console.log(`[qqbot] sendText: Sent voice via <qqvoice> tag: ${voicePath.slice(0, 60)}...`);
+          lastResult = await sendVoice(mediaTarget, item.content, undefined, account.config?.audioFormatPolicy?.transcodeEnabled !== false);
         } else if (item.type === "video") {
-          // 发送视频（支持公网 URL 和本地文件）
-          const videoPath = item.content;
-          const isHttpUrl = videoPath.startsWith("http://") || videoPath.startsWith("https://");
-
-          if (isHttpUrl) {
-            // 公网 URL
-            if (target.type === "c2c") {
-              const result = await sendC2CVideoMessage(accessToken, target.id, videoPath, undefined, replyToId ?? undefined);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            } else if (target.type === "group") {
-              const result = await sendGroupVideoMessage(accessToken, target.id, videoPath, undefined, replyToId ?? undefined);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            } else {
-              const result = await sendChannelMessage(accessToken, target.id, `[视频消息暂不支持频道发送]`, replyToId ?? undefined);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            }
-          } else {
-            // 本地文件：读取为 Base64
-            if (!(await fileExistsAsync(videoPath))) {
-              console.error(`[qqbot] sendText: Video file not found: ${videoPath}`);
-              continue;
-            }
-            const videoSizeCheck = checkFileSize(videoPath);
-            if (!videoSizeCheck.ok) {
-              console.error(`[qqbot] sendText: ${videoSizeCheck.error}`);
-              continue;
-            }
-            // 大文件进度提示
-            if (isLargeFile(videoSizeCheck.size)) {
-              try {
-                const hint = `⏳ 正在上传视频 (${formatFileSize(videoSizeCheck.size)})...`;
-                if (target.type === "c2c") {
-                  await sendC2CMessage(accessToken, target.id, hint, replyToId ?? undefined);
-                } else if (target.type === "group") {
-                  await sendGroupMessage(accessToken, target.id, hint, replyToId ?? undefined);
-                }
-              } catch {}
-            }
-            const fileBuffer = await readFileAsync(videoPath);
-            const videoBase64 = fileBuffer.toString("base64");
-            console.log(`[qqbot] sendText: Read local video (${formatFileSize(fileBuffer.length)}): ${videoPath}`);
-
-            if (target.type === "c2c") {
-              const result = await sendC2CVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined, undefined, videoPath);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            } else if (target.type === "group") {
-              const result = await sendGroupVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            } else {
-              const result = await sendChannelMessage(accessToken, target.id, `[视频消息暂不支持频道发送]`, replyToId ?? undefined);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            }
-          }
-          console.log(`[qqbot] sendText: Sent video via <qqvideo> tag: ${videoPath.slice(0, 60)}...`);
+          lastResult = await sendVideoMsg(mediaTarget, item.content);
         } else if (item.type === "file") {
-          // 发送文件
-          const filePath = item.content;
-          const isHttpUrl = filePath.startsWith("http://") || filePath.startsWith("https://");
-          const fileName = sanitizeFileName(path.basename(filePath));
-
-          if (isHttpUrl) {
-            // 公网 URL：直接通过 url 参数上传
-            if (target.type === "c2c") {
-              const result = await sendC2CFileMessage(accessToken, target.id, undefined, filePath, replyToId ?? undefined, fileName);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            } else if (target.type === "group") {
-              const result = await sendGroupFileMessage(accessToken, target.id, undefined, filePath, replyToId ?? undefined, fileName);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            } else {
-              const result = await sendChannelMessage(accessToken, target.id, `[文件消息暂不支持频道发送]`, replyToId ?? undefined);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            }
-          } else {
-            // 本地文件：读取转 Base64 上传
-            if (!(await fileExistsAsync(filePath))) {
-              console.error(`[qqbot] sendText: File not found: ${filePath}`);
-              continue;
-            }
-            const fileSizeCheck = checkFileSize(filePath);
-            if (!fileSizeCheck.ok) {
-              console.error(`[qqbot] sendText: ${fileSizeCheck.error}`);
-              continue;
-            }
-            // 大文件进度提示
-            if (isLargeFile(fileSizeCheck.size)) {
-              try {
-                const hint = `⏳ 正在上传文件 ${fileName} (${formatFileSize(fileSizeCheck.size)})...`;
-                if (target.type === "c2c") {
-                  await sendC2CMessage(accessToken, target.id, hint, replyToId ?? undefined);
-                } else if (target.type === "group") {
-                  await sendGroupMessage(accessToken, target.id, hint, replyToId ?? undefined);
-                }
-              } catch {}
-            }
-            const fileBuffer = await readFileAsync(filePath);
-            const fileBase64 = fileBuffer.toString("base64");
-            console.log(`[qqbot] sendText: Read local file (${formatFileSize(fileBuffer.length)}): ${filePath}`);
-
-            if (target.type === "c2c") {
-              const result = await sendC2CFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName, filePath);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            } else if (target.type === "group") {
-              const result = await sendGroupFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            } else {
-              const result = await sendChannelMessage(accessToken, target.id, `[文件消息暂不支持频道发送]`, replyToId ?? undefined);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-            }
-          }
-          console.log(`[qqbot] sendText: Sent file via <qqfile> tag: ${filePath.slice(0, 60)}...`);
+          lastResult = await sendDocument(mediaTarget, item.content);
+        } else if (item.type === "media") {
+          // qqmedia: 自动根据扩展名路由
+          lastResult = await sendMedia({
+            to, text: "", mediaUrl: item.content,
+            accountId: account.accountId, replyToId, account,
+          });
         }
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
         console.error(`[qqbot] sendText: Failed to send ${item.type}: ${errMsg}`);
-        // 继续发送队列中的其他内容
       }
     }
     
@@ -804,428 +1098,94 @@ export async function sendProactiveMessage(
  * ```
  */
 export async function sendMedia(ctx: MediaOutboundContext): Promise<OutboundResult> {
-  const { to, text, replyToId, account } = ctx;
-  // 展开波浪线路径：~/Desktop/file.png → /Users/xxx/Desktop/file.png
+  const { to, text, replyToId, account, mimeType } = ctx;
   const mediaUrl = normalizePath(ctx.mediaUrl);
 
   if (!account.appId || !account.clientSecret) {
     return { channel: "qqbot", error: "QQBot not configured (missing appId or clientSecret)" };
   }
-
   if (!mediaUrl) {
     return { channel: "qqbot", error: "mediaUrl is required for sendMedia" };
   }
 
-  // 判断是否为语音文件（本地文件路径 + 音频扩展名）
-  const isLocalPath = isLocalFilePath(mediaUrl);
-  const isHttpUrl = mediaUrl.startsWith("http://") || mediaUrl.startsWith("https://");
+  const target = buildMediaTarget({ to, account, replyToId }, "[qqbot:sendMedia]");
 
-  if (isLocalPath && isAudioFile(mediaUrl)) {
-    return sendVoiceFile(ctx);
-  }
-
-  // 判断是否为视频（公网 URL 或本地视频文件）
-  if (isVideoFile(mediaUrl)) {
-    if (isHttpUrl) {
-      return sendVideoUrl(ctx);
+  // 按类型分发（MIME 优先，扩展名回退）
+  // 各 send* 函数内部已自带 URL 直传/下载策略（受 urlDirectUpload 开关控制）
+  if (isAudioFile(mediaUrl, mimeType)) {
+    const formats = account.config?.audioFormatPolicy?.uploadDirectFormats ?? account.config?.voiceDirectUploadFormats;
+    const transcodeEnabled = account.config?.audioFormatPolicy?.transcodeEnabled !== false;
+    const result = await sendVoice(target, mediaUrl, formats, transcodeEnabled);
+    if (!result.error) {
+      if (text?.trim()) await sendTextAfterMedia(target, text);
+      return result;
     }
-    if (isLocalPath) {
-      return sendVideoFile(ctx);
+    // 语音发送失败 fallback 到文件发送（保留错误链）
+    const voiceError = result.error;
+    console.warn(`[qqbot] sendMedia: sendVoice failed (${voiceError}), falling back to sendDocument`);
+    const fallback = await sendDocument(target, mediaUrl);
+    if (!fallback.error) {
+      if (text?.trim()) await sendTextAfterMedia(target, text);
+      return fallback;
     }
+    return { channel: "qqbot", error: `voice: ${voiceError} | fallback file: ${fallback.error}` };
   }
 
-  // 判断是否为文档/文件（非图片、非音频、非视频的本地文件）
-  if (isLocalPath && !isImageFile(mediaUrl) && !isAudioFile(mediaUrl)) {
-    return sendDocumentFile(ctx);
+  if (isVideoFile(mediaUrl, mimeType)) {
+    const result = await sendVideoMsg(target, mediaUrl);
+    if (!result.error && text?.trim()) await sendTextAfterMedia(target, text);
+    return result;
   }
 
-  // === 以下为图片发送逻辑（原有逻辑） ===
-
-  const isDataUrl = mediaUrl.startsWith("data:");
-  
-  let processedMediaUrl = mediaUrl;
-  
-  if (isLocalPath) {
-    console.log(`[qqbot] sendMedia: local file path detected: ${mediaUrl}`);
-    
-    try {
-      if (!(await fileExistsAsync(mediaUrl))) {
-        return { channel: "qqbot", error: `本地文件不存在: ${mediaUrl}` };
-      }
-      
-      // 文件大小校验
-      const sizeCheck = checkFileSize(mediaUrl);
-      if (!sizeCheck.ok) {
-        return { channel: "qqbot", error: sizeCheck.error! };
-      }
-      
-      const fileBuffer = await readFileAsync(mediaUrl);
-      const base64Data = fileBuffer.toString("base64");
-      
-      const ext = path.extname(mediaUrl).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) {
-        return { 
-          channel: "qqbot", 
-          error: `不支持的图片格式: ${ext}。支持的格式: ${Object.keys(mimeTypes).join(", ")}` 
-        };
-      }
-      
-      processedMediaUrl = `data:${mimeType};base64,${base64Data}`;
-      console.log(`[qqbot] sendMedia: local file converted to Base64 (size: ${fileBuffer.length} bytes, type: ${mimeType})`);
-      
-    } catch (readErr) {
-      const errMsg = readErr instanceof Error ? readErr.message : String(readErr);
-      console.error(`[qqbot] sendMedia: failed to read local file: ${errMsg}`);
-      return { channel: "qqbot", error: `读取本地文件失败: ${errMsg}` };
-    }
-  } else if (!isHttpUrl && !isDataUrl) {
-    console.log(`[qqbot] sendMedia: unsupported media format: ${mediaUrl.slice(0, 50)}`);
-    return { 
-      channel: "qqbot", 
-      error: `不支持的媒体格式: ${mediaUrl.slice(0, 50)}...。支持: 公网 URL、Base64 Data URL 或本地文件路径（图片/音频）。` 
-    };
-  } else if (isDataUrl) {
-    console.log(`[qqbot] sendMedia: sending Base64 image (length: ${mediaUrl.length})`);
-  } else {
-    console.log(`[qqbot] sendMedia: sending image URL: ${mediaUrl.slice(0, 80)}...`);
+  // 非图片、非音频、非视频 → 文件发送
+  if (!isImageFile(mediaUrl, mimeType) && !isAudioFile(mediaUrl, mimeType) && !isVideoFile(mediaUrl, mimeType)) {
+    const result = await sendDocument(target, mediaUrl);
+    if (!result.error && text?.trim()) await sendTextAfterMedia(target, text);
+    return result;
   }
 
-  try {
-    const accessToken = await getAccessToken(account.appId, account.clientSecret);
-    const target = parseTarget(to);
-
-    let imageResult: { id: string; timestamp: number | string };
-    if (target.type === "c2c") {
-      imageResult = await sendC2CImageMessage(
-        accessToken, target.id, processedMediaUrl, replyToId ?? undefined, undefined, isLocalPath ? mediaUrl : undefined
-      );
-    } else if (target.type === "group") {
-      imageResult = await sendGroupImageMessage(
-        accessToken, target.id, processedMediaUrl, replyToId ?? undefined, undefined
-      );
-    } else {
-      const displayUrl = isLocalPath ? "[本地文件]" : mediaUrl;
-      const textWithUrl = text ? `${text}\n${displayUrl}` : displayUrl;
-      const result = await sendChannelMessage(accessToken, target.id, textWithUrl, replyToId ?? undefined);
-      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-    }
-
-    if (text?.trim()) {
-      try {
-        if (target.type === "c2c") {
-          await sendC2CMessage(accessToken, target.id, text, replyToId ?? undefined);
-        } else if (target.type === "group") {
-          await sendGroupMessage(accessToken, target.id, text, replyToId ?? undefined);
-        }
-      } catch (textErr) {
-        console.error(`[qqbot] Failed to send text after image: ${textErr}`);
-      }
-    }
-
-  return { channel: "qqbot", messageId: imageResult.id, timestamp: imageResult.timestamp, refIdx: (imageResult as any).ext_info?.ref_idx };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { channel: "qqbot", error: message };
-  }
+  // 默认：图片（sendPhoto 内置 URL fallback）
+  const result = await sendPhoto(target, mediaUrl);
+  if (!result.error && text?.trim()) await sendTextAfterMedia(target, text);
+  return result;
 }
 
-/**
- * 发送语音文件消息
- * 流程类似图片发送：读取本地音频文件 → 转为 SILK Base64 → 上传 → 发送
- */
-async function sendVoiceFile(ctx: MediaOutboundContext): Promise<OutboundResult> {
-  const { to, text, replyToId, account, mediaUrl } = ctx;
-
-  console.log(`[qqbot] sendVoiceFile: ${mediaUrl}`);
-
-  // 等待文件就绪（TTS 工具异步生成，文件可能还没写完）
-  const fileSize = await waitForFile(mediaUrl);
-  if (fileSize === 0) {
-    return { channel: "qqbot", error: `语音生成失败，请稍后重试` };
-  }
-
+/** 发送媒体后附带文本说明 */
+async function sendTextAfterMedia(ctx: MediaTargetContext, text: string): Promise<void> {
   try {
-    // 尝试转换为 SILK 格式（QQ 语音要求 SILK 格式），支持配置直传格式跳过转换
-    const directFormats = account.config?.audioFormatPolicy?.uploadDirectFormats ?? account.config?.voiceDirectUploadFormats;
-    const silkBase64 = await audioFileToSilkBase64(mediaUrl, directFormats);
-    if (!silkBase64) {
-      // 如果无法转换为 SILK，直接读取文件作为 Base64 上传（让 API 尝试处理）
-      const buf = await readFileAsync(mediaUrl);
-      const fallbackBase64 = buf.toString("base64");
-      console.log(`[qqbot] sendVoiceFile: not SILK format, uploading raw file (${formatFileSize(buf.length)})`);
-
-      const accessToken = await getAccessToken(account.appId!, account.clientSecret!);
-      const target = parseTarget(to);
-
-      let result: { id: string; timestamp: number | string };
-      if (target.type === "c2c") {
-        result = await sendC2CVoiceMessage(accessToken, target.id, fallbackBase64, replyToId ?? undefined);
-      } else if (target.type === "group") {
-        result = await sendGroupVoiceMessage(accessToken, target.id, fallbackBase64, replyToId ?? undefined);
-      } else {
-        const r = await sendChannelMessage(accessToken, target.id, `[语音消息暂不支持频道发送]`, replyToId ?? undefined);
-        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
-      }
-
-      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
-    }
-
-    console.log(`[qqbot] sendVoiceFile: SILK format ready, uploading...`);
-
-    const accessToken = await getAccessToken(account.appId!, account.clientSecret!);
-    const target = parseTarget(to);
-
-    let voiceResult: { id: string; timestamp: number | string };
-    if (target.type === "c2c") {
-      voiceResult = await sendC2CVoiceMessage(accessToken, target.id, silkBase64, replyToId ?? undefined);
-    } else if (target.type === "group") {
-      voiceResult = await sendGroupVoiceMessage(accessToken, target.id, silkBase64, replyToId ?? undefined);
-    } else {
-      const r = await sendChannelMessage(accessToken, target.id, `[语音消息暂不支持频道发送]`, replyToId ?? undefined);
-      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
+    const token = await getToken(ctx.account);
+    if (ctx.targetType === "c2c") {
+      await sendC2CMessage(token, ctx.targetId, text, ctx.replyToId);
+    } else if (ctx.targetType === "group") {
+      await sendGroupMessage(token, ctx.targetId, text, ctx.replyToId);
     }
-
-    // 如果有文本说明，再发送一条文本消息
-    if (text?.trim()) {
-      try {
-        if (target.type === "c2c") {
-          await sendC2CMessage(accessToken, target.id, text, replyToId ?? undefined);
-        } else if (target.type === "group") {
-          await sendGroupMessage(accessToken, target.id, text, replyToId ?? undefined);
-        }
-      } catch (textErr) {
-        console.error(`[qqbot] Failed to send text after voice: ${textErr}`);
-      }
-    }
-
-    console.log(`[qqbot] sendVoiceFile: voice message sent`);
-    return { channel: "qqbot", messageId: voiceResult.id, timestamp: voiceResult.timestamp, refIdx: (voiceResult as any).ext_info?.ref_idx };
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`[qqbot] sendVoiceFile: failed: ${message}`);
-    return { channel: "qqbot", error: message };
+    console.error(`[qqbot] sendTextAfterMedia failed: ${err}`);
   }
 }
 
-/** 判断文件是否为图片格式 */
-function isImageFile(filePath: string): boolean {
-  const ext = path.extname(filePath).toLowerCase();
-  return [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"].includes(ext);
-}
-
-/** 判断文件/URL 是否为视频格式 */
-function isVideoFile(filePath: string): boolean {
-  // 去掉 URL query 参数后判断扩展名
-  const cleanPath = filePath.split("?")[0]!;
-  const ext = path.extname(cleanPath).toLowerCase();
-  return [".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".wmv"].includes(ext);
+/** 从路径/URL 中提取扩展名（去除查询参数和 hash） */
+function getCleanExt(filePath: string): string {
+  const cleanPath = filePath.split("?")[0]!.split("#")[0]!;
+  return path.extname(cleanPath).toLowerCase();
 }
 
-/**
- * 发送视频消息（公网 URL）
- */
-async function sendVideoUrl(ctx: MediaOutboundContext): Promise<OutboundResult> {
-  const { to, text, replyToId, account, mediaUrl } = ctx;
-
-  console.log(`[qqbot] sendVideoUrl: ${mediaUrl}`);
-
-  if (!account.appId || !account.clientSecret) {
-    return { channel: "qqbot", error: "QQBot not configured (missing appId or clientSecret)" };
-  }
-
-  try {
-    const accessToken = await getAccessToken(account.appId, account.clientSecret);
-    const target = parseTarget(to);
-
-    let videoResult: { id: string; timestamp: number | string };
-    if (target.type === "c2c") {
-      videoResult = await sendC2CVideoMessage(accessToken, target.id, mediaUrl, undefined, replyToId ?? undefined);
-    } else if (target.type === "group") {
-      videoResult = await sendGroupVideoMessage(accessToken, target.id, mediaUrl, undefined, replyToId ?? undefined);
-    } else {
-      const r = await sendChannelMessage(accessToken, target.id, `[视频消息暂不支持频道发送]`, replyToId ?? undefined);
-      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
-    }
-
-    // 如果有文本说明，再发送一条文本消息
-    if (text?.trim()) {
-      try {
-        if (target.type === "c2c") {
-          await sendC2CMessage(accessToken, target.id, text, replyToId ?? undefined);
-        } else if (target.type === "group") {
-          await sendGroupMessage(accessToken, target.id, text, replyToId ?? undefined);
-        }
-      } catch (textErr) {
-        console.error(`[qqbot] Failed to send text after video: ${textErr}`);
-      }
-    }
-
-    console.log(`[qqbot] sendVideoUrl: video message sent`);
-    return { channel: "qqbot", messageId: videoResult.id, timestamp: videoResult.timestamp, refIdx: (videoResult as any).ext_info?.ref_idx };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`[qqbot] sendVideoUrl: failed: ${message}`);
-    return { channel: "qqbot", error: message };
-  }
-}
-
-/**
- * 发送本地视频文件
- * 流程：读取本地文件 → Base64 → 上传(file_type=2) → 发送
- */
-async function sendVideoFile(ctx: MediaOutboundContext): Promise<OutboundResult> {
-  const { to, text, replyToId, account, mediaUrl } = ctx;
-
-  console.log(`[qqbot] sendVideoFile: ${mediaUrl}`);
-
-  if (!account.appId || !account.clientSecret) {
-    return { channel: "qqbot", error: "QQBot not configured (missing appId or clientSecret)" };
-  }
-
-  try {
-    if (!(await fileExistsAsync(mediaUrl))) {
-      return { channel: "qqbot", error: `视频文件不存在: ${mediaUrl}` };
-    }
-
-    // 文件大小校验
-    const sizeCheck = checkFileSize(mediaUrl);
-    if (!sizeCheck.ok) {
-      return { channel: "qqbot", error: sizeCheck.error! };
-    }
-
-    const fileBuffer = await readFileAsync(mediaUrl);
-    const videoBase64 = fileBuffer.toString("base64");
-    console.log(`[qqbot] sendVideoFile: Read local video (${formatFileSize(fileBuffer.length)})`);
-
-    const accessToken = await getAccessToken(account.appId, account.clientSecret);
-    const target = parseTarget(to);
-
-    let videoResult: { id: string; timestamp: number | string };
-    if (target.type === "c2c") {
-      videoResult = await sendC2CVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined, undefined, mediaUrl);
-    } else if (target.type === "group") {
-      videoResult = await sendGroupVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined);
-    } else {
-      const r = await sendChannelMessage(accessToken, target.id, `[视频消息暂不支持频道发送]`, replyToId ?? undefined);
-      return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
-    }
-
-    // 如果有文本说明，再发送一条文本消息
-    if (text?.trim()) {
-      try {
-        if (target.type === "c2c") {
-          await sendC2CMessage(accessToken, target.id, text, replyToId ?? undefined);
-        } else if (target.type === "group") {
-          await sendGroupMessage(accessToken, target.id, text, replyToId ?? undefined);
-        }
-      } catch (textErr) {
-        console.error(`[qqbot] Failed to send text after video: ${textErr}`);
-      }
-    }
-
-    console.log(`[qqbot] sendVideoFile: video message sent`);
-    return { channel: "qqbot", messageId: videoResult.id, timestamp: videoResult.timestamp, refIdx: (videoResult as any).ext_info?.ref_idx };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`[qqbot] sendVideoFile: failed: ${message}`);
-    return { channel: "qqbot", error: message };
+/** 判断文件是否为图片格式（MIME 优先，扩展名回退） */
+function isImageFile(filePath: string, mimeType?: string): boolean {
+  if (mimeType) {
+    if (mimeType.startsWith("image/")) return true;
   }
+  const ext = getCleanExt(filePath);
+  return [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"].includes(ext);
 }
 
-/**
- * 发送文件消息
- * 流程：读取本地文件 → Base64 → 上传(file_type=4) → 发送
- * 支持本地文件路径和公网 URL
- */
-async function sendDocumentFile(ctx: MediaOutboundContext): Promise<OutboundResult> {
-  const { to, text, replyToId, account, mediaUrl } = ctx;
-
-  console.log(`[qqbot] sendDocumentFile: ${mediaUrl}`);
-
-  if (!account.appId || !account.clientSecret) {
-    return { channel: "qqbot", error: "QQBot not configured (missing appId or clientSecret)" };
-  }
-
-  const isHttpUrl = mediaUrl.startsWith("http://") || mediaUrl.startsWith("https://");
-  const fileName = sanitizeFileName(path.basename(mediaUrl));
-
-  try {
-    const accessToken = await getAccessToken(account.appId, account.clientSecret);
-    const target = parseTarget(to);
-
-    let fileResult: { id: string; timestamp: number | string };
-
-    if (isHttpUrl) {
-      // 公网 URL：通过 url 参数上传
-      console.log(`[qqbot] sendDocumentFile: uploading via URL: ${mediaUrl}`);
-      if (target.type === "c2c") {
-        fileResult = await sendC2CFileMessage(accessToken, target.id, undefined, mediaUrl, replyToId ?? undefined, fileName);
-      } else if (target.type === "group") {
-        fileResult = await sendGroupFileMessage(accessToken, target.id, undefined, mediaUrl, replyToId ?? undefined, fileName);
-      } else {
-        const r = await sendChannelMessage(accessToken, target.id, `[文件消息暂不支持频道发送]`, replyToId ?? undefined);
-        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
-      }
-    } else {
-      // 本地文件：读取转 Base64 上传
-      if (!(await fileExistsAsync(mediaUrl))) {
-        return { channel: "qqbot", error: `本地文件不存在: ${mediaUrl}` };
-      }
-
-      // 文件大小校验
-      const docSizeCheck = checkFileSize(mediaUrl);
-      if (!docSizeCheck.ok) {
-        return { channel: "qqbot", error: docSizeCheck.error! };
-      }
-
-      const fileBuffer = await readFileAsync(mediaUrl);
-      if (fileBuffer.length === 0) {
-        return { channel: "qqbot", error: `文件内容为空: ${mediaUrl}` };
-      }
-
-      const fileBase64 = fileBuffer.toString("base64");
-      console.log(`[qqbot] sendDocumentFile: read local file (${formatFileSize(fileBuffer.length)}), uploading...`);
-
-      if (target.type === "c2c") {
-        fileResult = await sendC2CFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName, mediaUrl);
-      } else if (target.type === "group") {
-        fileResult = await sendGroupFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName);
-      } else {
-        const r = await sendChannelMessage(accessToken, target.id, `[文件消息暂不支持频道发送]`, replyToId ?? undefined);
-        return { channel: "qqbot", messageId: r.id, timestamp: r.timestamp };
-      }
-    }
-
-    // 如果有附带文本说明，再发送一条文本消息
-    if (text?.trim()) {
-      try {
-        if (target.type === "c2c") {
-          await sendC2CMessage(accessToken, target.id, text, replyToId ?? undefined);
-        } else if (target.type === "group") {
-          await sendGroupMessage(accessToken, target.id, text, replyToId ?? undefined);
-        }
-      } catch (textErr) {
-        console.error(`[qqbot] Failed to send text after file: ${textErr}`);
-      }
-    }
-
-    console.log(`[qqbot] sendDocumentFile: file message sent`);
-    return { channel: "qqbot", messageId: fileResult.id, timestamp: fileResult.timestamp, refIdx: (fileResult as any).ext_info?.ref_idx };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`[qqbot] sendDocumentFile: failed: ${message}`);
-    return { channel: "qqbot", error: message };
+/** 判断文件/URL 是否为视频格式（MIME 优先，扩展名回退） */
+function isVideoFile(filePath: string, mimeType?: string): boolean {
+  if (mimeType) {
+    if (mimeType.startsWith("video/")) return true;
   }
+  const ext = getCleanExt(filePath);
+  return [".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".wmv"].includes(ext);
 }
 
 /**