@jerryliang122/openclaw-qqbot 1.0.0

package/src/gateway/middleware-setup.ts

@@ -0,0 +1,173 @@
+/**
+ * SDK 中间件编排
+ *
+ * 根据账户配置组装 SDK 内置中间件链。
+ * 中间件负责过滤和上下文富化。
+ * 
+ * 并发控制说明（群聊/私聊差异化）：
+ * - 群聊：使用消息合并中间件，所有消息都应该被处理，快速消息应该被合并
+ * - 私聊：依赖 OpenClaw 框架的 session lane 机制，用户可以"插嘴"（新消息取消旧消息）
+ * - 这样与 Telegram 等其他 channel 保持一致
+ */
+import type { QQBot, MiddlewareContext } from '@tencent-connect/qqbot-nodejs';
+import {
+  messageFilter,
+  contentSanitizer,
+  rateLimiter,
+  mentionGate,
+  quoteRef,
+  historyBuffer,
+  envelopeFormatter,
+  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 { inboundGuard } from '../middleware/inbound-guard.js';
+import { secretCapture } from '../middleware/secret-capture.js';
+import { c2cTypingIndicator } from '../middleware/typing.js';
+import { stripMentionText } from '../utils/mention.js';
+import { resolveGroupConfigFromAccount } from '../config.js';
+
+export interface MiddlewareSetupOptions {
+  /** 获取 runtime */
+  getRuntime: () => any;
+}
+
+/**
+ * 为 QQBot 实例编排完整的中间件链
+ */
+export function setupMiddlewares(bot: QQBot, account: ResolvedQQBotAccount, opts: MiddlewareSetupOptions): void {
+  // 1. 错误兜底（最外层洋葱皮）
+  bot.use(errorHandler());
+
+  // 2. 消息过滤：bot 回声 + 消息去重
+  //    skipSelfEcho 必须开启：SDK 注明 QQ 会把 bot 自身出站消息回投为入站
+  //    事件（群聊尤其常见，按 author.bot 识别）；私聊回声无该标记，
+  //    由 inboundGuard 的出站 id 比对兜底
+  bot.use(messageFilter({ skipSelfEcho: true }));
+
+  // 2.5 入站事件守卫：出站回声（c2c）+ 重复推送长窗口去重 + 空内容事件
+  //     三个检查都打 INFO 日志留痕；详见 src/middleware/inbound-guard.ts
+  bot.use(inboundGuard({ accountId: account.accountId }));
+
+  // 3. 动态策略注入 — 每条消息注入 ctx.state.policy
+  //    后续 dynamicAccessControl / mentionGate / historyBuffer 自动读取
+  bot.use(createPolicyInjector(account));
+
+  // 4. 群历史缓冲 — 放在门控之前，确保所有消息（含未 @bot）都计入上下文
+  //    limit 从 ctx.state.policy.group.historyLimit 读取，key 带 accountId 前缀隔离多账号；
+  //    room_event 群返回 undefined 跳过记录——该模式下每条消息已作为入站事件
+  //    进框架持久化 transcript，插件历史快照会造成双份上下文
+  bot.use(historyBuffer({
+    store: getHistoryStore(),
+    groupKey: (ctx) => {
+      const gid = ctx.message.groupOpenid;
+      if (ctx.message.kind !== 'group' || !gid) return undefined;
+      if (resolveGroupConfigFromAccount(account, gid).unmentionedInbound === 'room_event') {
+        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 读取动态配置）
+  //    isImplicitMention：引用 bot 出站消息 = 隐式被点名（对齐 telegram
+  //    reply-to-bot 语义）。ref-index get 为同步内存查询，可直接放同步回调；
+  //    仅全量模式（GROUP_MESSAGE_CREATE）下未 @ 消息才可能带引用进到这里。
+  bot.use(mentionGate({
+      isImplicitMention: (ctx) => {
+        const msg = ctx.message as { refMsgIdx?: string };
+        if (!msg?.refMsgIdx) return false;
+        try {
+          const entry = getPersistedRefIndexStore(account.accountId).get(msg.refMsgIdx) as
+            | { isBot?: boolean }
+            | undefined;
+          return entry?.isBot === true;
+        } catch (err) {
+          ctx.log.debug?.(`[mention] implicit quote-bot check failed: ${err instanceof Error ? err.message : String(err)}`);
+          return false;
+        }
+      },
+    }));
+  // 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）
+  //    默认启用保守阈值（20/min、60/min、300/min），正常使用不会触发；
+  //    触发即 INFO 留痕（不自动回复，避免烧被动配额/刷屏）。账号级
+  //    channels.qqbot.rateLimit 可覆盖或 {enabled:false} 关闭。
+  {
+    const rl = account.config.rateLimit ?? {};
+    if (rl.enabled !== false) {
+      bot.use(rateLimiter({
+        perSender: rl.perSender ?? { max: 20, windowMs: 60_000 },
+        perGroup: rl.perGroup ?? { max: 60, windowMs: 60_000 },
+        global: rl.global ?? { max: 300, windowMs: 60_000 },
+        onLimit: (ctx, tier) => {
+          ctx.log.info?.(
+            `[rate-limit] dropped (${tier}) sender=${(ctx.message as any).senderId ?? '-'} group=${(ctx.message as any).groupOpenid ?? '-'}`,
+          );
+        },
+      }));
+    }
+  }
+
+  // 9. 斜杠命令（命令匹配后直接 reply + stop）
+  //    依赖：ctx.state.policy（policyInjector, #3）、ctx.message.*（原始消息）
+  const slash = slashCommand({ commands: buildCommandList(account, { getRuntime: opts.getRuntime }) });
+  bot.use(slash.middleware);
+
+  // 9.5 密钥捕获 — pending 密钥输入时拦截该 c2c 用户的下一条文本消息，
+  //     就地执行 openclaw secrets store set 并直接回执，消息不进框架
+  //     （密钥绝不进入 AI 转录）。放在斜杠命令之后：/bot-* 优先可用；
+  //     拦截后不再触发 typing / envelope；多问题 ask_user 答案消息红线放行
+  bot.use(secretCapture({ accountId: account.accountId }));
+
+  // 10. 群聊消息排队已完全交给框架队列（dispatch 侧按 coalesce.enabled 传
+  //     queueModeOverride collect/followup），插件内不再做 busy-buffering。
+
+  // 11. C2C 输入状态指示器（配额感知：优先占被动回复配额，耗尽后与回复
+  //     消息一样降级为主动发送；续期间隔默认 20s 且不低于 20s，
+  //     详见 src/middleware/typing.ts）
+  const typingCfg = account.config.typing;
+  if (typingCfg?.enabled !== false) {
+    bot.use(c2cTypingIndicator({
+      accountId: account.accountId,
+      intervalMs: typingCfg?.intervalMs,
+    }));
+  }
+
+  // 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,458 @@
+/**
+ * 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 { recordOutboundMessageId } from '../features/outbound-echo-store.js';
+import { recordOutboundToGroupHistory } from '../features/history-store.js';
+import { resolveGroupConfigFromAccount } from '../config.js';
+import { checkAndConsumePassiveReplyQuota } from '../features/quota-manager.js';
+import { recordProactiveSend } from '../features/proactive-budget.js';
+import { getCachedMsgId } from '../features/msgid-cache.js';
+import { notifyOutboundMessageSent } from '../features/typing-refresh.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 已移除，消息不再在此处合并
+    // 所有消息都直接走完中间件链，由 bot.on('message') 处理转发
+    // 并发控制由 OpenClaw 框架的 session lane 机制处理
+    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}`);
+      });
+    });
+
+    // 平台原始事件观测：一切未被 SDK 映射为 message/interaction 的推送
+    // （入群申请、好友变动、reaction、media_upload_finish、未来新增类型）
+    // 都走这里 —— 此前被静默丢弃，是入站诊断的主要盲区
+    this.bot.on('rawEvent', (evt: { eventType?: string; data?: unknown }) => {
+      let preview = '{}';
+      try {
+        preview = JSON.stringify(evt?.data ?? {});
+      } catch {
+        preview = '<unserializable>';
+      }
+      if (preview.length > 300) preview = `${preview.slice(0, 300)}…`;
+      this.log.info(`[rawEvent] t=${evt?.eventType ?? '?'} payload=${preview}`);
+    });
+
+    await this.bot.start(signal);
+  }
+
+  async stop(): Promise<void> {
+    await this.bot.stop();
+  }
+
+  async sendText(target: ReplyTarget, text: string, opts?: SendOptions): Promise<MessageResponse> {
+    const { target: resolved, rollback } = this.attachMsgIdWithQuota(target, opts);
+    if (!resolved.msgId) recordProactiveSend(this.account.accountId);
+    try {
+      const result = await withTimeout(
+        this.bot.sendText(resolved, text),
+        this.textTimeout, 'sendText',
+      );
+      this.notifyTypingRefresh(target);
+      return result;
+    } catch (err) {
+      rollback();
+      throw err;
+    }
+  }
+
+  async sendMedia(
+    target: ReplyTarget,
+    source: string,
+    opts?: SendOptions & { fileType?: MediaFileType },
+  ): Promise<MessageResponse> {
+    const { target: resolvedTarget, rollback } = this.attachMsgIdWithQuota(target, opts);
+    if (!resolvedTarget.msgId) recordProactiveSend(this.account.accountId);
+    const fileType = opts?.fileType ?? MediaFileType.IMAGE;
+    const sourceOpts = resolveMediaSource(source);
+    try {
+      const result = await withTimeout(
+        this.bot.sendMedia({ target: resolvedTarget, fileType, ...sourceOpts, content: opts?.text }),
+        this.mediaTimeout, 'sendMedia',
+      );
+      this.notifyTypingRefresh(target);
+      return result.message ?? { id: '', timestamp: Date.now() };
+    } catch (err) {
+      rollback();
+      throw err;
+    }
+  }
+
+  async sendVoice(
+    target: ReplyTarget,
+    source: { url?: string; base64?: string; localPath?: string },
+    opts?: SendOptions,
+  ): Promise<MessageResponse> {
+    const { target: resolvedTarget, rollback } = this.attachMsgIdWithQuota(target, opts);
+    if (!resolvedTarget.msgId) recordProactiveSend(this.account.accountId);
+
+    const send = (params: Record<string, unknown>, label: string) =>
+      withTimeout(
+        this.bot.sendMedia({
+          target: resolvedTarget,
+          fileType: MediaFileType.VOICE,
+          ...params,
+          content: opts?.text,
+        } as any),
+        this.mediaTimeout, label,
+      );
+    try {
+      let result: { message?: MessageResponse };
+      if (source.base64) {
+        result = await send({ fileData: source.base64 }, 'sendVoice(base64)');
+      } else if (source.localPath) {
+        result = await send({ localPath: source.localPath }, 'sendVoice(path)');
+      } else {
+        result = await send({ url: source.url! }, 'sendVoice(url)');
+      }
+      this.notifyTypingRefresh(target);
+      return result.message ?? { id: '', timestamp: Date.now() };
+    } catch (err) {
+      rollback();
+      throw err;
+    }
+  }
+
+  async sendVideo(
+    target: ReplyTarget,
+    source: string,
+    opts?: SendOptions,
+  ): Promise<MessageResponse> {
+    const { target: resolvedTarget, rollback } = this.attachMsgIdWithQuota(target, opts);
+    if (!resolvedTarget.msgId) recordProactiveSend(this.account.accountId);
+    const sourceOpts = resolveMediaSource(source);
+    try {
+      const result = await withTimeout(
+        this.bot.sendMedia({ target: resolvedTarget, fileType: MediaFileType.VIDEO, ...sourceOpts, content: opts?.text }),
+        this.mediaTimeout, 'sendVideo',
+      );
+      this.notifyTypingRefresh(target);
+      return result.message ?? { id: '', timestamp: Date.now() };
+    } catch (err) {
+      rollback();
+      throw err;
+    }
+  }
+
+  async sendFile(
+    target: ReplyTarget,
+    source: string,
+    opts?: SendOptions & { fileName?: string },
+  ): Promise<MessageResponse> {
+    const { target: resolvedTarget, rollback } = this.attachMsgIdWithQuota(target, opts);
+    if (!resolvedTarget.msgId) recordProactiveSend(this.account.accountId);
+    const sourceOpts = resolveMediaSource(source);
+    try {
+      const result = await withTimeout(
+        this.bot.sendMedia({ target: resolvedTarget, fileType: MediaFileType.FILE, ...sourceOpts, fileName: opts?.fileName, content: opts?.text }),
+        this.mediaTimeout, 'sendFile',
+      );
+      this.notifyTypingRefresh(target);
+      return result.message ?? { id: '', timestamp: Date.now() };
+    } catch (err) {
+      rollback();
+      throw err;
+    }
+  }
+
+  openStream(target: ReplyTarget, msgId: string): StreamSession {
+    return this.bot.openStream({
+      target: { ...target, msgId },
+    });
+  }
+
+  async sendTyping(target: ReplyTarget): Promise<void> {
+    await this.bot.sendTyping(target);
+  }
+
+  /**
+   * 消息发送成功后通知活跃的 typing 会话补发续期。
+   * QQ 客户端收到机器人消息（含思维链等中间输出）会终止"正在输入"
+   * 显示；若框架任务仍在进行，typing 中间件会在 5s 后补发恢复显示。
+   */
+  private notifyTypingRefresh(target: ReplyTarget): void {
+    notifyOutboundMessageSent(this.account.accountId, target.scope, target.targetId);
+  }
+
+  private wrapBotSendForRefIndex(): void {
+    const { accountId, appId } = this.account;
+    const senderName = this.account.config.name ?? appId;
+
+    const storeEntry = (msg: MessageResponse, content: string, target: { scope: string; targetId?: string }, mediaKind?: string): void => {
+      // 出站 id 先登记回声表（不依赖 ext_info.ref_idx 是否返回），
+      // 供 inboundGuard 识别平台回投的 bot 自身消息
+      recordOutboundMessageId(accountId, msg.id);
+
+      // 修复运算符优先级问题：当 content 非空时直接使用，否则回退到媒体标签
+      let finalContent = content;
+      if (!content && mediaKind) {
+        finalContent = mediaKind === 'voice' ? '[语音]'
+          : mediaKind === 'image' ? '[图片]'
+          : mediaKind === 'video' ? '[视频]'
+          : mediaKind === 'file' ? '[文件]'
+          : `[${mediaKind}]`;
+      }
+
+      // rolling 历史模式：群出站记入 historyBuffer（isBot 标记，
+      // 供"裁剪到最后一条 bot 发言"定位；historyLimit=0 或 room_event 群
+      // ——上下文以框架 transcript 为准——时 no-op）
+      if (
+        target.scope === 'group' &&
+        target.targetId &&
+        resolveGroupConfigFromAccount(this.account, target.targetId).unmentionedInbound !== 'room_event'
+      ) {
+        recordOutboundToGroupHistory(accountId, target.targetId, {
+          messageId: msg.id,
+          senderId: appId,
+          senderName,
+          content: finalContent || '[消息]',
+        }, resolveGroupConfigFromAccount(this.account, target.targetId).historyLimit);
+      }
+
+      const refIdx = msg.ext_info?.ref_idx;
+      if (!refIdx) return;
+
+      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: target.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);
+      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();
+        recordOutboundMessageId(accountId, result?.id);
+        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;
+    };
+  }
+
+  /**
+   * 配额感知的 msg_id 挂接（被动优先）。
+   *
+   * - 显式 msgId（opts.msgId）：上游 adapter 已做配额记账（quotaReserved），
+   *   直接透传，不重复消费。
+   * - 无显式 msgId：尝试挂 msgid-cache 最新条目；挂接前经 quota-manager
+   *   原子预检+扣减——配额耗尽则不挂（降级主动，避免平台 40034128 硬失败），
+   *   API 抛错时由调用方 rollback 释放已扣减的额度。
+   */
+  private attachMsgIdWithQuota(
+    target: ReplyTarget,
+    opts?: SendOptions,
+  ): { target: ReplyTarget; rollback: () => void } {
+    if (opts?.msgId) {
+      return { target: { ...target, msgId: opts.msgId }, rollback: () => {} };
+    }
+    const cached = getCachedMsgId(target.scope, target.targetId);
+    if (!cached) return { target, rollback: () => {} };
+
+    const reservation = checkAndConsumePassiveReplyQuota({
+      accountId: this.account.accountId,
+      msgId: cached,
+      scope: target.scope,
+    });
+    if (!reservation.canReply) {
+      // INFO：降级主动消耗每日预算，是出站行为的可观测分界点
+      this.log.info?.(`[quota] passive quota exhausted for msgId=${cached}; falling back to proactive send`);
+      return { target, rollback: () => {} };
+    }
+    return { target: { ...target, msgId: cached }, rollback: reservation.rollback };
+  }
+}
+
+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 };
+}

package/src/gateway-adapter.ts

@@ -0,0 +1,44 @@
+/**
+ * QQBot Gateway 适配器
+ *
+ * 账户启动/停止/登出
+ */
+
+import type { ResolvedQQBotAccount } from './types.js';
+import {
+  startAccountWithCredentialRecovery,
+  stopAccountGracefully,
+  logoutAndClearCredentials,
+} from './gateway/lifecycle.js';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/config-contracts';
+
+/**
+ * QQBot Gateway Adapter
+ */
+export const qqbotGatewayAdapter = {
+  startAccount: async (ctx: {
+    account: ResolvedQQBotAccount;
+    accountId: string;
+    abortSignal: AbortSignal;
+    cfg: OpenClawConfig;
+    log?: any;
+    getStatus: () => Record<string, unknown>;
+    setStatus: (status: any) => void;
+  }) => {
+    return startAccountWithCredentialRecovery(ctx);
+  },
+
+  stopAccount: async (ctx: { accountId: string; log?: any }) => {
+    await stopAccountGracefully({
+      accountId: ctx.accountId,
+      log: ctx.log,
+    });
+  },
+
+  logoutAccount: async (params: {
+    accountId: string;
+    cfg: OpenClawConfig;
+  }) => {
+    return logoutAndClearCredentials(params);
+  },
+};