@karinjs/adapter-qqbot 2.2.1 → 3.0.0

package/dist/message-BTGL3TSn.js

@@ -0,0 +1,1843 @@
+import { m as log, n as config, p as pluginDirName } from "./config-BUuU6FnQ.js";
+import { karinPathBase, karinPathTemp } from "node-karin";
+import { createWriteStream } from "node:fs";
+import axios from "node-karin/axios";
+import crypto from "node:crypto";
+import { mkdir, readdir, rename, rm, stat, utimes } from "node:fs/promises";
+import { dirname, extname, join, sep } from "node:path";
+import sqlite3 from "node-karin/sqlite3";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { imageSizeFromFile } from "image-size/fromFile";
+
+//#region src/core/storage/message-store/constants.ts
+/** 默认缓存保留时长；实际值由 messageCache.ttlHours 配置，多 bot 取最大值。 */
+const MESSAGE_TTL = 1440 * 60 * 1e3;
+/**
+* 待落库队列上限；超过后丢弃最旧的待写缓存，避免反向拖垮消息事件。
+* 队列每项都持有完整消息克隆，上限同时也是内存保护。
+*/
+const MAX_WRITE_QUEUE = 1e4;
+/** 媒体本地化待处理队列上限；超过后丢弃最旧任务，原消息仍保留短期 URL。 */
+const MAX_MEDIA_LOCALIZE_QUEUE = 2e3;
+/**
+* 启动时最多补救的远程媒体消息数。
+* 与 MAX_MEDIA_LOCALIZE_QUEUE 对齐：查询走 has_remote_media 部分索引且不阻塞
+* 初始化，多查无成本；但超出队列上限的任务会被丢弃，取更大值没有意义。
+*/
+const MEDIA_RECOVERY_LIMIT = MAX_MEDIA_LOCALIZE_QUEUE;
+/**
+* 消息主表默认硬上限；实际值由 messageCache.maxRows 配置，多 bot 取最大值。
+* TTL 只能约束时间维度，硬上限保证刷屏场景下磁盘占用可预期。
+*/
+const MAX_MESSAGE_ROWS = 2e5;
+/** 单个 text/markdown 消息段最大缓存字符数，超出部分截断。 */
+const ELEMENT_TEXT_LIMIT = 4096;
+/** file_info 上传缓存最大行数，超出后删除最旧。 */
+const UPLOAD_CACHE_MAX_ROWS = 2e3;
+
+//#endregion
+//#region src/core/storage/message-store/media.ts
+/** 消息媒体缓存根目录：${karinPathTemp}/${pluginDirName}/message-media。 */
+const MEDIA_CACHE_DIR = join(karinPathTemp, pluginDirName, "message-media");
+/** 单个媒体下载请求的超时时间。 */
+const FETCH_TIMEOUT = 300 * 1e3;
+/** 各类型允许缓存的最大体积，防止短期 URL 下载拖垮磁盘或内存。 */
+const MAX_CACHE_BYTES = {
+	image: 30 * 1024 * 1024,
+	video: 100 * 1024 * 1024,
+	record: 20 * 1024 * 1024,
+	file: 100 * 1024 * 1024
+};
+/** 无法从消息段或响应头判断格式时使用的兜底扩展名。 */
+const EXTENSIONS_BY_TYPE = {
+	image: ".jpg",
+	video: ".mp4",
+	record: ".mp3",
+	file: ".bin"
+};
+/** 数据库中相对媒体路径的标记前缀。 */
+const STORED_PATH_SCHEME = "media://";
+/** 图片 subType 到扩展名的映射，优先级高于 URL 后缀。 */
+const SUBTYPE_EXTENSIONS = {
+	jpg: ".jpg",
+	jpeg: ".jpg",
+	png: ".png",
+	gif: ".gif",
+	webp: ".webp",
+	bmp: ".bmp",
+	mp4: ".mp4",
+	silk: ".silk",
+	amr: ".amr",
+	wav: ".wav",
+	mp3: ".mp3"
+};
+/**
+* 判断 elements 中是否存在需要本地化缓存的远程 file 字段。
+*
+* @param elements Karin 消息段数组。
+* @returns true 表示至少有一个 image/video/record/file 使用远程 URL。
+*/
+const hasRemoteFileElement = (elements) => {
+	return elements.some((element) => isFileBackedElement(element) && isRemoteUrl(element.file));
+};
+/**
+* 将接收侧短期媒体 URL 缓存到本地 temp 目录。
+*
+* Karin 的 image/video/record/file 段都通过 `file` 字段承载资源。这里优先保存
+* 本地路径，避免每条入站媒体都转存到图床；失败时保留原 URL，让缓存尽量完整。
+*
+* @param elements 原始 Karin 消息段数组。
+* @returns 本地化后的消息段、是否变化、以及单段失败信息。
+*/
+const localizeFileElements = async (elements) => {
+	let changed = false;
+	const failures = [];
+	const localized = [];
+	for (const element of elements) {
+		if (!isFileBackedElement(element) || !isRemoteUrl(element.file)) {
+			localized.push({ ...element });
+			continue;
+		}
+		try {
+			const cached = await cacheFileElement(element);
+			changed ||= cached.file !== element.file;
+			localized.push(cached);
+		} catch (err) {
+			failures.push(err instanceof Error ? err.message : String(err));
+			localized.push({ ...element });
+		}
+	}
+	return {
+		elements: localized,
+		changed,
+		failures
+	};
+};
+/**
+* 清理超过消息缓存 TTL 的本地媒体文件。
+*
+* @param ttlMs 保留时长；缺省使用默认 TTL。
+* @returns 清理完成 Promise。
+*/
+const cleanupMessageMediaCache = async (ttlMs = MESSAGE_TTL) => {
+	const deadline = Date.now() - ttlMs;
+	await cleanupDir(MEDIA_CACHE_DIR, deadline);
+};
+/**
+* 将本地媒体缓存绝对路径转换为数据库存储形态。
+*
+* 缓存目录下的文件存为 `media://<相对路径>`：一是省掉每条媒体消息重复的
+* 目录前缀（几十字节），二是换机器或缓存目录变更后路径仍可解析。
+*
+* @param file 消息段 file 字段。
+* @returns 缓存目录内的文件返回相对形态，其余原样返回。
+*/
+const toStoredFilePath = (file) => {
+	const prefix = MEDIA_CACHE_DIR + sep;
+	if (!file.startsWith(prefix)) return file;
+	return STORED_PATH_SCHEME + file.slice(prefix.length).split(sep).join("/");
+};
+/**
+* 将数据库存储形态还原为本地绝对路径。
+*
+* @param value `qqbot_messages.elements` 中的 file 字段值。
+* @returns `media://` 形态还原为绝对路径，其余原样返回。
+*/
+const fromStoredFilePath = (value) => {
+	if (!value.startsWith(STORED_PATH_SCHEME)) return value;
+	const relative = value.slice(8);
+	return join(MEDIA_CACHE_DIR, ...relative.split("/"));
+};
+/**
+* 缓存单个媒体消息段的远程文件。
+*
+* 图片会在下载后补充 subType、width、height；其他类型只替换 file 为本地路径。
+*
+* @param element 需要本地化的 image/video/record/file 消息段。
+* @returns 替换 file 字段后的消息段。
+*/
+const cacheFileElement = async (element) => {
+	const source = normalizeRemoteUrl(element.file);
+	const dir = join(MEDIA_CACHE_DIR, element.type);
+	await mkdir(dir, { recursive: true });
+	/**
+	* 文件名由 URL hash 决定：同一 URL 出现在多条消息或重复本地化时，
+	* 只会落盘一份，且已存在时直接跳过下载。
+	*/
+	const filename = getLocalFilename(element, source);
+	const finalFile = join(dir, filename);
+	if (await stat(finalFile).then((info) => info.isFile()).catch(() => false)) {
+		const now = /* @__PURE__ */ new Date();
+		await utimes(finalFile, now, now).catch(() => void 0);
+	} else await downloadRemoteFile({
+		url: source,
+		dir,
+		finalFile,
+		element,
+		maxBytes: MAX_CACHE_BYTES[element.type]
+	});
+	const result = {
+		...element,
+		file: finalFile
+	};
+	if (element.type === "image") {
+		const dimensions = await imageSizeFromFile(finalFile).catch(() => void 0);
+		return {
+			...result,
+			subType: extensionToSubType(extname(filename)) || element.subType,
+			width: dimensions?.width || element.width,
+			height: dimensions?.height || element.height
+		};
+	}
+	return result;
+};
+/**
+* 使用 node-karin/axios 以流方式下载远程媒体到本地文件。
+*
+* 先写入 `.part` 临时文件，完整下载后再 rename，避免半文件被后续读取。
+*
+* @param params 下载参数。
+* @param params.url 规范化后的远程 URL。
+* @param params.dir 当前媒体类型的缓存目录。
+* @param params.finalFile 下载完成后的目标绝对路径。
+* @param params.element 原始媒体消息段，用于响应类型校验。
+* @param params.maxBytes 当前类型允许的最大下载体积。
+* @returns 下载完成 Promise。
+*/
+const downloadRemoteFile = async (params) => {
+	const { url, dir, finalFile, element, maxBytes } = params;
+	const response = await axios({
+		url,
+		method: "GET",
+		responseType: "stream",
+		timeout: FETCH_TIMEOUT,
+		maxContentLength: maxBytes,
+		maxBodyLength: maxBytes,
+		validateStatus: () => true
+	});
+	if (response.status < 200 || response.status >= 300) throw new Error(`下载媒体失败: HTTP ${response.status}`);
+	const body = response.data;
+	if (!body) throw new Error("下载媒体失败: 响应体为空");
+	const contentType = String(response.headers["content-type"] || "").split(";")[0].trim().toLowerCase();
+	validateContentType(element.type, contentType);
+	const contentLength = Number(response.headers["content-length"] || 0);
+	if (contentLength > maxBytes) throw new Error(`下载媒体失败: 文件过大 ${contentLength} bytes`);
+	const tempFile = join(dir, `${Date.now()}-${crypto.randomBytes(6).toString("hex")}.part`);
+	const progress = { bytes: 0 };
+	try {
+		await pipeline(body, createLimitStream(progress, maxBytes), createWriteStream(tempFile));
+		await rename(tempFile, finalFile);
+	} catch (err) {
+		await rm(tempFile, { force: true }).catch(() => void 0);
+		throw err;
+	}
+};
+/**
+* 创建限制下载体积的 Transform 流。
+*
+* axios 的 content-length 可能缺失或不可信，这里按实际流经字节再次限制。
+*
+* @param progress 下载进度对象。
+* @param maxBytes 允许通过的最大字节数。
+* @returns 可插入 pipeline 的 Transform 流。
+*/
+const createLimitStream = (progress, maxBytes) => {
+	return new Transform({ transform(chunk, _encoding, callback) {
+		progress.bytes += chunk.length;
+		if (progress.bytes > maxBytes) {
+			callback(/* @__PURE__ */ new Error(`下载媒体失败: 文件过大 ${progress.bytes} bytes`));
+			return;
+		}
+		callback(null, chunk);
+	} });
+};
+/**
+* 递归清理过期缓存文件。
+*
+* 目录本身会保留，只删除超过 deadline 的普通文件。
+*
+* @param dir 需要扫描的目录。
+* @param deadline 过期时间戳，小于等于该时间的文件会被删除。
+* @returns 清理完成 Promise。
+*/
+const cleanupDir = async (dir, deadline) => {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch (err) {
+		if (err.code === "ENOENT") return;
+		throw err;
+	}
+	await Promise.all(entries.map(async (entry) => {
+		const file = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			await cleanupDir(file, deadline);
+			return;
+		}
+		if (!entry.isFile()) return;
+		const info = await stat(file).catch(() => void 0);
+		if (!info || info.mtimeMs > deadline) return;
+		await rm(file, { force: true }).catch(() => void 0);
+	}));
+};
+/**
+* 生成本地缓存文件名。
+*
+* 文件名由 URL 的 sha1 hash 决定，保证同一 URL 的重复本地化落到同一文件，
+* 使去重和跳过下载生效。业务文件名保留在消息段 name 字段里，不进文件名。
+*
+* @param element 媒体消息段。
+* @param source 远程 URL。
+* @returns 不含目录的本地文件名。
+*/
+const getLocalFilename = (element, source) => {
+	return `${crypto.createHash("sha1").update(source).digest("hex").slice(0, 20)}${getFileExtension(element, source)}`;
+};
+/**
+* 推断本地缓存文件扩展名。
+*
+* 文件名必须在请求发出前确定（用于命中已有缓存跳过下载），因此不使用
+* 响应 content-type。优先级：
+* 1. 图片 subType；
+* 2. 文件消息段自带 name 后缀；
+* 3. 语音固定 .mp3；
+* 4. name、URL 后缀；
+* 5. 类型默认扩展名。
+*
+* @param element 媒体消息段。
+* @param source 远程 URL。
+* @returns 带点号的扩展名。
+*/
+const getFileExtension = (element, source) => {
+	if (element.type === "image") {
+		const subtype = element.subType?.toLowerCase();
+		if (subtype && SUBTYPE_EXTENSIONS[subtype]) return SUBTYPE_EXTENSIONS[subtype];
+	}
+	if (element.type === "file") {
+		const fileNameExt = normalizeExtension(extname(element.name || ""));
+		if (fileNameExt) return fileNameExt;
+	}
+	if (element.type === "record") return EXTENSIONS_BY_TYPE.record;
+	const byName = normalizeExtension(extname(element.name || ""));
+	if (byName) return byName;
+	return normalizeExtension(extname(safeUrlPathname(source))) || EXTENSIONS_BY_TYPE[element.type];
+};
+/**
+* 提取 URL pathname，非法 URL 返回空字符串。
+*
+* @param source 远程 URL。
+* @returns pathname 或空字符串。
+*/
+const safeUrlPathname = (source) => {
+	try {
+		return new URL(source).pathname;
+	} catch {
+		return "";
+	}
+};
+/**
+* 规范化并校验扩展名。
+*
+* 只允许短的字母数字扩展名，避免 URL 或文件名中的异常内容进入本地路径。
+*
+* @param ext 原始扩展名。
+* @returns 合法扩展名；非法时返回空字符串。
+*/
+const normalizeExtension = (ext) => {
+	const normalized = ext.toLowerCase();
+	if (!normalized || normalized.length > 16) return "";
+	if (!/^\.[a-z0-9]+$/.test(normalized)) return "";
+	return normalized === ".jpeg" ? ".jpg" : normalized;
+};
+/**
+* 将图片扩展名转换为 Karin image.subType。
+*
+* @param ext 带点号的扩展名。
+* @returns Karin 使用的图片格式名。
+*/
+const extensionToSubType = (ext) => {
+	const normalized = ext.replace(/^\./, "").toLowerCase();
+	return normalized === "jpg" ? "jpeg" : normalized;
+};
+/**
+* 校验响应 content-type 是否和消息段类型相容。
+*
+* 当前只严格校验图片，其他媒体平台可能返回 octet-stream 或不完整类型。
+*
+* @param type 消息段类型。
+* @param contentType 响应 content-type。
+*/
+const validateContentType = (type, contentType) => {
+	if (!contentType) return;
+	if (type === "image" && !contentType.startsWith("image/") && contentType !== "application/octet-stream") throw new Error(`下载媒体失败: 非图片类型 ${contentType}`);
+};
+/**
+* 判断消息段是否带有可本地化的 file 字段。
+*
+* @param element Karin 消息段。
+* @returns true 表示该消息段可以进行媒体本地化。
+*/
+const isFileBackedElement = (element) => {
+	return element.type === "image" || element.type === "video" || element.type === "record" || element.type === "file";
+};
+/**
+* 判断 file 字段是否是远程 URL。
+*
+* @param value file 字段值。
+* @returns true 表示需要下载到本地缓存。
+*/
+const isRemoteUrl = (value) => {
+	return /^https?:\/\//i.test(value) || value.startsWith("//");
+};
+/**
+* 规范化远程 URL。
+*
+* QQ 下发的资源有时是协议相对 URL，这里默认补全为 https。
+*
+* @param value 原始 URL。
+* @returns 可交给 axios 请求的完整 URL。
+*/
+const normalizeRemoteUrl = (value) => {
+	return value.startsWith("//") ? `https:${value}` : value;
+};
+
+//#endregion
+//#region src/core/storage/message-store/codec.ts
+/** 各存储分级允许落库的消息段类型；full 不过滤（encode 自身会跳过不支持的类型）。 */
+const LEVEL_ALLOWED = {
+	minimal: /* @__PURE__ */ new Set(["reply"]),
+	standard: /* @__PURE__ */ new Set([
+		"text",
+		"at",
+		"reply",
+		"face",
+		"image",
+		"video",
+		"record",
+		"file"
+	])
+};
+/**
+* 按存储分级过滤消息段。
+*
+* minimal 只保留 reply 段（引用链解析所需）；standard 丢弃 markdown 原文；
+* full 原样返回。消息主记录（ID 映射、is_self）不受分级影响，始终落库。
+*
+* @param elements Karin 消息段数组。
+* @param level 存储分级；缺省按 standard 处理。
+* @returns 过滤后的消息段数组。
+*/
+const filterElementsByLevel = (elements, level = "standard") => {
+	if (level === "full") return elements;
+	const allowed = LEVEL_ALLOWED[level] || LEVEL_ALLOWED.standard;
+	return elements.filter((element) => allowed.has(element.type));
+};
+/**
+* 将 Karin 消息段编码为紧凑 JSON。
+*
+* 每种消息段只保留 getMsg/getHistoryMsg 还原所需的最小字段；text/markdown
+* 超过 `ELEMENT_TEXT_LIMIT` 截断；本地媒体路径转为相对形式存储。
+* 不支持缓存的类型直接跳过。
+*
+* @param elements Karin 消息段数组。
+* @returns JSON 串和可索引字段。
+*/
+const encodeElements = (elements) => {
+	const stored = [];
+	let replyTo = null;
+	for (const element of elements) {
+		const item = encodeElement(element);
+		if (!item) continue;
+		stored.push(item);
+		if (element.type === "reply" && !replyTo) replyTo = element.messageId;
+	}
+	return {
+		json: JSON.stringify(stored),
+		replyTo
+	};
+};
+/**
+* 将数据库中的紧凑 JSON 还原为 Karin 消息段。
+*
+* @param json `qqbot_messages.elements` 列内容。
+* @returns Karin 消息段数组；JSON 非法或含未知编码时跳过对应消息段。
+*/
+const decodeElements = (json) => {
+	let stored;
+	try {
+		stored = JSON.parse(json);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(stored)) return [];
+	return stored.flatMap(decodeElement);
+};
+/**
+* 编码单个消息段。
+*
+* @param element Karin 消息段。
+* @returns 紧凑存储对象；不支持缓存的类型返回 null。
+*/
+const encodeElement = (element) => {
+	switch (element.type) {
+		case "text": return {
+			c: "t",
+			v: truncateText(element.text)
+		};
+		case "at": return {
+			c: "a",
+			v: element.targetId
+		};
+		case "reply": return {
+			c: "r",
+			v: element.messageId
+		};
+		case "face": return {
+			c: "f",
+			v: element.id
+		};
+		case "image": return {
+			c: "i",
+			v: toStoredFilePath(element.file),
+			...element.subType ? { s: element.subType } : {},
+			...element.width ? { w: element.width } : {},
+			...element.height ? { h: element.height } : {}
+		};
+		case "video": return {
+			c: "v",
+			v: toStoredFilePath(element.file)
+		};
+		case "record": return {
+			c: "s",
+			v: toStoredFilePath(element.file),
+			...element.magic ? { g: 1 } : {}
+		};
+		case "file": return {
+			c: "d",
+			v: toStoredFilePath(element.file),
+			...element.name ? { n: element.name } : {}
+		};
+		case "markdown": return {
+			c: "m",
+			v: truncateText(element.markdown)
+		};
+		default: return null;
+	}
+};
+/**
+* 还原单个消息段。
+*
+* @param item 紧凑存储对象。
+* @returns Karin 消息段；未知编码返回空数组。
+*/
+const decodeElement = (item) => {
+	switch (item.c) {
+		case "t": return [{
+			type: "text",
+			text: stringValue(item.v)
+		}];
+		case "a": return [{
+			type: "at",
+			targetId: stringValue(item.v)
+		}];
+		case "r": return [{
+			type: "reply",
+			messageId: stringValue(item.v)
+		}];
+		case "f": return [{
+			type: "face",
+			id: numberValue(item.v) || 0
+		}];
+		case "i": return [{
+			type: "image",
+			file: fromStoredFilePath(stringValue(item.v)),
+			subType: item.s || void 0,
+			width: positiveNumber(item.w),
+			height: positiveNumber(item.h)
+		}];
+		case "v": return [{
+			type: "video",
+			file: fromStoredFilePath(stringValue(item.v))
+		}];
+		case "s": return [{
+			type: "record",
+			file: fromStoredFilePath(stringValue(item.v)),
+			magic: item.g === 1
+		}];
+		case "d": return [{
+			type: "file",
+			file: fromStoredFilePath(stringValue(item.v)),
+			name: item.n || void 0
+		}];
+		case "m": return [{
+			type: "markdown",
+			markdown: stringValue(item.v)
+		}];
+		default: return [];
+	}
+};
+/**
+* 截断超长文本，控制单条消息的缓存体积。
+*
+* @param text 原始文本。
+* @returns 截断后的文本。
+*/
+const truncateText = (text) => {
+	return text.length > 4096 ? text.slice(0, ELEMENT_TEXT_LIMIT) : text;
+};
+/**
+* 读取字符串字段。
+*
+* @param value 存储值。
+* @returns 字符串；缺失时返回空字符串。
+*/
+const stringValue = (value) => {
+	return value === void 0 ? "" : String(value);
+};
+/**
+* 读取数值字段。
+*
+* @param value 存储值。
+* @returns 有限数值；缺失或非法时返回 undefined。
+*/
+const numberValue = (value) => {
+	const num = Number(value);
+	return Number.isFinite(num) ? num : void 0;
+};
+/**
+* 读取正数字段，宽高等字段只有大于 0 时才还原。
+*
+* @param value 存储值。
+* @returns 正数值；不存在或非法时返回 undefined。
+*/
+const positiveNumber = (value) => {
+	const num = numberValue(value);
+	return num && num > 0 ? num : void 0;
+};
+
+//#endregion
+//#region src/core/storage/message-store/hash.ts
+const FNV_OFFSET = 14695981039346656037n;
+const FNV_PRIME = 1099511628211n;
+const MASK_64 = 18446744073709551615n;
+/** 截断到 53 位，保证 hash 能安全放进 JS number 和 SQLite INTEGER。 */
+const MASK_53 = 9007199254740991n;
+/**
+* 计算消息 ID 的 53 位 FNV-1a hash。
+*
+* QQ 的 `ROBOT1.0_...` / `REFIDX_...` ID 长达 50~90 字符；如果直接对 TEXT 建索引，
+* 每个索引条目都要完整复制一份 ID。改为对 hash 整数列建索引后，索引条目从
+* 几十字节降到 ~12 字节。查询命中后再比对原文，53 位空间下十万级数据的碰撞
+* 概率可以忽略。
+*
+* @param input 消息 ID 或引用索引原文。
+* @returns 53 位非负整数 hash。
+*/
+const hashId = (input) => {
+	let hash = FNV_OFFSET;
+	for (let index = 0; index < input.length; index++) {
+		hash ^= BigInt(input.charCodeAt(index));
+		hash = hash * FNV_PRIME & MASK_64;
+	}
+	return Number(hash & MASK_53);
+};
+
+//#endregion
+//#region src/core/storage/message-store/schema.ts
+/** 开发阶段和 v1 版本遗留的全部缓存表；v2 迁移时统一删除重建。 */
+const LEGACY_TABLES = [
+	"qqbot_message_aliases",
+	"qqbot_element_text",
+	"qqbot_element_at",
+	"qqbot_element_reply",
+	"qqbot_element_face",
+	"qqbot_element_media",
+	"qqbot_element_markdown",
+	"qqbot_message_elements",
+	"qqbot_messages",
+	"qqbot_senders",
+	"qqbot_contacts",
+	"qqbot_bots",
+	"qqbot_message_alias",
+	"qqbot_message_cache"
+];
+/**
+* 删除所有旧版缓存表。
+*
+* 消息缓存只有一天 TTL，跨大版本不迁移数据，直接重建。
+*
+* @param run SQL 执行函数。
+*/
+const dropLegacySchema = async (run) => {
+	for (const table of LEGACY_TABLES) await run(`DROP TABLE IF EXISTS ${table}`);
+};
+/**
+* 创建 v2 表结构。
+*
+* 设计要点（相对 v1 的 6 表规范化）：
+* - 一条消息一行：消息段收进单个 JSON 列，消灭消息段表的行开销、
+*   delete+reinsert 双写和读取时的 N+1 查询；
+* - alias 表取消：实践中一条消息最多只有一个 `msg_idx` 引用索引，
+*   直接作为 `ref_idx` 列存储；
+* - 长 ID 不建 TEXT 索引：`msg_id`/`ref_idx` 原文只存一份，索引建在
+*   53 位整数 hash 列上，命中后比对原文防碰撞；
+* - 不声明外键：无级联删除扫描；senders 由清理任务定期 GC；
+* - 不为 `time` 单独建索引：清理是每 10 分钟一次的后台全表扫描，
+*   省下的索引空间比扫描成本更值。
+*
+* @param run SQL 执行函数。
+*/
+const createSchema = async (run) => {
+	await run(`CREATE TABLE qqbot_contacts (
+    id INTEGER PRIMARY KEY,
+    bot_id TEXT NOT NULL,
+    scene TEXT NOT NULL,
+    peer TEXT NOT NULL,
+    sub_peer TEXT NOT NULL DEFAULT '',
+    name TEXT NOT NULL DEFAULT '',
+    sub_name TEXT NOT NULL DEFAULT '',
+    UNIQUE(bot_id, scene, peer, sub_peer)
+  )`);
+	await run(`CREATE TABLE qqbot_senders (
+    id INTEGER PRIMARY KEY,
+    bot_id TEXT NOT NULL,
+    user_id TEXT NOT NULL,
+    nick TEXT NOT NULL DEFAULT '',
+    name TEXT NOT NULL DEFAULT '',
+    role TEXT NOT NULL DEFAULT 'member',
+    UNIQUE(bot_id, user_id, nick, name, role)
+  )`);
+	await run(`CREATE TABLE qqbot_messages (
+    id INTEGER PRIMARY KEY,
+    contact_ref INTEGER NOT NULL,
+    sender_ref INTEGER NOT NULL,
+    msg_id TEXT NOT NULL,
+    msg_id_hash INTEGER NOT NULL,
+    ref_idx TEXT,
+    ref_idx_hash INTEGER,
+    reply_to TEXT,
+    time INTEGER NOT NULL,
+    is_self INTEGER NOT NULL DEFAULT 0,
+    is_ref_context INTEGER NOT NULL DEFAULT 0,
+    has_remote_media INTEGER NOT NULL DEFAULT 0,
+    elements TEXT NOT NULL
+  )`);
+	await run("CREATE INDEX idx_qqbot_messages_msg_hash ON qqbot_messages(msg_id_hash)");
+	await run(`CREATE INDEX idx_qqbot_messages_ref_hash ON qqbot_messages(ref_idx_hash)
+    WHERE ref_idx_hash IS NOT NULL`);
+	await run("CREATE INDEX idx_qqbot_messages_history ON qqbot_messages(contact_ref, time)");
+	await run(`CREATE INDEX idx_qqbot_messages_remote ON qqbot_messages(has_remote_media)
+    WHERE has_remote_media = 1`);
+};
+/**
+* 创建 v3 file_info 上传缓存表。
+*
+* QQ 上传接口返回的 file_info 有明确 ttl（可达数天）；持久化后进程重启
+* 不再需要把同一份媒体重新上传。行数少（上限 2000），TEXT 主键即可。
+*
+* @param run SQL 执行函数。
+*/
+const createUploadCacheSchema = async (run) => {
+	await run(`CREATE TABLE IF NOT EXISTS qqbot_upload_cache (
+    cache_key TEXT PRIMARY KEY,
+    response TEXT NOT NULL,
+    expires_at INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL
+  )`);
+};
+
+//#endregion
+//#region src/core/storage/message-store/migrations.ts
+/**
+* 消息缓存数据库迁移入口。
+*
+* 后续改表时只需要在数组末尾追加对象，例如：
+*
+* ```ts
+* {
+*   version: 3,
+*   description: '给 qqbot_messages 增加 xxx 字段',
+*   up: async ({ run }) => {
+*     await run('ALTER TABLE qqbot_messages ADD COLUMN xxx TEXT')
+*   },
+* }
+* ```
+*/
+const migrations = [
+	{
+		version: 1,
+		description: "旧版 6 表基线；已被 v2 整体重建取代，仅保留版本号占位",
+		up: async () => {}
+	},
+	{
+		version: 2,
+		description: "v2 重建：单表消息 + 整数 hash 索引 + JSON 消息段，取消 alias 表和外键",
+		up: async ({ run, markVacuum }) => {
+			await dropLegacySchema(run);
+			markVacuum();
+			await createSchema(run);
+		}
+	},
+	{
+		version: 3,
+		description: "新增 file_info 上传结果持久化缓存表",
+		up: async ({ run }) => {
+			await createUploadCacheSchema(run);
+		}
+	}
+];
+
+//#endregion
+//#region src/core/storage/message-store/sql.ts
+/**
+* 消息主表查询字段。
+*
+* 长 ID 只在 `qqbot_messages` 存一份原文；查询统一走整数 hash 索引，
+* 命中后由调用方比对原文防碰撞。
+*/
+const messageSelectFields = `
+  m.id AS message_ref,
+  m.contact_ref,
+  c.bot_id,
+  m.msg_id,
+  m.ref_idx,
+  m.reply_to,
+  m.time,
+  m.is_self,
+  m.elements,
+  c.scene,
+  c.peer,
+  c.sub_peer,
+  c.name AS contact_name,
+  c.sub_name AS contact_sub_name,
+  s.user_id AS sender_user_id,
+  s.nick AS sender_nick,
+  s.name AS sender_name,
+  s.role AS sender_role`;
+const messageJoins = `
+  FROM qqbot_messages m
+  JOIN qqbot_contacts c ON c.id = m.contact_ref
+  JOIN qqbot_senders s ON s.id = m.sender_ref`;
+const SQL = {
+	upsertContact: `INSERT INTO qqbot_contacts (bot_id, scene, peer, sub_peer, name, sub_name)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(bot_id, scene, peer, sub_peer) DO UPDATE SET
+      name = excluded.name,
+      sub_name = excluded.sub_name`,
+	selectContactId: `SELECT id FROM qqbot_contacts
+    WHERE bot_id = ? AND scene = ? AND peer = ? AND sub_peer = ?`,
+	upsertSender: `INSERT INTO qqbot_senders (bot_id, user_id, nick, name, role)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(bot_id, user_id, nick, name, role) DO NOTHING`,
+	selectSenderId: `SELECT id FROM qqbot_senders
+    WHERE bot_id = ? AND user_id = ? AND nick = ? AND name = ? AND role = ?`,
+	/** 写入侧按 hash 定位既有行；同一 flush 循环串行执行，无并发写竞争。 */
+	selectMessageIdByMsgId: `SELECT id FROM qqbot_messages
+    WHERE msg_id_hash = ? AND contact_ref = ? AND msg_id = ?`,
+	selectMessageIdByRefIdx: `SELECT id FROM qqbot_messages
+    WHERE ref_idx_hash = ? AND ref_idx_hash IS NOT NULL AND contact_ref = ? AND ref_idx = ?`,
+	insertMessage: `INSERT INTO qqbot_messages (
+    contact_ref, sender_ref, msg_id, msg_id_hash, ref_idx, ref_idx_hash,
+    reply_to, time, is_self, is_ref_context, has_remote_media, elements
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+	updateMessage: `UPDATE qqbot_messages SET
+    sender_ref = ?,
+    ref_idx = COALESCE(?, ref_idx),
+    ref_idx_hash = COALESCE(?, ref_idx_hash),
+    reply_to = ?,
+    time = ?,
+    is_self = ?,
+    has_remote_media = ?,
+    elements = ?
+    WHERE id = ?`,
+	selectByMsgId: `SELECT ${messageSelectFields} ${messageJoins}
+    WHERE m.msg_id_hash = ? AND c.bot_id = ? AND m.msg_id = ?
+    LIMIT 1`,
+	selectByMsgIdScoped: `SELECT ${messageSelectFields} ${messageJoins}
+    WHERE m.msg_id_hash = ? AND c.bot_id = ? AND c.scene = ? AND c.peer = ? AND c.sub_peer = ?
+      AND m.msg_id = ?
+    LIMIT 1`,
+	selectByRefIdx: `SELECT ${messageSelectFields} ${messageJoins}
+    WHERE m.ref_idx_hash = ? AND m.ref_idx_hash IS NOT NULL AND c.bot_id = ? AND m.ref_idx = ?
+    LIMIT 1`,
+	selectByRefIdxScoped: `SELECT ${messageSelectFields} ${messageJoins}
+    WHERE m.ref_idx_hash = ? AND m.ref_idx_hash IS NOT NULL
+      AND c.bot_id = ? AND c.scene = ? AND c.peer = ? AND c.sub_peer = ?
+      AND m.ref_idx = ?
+    LIMIT 1`,
+	/** 清除指向错误消息的引用索引（历史缓存中 alias 污染的兜底）。 */
+	clearRefIdx: "UPDATE qqbot_messages SET ref_idx = NULL, ref_idx_hash = NULL WHERE id = ?",
+	selectHistory: `SELECT ${messageSelectFields} ${messageJoins}
+    WHERE m.contact_ref = ?
+      AND (m.time < ? OR (m.time = ? AND m.id <= ?))
+    ORDER BY m.time DESC, m.id DESC
+    LIMIT ?`,
+	selectRemoteMedia: `SELECT ${messageSelectFields} ${messageJoins}
+    WHERE m.has_remote_media = 1 AND m.time > ?
+    ORDER BY m.time DESC
+    LIMIT ?`,
+	cleanup: "DELETE FROM qqbot_messages WHERE time <= ?",
+	countMessages: "SELECT COUNT(*) AS total FROM qqbot_messages",
+	/** 超过硬上限时删除最旧的行；id 单调递增，等价于按写入顺序删除。 */
+	deleteOverCap: `DELETE FROM qqbot_messages WHERE id IN (
+    SELECT id FROM qqbot_messages ORDER BY id ASC LIMIT ?
+  )`,
+	/** 清理不再被任何消息引用的 sender 行，避免昵称变化导致的永久膨胀。 */
+	gcSenders: `DELETE FROM qqbot_senders WHERE id NOT IN (
+    SELECT DISTINCT sender_ref FROM qqbot_messages
+  )`,
+	selectUpload: "SELECT response, expires_at FROM qqbot_upload_cache WHERE cache_key = ?",
+	upsertUpload: `INSERT INTO qqbot_upload_cache (cache_key, response, expires_at, created_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(cache_key) DO UPDATE SET
+      response = excluded.response,
+      expires_at = excluded.expires_at,
+      created_at = excluded.created_at`,
+	/** expires_at = 0 表示长期有效，只受行数上限淘汰。 */
+	cleanupUploads: "DELETE FROM qqbot_upload_cache WHERE expires_at != 0 AND expires_at <= ?",
+	countUploads: "SELECT COUNT(*) AS total FROM qqbot_upload_cache",
+	deleteUploadsOverCap: `DELETE FROM qqbot_upload_cache WHERE cache_key IN (
+    SELECT cache_key FROM qqbot_upload_cache ORDER BY created_at ASC LIMIT ?
+  )`
+};
+
+//#endregion
+//#region src/core/storage/message-store/store.ts
+/**
+* QQBot 收到的消息缓存。
+*
+* SQLite 是唯一数据层，没有内存镜像：
+* - 写入热路径只入队，后台按批次事务落库，每条消息稳定 2~3 次语句
+*   往返（prepared statement 复用）；
+* - 所有读取直接查 SQLite（WAL + 整数 hash 索引，点查亚毫秒级）；
+*   读取前先排空待写队列，保证"读到自己刚写的数据"。
+*/
+var MessageStore = class {
+	db;
+	ready;
+	shouldVacuum = false;
+	flushTimer;
+	flushActive;
+	mediaTimer;
+	mediaActive = 0;
+	pending = [];
+	pendingMedia = [];
+	pendingMediaKeys = /* @__PURE__ */ new Set();
+	statements = /* @__PURE__ */ new Map();
+	contactRefCache = /* @__PURE__ */ new Map();
+	senderRefCache = /* @__PURE__ */ new Map();
+	/** 当前生效的缓存保留时长；由配置解析，多 bot 取最大值。 */
+	ttlMs = MESSAGE_TTL;
+	/** 当前生效的消息行数硬上限；由配置解析，多 bot 取最大值。 */
+	maxRows = MAX_MESSAGE_ROWS;
+	constructor() {
+		this.ready = this.initialize();
+		this.ready.then(() => this.recoverRemoteMedia()).catch((err) => log("error", "[getMsg] 消息缓存数据库初始化失败", err));
+	}
+	/**
+	* 立即执行一次过期消息和本地媒体缓存清理。
+	*
+	* 该方法交给 Karin `task` 调度调用；读写路径不再内嵌清理，避免尾延迟。
+	*
+	* @returns 清理完成 Promise。
+	*/
+	async cleanupExpired() {
+		await this.ready;
+		await this.cleanup();
+	}
+	/**
+	* 保存实际消息。
+	*
+	* 只克隆快照并投递后台队列，不等待 SQLite，消息事件创建不会被
+	* 数据库写锁或小事务阻塞。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param message 已转换为 Karin elements 的消息缓存。
+	* @param options 引用索引与自己消息标记。
+	*/
+	async save(botId, message, options = {}) {
+		if (!message.messageId) return;
+		if (this.isExpired(message)) return;
+		const cached = this.cloneMessage({
+			...message,
+			elements: filterElementsByLevel(message.elements, options.level)
+		});
+		const refIdx = options.refIdx && options.refIdx !== message.messageId ? options.refIdx : void 0;
+		const isSelf = !!options.isSelf;
+		this.enqueue({
+			botId,
+			message: cached,
+			refIdx,
+			isSelf,
+			referenceOnly: false
+		});
+		this.enqueueMediaLocalize(botId, cached, refIdx, isSelf);
+	}
+	/**
+	* 保存 QQ 下发的引用上下文。
+	*
+	* 是否已有同 ID 缓存（原消息或引用索引）由后台 flush 在事务内判断并去重，
+	* 避免阻塞事件热路径。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param message 以 `ref_msg_idx` 作为 messageId 的引用上下文。
+	* @param level 存储分级；缺省按 standard 处理。
+	*/
+	async saveReferenceIfAbsent(botId, message, level) {
+		if (!message.messageId) return;
+		if (this.isExpired(message)) return;
+		const cached = this.cloneMessage({
+			...message,
+			elements: filterElementsByLevel(message.elements, level)
+		});
+		this.enqueue({
+			botId,
+			message: cached,
+			isSelf: false,
+			referenceOnly: true
+		});
+		this.enqueueMediaLocalize(botId, cached, void 0, false);
+	}
+	/**
+	* 读取缓存消息。
+	*
+	* OneBot v11 标准调用只传 messageId；contact 参数仅用于额外限定范围。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param messageId 真实消息 ID 或 QQ `REFIDX` 引用索引。
+	* @param contact 可选会话范围，传入后只在该会话下查询。
+	* @returns 命中的消息缓存；未命中或已过期时返回 null。
+	*/
+	async get(botId, messageId, contact) {
+		if (!messageId) return null;
+		await this.ready;
+		await this.flushAll();
+		const row = await this.queryMessageRow(botId, messageId, contact);
+		if (!row || this.isExpired(row)) return null;
+		return this.rowToResponse(row);
+	}
+	/**
+	* 按起始消息 ID 读取同一会话内的历史缓存消息。
+	*
+	* QQ 官方 Bot 没有 seq 历史查询能力；这里以本地缓存中命中的起始消息为锚点，
+	* 按时间倒序返回最近的 `count` 条消息，包含起始消息本身。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact 查询限定的会话。
+	* @param startMsgId 起始消息 ID 或 QQ `REFIDX` 引用索引。
+	* @param count 获取消息数量。
+	* @returns 命中的历史消息数组；未命中或已过期时返回空数组。
+	*/
+	async getHistory(botId, contact, startMsgId, count) {
+		const limit = Math.trunc(count || 1);
+		if (!startMsgId || limit <= 0) return [];
+		await this.ready;
+		await this.flushAll();
+		const anchor = await this.queryMessageRow(botId, startMsgId, contact);
+		if (!anchor || this.isExpired(anchor)) return [];
+		return (await this.allS(SQL.selectHistory, [
+			anchor.contact_ref,
+			anchor.time,
+			anchor.time,
+			anchor.message_ref,
+			limit
+		])).map((row) => this.rowToResponse(row));
+	}
+	/**
+	* 将 QQ `REFIDX` 引用索引解析为 API 消息 ID。
+	*
+	* 撤回等平台接口的唯一映射来源；ID 映射行不受缓存开关影响，始终落库。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact 消息所在会话。
+	* @param refIdx QQ 引用索引，通常为 REFIDX_...。
+	* @returns 对应的 API 消息 ID；未命中时返回 null。
+	*/
+	async resolveApiMessageId(botId, contact, refIdx) {
+		if (!refIdx) return null;
+		await this.ready;
+		await this.flushAll();
+		const row = await this.getS(SQL.selectByRefIdxScoped, [
+			hashId(refIdx),
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			refIdx
+		]);
+		if (!row || this.isExpired(row)) return null;
+		return row.msg_id;
+	}
+	/**
+	* 将 API 消息 ID 反向解析为 QQ `REFIDX` 引用索引。
+	*
+	* 发送侧显式引用回复的唯一映射来源。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact 消息所在会话。
+	* @param messageId QQ API 消息 ID，通常为 ROBOT1.0_...。
+	* @returns 对应的引用索引；未命中时返回 null。
+	*/
+	async resolveRefIdx(botId, contact, messageId) {
+		if (!messageId) return null;
+		await this.ready;
+		await this.flushAll();
+		const row = await this.getS(SQL.selectByMsgIdScoped, [
+			hashId(messageId),
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			messageId
+		]);
+		if (!row || this.isExpired(row)) return null;
+		return row.ref_idx;
+	}
+	/**
+	* 读取持久化的 file_info 上传缓存。
+	*
+	* @param key 由 api 层构造的缓存键。
+	* @returns 序列化的上传响应 JSON；未命中或已过期时返回 null。
+	*/
+	async getUploadCache(key) {
+		if (!key) return null;
+		await this.ready;
+		const row = await this.getS(SQL.selectUpload, [key]);
+		if (!row) return null;
+		if (row.expires_at !== 0 && row.expires_at <= Date.now()) return null;
+		return row.response;
+	}
+	/**
+	* 写入持久化的 file_info 上传缓存。
+	*
+	* @param key 由 api 层构造的缓存键。
+	* @param response 序列化的上传响应 JSON。
+	* @param expiresAt 失效时间戳；0 表示长期有效。
+	*/
+	async setUploadCache(key, response, expiresAt) {
+		if (!key) return;
+		await this.ready;
+		await this.runS(SQL.upsertUpload, [
+			key,
+			response,
+			expiresAt,
+			Date.now()
+		]);
+	}
+	/**
+	* 判断消息是否由机器人自己发送。
+	*
+	* 单聊撤回判定的唯一来源，读取消息行的 `is_self` 标记。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact 消息所在会话。
+	* @param messageId QQ API 消息 ID。
+	* @returns true 表示是机器人自己发送的消息。
+	*/
+	async isSelfMessage(botId, contact, messageId) {
+		if (!messageId) return false;
+		await this.ready;
+		await this.flushAll();
+		const row = await this.queryMessageRow(botId, messageId, contact);
+		return !!row && !this.isExpired(row) && row.is_self === 1;
+	}
+	/**
+	* 初始化 SQLite 连接、表结构，并执行一次启动清理。
+	*
+	* 远程媒体补救不在这里执行，避免阻塞 `ready` 拖慢首批消息落库。
+	*
+	* @returns 初始化完成 Promise。
+	*/
+	async initialize() {
+		const file = join(karinPathBase, "@karinjs-adapter-qqbot", "data", "message-cache.db");
+		await mkdir(dirname(file), { recursive: true });
+		this.db = await new Promise((resolve, reject) => {
+			const db = new sqlite3.Database(file, (err) => err ? reject(err) : resolve(db));
+		});
+		await this.exec("PRAGMA journal_mode = WAL");
+		await this.exec("PRAGMA synchronous = NORMAL");
+		await this.exec("PRAGMA temp_store = MEMORY");
+		await this.exec("PRAGMA busy_timeout = 5000");
+		/** 在迁移 VACUUM 前设置才会生效；生效后清理任务通过增量 vacuum 归还空间。 */
+		await this.exec("PRAGMA auto_vacuum = INCREMENTAL");
+		await this.migrate();
+		await this.cleanup();
+	}
+	/**
+	* 从配置解析当前生效的 TTL 与行数上限。
+	*
+	* 数据库为全 bot 共享，多个 bot 同时开启缓存时取最大值；配置读取失败时
+	* 保持当前值。每次清理前刷新，配置修改最迟 10 分钟内生效。
+	*/
+	refreshSettings() {
+		try {
+			const enabled = config().filter((item) => item.messageCache.enable);
+			if (!enabled.length) {
+				this.ttlMs = MESSAGE_TTL;
+				this.maxRows = MAX_MESSAGE_ROWS;
+				return;
+			}
+			this.ttlMs = Math.max(...enabled.map((item) => item.messageCache.ttlHours)) * 60 * 60 * 1e3;
+			this.maxRows = Math.max(...enabled.map((item) => item.messageCache.maxRows));
+		} catch (err) {
+			log("debug", "[getMsg] 读取消息缓存配置失败，沿用当前 TTL/上限", err);
+		}
+	}
+	/**
+	* 投递待落库消息。
+	*
+	* @param item 待写入 SQLite 的缓存任务。
+	*/
+	enqueue(item) {
+		this.pending.push(item);
+		if (this.pending.length > 1e4) {
+			this.prunePending();
+			if (this.pending.length > 1e4) {
+				const dropCount = this.pending.length - MAX_WRITE_QUEUE;
+				this.pending.splice(0, dropCount);
+				log("warn", `[getMsg] SQLite 写入队列过长，已丢弃 ${dropCount} 条最旧待写缓存`);
+			}
+		}
+		this.scheduleFlush();
+	}
+	/**
+	* 安排一次后台批量落库。
+	*
+	* 已有 timer 或正在 flush 时不会重复安排。
+	*/
+	scheduleFlush() {
+		if (this.flushTimer || this.flushActive) return;
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = void 0;
+			this.flushQueue().catch(() => void 0);
+		}, 100);
+		this.flushTimer.unref();
+	}
+	/**
+	* 触发一次批量落库；已有进行中的 flush 时复用其 Promise。
+	*
+	* @returns 当前批次落库完成的 Promise。
+	*/
+	flushQueue() {
+		if (!this.flushActive) this.flushActive = this.doFlushBatch().catch((err) => log("warn", "[getMsg] 批量写入消息缓存失败", err)).finally(() => {
+			this.flushActive = void 0;
+			if (this.pending.length) this.scheduleFlush();
+		});
+		return this.flushActive;
+	}
+	/**
+	* 等待写入队列完全清空。
+	*
+	* 所有读取入口先经过它，保证"读到自己刚写的数据"；队列为空时零开销。
+	*/
+	async flushAll() {
+		while (this.pending.length || this.flushActive) await this.flushQueue();
+	}
+	/**
+	* 批量落库队列中的消息。
+	*
+	* 单次最多处理 `FLUSH_BATCH_SIZE` 条，并在一个事务内完成写入。
+	*
+	* @returns flush 完成 Promise。
+	*/
+	async doFlushBatch() {
+		await this.ready;
+		const batch = this.pending.splice(0, 500);
+		if (!batch.length) return;
+		await this.transaction(async () => {
+			for (const item of batch) {
+				if (this.isExpired(item.message)) continue;
+				try {
+					await this.writeItem(item);
+				} catch (err) {
+					/** 单条失败只跳过自身，不让一条毒消息丢掉整批 ID 映射。 */
+					log("warn", `[getMsg] 跳过写入失败的缓存消息: ${item.message.messageId}`, err);
+				}
+			}
+		});
+	}
+	/**
+	* 写入一条待落库消息。
+	*
+	* 稳定状态下（contact/sender 已缓存）每条消息 2 次语句往返：
+	* 定位既有行 + INSERT 或 UPDATE。
+	*
+	* @param item 待写入的消息任务。
+	*/
+	async writeItem(item) {
+		const contactRef = await this.ensureContact(item.botId, item.message.contact);
+		const msgHash = hashId(item.message.messageId);
+		const existing = await this.getS(SQL.selectMessageIdByMsgId, [
+			msgHash,
+			contactRef,
+			item.message.messageId
+		]);
+		if (item.referenceOnly) {
+			if (existing) return;
+			if (await this.getS(SQL.selectMessageIdByRefIdx, [
+				msgHash,
+				contactRef,
+				item.message.messageId
+			])) return;
+		}
+		const senderRef = await this.ensureSender(item.botId, item.message.sender);
+		const encoded = encodeElements(item.message.elements);
+		const hasRemote = hasRemoteFileElement(item.message.elements) ? 1 : 0;
+		const refIdx = item.refIdx || null;
+		const refHash = refIdx ? hashId(refIdx) : null;
+		if (existing) {
+			await this.runS(SQL.updateMessage, [
+				senderRef,
+				refIdx,
+				refHash,
+				encoded.replyTo,
+				item.message.time,
+				item.isSelf ? 1 : 0,
+				hasRemote,
+				encoded.json,
+				existing.id
+			]);
+			return;
+		}
+		await this.runS(SQL.insertMessage, [
+			contactRef,
+			senderRef,
+			item.message.messageId,
+			msgHash,
+			refIdx,
+			refHash,
+			encoded.replyTo,
+			item.message.time,
+			item.isSelf ? 1 : 0,
+			item.referenceOnly ? 1 : 0,
+			hasRemote,
+			encoded.json
+		]);
+	}
+	/**
+	* 清理待写队列中已经过期的消息。
+	*/
+	prunePending() {
+		const deadline = Date.now() - this.ttlMs;
+		const kept = this.pending.filter((item) => item.message.time > deadline);
+		if (kept.length !== this.pending.length) this.pending = kept;
+	}
+	/**
+	* 投递媒体本地化任务。
+	*
+	* 原消息会先保留短期 URL 写入缓存；本地化成功后再覆盖同一条消息。队列会按
+	* message scoped key 去重，避免高频更新同一条消息时重复下载。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param message 可能包含远程媒体 URL 的消息快照。
+	* @param refIdx 该消息的引用索引，成功本地化后随消息一并回写。
+	* @param isSelf 是否机器人自己发送。
+	*/
+	enqueueMediaLocalize(botId, message, refIdx, isSelf) {
+		if (!hasRemoteFileElement(message.elements)) return;
+		if (this.isExpired(message)) return;
+		const key = [
+			botId,
+			message.contact.scene,
+			message.contact.peer,
+			message.contact.subPeer || "",
+			message.messageId
+		].join("");
+		if (this.pendingMediaKeys.has(key)) return;
+		this.pendingMedia.push({
+			botId,
+			message: this.cloneMessage(message),
+			refIdx,
+			isSelf,
+			key
+		});
+		this.pendingMediaKeys.add(key);
+		if (this.pendingMedia.length > 2e3) {
+			this.prunePendingMedia();
+			if (this.pendingMedia.length > 2e3) {
+				const dropped = this.pendingMedia.splice(0, this.pendingMedia.length - MAX_MEDIA_LOCALIZE_QUEUE);
+				dropped.forEach((item) => this.pendingMediaKeys.delete(item.key));
+				log("warn", `[getMsg] 媒体本地缓存队列过长，已丢弃 ${dropped.length} 条最旧任务`);
+			}
+		}
+		this.scheduleMediaLocalize();
+	}
+	/**
+	* 安排媒体本地化队列处理。
+	*
+	* @returns 已存在定时器或队列为空时直接返回。
+	*/
+	scheduleMediaLocalize() {
+		if (this.mediaTimer) return;
+		if (!this.pendingMedia.length) return;
+		this.mediaTimer = setTimeout(() => {
+			this.mediaTimer = void 0;
+			this.drainMediaLocalizeQueue();
+		}, 100);
+		this.mediaTimer.unref();
+	}
+	/**
+	* 按固定并发处理媒体本地化任务。
+	*
+	* @returns 队列为空或达到并发上限时返回。
+	*/
+	drainMediaLocalizeQueue() {
+		while (this.mediaActive < 4 && this.pendingMedia.length) {
+			const item = this.pendingMedia.shift();
+			this.mediaActive++;
+			this.localizeMediaItem(item).catch((err) => log("warn", `[getMsg] 媒体本地缓存失败: ${item.message.messageId}`, err)).finally(() => {
+				this.mediaActive--;
+				this.pendingMediaKeys.delete(item.key);
+				if (this.pendingMedia.length) this.scheduleMediaLocalize();
+			});
+		}
+	}
+	/**
+	* 本地化单条消息中的远程媒体字段，并在成功后覆盖内存与 SQLite。
+	*
+	* @param item 待处理的媒体本地化任务。
+	* @returns 本地化与回写完成 Promise。
+	*/
+	async localizeMediaItem(item) {
+		if (this.isExpired(item.message)) return;
+		const result = await localizeFileElements(item.message.elements);
+		for (const failure of result.failures) log("debug", `[getMsg] 媒体本地缓存跳过: ${item.message.messageId} ${failure}`);
+		if (!result.changed) return;
+		const localized = this.cloneMessage({
+			...item.message,
+			elements: result.elements
+		});
+		this.enqueue({
+			botId: item.botId,
+			message: localized,
+			refIdx: item.refIdx,
+			isSelf: item.isSelf,
+			referenceOnly: false
+		});
+	}
+	/**
+	* 清理已经过期的媒体本地化待处理任务。
+	*/
+	prunePendingMedia() {
+		const deadline = Date.now() - this.ttlMs;
+		const kept = [];
+		for (const item of this.pendingMedia) if (item.message.time > deadline) kept.push(item);
+		else this.pendingMediaKeys.delete(item.key);
+		if (kept.length !== this.pendingMedia.length) this.pendingMedia = kept;
+	}
+	/**
+	* 启动时扫描 SQLite 中尚未本地化的远程媒体消息，并重新投递队列补救。
+	*
+	* `has_remote_media` 是部分索引列，扫描不再需要 LIKE 全表匹配。
+	*
+	* @returns 扫描和投递完成 Promise。
+	*/
+	async recoverRemoteMedia() {
+		const rows = await this.allS(SQL.selectRemoteMedia, [Date.now() - this.ttlMs, MEDIA_RECOVERY_LIMIT]);
+		if (!rows.length) return;
+		for (const row of rows) {
+			const response = this.rowToResponse(row);
+			this.enqueueMediaLocalize(row.bot_id, {
+				messageId: response.messageId,
+				messageSeq: response.messageSeq,
+				time: response.time,
+				contact: response.contact,
+				sender: response.sender,
+				elements: response.elements
+			}, row.ref_idx || void 0, row.is_self === 1);
+		}
+		log("debug", `[getMsg] 已投递 ${rows.length} 条远程媒体缓存补救任务`);
+	}
+	/**
+	* 按消息 ID 或引用索引查询消息行。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param messageId 真实消息 ID 或 `REFIDX` 引用索引。
+	* @param contact 可选会话范围。
+	* @returns 命中的消息行；未命中时返回 null。
+	*/
+	async queryMessageRow(botId, messageId, contact) {
+		const hash = hashId(messageId);
+		const direct = contact ? await this.getS(SQL.selectByMsgIdScoped, [
+			hash,
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			messageId
+		]) : await this.getS(SQL.selectByMsgId, [
+			hash,
+			botId,
+			messageId
+		]);
+		if (direct) return direct;
+		const byRef = contact ? await this.getS(SQL.selectByRefIdxScoped, [
+			hash,
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			messageId
+		]) : await this.getS(SQL.selectByRefIdx, [
+			hash,
+			botId,
+			messageId
+		]);
+		if (!byRef) return null;
+		if (byRef.reply_to === messageId) {
+			/** 该行的引用索引错误指向它引用的消息，属于旧缓存污染，清除后按未命中处理。 */
+			await this.runS(SQL.clearRefIdx, [byRef.message_ref]);
+			return null;
+		}
+		return byRef;
+	}
+	/**
+	* 浅拷贝消息缓存，避免后续事件对象被插件侧修改后污染缓存。
+	*
+	* @param message 原始缓存消息。
+	* @returns 可安全放入缓存的消息副本。
+	*/
+	cloneMessage(message) {
+		return {
+			...message,
+			contact: { ...message.contact },
+			sender: { ...message.sender },
+			elements: message.elements.map((element) => ({ ...element }))
+		};
+	}
+	/**
+	* 将数据库行还原为 Karin `MessageResponse`。
+	*
+	* @param row 消息主查询结果。
+	* @returns Karin 标准消息查询结果。
+	*/
+	rowToResponse(row) {
+		return {
+			messageId: row.msg_id,
+			messageSeq: 0,
+			time: row.time,
+			contact: this.contactFromRow(row),
+			sender: {
+				userId: row.sender_user_id,
+				nick: row.sender_nick,
+				name: row.sender_name,
+				role: row.sender_role
+			},
+			elements: decodeElements(row.elements)
+		};
+	}
+	/**
+	* 从查询行还原 Karin Contact。
+	*
+	* @param row 消息主查询结果。
+	* @returns Karin Contact。
+	*/
+	contactFromRow(row) {
+		const common = {
+			peer: row.peer,
+			name: row.contact_name
+		};
+		switch (row.scene) {
+			case "group": return {
+				scene: "group",
+				...common
+			};
+			case "friend": return {
+				scene: "friend",
+				...common
+			};
+			case "guild": return {
+				scene: "guild",
+				...common,
+				subPeer: row.sub_peer,
+				subName: row.contact_sub_name
+			};
+			case "direct": return {
+				scene: "direct",
+				...common,
+				subPeer: row.sub_peer,
+				subName: row.contact_sub_name
+			};
+			case "groupTemp": return {
+				scene: "groupTemp",
+				...common,
+				subPeer: row.sub_peer
+			};
+		}
+	}
+	/**
+	* 获取或创建会话映射 ID。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact Karin 会话对象。
+	* @returns `qqbot_contacts.id`。
+	*/
+	async ensureContact(botId, contact) {
+		const key = [
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || ""
+		].join("");
+		const cached = this.contactRefCache.get(key);
+		if (cached) return cached;
+		const values = [
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			contact.name || "",
+			contact.subName || ""
+		];
+		await this.runS(SQL.upsertContact, values);
+		const row = await this.getS(SQL.selectContactId, values.slice(0, 4));
+		if (!row) throw new Error(`消息缓存会话映射写入失败: ${contact.scene}:${contact.peer}`);
+		this.contactRefCache.set(key, row.id);
+		return row.id;
+	}
+	/**
+	* 获取或创建发送者映射 ID。
+	*
+	* sender 按 (userId, nick, name, role) 去重；不再被引用的行由清理任务 GC，
+	* 不会随昵称变化永久膨胀。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param sender Karin sender 对象。
+	* @returns `qqbot_senders.id`。
+	*/
+	async ensureSender(botId, sender) {
+		const role = sender.role || "member";
+		const values = [
+			botId,
+			sender.userId || "",
+			sender.nick || "",
+			sender.name || "",
+			role
+		];
+		const key = values.join("");
+		const cached = this.senderRefCache.get(key);
+		if (cached) return cached;
+		await this.runS(SQL.upsertSender, values);
+		const row = await this.getS(SQL.selectSenderId, values);
+		if (!row) throw new Error(`消息缓存发送者映射写入失败: ${sender.userId || ""}`);
+		this.senderRefCache.set(key, row.id);
+		return row.id;
+	}
+	/**
+	* 判断消息是否已经超过本地缓存 TTL。
+	*
+	* @param row 带 `time` 字段的消息对象。
+	* @returns true 表示已经超过一天缓存窗口。
+	*/
+	isExpired(row) {
+		return row.time <= Date.now() - this.ttlMs;
+	}
+	/**
+	* 清理过期缓存消息，并执行体积治理。
+	*
+	* 依次执行：配置刷新、TTL 删除、硬上限删除、上传缓存清理、
+	* sender GC（写空闲时）、增量 vacuum 归还空间、WAL checkpoint 截断、
+	* 媒体文件清理。
+	*/
+	async cleanup() {
+		this.refreshSettings();
+		await this.runS(SQL.cleanup, [Date.now() - this.ttlMs]);
+		const count = await this.getS(SQL.countMessages);
+		if (count && count.total > this.maxRows) {
+			const excess = count.total - this.maxRows;
+			await this.runS(SQL.deleteOverCap, [excess]);
+			log("warn", `[getMsg] 消息缓存超过 ${this.maxRows} 条硬上限，已删除最旧 ${excess} 条`);
+		}
+		await this.runS(SQL.cleanupUploads, [Date.now()]);
+		const uploads = await this.getS(SQL.countUploads);
+		if (uploads && uploads.total > 2e3) await this.runS(SQL.deleteUploadsOverCap, [uploads.total - UPLOAD_CACHE_MAX_ROWS]);
+		/** sender GC 与批量写并发会产生悬空 sender_ref，只在写队列空闲时执行。 */
+		if (!this.pending.length && !this.flushActive) {
+			await this.runS(SQL.gcSenders);
+			this.senderRefCache.clear();
+		}
+		await this.exec("PRAGMA incremental_vacuum");
+		await this.rawGet("PRAGMA wal_checkpoint(TRUNCATE)").catch(() => void 0);
+		await cleanupMessageMediaCache(this.ttlMs);
+	}
+	/**
+	* 执行数据库版本迁移。
+	*
+	* 使用 SQLite `PRAGMA user_version` 记录已应用的 schema 版本。
+	*
+	* @returns 迁移完成 Promise。
+	*/
+	async migrate() {
+		const latest = migrations.at(-1)?.version || 0;
+		if (latest !== 3) throw new Error(`消息缓存数据库迁移版本不一致: 常量 v${3}，迁移入口 v${latest}`);
+		const current = await this.getUserVersion();
+		if (current > 3) throw new Error(`消息缓存数据库版本过高: 当前 v${current}，适配器支持 v${3}`);
+		for (let version = current + 1; version <= 3; version++) {
+			const migration = migrations.find((item) => item.version === version);
+			if (!migration) throw new Error(`缺少消息缓存数据库迁移: v${version}`);
+			await this.transaction(() => migration.up({
+				run: (sql, params) => this.exec(sql, params),
+				tableColumns: (name) => this.tableColumns(name),
+				tableExists: (name) => this.tableExists(name),
+				markVacuum: () => {
+					this.shouldVacuum = true;
+				}
+			}));
+			await this.exec(`PRAGMA user_version = ${version}`);
+		}
+		if (this.shouldVacuum) {
+			await this.exec("VACUUM");
+			this.shouldVacuum = false;
+		}
+	}
+	/**
+	* 判断 SQLite 表是否存在。
+	*
+	* @param name 表名。
+	* @returns true 表示表存在。
+	*/
+	async tableExists(name) {
+		return !!await this.rawGet("SELECT 1 AS found FROM sqlite_master WHERE type = ? AND name = ?", ["table", name]);
+	}
+	/**
+	* 读取 SQLite 表字段名。
+	*
+	* @param name 表名。
+	* @returns 字段名数组；表不存在时返回空数组。
+	*/
+	async tableColumns(name) {
+		if (!await this.tableExists(name)) return [];
+		return (await this.rawAll(`PRAGMA table_info(${name})`)).map((row) => row.name);
+	}
+	/**
+	* 读取 SQLite schema 版本。
+	*
+	* @returns 当前 `PRAGMA user_version`；新库默认为 0。
+	*/
+	async getUserVersion() {
+		return (await this.rawGet("PRAGMA user_version"))?.user_version || 0;
+	}
+	/**
+	* 在 `BEGIN IMMEDIATE` 事务中执行写操作。
+	*
+	* @param fn 事务内执行的异步函数。
+	*/
+	async transaction(fn) {
+		await this.exec("BEGIN IMMEDIATE");
+		try {
+			await fn();
+			await this.exec("COMMIT");
+		} catch (err) {
+			await this.exec("ROLLBACK").catch(() => void 0);
+			throw err;
+		}
+	}
+	/**
+	* 获取当前数据库连接。
+	*
+	* @returns 已初始化的 sqlite3 Database。
+	*/
+	database() {
+		if (!this.db) throw new Error("消息缓存数据库尚未初始化");
+		return this.db;
+	}
+	/**
+	* 获取（并缓存）prepared statement。
+	*
+	* 热路径 SQL 只 parse 一次，重复执行只做参数绑定。
+	*
+	* @param sql SQL 字符串。
+	* @returns 复用的 Statement。
+	*/
+	prepared(sql) {
+		let stmt = this.statements.get(sql);
+		if (!stmt) {
+			stmt = this.database().prepare(sql);
+			this.statements.set(sql, stmt);
+		}
+		return stmt;
+	}
+	/**
+	* 以 prepared statement 执行不返回行的 SQL。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	*/
+	runS(sql, params = []) {
+		return new Promise((resolve, reject) => {
+			this.prepared(sql).run(params, (err) => err ? reject(err) : resolve());
+		});
+	}
+	/**
+	* 以 prepared statement 查询单行数据。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	* @returns 查询结果；未命中时返回 undefined。
+	*/
+	getS(sql, params = []) {
+		return new Promise((resolve, reject) => {
+			this.prepared(sql).get(params, (err, row) => err ? reject(err) : resolve(row));
+		});
+	}
+	/**
+	* 以 prepared statement 查询多行数据。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	* @returns 查询结果数组。
+	*/
+	allS(sql, params = []) {
+		return new Promise((resolve, reject) => {
+			this.prepared(sql).all(params, (err, rows) => err ? reject(err) : resolve(rows));
+		});
+	}
+	/**
+	* 执行一次性 SQL（DDL、PRAGMA、事务控制），不走 prepared statement 缓存。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	*/
+	exec(sql, params = []) {
+		return new Promise((resolve, reject) => {
+			this.database().run(sql, params, (err) => err ? reject(err) : resolve());
+		});
+	}
+	/**
+	* 一次性查询单行（PRAGMA / 系统表）。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	* @returns 查询结果；未命中时返回 undefined。
+	*/
+	rawGet(sql, params = []) {
+		return new Promise((resolve, reject) => {
+			this.database().get(sql, params, (err, row) => err ? reject(err) : resolve(row));
+		});
+	}
+	/**
+	* 一次性查询多行（PRAGMA / 系统表）。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	* @returns 查询结果数组。
+	*/
+	rawAll(sql, params = []) {
+		return new Promise((resolve, reject) => {
+			this.database().all(sql, params, (err, rows) => err ? reject(err) : resolve(rows));
+		});
+	}
+};
+
+//#endregion
+//#region src/core/storage/message-store/index.ts
+/** 单一 SQLite 连接：所有 bot 共用同一份缓存表与清理任务。 */
+let store;
+const getMessageStore = () => {
+	store ||= new MessageStore();
+	return store;
+};
+
+//#endregion
+export { getMessageStore as t };