@karinjs/adapter-qqbot 3.3.0 → 3.4.0

package/dist/base-Dw5yfdft.d.ts

@@ -0,0 +1,2688 @@
+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 } from "node-karin";
+import { AxiosRequestConfig, AxiosResponse } from "node-karin/axios";
+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，6 输入中状态（仅单聊），7 media 富媒体 */
+  msg_type: 0 | 2 | 3 | 4 | 6 | 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;
+  /**
+   * 指明发送消息为互动召回消息，与 msg_id、event_id 互斥使用
+   *
+   * 接口文档 v1.28.0（2026-09-03）起该字段已从群消息发送接口移除，
+   * 目前仅单聊 `POST /v2/users/{user_openid}/messages` 可用。
+   */
+  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 消息结构（官方已全量开放原生 markdown，2.0 不再支持模板模式） */
+interface Markdown {
+  /** markdown 文本 */
+  content: string;
+}
+/** keyboard 按钮渲染（Button.render_data） */
+interface KeyboardButtonRenderData {
+  /** 按钮文字，最多 10 字符 */
+  label?: string;
+  /** 点击后文字，不传则保持不变 */
+  visited_label?: string;
+  /**
+   * 按钮样式
+   * - `0` 灰色线框
+   * - `1` 蓝色线框
+   * - `3` 白色背景 + 红色字体
+   * - `4` 蓝色背景 + 白色字体
+   *
+   * 接口文档 v1.28.0（2026-09-03）重定义了取值，旧文档中的 `2`（白字）已被移除。
+   */
+  style?: number;
+}
+/** keyboard 按钮点击权限（Button.action.permission） */
+interface KeyboardButtonPermission {
+  /** 0 指定用户可操作，1 仅管理者可操作，2 所有人可操作，3 指定身份组可操作（仅频道可用） */
+  type?: number;
+  /** 有权限的用户 id 的列表 */
+  specify_user_ids?: string[];
+  /** 有权限的身份组 id 的列表（仅频道可用） */
+  specify_role_ids?: string[];
+}
+/**
+ * 按钮二次确认（Button.action.modal）
+ *
+ * 接口文档 v1.28.0（2026-09-03）新增：点击按钮后先弹确认框，确认后才触发按钮行为。
+ */
+interface KeyboardButtonModal {
+  /** 二次确认的提示文本，不为空则进行二次确认；最多 40 个字符，不能有 URL */
+  content?: string;
+  /** 确认按钮上展示的文字，可为空，默认「确认」；最多 4 个字符 */
+  confirm_text?: string;
+  /** 取消按钮上展示的文字，可为空，默认「取消」；最多 4 个字符 */
+  cancel_text?: string;
+}
+/** keyboard 按钮点击行为（Button.action） */
+interface KeyboardButtonAction {
+  /** 0 跳转按钮（http / 小程序 scheme），1 回调按钮（回调后台接口），2 指令按钮（在输入框插入 @bot data） */
+  type?: number;
+  /** 权限设置 */
+  permission?: KeyboardButtonPermission;
+  /** 操作相关的数据 */
+  data?: string;
+  /** 客户端不支持本 action 的时候，弹出的 toast 文案 */
+  unsupport_tips?: string;
+  /** 指令按钮可用，点击按钮后直接自动发送 data，仅单聊可用，默认 false（支持版本 8983） */
+  enter?: boolean;
+  /** 指令按钮可用，指令是否带引用回复本消息，默认 false（支持版本 8983） */
+  reply?: boolean;
+  /**
+   * 仅在指令按钮下有效，设置后会忽略 `enter` 配置。
+   * 设为 1 时点击按钮自动唤起手 Q 选图器（仅手机端 8983+ 的单聊场景）。
+   */
+  anchor?: number;
+  /** 用户点击后的二次确认操作 */
+  modal?: KeyboardButtonModal;
+  /** @deprecated 官方已弃用：可操作点击的次数 */
+  click_limit?: number;
+  /** @deprecated 官方已弃用：指令按钮弹出子频道选择器 */
+  at_bot_show_channel_list?: boolean;
+}
+/**
+ * keyboard 按钮（Button）
+ *
+ * 字段与官方文档一致，并且是 node-karin `QQBotButton` 的结构超集，
+ * 因此 `karinToQQBot()` 的输出可以直接放进 {@link Keyboard}。
+ */
+interface KeyboardButton {
+  /** 按钮 ID，同一键盘内唯一 */
+  id?: string;
+  /** 按钮渲染 */
+  render_data?: KeyboardButtonRenderData;
+  /** 按钮点击行为 */
+  action?: KeyboardButtonAction;
+  /**
+   * 分组 ID，同一分组内有一个按钮被操作后，其它按钮变灰不可点击
+   *
+   * 接口文档 v1.28.0（2026-09-03）新增，仅当 `action.type = 1` 时有效。
+   */
+  group_id?: string;
+}
+/** keyboard 一行按钮 */
+interface KeyboardRow {
+  /** 该行的按钮，官方限制每行最多 5 个 */
+  buttons: KeyboardButton[];
+}
+/** 按钮消息结构（官方已全量开放自定义 keyboard，2.0 不再支持模板按钮） */
+interface Keyboard {
+  /** 键盘内容，官方限制最多 5 行 */
+  content: {
+    rows: KeyboardRow[];
+  };
+}
+/** 发送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;
+}
+/** 发送QQ Ark 消息请求参数 */
+interface SendQQArkMessageRequest extends SendQQMessageRequest, QQMessageID {
+  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;
+  };
+  /**
+   * 按钮。
+   *
+   * `keyboard` 在官方发消息接口中是与 `content` / `markdown` / `media` 平级的独立字段，
+   * 文档未声明它与 `media` 互斥（互斥约束只写在 `content` / `markdown` / `ark` 之间），
+   * 接口说明也写明「支持文本/Markdown/富媒体等类型，可附带内嵌键盘」。
+   *
+   * 用于图片走 QQ 上传兜底（无法进入 markdown）时，让按钮随富媒体一起发出，
+   * 避免额外产生一条只有按钮的空消息。若平台拒绝（305007），发送层会去掉
+   * keyboard 重试一次，保证富媒体本身能送达。
+   */
+  keyboard?: Keyboard;
+}
+/** 发送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消息请求参数 */
+type SendQQMsg = SendQQTextMessageRequest | SendQQMarkdownMessageRequest | SendQQArkMessageRequest | SendQQMediaMessageRequest;
+/** 发送频道被动消息参数 */
+interface SendGuildMessageID {
+  /** 消息ID */
+  msg_id?: string;
+  /** 事件id */
+  event_id?: string;
+  /** 引用消息对象 */
+  message_reference?: MessageReference;
+}
+/** 发送频道引用消息参数 */
+interface SendGuildQuoteMessage {
+  /** 引用消息的ID */
+  message_id?: string;
+  /** 是否忽略获取引用消息详情错误，默认否 */
+  ignore_get_message_error?: boolean;
+}
+/** 发送频道消息请求参数基类 */
+interface SendGuildMessageRequest {
+  /** 单独加一个类型 用于区分不同的消息类型 */
+  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;
+}
+/** 发送频道 图片 消息请求参数 */
+interface SendGuildImageMessageRequest extends SendGuildMessageID, SendGuildQuoteMessage, SendGuildMessageRequest {
+  type: 'image';
+  /** 图片url地址 */
+  image: string;
+}
+/** embeds消息结构 */
+interface Embeds {
+  /** 标题 */
+  title: string;
+  /** 消息弹窗内容 */
+  prompt: string;
+  /** 缩略图 */
+  thumbnail: {
+    /** 图片地址 */
+    url: string;
+  };
+  /** embed 字段数据 */
+  fields: Record<string, any>[];
+}
+/** 发送频道 embed 消息请求参数 */
+interface SendGuildEmbedMessageRequest extends SendGuildMessageID, SendGuildMessageRequest {
+  type: 'embed';
+  /** embed 消息内容 */
+  embed: Embeds;
+}
+/** ark消息结构 */
+interface Ark {
+  /** 模版id */
+  template_id: number;
+  /** 模版内变量与填充值的kv映射 */
+  kv: {
+    key: string;
+    value: string;
+    /** 这个嵌套是认真的嘛... */
+    obj: {
+      obj_kv: {
+        key: string;
+        value: string;
+      }[];
+    }[];
+  }[];
+}
+/** 发送频道 ark 消息请求参数 */
+interface SendGuildArkMessageRequest extends SendGuildMessageID, SendGuildMessageRequest {
+  type: 'ark';
+  /** ark 消息内容 */
+  ark: Ark;
+}
+/** 发送频道 markdown 消息请求参数 */
+interface SendGuildMarkdownMessageRequest extends SendGuildMessageID, SendGuildMessageRequest {
+  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;
+}
+/** 创建私信会话接口响应 */
+interface DmsResponse {
+  /** 频道ID 用于私信会话使用 */
+  guild_id: string;
+  /** 子频道ID 用于私信会话使用 */
+  channel_id: string;
+  /** 创建时间 */
+  create_time: string;
+}
+/** 发送QQ消息后响应 */
+interface SendQQMsgResponse {
+  /** 消息唯一 ID */
+  id: string;
+  /** 发送时间 */
+  timestamp: number | string;
+  /** 扩展信息；部分 QQ 消息发送响应会返回可用于 message_reference 的 REFIDX。 */
+  ext_info?: {
+    /** 当前发送消息可被引用时使用的索引。 */
+    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}）
+ *
+ * 该接口在接口文档 v1.28.0（2026-09-03）转为公开文档，属「内邀接入」的白名单接口，
+ * 未获权限时平台返回错误码 11253。官方昵称字段为 `username`，`nick` 是转公开之前
+ * 腾讯官方 openclaw 插件（@tencent-connect/openclaw-qqbot v2.0.0）使用的字段名，
+ * 保留以兼容旧返回。
+ */
+interface QQGroupMemberResponse {
+  /** 群成员 openid */
+  member_openid?: string;
+  /** 用户昵称 */
+  username?: string;
+  /**
+   * 群成员昵称
+   * @deprecated 官方公开文档中的字段名是 {@link QQGroupMemberResponse.username}
+   */
+  nick?: string;
+  /** 入群时间，RFC3339 格式 */
+  joined_at?: string;
+  /** 群内角色：owner / admin / member */
+  member_role?: 'owner' | 'admin' | 'member';
+  /** 是否机器人 */
+  bot?: boolean;
+  /** 用户在应用/开放平台下的统一标识（如有） */
+  union_openid?: string;
+  /** 其余未公开字段原样保留 */
+  [key: string]: unknown;
+}
+/** 发送频道消息后响应 */
+interface SendGuildResponse {
+  /** 消息唯一 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;
+  /**
+   * 文件下载链接（COS 预签名 GET URL），有效期与 `ttl` 一致。
+   *
+   * 仅分片上传合并（走 `upload_id` 路径）且 `file_type` 为图片/视频/语音时返回；
+   * URL 直传和文件类型（`file_type=4`）不返回该字段。
+   *
+   * 这是把 QQ 分片上传当图床用的关键：拿到该直链后，图片就能以 markdown
+   * 图片语法嵌入 msg_type=2，不必再走 msg_type=7 富媒体单独发送。
+   */
+  raw_url?: string;
+}
+/** 申请上传 Markdown 素材图片（POST /v2/media-images/prepare） */
+interface MediaImagePrepareRequest {
+  /** 文件名（含扩展名） */
+  file_name: string;
+  /** 文件大小（字节） */
+  file_size: number;
+  /** 图片 MIME 类型：image/png / image/jpeg / image/gif / image/webp */
+  content_type: string;
+  /** 文件内容 MD5（32 位十六进制） */
+  md5: string;
+  /** 文件内容 SHA1（40 位十六进制） */
+  sha1: string;
+}
+/** 申请上传 Markdown 素材图片的响应 */
+interface MediaImagePrepareResponse {
+  /** 上传任务 ID，4 小时内有效 */
+  upload_id: string;
+  /** 预签名上传 URL，使用 HTTP PUT 直传图片二进制 */
+  presigned_url: string;
+  /** 预签名 URL 有效期（秒） */
+  expires_in: number;
+}
+/** 完成 Markdown 素材图片上传（POST /v2/media-images/complete） */
+interface MediaImageCompleteRequest {
+  /** prepare 返回的上传任务 ID */
+  upload_id: string;
+  /** 文件 MD5（32 位十六进制），服务端会与 COS 对象实际 ETag 比对 */
+  md5: string;
+}
+/** 完成 Markdown 素材图片上传的响应 */
+interface MediaImageCompleteResponse {
+  /** 图片 ID，用于查询与删除 */
+  image_id: string;
+  /** Markdown 引用链接：`qqbot-media://image/v1/<token>` */
+  url: string;
+  /** 滑动有效期窗口（秒） */
+  ttl: number;
+  /** 临时预览链接，短时效，请勿持久化存储 */
+  preview_url?: string;
+}
+/** 查询 Markdown 素材图片列表的查询参数 */
+interface MediaImageListParams {
+  /** 翻页游标；首页不传，末页返回空字符串 */
+  cursor?: string;
+}
+/** Markdown 素材图片列表项 */
+interface MediaImageItem {
+  image_id: string;
+  url: string;
+  file_name: string;
+  preview_url?: string;
+  created_at: number;
+  expires_at: number;
+}
+/** 查询 Markdown 素材图片列表的响应 */
+interface MediaImageListResponse {
+  images: MediaImageItem[];
+  next_cursor: string;
+  total: number;
+}
+/** 自定义菜单按钮类型 */
+type MenuItemType = 'switch' | 'send_message' | 'link' | 'menu';
+/** 自定义菜单开关配置（仅 type=switch 时有效） */
+interface MenuSwitch {
+  /**
+   * 开关唯一标识
+   *
+   * 用户切换开关状态后会发送一条消息，消息 `ext` 字段中携带 `{switch_id}=1`；
+   * 关闭后不携带该标识。
+   */
+  switch_id?: string;
+  /** 开关的初始状态，true 默认打开 */
+  default?: boolean;
+}
+/** 自定义菜单二级菜单项（不支持再嵌套子菜单） */
+interface SubMenuItem {
+  /** 按钮名称，最多 14 个字符（约 7 个中文汉字） */
+  name?: string;
+  /** 按钮类型，二级菜单仅支持 send_message / link */
+  type?: Extract<MenuItemType, 'send_message' | 'link'>;
+  /** 发送的内容，仅 type=send_message 时有效，用户点击后自动填入输入框 */
+  send_message?: string;
+  /** 跳转链接，仅 type=link 时有效，必须以 https:// 开头 */
+  link?: string;
+}
+/** 自定义菜单一级菜单项 */
+interface MenuItem {
+  /** 按钮名称，最多 10 个字符（一个中文汉字算 2 个字符） */
+  name?: string;
+  /** 按钮类型 */
+  type?: MenuItemType;
+  /** 子菜单列表，仅 type=menu 时有效，最多 5 个 */
+  sub_menu_items?: SubMenuItem[];
+  /** 发送的内容，仅 type=send_message 时有效，用户点击后自动填入输入框 */
+  send_message?: string;
+  /** 跳转链接，仅 type=link 时有效，必须以 https:// 开头 */
+  link?: string;
+  /** 开关配置，仅 type=switch 时有效 */
+  switch?: MenuSwitch;
+}
+/** 自定义菜单配置 */
+interface Menu {
+  /** 菜单项列表，最多 10 个，按列表顺序从左到右展示 */
+  items?: MenuItem[];
+}
+/** 查询全局自定义菜单响应（GET /v2/menu） */
+interface GetMenuResponse {
+  /** 当前菜单的版本号 */
+  version: number;
+  /** 当前生效的菜单配置；未设置过菜单时该字段为空 */
+  menu?: Menu;
+}
+/** 修改全局自定义菜单响应（PUT /v2/menu） */
+interface UpdateMenuResponse {
+  /** 本次修改后的菜单版本号，可用于后续判断配置是否有变更 */
+  version: number;
+}
+/** 指令面板生效场景：c2c 单聊 / group 群聊 / channel 文字子频道 / dm 频道私信 */
+type PanelScope = 'c2c' | 'group' | 'channel' | 'dm';
+/** 指令面板作用范围：all 全局生效 / specific 指定用户或群生效 */
+type PanelTargetType = 'all' | 'specific';
+/** 指令面板元素类型 */
+type PanelItemType = 'command' | 'link';
+/** 指令面板元素 */
+interface PanelItem {
+  /**
+   * 元素名称，最多 14 个字符（约 7 个中文汉字）
+   *
+   * type=command 时用户点击后该内容会填入聊天输入框；type=link 时仅用于面板展示。
+   */
+  name?: string;
+  /** 元素描述，最多 30 个字符（约 15 个中文汉字），在面板中展示给用户 */
+  desc?: string;
+  /** 元素类型 */
+  type?: PanelItemType;
+  /** 是否仅管理员可操作，true 时仅频道/群管理员可点击 */
+  only_admin?: boolean;
+  /** 跳转链接，仅 type=link 时有效，必须以 https:// 开头 */
+  link?: string;
+}
+/** 指令面板配置内容 */
+interface Panel {
+  /** 面板元素列表，一个面板最多配置 20 个元素 */
+  items?: PanelItem[];
+  /** 面板备注，最多 255 个字符，不对用户展示 */
+  remark?: string;
+  /** 当前版本号 */
+  version?: number;
+}
+/** 查询指令面板列表查询参数（GET /v2/panels） */
+interface GetPanelListParams {
+  /** 生效场景，必填 */
+  scope: PanelScope;
+  /** 分页游标，首次请求不传或传空串，后续传上次响应的 next_cursor */
+  cursor?: string;
+  /** 每页拉取条数，默认 20，最大 50 */
+  limit?: number;
+}
+/** 指令面板记录 */
+interface PanelRecord {
+  /** 面板 ID */
+  panel_id: string;
+  /** 生效场景 */
+  scope: PanelScope;
+  /** 作用范围，仅 c2c/group 场景可能为 specific */
+  target_type: PanelTargetType;
+  /** 面板配置内容 */
+  panel: Panel;
+  /** 面板创建时间，RFC3339 格式 */
+  created_at?: string;
+  /** 面板更新时间，RFC3339 格式 */
+  updated_at?: string;
+  /** 面板版本号 */
+  version: number;
+}
+/** 查询指令面板列表响应（GET /v2/panels） */
+interface GetPanelListResponse {
+  /** 面板记录列表，按设置时间倒序排列 */
+  records: PanelRecord[];
+  /** 下一页游标，空串表示已到最后一页 */
+  next_cursor: string;
+  /** 是否已拉取到最后一页 */
+  is_end: boolean;
+}
+/** 创建指令面板请求体（POST /v2/panels） */
+interface CreatePanelRequest {
+  /** 生效场景，channel / dm 场景 target_type 只能为 all */
+  scope: PanelScope;
+  /** 作用范围，仅 c2c / group 场景支持 specific */
+  target_type?: PanelTargetType;
+  /** 用户 openid 列表，仅 c2c 场景且 target_type=specific 时有效，一次最多 20 个 */
+  user_openids?: string[];
+  /** 群 openid 列表，仅 group 场景且 target_type=specific 时有效，一次最多 20 个 */
+  group_openids?: string[];
+  /** 面板配置内容 */
+  panel: Panel;
+}
+/** 创建指令面板响应（POST /v2/panels） */
+interface CreatePanelResponse {
+  /** 新创建的面板 ID，后续修改、删除、查询详情均需使用此 ID */
+  panel_id: string;
+}
+/** 查询指令面板详情响应（GET /v2/panels/{panel_id}） */
+interface GetPanelResponse extends PanelRecord {
+  /** 关联的用户 openid 列表，仅 c2c 场景且 target_type=specific 时返回，最多 1000 条 */
+  user_openids?: string[];
+  /** 关联的群 openid 列表，仅 group 场景且 target_type=specific 时返回，最多 1000 条 */
+  group_openids?: string[];
+}
+/** 修改指令面板响应（PUT /v2/panels/{panel_id}） */
+interface UpdatePanelResponse {
+  /** 本次修改后的面板版本号 */
+  version: number;
+}
+/** 修改指令面板关联对象请求体（PUT /v2/panels/{panel_id}/target） */
+interface UpdatePanelTargetRequest {
+  /** 操作类型：add 添加关联对象 / del 移除关联对象 */
+  op: 'add' | 'del';
+  /** 用户 openid 列表，仅 c2c 场景有效，一次最多 20 个 */
+  user_openids?: string[];
+  /** 群 openid 列表，仅 group 场景有效，一次最多 20 个 */
+  group_openids?: string[];
+}
+/** 频道信息 */
+interface GuildInfo {
+  /** 频道 ID */
+  id: string;
+  /** 频道名称 */
+  name: string;
+  /** 频道头像 URL */
+  icon?: string;
+  /** 频道创建者 ID */
+  owner_id?: string;
+  /** 当前机器人是否为频道创建者 */
+  owner?: boolean;
+  /** 加入时间，ISO8601 格式 */
+  joined_at?: string;
+  /** 频道成员数 */
+  member_count?: number;
+  /** 频道成员上限 */
+  max_members?: number;
+  /** 频道简介 */
+  description?: string;
+}
+/** 获取机器人加入的频道列表查询参数（GET /users/@me/guilds） */
+interface GetGuildListParams {
+  /** 读取此 guild_id 之前的数据，设置时先反序再分页 */
+  before?: string;
+  /** 读取此 guild_id 之后的数据，与 before 同时设置时 after 无效 */
+  after?: string;
+  /** 每次拉取条数，默认 100，最大 100 */
+  limit?: number;
+}
+/** 子频道类型：0=文字，2=语音，4=分组，10005=直播，10006=应用，10007=论坛 */
+type ChannelType = 0 | 2 | 4 | 10005 | 10006 | 10007;
+/** 文字子频道子类型：0=闲聊，1=公告，2=攻略，3=开黑 */
+type ChannelSubType = 0 | 1 | 2 | 3;
+/** 子频道私密类型：0=公开，1=群主管理员可见，2=群主管理员+指定成员 */
+type ChannelPrivateType = 0 | 1 | 2;
+/** 子频道发言权限：0=无效，1=所有人，2=群主管理员+指定成员 */
+type ChannelSpeakPermission = 0 | 1 | 2;
+/** 子频道信息 */
+interface ChannelInfo {
+  /** 子频道 ID */
+  id: string;
+  /** 所属频道 ID */
+  guild_id: string;
+  /** 子频道名 */
+  name: string;
+  /** 子频道类型 */
+  type: ChannelType;
+  /** 子频道子类型（文字子频道） */
+  sub_type?: ChannelSubType;
+  /** 排序值，从 1 开始 */
+  position?: number;
+  /** 所属分组 ID（仅子频道有效） */
+  parent_id?: string;
+  /** 创建人 ID */
+  owner_id?: string;
+  /** 子频道私密类型 */
+  private_type?: ChannelPrivateType;
+  /** 子频道发言权限 */
+  speak_permission?: ChannelSpeakPermission;
+  /** 应用子频道标识 */
+  application_id?: string;
+  /** 用户拥有的子频道权限 */
+  permissions?: string;
+}
+/** 创建子频道请求体（POST /guilds/{guild_id}/channels） */
+interface CreateChannelRequest {
+  /** 子频道名称 */
+  name?: string;
+  /** 子频道类型 */
+  type?: ChannelType;
+  /** 子频道子类型 */
+  sub_type?: ChannelSubType;
+  /** 排序值（分组类型必须 >= 2） */
+  position?: number;
+  /** 所属分组 ID */
+  parent_id?: string;
+  /** 私密类型 */
+  private_type?: ChannelPrivateType;
+  /** 私密成员 ID 列表 */
+  private_user_ids?: string[];
+  /** 发言权限 */
+  speak_permission?: ChannelSpeakPermission;
+  /** 应用子频道 AppID */
+  application_id?: string;
+}
+/** 修改子频道请求体（PATCH /channels/{channel_id}），只需传入要修改的字段 */
+interface UpdateChannelRequest {
+  /** 子频道名 */
+  name?: string;
+  /** 排序 */
+  position?: number;
+  /** 分组 ID */
+  parent_id?: string;
+  /** 私密类型 */
+  private_type?: ChannelPrivateType;
+  /** 发言权限 */
+  speak_permission?: ChannelSpeakPermission;
+}
+/** 生成分享链接请求体（POST /v2/generate_url_link） */
+interface GenerateUrlLinkRequest {
+  /**
+   * 开发者自定义回调数据，最长 32 字符
+   *
+   * 用户通过该链接添加机器人时会透传回 `FRIEND_ADD` 事件的 `scene_param`。
+   */
+  callback_data?: string;
+}
+/** 生成分享链接响应（POST /v2/generate_url_link） */
+interface GenerateUrlLinkResponse {
+  /** 接口返回数据 */
+  data: {
+    /** 生成的分享链接 */
+    url: string;
+  };
+}
+/** 全员禁言模式：none 未开启 / always 始终禁言 / schedule 定时或周期性禁言 */
+type GroupMuteMode = 'none' | 'always' | 'schedule';
+/** 定时禁言规则 */
+interface MuteScheduleRule {
+  /** 任务 ID */
+  task_id: string;
+  /** 禁言开始时间（RFC3339 格式） */
+  start_at: string;
+  /** 禁言结束时间（RFC3339 格式） */
+  end_at: string;
+  /** 此规则是否启用 */
+  enabled: boolean;
+}
+/** 周期禁言规则 */
+interface MuteRecurringRule {
+  /** 任务 ID */
+  task_id: string;
+  /** 生效星期几列表，取值 1~7（1=周一，7=周日） */
+  weekdays: number[];
+  /** 时段开始时间，格式 HH:mm（北京时间） */
+  start_time: string;
+  /** 时段结束时间，格式 HH:mm（北京时间）；小于 start_time 表示跨天到次日 */
+  end_time: string;
+  /** 此规则是否启用 */
+  enabled: boolean;
+}
+/** 群级禁言规则（全员禁言配置） */
+interface GlobalMuteRule {
+  /** 全员禁言模式 */
+  mode: GroupMuteMode;
+  /** 定时禁言规则列表 */
+  schedule_rules?: MuteScheduleRule[];
+  /** 周期禁言规则列表 */
+  recurring_rules?: MuteRecurringRule[];
+}
+/** 成员禁言状态 */
+interface MemberMuteState {
+  /** 被禁言成员的 openid */
+  member_openid: string;
+  /** 禁言到期时间（RFC3339 格式） */
+  mute_expire_at: string;
+  /** 被禁言成员的昵称 */
+  username?: string;
+  /** 用户在应用/开放平台下的统一标识 */
+  union_openid?: string;
+}
+/**
+ * 设置成员禁言项（POST /v2/groups/{group_openid}/restrict_chat_setting）
+ *
+ * 单次请求最多 20 项（接口文档 v1.28.0 由 10 提升至 20）。
+ */
+interface SetMemberMuteState {
+  /** 操作类型：add 增加禁言，update 更新禁言到期时间，del 解除禁言 */
+  op: 'add' | 'update' | 'del';
+  /** 被禁言成员的 openid；增加 / 更新时只能操作普通成员，不能操作群主、管理员、机器人 */
+  member_openid: string;
+  /** 禁言到期时间（RFC3339 格式）；op=del 时可传空串表示立即解除禁言 */
+  mute_expire_at?: string;
+}
+/** 查询群禁言状态响应（GET /v2/groups/{group_openid}/restrict_chat_setting） */
+interface GetGroupMuteSettingResponse {
+  /** 群级禁言规则 */
+  global_rule?: GlobalMuteRule;
+  /** 当前处于禁言中的用户列表（不含已过期） */
+  members?: MemberMuteState[];
+}
+/** 入群验证方式 */
+interface JoinRequestVerifyInfo {
+  /** 入群验证方式 */
+  method: 'verify_message' | 'admin_review_qa';
+  /** 验证消息内容，仅 method=verify_message 时可能携带 */
+  verify_message?: string;
+  /** 问答列表，仅 method=admin_review_qa 时可能携带 */
+  review_qa_list?: {
+    /** 管理员设置的问题 */
+    question: string;
+    /** 申请人填写的答案 */
+    answer: string;
+  }[];
+}
+/** 入群申请 */
+interface JoinRequest {
+  /** 申请 ID，需要在审批接口回传 */
+  join_request_id: string;
+  /** 安全提示语 */
+  risk_tips?: string;
+  /** 用户在应用/开放平台下的统一标识 */
+  union_openid?: string;
+  /** 申请人 openid */
+  member_openid: string;
+  /** 申请人昵称 */
+  username?: string;
+  /** 申请时间戳（RFC3339 格式） */
+  apply_at?: string;
+  /** 申请来源：self_apply 主动申请，invited 被邀请 */
+  apply_source?: 'self_apply' | 'invited';
+  /** 邀请人 openid（apply_source=invited 时有效） */
+  invited_by?: string;
+  /** 是否为机器人账号 */
+  bot?: boolean;
+  /** 用户入群验证方式 */
+  verify_info?: JoinRequestVerifyInfo;
+}
+/** 入群申请列表查询参数（GET /v2/groups/{group_openid}/join_request_list） */
+interface GetJoinRequestListParams {
+  /** 分页游标，首次请求可不传或传空串 */
+  cursor?: string;
+  /** 单页数量，默认 20，最大 50 */
+  limit?: number;
+}
+/** 入群申请列表响应（GET /v2/groups/{group_openid}/join_request_list） */
+interface GetJoinRequestListResponse {
+  /** 入群申请列表 */
+  list: JoinRequest[];
+  /** 下一页游标，空串表示已到末页 */
+  next_cursor: string;
+}
+/** 入群申请审批请求体（POST /v2/groups/{group_openid}/approval_join_request/{member_openid}） */
+interface ApprovalJoinRequestBody {
+  /** 审批动作：approve 通过，decline 拒绝 */
+  op: 'approve' | 'decline';
+  /** 申请 ID */
+  join_request_id?: string;
+  /** 拒绝理由，op=decline 时可填 */
+  reject_reason?: string;
+  /** 是否同时加入群黑名单，默认 false，op=decline 时可填 */
+  add_to_member_blacklist?: boolean;
+}
+/** 群成员（GET /v2/groups/{group_openid}/members 列表项） */
+interface GroupMemberItem {
+  /** 成员 openid */
+  member_openid: string;
+  /** 用户昵称 */
+  username?: string;
+  /** 群成员角色：member 普通成员 / owner 群主 / admin 管理员 */
+  member_role?: 'owner' | 'admin' | 'member';
+  /** 是否机器人 */
+  bot?: boolean;
+  /** 入群时间戳（RFC3339 格式） */
+  joined_at?: string;
+  /** 用户在应用/开放平台下的统一标识（如有） */
+  union_openid?: string;
+}
+/** 群成员列表查询参数（GET /v2/groups/{group_openid}/members） */
+interface GetGroupMemberListParams {
+  /** 分页游标，首次请求可不传或传空串；后续传上一次响应的 next_cursor */
+  cursor?: string;
+}
+/** 群成员列表响应（GET /v2/groups/{group_openid}/members） */
+interface GetGroupMemberListResponse {
+  /** 成员列表，每次最多返回 30 条 */
+  members: GroupMemberItem[];
+  /** 下一页游标，空串表示已到末页 */
+  next_cursor: string;
+}
+/** 群成员批量移除请求体（POST /v2/groups/{group_openid}/batch_remove_members） */
+interface BatchRemoveGroupMembersBody {
+  /** 需要移除的成员 member_openid 列表，单次最多 20 个 */
+  member_openids: string[];
+  /** 是否同时加入群黑名单，默认 false */
+  add_to_member_blacklist?: boolean;
+}
+/** 群成员批量移除响应 */
+interface BatchRemoveGroupMembersResponse {
+  /** 成功时返回 success */
+  remove_members_result?: string;
+  /** 拉黑失败的 openid */
+  add_to_member_blacklist_fail_openids?: string[];
+}
+/** 群黑名单用户（GET /v2/groups/{group_openid}/member_blacklist 列表项） */
+interface GroupBlacklistUser {
+  /** 用户在应用/开放平台下的统一标识（如有） */
+  union_openid?: string;
+  /** 用户 openid */
+  member_openid: string;
+  /** 用户昵称 */
+  username?: string;
+  /** 拉黑时间戳（RFC3339 格式） */
+  banned_at?: string;
+  /** 是否为机器人账号 */
+  bot?: boolean;
+}
+/** 群黑名单查询参数（GET /v2/groups/{group_openid}/member_blacklist） */
+interface GetGroupMemberBlacklistParams {
+  /** 分页游标，首次请求可不传或传空串 */
+  cursor?: string;
+  /** 单页数量，默认 20，最大 100 */
+  limit?: number;
+}
+/** 群黑名单查询响应（GET /v2/groups/{group_openid}/member_blacklist） */
+interface GetGroupMemberBlacklistResponse {
+  /** 黑名单用户列表 */
+  users: GroupBlacklistUser[];
+  /** 下一页游标，空串表示已到末页 */
+  next_cursor: string;
+}
+/** 群黑名单操作请求体（POST /v2/groups/{group_openid}/member_blacklist） */
+interface SetGroupMemberBlacklistBody {
+  /** 操作类型：add 加入黑名单（目标成员在群中时无法加入），del 移出黑名单 */
+  op: 'add' | 'del';
+  /** 目标成员 openid 列表，单次最多 20 个 */
+  member_openids: string[];
+}
+/** 群黑名单操作响应 */
+interface SetGroupMemberBlacklistResponse {
+  /** 操作失败的 openid 列表，op=add / op=del 同义 */
+  fail_openids?: string[];
+}
+/** 入群自动审批策略 */
+interface JoinApprovalStrategy {
+  /** 策略 ID */
+  strategy_id: string;
+  /** 关联的群 openid 列表（创建时使用 group_openids 时返回） */
+  group_openids?: string[];
+  /** 关联的 QQ 群号列表（创建时使用 group_ids 时返回） */
+  group_ids?: string[];
+  /** 白名单中的号码数量（估算，可能存在少量误差） */
+  whitelist_user_count?: number;
+  /** 策略是否启用：on 启用 / off 关闭 */
+  is_enable: 'on' | 'off';
+  /** 过期时间（RFC3339 格式） */
+  expire_at?: string;
+  /** 创建时间（RFC3339 格式） */
+  created_at?: string;
+  /** 最近更新时间（RFC3339 格式） */
+  updated_at?: string;
+  /** 策略备注 */
+  remark?: string;
+}
+/** 查询入群自动审批策略列表查询参数（GET /v2/groups/join_approval_strategy） */
+interface GetJoinApprovalStrategyListParams {
+  /** 分页游标，首次请求可不传或传空串 */
+  cursor?: string;
+  /** 单页数量，默认 20，最大 50 */
+  limit?: number;
+}
+/** 查询入群自动审批策略列表响应 */
+interface GetJoinApprovalStrategyListResponse {
+  /** 生效中的策略列表 */
+  strategies: JoinApprovalStrategy[];
+  /** 下一页游标，空串表示已到末页 */
+  next_cursor: string;
+}
+/** 创建入群自动审批策略请求体（POST /v2/groups/join_approval_strategy） */
+interface CreateJoinApprovalStrategyRequest {
+  /** 关联的群 openid 列表，最多 100 个；与 group_ids 互斥且二选一必填 */
+  group_openids?: string[];
+  /** 关联的 QQ 群号列表，最多 100 个；与 group_openids 互斥且二选一必填 */
+  group_ids?: string[];
+  /** 是否启用策略，默认 on */
+  is_enable?: 'on' | 'off';
+  /** 过期时间（RFC3339 格式），不传默认一年过期 */
+  expire_at?: string;
+  /** 策略备注，最多 255 个汉字 */
+  remark?: string;
+}
+/** 创建入群自动审批策略响应 */
+interface CreateJoinApprovalStrategyResponse {
+  /** 服务端生成的策略 ID */
+  strategy_id: string;
+  /** 是否启用 */
+  is_enable: 'on' | 'off';
+  /** 过期时间（RFC3339 格式） */
+  expire_at?: string;
+}
+/** 修改入群自动审批策略请求体（PATCH /v2/groups/join_approval_strategy/{strategy_id}） */
+interface UpdateJoinApprovalStrategyRequest {
+  /** 是否启用策略 */
+  is_enable?: 'on' | 'off';
+  /** 过期时间（RFC3339 格式） */
+  expire_at?: string;
+  /** 关联群增删操作；群标识形式须与创建时一致 */
+  group_action?: {
+    /** 操作类型：add 新增关联群，del 删除关联群 */
+    op: 'add' | 'del';
+    /** 待操作的群 openid 列表；与 group_ids 互斥 */
+    group_openids?: string[];
+    /** 待操作的 QQ 群号列表；与 group_openids 互斥 */
+    group_ids?: string[];
+  };
+  /** 策略备注，最多 255 个汉字 */
+  remark?: string;
+}
+/** 修改入群自动审批策略响应 */
+interface UpdateJoinApprovalStrategyResponse {
+  /** 是否启用 */
+  is_enable: 'on' | 'off';
+  /** 过期时间（RFC3339 格式） */
+  expire_at?: string;
+}
+/** 修改策略白名单号码请求体（POST /v2/groups/join_approval_strategy/{strategy_id}/whitelist_users） */
+interface UpdateWhitelistUsersRequest {
+  /** 操作类型：add 新增号码，del 删除号码 */
+  op: 'add' | 'del';
+  /** QQ 号码列表，单次最多 10000 个；使用字符串类型避免 JS 精度问题 */
+  whitelist_users: string[];
+}
+/** 修改策略白名单号码响应 */
+interface UpdateWhitelistUsersResponse {
+  /** 策略 ID */
+  strategy_id: string;
+  /** 操作后策略当前白名单号码数（估算） */
+  whitelist_user_count: number;
+  /** 策略更新时间（RFC3339 格式） */
+  updated_at?: string;
+}
+//#endregion
+//#region src/core/internal/axios.d.ts
+/**
+ * 创建 axios 实例，自动从 tokens map 取最新 access_token
+ */
+declare const createAxiosInstance: (appId: string) => import("node-karin/axios").AxiosInstance;
+//#endregion
+//#region src/core/api/http.d.ts
+type AxiosInstance = ReturnType<typeof createAxiosInstance>;
+/**
+ * 单次请求的可选配置。
+ *
+ * 这是 axios 请求配置的常用子集；需要完整能力时用
+ * {@link Http.request} 或直接使用 `axios` 实例。
+ */
+interface RequestOptions {
+  /** 追加请求头，会与实例默认头合并 */
+  headers?: Record<string, string>;
+  /** 超时毫秒数，默认取实例配置（5500ms） */
+  timeout?: number;
+  /** query 参数，axios 会自动序列化后拼到 URL */
+  params?: Record<string, unknown>;
+  /** 中断信号 */
+  signal?: AbortSignal;
+  /** 响应类型，下载二进制时可传 `arraybuffer` */
+  responseType?: AxiosRequestConfig['responseType'];
+}
+/**
+ * Http 基础类，子模块继承此类共享 axios 实例与错误格式化
+ *
+ * 各请求方法均为 `protected`，只供各领域 API 子类内部使用；
+ * 需要给下游插件开放的裸请求入口见 {@link RequestApi}。
+ */
+declare class Http {
+  readonly axios: AxiosInstance;
+  constructor(axios: AxiosInstance);
+  protected get<T>(path: string, options?: RequestOptions): Promise<T>;
+  protected post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  protected put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  protected patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  protected delete<T>(path: string, options?: RequestOptions): Promise<T>;
+  /**
+   * 任意 method 的裸请求，返回响应体。
+   *
+   * @param config axios 请求配置，`url` 相对 `baseURL`。
+   * @returns 响应体 `data`。
+   */
+  protected request<T>(config: AxiosRequestConfig): Promise<T>;
+  /**
+   * 任意 method 的裸请求，返回完整 axios 响应。
+   *
+   * 需要读取响应头或状态码时使用。
+   *
+   * @param config axios 请求配置，`url` 相对 `baseURL`。
+   * @returns 完整 axios 响应。
+   */
+  protected requestRaw<T>(config: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+}
+//#endregion
+//#region src/core/api/request.d.ts
+/**
+ * 裸请求入口，供下游插件直接调用官方 OpenAPI。
+ *
+ * {@link Http} 的请求方法是 `protected`，只供各领域 API 子类内部使用；
+ * 本类把同一套方法以 `public` 暴露出来，用于官方新接口尚未被适配器封装、
+ * 或需要传自定义参数的场景：
+ *
+ * ```ts
+ * const bot = e.bot as AdapterQQBot
+ *
+ * // GET，query 走 params
+ * const menu = await bot.super.request.get('/v2/menu')
+ * const list = await bot.super.request.get('/v2/panels', { params: { scope: 'group', limit: 20 } })
+ *
+ * // POST / PUT / PATCH / DELETE
+ * await bot.super.request.post(`/v2/groups/${groupId}/messages`, { content: 'hi', msg_type: 0 })
+ * await bot.super.request.put('/v2/menu', { menu })
+ *
+ * // 任意 method
+ * await bot.super.request.request({ method: 'POST', url: '/v2/xxx', data: {} })
+ * ```
+ *
+ * 与直接用 `bot.super.axios` 的区别：
+ * - 自动解包 `response.data`；
+ * - 失败时抛出的 Error 已带请求路径、脱敏请求体、QQ 错误码中文描述和 TraceID。
+ *
+ * 需要读响应头或状态码时用 {@link RequestApi.requestRaw}；
+ * 需要完全裸的 axios 时用 `bot.super.axios`。
+ *
+ * 路径相对官方 API baseURL，鉴权头由拦截器自动注入，无需自己传 Authorization。
+ */
+declare class RequestApi extends Http {
+  /**
+   * GET 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+  /**
+   * POST 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param body 请求体，默认空对象。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  /**
+   * PUT 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param body 请求体，默认空对象。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  /**
+   * PATCH 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param body 请求体，默认空对象。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  /**
+   * DELETE 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+  /**
+   * 任意 method 的请求，返回响应体。
+   *
+   * @param config axios 请求配置，`url` 相对 baseURL。
+   * @returns 响应体。
+   */
+  request<T = unknown>(config: AxiosRequestConfig): Promise<T>;
+  /**
+   * 任意 method 的请求，返回完整 axios 响应。
+   *
+   * 需要读取响应头或状态码时使用。
+   *
+   * @param config axios 请求配置，`url` 相对 baseURL。
+   * @returns 完整 axios 响应。
+   */
+  requestRaw<T = unknown>(config: AxiosRequestConfig): Promise<AxiosResponse<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>;
+  /**
+   * 单聊输入中状态（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>;
+  /**
+   * 频道私信消息
+   * - 单参 (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 文件消息的展示文件名
+   * @param forceChunk 是否强制走分片上传，不按 5MB 阈值判断
+   * @returns 上传结果，包含后续发送消息所需的 file_info
+   */
+  uploadFallback(scene: Scene, peer: string, type: MediaType, source: string, srvSendMsg?: boolean, fileName?: string, forceChunk?: boolean): Promise<UploadMediaResponse>;
+  /**
+   * 上传资源并取回它的公网直链。
+   *
+   * 分片上传的合并响应里带 `raw_url`，等价于一个临时图床：拿到地址后图片就能以
+   * markdown 图片语法嵌进 msg_type=2，和文本、按钮合成一条消息，不必退化成
+   * 独立的 msg_type=7 富媒体消息。
+   *
+   * 与 `uploadFallback` 的差别只有一处：那边按体积决定是否分片，目标是拿
+   * `file_info`；这里必须无条件分片，否则服务端不会给出 `raw_url`。
+   *
+   * 直链的存活时间等于响应里的 `ttl`，属于临时地址，只适合当次发送使用。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid，决定上传归属的会话
+   * @param type 文件类型；`file` 无直链可取
+   * @param source 本地路径、http url、data URL、base64:// 或裸 base64
+   * @param fileName 文件名，同时用于推断直链声明的 MIME
+   * @returns 可直接嵌入消息的直链，以及原始上传响应
+   */
+  uploadForUrl(scene: Scene, peer: string, type: MediaType, source: string, fileName?: string): Promise<{
+    url: string;
+    response: 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/media-images.d.ts
+/**
+ * Markdown 素材图片管理。
+ *
+ * 官方接口文档 v1.42.0 新增 `/v2/media-images` 系列接口，用于把本地图片
+ * 上传为可长期复用的 `qqbot-media://` Markdown 引用。
+ */
+declare class MediaImagesApi extends Http {
+  /** 当前 bot 进程内按内容 MD5 复用的素材缓存。 */
+  private readonly cache;
+  /** 申请上传图片，获取 upload_id 与预签名 PUT 地址。 */
+  prepare(body: MediaImagePrepareRequest): Promise<MediaImagePrepareResponse>;
+  /** 完成图片上传，获取可写入 Markdown 的 `qqbot-media://` 引用。 */
+  complete(body: MediaImageCompleteRequest): Promise<MediaImageCompleteResponse>;
+  /** 查询当前机器人的有效素材图片。 */
+  list(params?: MediaImageListParams): Promise<MediaImageListResponse>;
+  /** 删除素材图片并释放数量配额。 */
+  delete<T = Record<string, never>>(imageId: string): Promise<T>;
+  /**
+   * 上传图片并返回可写入 Markdown 的 `qqbot-media://` 引用。
+   *
+   * 自动完成文件头识别、文件名规范化、MD5/SHA1 计算、预签名 PUT 与 complete。
+   *
+   * @param source 图片来源：Buffer、URL、本地路径、data URL 或 base64://。
+   * @param fileName 可选文件名；未提供时按真实图片格式生成。
+   * @returns complete 接口响应。
+   */
+  upload(source: string | Buffer | Uint8Array, fileName?: string): Promise<MediaImageCompleteResponse>;
+}
+//#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;
+  }>;
+  /**
+   * 生成机器人分享链接
+   *
+   * 用于邀请用户添加机器人为好友；`callback_data`（最长 32 字符）会在用户通过该
+   * 链接添加机器人时透传到 `FRIEND_ADD` 事件的 `scene_param`。
+   *
+   * @param body 分享链接参数，均为可选
+   */
+  generateUrlLink(body?: GenerateUrlLinkRequest): Promise<GenerateUrlLinkResponse>;
+}
+//#endregion
+//#region src/core/api/groups.d.ts
+/**
+ * QQ 群信息与群成员管理接口
+ *
+ * 注意：以下接口均为白名单接口，未开通权限时平台返回错误码 11253，
+ * 需要向平台运营申请后可用。接口文档 v1.28.0（2026-09-03）新增的群成员管理
+ * 接口（成员列表 / 批量移除 / 黑名单）官方标注为「正在内邀接入中」，
+ * 开放范围可能比其它白名单接口更窄。
+ */
+declare class GroupsApi extends Http {
+  /**
+   * 获取群基础信息
+   * @param groupOpenid 群 openid
+   */
+  getGroupInfo(groupOpenid: string): Promise<QQGroupInfoResponse>;
+  /**
+   * 获取机器人在群内的状态（角色、入群时间、主动消息开关等）
+   * @param groupOpenid 群 openid
+   */
+  getBotState(groupOpenid: string): Promise<GroupBotStateResponse>;
+  /**
+   * 获取群成员列表
+   *
+   * 每次最多返回 30 条，只支持 cursor 翻页：首次不传 `cursor`，之后回传上一次
+   * 响应的 `next_cursor`，`next_cursor` 为空串表示已到末页。
+   *
+   * @param groupOpenid 群 openid
+   * @param params 分页参数
+   */
+  getGroupMemberList(groupOpenid: string, params?: GetGroupMemberListParams): Promise<GetGroupMemberListResponse>;
+  /**
+   * 获取群成员详情
+   *
+   * 昵称字段为 `username`；`nick` 是该接口转为公开文档之前的字段名，仅作兼容。
+   *
+   * @param groupOpenid 群 openid
+   * @param memberOpenid 群成员 openid
+   */
+  getGroupMember(groupOpenid: string, memberOpenid: string): Promise<QQGroupMemberResponse>;
+  /**
+   * 群成员批量移除
+   *
+   * 单次最多 20 个成员，可通过 `add_to_member_blacklist` 在移除的同时拉黑。
+   * 机器人需拥有群管理员身份。
+   *
+   * @param groupOpenid 群 openid
+   * @param body 待移除的成员列表与是否同时拉黑
+   */
+  batchRemoveGroupMembers(groupOpenid: string, body: BatchRemoveGroupMembersBody): Promise<BatchRemoveGroupMembersResponse>;
+  /**
+   * 查询群黑名单
+   *
+   * @param groupOpenid 群 openid
+   * @param params 分页参数，`limit` 默认 20、最大 100
+   */
+  getGroupMemberBlacklist(groupOpenid: string, params?: GetGroupMemberBlacklistParams): Promise<GetGroupMemberBlacklistResponse>;
+  /**
+   * 群黑名单操作
+   *
+   * 只有目标用户不在群中时才能加入黑名单，需要先移除再拉黑；单次最多 20 个。
+   * 返回的 `fail_openids` 在 `op=add` / `op=del` 下同义，都是操作失败的 openid。
+   *
+   * @param groupOpenid 群 openid
+   * @param body 操作类型与目标成员列表
+   */
+  setGroupMemberBlacklist(groupOpenid: string, body: SetGroupMemberBlacklistBody): Promise<SetGroupMemberBlacklistResponse>;
+  /**
+   * 设置群成员禁言
+   *
+   * 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天；
+   * 只能操作普通成员，不能操作群主、管理员与机器人。
+   * 需要一次设置多个成员时用 {@link GroupsApi.setGroupMuteBatch}。
+   *
+   * @param groupOpenid 群 openid
+   * @param memberOpenid 群成员 openid
+   * @param op 操作: add 增加禁言，update 更新禁言到期时间，del 解除禁言
+   * @param duration 禁言时间使用RFC3339 格式
+   */
+  setGroupMute(groupOpenid: string, memberOpenid: string, op: 'add' | 'update' | 'del', duration: string): Promise<{}>;
+  /**
+   * 批量设置群成员禁言
+   *
+   * 每项通过自身的 `op` 控制增 / 改 / 删，可以在一次请求里混用。
+   * 平台限制单次最多 20 个成员（接口文档 v1.28.0 由 10 提升至 20），
+   * 超出时平台会直接拒绝整个请求。
+   *
+   * @param groupOpenid 群 openid
+   * @param members 成员禁言设置列表
+   */
+  setGroupMuteBatch(groupOpenid: string, members: SetMemberMuteState[]): Promise<{}>;
+  /**
+   * 设置群成员禁言
+   * @deprecated 方法名拼写错误，请使用 {@link GroupsApi.setGroupMute}
+   */
+  setGroupMetu(groupOpenid: string, memberOpenid: string, op: 'add' | 'update' | 'del', duration: string): Promise<{}>;
+  /**
+   * 查询群禁言状态
+   *
+   * 返回全员禁言模式（含定时 / 周期规则）与当前禁言中的成员列表（不含已过期）。
+   * 机器人需拥有群管理员身份。
+   *
+   * @param groupOpenid 群 openid
+   */
+  getGroupMuteSetting(groupOpenid: string): Promise<GetGroupMuteSettingResponse>;
+  /**
+   * 拉取入群申请列表
+   *
+   * 机器人需拥有群管理员身份。
+   *
+   * @param groupOpenid 群 openid
+   * @param params 分页参数，`limit` 默认 20、最大 50（接口文档 v1.28.0 由 100 下调），
+   * 传入更大的值会被收敛到 50，避免平台直接拒绝
+   */
+  getJoinRequestList(groupOpenid: string, params?: GetJoinRequestListParams): Promise<GetJoinRequestListResponse>;
+  /**
+   * 审批入群申请
+   *
+   * 机器人需拥有群管理员身份。
+   *
+   * @param groupOpenid 群 openid
+   * @param memberOpenid 申请人 openid
+   * @param body 审批动作，`op=decline` 时可附带拒绝理由与拉黑标记
+   */
+  approvalJoinRequest(groupOpenid: string, memberOpenid: string, body: ApprovalJoinRequestBody): Promise<{}>;
+}
+//#endregion
+//#region src/core/api/guilds.d.ts
+/**
+ * 频道 / 子频道接口
+ *
+ * 子频道的创建、修改、删除均需要管理员权限且属于私域接口，
+ * 操作成功后会触发 `CHANNEL_CREATE` / `CHANNEL_UPDATE` / `CHANNEL_DELETE` 事件。
+ */
+declare class GuildsApi extends Http {
+  /**
+   * 获取机器人加入的频道列表
+   *
+   * 官方文档响应体标注为 `{ guilds: [] }`，但示例与实际返回均为裸数组；
+   * 这里对两种形态都做兼容。
+   *
+   * @param params 分页参数，`limit` 默认 100、最大 100
+   */
+  getGuildList(params?: GetGuildListParams): Promise<GuildInfo[]>;
+  /**
+   * 获取频道详情
+   * @param guildId 频道 ID
+   */
+  getGuild(guildId: string): Promise<GuildInfo>;
+  /**
+   * 获取子频道列表
+   *
+   * 官方文档响应体标注为 `{ channels: [] }`，但示例与实际返回均为裸数组；
+   * 这里对两种形态都做兼容。
+   *
+   * @param guildId 频道 ID
+   */
+  getChannelList(guildId: string): Promise<ChannelInfo[]>;
+  /**
+   * 创建子频道（需要管理员权限，私域接口）
+   * @param guildId 频道 ID
+   * @param body 子频道配置
+   */
+  createChannel(guildId: string, body: CreateChannelRequest): Promise<ChannelInfo>;
+  /**
+   * 获取子频道详情
+   * @param channelId 子频道 ID
+   */
+  getChannel(channelId: string): Promise<ChannelInfo>;
+  /**
+   * 修改子频道（需要管理员权限，私域接口）
+   *
+   * 只需传入要修改的字段。
+   * @param channelId 子频道 ID
+   * @param body 待修改的字段
+   */
+  updateChannel(channelId: string, body: UpdateChannelRequest): Promise<ChannelInfo>;
+  /**
+   * 删除子频道（需要管理员权限，私域接口）
+   *
+   * 子频道删除后无法恢复。
+   * @param channelId 子频道 ID
+   */
+  deleteChannel(channelId: string): Promise<{}>;
+}
+//#endregion
+//#region src/core/api/menu.d.ts
+/**
+ * 全局自定义菜单接口
+ *
+ * 自定义菜单展示在机器人单聊窗口底部，仅支持 C2C（单聊）场景，
+ * 设置后对所有用户生效，不支持按用户维度区分。
+ *
+ * {@link https://bot.q.qq.com/wiki/develop/api-v2/server-inter/menu-panel/}
+ */
+declare class MenuApi extends Http {
+  /**
+   * 查询全局自定义菜单
+   *
+   * 未设置过菜单时响应的 `menu` 字段为空。
+   * @returns 当前生效的菜单配置与版本号
+   */
+  getMenu(): Promise<GetMenuResponse>;
+  /**
+   * 修改全局自定义菜单
+   *
+   * 传入后会覆盖原有的完整菜单配置；不传 `menu` 表示清空菜单。
+   * @param menu 菜单配置，最多 10 个一级菜单项
+   * @returns 本次修改后的菜单版本号
+   */
+  updateMenu(menu?: Menu): Promise<UpdateMenuResponse>;
+}
+//#endregion
+//#region src/core/api/panels.d.ts
+/**
+ * 指令面板接口
+ *
+ * 指令面板以面板形式展示指令或链接，支持 c2c（单聊）、group（群聊）、
+ * channel（文字子频道）、dm（频道私信）四种场景；其中 c2c / group 支持
+ * 按指定用户或群生效（target_type=specific），channel / dm 仅支持全局配置。
+ *
+ * 一个机器人最多创建 20 个指令面板。
+ *
+ * {@link https://bot.q.qq.com/wiki/develop/api-v2/server-inter/menu-panel/}
+ */
+declare class PanelsApi extends Http {
+  /**
+   * 查询指令面板列表
+   *
+   * 分页拉取指定场景下已生效的面板，按设置时间倒序排列。
+   * @param params 查询参数，`scope` 必填
+   * @returns 面板记录列表与分页游标
+   */
+  getPanelList(params: GetPanelListParams): Promise<GetPanelListResponse>;
+  /**
+   * 创建指令面板
+   * @param body 面板场景、作用范围与配置内容
+   * @returns 新创建的面板 ID
+   */
+  createPanel(body: CreatePanelRequest): Promise<CreatePanelResponse>;
+  /**
+   * 查询指令面板详情
+   *
+   * 返回面板完整配置，target_type=specific 时同时返回关联的用户 / 群 openid 列表。
+   * @param panelId 面板 ID
+   */
+  getPanel(panelId: string): Promise<GetPanelResponse>;
+  /**
+   * 修改指令面板
+   *
+   * 传入后会覆盖原有的面板元素列表和备注，不影响已关联的用户 / 群列表。
+   * @param panelId 面板 ID
+   * @param panel 面板配置内容
+   * @returns 本次修改后的面板版本号
+   */
+  updatePanel(panelId: string, panel: Panel): Promise<UpdatePanelResponse>;
+  /**
+   * 删除指令面板
+   *
+   * 删除后该面板不再对任何用户或群生效。
+   * @param panelId 面板 ID
+   */
+  deletePanel(panelId: string): Promise<{}>;
+  /**
+   * 修改指令面板关联对象
+   *
+   * c2c 场景操作 `user_openids`，group 场景操作 `group_openids`，一次最多 20 个；
+   * channel / dm 场景为全局配置，不支持此操作。
+   * @param panelId 面板 ID
+   * @param body 操作类型与关联对象列表
+   */
+  updatePanelTarget(panelId: string, body: UpdatePanelTargetRequest): Promise<{}>;
+}
+//#endregion
+//#region src/core/api/join-approval.d.ts
+/**
+ * 入群自动审批策略接口
+ *
+ * 策略把「关联群 + 白名单 QQ 号码」绑在一起，命中白名单的入群申请会自动审批通过。
+ * 规则仅在机器人拥有群管理员身份时才会实际运行；一个机器人最多 20 个策略。
+ */
+declare class JoinApprovalApi extends Http {
+  /**
+   * 查询入群自动审批策略列表
+   *
+   * 按创建时间倒序，支持分页。
+   * @param params 分页参数，`limit` 默认 20、最大 50（接口文档 v1.28.0 由 100 下调），
+   * 传入更大的值会被收敛到 50，避免平台直接拒绝
+   */
+  getStrategyList(params?: GetJoinApprovalStrategyListParams): Promise<GetJoinApprovalStrategyListResponse>;
+  /**
+   * 创建入群自动审批策略
+   *
+   * `group_openids` 与 `group_ids` 二选一必填，同时传入或均未传入都会报错。
+   * @param body 策略配置
+   */
+  createStrategy(body: CreateJoinApprovalStrategyRequest): Promise<CreateJoinApprovalStrategyResponse>;
+  /**
+   * 修改入群自动审批策略
+   *
+   * 可修改生效状态、失效时间、备注，或增删关联群；
+   * 增删关联群时的群标识形式必须与创建时一致。
+   * @param strategyId 策略 ID
+   * @param body 待修改的字段
+   */
+  updateStrategy(strategyId: string, body: UpdateJoinApprovalStrategyRequest): Promise<UpdateJoinApprovalStrategyResponse>;
+  /**
+   * 删除入群自动审批策略
+   * @param strategyId 策略 ID
+   */
+  deleteStrategy(strategyId: string): Promise<{}>;
+  /**
+   * 执行入群自动审批策略
+   *
+   * 对策略关联的全部群发起全量扫描，命中白名单号码的入群申请自动审批通过。
+   * 异步执行，约 10 分钟完成。
+   * @param strategyId 策略 ID
+   */
+  executeStrategy(strategyId: string): Promise<{}>;
+  /**
+   * 修改入群自动审批策略的白名单号码
+   *
+   * 单次最多 10000 个，策略号码上限 10W。
+   * @param strategyId 策略 ID
+   * @param body 操作类型与号码列表
+   */
+  updateWhitelistUsers(strategyId: string, body: UpdateWhitelistUsersRequest): Promise<UpdateWhitelistUsersResponse>;
+}
+//#endregion
+//#region src/core/api/index.d.ts
+/**
+ * QQBot 官方 API 门面
+ *
+ * 子模块按职能拆分：
+ * - messages：发送 / 撤回
+ * - media：富媒体上传
+ * - mediaImages：Markdown 素材图片管理
+ * - interaction：按钮回调 ack
+ * - meta：@me / dms / gateway / 分享链接
+ * - groups：群基础信息 / 机器人群内状态 / 群成员列表与详情 / 禁言 / 批量移除 / 群黑名单 / 入群申请（白名单接口）
+ * - guilds：频道与子频道的查询和增删改
+ * - menu：全局自定义菜单（仅单聊）
+ * - panels：指令面板
+ * - joinApproval：入群自动审批策略
+ * - request：裸请求入口，用于调用尚未封装的官方接口
+ *
+ * 请求体构造器 {@link buildQQMsg} / {@link buildGuildMsg} 独立导出，避免与 HTTP 调用耦合
+ */
+declare class QQBotApi {
+  readonly axios: AxiosInstance;
+  /**
+   * 裸请求入口，直接调用官方 OpenAPI。
+   *
+   * 官方新接口还没被适配器封装时可用它兜底，会自动带鉴权、解包 `data`、
+   * 格式化错误码：
+   *
+   * ```ts
+   * await bot.super.request.get('/v2/menu')
+   * await bot.super.request.post('/v2/xxx', { foo: 1 })
+   * ```
+   *
+   * @see {@link RequestApi}
+   */
+  readonly request: RequestApi;
+  readonly messages: MessagesApi;
+  readonly media: MediaApi;
+  readonly mediaImages: MediaImagesApi;
+  readonly interaction: InteractionApi;
+  readonly meta: MetaApi;
+  readonly groups: GroupsApi;
+  readonly guilds: GuildsApi;
+  readonly menu: MenuApi;
+  readonly panels: PanelsApi;
+  readonly joinApproval: JoinApprovalApi;
+  /** 请求体构造器（静态便利） */
+  readonly qq: {
+    text(content: string): SendQQTextMessageRequest;
+    markdown(markdown: Markdown, keyboard?: Keyboard): SendQQMarkdownMessageRequest;
+    ark(ark: SendQQArkMessageRequest["ark"]): SendQQArkMessageRequest;
+    media(fileInfo: string, keyboard?: Keyboard): 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);
+}
+//#endregion
+//#region src/types/config.d.ts
+/**
+ * 消息缓存存储分级。
+ *
+ * - minimal: 只存 ID 映射与引用关系（reply 段），撤回 / 引用解析可用，正文不落库；
+ * - standard: 额外保存文本、表情与媒体本地路径，markdown 原文不落库；
+ * - full: 全部可缓存消息段原样保存。
+ */
+type MessageCacheLevel = 'minimal' | 'standard' | 'full';
+/**
+ * 单个 QQBot 配置
+ */
+interface QQBotConfig {
+  /** 机器人 ID */
+  appId: string;
+  /** 机器人密钥 */
+  secret: string;
+  /** 开启 QQ 场景能力（单聊 / 群聊） */
+  qqEnable: boolean;
+  /** 开启频道场景能力 */
+  guildEnable: boolean;
+  /** 频道场景模式 0 公域 / 1 私域 */
+  guildMode: 0 | 1;
+  /** 收到消息后对文本进行表达式处理 */
+  regex: {
+    reg: string | RegExp;
+    rep: string;
+  }[];
+  /** 消息缓存配置 */
+  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;
+  messageSeq: number;
+  time: number;
+  contact: Contact;
+  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 是唯一数据层，没有内存镜像：
+ * - 写入热路径只入队，后台按批次事务落库，每条消息稳定 2~3 次语句
+ *   往返（prepared statement 复用）；
+ * - 所有读取直接查 SQLite（WAL + 整数 hash 索引，点查亚毫秒级）；
+ *   读取前先排空待写队列，保证"读到自己刚写的数据"。
+ */
+declare class MessageStore {
+  private db?;
+  private readonly ready;
+  private shouldVacuum;
+  private flushTimer?;
+  private flushActive?;
+  private mediaTimer?;
+  private mediaActive;
+  private pending;
+  private pendingMedia;
+  private readonly pendingMediaKeys;
+  private readonly statements;
+  private readonly contactRefCache;
+  private readonly senderRefCache;
+  /** 当前生效的缓存保留时长；由配置解析，多 bot 取最大值。 */
+  private ttlMs;
+  /** 当前生效的消息行数硬上限；由配置解析，多 bot 取最大值。 */
+  private maxRows;
+  constructor();
+  /**
+   * 立即执行一次过期消息和本地媒体缓存清理。
+   *
+   * 该方法交给 Karin `task` 调度调用；读写路径不再内嵌清理，避免尾延迟。
+   *
+   * @returns 清理完成 Promise。
+   */
+  cleanupExpired(): Promise<void>;
+  /**
+   * 保存实际消息。
+   *
+   * 只克隆快照并投递后台队列，不等待 SQLite，消息事件创建不会被
+   * 数据库写锁或小事务阻塞。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 已转换为 Karin elements 的消息缓存。
+   * @param options 引用索引与自己消息标记。
+   */
+  save(botId: string, message: CachedMessage, options?: SaveOptions): Promise<void>;
+  /**
+   * 保存 QQ 下发的引用上下文。
+   *
+   * 是否已有同 ID 缓存（原消息或引用索引）由后台 flush 在事务内判断并去重，
+   * 避免阻塞事件热路径。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 以 `ref_msg_idx` 作为 messageId 的引用上下文。
+   * @param level 存储分级；缺省按 standard 处理。
+   */
+  saveReferenceIfAbsent(botId: string, message: CachedMessage, level?: SaveOptions['level']): 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[]>;
+  /**
+   * 将 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;
+  /**
+   * 投递待落库消息。
+   *
+   * @param item 待写入 SQLite 的缓存任务。
+   */
+  private enqueue;
+  /**
+   * 安排一次后台批量落库。
+   *
+   * 已有 timer 或正在 flush 时不会重复安排。
+   */
+  private scheduleFlush;
+  /**
+   * 触发一次批量落库；已有进行中的 flush 时复用其 Promise。
+   *
+   * @returns 当前批次落库完成的 Promise。
+   */
+  private flushQueue;
+  /**
+   * 等待写入队列完全清空。
+   *
+   * 所有读取入口先经过它，保证"读到自己刚写的数据"；队列为空时零开销。
+   */
+  private flushAll;
+  /**
+   * 批量落库队列中的消息。
+   *
+   * 单次最多处理 `FLUSH_BATCH_SIZE` 条，并在一个事务内完成写入。
+   *
+   * @returns flush 完成 Promise。
+   */
+  private doFlushBatch;
+  /**
+   * 写入一条待落库消息。
+   *
+   * 稳定状态下（contact/sender 已缓存）每条消息 2 次语句往返：
+   * 定位既有行 + INSERT 或 UPDATE。
+   *
+   * @param item 待写入的消息任务。
+   */
+  private writeItem;
+  /**
+   * 清理待写队列中已经过期的消息。
+   */
+  private prunePending;
+  /**
+   * 投递媒体本地化任务。
+   *
+   * 原消息会先保留短期 URL 写入缓存；本地化成功后再覆盖同一条消息。队列会按
+   * message scoped key 去重，避免高频更新同一条消息时重复下载。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 可能包含远程媒体 URL 的消息快照。
+   * @param refIdx 该消息的引用索引，成功本地化后随消息一并回写。
+   * @param isSelf 是否机器人自己发送。
+   */
+  private enqueueMediaLocalize;
+  /**
+   * 安排媒体本地化队列处理。
+   *
+   * @returns 已存在定时器或队列为空时直接返回。
+   */
+  private scheduleMediaLocalize;
+  /**
+   * 按固定并发处理媒体本地化任务。
+   *
+   * @returns 队列为空或达到并发上限时返回。
+   */
+  private drainMediaLocalizeQueue;
+  /**
+   * 本地化单条消息中的远程媒体字段，并在成功后覆盖内存与 SQLite。
+   *
+   * @param item 待处理的媒体本地化任务。
+   * @returns 本地化与回写完成 Promise。
+   */
+  private localizeMediaItem;
+  /**
+   * 清理已经过期的媒体本地化待处理任务。
+   */
+  private prunePendingMedia;
+  /**
+   * 启动时扫描 SQLite 中尚未本地化的远程媒体消息，并重新投递队列补救。
+   *
+   * `has_remote_media` 是部分索引列，扫描不再需要 LIKE 全表匹配。
+   *
+   * @returns 扫描和投递完成 Promise。
+   */
+  private recoverRemoteMedia;
+  /**
+   * 按消息 ID 或引用索引查询消息行。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param messageId 真实消息 ID 或 `REFIDX` 引用索引。
+   * @param contact 可选会话范围。
+   * @returns 命中的消息行；未命中时返回 null。
+   */
+  private queryMessageRow;
+  /**
+   * 浅拷贝消息缓存，避免后续事件对象被插件侧修改后污染缓存。
+   *
+   * @param message 原始缓存消息。
+   * @returns 可安全放入缓存的消息副本。
+   */
+  private cloneMessage;
+  /**
+   * 将数据库行还原为 Karin `MessageResponse`。
+   *
+   * @param row 消息主查询结果。
+   * @returns Karin 标准消息查询结果。
+   */
+  private rowToResponse;
+  /**
+   * 从查询行还原 Karin Contact。
+   *
+   * @param row 消息主查询结果。
+   * @returns Karin Contact。
+   */
+  private contactFromRow;
+  /**
+   * 获取或创建会话映射 ID。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact Karin 会话对象。
+   * @returns `qqbot_contacts.id`。
+   */
+  private ensureContact;
+  /**
+   * 获取或创建发送者映射 ID。
+   *
+   * sender 按 (userId, nick, name, role) 去重；不再被引用的行由清理任务 GC，
+   * 不会随昵称变化永久膨胀。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param sender Karin sender 对象。
+   * @returns `qqbot_senders.id`。
+   */
+  private ensureSender;
+  /**
+   * 判断消息是否已经超过本地缓存 TTL。
+   *
+   * @param row 带 `time` 字段的消息对象。
+   * @returns true 表示已经超过一天缓存窗口。
+   */
+  private isExpired;
+  /**
+   * 清理过期缓存消息，并执行体积治理。
+   *
+   * 依次执行：配置刷新、TTL 删除、硬上限删除、上传缓存清理、
+   * sender GC（写空闲时）、增量 vacuum 归还空间、WAL checkpoint 截断、
+   * 媒体文件清理。
+   */
+  private cleanup;
+  /**
+   * 执行数据库版本迁移。
+   *
+   * 使用 SQLite `PRAGMA user_version` 记录已应用的 schema 版本。
+   *
+   * @returns 迁移完成 Promise。
+   */
+  private migrate;
+  /**
+   * 判断 SQLite 表是否存在。
+   *
+   * @param name 表名。
+   * @returns true 表示表存在。
+   */
+  private tableExists;
+  /**
+   * 读取 SQLite 表字段名。
+   *
+   * @param name 表名。
+   * @returns 字段名数组；表不存在时返回空数组。
+   */
+  private tableColumns;
+  /**
+   * 读取 SQLite schema 版本。
+   *
+   * @returns 当前 `PRAGMA user_version`；新库默认为 0。
+   */
+  private getUserVersion;
+  /**
+   * 在 `BEGIN IMMEDIATE` 事务中执行写操作。
+   *
+   * @param fn 事务内执行的异步函数。
+   */
+  private transaction;
+  /**
+   * 获取当前数据库连接。
+   *
+   * @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 runS;
+  /**
+   * 以 prepared statement 查询单行数据。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   * @returns 查询结果；未命中时返回 undefined。
+   */
+  private getS;
+  /**
+   * 以 prepared statement 查询多行数据。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   * @returns 查询结果数组。
+   */
+  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
+/**
+ * QQ Official Bot 适配器
+ *
+ * 发送通道由平台能力决定，没有对应的用户配置项：QQ 单聊 / 群聊的自定义 Markdown
+ * 已对所有机器人开放，固定走 msg_type=2；频道场景仍需内邀开通，先乐观尝试
+ * Markdown，被拒后自动降级为普通消息（详见 pipeline-qq / pipeline-guild 与
+ * guild-markdown）。视频 / 语音 / 文件由 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>;
+  /**
+   * 撤回消息
+   *
+   * 群聊中机器人被群主设为管理员后，也可撤回成员消息；平台仍限制消息发送后两分钟内。
+   * REFIDX 与 API 消息 ID 的映射、单聊"是否自己发送"的判定都直接查询
+   * SQLite 消息缓存（ID 映射行不受缓存开关影响，始终落库）。
+   */
+  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>;
+  /**
+   * 发送合并转发消息
+   *
+   * QQ 官方没有合并转发能力，这里把各节点摊平成一段 Markdown 正文，节点之间用
+   * 强制换行隔开，不添加任何前缀提示文本。
+   *
+   * 图片以 markdown 图片语法写入，**保留原始来源**（本地路径 / base64 / URL）：
+   * 究竟走内置图床、第三方 fileToUrl，还是降级成 msg_type=7 富媒体，由发送
+   * pipeline 统一决定。这里不自己上传，也不自己判断通道——否则频道场景在没有
+   * Markdown 权限时会绕过降级逻辑，直接被平台拒掉。
+   *
+   * 视频 / 语音 / 文件进不了 markdown，作为普通消息段跟随主消息一起交给 pipeline，
+   * 由它在同一次发送里以 msg_type=7 补发。
+   */
+  sendForwardMsg(contact: Contact, elements: Array<NodeElement>, _options?: ForwardOptions): Promise<{
+    messageId: string;
+    forwardId: string;
+  }>;
+  /**
+   * 获取头像 url
+   *
+   * 第三方头像 CDN 的模式是 `qqapp/{appId}/{openid}/{size}`，只有拼用户 openid 才有效；
+   * 机器人自身没有可用的 openid（selfId 就是 appId，拼出 appId/appid 只会得到默认头像），
+   * 因此目标是自己时改走官方 `GET /users/@me` 返回的 avatar 字段，取值与缓存见 self-avatar。
+   */
+  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>;
+  /**
+   * 群踢人
+   *
+   * 走官方 `POST /v2/groups/{group_openid}/batch_remove_members`，机器人需拥有群
+   * 管理员身份。Karin 的 `rejectAddRequest` 映射为官方的 `add_to_member_blacklist`：
+   * 移除的同时拉入群黑名单，该用户之后无法再次入群。官方接口没有踢人理由字段，
+   * `kickReason` 只会被记录到日志。
+   *
+   * 需要一次移除多人时用 `bot.super.groups.batchRemoveGroupMembers()`，单次最多 20 个。
+   *
+   * @param _groupId 群 openid
+   * @param _targetId 群成员 openid
+   * @param _rejectAddRequest 是否同时拉入群黑名单，默认 false
+   * @param _kickReason 官方不支持，仅在传入时输出提示
+   */
+  groupKickMember(_groupId: string, _targetId: string, _rejectAddRequest?: boolean, _kickReason?: string): Promise<void>;
+  /**
+   * 禁言群成员
+   *
+   * 机器人需拥有群管理员身份；平台限制最大禁言时长为 30 天，
+   * 超出部分会被截断到 30 天而不是直接失败。
+   *
+   * @param _groupId 群 openid
+   * @param _targetId 群成员 openid
+   * @param duration 禁言时长（秒），传 0 或负数表示解除禁言
+   */
+  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>>;
+  /**
+   * 获取群信息
+   *
+   * QQ 群走官方 `GET /v2/groups/{group_openid}/info`（白名单接口）；传入的是频道
+   * ID 时退回 `GET /guilds/{guild_id}`，这样频道场景下的插件调用也能拿到名称和
+   * 人数。两者都不可用（如白名单未开通返回 11253）时降级为空结构并告警。
+   *
+   * @param _groupId 群 openid 或频道 ID。
+   */
+  getGroupInfo(_groupId: string, _noCache?: boolean): Promise<GroupInfo>;
+  /**
+   * 获取群列表
+   *
+   * 官方没有 QQ 群列表接口。频道列表可用 `bot.super.guilds.getGuildList()` 获取，
+   * 但频道在 Karin 里属于 guild 场景，与 QQ 群不是同一类会话，因此不在此处混用。
+   */
+  getGroupList(_refresh?: boolean): Promise<Array<GroupInfo>>;
+  /**
+   * 获取群成员信息
+   *
+   * - 查询机器人自身（targetId 为 selfId）走官方 `GET /v2/groups/{group_openid}/bot_state`。
+   * - 查询其他成员走 `GET /v2/groups/{group_openid}/members/{member_openid}`，该接口在
+   *   接口文档 v1.28.0（2026-09-03）转为公开文档，昵称字段为 `username`，`nick` 是
+   *   转公开之前的字段名，仅作兼容回退。
+   *
+   * 两者都是白名单接口，未开通权限（11253）或查询失败时降级为占位结构并告警。
+   */
+  getGroupMemberInfo(_groupId: string, _targetId: string, _refresh?: boolean): Promise<GroupMemberInfo>;
+  /**
+   * 获取群成员列表
+   *
+   * 走官方 `GET /v2/groups/{group_openid}/members`（白名单接口），每页最多 30 条，
+   * 这里按 `next_cursor` 自动翻完所有页；顺便把昵称写入
+   * {@link AdapterQQBot.nicknameCache}，让后续消息事件能直接取到昵称。
+   *
+   * 为防止平台返回的游标不收敛，翻页数有安全上限（约 6000 人），触顶会告警并返回已取到的部分。
+   * 未开通权限（11253）或查询失败时返回已取到的部分并告警。
+   *
+   * @param _groupId 群 openid
+   */
+  getGroupMemberList(_groupId: string, _refresh?: boolean): Promise<Array<GroupMemberInfo>>;
+  /**
+   * 获取群荣誉信息
+   */
+  getGroupHonor(_groupId: string): Promise<Array<QQGroupHonorInfo>>;
+  /**
+   * 设置好友请求结果
+   */
+  setFriendApplyResult(_requestId: string, _isApprove: boolean, _remark?: string): Promise<void>;
+  /**
+   * 审批入群申请。
+   *
+   * 走官方 `POST /v2/groups/{group_openid}/approval_join_request/{member_openid}`，
+   * 机器人需拥有群管理员身份。Karin 只透传 flag（`join_request_id`），群与申请人
+   * openid 由 `join-request-cache` 在收到申请事件时记录，因此仅支持审批本次运行
+   * 期间收到过的申请；历史申请请改用
+   * `bot.super.groups.getJoinRequestList()` + `bot.super.groups.approvalJoinRequest()`。
+   *
+   * @param requestId 申请 ID（Karin 请求事件的 flag）。
+   * @param isApprove 是否通过。
+   * @param denyReason 拒绝理由，仅拒绝时生效。
+   */
+  setGroupApplyResult(requestId: string, isApprove: boolean, denyReason?: string): Promise<void>;
+  /**
+   * 设置邀请加入群请求结果。
+   *
+   * 机器人被邀请入群与用户主动申请入群在官方侧是同一条 `GROUP_JOIN_REQUEST`
+   * 事件，审批走同一个接口，因此直接复用 {@link AdapterQQBot.setGroupApplyResult}。
+   *
+   * @param requestId 申请 ID（Karin 请求事件的 flag）。
+   * @param isApprove 是否通过。
+   */
+  setInvitedJoinGroupResult(requestId: string, isApprove: boolean): Promise<void>;
+  /**
+   * 设置消息表情回应
+   */
+  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>;
+  /**
+   * 下载文件到协议端本地
+   */
+  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>;
+  /**
+   * 上传群文件
+   *
+   * 实现同 {@link uploadFile}：官方无群文件系统，走 files 接口由服务端直发文件消息。
+   */
+  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>;
+  /**
+   * 获取群被禁言用户列表
+   *
+   * 走官方 `GET /v2/groups/{group_openid}/restrict_chat_setting`，只返回仍在
+   * 禁言中的成员（不含已过期）。机器人需拥有群管理员身份，无权限或查询失败时
+   * 降级为空数组并告警。
+   *
+   * `muteTime` 为禁言到期时间的 Unix 秒，而非剩余时长；全员禁言规则不在该返回
+   * 结构内，需要时请用 `bot.super.groups.getGroupMuteSetting()` 读取 `global_rule`。
+   *
+   * @param _groupId 群 openid
+   */
+  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 { Scene as i, QQBotApi as n, MediaType as r, AdapterQQBot as t };