@karinjs/adapter-qqbot 1.3.1 → 2.0.0

package/dist/index.d.ts

@@ -1,499 +1,670 @@
-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, UserInfo, karinToQQBot } from "node-karin";
+import FormData from "form-data";
+import * as _$node_karin_axios0 from "node-karin/axios";
 
+//#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;
+  };
+  /** 当 msg_type = 7 时，content 字段需要填入一个值，譬如一个空格 “ ”，后续版本会修复该问题。 */
+  content: 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;
 }
 /** 发送频道消息后响应 */
 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) => _$node_karin_axios0.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>): Promise<T>;
+  protected put<T>(path: string, body?: unknown, headers?: Record<string, string>): 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 上传后是否由服务端直接发送
+   */
+  upload(scene: Scene, peer: string, type: MediaType, source: string, srvSendMsg?: boolean): Promise<UploadMediaResponse>;
+}
+//#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/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;
+  };
+  /** 事件接收配置 */
+  event: {
+    /** 接收方式 0 关闭 / 1 webhook / 2 ws */type: 0 | 1 | 2;
+  };
 }
+//#endregion
+//#region src/core/adapter/base.d.ts
 /**
- * @adaoter QQBot
- * @version 1.8.0
+ * QQ Official Bot 适配器
+ *
+ * 全场景统一走 msg_type=2 Markdown 通道（详见 pipeline-qq / pipeline-guild）。
+ * 视频 / 语音 / 文件由 pipeline 内部以 msg_type=7 紧随主消息补发。
  */
-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 AdapterQQBot extends AdapterBase implements AdapterType {
+  /** 与官方 API 交互 */
+  super: QQBotApi;
+  /** 当前 bot 配置 */
+  cfg: QQBotConfig;
+  /** openId / member_openid -> 昵称 缓存 */
+  nicknameCache: Map<string, string>;
+  constructor(cfg: QQBotConfig, api: QQBotApi);
+  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>;
+  /**
+   * 获取消息
+   */
+  getMsg(_contact: Contact | string, _messageId?: string): Promise<MessageResponse>;
+  /**
+   * 获取历史消息（通过消息 ID）
+   */
+  getHistoryMsg(_contact: Contact, _startMsgId: string, _count: number): Promise<Array<MessageResponse>>;
+  /**
+   * 获取历史消息（通过消息序列号）
+   */
+  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;
+  }>;
 }
-
-export { AdapterQQBot };
+//#endregion
+export { type AdapterQQBot };