@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/gateway/lifecycle.ts

@@ -0,0 +1,221 @@
+/**
+ * Gateway 生命周期管理
+ *
+ * 封装 startAccount / logoutAccount 的业务逻辑：
+ * - 凭证恢复
+ * - QQBotGateway 实例创建与注册
+ * - Features 初始化（update-checker、approval-handler）
+ * - 登出时凭证清除
+ */
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { DEFAULT_ACCOUNT_ID, resolveQQBotAccount, applyQQBotAccountConfig } from '../config.js';
+import { getQQBotRuntime } from '../runtime.js';
+import { getAdapters } from '../adapter/resolve.js';
+import { QQBotGateway } from './qqbot-gateway.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import { registerGateway, unregisterGateway, getGateway } from '../outbound/outbound-service.js';
+import { saveCredentialBackup, loadCredentialBackup } from '../features/credential-backup.js';
+import { triggerUpdateCheck } from '../features/update-checker.js';
+import { QQBotApprovalHandler, registerApprovalHandler, unregisterApprovalHandler, getApprovalHandler } from '../features/approval-handler.js';
+
+export interface StartAccountContext {
+  account: ResolvedQQBotAccount;
+  abortSignal?: AbortSignal;
+  cfg: any;
+  /**
+   * 框架传入的基础 logger（无 child 方法）。内部会自动包装为 PluginLogger。
+   * 写日志的优先级：info > warn > error > debug，方法均为必选。
+   */
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void; debug: (msg: string) => void };
+  getStatus: () => Record<string, unknown>;
+  setStatus: (s: Record<string, unknown>) => void;
+  [key: string]: unknown;
+}
+
+/**
+ * 启动账户（含凭证恢复 + features 初始化）
+ */
+export async function startAccountWithCredentialRecovery(ctx: StartAccountContext): Promise<void> {
+  let { account } = ctx;
+  const { abortSignal, cfg } = ctx;
+  const log: PluginLogger = createPluginLogger({
+    prefix: `[${account.accountId}]`,
+    ...(ctx.log?.info ? { output: ctx.log as PluginLogger } : {}),
+  });
+  const runtime = getQQBotRuntime();
+
+  // 凭证恢复：配置中 appId/secret 为空时尝试从暂存文件恢复
+  if (!account.appId || !account.clientSecret) {
+    const backup = loadCredentialBackup(account.accountId);
+    if (backup) {
+      log?.info(`[qqbot:${account.accountId}] 从暂存文件恢复凭证 (appId=${backup.appId})`);
+      try {
+        const restoredCfg = applyQQBotAccountConfig(cfg, account.accountId, {
+          appId: backup.appId,
+          clientSecret: backup.clientSecret,
+            });
+        const adapters = getAdapters(runtime);
+        if (adapters.persistConfig) {
+          await adapters.persistConfig(() => restoredCfg);
+        }
+        account = resolveQQBotAccount(restoredCfg, account.accountId);
+      } catch (e) {
+        log?.error(`[qqbot:${account.accountId}] 凭证恢复失败: ${e}`);
+      }
+    }
+  }
+
+  // 创建 gateway 实例并注册
+  const gw = new QQBotGateway(account, runtime, log);
+  registerGateway(account.accountId, gw);
+
+  await gw.start(
+    {
+      onReady: () => {
+        saveCredentialBackup(account.accountId, account.appId, account.clientSecret);
+        ctx.setStatus({
+          ...ctx.getStatus(),
+          running: true,
+          connected: true,
+          lastConnectedAt: Date.now(),
+            });
+
+        // ── Features 初始化（gateway ready 后触发）──
+        initFeatures(account, cfg, log).catch((e) => {
+          log?.error(`[qqbot:${account.accountId}] initFeatures error: ${e}`);
+            });
+      },
+      onError: (error) => {
+        log?.error(`[qqbot:${account.accountId}] Gateway error: ${error.message}`);
+        ctx.setStatus({ ...ctx.getStatus(), lastError: error.message });
+      },
+    },
+    abortSignal,
+  );
+}
+
+/**
+ * Gateway ready 后初始化各 feature 模块
+ */
+async function initFeatures(account: ResolvedQQBotAccount, cfg: any, log: PluginLogger): Promise<void> {
+  // 1. 版本更新检测（后台预热，fire-and-forget）
+  triggerUpdateCheck(log);
+
+  const existing = getApprovalHandler(account.accountId);
+  if (existing) {
+    await existing.stop();
+    unregisterApprovalHandler(account.accountId);
+  }
+  const approvalLog = log.child('approval');
+  try {
+    const handler = new QQBotApprovalHandler({
+      accountId: account.accountId,
+      appId: account.appId,
+      clientSecret: account.clientSecret,
+      cfg,
+      log: approvalLog,
+    });
+    registerApprovalHandler(account.accountId, handler);
+    await handler.start();
+    approvalLog.info('registered');
+  } catch (e) {
+    approvalLog.debug(`not available: ${e}`);
+  }
+}
+
+/**
+ * 停止账户 — 主动调用，与 abort 信号双保险。
+ *
+ * 框架先 abort.abort() 让 startAccount promise 自然 resolve，
+ * 再调用 stopAccount 给插件机会做主动清理（关 WebSocket、注销处理器、刷新持久化）。
+ *
+ * 实现策略：
+ *   1. 主动调用 bot.stop() — 比 abort 信号更立刻、不依赖事件循环时机
+ *   2. 注销 approval handler / gateway
+ *   3. 立即返回；剩余资源（typing keepalive 定时器等）由 abort 信号触发收尾
+ */
+export async function stopAccountGracefully(params: {
+  accountId: string;
+  log?: PluginLogger;
+}): Promise<void> {
+  const { accountId, log } = params;
+  const gw = getGateway(accountId);
+
+  // 1. 主动停止 bot
+  if (gw) {
+    try {
+      await gw.stop();
+      log?.info(`[qqbot:${accountId}] gateway stopped`);
+    } catch (err) {
+      log?.error(`[qqbot:${accountId}] gateway stop error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  unregisterGateway(accountId);
+  try {
+    const h = getApprovalHandler(accountId);
+    if (h) await h.stop();
+  } catch {
+  }
+  unregisterApprovalHandler(accountId);
+}
+
+/**
+ * 登出账户（清除凭证）
+ */
+export async function logoutAndClearCredentials(params: {
+  accountId: string;
+  cfg: any;
+}): Promise<{ ok: boolean; cleared: boolean; envToken: boolean; loggedOut: boolean }> {
+  const { accountId, cfg } = params;
+  unregisterGateway(accountId);
+  try {
+    const h = getApprovalHandler(accountId);
+    if (h) await h.stop();
+  } catch {
+  }
+  unregisterApprovalHandler(accountId);
+
+  const nextCfg = { ...cfg } as OpenClawConfig;
+  const nextQQBot = cfg.channels?.qqbot ? { ...cfg.channels.qqbot } : undefined;
+  let cleared = false;
+  let changed = false;
+
+  if (nextQQBot) {
+    const qqbot = nextQQBot as Record<string, unknown>;
+    if (accountId === DEFAULT_ACCOUNT_ID && qqbot.clientSecret) {
+      delete qqbot.clientSecret;
+      cleared = true;
+      changed = true;
+    }
+    const accounts = qqbot.accounts as Record<string, Record<string, unknown>> | undefined;
+    if (accounts && accountId in accounts) {
+      const entry = accounts[accountId];
+      if (entry && 'clientSecret' in entry) {
+        delete entry.clientSecret;
+        cleared = true;
+        changed = true;
+      }
+      if (entry && Object.keys(entry).length === 0) {
+        delete accounts[accountId];
+        changed = true;
+      }
+    }
+  }
+
+  if (changed && nextQQBot) {
+    nextCfg.channels = { ...nextCfg.channels, qqbot: nextQQBot };
+    const runtime = getQQBotRuntime();
+    const adapters = getAdapters(runtime);
+    if (adapters.persistConfig) {
+      await adapters.persistConfig(() => nextCfg);
+    }
+  }
+
+  const resolved = resolveQQBotAccount(changed ? nextCfg : cfg, accountId);
+  const loggedOut = resolved.secretSource === 'none';
+  const envToken = Boolean(process.env.QQBOT_CLIENT_SECRET);
+  return { ok: true, cleared, envToken, loggedOut };
+}

package/src/gateway/middleware-setup.ts

@@ -0,0 +1,139 @@
+/**
+ * SDK 中间件编排
+ *
+ * 根据账户配置组装 SDK 内置中间件链。
+ * 中间件负责过滤和上下文富化；concurrencyGuard 负责串行+合并，
+ * 合并后的消息继续走完剩余中间件链，最终统一由 bot.on("message") 处理转发。
+ */
+import type { QQBot, MiddlewareContext } from '@tencent-connect/qqbot-nodejs';
+import {
+  messageFilter,
+  contentSanitizer,
+  rateLimiter,
+  concurrencyGuard,
+  mentionGate,
+  quoteRef,
+  historyBuffer,
+  envelopeFormatter,
+  typingIndicator,
+  slashCommand,
+  errorHandler,
+} from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { buildCommandList } from '../commands/index.js';
+import { attachmentProcessor } from '../middleware/attachment.js';
+import { assembleBody } from '../dispatch/body-assembler.js';
+import { getPersistedRefIndexStore } from '../features/ref-index-store.js';
+import { createPolicyInjector } from '../middleware/policy-injector.js';
+import { getHistoryStore, historyGroupKey } from '../features/history-store.js';
+import { dynamicAccessControl } from '../middleware/access-control.js';
+import { stripMentionText } from '../utils/mention.js';
+
+export interface MiddlewareSetupOptions {
+  /** 获取 runtime */
+  getRuntime: () => any;
+}
+
+/**
+ * 为 QQBot 实例编排完整的中间件链
+ */
+export function setupMiddlewares(bot: QQBot, account: ResolvedQQBotAccount, opts: MiddlewareSetupOptions): void {
+  // 1. 错误兜底（最外层洋葱皮）
+  bot.use(errorHandler());
+
+  // 2. 消息过滤：bot 回声 + 消息去重
+  bot.use(messageFilter({ skipSelfEcho: false }));
+
+  // 3. 动态策略注入 — 每条消息注入 ctx.state.policy
+  //    后续 dynamicAccessControl / mentionGate / historyBuffer 自动读取
+  bot.use(createPolicyInjector(account));
+
+  // 4. 群历史缓冲 — 放在门控之前，确保所有消息（含未 @bot）都计入上下文
+  //    limit 从 ctx.state.policy.group.historyLimit 读取，key 带 accountId 前缀隔离多账号
+  bot.use(historyBuffer({
+    store: getHistoryStore(),
+    groupKey: (ctx) => {
+      const gid = ctx.message.groupOpenid;
+      if (ctx.message.kind !== 'group' || !gid) return undefined;
+      return historyGroupKey(account.accountId, gid);
+    },
+  }));
+
+  // 5. 动态访问控制 — 从 ctx.state.policy 动态读取，支持 pairing
+  bot.use(dynamicAccessControl({
+    accountId: account.accountId,
+    getRuntime: opts.getRuntime,
+  }));
+
+  // 6. 群聊 @bot 门控（从 ctx.state.policy.group 读取动态配置）
+  bot.use(mentionGate());
+  // 7. 内容清洗（去 @marker、表情标签、多余空白）
+  // SDK 用 appId 匹配 @标记，但 QQ openid 不等于 appId，追加 stripMentionText 正确剥离
+  bot.use(contentSanitizer({
+    parseFaceTags: true,
+    transform: (content, ctx) => stripMentionText(content, (ctx.message as any).mentions),
+  }));
+
+  // 8. 三层限流（sender / group / global）
+  bot.use(rateLimiter());
+
+  // 9. 斜杠命令（在并发锁之前，命令匹配后直接 reply + stop，不排队）
+  //    依赖：ctx.state.policy（policyInjector, #3）、ctx.message.*（原始消息）
+  //    注意：/stop 是框架级命令，不在 qqbot 命令列表中，仍由 urgentPredicate 处理
+  const slash = slashCommand({ commands: buildCommandList(account, { getRuntime: opts.getRuntime }) });
+  bot.use(slash.middleware);
+
+  // 10. 并发串行+合并（在副作用中间件之前）
+  //     - 同 peer 串行处理，避免平台 session conflict
+  //     - 处理中消息暂存 buffer；完成后合并为一条，继续走完剩余中间件链
+  //       （typingIndicator/quoteRef/attachmentProcessor/... 直到 bot.on("message")）
+  //     - 合并时清除 assembledBody 让 dispatch.ts 用合并后 content 重建
+  //     - 超时后 abort 处理链（取消 LLM 调用），释放锁并排空缓冲
+  bot.use(concurrencyGuard({
+    strategy: 'merge',
+    maxQueue: 50,
+    maxProcessingMs: account.processingTimeoutMs,
+    /** 紧急指令（/stop）跳过排队，立即处理 */
+    urgentPredicate: (ctx: MiddlewareContext) => {
+      return (ctx.message.content as string ?? '').trim() === '/stop';
+    },
+    onMerge: (buffered) => {
+      const last = buffered[buffered.length - 1];
+      if (buffered.length === 1) return last;
+
+      // 透传原始消息列表，格式拼接下沉给下游 envelopeFormatter / assembleBody
+      (last.state as Record<string, unknown>).mergedMessages = buffered;
+
+      // 合并附件（所有 buffer 中的附件汇总到 survivor）
+      const attachments = buffered.flatMap((c) => c.message.attachments ?? []);
+      if (attachments.length > 0) {
+        last.message.attachments = attachments;
+      }
+
+      // 清除 assembledBody，让 dispatch.ts 用合并后的 ctx 重新构建
+      delete (last.state as Record<string, unknown>).assembledBody;
+
+      return last;
+    },
+  }));
+
+  // 11. C2C 输入状态指示器
+  bot.use(typingIndicator());
+
+  // 12. 引用消息解析（默认优先 msg_elements 获取文件名等丰富信息）
+  bot.use(quoteRef({
+    store: getPersistedRefIndexStore(account.accountId),
+  }));
+
+  // 13. 附件处理（语音 STT 转录 + 图片/文件下载）
+  bot.use(attachmentProcessor({ getRuntime: opts.getRuntime }));
+
+  // 14. 上下文组装（构建框架规约的 body）
+  bot.use(envelopeFormatter({
+    format: (ctx) => {
+      const assembled = assembleBody(ctx, ctx.message as never, account, opts.getRuntime);
+      (ctx.state as Record<string, unknown>).assembledBody = assembled;
+      return assembled.agentBody;
+    },
+  }));
+}

package/src/gateway/qqbot-gateway.ts

@@ -0,0 +1,342 @@
+/**
+ * QQBotGateway — 封装单个 Bot 实例的完整生命周期
+ */
+import {
+  QQBot,
+  FileKVStore,
+  kvSessionPersistence,
+  MediaFileType,
+  type ReplyTarget,
+  type QQBotInboundMessage,
+  type MiddlewareContext,
+  type InteractionEvent,
+  type MessageResponse,
+  type StreamSession,
+} from '@tencent-connect/qqbot-nodejs';
+import os from 'node:os';
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
+import { setupMiddlewares } from './middleware-setup.js';
+import { handleMessage, handleInteraction } from './event-handlers.js';
+import { getQQBotDataDir } from '../utils/platform.js';
+import { buildUserAgent } from '../bot-instance.js';
+import { createPluginWebhookAdapter } from '../adapter/webhook.js';
+import { getPersistedRefIndexStore } from '../features/ref-index-store.js';
+import { getCachedMsgId } from '../features/msgid-cache.js';
+
+export interface GatewayCallbacks {
+  onReady?: () => void;
+  onError?: (error: Error) => void;
+}
+
+export interface SendOptions {
+  msgId?: string;
+  text?: string;
+}
+
+// ── 超时常量 ──
+
+const TEXT_TIMEOUT_MS = 30_000;
+const MEDIA_TIMEOUT_MS = 300_000;
+
+function resolveMs(envKey: string, defaultMs: number): number {
+  const env = process.env[envKey];
+  if (env) {
+    const v = Number(env);
+    if (!Number.isNaN(v) && v > 0) return v;
+  }
+  return defaultMs;
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  if (ms <= 0) return promise;
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(() => reject(new Error(`出站超时: ${label} (${ms}ms)`)), ms),
+    ),
+  ]);
+}
+
+export class QQBotGateway {
+  readonly bot: QQBot;
+  private readonly account: ResolvedQQBotAccount;
+  private readonly runtime: PluginRuntime;
+  readonly log: PluginLogger;
+  private readonly textTimeout: number;
+  private readonly mediaTimeout: number;
+
+  constructor(account: ResolvedQQBotAccount, runtime: PluginRuntime, log?: PluginLogger) {
+    this.textTimeout = resolveMs('OPENCLAW_OUTBOUND_TIMEOUT_MS', TEXT_TIMEOUT_MS);
+    this.mediaTimeout = resolveMs('OPENCLAW_OUTBOUND_MEDIA_TIMEOUT_MS', MEDIA_TIMEOUT_MS);
+    this.account = account;
+    this.runtime = runtime;
+    this.log = log ?? createPluginLogger({ prefix: `[qqbot:${account.accountId}]` });
+
+    const dataDir = getQQBotDataDir(account.accountId);
+
+    const isWebhook = account.config.transport === 'webhook';
+
+    this.bot = new QQBot({
+      appId: account.appId,
+      appSecret: account.clientSecret,
+      accountId: account.accountId,
+      markdownSupport: account.markdownSupport,
+      userAgent: buildUserAgent(account.userAgentSuffix),
+      baseUrl: process.env.QQBOT_BASE_URL?.replace(/\/+$/, '') || 'https://api.sgroup.qq.com',
+      tokenBaseUrl: process.env.QQBOT_TOKEN_BASE_URL?.replace(/\/+$/, '') || 'https://bots.qq.com',
+      transport: account.config.transport,
+      webhook: isWebhook ? { path: account.config.webhook?.path, server: createPluginWebhookAdapter({ account, log: this.log }) } : undefined,
+      sessionPersistence: kvSessionPersistence({
+        store: new FileKVStore({ dir: dataDir, fileName: 'session.json' }),
+        accountId: account.accountId,
+      }),
+      tokenPrefetch: 'sync',
+      logger: this.log,
+    });
+
+    // 包装 sendText/sendMedia，回复后自动写入 ref-index store
+    this.wrapBotSendForRefIndex();
+
+    // concurrencyGuard 的 merge 策略合并后会继续走完剩余中间件链，
+    // 最终与单条消息一样统一由下方 bot.on('message') 处理转发，
+    // 因此这里不再需要单独的 onMergeDispatch 回调。
+    setupMiddlewares(this.bot, account, {
+      getRuntime: () => runtime,
+    });
+  }
+
+  async start(callbacks?: GatewayCallbacks, signal?: AbortSignal): Promise<void> {
+    const handleReady = () => {
+      this.log.info(`Gateway ready`);
+      callbacks?.onReady?.();
+    };
+    this.bot.on(`ready`, handleReady);
+    this.bot.on(`resumed`, handleReady);
+
+
+    this.bot.on('error', (err: Error) => {
+      this.log.error(`Gateway error: ${err.message}`);
+      callbacks?.onError?.(err);
+    });
+
+    const gatewayLog = this.log.child('gateway');
+
+    this.bot.on('message', async (ctx: MiddlewareContext, msg: QQBotInboundMessage) => {
+      gatewayLog.debug(`message msgId=${msg.messageId}`);
+      try {
+        await handleMessage(ctx, msg, this.account, this.runtime, this.log);
+      } catch (err) {
+        gatewayLog.error(`Dispatch error: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    });
+
+    this.bot.on('interaction', (_ctx, event: InteractionEvent) => {
+      handleInteraction(event, this.account, this.runtime, this.log, (id, code, data) =>
+        this.bot.acknowledgeInteraction(id, code, data),
+      ).catch((err) => {
+        this.log.error(`Interaction error: ${err}`);
+      });
+    });
+
+    await this.bot.start(signal);
+  }
+
+  async stop(): Promise<void> {
+    await this.bot.stop();
+  }
+
+  async sendText(target: ReplyTarget, text: string, opts?: SendOptions): Promise<MessageResponse> {
+    return withTimeout(
+      this.bot.sendText(attachMsgId(target, opts), text),
+      this.textTimeout, 'sendText',
+    );
+  }
+
+  async sendMedia(
+    target: ReplyTarget,
+    source: string,
+    opts?: SendOptions & { fileType?: MediaFileType },
+  ): Promise<MessageResponse> {
+    const resolvedTarget = attachMsgId(target, opts);
+    const fileType = opts?.fileType ?? MediaFileType.IMAGE;
+    const sourceOpts = resolveMediaSource(source);
+    const result = await withTimeout(
+      this.bot.sendMedia({ target: resolvedTarget, fileType, ...sourceOpts, content: opts?.text }),
+      this.mediaTimeout, 'sendMedia',
+    );
+    return result.message ?? { id: '', timestamp: Date.now() };
+  }
+
+  async sendVoice(
+    target: ReplyTarget,
+    source: { url?: string; base64?: string; localPath?: string },
+    opts?: SendOptions,
+  ): Promise<MessageResponse> {
+    const resolvedTarget = attachMsgId(target, opts);
+
+    if (source.base64) {
+      const result = await withTimeout(
+        this.bot.sendMedia({ target: resolvedTarget, fileType: MediaFileType.VOICE, fileData: source.base64, content: opts?.text }),
+        this.mediaTimeout, 'sendVoice(base64)',
+      );
+      return result.message ?? { id: '', timestamp: Date.now() };
+    }
+    if (source.localPath) {
+      const result = await withTimeout(
+        this.bot.sendMedia({ target: resolvedTarget, fileType: MediaFileType.VOICE, localPath: source.localPath, content: opts?.text }),
+        this.mediaTimeout, 'sendVoice(path)',
+      );
+      return result.message ?? { id: '', timestamp: Date.now() };
+    }
+    const result = await withTimeout(
+      this.bot.sendMedia({ target: resolvedTarget, fileType: MediaFileType.VOICE, url: source.url!, content: opts?.text }),
+      this.mediaTimeout, 'sendVoice(url)',
+    );
+    return result.message ?? { id: '', timestamp: Date.now() };
+  }
+
+  async sendVideo(
+    target: ReplyTarget,
+    source: string,
+    opts?: SendOptions,
+  ): Promise<MessageResponse> {
+    const resolvedTarget = attachMsgId(target, opts);
+    const sourceOpts = resolveMediaSource(source);
+    const result = await withTimeout(
+      this.bot.sendMedia({ target: resolvedTarget, fileType: MediaFileType.VIDEO, ...sourceOpts, content: opts?.text }),
+      this.mediaTimeout, 'sendVideo',
+    );
+    return result.message ?? { id: '', timestamp: Date.now() };
+  }
+
+  async sendFile(
+    target: ReplyTarget,
+    source: string,
+    opts?: SendOptions & { fileName?: string },
+  ): Promise<MessageResponse> {
+    const resolvedTarget = attachMsgId(target, opts);
+    const sourceOpts = resolveMediaSource(source);
+    const result = await withTimeout(
+      this.bot.sendMedia({ target: resolvedTarget, fileType: MediaFileType.FILE, ...sourceOpts, fileName: opts?.fileName, content: opts?.text }),
+      this.mediaTimeout, 'sendFile',
+    );
+    return result.message ?? { id: '', timestamp: Date.now() };
+  }
+
+  openStream(target: ReplyTarget, msgId: string): StreamSession {
+    return this.bot.openStream({
+      target: { ...target, msgId },
+    });
+  }
+
+  async sendTyping(target: ReplyTarget): Promise<void> {
+    await this.bot.sendTyping(target);
+  }
+
+  private wrapBotSendForRefIndex(): void {
+    const { accountId, appId } = this.account;
+    const senderName = this.account.config.name ?? appId;
+
+    const storeEntry = (msg: MessageResponse, content: string, scope: string, mediaKind?: string): void => {
+      const refIdx = msg.ext_info?.ref_idx;
+      if (!refIdx) return;
+      // 空内容降级为媒体类型标签
+      const finalContent = content || mediaKind
+        ? mediaKind === 'voice' ? '[语音]'
+        : mediaKind === 'image' ? '[图片]'
+        : mediaKind ? `[${mediaKind}]`
+        : content
+        : '';
+      const entry = {
+        messageId: msg.id, content: finalContent, senderId: appId, senderName,
+        timestamp: typeof msg.timestamp === 'number' ? new Date(msg.timestamp).toISOString() : msg.timestamp,
+        isBot: true, scope,
+      };
+      getPersistedRefIndexStore(accountId).set(refIdx, entry as any);
+    };
+
+    // sendText → 直接捕获 text content
+    const origSendText = this.bot.sendText.bind(this.bot);
+    this.bot.sendText = async (target, text, ...rest) => {
+      const result = await origSendText(target, text, ...rest);
+      storeEntry(result, text, target.scope);
+      return result;
+    };
+
+    // sendMedia → ext_info 在 result.message 里
+    const origSendMedia = this.bot.sendMedia.bind(this.bot);
+    this.bot.sendMedia = async (params: any) => {
+      const result = await origSendMedia(params);
+      const msg = (result as any).message as MessageResponse | undefined;
+      if (msg) storeEntry(msg, '', params.target?.scope ?? '', params.mediaKind);
+      return result;
+    };
+
+    // openStream → 流式消息 complete() 时才返回 ext_info.ref_idx
+    const origOpenStream = this.bot.openStream.bind(this.bot);
+    this.bot.openStream = (opts) => {
+      const session = origOpenStream(opts);
+      let lastContent = '';
+      const origUpdate = session.update.bind(session);
+      session.update = async (content: string) => {
+        lastContent = content;
+        return origUpdate(content);
+      };
+      const origComplete = session.complete.bind(session);
+      session.complete = async (): Promise<any> => {
+        const result = await origComplete();
+        if (result?.ext_info?.ref_idx) {
+          getPersistedRefIndexStore(accountId).set(result.ext_info.ref_idx, {
+            messageId: result.id, content: lastContent, senderId: appId, senderName,
+            timestamp: typeof result.timestamp === 'number' ? new Date(result.timestamp).toISOString() : result.timestamp,
+            isBot: true, scope: opts.target?.scope ?? '',
+          } as any);
+        }
+        return result;
+      };
+      return session;
+    };
+  }
+}
+
+function attachMsgId(target: ReplyTarget, opts?: SendOptions): ReplyTarget {
+  if (opts?.msgId) return { ...target, msgId: opts.msgId };
+  // 无显式 msgId 时尝试从缓存获取
+  const cached = getCachedMsgId(target.scope, target.targetId);
+  return cached ? { ...target, msgId: cached } : target;
+}
+
+function resolveMediaSource(source: string): { url?: string; localPath?: string; fileData?: string } {
+  if (source.startsWith('data:')) {
+    const commaIdx = source.indexOf(',');
+    if (commaIdx > 0) {
+      return { fileData: source.slice(commaIdx + 1) };
+    }
+    return { fileData: source };
+  }
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    return { url: source };
+  }
+  if (source.startsWith('file://')) {
+    let p = source.slice('file://'.length);
+    if (/^\/[a-zA-Z]:[\\/]/.test(p)) p = p.slice(1);
+    try { p = decodeURIComponent(p); } catch {}
+    return { localPath: p };
+  }
+  if (source === '~' || source.startsWith('~/') || source.startsWith('~\\')) {
+    return { localPath: source.replace(/^~/, os.homedir()) };
+  }
+  if (
+    source.startsWith('/') ||
+    source.startsWith('./') || source.startsWith('../') ||
+    source.startsWith('.\\') || source.startsWith('..\\') ||
+    /^[a-zA-Z]:[\\/]/.test(source) ||
+    source.startsWith('\\\\')
+  ) {
+    return { localPath: source };
+  }
+  return { url: source };
+}