@karinjs/adapter-qqbot 1.3.1 → 2.1.0

package/dist/index.d.ts

@@ -1,499 +1,1141 @@
-import FormData from 'form-data';
-import * as axios from 'axios';
-import { karinToQQBot, AdapterBase, LogMethodNames, Contact, ButtonElement, KeyboardElement, MarkdownElement, MarkdownTplElement, SendMsgResults } from 'node-karin';
-
-/**
- * @description 创建axios实例
- * @param url 请求地址
- * @param appId 机器人ID
- */
-declare const createAxiosInstance: (url: string, appId: string) => axios.AxiosInstance;
+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';
 /** 上传富媒体文件类型 */
 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，7 media 富媒体 */
+  msg_type: 0 | 2 | 3 | 4 | 7;
+}
+/** 消息引用对象 */
+interface MessageReference {
+  /** 需要引用回复的消息 id */
+  message_id: string;
+  /** 是否忽略获取引用消息详情错误，默认否 */
+  ignore_get_message_error?: boolean;
 }
 /** 发送QQ被动消息参数 */
 interface QQMessageID {
-    /** 前置收到的事件 ID，用于发送被动消息，支持事件："INTERACTION_CREATE"、"C2C_MSG_RECEIVE"、"FRIEND_ADD" */
-    event_id?: string;
-    /** 前置收到的用户发送过来的消息 ID，用于发送被动（回复）消息 */
-    msg_id?: string;
-    /** 回复消息的序号，与 msg_id 联合使用，避免相同消息id回复重复发送，不填默认是1。相同的 msg_id + msg_seq 重复发送会失败。 */
-    msg_seq?: number;
+  /** 前置收到的事件 ID，用于发送被动消息，支持事件："INTERACTION_CREATE"、"C2C_MSG_RECEIVE"、"FRIEND_ADD" */
+  event_id?: string;
+  /** 前置收到的用户发送过来的消息 ID，用于发送被动（回复）消息 */
+  msg_id?: string;
+  /** 回复消息的序号，与 msg_id 联合使用，避免相同消息id回复重复发送，不填默认是1。相同的 msg_id + msg_seq 重复发送会失败。 */
+  msg_seq?: number;
+  /** 指明发送消息为互动召回消息，与 msg_id，event_id 互斥使用 */
+  is_wakeup?: boolean;
+  /** 引用消息对象，QQ单聊和群聊场景均支持 */
+  message_reference?: MessageReference;
 }
 /** 发送QQ文本消息请求参数 */
 interface SendQQTextMessageRequest extends SendQQMessageRequest, QQMessageID {
-    msg_type: 0;
-    /**
-     * 消息内容 支持如下内嵌格式
-     * - `<qqbot-at-user id="" />` `@用户` **注意双引号不能省略**
-     * - `<qqbot-at-everyone />` `@所有人`
-     */
-    content: string;
-}
-/** markdown消息结构 */
-type Markdown = {
-    /** markdown 文本 */
-    content: string;
-} | {
-    /** markdown 模版id，申请模版后获得 */
-    custom_template_id: string;
-    /** 模版内变量与填充值的kv映射 */
-    params: {
-        key: string;
-        values: string[];
-    }[];
-};
-/** 按钮消息结构 */
-type Keyboard = {
-    content: {
-        rows: ReturnType<typeof karinToQQBot>;
-    };
-} | {
-    /** 按钮模版id */
-    id: string;
-};
+  msg_type: 0;
+  /**
+   * 消息内容 支持如下内嵌格式
+   * - `<qqbot-at-user id="" />` `@用户` **注意双引号不能省略**
+   * - `<qqbot-at-everyone />` `@所有人`
+   */
+  content: string;
+}
+/** markdown 消息结构（官方已全量开放原生 markdown，2.0 不再支持模板模式） */
+interface Markdown {
+  /** markdown 文本 */
+  content: string;
+}
+/** 按钮消息结构（官方已全量开放自定义 keyboard，2.0 不再支持模板按钮） */
+interface Keyboard {
+  content: {
+    rows: ReturnType<typeof karinToQQBot>;
+  };
+}
 /** 发送QQ Markdown 消息请求参数 */
 interface SendQQMarkdownMessageRequest extends SendQQMessageRequest, QQMessageID {
-    msg_type: 2;
-    /**
-     * markdown 消息内容 支持如下内嵌格式
-     * - `<qqbot-cmd-enter text="xxx" />` `回车按钮: 点击后，文本直接发送`
-     * - `<qqbot-cmd-input text="xxx" show="xxx" reference="false" />` `点击后，文本输入框弹出`
-     * - `text 用户点击后插入输入框的文本，参数必填，最大限制 100 字符，传值时需要 urlencode`
-     * - `show 用户在消息内看到的文本，参数选填，默认取 text 值，最大限制 100 字符，传值时需要 urlencode。`
-     * - `reference 插入输入框时是否带消息原文回复引用，参数选填，默认为 false，填入 true 时则带引用回复到输入框中。`
-     *
-     * {@link https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/trans/text-chain.html}
-     */
-    markdown: Markdown;
-    /** 按钮 */
-    keyboard?: Keyboard;
+  msg_type: 2;
+  /**
+   * markdown 消息内容 支持如下内嵌格式
+   * - `<qqbot-cmd-enter text="xxx" />` `回车按钮: 点击后，文本直接发送`
+   * - `<qqbot-cmd-input text="xxx" show="xxx" reference="false" />` `点击后，文本输入框弹出`
+   * - `text 用户点击后插入输入框的文本，参数必填，最大限制 100 字符，传值时需要 urlencode`
+   * - `show 用户在消息内看到的文本，参数选填，默认取 text 值，最大限制 100 字符，传值时需要 urlencode。`
+   * - `reference 插入输入框时是否带消息原文回复引用，参数选填，默认为 false，填入 true 时则带引用回复到输入框中。`
+   *
+   * {@link https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/trans/text-chain.html}
+   */
+  markdown: Markdown;
+  /** 按钮 */
+  keyboard?: Keyboard;
 }
 /** 发送QQ Ark 消息请求参数 */
 interface SendQQArkMessageRequest extends SendQQMessageRequest, QQMessageID {
-    msg_type: 3;
-    /** ark 消息内容 */
-    ark: {
-        /** ark 模版id */
-        template_id: number;
-        /** 模版内变量与填充值的kv映射 tips: 未经测试 先any */
-        kv: any[];
-    };
+  msg_type: 3;
+  /** ark 消息内容 */
+  ark: {
+    /** ark 模版id */template_id: number; /** 模版内变量与填充值的kv映射 tips: 未经测试 先any */
+    kv: any[];
+  };
 }
 /** 发送QQ Embed 消息请求参数 文档没看到发送接口 */
 /** 发送QQ Media 消息请求参数 */
 interface SendQQMediaMessageRequest extends SendQQMessageRequest, QQMessageID {
-    msg_type: 7;
-    /** media 消息内容 */
-    media: {
-        /** 文件信息，用于发消息接口的 media 字段使用 */
-        file_info: string;
-    };
-    /** 当 msg_type = 7 时，content 字段需要填入一个值，譬如一个空格 “ ”，后续版本会修复该问题。 */
-    content: string;
+  msg_type: 7;
+  /** media 消息内容 */
+  media: {
+    /** 文件信息，用于发消息接口的 media 字段使用 */file_info: string;
+  };
 }
 /** 发送QQ消息请求参数 */
 type SendQQMsg = SendQQTextMessageRequest | SendQQMarkdownMessageRequest | SendQQArkMessageRequest | SendQQMediaMessageRequest;
 /** 发送频道被动消息参数 */
 interface SendGuildMessageID {
-    /** 消息ID */
-    msg_id?: string;
-    /** 事件id */
-    event_id?: string;
+  /** 消息ID */
+  msg_id?: string;
+  /** 事件id */
+  event_id?: string;
+  /** 引用消息对象 */
+  message_reference?: MessageReference;
 }
 /** 发送频道引用消息参数 */
 interface SendGuildQuoteMessage {
-    /** 引用消息的ID */
-    message_id?: string;
-    /** 是否忽略获取引用消息详情错误，默认否 */
-    ignore_get_message_error?: boolean;
+  /** 引用消息的ID */
+  message_id?: string;
+  /** 是否忽略获取引用消息详情错误，默认否 */
+  ignore_get_message_error?: boolean;
 }
 /** 发送频道消息请求参数基类 */
 interface SendGuildMessageRequest {
-    /** 单独加一个类型 用于区分不同的消息类型 */
-    type: 'text' | 'image' | 'embed' | 'ark' | 'markdown';
+  /** 单独加一个类型 用于区分不同的消息类型 */
+  type: 'text' | 'image' | 'embed' | 'ark' | 'markdown';
 }
 /** 发送频道 文本 消息请求参数 */
 interface SendGuildTextMessageRequest extends SendGuildMessageID, SendGuildQuoteMessage, SendGuildMessageRequest {
-    type: 'text';
-    /**
-     * 消息内容 支持如下内嵌格式
-     * - `<@user_id>` `@用户`
-     * - `@everyone` `@所有人`
-     * - `<#channel_id>` `#子频道`
-     * - `<emoji:id>` `表情`
-     */
-    content: string;
-    /** 图片url地址 */
-    image?: string;
+  type: 'text';
+  /**
+   * 消息内容 支持如下内嵌格式
+   * - `<@user_id>` `@用户`
+   * - `@everyone` `@所有人`
+   * - `<#channel_id>` `#子频道`
+   * - `<emoji:id>` `表情`
+   */
+  content: string;
+  /** 图片url地址 */
+  image?: string;
 }
 /** 发送频道 图片 消息请求参数 */
 interface SendGuildImageMessageRequest extends SendGuildMessageID, SendGuildQuoteMessage, SendGuildMessageRequest {
-    type: 'image';
-    /** 图片url地址 */
-    image: string;
+  type: 'image';
+  /** 图片url地址 */
+  image: string;
 }
 /** embeds消息结构 */
 interface Embeds {
-    /** 标题 */
-    title: string;
-    /** 消息弹窗内容 */
-    prompt: string;
-    /** 缩略图 */
-    thumbnail: {
-        /** 图片地址 */
-        url: string;
-    };
-    /** embed 字段数据 */
-    fields: Record<string, any>[];
+  /** 标题 */
+  title: string;
+  /** 消息弹窗内容 */
+  prompt: string;
+  /** 缩略图 */
+  thumbnail: {
+    /** 图片地址 */url: string;
+  };
+  /** embed 字段数据 */
+  fields: Record<string, any>[];
 }
 /** 发送频道 embed 消息请求参数 */
 interface SendGuildEmbedMessageRequest extends SendGuildMessageID, SendGuildMessageRequest {
-    type: 'embed';
-    /** embed 消息内容 */
-    embed: Embeds;
+  type: 'embed';
+  /** embed 消息内容 */
+  embed: Embeds;
 }
 /** ark消息结构 */
 interface Ark {
-    /** 模版id */
-    template_id: number;
-    /** 模版内变量与填充值的kv映射 */
-    kv: {
+  /** 模版id */
+  template_id: number;
+  /** 模版内变量与填充值的kv映射 */
+  kv: {
+    key: string;
+    value: string; /** 这个嵌套是认真的嘛... */
+    obj: {
+      obj_kv: {
         key: string;
         value: string;
-        /** 这个嵌套是认真的嘛... */
-        obj: {
-            obj_kv: {
-                key: string;
-                value: string;
-            }[];
-        }[];
+      }[];
     }[];
+  }[];
 }
 /** 发送频道 ark 消息请求参数 */
 interface SendGuildArkMessageRequest extends SendGuildMessageID, SendGuildMessageRequest {
-    type: 'ark';
-    /** ark 消息内容 */
-    ark: Ark;
+  type: 'ark';
+  /** ark 消息内容 */
+  ark: Ark;
 }
 /** 发送频道 markdown 消息请求参数 */
 interface SendGuildMarkdownMessageRequest extends SendGuildMessageID, SendGuildMessageRequest {
-    type: 'markdown';
-    /** markdown 消息内容 */
-    markdown: Markdown;
-    /** 按钮 */
-    keyboard?: Keyboard;
+  type: 'markdown';
+  /** markdown 消息内容 */
+  markdown: Markdown;
+  /** 按钮 */
+  keyboard?: Keyboard;
 }
 /** 发送频道消息请求参数 */
 type SendGuildMsg = SendGuildTextMessageRequest | SendGuildImageMessageRequest | SendGuildEmbedMessageRequest | SendGuildArkMessageRequest | SendGuildMarkdownMessageRequest;
 /** 获取当前机器人详情接口响应 */
 interface GetMeResponse {
-    /** 机器人的频道ID */
-    id: string;
-    /** 机器人的昵称 */
-    username: string;
-    /** 用户头像 */
-    avatar: string;
-    /** 特殊关联应用的 openid */
-    union_openid: string;
-    /** 机器人关联的互联应用的用户信息 */
-    union_user_account: string;
-    /** 机器人的分享url */
-    share_url: string;
-    /** 机器人介绍 */
-    welcome_msg: string;
+  /** 机器人的频道ID */
+  id: string;
+  /** 机器人的昵称 */
+  username: string;
+  /** 用户头像 */
+  avatar: string;
+  /** 特殊关联应用的 openid */
+  union_openid: string;
+  /** 机器人关联的互联应用的用户信息 */
+  union_user_account: string;
+  /** 机器人的分享url */
+  share_url: string;
+  /** 机器人介绍 */
+  welcome_msg: string;
 }
 /** 创建私信会话接口响应 */
 interface DmsResponse {
-    /** 频道ID 用于私信会话使用 */
-    guild_id: string;
-    /** 子频道ID 用于私信会话使用 */
-    channel_id: string;
-    /** 创建时间 */
-    create_time: string;
+  /** 频道ID 用于私信会话使用 */
+  guild_id: string;
+  /** 子频道ID 用于私信会话使用 */
+  channel_id: string;
+  /** 创建时间 */
+  create_time: string;
 }
 /** 发送QQ消息后响应 */
 interface SendQQMsgResponse {
-    /** 消息唯一 ID */
-    id: string;
-    /** 发送时间 */
-    timestamp: number;
+  /** 消息唯一 ID */
+  id: string;
+  /** 发送时间 */
+  timestamp: number | string;
+  /** 扩展信息；部分 QQ 消息发送响应会返回可用于 message_reference 的 REFIDX。 */
+  ext_info?: {
+    /** 当前发送消息可被引用时使用的索引。 */ref_idx?: string;
+  };
 }
 /** 发送频道消息后响应 */
 interface SendGuildResponse {
-    /** 消息唯一 ID */
-    id: string;
-    /** 发送时间 ISO8601 timestamp */
-    timestamp: string;
+  /** 消息唯一 ID */
+  id: string;
+  /** 发送时间 ISO8601 timestamp */
+  timestamp: string;
 }
 /** 上传富媒体文件响应 */
 interface UploadMediaResponse {
-    /** 文件 ID */
-    file_uuid: string;
-    /** 文件信息，用于发消息接口的 media 字段使用 */
-    file_info: string;
-    /** 有效期，表示剩余多少秒到期，到期后 file_info 失效，当等于 0 时，表示可长期使用 */
-    ttl: number;
-    /** 发送消息的唯一ID，当srv_send_msg设置为true时返回 */
-    id: string;
+  /** 文件 ID */
+  file_uuid: string;
+  /** 文件信息，用于发消息接口的 media 字段使用 */
+  file_info: string;
+  /** 有效期，表示剩余多少秒到期，到期后 file_info 失效，当等于 0 时，表示可长期使用 */
+  ttl: number;
+  /** 发送消息的唯一ID，当srv_send_msg设置为true时返回 */
+  id: string;
 }
-
+//#endregion
+//#region src/core/internal/axios.d.ts
+/**
+ * 创建 axios 实例，自动从 tokens map 取最新 access_token
+ */
+declare const createAxiosInstance: (baseURL: string, appId: string) => import("node-karin/axios").AxiosInstance;
+//#endregion
+//#region src/core/api/http.d.ts
+type AxiosInstance = ReturnType<typeof createAxiosInstance>;
+/**
+ * Http 基础类，子模块继承此类共享 axios 实例与错误格式化
+ */
+declare class Http {
+  readonly axios: AxiosInstance;
+  constructor(axios: AxiosInstance);
+  protected get<T>(path: string): Promise<T>;
+  protected post<T>(path: string, body?: unknown, headers?: Record<string, string>, timeout?: number): Promise<T>;
+  protected put<T>(path: string, body?: unknown, headers?: Record<string, string>, timeout?: number): Promise<T>;
+  protected delete<T>(path: string): Promise<T>;
+}
+//#endregion
+//#region src/core/api/messages.d.ts
+/**
+ * 消息发送 + 撤回
+ */
+declare class MessagesApi extends Http {
+  /** 单聊消息 */
+  sendFriendMsg(openid: string, body: SendQQMsg): Promise<SendQQMsgResponse>;
+  /** 群聊消息 */
+  sendGroupMsg(groupOpenid: string, body: SendQQMsg): Promise<SendQQMsgResponse>;
+  /** 文字子频道消息 */
+  sendChannelMsg(channelId: string, body: SendGuildMsg | FormData): Promise<SendGuildResponse>;
+  /**
+   * 频道私信消息
+   * - 单参 (guildId, body)：guildId 已知
+   * - 双参 (recipientId, srcGuildId, body)：先创建会话再发送
+   */
+  sendDmsMsg(guildId: string, body: SendGuildMsg | FormData): Promise<SendGuildResponse>;
+  sendDmsMsg(recipientId: string, srcGuildId: string, body: SendGuildMsg | FormData): Promise<SendGuildResponse>;
+  /**
+   * 撤回消息
+   * - 'user' / 'group' 对应 QQ 单聊 / 群聊
+   * - 'channels' / 'dms' 对应频道 / 频道私信，支持 hidetip
+   */
+  recall(type: 'user' | 'group', peer: string, messageId: string): Promise<true>;
+  recall(type: 'channels' | 'dms', peer: string, messageId: string, hidetip?: boolean): Promise<true>;
+}
+//#endregion
+//#region src/core/api/media.d.ts
+/**
+ * 富媒体上传
+ */
+declare class MediaApi extends Http {
+  /**
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param type 文件类型
+   * @param source http url、本地路径或 base64 字符串
+   * @param srvSendMsg 上传后是否由服务端直接发送
+   * @param fileName 文件消息的展示文件名
+   */
+  upload(scene: Scene, peer: string, type: MediaType, source: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
+  /**
+   * 上传没有公网 URL 处理器可用时的 fallback 富媒体资源。
+   *
+   * 较大的 fallback 资源会优先使用 QQ 分片上传，提高直接发送成功率。
+   * `srvSendMsg` 为 true 时保留普通上传路径，避免分片完成接口与服务端直接发送语义冲突。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param type 文件类型
+   * @param source 本地路径、http url、data URL、base64:// 或裸 base64
+   * @param srvSendMsg 上传后是否由服务端直接发送
+   * @param fileName 文件消息的展示文件名
+   * @returns 上传结果，包含后续发送消息所需的 file_info
+   */
+  uploadFallback(scene: Scene, peer: string, type: MediaType, source: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
+  /**
+   * 确认单个分片已完成上传。
+   *
+   * QQ 有时会在分片刚 PUT 完时短暂返回 40093001，此时需要在服务端给出的
+   * retry_timeout 窗口内持续重试，而不是直接判定整个大文件上传失败。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param body upload_part_finish 请求体
+   * @param retryTimeout 服务端返回的持续重试秒数
+   */
+  private finishUploadPart;
+  /**
+   * 持续重试 upload_part_finish 的短暂服务端状态。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param body upload_part_finish 请求体
+   * @param retryTimeout 服务端返回的持续重试秒数
+   */
+  private retryUploadPartFinish;
+  /**
+   * 完成 QQ 分片上传，并对短暂失败做有限重试。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param uploadId upload_prepare 返回的上传任务 ID
+   * @returns 上传结果
+   */
+  private completeChunkedUpload;
+  /**
+   * 使用 QQ 官方分片协议上传 fallback 大资源。
+   *
+   * 流程为：准备上传 -> PUT 每个分片 -> 确认每个分片 -> 完成上传。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param type 文件类型
+   * @param source 已归一化的 fallback 来源
+   * @param preparedHashes 预计算的文件 hash
+   * @returns 上传结果，包含后续发送消息所需的 file_info
+   */
+  private uploadChunked;
+}
+//#endregion
+//#region src/core/api/interaction.d.ts
+/** ack 返回码 */
+type AckCode = 0 | 1 | 2 | 3 | 4 | 5;
+/**
+ * INTERACTION_CREATE 回应
+ */
+declare class InteractionApi extends Http {
+  /**
+   * @param interactionId INTERACTION_CREATE 事件中的 id
+   * @param code 0 成功 / 1 操作失败 / 2 操作频繁 / 3 重复操作 / 4 无权限 / 5 仅管理员
+   */
+  ack(interactionId: string, code?: AckCode): Promise<void>;
+}
+//#endregion
+//#region src/core/api/meta.d.ts
+/**
+ * 元信息接口：@me / dms / gateway
+ */
+declare class MetaApi extends Http {
+  /** 当前机器人详情 */
+  getMe(): Promise<GetMeResponse>;
+  /** 创建频道私信会话 */
+  createDms(recipientId: string, srcGuildId: string): Promise<DmsResponse>;
+  /** 获取通用 WSS 地址 */
+  getGateway(): Promise<{
+    url: string;
+  }>;
+}
+//#endregion
+//#region src/core/api/index.d.ts
+/**
+ * QQBot 官方 API 门面
+ *
+ * 子模块按职能拆分：
+ * - messages：发送 / 撤回
+ * - media：富媒体上传
+ * - interaction：按钮回调 ack
+ * - meta：@me / dms / gateway
+ *
+ * 请求体构造器 {@link buildQQMsg} / {@link buildGuildMsg} 独立导出，避免与 HTTP 调用耦合
+ */
 declare class QQBotApi {
-    /** axios 实例 */
-    axios: ReturnType<typeof createAxiosInstance>;
-    constructor(axios: ReturnType<typeof createAxiosInstance>);
-    /**
-     * 发送get请求
-     * @param path 请求路径
-     * @returns 请求结果
-     */
-    get<T>(path: string): Promise<T>;
-    /**
-     * 发送post请求
-     * @param path 请求路径
-     * @param options 请求数据
-     * @param headers 请求头
-     */
-    post<T>(path: string, options?: {}, headers?: Record<string, string>): Promise<T>;
-    /**
-     * 处理请求错误
-     * @param error 错误信息
-     */
-    handleError(path: string, options: any, error: any): void;
-    /**
-     * 发送单聊消息
-     * @param targetId 目标QQ用户的 openid
-     * @param options 消息参数
-     */
-    sendFriendMsg(targetId: string, options: SendQQMsg): Promise<SendQQMsgResponse>;
-    /**
-     * 发送群聊消息
-     * @param targetId 目标QQ群的 openid
-     * @param options 消息参数
-     */
-    sendGroupMsg(targetId: string, options: SendQQMsg): Promise<SendQQMsgResponse>;
-    /**
-     * 构建QQBot文本消息参数
-     * @param content 消息文本内容
-     */
-    QQdMsgOptions(type: 'text', content: string): SendQQTextMessageRequest;
-    /**
-     * 构建Markdown消息参数
-     * @param markdown Markdown文本内容
-     * @param keyboard 按钮
-     */
-    QQdMsgOptions(type: 'markdown', markdown: Markdown, keyboard?: Keyboard): SendQQMarkdownMessageRequest;
-    /**
-     * 构建Ark消息参数
-     * @param ark Ark参数
-     */
-    QQdMsgOptions(type: 'ark', ark: SendQQArkMessageRequest['ark']): SendQQArkMessageRequest;
-    /**
-     * 构建Media消息参数
-     * @param file 文件信息
-     */
-    QQdMsgOptions(type: 'media', file: string): SendQQMediaMessageRequest;
-    /**
-     * 构建频道文本、文本图片消息参数
-     * @param type 消息类型
-     * @param content 消息内容
-     * @param image 图片url
-     */
-    GuildMsgOptions(type: 'text', content: string, image?: string): SendGuildTextMessageRequest;
-    /**
-     * 构建图片消息参数
-     * @param type 消息类型
-     * @param image 图片url
-     */
-    GuildMsgOptions(type: 'image', image: string): SendGuildTextMessageRequest;
-    /**
-     * 构建Embed消息参数
-     * @param type 消息类型
-     * @param embed Embed参数
-     */
-    GuildMsgOptions(type: 'embed', embed: Embeds): SendGuildEmbedMessageRequest;
-    /**
-     * 构建Ark消息参数
-     * @param type 消息类型
-     * @param ark Ark参数
-     */
-    GuildMsgOptions(type: 'ark', ark: Ark): SendGuildArkMessageRequest;
-    /**
-     * 构建Markdown消息参数
-     * @param type 消息类型
-     * @param markdown Markdown文本
-     */
-    GuildMsgOptions(type: 'markdown', markdown: Markdown): SendGuildMarkdownMessageRequest;
-    /**
-     * 上传富媒体文件
-     * @param scene 上传场景
-     * @param targetId 目标id
-     * @param type 文件类型
-     * @param url 需要上传的文件的url
-     * @param srvSendMsg 是否发送消息
-     */
-    uploadMedia(scene: Scene, targetId: string, type: MediaType, url: string, srvSendMsg?: boolean): Promise<UploadMediaResponse>;
-    /**
-     * 上传富媒体文件
-     * @param scene 上传场景
-     * @param targetId 目标id
-     * @param type 文件类型
-     * @param base64 需要上传的文件的base64编码
-     * @param srvSendMsg 是否发送消息
-     */
-    uploadMedia(scene: Scene, targetId: string, type: MediaType, base64: string, srvSendMsg?: boolean): Promise<UploadMediaResponse>;
-    /**
-     * 单聊撤回消息
-     * @param type 场景类型
-     * @param targetId 目标QQ用户的openid
-     * @param messageId 消息id
-     */
-    recallMsg(type: 'user', targetId: string, messageId: string): Promise<boolean>;
-    /**
-     * 群聊撤回消息
-     * @param type 场景类型
-     * @param targetId 目标QQ群的openid
-     * @param messageId 消息id
-     */
-    recallMsg(type: 'group', targetId: string, messageId: string): Promise<boolean>;
-    /**
-     * 文字子频道撤回消息
-     * @param type 场景类型
-     * @param channelId 子频道的id
-     * @param messageId 消息id
-     * @param hidetip 是否隐藏提示小灰条，true 为隐藏，false 为显示。默认为false
-     */
-    recallMsg(type: 'channels', channelId: string, messageId: string, hidetip?: boolean): Promise<boolean>;
-    /**
-     * 频道私信撤回消息
-     * @param type 场景类型
-     * @param guildId 频道的id
-     * @param messageId 消息id
-     * @param hidetip 是否隐藏提示小灰条，true 为隐藏，false 为显示。默认为false
-     */
-    recallMsg(type: 'dms', guildId: string, messageId: string, hidetip?: boolean): Promise<boolean>;
-    /**
-     * 发送文字子频道消息
-     * @param targetId 目标子频道的id
-     * @param options 消息参数
-     */
-    sendChannelMsg(targetId: string, options: SendGuildMsg | FormData): Promise<SendGuildResponse>;
-    /**
-     * 直接发送频道消息
-     * @param guildID 频道的id
-     * @param options 消息参数
-     */
-    sendDmsMsg(guildID: string, options: SendGuildMsg | FormData): Promise<SendGuildResponse>;
-    /**
-     * 发送频道私信消息
-     * @param targetId 目标的id
-     * @param srcGuildId 源频道的id
-     * @param options 消息参数
-     */
-    sendDmsMsg(targetId: string, srcGuildId: string, options: SendGuildMsg | FormData): Promise<SendGuildResponse>;
-    /**
-     * 获取当前机器人详情
-     */
-    getMe(): Promise<GetMeResponse>;
-    /**
-     * 创建私信会话
-     * @param recipientID 接受者id
-     * @param srcGuildID 源频道id
-     */
-    dms(recipientID: string, srcGuildID: string): Promise<DmsResponse>;
+  readonly axios: AxiosInstance;
+  readonly messages: MessagesApi;
+  readonly media: MediaApi;
+  readonly interaction: InteractionApi;
+  readonly meta: MetaApi;
+  /** 请求体构造器（静态便利） */
+  readonly qq: {
+    text(content: string): SendQQTextMessageRequest;
+    markdown(markdown: Markdown, keyboard?: Keyboard): SendQQMarkdownMessageRequest;
+    ark(ark: SendQQArkMessageRequest["ark"]): SendQQArkMessageRequest;
+    media(fileInfo: string): SendQQMediaMessageRequest;
+  };
+  readonly guild: {
+    text(content: string, image?: string): SendGuildTextMessageRequest;
+    image(image: string): SendGuildImageMessageRequest;
+    embed(embed: Embeds): SendGuildEmbedMessageRequest;
+    ark(ark: Ark): SendGuildArkMessageRequest;
+    markdown(markdown: Markdown, keyboard?: Keyboard): SendGuildMarkdownMessageRequest;
+  };
+  constructor(axios: AxiosInstance);
 }
-
-/** 发送函数所需参数 */
-type Options<T extends 'qq' | 'guild'> = T extends 'qq' ? SendQQMsg : SendGuildMsg | FormData;
-type Pasmsg<T extends 'qq' | 'guild'> = {
-    type: 'msg' | 'event';
-    msg_id: string;
-    msg_seq: T extends 'qq' ? number : never;
-};
-interface Grouping<T extends 'qq' | 'guild'> {
-    /** 文本 */
-    content: string[];
-    /** 图片 QQ专属 */
-    image: string[];
-    /** 单行按钮 */
-    button: ButtonElement[];
-    /** 多行按钮 */
-    keyboard: KeyboardElement[];
-    /** markdown */
-    markdown: MarkdownElement[];
-    /** markdown模板 */
-    markdownTpl: MarkdownTplElement[];
-    /** 频道专属 图片url */
-    imageUrls: string[];
-    /** 频道专属 图片file */
-    imageFiles: string[];
-    /** 引用回复 频道专属 */
-    reply: {
-        message_id: string;
-    };
-    /** pasmsg */
-    pasmsg: Pasmsg<T>;
-    /** 代发送列表 */
-    list: Array<Options<T>>;
-    /**
-     * 处理按钮、markdown
-     * 统一格式后推入待发送消息列表
-     * @param type 构建类型
-     * @param list 分类列表
-     * @returns
-     */
-    markdownToButton: (type: T, list: Grouping<T>) => void;
+//#endregion
+//#region src/core/storage/message-store/types.d.ts
+interface CachedMessage {
+  messageId: string;
+  messageSeq: number;
+  time: number;
+  contact: Contact;
+  sender: Sender;
+  elements: ElementTypes[];
 }
+//#endregion
+//#region src/core/storage/message-store/store.d.ts
 /**
- * @adaoter QQBot
- * @version 1.8.0
+ * QQBot 收到的消息缓存。
+ *
+ * 热路径只写内存并入队，不等待 SQLite：
+ * - `getMsg` 优先查内存，插件在同一事件回调内可立即命中；
+ * - SQLite 在后台按批次事务落库，避免一条消息一个事务拖慢事件分发；
+ * - 元素表只保存 `type + value`，避免宽表 NULL 和多详情表多次 INSERT。
  */
-declare abstract class AdapterQQBot extends AdapterBase {
-    super: QQBotApi;
-    constructor(QQBot: QQBotApi);
-    logger(level: LogMethodNames, ...args: any[]): void;
-    /**
-     * 被动消息结构
-     * @param type 消息类型
-     */
-    pasmsg<T extends 'qq' | 'guild'>(type: T): Pasmsg<T>;
-    /**
-     * 撤回消息
-     * @param contact 联系人
-     * @param messageId 消息id
-     */
-    recallMsg(contact: Contact, messageId: string): Promise<void>;
-    /**
-     * 初始化消息分类对象
-     */
-    initList<T extends 'qq' | 'guild'>(type: T): Grouping<T>;
-    /**
-     * 初始化发送消息返回值
-     */
-    initSendMsgResults(): SendMsgResults;
-    /**
-     * 处理返回值
-     * @param data 返回值
-     */
-    handleResponse(data: SendMsgResults): SendMsgResults;
-    /**
-     * - 处理按钮、markdown
-     * - 统一格式后推入待发送消息列表
-     * @param type 消息类型
-     * @param button 按钮
-     * @param keyboard 键盘
-     * @param markdown markdown
-     * @param markdownTpl markdown模板
-     * @returns 消息列表
-     */
-    markdownToButton<T extends 'qq' | 'guild'>(type: T, list: Grouping<T>): void;
+declare class MessageStore {
+  private db?;
+  private readonly ready;
+  private lastCleanup;
+  private shouldVacuum;
+  private flushTimer?;
+  private flushing;
+  private mediaTimer?;
+  private mediaActive;
+  private readonly pending;
+  private readonly pendingMedia;
+  private readonly pendingMediaKeys;
+  private readonly memory;
+  private readonly directIndex;
+  private readonly aliasIndex;
+  private readonly scopedAliasIndex;
+  private readonly botRefCache;
+  private readonly contactRefCache;
+  private readonly senderRefCache;
+  constructor();
+  /**
+   * 立即执行一次过期消息和本地媒体缓存清理。
+   *
+   * 该方法交给 Karin `task` 调度调用；类内部只保留清理能力，不自行维护常驻定时器。
+   *
+   * @returns 清理完成 Promise。
+   */
+  cleanupExpired(): Promise<void>;
+  /**
+   * 保存实际消息，并为 QQ 的 `msg_idx` 等引用索引建立轻量映射。
+   *
+   * 该方法只同步写入内存并投递后台队列，不等待 SQLite。这样消息事件创建不会被
+   * 数据库写锁或小事务阻塞。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 已转换为 Karin elements 的消息缓存。
+   * @param aliases 可查询到该消息的额外消息索引，例如 QQ `msg_idx`。
+   */
+  save(botId: string, message: CachedMessage, aliases?: string[]): Promise<void>;
+  /**
+   * 仅当内存中没有该引用索引时保存 QQ 下发的引用上下文。
+   * 数据库是否已存在由后台 flush 再判断，避免阻塞事件热路径。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 以 `ref_msg_idx` 作为 messageId 的引用上下文。
+   */
+  saveReferenceIfAbsent(botId: string, message: CachedMessage): Promise<void>;
+  /**
+   * 读取缓存消息。
+   *
+   * OneBot v11 标准调用只传 messageId；contact 参数仅用于额外限定范围。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param messageId 真实消息 ID 或 QQ `REFIDX` 引用索引。
+   * @param contact 可选会话范围，传入后只在该会话下查询。
+   * @returns 命中的消息缓存；未命中或已过期时返回 null。
+   */
+  get(botId: string, messageId: string, contact?: Contact): Promise<MessageResponse | null>;
+  /**
+   * 按起始消息 ID 读取同一会话内的历史缓存消息。
+   *
+   * QQ 官方 Bot 没有 seq 历史查询能力；这里以本地缓存中命中的起始消息为锚点，
+   * 按时间倒序返回最近的 `count` 条消息，包含起始消息本身。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact 查询限定的会话。
+   * @param startMsgId 起始消息 ID 或 QQ `REFIDX` 引用索引。
+   * @param count 获取消息数量。
+   * @returns 命中的历史消息数组；未命中或已过期时返回空数组。
+   */
+  getHistory(botId: string, contact: Contact, startMsgId: string, count: number): Promise<MessageResponse[]>;
+  /**
+   * 初始化 SQLite 连接、表结构，并执行启动清理和媒体本地化补救。
+   *
+   * @returns 初始化完成 Promise。
+   */
+  private initialize;
+  /**
+   * 投递待落库消息。
+   *
+   * @param item 待写入 SQLite 的缓存任务。
+   */
+  private enqueue;
+  /**
+   * 安排一次后台批量落库。
+   *
+   * 已有 timer 或正在 flush 时不会重复安排。
+   */
+  private scheduleFlush;
+  /**
+   * 批量落库队列中的消息。
+   *
+   * 单次最多处理 `FLUSH_BATCH_SIZE` 条，并在一个事务内完成写入。
+   *
+   * @returns flush 完成 Promise。
+   */
+  private flushQueue;
+  /**
+   * 写入一条待落库消息。
+   *
+   * @param item 待写入的消息、alias 和引用上下文标记。
+   */
+  private writeItem;
+  /**
+   * 清理待写队列中已经过期的消息。
+   */
+  private prunePending;
+  /**
+   * 投递媒体本地化任务。
+   *
+   * 原消息会先保留短期 URL 写入缓存；本地化成功后再覆盖同一条消息。队列会按
+   * message scoped key 去重，避免高频更新同一条消息时重复下载。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 可能包含远程媒体 URL 的消息快照。
+   * @param aliases 该消息可被查询到的额外 alias。
+   */
+  private enqueueMediaLocalize;
+  /**
+   * 安排媒体本地化队列处理。
+   *
+   * @returns 已存在定时器或队列为空时直接返回。
+   */
+  private scheduleMediaLocalize;
+  /**
+   * 按固定并发处理媒体本地化任务。
+   *
+   * @returns 队列为空或达到并发上限时返回。
+   */
+  private drainMediaLocalizeQueue;
+  /**
+   * 本地化单条消息中的远程媒体字段，并在成功后覆盖内存与 SQLite。
+   *
+   * @param item 待处理的媒体本地化任务。
+   * @returns 本地化与回写完成 Promise。
+   */
+  private localizeMediaItem;
+  /**
+   * 清理已经过期的媒体本地化待处理任务。
+   *
+   * @returns 无返回值；会同步维护 pendingMediaKeys。
+   */
+  private prunePendingMedia;
+  /**
+   * 启动时扫描 SQLite 中尚未本地化的远程媒体 URL，并重新投递队列补救。
+   *
+   * @returns 扫描和投递完成 Promise。
+   */
+  private recoverRemoteMedia;
+  /**
+   * 写入内存热缓存。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 消息缓存。
+   * @param aliases 可查询到该消息的额外消息索引。
+   */
+  private putMemory;
+  /**
+   * 从内存热缓存读取消息。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param messageId 真实消息 ID 或 alias。
+   * @param contact 可选会话范围。
+   * @returns 命中的缓存消息；未命中或过期时返回 null。
+   */
+  private getFromMemory;
+  /**
+   * 到达清理间隔时清理内存缓存。
+   */
+  private cleanupMemoryIfDue;
+  /**
+   * 清理一天前的内存消息，并同步清理失效索引。
+   */
+  private cleanupMemory;
+  /**
+   * 清理指向已删除内存消息的索引。
+   *
+   * @param index 需要清理的索引 Map。
+   */
+  private cleanIndex;
+  /**
+   * 浅拷贝消息缓存，避免后续事件对象被插件侧修改后污染缓存。
+   *
+   * @param message 原始缓存消息。
+   * @returns 可安全放入缓存的消息副本。
+   */
+  private cloneMessage;
+  /**
+   * 将内存缓存转换为 Karin `MessageResponse`。
+   *
+   * @param message 内存缓存消息。
+   * @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;
+  /**
+   * 从查询行还原 Karin Contact。
+   *
+   * @param row 消息主查询结果。
+   * @returns Karin Contact。
+   */
+  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。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact Karin 会话对象。
+   * @param messageId 消息 ID 或 alias。
+   * @returns 内存 Map 使用的稳定 key。
+   */
+  private scopedKey;
+  /**
+   * 构造内存全局 key。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param messageId 消息 ID 或 alias。
+   * @returns 不限定会话时使用的内存 key。
+   */
+  private globalKey;
+  /**
+   * 删除指定会话下的 alias。
+   *
+   * @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 段。
+   */
+  private hasReplyTo;
+  /**
+   * 判断消息是否已经超过本地缓存 TTL。
+   *
+   * @param row 带 `time` 字段的消息对象。
+   * @returns true 表示已经超过一天缓存窗口。
+   */
+  private isExpired;
+  /**
+   * 到达清理间隔时清理内存和 SQLite 过期消息。
+   */
+  private cleanupIfDue;
+  /**
+   * 清理一天前的缓存消息。
+   *
+   * SQLite 只删除主消息表，消息段和 alias 通过外键级联删除。
+   */
+  private cleanup;
+  /**
+   * 判断 SQLite 表是否存在。
+   *
+   * @param name 表名。
+   * @returns true 表示表存在。
+   */
+  private tableExists;
+  /**
+   * 读取 SQLite 表字段名。
+   *
+   * @param name 表名。
+   * @returns 字段名数组；表不存在时返回空数组。
+   */
+  private tableColumns;
+  /**
+   * 读取 SQLite schema 版本。
+   *
+   * @returns 当前 `PRAGMA user_version`；新库默认为 0。
+   */
+  private getUserVersion;
+  /**
+   * 写入 SQLite schema 版本。
+   *
+   * @param version 已成功应用的数据库版本号。
+   */
+  private setUserVersion;
+  /**
+   * 在 `BEGIN IMMEDIATE` 事务中执行写操作。
+   *
+   * @param fn 事务内执行的异步函数。
+   */
+  private transaction;
+  /**
+   * 执行不返回行的 SQL。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   */
+  private run;
+  /**
+   * 查询单行数据。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   * @returns 查询结果；未命中时返回 undefined。
+   */
+  private getRow;
+  /**
+   * 查询多行数据。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   * @returns 查询结果数组。
+   */
+  private getRows;
 }
-
-export { AdapterQQBot };
+//#endregion
+//#region src/types/config.d.ts
+/**
+ * 单个 QQBot 配置
+ */
+interface QQBotConfig {
+  /** 机器人名称 */
+  name: string;
+  /** 机器人 ID */
+  appId: string;
+  /** 机器人密钥 */
+  secret: string;
+  /** 正式环境 API */
+  prodApi: string;
+  /** 测试环境 API */
+  sandboxApi: string;
+  /** 调用凭证 API */
+  tokenApi: string;
+  /** 开启沙盒环境 */
+  sandbox: boolean;
+  /** 开启 QQ 场景能力（单聊 / 群聊） */
+  qqEnable: boolean;
+  /** 开启频道场景能力 */
+  guildEnable: boolean;
+  /** 频道场景模式 0 公域 / 1 私域 */
+  guildMode: 0 | 1;
+  /** 收到消息后对文本进行表达式处理 */
+  regex: {
+    reg: string | RegExp;
+    rep: string;
+  }[];
+  /** 按钮自动化 */
+  keyboard: {
+    /** 是否将文本中的 URL 自动转换为 keyboard 按钮 */enable: boolean;
+  };
+  /** 消息缓存配置 */
+  messageCache: {
+    /** 是否启用数据库消息缓存，用于 bot.getMsg */enable: boolean; /** 是否缓存机器人自己发送的消息 */
+    self: boolean;
+  };
+  /** 事件接收配置 */
+  event: {
+    /** 接收方式 0 关闭 / 1 webhook / 2 ws */type: 0 | 1 | 2;
+  };
+}
+//#endregion
+//#region src/core/adapter/base.d.ts
+/**
+ * QQ Official Bot 适配器
+ *
+ * 全场景统一走 msg_type=2 Markdown 通道（详见 pipeline-qq / pipeline-guild）。
+ * 视频 / 语音 / 文件由 pipeline 内部以 msg_type=7 紧随主消息补发。
+ */
+declare class AdapterQQBot extends AdapterBase implements AdapterType {
+  /** 与官方 API 交互 */
+  super: QQBotApi;
+  /** openId / member_openid -> 昵称 缓存 */
+  nicknameCache: Map<string, string>;
+  constructor(cfg: QQBotConfig, api: QQBotApi);
+  /** 当前 bot 配置。真实配置存放在 WeakMap，避免被系统接口序列化整个适配器时带出。 */
+  get cfg(): QQBotConfig;
+  /** 接收消息的一天热缓存 + SQLite 缓存，用于实现 Karin 标准 `getMsg`。 */
+  get messageStore(): MessageStore;
+  logger(level: LogMethodNames, ...args: any[]): void;
+  /**
+   * 主消息回复入口（karin 调用）
+   */
+  srcReply(e: Message, elements: ElementTypes[]): Promise<SendMsgResults>;
+  /**
+   * 发送消息
+   */
+  sendMsg(contact: Contact, elements: Array<ElementTypes>, _retryCount?: number): Promise<SendMsgResults>;
+  /**
+   * 撤回消息
+   *
+   * 群聊中机器人被群主设为管理员后，也可撤回成员消息；平台仍限制消息发送后两分钟内。
+   */
+  recallMsg(contact: Contact, messageId: string): Promise<void>;
+  /**
+   * 构造空发送结果，pipeline 内填充 rawData
+   */
+  initSendMsgResults(): SendMsgResults;
+  /**
+   * 将 rawData[0].id / timestamp 同步到顶层字段
+   */
+  handleResponse(data: SendMsgResults): SendMsgResults;
+  /**
+   * 发送长消息
+   */
+  sendLongMsg(_contact: Contact, _resId: string): Promise<SendMsgResults>;
+  /**
+   * 发送合并转发消息
+   *
+   * 将 NodeElement 拆解为文本 + 图片等元素，拼接成 markdown 发送。
+   * 节点之间仅用换行隔开，不添加任何前缀提示文本。
+   */
+  sendForwardMsg(contact: Contact, elements: Array<NodeElement>, _options?: ForwardOptions): Promise<{
+    messageId: string;
+    forwardId: string;
+  }>;
+  /**
+   * 获取头像 url
+   */
+  getAvatarUrl(_userId: string, _size?: 0 | 40 | 100 | 140): Promise<string>;
+  /**
+   * 获取群头像 url
+   */
+  getGroupAvatarUrl(_groupId: string, _size?: 0 | 40 | 100 | 140, _history?: number): Promise<string>;
+  /**
+   * 按消息 ID 获取已接收的消息。
+   *
+   * QQ 官方 Bot API 没有历史消息查询接口，因此仅从本地缓存读取。
+   * 消息在接收时已转换为 Karin elements，最长保留一天；引用消息的 `REFIDX`
+   * 索引同样可作为 `messageId` 查询。
+   *
+   * @param input OneBot v11 标准单参 messageId，或用于限定查询范围的 Contact。
+   * @param messageId 当 input 是 Contact 时传入的目标消息 ID。
+   * @returns 命中的消息；未命中时返回空消息结构。
+   */
+  getMsg(input: Contact | string, messageId?: string): Promise<MessageResponse>;
+  /**
+   * 获取本地缓存历史消息（仅支持 message_id）
+   */
+  getHistoryMsg(contact: Contact, startMsgId: string, count: number): Promise<Array<MessageResponse>>;
+  /**
+   * 获取本地缓存历史消息（message_seq 暂不支持）
+   */
+  getHistoryMsg(contact: Contact, startMsgSeq: number, count: number): Promise<Array<MessageResponse>>;
+  /**
+   * 获取合并转发消息
+   */
+  getForwardMsg(_resId: string): Promise<Array<MessageResponse>>;
+  /**
+   * 获取精华消息
+   */
+  getGroupHighlights(_groupId: string, _page: number, _pageSize: number): Promise<Array<GetGroupHighlightsResponse>>;
+  /**
+   * 构造资源 ID
+   */
+  createResId(_contact: Contact, _elements: Array<NodeElement>): Promise<string>;
+  /**
+   * 设置、取消群精华消息
+   */
+  setGroupHighlights(_groupId: string, _messageId: string, _create: boolean): Promise<void>;
+  /**
+   * 发送好友赞
+   */
+  sendLike(_targetId: string, _count: number): Promise<void>;
+  /**
+   * 群踢人
+   */
+  groupKickMember(_groupId: string, _targetId: string, _rejectAddRequest?: boolean, _kickReason?: string): Promise<void>;
+  /**
+   * 禁言群成员
+   */
+  setGroupMute(_groupId: string, _targetId: string, _duration: number): Promise<void>;
+  /**
+   * 群全员禁言
+   */
+  setGroupAllMute(_groupId: string, _isBan: boolean): Promise<void>;
+  /**
+   * 设置群管理员
+   */
+  setGroupAdmin(_groupId: string, _targetId: string, _isAdmin: boolean): Promise<void>;
+  /**
+   * 设置群名片
+   */
+  setGroupMemberCard(_groupId: string, _targetId: string, _card: string): Promise<void>;
+  /**
+   * 设置群名
+   */
+  setGroupName(_groupId: string, _groupName: string): Promise<void>;
+  /**
+   * 退出群组
+   */
+  setGroupQuit(_groupId: string, _isDismiss: boolean): Promise<void>;
+  /**
+   * 设置群专属头衔
+   */
+  setGroupMemberTitle(_groupId: string, _targetId: string, _title: string): Promise<void>;
+  /**
+   * 获取陌生人信息
+   */
+  getStrangerInfo(_targetId: string): Promise<UserInfo>;
+  /**
+   * 获取好友列表
+   */
+  getFriendList(_refresh?: boolean): Promise<Array<UserInfo>>;
+  /**
+   * 获取群信息
+   */
+  getGroupInfo(_groupId: string, _noCache?: boolean): Promise<GroupInfo>;
+  /**
+   * 获取群列表
+   */
+  getGroupList(_refresh?: boolean): Promise<Array<GroupInfo>>;
+  /**
+   * 获取群成员信息
+   */
+  getGroupMemberInfo(_groupId: string, _targetId: string, _refresh?: boolean): Promise<GroupMemberInfo>;
+  /**
+   * 获取群成员列表
+   */
+  getGroupMemberList(_groupId: string, _refresh?: boolean): Promise<Array<GroupMemberInfo>>;
+  /**
+   * 获取群荣誉信息
+   */
+  getGroupHonor(_groupId: string): Promise<Array<QQGroupHonorInfo>>;
+  /**
+   * 设置好友请求结果
+   */
+  setFriendApplyResult(_requestId: string, _isApprove: boolean, _remark?: string): Promise<void>;
+  /**
+   * 设置申请加入群请求结果
+   */
+  setGroupApplyResult(_requestId: string, _isApprove: boolean, _denyReason?: string): Promise<void>;
+  /**
+   * 设置邀请加入群请求结果
+   */
+  setInvitedJoinGroupResult(_requestId: string, _isApprove: boolean): Promise<void>;
+  /**
+   * 设置消息表情回应
+   */
+  setMsgReaction(_contact: Contact, _messageId: string, _faceId: number | string, _isSet: boolean): Promise<void>;
+  /**
+   * 上传群文件、私聊文件
+   */
+  uploadFile(_contact: Contact, _file: string, _name: string, _folder?: string): Promise<void>;
+  /**
+   * 下载文件到协议端本地
+   */
+  downloadFile(_options?: DownloadFileOptions): Promise<DownloadFileResponse>;
+  /**
+   * 创建群文件夹
+   */
+  createGroupFolder(_groupId: string, _name: string): Promise<CreateGroupFolderResponse>;
+  /**
+   * 重命名群文件夹
+   */
+  renameGroupFolder(_groupId: string, _folderId: string, _name: string): Promise<boolean>;
+  /**
+   * 删除群文件夹
+   */
+  delGroupFolder(_groupId: string, _folderId: string): Promise<boolean>;
+  /**
+   * 上传群文件
+   */
+  uploadGroupFile(_groupId: string, _file: string, _name?: string): Promise<boolean>;
+  /**
+   * 获取文件 url
+   */
+  getFileUrl(_contact: Contact, _fileId: string): Promise<string>;
+  /**
+   * 删除群文件
+   */
+  delGroupFile(_groupId: string, _fileId: string, _busId: number): Promise<boolean>;
+  /**
+   * 获取群文件系统信息
+   */
+  getGroupFileSystemInfo(_groupId: string): Promise<GetGroupFileSystemInfoResponse>;
+  /**
+   * 获取群文件夹下文件列表
+   */
+  getGroupFileList(_groupId: string, _folderId?: string): Promise<GetGroupFileListResponse>;
+  /**
+   * 设置群备注
+   */
+  setGroupRemark(_groupId: string, _remark: string): Promise<boolean>;
+  /**
+   * 获取陌生群信息
+   */
+  getNotJoinedGroupInfo(_groupId: string): Promise<GroupInfo>;
+  /**
+   * 获取艾特全体成员剩余次数
+   */
+  getAtAllCount(_groupId: string): Promise<GetAtAllCountResponse>;
+  /**
+   * 获取群被禁言用户列表
+   */
+  getGroupMuteList(_groupId: string): Promise<Array<GetGroupMuteListResponse>>;
+  /**
+   * 戳一戳用户
+   */
+  pokeUser(_contact: Contact, _targetId: string, _count?: number): Promise<boolean>;
+  /**
+   * 获取 Cookies
+   */
+  getCookies(_domain: string): Promise<{
+    cookie: string;
+  }>;
+  /**
+   * 获取 QQ 相关接口凭证
+   */
+  getCredentials(_domain: string): Promise<{
+    cookies: string;
+    csrf_token: number;
+  }>;
+  /**
+   * 获取 CSRF Token
+   */
+  getCSRFToken(): Promise<{
+    token: number;
+  }>;
+  /**
+   * 设置头像
+   */
+  setAvatar(_file: string): Promise<void>;
+  /**
+   * 获取 rkey
+   */
+  getRkey(): Promise<Array<GetRkeyResponse>>;
+  /**
+   * 获取群 Ai 语音可用声色列表
+   */
+  getAiCharacters(): Promise<Array<GetAiCharactersResponse>>;
+  /**
+   * 设置群 Ai 语音声色
+   */
+  sendAiCharacter(_groupId: string, _characterId: string, _text: string): Promise<{
+    messageId: string;
+  }>;
+}
+//#endregion
+export type { AdapterQQBot };