@jerryliang122/openclaw-qqbot 1.0.0

package/src/outbound/media-send.ts

@@ -0,0 +1,408 @@
+/**
+ * 统一富媒体发送入口
+ *
+ * 职责：
+ *   1. 路径安全校验（只允许白名单目录下的本地文件）
+ *   2. 类型推断（扩展名 / MIME / 显式指定）
+ *   3. 路由分发（image / voice / video / file）
+ *   4. 语音发送失败 fallback 到文件
+ *
+ * 所有出站媒体发送（channel.outbound.sendMedia / deliver pipeline / Message 工具）
+ * 统一经过此入口。
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import { resolveAgentWorkspace } from '../adapter/workspace.js';
+import type { ReplyTarget } from '@tencent-connect/qqbot-nodejs';
+import type { QQBotGateway } from '../gateway/index.js';
+import { tryGetQQBotRuntime } from '../runtime.js';
+import { getAdapters } from '../adapter/resolve.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import { validateRemoteUrl } from '../utils/ssrf-guard.js';
+import { getGateway } from './outbound-service.js';
+import { parseTarget } from './target.js';
+import { checkAndConsumePassiveReplyQuota } from '../features/quota-manager.js';
+import {
+  isLocalFilePath,
+  isDataUrl,
+  normalizePath,
+  inferMediaKind,
+  inferMediaKindFromMime,
+  isPathInAllowedRoots,
+} from './local-file-router.js';
+import type { MediaKind } from './outbound-service.js';
+
+// ── 类型 ──
+
+export interface SendMediaParams {
+  /** 目标 (qqbot:c2c:xxx / qqbot:group:xxx) */
+  to: string;
+  /** 媒体源（URL / 本地路径 / data URL） */
+  source: string;
+  /** 附带文本 */
+  text?: string;
+  /** 显式指定类型（优先级最高） */
+  mediaKind?: MediaKind;
+  /** MIME type 提示（优先级次于 mediaKind） */
+  mimeType?: string;
+  /** 被动回复 ID */
+  replyToId?: string;
+  /** 账户 ID */
+  accountId: string;
+  /** 日志 */
+  log?: PluginLogger;
+  /** Agent ID（用于解析相对路径的工作区） */
+  agentId?: string;
+  /** 上层已原子预留配额；防止同一发送重复计数。 */
+  quotaReserved?: boolean;
+}
+
+export interface SendMediaResult {
+  messageId?: string;
+  error?: string;
+  /** 是否走了 fallback 路径 */
+  fallback?: boolean;
+}
+
+// ── 安全常量 ──
+
+/** 收集临时目录根路径：os.tmpdir + Unix /tmp（处理 macOS /tmp→/private/tmp 符号链接） */
+function resolveTempRoots(): string[] {
+  const roots = new Set<string>();
+  try {
+    const tmp = os.tmpdir();
+    roots.add(fs.existsSync(tmp) ? fs.realpathSync(tmp) : tmp);
+  } catch { /* skip */ }
+  // Unix: 解析 /tmp 真实路径，覆盖 macOS 符号链接场景
+  if (process.platform !== 'win32') {
+    try { roots.add(fs.realpathSync('/tmp')); } catch { /* skip */ }
+  }
+  return [...roots];
+}
+
+/**
+ * 构建动态白名单目录列表。
+ *
+ * 从 openclaw 核心已解析的 workspaceDir 反向推导配置目录，
+ * 同时保留已知配置目录名以向后兼容。
+ */
+function buildDynamicAllowedRoots(workspaceDir?: string): string[] {
+  const home = os.homedir();
+  const derivedBase = workspaceDir ? path.dirname(workspaceDir) : path.join(home, '.openclaw');
+  const roots: string[] = [];
+  const added = new Set<string>();
+
+  const addRoot = (p: string) => {
+    try {
+      const real = fs.existsSync(p) ? fs.realpathSync(p) : p;
+      if (!added.has(real)) {
+        added.add(real);
+        roots.push(real);
+      }
+    } catch { /* skip */ }
+  };
+
+  // 已知配置目录名（包括默认和开发模式）
+  const knownBases = [path.join(home, '.openclaw'), path.join(home, '.openclaw-dev')];
+
+  // 当前配置目录优先（从 workspaceDir 反推）
+  if (workspaceDir) {
+    addRoot(path.join(derivedBase, 'media'));
+    addRoot(path.join(derivedBase, 'workspace'));
+    addRoot(path.join(derivedBase, 'outbound'));
+    addRoot(workspaceDir);
+  }
+
+  // 所有已知配置目录（去重，确保向后兼容）
+  for (const base of knownBases) {
+    addRoot(path.join(base, 'media'));
+    addRoot(path.join(base, 'workspace'));
+    addRoot(path.join(base, 'outbound'));
+  }
+
+  // 临时目录
+  for (const t of resolveTempRoots()) addRoot(t);
+
+  return roots;
+}
+
+/** 入站 Base64 / Data URL 最大字节数（10MB） */
+const MAX_DATA_URL_BYTES = 10 * 1024 * 1024;
+
+// ── 统一入口 ──
+
+/**
+ * 统一富媒体发送入口
+ */
+export async function sendMedia(params: SendMediaParams): Promise<SendMediaResult> {
+  const { source, accountId, log } = params;
+  const mlog = log?.child('media');
+
+  if (!source) {
+    mlog?.error('source is empty');
+    return { error: 'sendMedia: source is required' };
+  }
+
+  // 1. 安全校验 + 路径规范化
+  const wsDir = resolveWorkspaceFromAgent(params.agentId);
+  mlog?.debug(`resolveMediaPath source=${source} agentId=${params.agentId ?? 'none'} workspaceDir=${wsDir ?? 'none'}`);
+  const resolved = await resolveMediaPath(source, mlog, wsDir);
+  if (!resolved.ok) {
+    mlog?.error(`resolveMediaPath failed: ${resolved.error}`);
+    return { error: resolved.error };
+  }
+
+  // 2. 推断类型
+  const kind = params.mediaKind
+    ?? (params.mimeType ? inferMediaKindFromMime(params.mimeType) : undefined)
+    ?? inferMediaKind(resolved.path);
+
+  // 3. 获取 gateway
+  const gw = getGateway(accountId);
+  if (!gw) {
+    return { error: `Bot "${accountId}" not running` };
+  }
+
+  const target = parseTarget(params.to);
+
+  const reservation = params.quotaReserved || !params.replyToId
+    ? { canReply: Boolean(params.replyToId), rollback: () => {} }
+    : checkAndConsumePassiveReplyQuota({
+        accountId,
+        msgId: params.replyToId,
+        scope: target.scope,
+        log,
+      });
+  const sendParams: SendMediaParams = {
+    ...params,
+    replyToId: reservation.canReply ? params.replyToId : undefined,
+  };
+
+  // 4. 路由分发
+  let result: SendMediaResult;
+  switch (kind) {
+    case 'voice':
+      result = await sendVoiceMedia(gw, target, resolved.path, sendParams);
+      break;
+    case 'video':
+      result = await sendVideoMedia(gw, target, resolved.path, sendParams);
+      break;
+    case 'file':
+      result = await sendFileMedia(gw, target, resolved.path, sendParams);
+      break;
+    case 'image':
+    default:
+      result = await sendImageMedia(gw, target, resolved.path, sendParams);
+      break;
+  }
+  if (result.error) reservation.rollback();
+  return result;
+}
+
+// ── 路径安全校验 ──
+
+interface ResolveResult {
+  ok: true;
+  path: string;
+  isLocal: boolean;
+}
+
+interface ResolveError {
+  ok: false;
+  error: string;
+}
+
+async function resolveMediaPath(source: string, log?: SendMediaParams['log'], workspaceDir?: string): Promise<ResolveResult | ResolveError> {
+  const normalized = normalizePath(source);
+
+  // Data URL → 大小限制检查
+  if (isDataUrl(normalized)) {
+    if (normalized.length > MAX_DATA_URL_BYTES) {
+      const sizeMB = (normalized.length / (1024 * 1024)).toFixed(1);
+      return { ok: false, error: `Data URL 过大（${sizeMB}MB，最大 10MB）` };
+    }
+    return { ok: true, path: normalized, isLocal: false };
+  }
+
+  // 远程 URL → SSRF 安全检查
+  if (normalized.startsWith('http://') || normalized.startsWith('https://')) {
+    try {
+      await validateRemoteUrl(normalized);
+    } catch (err) {
+      log?.warn(`SSRF blocked for media URL: ${normalized}`);
+      return { ok: false, error: `媒体 URL 被 SSRF 防护拦截: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    return { ok: true, path: normalized, isLocal: false };
+  }
+
+  // 纯文件名→工作区兜底查找
+  if (!isLocalFilePath(normalized)) {
+    const resolved = resolveWorkingFile(normalized, workspaceDir);
+    if (resolved) {
+      return resolveAllowedLocalPath(resolved, workspaceDir, log);
+    }
+    return { ok: true, path: normalized, isLocal: false };
+  }
+
+  return resolveAllowedLocalPath(normalized, workspaceDir, log);
+}
+
+/** 所有本地路径（包括纯文件名兜底）统一经过 realpath + 根目录白名单校验。 */
+function resolveAllowedLocalPath(
+  source: string,
+  workspaceDir?: string,
+  log?: SendMediaParams['log'],
+): ResolveResult | ResolveError {
+  const resolved = path.resolve(source);
+  if (!fs.existsSync(resolved)) {
+    return { ok: false, error: `File not found: ${resolved}` };
+  }
+
+  let real: string;
+  try {
+    real = fs.realpathSync(resolved);
+  } catch {
+    return { ok: false, error: `Cannot resolve path: ${resolved}` };
+  }
+
+  // 动态白名单：静态根目录 + 当前 agent 工作区
+  const dynamicRoots = buildDynamicAllowedRoots(workspaceDir);
+  const allowed = isPathInAllowedRoots(real, dynamicRoots);
+
+  if (!allowed) {
+    log?.warn(`path blocked — not in allowed directory: ${real}`);
+    return { ok: false, error: `文件路径不在允许的目录中` };
+  }
+
+  return { ok: true, path: real, isLocal: true };
+}
+
+/** Agent ID → workspaceDir（动态加载 plugin-sdk/health） */
+function resolveWorkspaceFromAgent(agentId?: string): string | undefined {
+  const cfg = resolveConfigViaAdapter();
+  if (!cfg) return undefined;
+  return resolveAgentWorkspace(cfg, agentId);
+}
+
+/** 通过 adapter 获取配置 */
+function resolveConfigViaAdapter(): Record<string, unknown> | undefined {
+  try {
+    const rt = tryGetQQBotRuntime();
+    if (!rt) return undefined;
+    return getAdapters(rt).getConfig?.();
+  } catch { return undefined; }
+}
+
+/** 纯文件名在 cwd + 工作区兜底查找 */
+function resolveWorkingFile(name: string, workspaceDir?: string): string | null {
+  for (const p of [path.resolve(name), workspaceDir ? path.join(workspaceDir, name) : null]) {
+    if (p && fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+// ── 各类型 sender ──
+
+async function sendImageMedia(
+  gw: QQBotGateway,
+  target: ReplyTarget,
+  source: string,
+  params: SendMediaParams,
+): Promise<SendMediaResult> {
+  try {
+    const result = await gw.sendMedia(target, source, {
+      text: params.text,
+      msgId: params.replyToId,
+    });
+    return { messageId: result.id };
+  } catch (err) {
+    return { error: formatErr(err) };
+  }
+}
+
+async function sendVoiceMedia(
+  gw: QQBotGateway,
+  target: ReplyTarget,
+  source: string,
+  params: SendMediaParams,
+): Promise<SendMediaResult> {
+  // 语音源路由：本地 → { localPath }，URL → { url }，其他 → { base64 }
+  const voiceSource = resolveVoiceSource(source);
+
+  try {
+    const result = await gw.sendVoice(target, voiceSource, {
+      msgId: params.replyToId,
+    });
+    return { messageId: result.id };
+  } catch (err) {
+    // 语音失败 → fallback 到文件发送
+    params.log?.child('media')?.warn(`sendVoice failed (${formatErr(err)}), falling back to sendFile`);
+    try {
+      const fileName = path.basename(source);
+      const fallback = await gw.sendFile(target, source, {
+        text: params.text,
+        msgId: params.replyToId,
+        fileName,
+      });
+      return { messageId: fallback.id, fallback: true };
+    } catch (fallbackErr) {
+      return { error: `voice: ${formatErr(err)} | fallback file: ${formatErr(fallbackErr)}` };
+    }
+  }
+}
+
+async function sendVideoMedia(
+  gw: QQBotGateway,
+  target: ReplyTarget,
+  source: string,
+  params: SendMediaParams,
+): Promise<SendMediaResult> {
+  try {
+    const result = await gw.sendVideo(target, source, {
+      text: params.text,
+      msgId: params.replyToId,
+    });
+    return { messageId: result.id };
+  } catch (err) {
+    return { error: formatErr(err) };
+  }
+}
+
+async function sendFileMedia(
+  gw: QQBotGateway,
+  target: ReplyTarget,
+  source: string,
+  params: SendMediaParams,
+): Promise<SendMediaResult> {
+  try {
+    const fileName = path.basename(source);
+    const result = await gw.sendFile(target, source, {
+      text: params.text,
+      msgId: params.replyToId,
+      fileName,
+    });
+    return { messageId: result.id };
+  } catch (err) {
+    return { error: formatErr(err) };
+  }
+}
+
+// ── 辅助 ──
+
+function resolveVoiceSource(source: string): { url?: string; base64?: string; localPath?: string } {
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    return { url: source };
+  }
+  if (source.startsWith('data:') || (!source.startsWith('/') && !source.startsWith('./') && !source.startsWith('../') && !source.startsWith('~'))) {
+    // data URL 或纯 base64 字符串
+    const commaIdx = source.indexOf(',');
+    return { base64: commaIdx > 0 ? source.slice(commaIdx + 1) : source };
+  }
+  return { localPath: source };
+}
+
+function formatErr(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/outbound/outbound-service.ts

@@ -0,0 +1,298 @@
+/**
+ * 出站消息服务
+ *
+ * 负责将 AI 回复通过 QQBotGateway 发送到 QQ。
+ * 超时保护由 QQBotGateway 内部统一处理，本层做 target 解析 + 被动回复限额管控。
+ */
+import * as path from 'node:path';
+import { MediaFileType } from '@tencent-connect/qqbot-nodejs';
+import type { QQBotGateway } from '../gateway/index.js';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { parseTarget } from './target.js';
+import {
+  checkAndConsumePassiveReplyQuota,
+  clearQuotaCacheForAccount,
+  rollbackPassiveReplyQuota,
+} from '../features/quota-manager.js';
+
+// ── Gateway 注册表（生命周期由 channel.ts 管理）──
+
+const gateways = new Map<string, QQBotGateway>();
+
+/**
+ * 为一次实际 API 调用预留被动回复配额。
+ * quotaReserved=true 表示上层 adapter 已经原子预留，避免同一发送重复计数。
+ */
+function reservePassiveReply(params: {
+  replyToId?: string;
+  accountId: string;
+  scope: 'c2c' | 'group';
+  quotaReserved?: boolean;
+}): { msgId?: string; rollback: () => void } {
+  if (!params.replyToId) return { rollback: () => {} };
+  if (params.quotaReserved) {
+    return { msgId: params.replyToId, rollback: () => {} };
+  }
+  const reservation = checkAndConsumePassiveReplyQuota({
+    accountId: params.accountId,
+    msgId: params.replyToId,
+    scope: params.scope,
+  });
+  return {
+    msgId: reservation.canReply ? params.replyToId : undefined,
+    rollback: reservation.canReply ? reservation.rollback : () => {},
+  };
+}
+
+/**
+ * 尝试为 typing 指示器占用一个被动回复配额（带 msg_id 发送）。
+ *
+ * typing 通知与回复消息共享同一 msg_id 的被动回复配额，必须经统一
+ * quota-manager 记账。配额不可用时调用方应降级为主动发送（不带 msg_id）。
+ *
+ * @returns 是否占得被动配额；false 表示应不带 msg_id 主动发送
+ */
+export function tryAcquirePassiveSlot(accountId: string, msgId: string | undefined): boolean {
+  if (!msgId) return false; // 无 msg_id 无法走被动通道
+  return checkAndConsumePassiveReplyQuota({ accountId, msgId, scope: 'c2c' }).canReply;
+}
+
+export function rollbackPassiveSlot(accountId: string, msgId: string | undefined): void {
+  if (!msgId) return;
+  rollbackPassiveReplyQuota({ accountId, msgId, scope: 'c2c' });
+}
+
+export function registerGateway(accountId: string, gw: QQBotGateway): void {
+  gateways.set(accountId, gw);
+}
+
+export function unregisterGateway(accountId: string): void {
+  gateways.delete(accountId);
+  clearQuotaCacheForAccount(accountId);
+}
+
+export function getGateway(accountId: string): QQBotGateway | undefined {
+  return gateways.get(accountId);
+}
+
+// ── 媒体类型映射 ──
+
+export type MediaKind = 'image' | 'voice' | 'video' | 'file';
+
+const MEDIA_KIND_TO_FILE_TYPE: Record<MediaKind, MediaFileType> = {
+  image: MediaFileType.IMAGE,
+  voice: MediaFileType.VOICE,
+  video: MediaFileType.VIDEO,
+  file: MediaFileType.FILE,
+};
+
+export interface SendResult {
+  messageId?: string;
+  error?: string;
+  errorCode?: string;
+  qqBizCode?: number;
+}
+
+// ── 公开 API（channel.ts / deliver-pipeline.ts 调用）──
+
+export async function sendText(params: {
+  to: string;
+  text: string;
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+  quotaReserved?: boolean;
+}): Promise<SendResult> {
+  const accountId = params.account.accountId;
+  const gw = gateways.get(accountId);
+  if (!gw) return { error: `Bot "${accountId}" not running` };
+  const target = parseTarget(params.to);
+  const reservation = reservePassiveReply({
+    replyToId: params.replyToId,
+    accountId,
+    scope: target.scope,
+    quotaReserved: params.quotaReserved,
+  });
+  try {
+    const result = await gw.sendText(target, params.text, { msgId: reservation.msgId });
+    return { messageId: result.id };
+  } catch (err: unknown) {
+    reservation.rollback();
+    return formatError(err);
+  }
+}
+
+export async function sendMedia(params: {
+  to: string;
+  text?: string;
+  mediaUrl: string;
+  mediaKind?: MediaKind;
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+  quotaReserved?: boolean;
+}): Promise<SendResult> {
+  const accountId = params.account.accountId;
+  const gw = gateways.get(accountId);
+  if (!gw) return { error: `Bot "${accountId}" not running` };
+  const target = parseTarget(params.to);
+  const reservation = reservePassiveReply({
+    replyToId: params.replyToId,
+    accountId,
+    scope: target.scope,
+    quotaReserved: params.quotaReserved,
+  });
+  try {
+    const kind = params.mediaKind ?? 'image';
+    const msgId = reservation.msgId;
+    if (kind === 'voice') {
+      const source = resolveVoiceSource(params.mediaUrl);
+      const result = await gw.sendVoice(target, source, { text: params.text, msgId });
+      return { messageId: result.id };
+    }
+    if (kind === 'video') {
+      const result = await gw.sendVideo(target, params.mediaUrl, { text: params.text, msgId });
+      return { messageId: result.id };
+    }
+    if (kind === 'file') {
+      const result = await gw.sendFile(target, params.mediaUrl, { text: params.text, msgId });
+      return { messageId: result.id };
+    }
+    const fileType = MEDIA_KIND_TO_FILE_TYPE[kind];
+    const result = await gw.sendMedia(target, params.mediaUrl, { text: params.text, msgId, fileType });
+    return { messageId: result.id };
+  } catch (err: unknown) {
+    reservation.rollback();
+    return formatError(err);
+  }
+}
+
+export async function sendVoice(params: {
+  to: string;
+  source: { url?: string; base64?: string };
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+  quotaReserved?: boolean;
+}): Promise<SendResult> {
+  const accountId = params.account.accountId;
+  const gw = gateways.get(accountId);
+  if (!gw) return { error: `Bot "${accountId}" not running` };
+  const target = parseTarget(params.to);
+  const reservation = reservePassiveReply({
+    replyToId: params.replyToId,
+    accountId,
+    scope: target.scope,
+    quotaReserved: params.quotaReserved,
+  });
+  try {
+    const result = await gw.sendVoice(target, params.source, { msgId: reservation.msgId });
+    return { messageId: result.id };
+  } catch (err: unknown) {
+    reservation.rollback();
+    return formatError(err);
+  }
+}
+
+export async function sendVideo(params: {
+  to: string;
+  videoUrl: string;
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+  quotaReserved?: boolean;
+}): Promise<SendResult> {
+  const accountId = params.account.accountId;
+  const gw = gateways.get(accountId);
+  if (!gw) return { error: `Bot "${accountId}" not running` };
+  const target = parseTarget(params.to);
+  const reservation = reservePassiveReply({
+    replyToId: params.replyToId,
+    accountId,
+    scope: target.scope,
+    quotaReserved: params.quotaReserved,
+  });
+  try {
+    const result = await gw.sendVideo(target, params.videoUrl, { msgId: reservation.msgId });
+    return { messageId: result.id };
+  } catch (err: unknown) {
+    reservation.rollback();
+    return formatError(err);
+  }
+}
+
+// ── OutboundService（deliver-pipeline 专用）──
+
+export class OutboundService {
+  constructor(private readonly gw: QQBotGateway, private readonly accountId: string) {}
+
+  async sendText(to: string, text: string, msgId?: string): Promise<SendResult> {
+    const target = parseTarget(to);
+    const reservation = reservePassiveReply({
+      replyToId: msgId,
+      accountId: this.accountId,
+      scope: target.scope,
+    });
+    try {
+      const result = await this.gw.sendText(target, text, { msgId: reservation.msgId });
+      return { messageId: result.id };
+    } catch (err: unknown) {
+      reservation.rollback();
+      return formatError(err);
+    }
+  }
+
+  async sendMedia(to: string, source: string, opts?: { text?: string; msgId?: string; mediaKind?: MediaKind }): Promise<SendResult> {
+    const target = parseTarget(to);
+    const reservation = reservePassiveReply({
+      replyToId: opts?.msgId,
+      accountId: this.accountId,
+      scope: target.scope,
+    });
+    try {
+      const kind = opts?.mediaKind ?? 'image';
+      const resolvedMsgId = reservation.msgId;
+      if (kind === 'voice') {
+        const voiceSource = resolveVoiceSource(source);
+        const result = await this.gw.sendVoice(target, voiceSource, { text: opts?.text, msgId: resolvedMsgId });
+        return { messageId: result.id };
+      }
+      if (kind === 'video') {
+        const result = await this.gw.sendVideo(target, source, { text: opts?.text, msgId: resolvedMsgId });
+        return { messageId: result.id };
+      }
+      if (kind === 'file') {
+        const result = await this.gw.sendFile(target, source, { text: opts?.text, msgId: resolvedMsgId, fileName: path.basename(source) });
+        return { messageId: result.id };
+      }
+      const fileType = MEDIA_KIND_TO_FILE_TYPE[kind];
+      const result = await this.gw.sendMedia(target, source, { text: opts?.text, msgId: resolvedMsgId, fileType });
+      return { messageId: result.id };
+    } catch (err: unknown) {
+      reservation.rollback();
+      return formatError(err);
+    }
+  }
+}
+
+// ── 辅助 ──
+
+function resolveVoiceSource(source: string): { url?: string; base64?: string; localPath?: string } {
+  if (source.startsWith('http://') || source.startsWith('https://')) return { url: source };
+  if (source.startsWith('/') || source.startsWith('./') || source.startsWith('../')) return { localPath: source };
+  if (source.startsWith('data:')) {
+    const i = source.indexOf(',');
+    return { base64: i > 0 ? source.slice(i + 1) : source };
+  }
+  return { base64: source };
+}
+
+function formatError(err: unknown): SendResult {
+  if (err instanceof Error) {
+    const result: SendResult = { error: err.message };
+    if ('code' in err) result.errorCode = String((err as any).code);
+    if ('qqBizCode' in err) result.qqBizCode = (err as any).qqBizCode;
+    return result;
+  }
+  return { error: String(err) };
+}