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

package/src/ref-index-store.ts

@@ -44,7 +44,7 @@ export interface RefAttachmentSummary {
   contentType?: string;
   /** 语音转录文本（入站：STT/ASR识别结果；出站：TTS原文本） */
   transcript?: string;
-  /** 语音转录来源：stt=本地STT、asr=QQ官方ASR、tts=TTS原文本、fallback=兜底文案 */
+  /** 语音转录来源：stt=本地STT、asr=平台ASR、tts=TTS原文本、fallback=兜底文案 */
   transcriptSource?: "stt" | "asr" | "tts" | "fallback";
   /** 已下载到本地的文件路径（持久化后可供引用时访问） */
   localPath?: string;

package/src/slash-commands.ts

@@ -0,0 +1,425 @@
+/**
+ * QQBot 插件级斜杠指令处理器
+ *
+ * 设计原则：
+ * 1. 在消息入队前拦截，匹配到插件级指令后直接回复，不进入 AI 处理队列
+ * 2. 不匹配的 "/" 消息照常入队，交给 OpenClaw 框架处理
+ * 3. 每个指令通过 SlashCommand 接口注册，易于扩展
+ *
+ * 时间线追踪：
+ *   开平推送时间戳 → 插件收到(Date.now()) → 指令处理完成(Date.now())
+ *   从而计算「开平→插件」和「插件处理」两段耗时
+ */
+
+import type { QQBotAccountConfig } from "./types.js";
+import { createRequire } from "node:module";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { getUpdateInfo, formatUpdateNotice } from "./update-checker.js";
+const require = createRequire(import.meta.url);
+const execFileAsync = promisify(execFile);
+
+// 读取 package.json 中的版本号
+let PLUGIN_VERSION = "unknown";
+try {
+  const pkg = require("../package.json");
+  PLUGIN_VERSION = pkg.version ?? "unknown";
+} catch {
+  // fallback
+}
+
+// 获取 openclaw 框架版本（缓存结果，只执行一次）
+let _frameworkVersion: string | null = null;
+function getFrameworkVersion(): string {
+  if (_frameworkVersion !== null) return _frameworkVersion;
+  try {
+    for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
+      try {
+        const out = execFileSync(cli, ["--version"], { timeout: 3000, encoding: "utf8" }).trim();
+        // 输出格式: "OpenClaw 2026.3.13 (61d171a)"
+        if (out) {
+          _frameworkVersion = out;
+          return _frameworkVersion;
+        }
+      } catch {
+        continue;
+      }
+    }
+  } catch {
+    // fallback
+  }
+  _frameworkVersion = "unknown";
+  return _frameworkVersion;
+}
+
+// ============ 类型定义 ============
+
+/** 斜杠指令上下文（消息元数据 + 运行时状态） */
+export interface SlashCommandContext {
+  /** 消息类型 */
+  type: "c2c" | "guild" | "dm" | "group";
+  /** 发送者 ID */
+  senderId: string;
+  /** 发送者昵称 */
+  senderName?: string;
+  /** 消息 ID（用于被动回复） */
+  messageId: string;
+  /** 开平推送的事件时间戳（ISO 字符串） */
+  eventTimestamp: string;
+  /** 插件收到消息的本地时间（ms） */
+  receivedAt: number;
+  /** 原始消息内容 */
+  rawContent: string;
+  /** 指令参数（去掉指令名后的部分） */
+  args: string;
+  /** 频道 ID（guild 类型） */
+  channelId?: string;
+  /** 群 openid（group 类型） */
+  groupOpenid?: string;
+  /** 账号 ID */
+  accountId: string;
+  /** 账号配置（供指令读取可配置项） */
+  accountConfig?: QQBotAccountConfig;
+  /** 当前用户队列状态快照 */
+  queueSnapshot: QueueSnapshot;
+}
+
+/** 队列状态快照 */
+export interface QueueSnapshot {
+  /** 各用户队列中的消息总数 */
+  totalPending: number;
+  /** 正在并行处理的用户数 */
+  activeUsers: number;
+  /** 最大并发用户数 */
+  maxConcurrentUsers: number;
+  /** 当前发送者在队列中的待处理消息数 */
+  senderPending: number;
+}
+
+/** 斜杠指令返回值：文本、带文件的结果、或 null（不处理） */
+export type SlashCommandResult = string | SlashCommandFileResult | null;
+
+/** 带文件的指令结果（先回复文本，再发送文件） */
+export interface SlashCommandFileResult {
+  text: string;
+  /** 要发送的本地文件路径 */
+  filePath: string;
+}
+
+/** 斜杠指令定义 */
+interface SlashCommand {
+  /** 指令名（不含 /） */
+  name: string;
+  /** 简要描述 */
+  description: string;
+  /** 处理函数 */
+  handler: (ctx: SlashCommandContext) => SlashCommandResult | Promise<SlashCommandResult>;
+}
+
+// ============ 指令注册表 ============
+
+const commands: Map<string, SlashCommand> = new Map();
+
+function registerCommand(cmd: SlashCommand): void {
+  commands.set(cmd.name.toLowerCase(), cmd);
+}
+
+// ============ 内置指令 ============
+
+/**
+ * /qqbot-ping — 连通性检查（含分段耗时）
+ *
+ * 测试当前 openclaw 与 QQ 连接的网络延迟情况
+ * 耗时拆解：
+ *   总延迟 = QQ开平→插件收到 + 插件处理
+ *   其中 QQ开平→插件 ≈ eventTimestamp → receivedAt
+ *        插件处理     ≈ receivedAt → now
+ */
+registerCommand({
+  name: "qqbot-ping",
+  description: "测试当前 openclaw 与 QQ 连接的网络延迟",
+  handler: (ctx) => {
+    const now = Date.now();
+    const eventTime = new Date(ctx.eventTimestamp).getTime();
+    if (isNaN(eventTime)) {
+      return `🏓 pong!`;
+    }
+    const totalMs = now - eventTime;
+    const qqToPlugin = ctx.receivedAt - eventTime;
+    const pluginProcess = now - ctx.receivedAt;
+    const lines = [
+      `🏓 pong!`,
+      `⏱ 总延迟: ${totalMs}ms`,
+      `  ├ QQ → 插件: ${qqToPlugin}ms`,
+      `  └ 插件处理: ${pluginProcess}ms`,
+    ];
+    return lines.join("\n");
+  },
+});
+
+/**
+ * /qqbot-version — 版本信息（框架 + 插件 + 更新状态）
+ *
+ * 示例输出：
+ *   🦞 框架: 2026.3.13 (61d171a)
+ *   🤖 插件: v1.6.0
+ *   ✅ 当前已是最新版本
+ */
+registerCommand({
+  name: "qqbot-version",
+  description: "版本信息",
+  handler: () => {
+    const frameworkVersion = getFrameworkVersion();
+    const lines = [
+      `🦞 框架: ${frameworkVersion}`,
+      `🤖 qqbot插件: v${PLUGIN_VERSION}`,
+    ];
+    const info = getUpdateInfo();
+    if (info.checkedAt === 0) {
+      // 尚未检查过
+      lines.push(`⏳ 版本检查中...`);
+    } else if (info.error) {
+      lines.push(`⚠️ 版本检查失败`);
+    } else     if (info.hasUpdate && info.latest) {
+      lines.push(`🆕 有新版本: v${info.latest}，使用 /qqbot-upgrade 升级`);
+    } else {
+      lines.push(`✅ 当前已是最新版本`);
+    }
+    return lines.join("\n");
+  },
+});
+
+/**
+ * /qqbot-help — 列出所有插件级斜杠指令
+ */
+registerCommand({
+  name: "qqbot-help",
+  description: "显示帮助信息",
+  handler: () => {
+    const lines = [`**qqbot 插件 v${PLUGIN_VERSION}**`, ``];
+    for (const [name, cmd] of commands) {
+      lines.push(`- \`/${name}\` — ${cmd.description}`);
+    }
+    // 如有更新可用，追加提示
+    const info = getUpdateInfo();
+    const notice = formatUpdateNotice(info);
+    if (notice) {
+      lines.push("", notice);
+    }
+    return lines.join("\n");
+  },
+});
+
+const DEFAULT_UPGRADE_URL = "https://github.com/tencent-connect/openclaw-qqbot";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const UPGRADE_SCRIPT = path.resolve(__dirname, "../scripts/upgrade-via-npm.sh");
+
+/**
+ * /qqbot-upgrade [version] — 触发插件版本升级
+ * 无参数: 升级到 latest
+ * 带参数: 升级到指定版本，如 /qqbot-upgrade 1.6.1
+ *
+ * 智能判断：
+ * - 当前版本 >= latest → 提示已是最新
+ * - 当前版本 < latest → 展示升级指引 + 执行升级
+ */
+registerCommand({
+  name: "qqbot-upgrade",
+  description: "升级插件（/qqbot-upgrade [版本号]）",
+  handler: async (ctx) => {
+    const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
+    const targetVersion = ctx.args.trim();
+
+    // 无指定版本时，先检查是否需要升级
+    if (!targetVersion) {
+      const info = getUpdateInfo();
+      if (info.checkedAt > 0 && !info.error && !info.hasUpdate) {
+        return `✅ 当前已是最新版本 v${PLUGIN_VERSION}\n\n升级指引: ${url}`;
+      }
+    }
+    const scriptArgs = targetVersion ? ["--version", targetVersion] : [];
+
+    let upgradeOk = false;
+    let report = "";
+    try {
+      const { stdout, stderr } = await execFileAsync("bash", [UPGRADE_SCRIPT, ...scriptArgs], {
+        timeout: 120_000,
+        env: { ...process.env, PATH: process.env.PATH },
+      });
+      const output = (stdout + stderr).trim();
+
+      // 从脚本输出解析报告文本（QQBOT_REPORT=...）和版本号
+      const reportMatch = output.match(/QQBOT_REPORT=(.+)/);
+      const versionMatch = output.match(/QQBOT_NEW_VERSION=(\S+)/);
+      const newVersion = versionMatch?.[1] || "unknown";
+      report = reportMatch?.[1] || `✅ QQBot 升级完成: v${newVersion}`;
+
+      upgradeOk = newVersion !== "unknown" && newVersion !== PLUGIN_VERSION;
+      if (!upgradeOk && newVersion === PLUGIN_VERSION) {
+        report = `ℹ️ 已是最新版本 v${PLUGIN_VERSION}`;
+      }
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      report = `❌ 升级失败: ${msg}`;
+    }
+
+    if (upgradeOk) {
+      setTimeout(() => {
+        try { updatePluginsInstalls(); } catch {}
+        const cliNames = ["openclaw", "clawdbot", "moltbot"];
+        const tryRestart = (idx: number) => {
+          if (idx >= cliNames.length) { process.exit(0); return; }
+          const cli = cliNames[idx];
+          const child = spawn(cli, ["gateway", "restart"], {
+            detached: true, stdio: "ignore", env: process.env,
+          });
+          child.on("error", () => tryRestart(idx + 1));
+          child.unref();
+        };
+        tryRestart(0);
+      }, 2000);
+    }
+
+    return report + `\n\n升级指引: ${url}`;
+  },
+});
+
+/**
+ * /qqbot-logs — 打包最近 2000 行日志发送给用户
+ */
+registerCommand({
+  name: "qqbot-logs",
+  description: "获取最近运行日志",
+  handler: () => {
+    const homeDir = process.env.HOME || "~";
+    const logDir = path.join(homeDir, ".openclaw", "logs");
+    const gatewayLog = path.join(logDir, "gateway.log");
+    const errLog = path.join(logDir, "gateway.err.log");
+
+    const lines: string[] = [];
+
+    // 读取 gateway.log 最后 2000 行
+    for (const logFile of [gatewayLog, errLog]) {
+      if (!fs.existsSync(logFile)) continue;
+      try {
+        const content = fs.readFileSync(logFile, "utf8");
+        const allLines = content.split("\n");
+        const tail = allLines.slice(-1000); // 每个文件取最后 1000 行
+        if (tail.length > 0) {
+          lines.push(`\n========== ${path.basename(logFile)} (last ${tail.length} lines) ==========\n`);
+          lines.push(...tail);
+        }
+      } catch {
+        lines.push(`[读取 ${path.basename(logFile)} 失败]`);
+      }
+    }
+
+    if (lines.length === 0) {
+      return "⚠️ 未找到日志文件";
+    }
+
+    // 写入临时文件
+    const tmpDir = path.join(homeDir, ".openclaw", "qqbot", "downloads");
+    if (!fs.existsSync(tmpDir)) {
+      fs.mkdirSync(tmpDir, { recursive: true });
+    }
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const tmpFile = path.join(tmpDir, `qqbot-logs-${timestamp}.txt`);
+    fs.writeFileSync(tmpFile, lines.join("\n"), "utf8");
+
+    const totalLines = lines.filter(l => !l.startsWith("=")).length;
+    return {
+      text: `📋 日志已打包（约 ${totalLines} 行），正在发送文件...`,
+      filePath: tmpFile,
+    };
+  },
+});
+
+// ============ 匹配入口 ============
+
+/**
+ * 尝试匹配并执行插件级斜杠指令
+ *
+ * @returns 回复文本（匹配成功），null（不匹配，应入队正常处理）
+ */
+export async function matchSlashCommand(ctx: SlashCommandContext): Promise<SlashCommandResult> {
+  const content = ctx.rawContent.trim();
+  if (!content.startsWith("/")) return null;
+
+  // 解析指令名和参数
+  const spaceIdx = content.indexOf(" ");
+  const cmdName = (spaceIdx === -1 ? content.slice(1) : content.slice(1, spaceIdx)).toLowerCase();
+  const args = spaceIdx === -1 ? "" : content.slice(spaceIdx + 1).trim();
+
+  const cmd = commands.get(cmdName);
+  if (!cmd) return null; // 不是插件级指令，交给框架
+
+  ctx.args = args;
+  const result = await cmd.handler(ctx);
+  return result;
+}
+
+/** 获取插件版本号（供外部使用） */
+export function getPluginVersion(): string {
+  return PLUGIN_VERSION;
+}
+
+/**
+ * 更新 openclaw.json 中的 plugins.installs 记录。
+ * - 如果 source 是 "path"（开发目录），改为 "npm" 并删除 sourcePath
+ * - 更新 installPath、version、installedAt
+ */
+function updatePluginsInstalls(): void {
+  const cliNames = ["openclaw", "clawdbot", "moltbot"];
+  let configPath = "";
+  let cliName = "";
+  for (const name of cliNames) {
+    const candidate = path.join(process.env.HOME || "~", `.${name}`, `${name}.json`);
+    if (fs.existsSync(candidate)) {
+      configPath = candidate;
+      cliName = name;
+      break;
+    }
+  }
+  if (!configPath) return;
+
+  const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  const extensionsDir = path.join(process.env.HOME || "~", `.${cliName}`, "extensions");
+  const installPath = path.join(extensionsDir, "openclaw-qqbot");
+
+  // 读取新安装的版本号
+  let newVersion = "unknown";
+  try {
+    const pkgPath = path.join(installPath, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      newVersion = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version || "unknown";
+    }
+  } catch {}
+
+  cfg.plugins = cfg.plugins || {};
+  cfg.plugins.installs = cfg.plugins.installs || {};
+
+  const existing = cfg.plugins.installs["openclaw-qqbot"] || {};
+
+  // 保留已有记录，只更新关键字段
+  cfg.plugins.installs["openclaw-qqbot"] = {
+    ...existing,
+    source: "npm",
+    installPath,
+    version: newVersion,
+    installedAt: new Date().toISOString(),
+  };
+  // 如果之前是 source:"path"，清除 sourcePath（指向开发目录）
+  delete cfg.plugins.installs["openclaw-qqbot"].sourcePath;
+
+  // 确保 plugins.entries 存在
+  cfg.plugins.entries = cfg.plugins.entries || {};
+  if (!cfg.plugins.entries["openclaw-qqbot"]) {
+    cfg.plugins.entries["openclaw-qqbot"] = { enabled: true };
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(cfg, null, 4) + "\n");
+}

