@karinjs/adapter-qqbot 2.0.0 → 2.2.1

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import { AdapterBase, AdapterType, Contact, CreateGroupFolderResponse, DownloadFileOptions, DownloadFileResponse, ElementTypes, ForwardOptions, GetAiCharactersResponse, GetAtAllCountResponse, GetGroupFileListResponse, GetGroupFileSystemInfoResponse, GetGroupHighlightsResponse, GetGroupMuteListResponse, GetRkeyResponse, GroupInfo, GroupMemberInfo, LogMethodNames, Message, MessageResponse, NodeElement, QQGroupHonorInfo, SendMsgResults, UserInfo, karinToQQBot } from "node-karin";
+import { AdapterBase, AdapterType, Contact, CreateGroupFolderResponse, DownloadFileOptions, DownloadFileResponse, ElementTypes, ForwardOptions, GetAiCharactersResponse, GetAtAllCountResponse, GetGroupFileListResponse, GetGroupFileSystemInfoResponse, GetGroupHighlightsResponse, GetGroupMuteListResponse, GetRkeyResponse, GroupInfo, GroupMemberInfo, LogMethodNames, Message, MessageResponse, NodeElement, QQGroupHonorInfo, SendMsgResults, Sender, UserInfo, karinToQQBot } from "node-karin";
 import FormData from "form-data";
-import * as _$node_karin_axios0 from "node-karin/axios";
 
 //#region src/core/api/types.d.ts
 /** 上传富媒体文件场景 */
@@ -87,8 +86,6 @@ interface SendQQMediaMessageRequest extends SendQQMessageRequest, QQMessageID {
   media: {
     /** 文件信息，用于发消息接口的 media 字段使用 */file_info: string;
   };
-  /** 当 msg_type = 7 时，content 字段需要填入一个值，譬如一个空格 “ ”，后续版本会修复该问题。 */
-  content: string;
 }
 /** 发送QQ消息请求参数 */
 type SendQQMsg = SendQQTextMessageRequest | SendQQMarkdownMessageRequest | SendQQArkMessageRequest | SendQQMediaMessageRequest;
