@karinjs/adapter-qqbot 2.2.1 → 3.0.0

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { AdapterBase, AdapterType, Contact, CreateGroupFolderResponse, DownloadFileOptions, DownloadFileResponse, ElementTypes, ForwardOptions, GetAiCharactersResponse, GetAtAllCountResponse, GetGroupFileListResponse, GetGroupFileSystemInfoResponse, GetGroupHighlightsResponse, GetGroupMuteListResponse, GetRkeyResponse, GroupInfo, GroupMemberInfo, LogMethodNames, Message, MessageResponse, NodeElement, QQGroupHonorInfo, SendMsgResults, Sender, UserInfo, karinToQQBot } from "node-karin";
 import FormData from "form-data";
-
 //#region src/core/api/types.d.ts
 /** 上传富媒体文件场景 */
 type Scene = 'user' | 'group';
@@ -8,8 +7,8 @@ type Scene = 'user' | 'group';
 type MediaType = 'image' | 'video' | 'record' | 'file';
 /** 发送QQ消息请求参数基类 */
 interface SendQQMessageRequest {
-  /** 消息类型：0 是文本，2 是 markdown， 3 ark，4 embed，7 media 富媒体 */
-  msg_type: 0 | 2 | 3 | 4 | 7;
+  /** 消息类型：0 是文本，2 是 markdown， 3 ark，4 embed，6 输入中状态（仅单聊），7 media 富媒体 */
+  msg_type: 0 | 2 | 3 | 4 | 6 | 7;
 }
 /** 消息引用对象 */
 interface MessageReference {
@@ -74,7 +73,9 @@ interface SendQQArkMessageRequest extends SendQQMessageRequest, QQMessageID {
   msg_type: 3;
   /** ark 消息内容 */
   ark: {
-    /** ark 模版id */template_id: number; /** 模版内变量与填充值的kv映射 tips: 未经测试 先any */
+    /** ark 模版id */
+    template_id: number;
+    /** 模版内变量与填充值的kv映射 tips: 未经测试 先any */
     kv: any[];
   };
 }
@@ -84,7 +85,49 @@ interface SendQQMediaMessageRequest extends SendQQMessageRequest, QQMessageID {
   msg_type: 7;
   /** media 消息内容 */
   media: {
-    /** 文件信息，用于发消息接口的 media 字段使用 */file_info: string;
+    /** 文件信息，用于发消息接口的 media 字段使用 */
+    file_info: string;
+  };
+}
+/** 发送QQ流式消息请求参数（POST /v2/users/{openid}/stream_messages，仅单聊） */
+interface SendQQStreamMessageRequest {
+  /**
+   * 输入模式：
+   * - append 增量追加（默认），content_raw 为本次新增内容
+   * - replace 全量替换，content_raw 为全量内容，且必须保持已下发内容前缀不变
+   */
+  input_mode?: 'append' | 'replace';
+  /** 输入状态：1 生成中 / 10 正文结束 */
+  input_state: 1 | 10;
+  /** 流式序号，从 0 开始逐帧递增，同一次流的 msg_seq 保持一致 */
+  index: number;
+  /** 内容类型，默认 text */
+  content_type?: 'text' | 'markdown';
+  /** 内容原文 */
+  content_raw: string;
+  /** 首帧由服务端生成并返回，后续帧需携带 */
+  stream_msg_id?: string;
+  /** 前置事件 ID（被动消息，与 msg_id 二选一） */
+  event_id?: string;
+  /** 前置消息 ID（被动消息，与 event_id 二选一） */
+  msg_id?: string;
+  /** 回复序号，与 msg_id 联合使用 */
+  msg_seq?: number;
+  /** 互动召回消息，与 msg_id、event_id 互斥 */
+  is_wakeup?: boolean;
+}
+/** 发送QQ流式消息响应 */
+interface SendQQStreamMessageResponse {
+  /** 流式消息 ID，后续帧作为 stream_msg_id 携带 */
+  id: string;
+  /** 发送时间 */
+  timestamp: number | string;
+  /** 剩余可发送字数 */
+  remain_msg_len?: number;
+  /** 扩展信息 */
+  ext_info?: {
+    /** 当前发送消息可被引用时使用的索引 */
+    ref_idx?: string;
   };
 }
 /** 发送QQ消息请求参数 */
@@ -138,7 +181,8 @@ interface Embeds {
   prompt: string;
   /** 缩略图 */
   thumbnail: {
-    /** 图片地址 */url: string;
+    /** 图片地址 */
+    url: string;
   };
   /** embed 字段数据 */
   fields: Record<string, any>[];
@@ -156,7 +200,8 @@ interface Ark {
   /** 模版内变量与填充值的kv映射 */
   kv: {
     key: string;
-    value: string; /** 这个嵌套是认真的嘛... */
+    value: string;
+    /** 这个嵌套是认真的嘛... */
     obj: {
       obj_kv: {
         key: string;
@@ -215,9 +260,57 @@ interface SendQQMsgResponse {
   timestamp: number | string;
   /** 扩展信息；部分 QQ 消息发送响应会返回可用于 message_reference 的 REFIDX。 */
   ext_info?: {
-    /** 当前发送消息可被引用时使用的索引。 */ref_idx?: string;
+    /** 当前发送消息可被引用时使用的索引。 */
+    ref_idx?: string;
   };
 }
+/** 获取群基础信息接口响应（GET /v2/groups/{group_openid}/info，白名单接口） */
+interface QQGroupInfoResponse {
+  /** 群 openid */
+  group_openid: string;
+  /** 群名称 */
+  group_name: string;
+  /** 群简介 */
+  group_finger_memo?: string;
+  /** 群分类文本 */
+  group_class_text?: string;
+  /** 群标签 */
+  group_tags?: string[];
+  /** 群成员人数 */
+  group_member_num?: number;
+}
+/** 获取机器人群内状态接口响应（GET /v2/groups/{group_openid}/bot_state，白名单接口） */
+interface GroupBotStateResponse {
+  /** 机器人在群内的 member_openid */
+  member_openid: string;
+  /** 入群时间，RFC3339 格式 */
+  joined_at?: string;
+  /** 是否允许主动发消息 */
+  allow_proactive_msg?: boolean;
+  /** 接收消息设置：all / only_mention / mention_and_context */
+  recv_msg_setting?: string;
+  /** 机器人在群内的角色：owner / admin / member */
+  member_role?: 'owner' | 'admin' | 'member';
+}
+/**
+ * 获取群成员详情接口响应（GET /v2/groups/{group_openid}/members/{member_openid}）
+ *
+ * 该接口未出现在公开文档中，仅在腾讯官方 openclaw 插件
+ * （@tencent-connect/openclaw-qqbot v2.0.0）中被作为一等接口使用，返回结构未公开，
+ * 字段全部按可选处理，实际以平台返回为准。
+ */
+interface QQGroupMemberResponse {
+  /** 群成员 openid */
+  member_openid?: string;
+  /** 群成员昵称 */
+  nick?: string;
+  /** 入群时间，RFC3339 格式 */
+  joined_at?: string;
+  /** 群内角色：owner / admin / member */
+  member_role?: 'owner' | 'admin' | 'member';
+  /** 其余未公开字段原样保留 */
+  [key: string]: unknown;
+}
 /** 发送频道消息后响应 */
 interface SendGuildResponse {
   /** 消息唯一 ID */
@@ -266,6 +359,22 @@ declare class MessagesApi extends Http {
   sendFriendMsg(openid: string, body: SendQQMsg): Promise<SendQQMsgResponse>;
   /** 群聊消息 */
   sendGroupMsg(groupOpenid: string, body: SendQQMsg): Promise<SendQQMsgResponse>;
+  /**
+   * 单聊输入中状态（msg_type=6，仅单聊）
+   * @param openid 用户 openid
+   * @param inputSecond 展示时长（秒），默认 60
+   * @param passive 被动消息参数（msg_id / event_id / msg_seq），可选
+   */
+  sendFriendInputNotify(openid: string, inputSecond?: number, passive?: QQMessageID): Promise<SendQQMsgResponse>;
+  /**
+   * 单聊流式消息（仅单聊）
+   *
+   * 首帧不带 stream_msg_id，响应的 id 作为后续帧的 stream_msg_id 回传；
+   * 同一次流 index 从 0 递增、msg_seq 保持一致；建议帧间隔 300~500ms。
+   * @param openid 用户 openid
+   * @param body 流式消息帧
+   */
+  sendFriendStreamMsg(openid: string, body: SendQQStreamMessageRequest): Promise<SendQQStreamMessageResponse>;
   /** 文字子频道消息 */
   sendChannelMsg(channelId: string, body: SendGuildMsg | FormData): Promise<SendGuildResponse>;
   /**
@@ -387,6 +496,34 @@ declare class MetaApi extends Http {
   }>;
 }
 //#endregion
+//#region src/core/api/groups.d.ts
+/**
+ * QQ 群信息接口
+ *
+ * 注意：以下接口均为白名单接口，未开通权限时平台返回错误码 11253，
+ * 需要向平台运营申请后可用。
+ */
+declare class GroupsApi extends Http {
+  /**
+   * 获取群基础信息
+   * @param groupOpenid 群 openid
+   */
+  getGroupInfo(groupOpenid: string): Promise<QQGroupInfoResponse>;
+  /**
+   * 获取机器人在群内的状态（角色、入群时间、主动消息开关等）
+   * @param groupOpenid 群 openid
+   */
+  getBotState(groupOpenid: string): Promise<GroupBotStateResponse>;
+  /**
+   * 获取群成员详情
+   *
+   * 未公开文档，来自腾讯官方 openclaw 插件（v2.0.0）的接口速查。
+   * @param groupOpenid 群 openid
+   * @param memberOpenid 群成员 openid
+   */
+  getGroupMember(groupOpenid: string, memberOpenid: string): Promise<QQGroupMemberResponse>;
+}
+//#endregion
 //#region src/core/api/index.d.ts
 /**
  * QQBot 官方 API 门面
@@ -396,6 +533,7 @@ declare class MetaApi extends Http {
  * - media：富媒体上传
  * - interaction：按钮回调 ack
  * - meta：@me / dms / gateway
+ * - groups：群基础信息 / 机器人群内状态（白名单接口）
  *
  * 请求体构造器 {@link buildQQMsg} / {@link buildGuildMsg} 独立导出，避免与 HTTP 调用耦合
  */
@@ -405,6 +543,7 @@ declare class QQBotApi {
   readonly media: MediaApi;
   readonly interaction: InteractionApi;
   readonly meta: MetaApi;
+  readonly groups: GroupsApi;
   /** 请求体构造器（静态便利） */
   readonly qq: {
     text(content: string): SendQQTextMessageRequest;
@@ -422,6 +561,85 @@ declare class QQBotApi {
   constructor(axios: AxiosInstance);
 }
 //#endregion
+//#region src/types/config.d.ts
+/**
+ * 自定义连接代理配置
+ */
+interface QQBotProxyConfig {
+  /** 正式环境 API */
+  prodApi: string;
+  /** 测试环境 API */
+  sandboxApi: string;
+  /** 调用凭证 API */
+  tokenApi: string;
+  /** 正式环境 WebSocket 网关 */
+  prodWs: string;
+  /** 测试环境 WebSocket 网关 */
+  sandboxWs: string;
+}
+/**
+ * 消息缓存存储分级。
+ *
+ * - minimal: 只存 ID 映射与引用关系（reply 段），撤回 / 引用解析可用，正文不落库；
+ * - standard: 额外保存文本、表情与媒体本地路径，markdown 原文不落库；
+ * - full: 全部可缓存消息段原样保存。
+ */
+type MessageCacheLevel = 'minimal' | 'standard' | 'full';
+/**
+ * 单个 QQBot 配置
+ */
+interface QQBotConfig {
+  /** 机器人名称 */
+  name: string;
+  /** 机器人 ID */
+  appId: string;
+  /** 机器人密钥 */
+  secret: string;
+  /** 自定义连接代理 */
+  proxy: QQBotProxyConfig;
+  /** 开启沙盒环境 */
+  sandbox: boolean;
+  /** 开启 QQ 场景能力（单聊 / 群聊） */
+  qqEnable: boolean;
+  /** 开启频道场景能力 */
+  guildEnable: boolean;
+  /** 频道场景模式 0 公域 / 1 私域 */
+  guildMode: 0 | 1;
+  /** 收到消息后对文本进行表达式处理 */
+  regex: {
+    reg: string | RegExp;
+    rep: string;
+  }[];
+  /** 按钮自动化 */
+  keyboard: {
+    /** 是否将文本中的 URL 自动转换为 keyboard 按钮 */
+    enable: boolean;
+  };
+  /** Markdown 通道 */
+  markdown: {
+    /** 是否启用 Markdown 通道发送消息 */
+    enable: boolean;
+  };
+  /** 消息缓存配置 */
+  messageCache: {
+    /** 是否启用数据库消息缓存，用于 bot.getMsg */
+    enable: boolean;
+    /** 是否缓存机器人自己发送的消息 */
+    self: boolean;
+    /** 存储分级，控制单条消息的落库体积 */
+    level: MessageCacheLevel;
+    /** 缓存保留小时数；多个 bot 同时开启时取最大值 */
+    ttlHours: number;
+    /** 消息缓存最大行数，超出后删除最旧；多个 bot 同时开启时取最大值 */
+    maxRows: number;
+  };
+  /** 事件接收配置 */
+  event: {
+    /** 接收方式 0 关闭 / 1 webhook / 2 ws */
+    type: 0 | 1 | 2;
+  };
+}
+//#endregion
 //#region src/core/storage/message-store/types.d.ts
 interface CachedMessage {
   messageId: string;
@@ -431,63 +649,75 @@ interface CachedMessage {
   sender: Sender;
   elements: ElementTypes[];
 }
+/** 保存消息时的附加标记。 */
+interface SaveOptions {
+  /** QQ 客户端引用使用的 `msg_idx`（REFIDX），作为消息的第二查询索引。 */
+  refIdx?: string;
+  /** 是否是机器人自己发送的消息，用于单聊撤回判定。 */
+  isSelf?: boolean;
+  /** 存储分级；缺省按 standard 处理。 */
+  level?: MessageCacheLevel;
+}
 //#endregion
 //#region src/core/storage/message-store/store.d.ts
 /**
  * QQBot 收到的消息缓存。
  *
- * 热路径只写内存并入队，不等待 SQLite：
- * - `getMsg` 优先查内存，插件在同一事件回调内可立即命中；
- * - SQLite 在后台按批次事务落库，避免一条消息一个事务拖慢事件分发；
- * - 元素表只保存 `type + value`，避免宽表 NULL 和多详情表多次 INSERT。
+ * SQLite 是唯一数据层，没有内存镜像：
+ * - 写入热路径只入队，后台按批次事务落库，每条消息稳定 2~3 次语句
+ *   往返（prepared statement 复用）；
+ * - 所有读取直接查 SQLite（WAL + 整数 hash 索引，点查亚毫秒级）；
+ *   读取前先排空待写队列，保证"读到自己刚写的数据"。
  */
 declare class MessageStore {
   private db?;
   private readonly ready;
-  private lastCleanup;
   private shouldVacuum;
   private flushTimer?;
-  private flushing;
+  private flushActive?;
   private mediaTimer?;
   private mediaActive;
-  private readonly pending;
-  private readonly pendingMedia;
+  private pending;
+  private pendingMedia;
   private readonly pendingMediaKeys;
-  private readonly memory;
-  private readonly directIndex;
-  private readonly aliasIndex;
-  private readonly scopedAliasIndex;
-  private readonly botRefCache;
+  private readonly statements;
   private readonly contactRefCache;
   private readonly senderRefCache;
+  /** 当前生效的缓存保留时长；由配置解析，多 bot 取最大值。 */
+  private ttlMs;
+  /** 当前生效的消息行数硬上限；由配置解析，多 bot 取最大值。 */
+  private maxRows;
   constructor();
   /**
    * 立即执行一次过期消息和本地媒体缓存清理。
    *
-   * 该方法交给 Karin `task` 调度调用；类内部只保留清理能力，不自行维护常驻定时器。
+   * 该方法交给 Karin `task` 调度调用；读写路径不再内嵌清理，避免尾延迟。
    *
    * @returns 清理完成 Promise。
    */
   cleanupExpired(): Promise<void>;
   /**
-   * 保存实际消息，并为 QQ 的 `msg_idx` 等引用索引建立轻量映射。
+   * 保存实际消息。
    *
-   * 该方法只同步写入内存并投递后台队列，不等待 SQLite。这样消息事件创建不会被
+   * 只克隆快照并投递后台队列，不等待 SQLite，消息事件创建不会被
    * 数据库写锁或小事务阻塞。
    *
    * @param botId 当前 QQBot appId。
    * @param message 已转换为 Karin elements 的消息缓存。
-   * @param aliases 可查询到该消息的额外消息索引，例如 QQ `msg_idx`。
+   * @param options 引用索引与自己消息标记。
    */
-  save(botId: string, message: CachedMessage, aliases?: string[]): Promise<void>;
+  save(botId: string, message: CachedMessage, options?: SaveOptions): Promise<void>;
   /**
-   * 仅当内存中没有该引用索引时保存 QQ 下发的引用上下文。
-   * 数据库是否已存在由后台 flush 再判断，避免阻塞事件热路径。
+   * 保存 QQ 下发的引用上下文。
+   *
+   * 是否已有同 ID 缓存（原消息或引用索引）由后台 flush 在事务内判断并去重，
+   * 避免阻塞事件热路径。
    *
    * @param botId 当前 QQBot appId。
    * @param message 以 `ref_msg_idx` 作为 messageId 的引用上下文。
+   * @param level 存储分级；缺省按 standard 处理。
    */
-  saveReferenceIfAbsent(botId: string, message: CachedMessage): Promise<void>;
+  saveReferenceIfAbsent(botId: string, message: CachedMessage, level?: SaveOptions['level']): Promise<void>;
   /**
    * 读取缓存消息。
    *
@@ -513,11 +743,68 @@ declare class MessageStore {
    */
   getHistory(botId: string, contact: Contact, startMsgId: string, count: number): Promise<MessageResponse[]>;
   /**
-   * 初始化 SQLite 连接、表结构，并执行启动清理和媒体本地化补救。
+   * 将 QQ `REFIDX` 引用索引解析为 API 消息 ID。
+   *
+   * 撤回等平台接口的唯一映射来源；ID 映射行不受缓存开关影响，始终落库。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact 消息所在会话。
+   * @param refIdx QQ 引用索引，通常为 REFIDX_...。
+   * @returns 对应的 API 消息 ID；未命中时返回 null。
+   */
+  resolveApiMessageId(botId: string, contact: Contact, refIdx: string): Promise<string | null>;
+  /**
+   * 将 API 消息 ID 反向解析为 QQ `REFIDX` 引用索引。
+   *
+   * 发送侧显式引用回复的唯一映射来源。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact 消息所在会话。
+   * @param messageId QQ API 消息 ID，通常为 ROBOT1.0_...。
+   * @returns 对应的引用索引；未命中时返回 null。
+   */
+  resolveRefIdx(botId: string, contact: Contact, messageId: string): Promise<string | null>;
+  /**
+   * 读取持久化的 file_info 上传缓存。
+   *
+   * @param key 由 api 层构造的缓存键。
+   * @returns 序列化的上传响应 JSON；未命中或已过期时返回 null。
+   */
+  getUploadCache(key: string): Promise<string | null>;
+  /**
+   * 写入持久化的 file_info 上传缓存。
+   *
+   * @param key 由 api 层构造的缓存键。
+   * @param response 序列化的上传响应 JSON。
+   * @param expiresAt 失效时间戳；0 表示长期有效。
+   */
+  setUploadCache(key: string, response: string, expiresAt: number): Promise<void>;
+  /**
+   * 判断消息是否由机器人自己发送。
+   *
+   * 单聊撤回判定的唯一来源，读取消息行的 `is_self` 标记。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact 消息所在会话。
+   * @param messageId QQ API 消息 ID。
+   * @returns true 表示是机器人自己发送的消息。
+   */
+  isSelfMessage(botId: string, contact: Contact, messageId: string): Promise<boolean>;
+  /**
+   * 初始化 SQLite 连接、表结构，并执行一次启动清理。
+   *
+   * 远程媒体补救不在这里执行，避免阻塞 `ready` 拖慢首批消息落库。
    *
    * @returns 初始化完成 Promise。
    */
   private initialize;
+  /**
+   * 从配置解析当前生效的 TTL 与行数上限。
+   *
+   * 数据库为全 bot 共享，多个 bot 同时开启缓存时取最大值；配置读取失败时
+   * 保持当前值。每次清理前刷新，配置修改最迟 10 分钟内生效。
+   */
+  private refreshSettings;
   /**
    * 投递待落库消息。
    *
@@ -530,6 +817,18 @@ declare class MessageStore {
    * 已有 timer 或正在 flush 时不会重复安排。
    */
   private scheduleFlush;
+  /**
+   * 触发一次批量落库；已有进行中的 flush 时复用其 Promise。
+   *
+   * @returns 当前批次落库完成的 Promise。
+   */
+  private flushQueue;
+  /**
+   * 等待写入队列完全清空。
+   *
+   * 所有读取入口先经过它，保证"读到自己刚写的数据"；队列为空时零开销。
+   */
+  private flushAll;
   /**
    * 批量落库队列中的消息。
    *
@@ -537,11 +836,14 @@ declare class MessageStore {
    *
    * @returns flush 完成 Promise。
    */
-  private flushQueue;
+  private doFlushBatch;
   /**
    * 写入一条待落库消息。
    *
-   * @param item 待写入的消息、alias 和引用上下文标记。
+   * 稳定状态下（contact/sender 已缓存）每条消息 2 次语句往返：
+   * 定位既有行 + INSERT 或 UPDATE。
+   *
+   * @param item 待写入的消息任务。
    */
   private writeItem;
   /**
@@ -556,7 +858,8 @@ declare class MessageStore {
    *
    * @param botId 当前 QQBot appId。
    * @param message 可能包含远程媒体 URL 的消息快照。
-   * @param aliases 该消息可被查询到的额外 alias。
+   * @param refIdx 该消息的引用索引，成功本地化后随消息一并回写。
+   * @param isSelf 是否机器人自己发送。
    */
   private enqueueMediaLocalize;
   /**
@@ -580,47 +883,25 @@ declare class MessageStore {
   private localizeMediaItem;
   /**
    * 清理已经过期的媒体本地化待处理任务。
-   *
-   * @returns 无返回值；会同步维护 pendingMediaKeys。
    */
   private prunePendingMedia;
   /**
-   * 启动时扫描 SQLite 中尚未本地化的远程媒体 URL，并重新投递队列补救。
+   * 启动时扫描 SQLite 中尚未本地化的远程媒体消息，并重新投递队列补救。
+   *
+   * `has_remote_media` 是部分索引列，扫描不再需要 LIKE 全表匹配。
    *
    * @returns 扫描和投递完成 Promise。
    */
   private recoverRemoteMedia;
   /**
-   * 写入内存热缓存。
-   *
-   * @param botId 当前 QQBot appId。
-   * @param message 消息缓存。
-   * @param aliases 可查询到该消息的额外消息索引。
-   */
-  private putMemory;
-  /**
-   * 从内存热缓存读取消息。
+   * 按消息 ID 或引用索引查询消息行。
    *
    * @param botId 当前 QQBot appId。
-   * @param messageId 真实消息 ID 或 alias。
+   * @param messageId 真实消息 ID 或 `REFIDX` 引用索引。
    * @param contact 可选会话范围。
-   * @returns 命中的缓存消息；未命中或过期时返回 null。
-   */
-  private getFromMemory;
-  /**
-   * 到达清理间隔时清理内存缓存。
-   */
-  private cleanupMemoryIfDue;
-  /**
-   * 清理一天前的内存消息，并同步清理失效索引。
-   */
-  private cleanupMemory;
-  /**
-   * 清理指向已删除内存消息的索引。
-   *
-   * @param index 需要清理的索引 Map。
+   * @returns 命中的消息行；未命中时返回 null。
    */
-  private cleanIndex;
+  private queryMessageRow;
   /**
    * 浅拷贝消息缓存，避免后续事件对象被插件侧修改后污染缓存。
    *
@@ -629,54 +910,12 @@ declare class MessageStore {
    */
   private cloneMessage;
   /**
-   * 将内存缓存转换为 Karin `MessageResponse`。
+   * 将数据库行还原为 Karin `MessageResponse`。
    *
-   * @param message 内存缓存消息。
+   * @param row 消息主查询结果。
    * @returns Karin 标准消息查询结果。
    */
-  private toResponse;
-  /**
-   * 执行数据库版本迁移。
-   *
-   * 使用 SQLite `PRAGMA user_version` 记录已应用的 schema 版本。
-   * 版本 0 只表示“未初始化或开发期旧库”，首个 alpha 发布基线为 v1。
-   *
-   * @returns 迁移完成 Promise。
-   */
-  private migrate;
-  /**
-   * 获取或创建 bot 映射 ID。
-   *
-   * @param botId 当前 QQBot appId。
-   * @returns `qqbot_bots.id`。
-   */
-  private ensureBot;
-  /**
-   * 获取或创建会话映射 ID。
-   *
-   * @param botRef `qqbot_bots.id`。
-   * @param contact Karin 会话对象。
-   * @returns `qqbot_contacts.id`。
-   */
-  private ensureContact;
-  /**
-   * 获取或创建发送者映射 ID。
-   *
-   * @param botRef `qqbot_bots.id`。
-   * @param sender Karin sender 对象。
-   * @returns `qqbot_senders.id`。
-   */
-  private ensureSender;
-  /**
-   * 获取或创建消息主记录。
-   *
-   * @param botRef `qqbot_bots.id`。
-   * @param contactRef `qqbot_contacts.id`。
-   * @param senderRef `qqbot_senders.id`。
-   * @param message 消息缓存。
-   * @returns `qqbot_messages.id`。
-   */
-  private ensureMessage;
+  private rowToResponse;
   /**
    * 从查询行还原 Karin Contact。
    *
@@ -685,63 +924,24 @@ declare class MessageStore {
    */
   private contactFromRow;
   /**
-   * 将数据库行还原为 Karin `MessageResponse`。
-   *
-   * @param row 消息主查询结果。
-   * @returns Karin 标准消息查询结果。
-   */
-  private rowToResponse;
-  /**
-   * 在指定会话中解析消息 ID 或 alias 到消息主表行。
-   *
-   * @param botId 当前 QQBot appId。
-   * @param contact Karin 会话对象。
-   * @param messageId 真实消息 ID 或 alias。
-   * @returns 命中的消息行；未命中时返回 null。
-   */
-  private resolveMessageRow;
-  /**
-   * 构造会话级查询键。
-   *
-   * @param botId 当前 QQBot appId。
-   * @param contact Karin 会话对象。
-   * @param messageId 消息 ID 或 alias。
-   * @returns 用于 SQL 参数或内存 key 的字段数组。
-   */
-  private contactKey;
-  /**
-   * 构造内存会话级 key。
+   * 获取或创建会话映射 ID。
    *
    * @param botId 当前 QQBot appId。
    * @param contact Karin 会话对象。
-   * @param messageId 消息 ID 或 alias。
-   * @returns 内存 Map 使用的稳定 key。
+   * @returns `qqbot_contacts.id`。
    */
-  private scopedKey;
+  private ensureContact;
   /**
-   * 构造内存全局 key。
+   * 获取或创建发送者映射 ID。
    *
-   * @param botId 当前 QQBot appId。
-   * @param messageId 消息 ID 或 alias。
-   * @returns 不限定会话时使用的内存 key。
-   */
-  private globalKey;
-  /**
-   * 删除指定会话下的 alias。
+   * sender 按 (userId, nick, name, role) 去重；不再被引用的行由清理任务 GC，
+   * 不会随昵称变化永久膨胀。
    *
    * @param botId 当前 QQBot appId。
-   * @param contact Karin 会话对象。
-   * @param messageId 需要删除的 alias ID。
-   */
-  private deleteAlias;
-  /**
-   * 判断某条消息是否包含指向指定 ID 的 reply 段。
-   *
-   * @param messageRef `qqbot_messages.id`。
-   * @param replyId 被引用的消息 ID。
-   * @returns true 表示该消息包含对应 reply 段。
+   * @param sender Karin sender 对象。
+   * @returns `qqbot_senders.id`。
    */
-  private hasReplyTo;
+  private ensureSender;
   /**
    * 判断消息是否已经超过本地缓存 TTL。
    *
@@ -750,15 +950,21 @@ declare class MessageStore {
    */
   private isExpired;
   /**
-   * 到达清理间隔时清理内存和 SQLite 过期消息。
+   * 清理过期缓存消息，并执行体积治理。
+   *
+   * 依次执行：配置刷新、TTL 删除、硬上限删除、上传缓存清理、
+   * sender GC（写空闲时）、增量 vacuum 归还空间、WAL checkpoint 截断、
+   * 媒体文件清理。
    */
-  private cleanupIfDue;
+  private cleanup;
   /**
-   * 清理一天前的缓存消息。
+   * 执行数据库版本迁移。
    *
-   * SQLite 只删除主消息表，消息段和 alias 通过外键级联删除。
+   * 使用 SQLite `PRAGMA user_version` 记录已应用的 schema 版本。
+   *
+   * @returns 迁移完成 Promise。
    */
-  private cleanup;
+  private migrate;
   /**
    * 判断 SQLite 表是否存在。
    *
@@ -779,12 +985,6 @@ declare class MessageStore {
    * @returns 当前 `PRAGMA user_version`；新库默认为 0。
    */
   private getUserVersion;
-  /**
-   * 写入 SQLite schema 版本。
-   *
-   * @param version 已成功应用的数据库版本号。
-   */
-  private setUserVersion;
   /**
    * 在 `BEGIN IMMEDIATE` 事务中执行写操作。
    *
@@ -792,88 +992,66 @@ declare class MessageStore {
    */
   private transaction;
   /**
-   * 执行不返回行的 SQL。
+   * 获取当前数据库连接。
+   *
+   * @returns 已初始化的 sqlite3 Database。
+   */
+  private database;
+  /**
+   * 获取（并缓存）prepared statement。
+   *
+   * 热路径 SQL 只 parse 一次，重复执行只做参数绑定。
+   *
+   * @param sql SQL 字符串。
+   * @returns 复用的 Statement。
+   */
+  private prepared;
+  /**
+   * 以 prepared statement 执行不返回行的 SQL。
    *
    * @param sql SQL 字符串。
    * @param params SQL 参数。
    */
-  private run;
+  private runS;
   /**
-   * 查询单行数据。
+   * 以 prepared statement 查询单行数据。
    *
    * @param sql SQL 字符串。
    * @param params SQL 参数。
    * @returns 查询结果；未命中时返回 undefined。
    */
-  private getRow;
+  private getS;
   /**
-   * 查询多行数据。
+   * 以 prepared statement 查询多行数据。
    *
    * @param sql SQL 字符串。
    * @param params SQL 参数。
    * @returns 查询结果数组。
    */
-  private getRows;
-}
-//#endregion
-//#region src/types/config.d.ts
-/**
- * 自定义连接代理配置
- */
-interface QQBotProxyConfig {
-  /** 正式环境 API */
-  prodApi: string;
-  /** 测试环境 API */
-  sandboxApi: string;
-  /** 调用凭证 API */
-  tokenApi: string;
-  /** 正式环境 WebSocket 网关 */
-  prodWs: string;
-  /** 测试环境 WebSocket 网关 */
-  sandboxWs: string;
-}
-/**
- * 单个 QQBot 配置
- */
-interface QQBotConfig {
-  /** 机器人名称 */
-  name: string;
-  /** 机器人 ID */
-  appId: string;
-  /** 机器人密钥 */
-  secret: string;
-  /** 自定义连接代理 */
-  proxy: QQBotProxyConfig;
-  /** 开启沙盒环境 */
-  sandbox: boolean;
-  /** 开启 QQ 场景能力（单聊 / 群聊） */
-  qqEnable: boolean;
-  /** 开启频道场景能力 */
-  guildEnable: boolean;
-  /** 频道场景模式 0 公域 / 1 私域 */
-  guildMode: 0 | 1;
-  /** 收到消息后对文本进行表达式处理 */
-  regex: {
-    reg: string | RegExp;
-    rep: string;
-  }[];
-  /** 按钮自动化 */
-  keyboard: {
-    /** 是否将文本中的 URL 自动转换为 keyboard 按钮 */enable: boolean;
-  };
-  /** Markdown 通道 */
-  markdown: {
-    /** 是否启用 Markdown 通道发送消息 */enable: boolean;
-  };
-  /** 消息缓存配置 */
-  messageCache: {
-    /** 是否启用数据库消息缓存，用于 bot.getMsg */enable: boolean; /** 是否缓存机器人自己发送的消息 */
-    self: boolean;
-  };
-  /** 事件接收配置 */
-  event: {
-    /** 接收方式 0 关闭 / 1 webhook / 2 ws */type: 0 | 1 | 2;
-  };
+  private allS;
+  /**
+   * 执行一次性 SQL（DDL、PRAGMA、事务控制），不走 prepared statement 缓存。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   */
+  private exec;
+  /**
+   * 一次性查询单行（PRAGMA / 系统表）。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   * @returns 查询结果；未命中时返回 undefined。
+   */
+  private rawGet;
+  /**
+   * 一次性查询多行（PRAGMA / 系统表）。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   * @returns 查询结果数组。
+   */
+  private rawAll;
 }
 //#endregion
 //#region src/core/adapter/base.d.ts
@@ -906,6 +1084,8 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
    * 撤回消息
    *
    * 群聊中机器人被群主设为管理员后，也可撤回成员消息；平台仍限制消息发送后两分钟内。
+   * REFIDX 与 API 消息 ID 的映射、单聊"是否自己发送"的判定都直接查询
+   * SQLite 消息缓存（ID 映射行不受缓存开关影响，始终落库）。
    */
   recallMsg(contact: Contact, messageId: string): Promise<void>;
   /**
@@ -1020,6 +1200,9 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   getFriendList(_refresh?: boolean): Promise<Array<UserInfo>>;
   /**
    * 获取群信息
+   *
+   * 走官方 `GET /v2/groups/{group_openid}/info`（白名单接口）。
+   * 未开通权限（11253）或查询失败时降级为空结构并告警。
    */
   getGroupInfo(_groupId: string, _noCache?: boolean): Promise<GroupInfo>;
   /**
@@ -1028,6 +1211,11 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   getGroupList(_refresh?: boolean): Promise<Array<GroupInfo>>;
   /**
    * 获取群成员信息
+   *
+   * - 查询机器人自身（targetId 为 selfId）走官方 `GET /v2/groups/{group_openid}/bot_state`（白名单）。
+   * - 查询其他成员走 `GET /v2/groups/{group_openid}/members/{member_openid}`，
+   *   该接口未公开文档，来自腾讯官方 openclaw 插件 v2.0.0，返回结构以平台实际为准。
+   * 接口不可用（如白名单未开通返回 11253）时降级为占位结构并告警。
    */
   getGroupMemberInfo(_groupId: string, _targetId: string, _refresh?: boolean): Promise<GroupMemberInfo>;
   /**
@@ -1056,6 +1244,10 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   setMsgReaction(_contact: Contact, _messageId: string, _faceId: number | string, _isSet: boolean): Promise<void>;
   /**
    * 上传群文件、私聊文件
+   *
+   * QQ 官方 Bot API 没有群文件系统，上传走 `POST /v2/{users|groups}/{openid}/files`
+   * （file_type=4 + srv_send_msg=true），由服务端直接发送文件消息。
+   * 频道 / 频道私信场景官方无文件接口，暂不支持。
    */
   uploadFile(_contact: Contact, _file: string, _name: string, _folder?: string): Promise<void>;
   /**
@@ -1076,6 +1268,8 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   delGroupFolder(_groupId: string, _folderId: string): Promise<boolean>;
   /**
    * 上传群文件
+   *
+   * 实现同 {@link uploadFile}：官方无群文件系统，走 files 接口由服务端直发文件消息。
    */
   uploadGroupFile(_groupId: string, _file: string, _name?: string): Promise<boolean>;
   /**