package/src/types.ts

@@ -53,6 +53,17 @@ export interface QQBotAccountConfig {
    * 统一管理入站（STT）和出站（上传）的音频格式转换行为
    */
   audioFormatPolicy?: AudioFormatPolicy;
+  /**
+   * 是否启用公网 URL 直传 QQ 平台（默认 true）
+   * 启用时：公网 URL 先直传给 QQ 开放平台的富媒体 API，平台自行拉取；失败后自动 fallback 到插件下载再 Base64 上传
+   * 禁用时：公网 URL 始终由插件先下载到本地，再以 Base64 上传（适用于 QQ 平台无法访问目标 URL 的场景）
+   */
+  urlDirectUpload?: boolean;
+  /**
+   * /qqbot-upgrade 指令返回的升级指引网址
+   * 默认: https://github.com/tencent-connect/openclaw-qqbot
+   */
+  upgradeUrl?: string;
 }
 
 /**
@@ -72,6 +83,12 @@ export interface AudioFormatPolicy {
    * 仅当需要覆盖默认值时才配置此项
    */
   uploadDirectFormats?: string[];
+  /**
+   * 是否启用语音转码（默认 true）
+   * 设为 false 可在环境无 ffmpeg 时跳过转码，直接以文件形式发送
+   * 当禁用时，非原生格式的音频会 fallback 到 sendDocument（文件发送）
+   */
+  transcodeEnabled?: boolean;
 }
 
 /**
@@ -85,7 +102,7 @@ export interface MessageAttachment {
   size?: number;
   url: string;
   voice_wav_url?: string;  // QQ 提供的 WAV 格式语音直链，有值时优先使用以避免 SILK→WAV 转换
-  asr_refer_text?: string; // QQ 事件内置 ASR 文本（精度有限，可作为无 STT/转录失败时的兜底）
+  asr_refer_text?: string; // QQ 事件内置 ASR 语音识别文本
 }
 
 /**

package/src/update-checker.ts

@@ -0,0 +1,102 @@
+/**
+ * 后台版本检查器
+ *
+ * - triggerUpdateCheck(): gateway 启动时调用，后台检查 npm registry 是否有新版本
+ * - getUpdateInfo(): 返回上次检查结果（供 /version、/help 指令使用）
+ * - formatUpdateNotice(): 格式化更新提示文本
+ */
+
+import { createRequire } from "node:module";
+import { execFile } from "node:child_process";
+
+const require = createRequire(import.meta.url);
+
+const PKG_NAME = "@tencent-connect/openclaw-qqbot";
+
+let CURRENT_VERSION = "unknown";
+try {
+  const pkg = require("../package.json");
+  CURRENT_VERSION = pkg.version ?? "unknown";
+} catch {
+  // fallback
+}
+
+export interface UpdateInfo {
+  current: string;
+  latest: string | null;
+  hasUpdate: boolean;
+  checkedAt: number;
+  error?: string;
+}
+
+let _lastInfo: UpdateInfo = {
+  current: CURRENT_VERSION,
+  latest: null,
+  hasUpdate: false,
+  checkedAt: 0,
+};
+
+let _checking = false;
+
+export function triggerUpdateCheck(log?: {
+  info: (msg: string) => void;
+  error: (msg: string) => void;
+  debug?: (msg: string) => void;
+}): void {
+  if (_checking) return;
+  const INTERVAL_MS = 30 * 60 * 1000;
+  if (_lastInfo.checkedAt > 0 && Date.now() - _lastInfo.checkedAt < INTERVAL_MS) {
+    return;
+  }
+  _checking = true;
+  log?.debug?.(`[qqbot:update-checker] checking (current: ${CURRENT_VERSION})...`);
+
+  execFile(
+    "npm",
+    ["view", PKG_NAME, "version", "--json"],
+    { timeout: 15_000, env: { ...process.env, PATH: process.env.PATH } },
+    (err, stdout, _stderr) => {
+      _checking = false;
+      const now = Date.now();
+      if (err) {
+        log?.debug?.(`[qqbot:update-checker] check failed: ${err.message}`);
+        _lastInfo = { current: CURRENT_VERSION, latest: null, hasUpdate: false, checkedAt: now, error: err.message };
+        return;
+      }
+      try {
+        const latest = JSON.parse(stdout.trim());
+        const hasUpdate = typeof latest === "string" && latest !== CURRENT_VERSION && compareVersions(latest, CURRENT_VERSION) > 0;
+        _lastInfo = { current: CURRENT_VERSION, latest, hasUpdate, checkedAt: now };
+        if (hasUpdate) {
+          log?.info?.(`[qqbot:update-checker] new version available: ${latest} (current: ${CURRENT_VERSION})`);
+        }
+      } catch (parseErr) {
+        _lastInfo = { current: CURRENT_VERSION, latest: null, hasUpdate: false, checkedAt: now, error: String(parseErr) };
+      }
+    },
+  );
+}
+
+export function getUpdateInfo(): UpdateInfo {
+  return { ..._lastInfo };
+}
+
+export function formatUpdateNotice(info: UpdateInfo): string {
+  if (!info.hasUpdate || !info.latest) return "";
+  return `\u{1f195} 有新版本可用: v${info.latest}（当前 v${info.current}）\n使用 /upgrade 升级`;
+}
+
+function compareVersions(a: string, b: string): number {
+  const normalize = (v: string) => v.replace(/^v/, "").split("-")[0].split(".").map(Number);
+  const pa = normalize(a);
+  const pb = normalize(b);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  const aIsPrerelease = a.includes("-");
+  const bIsPrerelease = b.includes("-");
+  if (aIsPrerelease && !bIsPrerelease) return -1;
+  if (!aIsPrerelease && bIsPrerelease) return 1;
+  return 0;
+}