@@ -215,7 +212,11 @@ interface SendQQMsgResponse {
   /** 消息唯一 ID */
   id: string;
   /** 发送时间 */
-  timestamp: number;
+  timestamp: number | string;
+  /** 扩展信息；部分 QQ 消息发送响应会返回可用于 message_reference 的 REFIDX。 */
+  ext_info?: {
+    /** 当前发送消息可被引用时使用的索引。 */ref_idx?: string;
+  };
 }
 /** 发送频道消息后响应 */
 interface SendGuildResponse {
@@ -240,7 +241,7 @@ interface UploadMediaResponse {
 /**
  * 创建 axios 实例，自动从 tokens map 取最新 access_token
  */
-declare const createAxiosInstance: (baseURL: string, appId: string) => _$node_karin_axios0.AxiosInstance;
+declare const createAxiosInstance: (baseURL: string, appId: string) => import("node-karin/axios").AxiosInstance;
 //#endregion
 //#region src/core/api/http.d.ts
 type AxiosInstance = ReturnType<typeof createAxiosInstance>;
@@ -251,8 +252,8 @@ 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 post<T>(path: string, body?: unknown, headers?: Record<string, string>, timeout?: number): Promise<T>;
+  protected put<T>(path: string, body?: unknown, headers?: Record<string, string>, timeout?: number): Promise<T>;
   protected delete<T>(path: string): Promise<T>;
 }
 //#endregion
@@ -292,10 +293,69 @@ declare class MediaApi extends Http {
    * @param scene user(单聊) / group(群聊)
    * @param peer openid 或 group_openid
    * @param type 文件类型
-   * @param source 必须是 http url 或 base64 字符串
+   * @param source http url、本地路径或 base64 字符串
    * @param srvSendMsg 上传后是否由服务端直接发送
+   * @param fileName 文件消息的展示文件名
+   */
+  upload(scene: Scene, peer: string, type: MediaType, source: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
+  /**
+   * 上传没有公网 URL 处理器可用时的 fallback 富媒体资源。
+   *
+   * 较大的 fallback 资源会优先使用 QQ 分片上传，提高直接发送成功率。
+   * `srvSendMsg` 为 true 时保留普通上传路径，避免分片完成接口与服务端直接发送语义冲突。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param type 文件类型
+   * @param source 本地路径、http url、data URL、base64:// 或裸 base64
+   * @param srvSendMsg 上传后是否由服务端直接发送
+   * @param fileName 文件消息的展示文件名
+   * @returns 上传结果，包含后续发送消息所需的 file_info
+   */
+  uploadFallback(scene: Scene, peer: string, type: MediaType, source: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
+  /**
+   * 确认单个分片已完成上传。
+   *
+   * QQ 有时会在分片刚 PUT 完时短暂返回 40093001，此时需要在服务端给出的
+   * retry_timeout 窗口内持续重试，而不是直接判定整个大文件上传失败。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param body upload_part_finish 请求体
+   * @param retryTimeout 服务端返回的持续重试秒数
+   */
+  private finishUploadPart;
+  /**
+   * 持续重试 upload_part_finish 的短暂服务端状态。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param body upload_part_finish 请求体
+   * @param retryTimeout 服务端返回的持续重试秒数
+   */
+  private retryUploadPartFinish;
+  /**
+   * 完成 QQ 分片上传，并对短暂失败做有限重试。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param uploadId upload_prepare 返回的上传任务 ID
+   * @returns 上传结果
    */
-  upload(scene: Scene, peer: string, type: MediaType, source: string, srvSendMsg?: boolean): Promise<UploadMediaResponse>;
+  private completeChunkedUpload;
+  /**
+   * 使用 QQ 官方分片协议上传 fallback 大资源。
+   *
+   * 流程为：准备上传 -> PUT 每个分片 -> 确认每个分片 -> 完成上传。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid
+   * @param type 文件类型
+   * @param source 已归一化的 fallback 来源
+   * @param preparedHashes 预计算的文件 hash
+   * @returns 上传结果，包含后续发送消息所需的 file_info
+   */
+  private uploadChunked;
 }
 //#endregion
 //#region src/core/api/interaction.d.ts
@@ -362,7 +422,416 @@ declare class QQBotApi {
   constructor(axios: AxiosInstance);
 }
 //#endregion
+//#region src/core/storage/message-store/types.d.ts
+interface CachedMessage {
+  messageId: string;
+  messageSeq: number;
+  time: number;
+  contact: Contact;
+  sender: Sender;
+  elements: ElementTypes[];
+}
+//#endregion
+//#region src/core/storage/message-store/store.d.ts
+/**
+ * QQBot 收到的消息缓存。
+ *
+ * 热路径只写内存并入队，不等待 SQLite：
+ * - `getMsg` 优先查内存，插件在同一事件回调内可立即命中；
+ * - SQLite 在后台按批次事务落库，避免一条消息一个事务拖慢事件分发；
+ * - 元素表只保存 `type + value`，避免宽表 NULL 和多详情表多次 INSERT。
+ */
+declare class MessageStore {
+  private db?;
+  private readonly ready;
+  private lastCleanup;
+  private shouldVacuum;
+  private flushTimer?;
+  private flushing;
+  private mediaTimer?;
+  private mediaActive;
+  private readonly pending;
+  private readonly pendingMedia;
+  private readonly pendingMediaKeys;
+  private readonly memory;
+  private readonly directIndex;
+  private readonly aliasIndex;
+  private readonly scopedAliasIndex;
+  private readonly botRefCache;
+  private readonly contactRefCache;
+  private readonly senderRefCache;
+  constructor();
+  /**
+   * 立即执行一次过期消息和本地媒体缓存清理。
+   *
+   * 该方法交给 Karin `task` 调度调用；类内部只保留清理能力，不自行维护常驻定时器。
+   *
+   * @returns 清理完成 Promise。
+   */
+  cleanupExpired(): Promise<void>;
+  /**
+   * 保存实际消息，并为 QQ 的 `msg_idx` 等引用索引建立轻量映射。
+   *
+   * 该方法只同步写入内存并投递后台队列，不等待 SQLite。这样消息事件创建不会被
+   * 数据库写锁或小事务阻塞。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 已转换为 Karin elements 的消息缓存。
+   * @param aliases 可查询到该消息的额外消息索引，例如 QQ `msg_idx`。
+   */
+  save(botId: string, message: CachedMessage, aliases?: string[]): Promise<void>;
+  /**
+   * 仅当内存中没有该引用索引时保存 QQ 下发的引用上下文。
+   * 数据库是否已存在由后台 flush 再判断，避免阻塞事件热路径。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 以 `ref_msg_idx` 作为 messageId 的引用上下文。
+   */
+  saveReferenceIfAbsent(botId: string, message: CachedMessage): Promise<void>;
+  /**
+   * 读取缓存消息。
+   *
+   * OneBot v11 标准调用只传 messageId；contact 参数仅用于额外限定范围。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param messageId 真实消息 ID 或 QQ `REFIDX` 引用索引。
+   * @param contact 可选会话范围，传入后只在该会话下查询。
+   * @returns 命中的消息缓存；未命中或已过期时返回 null。
+   */
+  get(botId: string, messageId: string, contact?: Contact): Promise<MessageResponse | null>;
+  /**
+   * 按起始消息 ID 读取同一会话内的历史缓存消息。
+   *
+   * QQ 官方 Bot 没有 seq 历史查询能力；这里以本地缓存中命中的起始消息为锚点，
+   * 按时间倒序返回最近的 `count` 条消息，包含起始消息本身。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact 查询限定的会话。
+   * @param startMsgId 起始消息 ID 或 QQ `REFIDX` 引用索引。
+   * @param count 获取消息数量。
+   * @returns 命中的历史消息数组；未命中或已过期时返回空数组。
+   */
+  getHistory(botId: string, contact: Contact, startMsgId: string, count: number): Promise<MessageResponse[]>;
+  /**
+   * 初始化 SQLite 连接、表结构，并执行启动清理和媒体本地化补救。
+   *
+   * @returns 初始化完成 Promise。
+   */
+  private initialize;
+  /**
+   * 投递待落库消息。
+   *
+   * @param item 待写入 SQLite 的缓存任务。
+   */
+  private enqueue;
+  /**
+   * 安排一次后台批量落库。
+   *
+   * 已有 timer 或正在 flush 时不会重复安排。
+   */
+  private scheduleFlush;
+  /**
+   * 批量落库队列中的消息。
+   *
+   * 单次最多处理 `FLUSH_BATCH_SIZE` 条，并在一个事务内完成写入。
+   *
+   * @returns flush 完成 Promise。
+   */
+  private flushQueue;
+  /**
+   * 写入一条待落库消息。
+   *
+   * @param item 待写入的消息、alias 和引用上下文标记。
+   */
+  private writeItem;
+  /**
+   * 清理待写队列中已经过期的消息。
+   */
+  private prunePending;
+  /**
+   * 投递媒体本地化任务。
+   *
+   * 原消息会先保留短期 URL 写入缓存；本地化成功后再覆盖同一条消息。队列会按
+   * message scoped key 去重，避免高频更新同一条消息时重复下载。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 可能包含远程媒体 URL 的消息快照。
+   * @param aliases 该消息可被查询到的额外 alias。
+   */
+  private enqueueMediaLocalize;
+  /**
+   * 安排媒体本地化队列处理。
+   *
+   * @returns 已存在定时器或队列为空时直接返回。
+   */
+  private scheduleMediaLocalize;
+  /**
+   * 按固定并发处理媒体本地化任务。
+   *
+   * @returns 队列为空或达到并发上限时返回。
+   */
+  private drainMediaLocalizeQueue;
+  /**
+   * 本地化单条消息中的远程媒体字段，并在成功后覆盖内存与 SQLite。
+   *
+   * @param item 待处理的媒体本地化任务。
+   * @returns 本地化与回写完成 Promise。
+   */
+  private localizeMediaItem;
+  /**
+   * 清理已经过期的媒体本地化待处理任务。
+   *
+   * @returns 无返回值；会同步维护 pendingMediaKeys。
+   */
+  private prunePendingMedia;
+  /**
+   * 启动时扫描 SQLite 中尚未本地化的远程媒体 URL，并重新投递队列补救。
+   *
+   * @returns 扫描和投递完成 Promise。
+   */
+  private recoverRemoteMedia;
+  /**
+   * 写入内存热缓存。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param message 消息缓存。
+   * @param aliases 可查询到该消息的额外消息索引。
+   */
+  private putMemory;
+  /**
+   * 从内存热缓存读取消息。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param messageId 真实消息 ID 或 alias。
+   * @param contact 可选会话范围。
+   * @returns 命中的缓存消息；未命中或过期时返回 null。
+   */
+  private getFromMemory;
+  /**
+   * 到达清理间隔时清理内存缓存。
+   */
+  private cleanupMemoryIfDue;
+  /**
+   * 清理一天前的内存消息，并同步清理失效索引。
+   */
+  private cleanupMemory;
+  /**
+   * 清理指向已删除内存消息的索引。
+   *
+   * @param index 需要清理的索引 Map。
+   */
+  private cleanIndex;
+  /**
+   * 浅拷贝消息缓存，避免后续事件对象被插件侧修改后污染缓存。
+   *
+   * @param message 原始缓存消息。
+   * @returns 可安全放入缓存的消息副本。
+   */
+  private cloneMessage;
+  /**
+   * 将内存缓存转换为 Karin `MessageResponse`。
+   *
+   * @param message 内存缓存消息。
+   * @returns Karin 标准消息查询结果。
+   */
+  private toResponse;
+  /**
+   * 执行数据库版本迁移。
+   *
+   * 使用 SQLite `PRAGMA user_version` 记录已应用的 schema 版本。
+   * 版本 0 只表示“未初始化或开发期旧库”，首个 alpha 发布基线为 v1。
+   *
+   * @returns 迁移完成 Promise。
+   */
+  private migrate;
+  /**
+   * 获取或创建 bot 映射 ID。
+   *
+   * @param botId 当前 QQBot appId。
+   * @returns `qqbot_bots.id`。
+   */
+  private ensureBot;
+  /**
+   * 获取或创建会话映射 ID。
+   *
+   * @param botRef `qqbot_bots.id`。
+   * @param contact Karin 会话对象。
+   * @returns `qqbot_contacts.id`。
+   */
+  private ensureContact;
+  /**
+   * 获取或创建发送者映射 ID。
+   *
+   * @param botRef `qqbot_bots.id`。
+   * @param sender Karin sender 对象。
+   * @returns `qqbot_senders.id`。
+   */
+  private ensureSender;
+  /**
+   * 获取或创建消息主记录。
+   *
+   * @param botRef `qqbot_bots.id`。
+   * @param contactRef `qqbot_contacts.id`。
+   * @param senderRef `qqbot_senders.id`。
+   * @param message 消息缓存。
+   * @returns `qqbot_messages.id`。
+   */
+  private ensureMessage;
+  /**
+   * 从查询行还原 Karin Contact。
+   *
+   * @param row 消息主查询结果。
+   * @returns Karin Contact。
+   */
+  private contactFromRow;
+  /**
+   * 将数据库行还原为 Karin `MessageResponse`。
+   *
+   * @param row 消息主查询结果。
+   * @returns Karin 标准消息查询结果。
+   */
+  private rowToResponse;
+  /**
+   * 在指定会话中解析消息 ID 或 alias 到消息主表行。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact Karin 会话对象。
+   * @param messageId 真实消息 ID 或 alias。
+   * @returns 命中的消息行；未命中时返回 null。
+   */
+  private resolveMessageRow;
+  /**
+   * 构造会话级查询键。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact Karin 会话对象。
+   * @param messageId 消息 ID 或 alias。
+   * @returns 用于 SQL 参数或内存 key 的字段数组。
+   */
+  private contactKey;
+  /**
+   * 构造内存会话级 key。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact Karin 会话对象。
+   * @param messageId 消息 ID 或 alias。
+   * @returns 内存 Map 使用的稳定 key。
+   */
+  private scopedKey;
+  /**
+   * 构造内存全局 key。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param messageId 消息 ID 或 alias。
+   * @returns 不限定会话时使用的内存 key。
+   */
+  private globalKey;
+  /**
+   * 删除指定会话下的 alias。
+   *
+   * @param botId 当前 QQBot appId。
+   * @param contact Karin 会话对象。
+   * @param messageId 需要删除的 alias ID。
+   */
+  private deleteAlias;
+  /**
+   * 判断某条消息是否包含指向指定 ID 的 reply 段。
+   *
+   * @param messageRef `qqbot_messages.id`。
+   * @param replyId 被引用的消息 ID。
+   * @returns true 表示该消息包含对应 reply 段。
+   */
+  private hasReplyTo;
+  /**
+   * 判断消息是否已经超过本地缓存 TTL。
+   *
+   * @param row 带 `time` 字段的消息对象。
+   * @returns true 表示已经超过一天缓存窗口。
+   */
+  private isExpired;
+  /**
+   * 到达清理间隔时清理内存和 SQLite 过期消息。
+   */
+  private cleanupIfDue;
+  /**
+   * 清理一天前的缓存消息。
+   *
+   * SQLite 只删除主消息表，消息段和 alias 通过外键级联删除。
+   */
+  private cleanup;
+  /**
+   * 判断 SQLite 表是否存在。
+   *
+   * @param name 表名。
+   * @returns true 表示表存在。
+   */
+  private tableExists;
+  /**
+   * 读取 SQLite 表字段名。
+   *
+   * @param name 表名。
+   * @returns 字段名数组；表不存在时返回空数组。
+   */
+  private tableColumns;
+  /**
+   * 读取 SQLite schema 版本。
+   *
+   * @returns 当前 `PRAGMA user_version`；新库默认为 0。
+   */
+  private getUserVersion;
+  /**
+   * 写入 SQLite schema 版本。
+   *
+   * @param version 已成功应用的数据库版本号。
+   */
+  private setUserVersion;
+  /**
+   * 在 `BEGIN IMMEDIATE` 事务中执行写操作。
+   *
+   * @param fn 事务内执行的异步函数。
+   */
+  private transaction;
+  /**
+   * 执行不返回行的 SQL。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   */
+  private run;
+  /**
+   * 查询单行数据。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   * @returns 查询结果；未命中时返回 undefined。
+   */
+  private getRow;
+  /**
+   * 查询多行数据。
+   *
+   * @param sql SQL 字符串。
+   * @param params SQL 参数。
+   * @returns 查询结果数组。
+   */
+  private getRows;
+}
+//#endregion
 //#region src/types/config.d.ts
+/**
+ * 自定义连接代理配置
+ */
+interface QQBotProxyConfig {
+  /** 正式环境 API */
+  prodApi: string;
+  /** 测试环境 API */
+  sandboxApi: string;
+  /** 调用凭证 API */
+  tokenApi: string;
+  /** 正式环境 WebSocket 网关 */
+  prodWs: string;
+  /** 测试环境 WebSocket 网关 */
+  sandboxWs: string;
+}
 /**
  * 单个 QQBot 配置
  */
@@ -373,12 +842,8 @@ interface QQBotConfig {
   appId: string;
   /** 机器人密钥 */
   secret: string;
-  /** 正式环境 API */
-  prodApi: string;
-  /** 测试环境 API */
-  sandboxApi: string;
-  /** 调用凭证 API */
-  tokenApi: string;
+  /** 自定义连接代理 */
+  proxy: QQBotProxyConfig;
   /** 开启沙盒环境 */
   sandbox: boolean;
   /** 开启 QQ 场景能力（单聊 / 群聊） */
@@ -396,6 +861,15 @@ interface QQBotConfig {
   keyboard: {
     /** 是否将文本中的 URL 自动转换为 keyboard 按钮 */enable: boolean;
   };
+  /** Markdown 通道 */
+  markdown: {
+    /** 是否启用 Markdown 通道发送消息 */enable: boolean;
+  };
+  /** 消息缓存配置 */
+  messageCache: {
+    /** 是否启用数据库消息缓存，用于 bot.getMsg */enable: boolean; /** 是否缓存机器人自己发送的消息 */
+    self: boolean;
+  };
   /** 事件接收配置 */
   event: {
     /** 接收方式 0 关闭 / 1 webhook / 2 ws */type: 0 | 1 | 2;
@@ -412,11 +886,13 @@ interface QQBotConfig {
 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);
+  /** 当前 bot 配置。真实配置存放在 WeakMap，避免被系统接口序列化整个适配器时带出。 */
+  get cfg(): QQBotConfig;
+  /** 接收消息的一天热缓存 + SQLite 缓存，用于实现 Karin 标准 `getMsg`。 */
+  get messageStore(): MessageStore;
   logger(level: LogMethodNames, ...args: any[]): void;
   /**
    * 主消息回复入口（karin 调用）
@@ -428,6 +904,8 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   sendMsg(contact: Contact, elements: Array<ElementTypes>, _retryCount?: number): Promise<SendMsgResults>;
   /**
    * 撤回消息
+   *
+   * 群聊中机器人被群主设为管理员后，也可撤回成员消息；平台仍限制消息发送后两分钟内。
    */
   recallMsg(contact: Contact, messageId: string): Promise<void>;
   /**
@@ -461,17 +939,25 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
    */
   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(_contact: Contact | string, _messageId?: string): Promise<MessageResponse>;
+  getMsg(input: Contact | string, messageId?: string): Promise<MessageResponse>;
   /**
-   * 获取历史消息（通过消息 ID）
+   * 获取本地缓存历史消息（仅支持 message_id）
    */
-  getHistoryMsg(_contact: Contact, _startMsgId: string, _count: number): Promise<Array<MessageResponse>>;
+  getHistoryMsg(contact: Contact, startMsgId: string, count: number): Promise<Array<MessageResponse>>;
   /**
-   * 获取历史消息（通过消息序列号）
+   * 获取本地缓存历史消息（message_seq 暂不支持）
    */
-  getHistoryMsg(_contact: Contact, _startMsgSeq: number, _count: number): Promise<Array<MessageResponse>>;
+  getHistoryMsg(contact: Contact, startMsgSeq: number, count: number): Promise<Array<MessageResponse>>;
   /**
    * 获取合并转发消息
    */
@@ -667,4 +1153,4 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   }>;
 }
 //#endregion
-export { type AdapterQQBot };
+export type { AdapterQQBot };