package/src/user-messages.ts

@@ -0,0 +1,73 @@
+/**
+ * 用户面向的提示文案集中管理
+ *
+ * 设计原则（参考 Telegram / Discord / Slack / 飞书）：
+ * 1. 禁止暴露服务器路径、原始 Error、配置文件结构
+ * 2. 错误信息分级：用户只看到通用友好文案，技术细节走日志
+ * 3. 统一风格：去掉 [QQBot] 前缀和 [方括号] 格式
+ * 4. 所有面向用户的文案集中在此文件，便于维护和国际化
+ */
+
+// ============ 媒体发送错误 ============
+
+export const MSG = {
+  // 通用错误
+  GENERIC_ERROR: "抱歉，处理消息时遇到了问题，请稍后再试～",
+  AI_AUTH_ERROR: "抱歉，AI 服务暂时不可用，请联系管理员检查配置～",
+  AI_PROCESS_ERROR: "抱歉，AI 处理遇到了问题，请稍后再试～",
+  TIMEOUT_HINT: "已收到消息，正在处理中…",
+
+  // 图片
+  IMAGE_NOT_FOUND: "抱歉，图片不存在或已失效，无法发送～",
+  IMAGE_FORMAT_UNSUPPORTED: (ext: string) => `抱歉，暂不支持 ${ext} 格式的图片～`,
+  IMAGE_SEND_FAILED: "抱歉，图片发送失败了，请稍后再试～",
+  IMAGE_UPLOADING: (size: string) => `正在上传图片 (${size})...`,
+
+  // 语音
+  VOICE_GENERATE_FAILED: "抱歉，语音生成失败，请稍后重试～",
+  VOICE_CONVERT_FAILED: "抱歉，语音格式转换失败，请稍后重试～",
+  VOICE_SEND_FAILED: "抱歉，语音发送失败了，请稍后再试～",
+  VOICE_NOT_AVAILABLE: "抱歉，语音功能暂未开启～",
+  VOICE_MISSING_TEXT: "抱歉，语音消息缺少内容～",
+  VOICE_CHANNEL_UNSUPPORTED: "抱歉，语音消息暂不支持在频道中发送～",
+
+  // 视频
+  VIDEO_NOT_FOUND: "抱歉，视频文件不存在或已失效，无法发送～",
+  VIDEO_SEND_FAILED: "抱歉，视频发送失败了，请稍后再试～",
+  VIDEO_MISSING_PATH: "抱歉，视频消息缺少内容～",
+  VIDEO_CHANNEL_UNSUPPORTED: "抱歉，视频消息暂不支持在频道中发送～",
+  VIDEO_UPLOADING: (size: string) => `正在上传视频 (${size})...`,
+
+  // 文件
+  FILE_NOT_FOUND: "抱歉，文件不存在或已失效，无法发送～",
+  FILE_SEND_FAILED: "抱歉，文件发送失败了，请稍后再试～",
+  FILE_MISSING_PATH: "抱歉，文件消息缺少内容～",
+  FILE_CHANNEL_UNSUPPORTED: "抱歉，文件消息暂不支持在频道中发送～",
+  FILE_UPLOADING: (name: string, size: string) => `正在上传文件 ${name} (${size})...`,
+
+  // 载荷解析
+  PAYLOAD_PARSE_ERROR: "抱歉，消息格式异常，无法处理～",
+  UNSUPPORTED_MEDIA_TYPE: "抱歉，暂不支持该媒体类型～",
+  UNSUPPORTED_PAYLOAD_TYPE: "抱歉，暂不支持该消息类型～",
+} as const;
+
+/**
+ * 将媒体上传/发送错误转为对用户友好的提示文案
+ * 技术细节不暴露给用户，仅记录到日志
+ */
+export 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}发送失败了，请稍后再试～`;
+}