@karinjs/adapter-qqbot 2.0.0 → 2.1.0

package/dist/message-O73AeL_P.js

@@ -0,0 +1,1739 @@
+import { c as log, s as pluginDirName } from "./config-DKa7596f.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 } 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
+/** QQ 官方不提供按消息 ID 查询历史消息；本地缓存保留一天。 */
+const MESSAGE_TTL = 1440 * 60 * 1e3;
+/** 空闲时也定期清理，避免长期运行的机器人积累过期记录。 */
+const CLEANUP_INTERVAL = 600 * 1e3;
+/** 待落库队列上限；超过后丢弃最旧的待写缓存，避免反向拖垮消息事件。 */
+const MAX_WRITE_QUEUE = 5e4;
+/** 媒体本地化待处理队列上限；超过后丢弃最旧任务，原消息仍保留短期 URL。 */
+const MAX_MEDIA_LOCALIZE_QUEUE = 5e4;
+/** 启动时最多补救的远程媒体消息数。 */
+const MEDIA_RECOVERY_LIMIT = 5e4;
+
+//#endregion
+//#region src/core/storage/message-store/sql.ts
+/**
+* 消息主表查询字段。
+*
+* 主表只保存整数外键，读取时再 JOIN 联系人和发送者映射表，避免在每条消息和每个
+* 消息段上重复写入 bot、群号、用户 ID 等长字符串。
+*/
+const messageSelectFields = () => `
+  m.id AS message_ref,
+  m.bot_ref,
+  m.contact_ref,
+  m.sender_ref,
+  b.bot_id,
+  m.message_id,
+  m.message_seq,
+  m.time,
+  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 SQL = {
+	insertBot: "INSERT INTO qqbot_bots (bot_id) VALUES (?) ON CONFLICT(bot_id) DO NOTHING",
+	selectBotId: "SELECT id FROM qqbot_bots WHERE bot_id = ?",
+	upsertContact: `INSERT INTO qqbot_contacts (bot_ref, scene, peer, sub_peer, name, sub_name)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(bot_ref, scene, peer, sub_peer) DO UPDATE SET
+      name = excluded.name,
+      sub_name = excluded.sub_name`,
+	selectContactId: `SELECT id FROM qqbot_contacts
+    WHERE bot_ref = ? AND scene = ? AND peer = ? AND sub_peer = ?`,
+	upsertSender: `INSERT INTO qqbot_senders (bot_ref, user_id, nick, name, role)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(bot_ref, user_id, nick, name, role) DO NOTHING`,
+	selectSenderId: `SELECT id FROM qqbot_senders
+    WHERE bot_ref = ? AND user_id = ? AND nick = ? AND name = ? AND role = ?`,
+	upsertMessage: `INSERT INTO qqbot_messages (
+    bot_ref, contact_ref, sender_ref, message_id, message_seq, time
+  ) VALUES (?, ?, ?, ?, ?, ?)
+  ON CONFLICT(bot_ref, contact_ref, message_id) DO UPDATE SET
+    sender_ref = excluded.sender_ref,
+    message_seq = excluded.message_seq,
+    time = excluded.time`,
+	selectMessageRef: `SELECT id FROM qqbot_messages
+    WHERE bot_ref = ? AND contact_ref = ? AND message_id = ?`,
+	deleteElements: "DELETE FROM qqbot_message_elements WHERE message_ref = ?",
+	insertElement: `INSERT INTO qqbot_message_elements (
+    message_ref, element_index, element_type, value
+  ) VALUES (?, ?, ?, ?)`,
+	insertAlias: `INSERT INTO qqbot_message_aliases (
+    bot_ref, contact_ref, alias_message_id, message_ref
+  ) VALUES (?, ?, ?, ?)
+  ON CONFLICT(bot_ref, contact_ref, alias_message_id) DO UPDATE SET
+    message_ref = excluded.message_ref`,
+	selectMessage: `SELECT ${messageSelectFields()}
+    FROM qqbot_messages m
+    JOIN qqbot_bots b ON b.id = m.bot_ref
+    JOIN qqbot_contacts c ON c.id = m.contact_ref
+    JOIN qqbot_senders s ON s.id = m.sender_ref
+    WHERE b.bot_id = ? AND c.scene = ? AND c.peer = ? AND c.sub_peer = ? AND m.message_id = ?`,
+	selectMessageById: `SELECT ${messageSelectFields()}
+    FROM qqbot_messages m
+    JOIN qqbot_bots b ON b.id = m.bot_ref
+    JOIN qqbot_contacts c ON c.id = m.contact_ref
+    JOIN qqbot_senders s ON s.id = m.sender_ref
+    WHERE b.bot_id = ? AND m.message_id = ?
+    LIMIT 1`,
+	selectMessageByRef: `SELECT ${messageSelectFields()}
+    FROM qqbot_messages m
+    JOIN qqbot_bots b ON b.id = m.bot_ref
+    JOIN qqbot_contacts c ON c.id = m.contact_ref
+    JOIN qqbot_senders s ON s.id = m.sender_ref
+    WHERE m.id = ?`,
+	selectHistory: `SELECT ${messageSelectFields()}
+    FROM qqbot_messages m
+    JOIN qqbot_bots b ON b.id = m.bot_ref
+    JOIN qqbot_contacts c ON c.id = m.contact_ref
+    JOIN qqbot_senders s ON s.id = m.sender_ref
+    WHERE b.bot_id = ? AND c.scene = ? AND c.peer = ? AND c.sub_peer = ?
+      AND (m.time < ? OR (m.time = ? AND m.id <= ?))
+    ORDER BY m.time DESC, m.id DESC
+    LIMIT ?`,
+	selectElements: `SELECT element_index, element_type, value
+    FROM qqbot_message_elements
+    WHERE message_ref = ?
+    ORDER BY element_index ASC`,
+	/** 查询仍保存远程 URL 的媒体消息，value 只匹配 URLSearchParams 编码后的 file 字段。 */
+	selectMessagesWithRemoteMedia: `SELECT DISTINCT ${messageSelectFields()}
+    FROM qqbot_messages m
+    JOIN qqbot_bots b ON b.id = m.bot_ref
+    JOIN qqbot_contacts c ON c.id = m.contact_ref
+    JOIN qqbot_senders s ON s.id = m.sender_ref
+    JOIN qqbot_message_elements e ON e.message_ref = m.id
+    WHERE m.time > ?
+      AND e.element_type IN ('image', 'video', 'record', 'file')
+      AND (
+        e.value LIKE 'file=http%3A%2F%2F%' OR e.value LIKE 'file=https%3A%2F%2F%'
+        OR e.value LIKE 'file=%2F%2F%'
+      )
+    ORDER BY m.time DESC, m.id DESC
+    LIMIT ?`,
+	selectAlias: `SELECT a.message_ref
+    FROM qqbot_message_aliases a
+    JOIN qqbot_bots b ON b.id = a.bot_ref
+    JOIN qqbot_contacts c ON c.id = a.contact_ref
+    WHERE b.bot_id = ? AND c.scene = ? AND c.peer = ? AND c.sub_peer = ? AND a.alias_message_id = ?`,
+	selectAliasById: `SELECT a.message_ref
+    FROM qqbot_message_aliases a
+    JOIN qqbot_bots b ON b.id = a.bot_ref
+    WHERE b.bot_id = ? AND a.alias_message_id = ?
+    LIMIT 1`,
+	deleteAlias: `DELETE FROM qqbot_message_aliases
+    WHERE bot_ref = (SELECT id FROM qqbot_bots WHERE bot_id = ?)
+      AND contact_ref = (
+        SELECT id FROM qqbot_contacts
+        WHERE bot_ref = (SELECT id FROM qqbot_bots WHERE bot_id = ?)
+          AND scene = ? AND peer = ? AND sub_peer = ?
+      )
+      AND alias_message_id = ?`,
+	/** 判断消息是否包含指定 reply 段，value 参数必须使用 elements.replyElementValue 编码。 */
+	hasReply: `SELECT 1 AS found FROM qqbot_message_elements
+    WHERE message_ref = ? AND element_type = 'reply' AND value = ?
+    LIMIT 1`,
+	cleanup: "DELETE FROM qqbot_messages WHERE time <= ?"
+};
+
+//#endregion
+//#region src/core/storage/message-store/elements.ts
+/** 接收侧当前会缓存的 Karin 消息段类型。 */
+const storableTypes = /* @__PURE__ */ new Set([
+	"text",
+	"at",
+	"reply",
+	"face",
+	"image",
+	"video",
+	"record",
+	"file",
+	"markdown"
+]);
+/**
+* 保存一个消息段。
+*
+* 只写 `element_type + value`，避免稀疏宽表产生大量 NULL，也避免每个消息段
+* 再额外写详情表。
+*
+* @param run SQL 执行函数，通常绑定到当前 MessageStore 的 SQLite 连接。
+* @param messageRef `qqbot_messages.id`，用于关联所属消息。
+* @param index 消息段在 Karin elements 中的原始顺序。
+* @param element 需要缓存的 Karin 消息段。
+*/
+const saveElement = async (run, messageRef, index, element) => {
+	const value = elementValue(element);
+	if (value === void 0) return;
+	await run(SQL.insertElement, [
+		messageRef,
+		index,
+		element.type,
+		value
+	]);
+};
+/**
+* 读取并还原消息段。
+*
+* @param getRows SQL 多行查询函数。
+* @param messageRef `qqbot_messages.id`，用于读取该消息的全部消息段。
+* @returns 按 `element_index` 排序后的 Karin 消息段数组。
+*/
+const loadElements = async (getRows, messageRef) => {
+	return (await getRows(SQL.selectElements, [messageRef])).flatMap(elementFromRow);
+};
+/**
+* 将数据库中的单 value 消息段还原为 Karin 消息段。
+*
+* @param row `qqbot_message_elements` 查询行。
+* @returns 可还原的 Karin 消息段；未知类型返回空数组。
+*/
+const elementFromRow = (row) => {
+	const value = new URLSearchParams(row.value);
+	switch (row.element_type) {
+		case "text": return [{
+			type: "text",
+			text: stringValue(value, "text")
+		}];
+		case "at": return [{
+			type: "at",
+			targetId: stringValue(value, "targetId")
+		}];
+		case "reply": return [{
+			type: "reply",
+			messageId: stringValue(value, "messageId")
+		}];
+		case "face": return [{
+			type: "face",
+			id: numberValue(value, "id") || 0
+		}];
+		case "image": return [{
+			type: "image",
+			file: stringValue(value, "file"),
+			subType: stringValue(value, "subType") || void 0,
+			width: numberValue(value, "width"),
+			height: numberValue(value, "height")
+		}];
+		case "video": return [{
+			type: "video",
+			file: stringValue(value, "file")
+		}];
+		case "record": return [{
+			type: "record",
+			file: stringValue(value, "file"),
+			magic: false
+		}];
+		case "file": return [{
+			type: "file",
+			file: stringValue(value, "file"),
+			name: stringValue(value, "name") || void 0
+		}];
+		case "markdown": return [{
+			type: "markdown",
+			markdown: stringValue(value, "markdown")
+		}];
+		default: return [];
+	}
+};
+/**
+* 提取并编码消息段缓存值。
+*
+* 数据库只保存 `element_type + value`，其中 value 统一为 URLSearchParams。每种消息段
+* 只保留 getMsg/getHistoryMsg 还原所需的最小字段。
+*
+* @param element Karin 消息段。
+* @returns URLSearchParams 编码后的最小字段；不支持缓存的类型返回 undefined。
+*/
+const elementValue = (element) => {
+	if (!storableTypes.has(element.type)) return void 0;
+	switch (element.type) {
+		case "text": return encodeElementValue({ text: element.text });
+		case "at": return encodeElementValue({ targetId: element.targetId });
+		case "reply": return replyElementValue(element.messageId);
+		case "face": return encodeElementValue({ id: element.id });
+		case "image": return encodeElementValue({
+			file: element.file,
+			subType: element.subType,
+			width: element.width,
+			height: element.height
+		});
+		case "video": return encodeElementValue({ file: element.file });
+		case "record": return encodeElementValue({ file: element.file });
+		case "file": return encodeElementValue({
+			file: element.file,
+			name: element.name
+		});
+		case "markdown": return encodeElementValue({ markdown: element.markdown });
+	}
+};
+/**
+* 编码 reply 段的数据库 value。
+*
+* `hasReply` 查询需要和写入时使用完全一致的 URLSearchParams 格式，单独导出这个
+* helper 可以避免查询侧再手写一份 `messageId=...`。
+*
+* @param messageId 被引用的消息 ID。
+* @returns 可直接写入或查询 `qqbot_message_elements.value` 的编码值。
+*/
+const replyElementValue = (messageId) => encodeElementValue({ messageId });
+/**
+* 将消息段字段编码成数据库 value。
+*
+* 所有消息段都统一使用 URLSearchParams，避免不同类型混用裸字符串和结构化值。空值
+* 不写入，减少缓存字段噪声。
+*
+* @param data 需要保留的最小消息段字段。
+* @returns URLSearchParams 编码后的 value。
+*/
+const encodeElementValue = (data) => {
+	const value = new URLSearchParams();
+	for (const [key, item] of Object.entries(data)) {
+		if (item === void 0 || item === null || item === "") continue;
+		value.set(key, String(item));
+	}
+	return value.toString();
+};
+/**
+* 从解析后的 value 中读取字符串字段。
+*
+* URLSearchParams 允许重复 key，这里固定取首个值，保证还原结果稳定。
+*
+* @param value 已解析的 value。
+* @param key 字段名。
+* @returns 字符串字段；不存在时返回空字符串。
+*/
+const stringValue = (value, key) => value.get(key) || "";
+/**
+* 从解析后的 value 中读取正数字段。
+*
+* 宽高、表情 ID 等数值字段只有大于 0 时才还原，避免把空值或异常值写回消息段。
+*
+* @param value 已解析的 value。
+* @param key 字段名。
+* @returns 正数值；不存在或非法时返回 undefined。
+*/
+const numberValue = (value, key) => {
+	const num = Number(stringValue(value, key));
+	return Number.isFinite(num) && num > 0 ? num : void 0;
+};
+
+//#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"
+};
+/** 常见 content-type 到本地文件扩展名的映射。 */
+const CONTENT_TYPE_EXTENSIONS = {
+	"image/jpeg": ".jpg",
+	"image/jpg": ".jpg",
+	"image/png": ".png",
+	"image/gif": ".gif",
+	"image/webp": ".webp",
+	"image/bmp": ".bmp",
+	"video/mp4": ".mp4",
+	"audio/mpeg": ".mp3",
+	"audio/mp3": ".mp3",
+	"audio/wav": ".wav",
+	"audio/x-wav": ".wav",
+	"audio/amr": ".amr"
+};
+/** 图片 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"
+};
+/** 上次清理本地媒体缓存的时间戳。 */
+let lastCleanup = 0;
+/**
+* 判断 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) => {
+	await cleanupMessageMediaCacheIfDue();
+	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 的本地媒体文件。
+*
+* @returns 清理完成 Promise。
+*/
+const cleanupMessageMediaCache = async () => {
+	lastCleanup = Date.now();
+	await cleanupDir(MEDIA_CACHE_DIR, Date.now() - MESSAGE_TTL);
+};
+/**
+* 到达清理间隔时清理本地媒体文件。
+*
+* @returns 清理完成 Promise；未到间隔时立即返回。
+*/
+const cleanupMessageMediaCacheIfDue = async () => {
+	if (Date.now() - lastCleanup < 6e5) return;
+	await cleanupMessageMediaCache();
+};
+/**
+* 缓存单个媒体消息段的远程文件。
+*
+* 图片会在下载后补充 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 });
+	const downloaded = await downloadRemoteFile({
+		url: source,
+		dir,
+		element,
+		maxBytes: MAX_CACHE_BYTES[element.type]
+	});
+	const result = {
+		...element,
+		file: downloaded.file
+	};
+	if (element.type === "image") {
+		const dimensions = await imageSizeFromFile(downloaded.file).catch(() => void 0);
+		return {
+			...result,
+			subType: downloaded.subType || 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.element 原始媒体消息段，用于命名和扩展名推断。
+* @param params.maxBytes 当前类型允许的最大下载体积。
+* @returns 下载后的本地文件路径和格式信息。
+*/
+const downloadRemoteFile = async (params) => {
+	const { url, dir, 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));
+		const filename = getLocalFilename(element, url, contentType);
+		const finalFile = join(dir, filename);
+		const now = /* @__PURE__ */ new Date();
+		if (await stat(finalFile).then(() => true).catch(() => false)) {
+			await rm(tempFile, { force: true }).catch(() => void 0);
+			await utimes(finalFile, now, now).catch(() => void 0);
+		} else await rename(tempFile, finalFile);
+		return {
+			file: finalFile,
+			contentType,
+			subType: element.type === "image" ? extensionToSubType(extname(filename)) : void 0
+		};
+	} 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);
+	}));
+};
+/**
+* 生成本地缓存文件名。
+*
+* 文件名使用原始 name 的主文件名加 UUID，既保留可读性，也避免同名文件冲突。
+*
+* @param element 媒体消息段。
+* @param source 远程 URL。
+* @param contentType 响应 content-type。
+* @returns 不含目录的本地文件名。
+*/
+const getLocalFilename = (element, source, contentType) => {
+	const ext = getFileExtension(element, source, contentType);
+	return `${getFileBaseName(element) || element.type}-${crypto.randomUUID()}${ext}`;
+};
+/**
+* 推断本地缓存文件扩展名。
+*
+* 优先级：
+* 1. 图片 subType；
+* 2. 文件消息段自带 name 后缀；
+* 3. 语音固定 .mp3；
+* 4. content-type、name、URL 后缀；
+* 5. 类型默认扩展名。
+*
+* @param element 媒体消息段。
+* @param source 远程 URL。
+* @param contentType 响应 content-type。
+* @returns 带点号的扩展名。
+*/
+const getFileExtension = (element, source, contentType) => {
+	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 byType = CONTENT_TYPE_EXTENSIONS[contentType];
+	if (byType) return byType;
+	const byName = normalizeExtension(extname(element.name || ""));
+	if (byName) return byName;
+	return normalizeExtension(extname(new URL(source).pathname)) || EXTENSIONS_BY_TYPE[element.type];
+};
+/**
+* 规范化并校验扩展名。
+*
+* 只允许短的字母数字扩展名，避免 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;
+};
+/**
+* 获取用于本地文件名的主文件名。
+*
+* 只有 file 消息段通常会带业务文件名；其他媒体没有 name 时由类型名兜底。
+*
+* @param element 媒体消息段。
+* @returns 已清理的主文件名，不包含扩展名。
+*/
+const getFileBaseName = (element) => {
+	const raw = element.name || "";
+	return sanitizeFilename(raw ? raw.slice(0, raw.length - extname(raw).length) : "");
+};
+/**
+* 清理文件名中的危险字符。
+*
+* @param name 原始文件名。
+* @returns 可安全拼接到本地路径中的文件名片段。
+*/
+const sanitizeFilename = (name) => {
+	return name.split("").map((char) => isUnsafeFilenameChar(char) ? "_" : char).join("").replace(/\s+/g, " ").trim().slice(0, 80);
+};
+/**
+* 判断字符是否不适合出现在 Windows/Unix 文件名中。
+*
+* @param char 单个字符。
+* @returns true 表示需要替换。
+*/
+const isUnsafeFilenameChar = (char) => {
+	return char.charCodeAt(0) < 32 || "<>:\"/\\|?*".includes(char);
+};
+/**
+* 将图片扩展名转换为 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/schema.ts
+const LEGACY_DETAIL_TABLES = [
+	"qqbot_element_text",
+	"qqbot_element_at",
+	"qqbot_element_reply",
+	"qqbot_element_face",
+	"qqbot_element_media",
+	"qqbot_element_markdown"
+];
+/**
+* 判断当前数据库是否已经是 v1 首发基线结构。
+*
+* @param tableColumns 读取指定表字段名的函数。
+* @param tableExists 判断指定表是否存在的函数。
+* @returns true 表示当前表结构可直接使用；false 表示需要重建缓存表。
+*/
+const isCurrentSchema = async (tableColumns, tableExists) => {
+	const columns = await tableColumns("qqbot_messages");
+	if (!columns.includes("contact_ref")) return false;
+	if (columns.includes("expires_at")) return false;
+	if (!(await tableColumns("qqbot_message_elements")).includes("value")) return false;
+	if (!await tableExists("qqbot_bots")) return false;
+	if (!await tableExists("qqbot_contacts")) return false;
+	if (!await tableExists("qqbot_senders")) return false;
+	if (!await tableExists("qqbot_message_elements")) return false;
+	if (!await tableExists("qqbot_message_aliases")) return false;
+	return true;
+};
+/**
+* 删除所有开发阶段旧缓存表。
+*
+* @param run SQL 执行函数。
+*/
+const dropSchema = async (run) => {
+	await run("DROP TABLE IF EXISTS qqbot_message_aliases");
+	for (const table of LEGACY_DETAIL_TABLES) await run(`DROP TABLE IF EXISTS ${table}`);
+	await run("DROP TABLE IF EXISTS qqbot_message_elements");
+	await run("DROP TABLE IF EXISTS qqbot_messages");
+	await run("DROP TABLE IF EXISTS qqbot_senders");
+	await run("DROP TABLE IF EXISTS qqbot_contacts");
+	await run("DROP TABLE IF EXISTS qqbot_bots");
+	await run("DROP TABLE IF EXISTS qqbot_message_alias");
+	await run("DROP TABLE IF EXISTS qqbot_message_cache");
+};
+/**
+* 创建 v1 首发基线表结构。
+*
+* @param run SQL 执行函数。
+*/
+const createSchema = async (run) => {
+	await run(`CREATE TABLE qqbot_bots (
+    id INTEGER PRIMARY KEY,
+    bot_id TEXT NOT NULL UNIQUE
+  )`);
+	await run(`CREATE TABLE qqbot_contacts (
+    id INTEGER PRIMARY KEY,
+    bot_ref INTEGER 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_ref, scene, peer, sub_peer),
+    FOREIGN KEY (bot_ref) REFERENCES qqbot_bots(id) ON DELETE CASCADE
+  )`);
+	await run(`CREATE TABLE qqbot_senders (
+    id INTEGER PRIMARY KEY,
+    bot_ref INTEGER 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_ref, user_id, nick, name, role),
+    FOREIGN KEY (bot_ref) REFERENCES qqbot_bots(id) ON DELETE CASCADE
+  )`);
+	await run(`CREATE TABLE qqbot_messages (
+    id INTEGER PRIMARY KEY,
+    bot_ref INTEGER NOT NULL,
+    contact_ref INTEGER NOT NULL,
+    sender_ref INTEGER NOT NULL,
+    message_id TEXT NOT NULL,
+    message_seq INTEGER NOT NULL DEFAULT 0,
+    time INTEGER NOT NULL,
+    UNIQUE(bot_ref, contact_ref, message_id),
+    FOREIGN KEY (bot_ref) REFERENCES qqbot_bots(id) ON DELETE CASCADE,
+    FOREIGN KEY (contact_ref) REFERENCES qqbot_contacts(id) ON DELETE CASCADE,
+    FOREIGN KEY (sender_ref) REFERENCES qqbot_senders(id) ON DELETE RESTRICT
+  )`);
+	await run(`CREATE TABLE qqbot_message_elements (
+    message_ref INTEGER NOT NULL,
+    element_index INTEGER NOT NULL,
+    element_type TEXT NOT NULL,
+    value TEXT NOT NULL,
+    PRIMARY KEY (message_ref, element_index),
+    FOREIGN KEY (message_ref) REFERENCES qqbot_messages(id) ON DELETE CASCADE
+  ) WITHOUT ROWID`);
+	await run(`CREATE TABLE qqbot_message_aliases (
+    bot_ref INTEGER NOT NULL,
+    contact_ref INTEGER NOT NULL,
+    alias_message_id TEXT NOT NULL,
+    message_ref INTEGER NOT NULL,
+    PRIMARY KEY (bot_ref, contact_ref, alias_message_id),
+    FOREIGN KEY (bot_ref) REFERENCES qqbot_bots(id) ON DELETE CASCADE,
+    FOREIGN KEY (contact_ref) REFERENCES qqbot_contacts(id) ON DELETE CASCADE,
+    FOREIGN KEY (message_ref) REFERENCES qqbot_messages(id) ON DELETE CASCADE
+  ) WITHOUT ROWID`);
+	await run("CREATE INDEX idx_qqbot_contacts_lookup ON qqbot_contacts(bot_ref, scene, peer, sub_peer)");
+	await run("CREATE INDEX idx_qqbot_messages_lookup ON qqbot_messages(bot_ref, message_id)");
+	await run("CREATE INDEX idx_qqbot_messages_time ON qqbot_messages(time)");
+	await run("CREATE INDEX idx_qqbot_message_aliases_id ON qqbot_message_aliases(bot_ref, alias_message_id)");
+};
+
+//#endregion
+//#region src/core/storage/message-store/migrations.ts
+/**
+* 消息缓存数据库迁移入口。
+*
+* 后续改表时只需要在数组末尾追加对象，例如：
+*
+* ```ts
+* {
+*   version: 2,
+*   description: '给 qqbot_messages 增加 xxx 字段',
+*   up: async ({ run }) => {
+*     await run('ALTER TABLE qqbot_messages ADD COLUMN xxx TEXT')
+*   },
+* }
+* ```
+*/
+const migrations = [{
+	version: 1,
+	description: "首个 alpha 发布基线：消息主表、单 value 消息段表和 alias 表",
+	up: async ({ run, tableColumns, tableExists, markVacuum }) => {
+		if (await isCurrentSchema(tableColumns, tableExists)) return;
+		await dropSchema(run);
+		markVacuum();
+		await createSchema(run);
+	}
+}];
+
+//#endregion
+//#region src/core/storage/message-store/store.ts
+/**
+* QQBot 收到的消息缓存。
+*
+* 热路径只写内存并入队，不等待 SQLite：
+* - `getMsg` 优先查内存，插件在同一事件回调内可立即命中；
+* - SQLite 在后台按批次事务落库，避免一条消息一个事务拖慢事件分发；
+* - 元素表只保存 `type + value`，避免宽表 NULL 和多详情表多次 INSERT。
+*/
+var MessageStore = class {
+	db;
+	ready;
+	lastCleanup = 0;
+	shouldVacuum = false;
+	flushTimer;
+	flushing = false;
+	mediaTimer;
+	mediaActive = 0;
+	pending = [];
+	pendingMedia = [];
+	pendingMediaKeys = /* @__PURE__ */ new Set();
+	memory = /* @__PURE__ */ new Map();
+	directIndex = /* @__PURE__ */ new Map();
+	aliasIndex = /* @__PURE__ */ new Map();
+	scopedAliasIndex = /* @__PURE__ */ new Map();
+	botRefCache = /* @__PURE__ */ new Map();
+	contactRefCache = /* @__PURE__ */ new Map();
+	senderRefCache = /* @__PURE__ */ new Map();
+	constructor() {
+		this.ready = this.initialize();
+	}
+	/**
+	* 立即执行一次过期消息和本地媒体缓存清理。
+	*
+	* 该方法交给 Karin `task` 调度调用；类内部只保留清理能力，不自行维护常驻定时器。
+	*
+	* @returns 清理完成 Promise。
+	*/
+	async cleanupExpired() {
+		await this.ready;
+		await this.cleanup();
+	}
+	/**
+	* 保存实际消息，并为 QQ 的 `msg_idx` 等引用索引建立轻量映射。
+	*
+	* 该方法只同步写入内存并投递后台队列，不等待 SQLite。这样消息事件创建不会被
+	* 数据库写锁或小事务阻塞。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param message 已转换为 Karin elements 的消息缓存。
+	* @param aliases 可查询到该消息的额外消息索引，例如 QQ `msg_idx`。
+	*/
+	async save(botId, message, aliases = []) {
+		if (!message.messageId) return;
+		this.cleanupMemoryIfDue();
+		const cached = this.cloneMessage(message);
+		this.putMemory(botId, cached, aliases);
+		this.enqueue({
+			botId,
+			message: cached,
+			aliases,
+			referenceOnly: false
+		});
+		this.enqueueMediaLocalize(botId, cached, aliases);
+	}
+	/**
+	* 仅当内存中没有该引用索引时保存 QQ 下发的引用上下文。
+	* 数据库是否已存在由后台 flush 再判断，避免阻塞事件热路径。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param message 以 `ref_msg_idx` 作为 messageId 的引用上下文。
+	*/
+	async saveReferenceIfAbsent(botId, message) {
+		if (!message.messageId) return;
+		this.cleanupMemoryIfDue();
+		if (this.getFromMemory(botId, message.messageId, message.contact)) return;
+		const cached = this.cloneMessage(message);
+		this.putMemory(botId, cached);
+		this.enqueue({
+			botId,
+			message: cached,
+			aliases: [],
+			referenceOnly: true
+		});
+		this.enqueueMediaLocalize(botId, cached, []);
+	}
+	/**
+	* 读取缓存消息。
+	*
+	* 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;
+		const memory = this.getFromMemory(botId, messageId, contact);
+		if (memory) return this.toResponse(memory);
+		await this.ready;
+		await this.cleanupIfDue();
+		const key = contact ? this.contactKey(botId, contact, messageId) : [botId, messageId];
+		const direct = await this.getRow(contact ? SQL.selectMessage : SQL.selectMessageById, key);
+		const alias = direct ? void 0 : await this.getRow(contact ? SQL.selectAlias : SQL.selectAliasById, key);
+		if (!direct && !alias) return null;
+		const row = direct || await this.getRow(SQL.selectMessageByRef, [alias.message_ref]);
+		if (!row) return null;
+		if (!direct && await this.hasReplyTo(row.message_ref, messageId)) {
+			/** 拒绝旧缓存中错误指向当前引用消息的别名。 */
+			await this.deleteAlias(botId, this.contactFromRow(row), messageId);
+			return null;
+		}
+		if (this.isExpired(row)) {
+			await this.cleanup();
+			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.cleanupIfDue();
+		await this.flushQueue();
+		const anchor = await this.resolveMessageRow(botId, contact, startMsgId);
+		if (!anchor) return [];
+		if (this.isExpired(anchor)) {
+			await this.cleanup();
+			return [];
+		}
+		const rows = await this.getRows(SQL.selectHistory, [
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			anchor.time,
+			anchor.time,
+			anchor.message_ref,
+			limit
+		]);
+		return Promise.all(rows.map((row) => this.rowToResponse(row)));
+	}
+	/**
+	* 初始化 SQLite 连接、表结构，并执行启动清理和媒体本地化补救。
+	*
+	* @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.run("PRAGMA foreign_keys = ON");
+		await this.run("PRAGMA journal_mode = WAL");
+		await this.run("PRAGMA synchronous = NORMAL");
+		await this.run("PRAGMA temp_store = MEMORY");
+		await this.run("PRAGMA busy_timeout = 5000");
+		await this.migrate();
+		await this.cleanup();
+		await this.recoverRemoteMedia();
+	}
+	/**
+	* 投递待落库消息。
+	*
+	* @param item 待写入 SQLite 的缓存任务。
+	*/
+	enqueue(item) {
+		this.pending.push(item);
+		if (this.pending.length > 5e4) {
+			this.prunePending();
+			if (this.pending.length > 5e4) log("warn", `[getMsg] SQLite 写入队列过长，已丢弃 ${this.pending.splice(0, this.pending.length - MAX_WRITE_QUEUE).length} 条最旧待写缓存`);
+		}
+		this.scheduleFlush();
+	}
+	/**
+	* 安排一次后台批量落库。
+	*
+	* 已有 timer 或正在 flush 时不会重复安排。
+	*/
+	scheduleFlush() {
+		if (this.flushTimer || this.flushing) return;
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = void 0;
+			this.flushQueue().catch((err) => log("warn", "[getMsg] 批量写入消息缓存失败", err));
+		}, 100);
+		this.flushTimer.unref();
+	}
+	/**
+	* 批量落库队列中的消息。
+	*
+	* 单次最多处理 `FLUSH_BATCH_SIZE` 条，并在一个事务内完成写入。
+	*
+	* @returns flush 完成 Promise。
+	*/
+	async flushQueue() {
+		if (this.flushing) return;
+		this.flushing = true;
+		try {
+			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;
+					await this.writeItem(item);
+				}
+			});
+			if (this.pending.length) this.scheduleFlush();
+		} finally {
+			this.flushing = false;
+			if (this.pending.length) this.scheduleFlush();
+		}
+	}
+	/**
+	* 写入一条待落库消息。
+	*
+	* @param item 待写入的消息、alias 和引用上下文标记。
+	*/
+	async writeItem(item) {
+		const botRef = await this.ensureBot(item.botId);
+		const contactRef = await this.ensureContact(botRef, item.message.contact);
+		if (item.referenceOnly) {
+			if (await this.getRow(SQL.selectMessageRef, [
+				botRef,
+				contactRef,
+				item.message.messageId
+			])) return;
+			/** 原消息已通过 msg_idx alias 缓存时，不再把引用上下文另存为一条消息。 */
+			if (await this.getRow(SQL.selectAlias, this.contactKey(item.botId, item.message.contact, item.message.messageId))) return;
+		}
+		const senderRef = await this.ensureSender(botRef, item.message.sender);
+		const messageRef = await this.ensureMessage(botRef, contactRef, senderRef, item.message);
+		await this.run(SQL.deleteElements, [messageRef]);
+		for (const [index, element] of item.message.elements.entries()) await saveElement((sql, params) => this.run(sql, params), messageRef, index, element);
+		for (const alias of new Set(item.aliases.filter((id) => id && id !== item.message.messageId))) await this.run(SQL.insertAlias, [
+			botRef,
+			contactRef,
+			alias,
+			messageRef
+		]);
+	}
+	/**
+	* 清理待写队列中已经过期的消息。
+	*/
+	prunePending() {
+		const deadline = Date.now() - MESSAGE_TTL;
+		for (let index = this.pending.length - 1; index >= 0; index--) if (this.pending[index].message.time <= deadline) this.pending.splice(index, 1);
+	}
+	/**
+	* 投递媒体本地化任务。
+	*
+	* 原消息会先保留短期 URL 写入缓存；本地化成功后再覆盖同一条消息。队列会按
+	* message scoped key 去重，避免高频更新同一条消息时重复下载。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param message 可能包含远程媒体 URL 的消息快照。
+	* @param aliases 该消息可被查询到的额外 alias。
+	*/
+	enqueueMediaLocalize(botId, message, aliases) {
+		if (!hasRemoteFileElement(message.elements)) return;
+		if (this.isExpired(message)) return;
+		const key = this.scopedKey(botId, message.contact, message.messageId);
+		if (this.pendingMediaKeys.has(key)) return;
+		const item = {
+			botId,
+			message: this.cloneMessage(message),
+			aliases,
+			key
+		};
+		this.pendingMedia.push(item);
+		this.pendingMediaKeys.add(key);
+		if (this.pendingMedia.length > 5e4) {
+			this.prunePendingMedia();
+			if (this.pendingMedia.length > 5e4) {
+				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.putMemory(item.botId, localized, item.aliases);
+		this.enqueue({
+			botId: item.botId,
+			message: localized,
+			aliases: item.aliases,
+			referenceOnly: false
+		});
+	}
+	/**
+	* 清理已经过期的媒体本地化待处理任务。
+	*
+	* @returns 无返回值；会同步维护 pendingMediaKeys。
+	*/
+	prunePendingMedia() {
+		const deadline = Date.now() - MESSAGE_TTL;
+		for (let index = this.pendingMedia.length - 1; index >= 0; index--) {
+			const item = this.pendingMedia[index];
+			if (item.message.time > deadline) continue;
+			this.pendingMedia.splice(index, 1);
+			this.pendingMediaKeys.delete(item.key);
+		}
+	}
+	/**
+	* 启动时扫描 SQLite 中尚未本地化的远程媒体 URL，并重新投递队列补救。
+	*
+	* @returns 扫描和投递完成 Promise。
+	*/
+	async recoverRemoteMedia() {
+		const rows = await this.getRows(SQL.selectMessagesWithRemoteMedia, [Date.now() - MESSAGE_TTL, MEDIA_RECOVERY_LIMIT]);
+		if (!rows.length) return;
+		for (const row of rows) {
+			const response = await 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
+			}, []);
+		}
+		log("debug", `[getMsg] 已投递 ${rows.length} 条远程媒体缓存补救任务`);
+	}
+	/**
+	* 写入内存热缓存。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param message 消息缓存。
+	* @param aliases 可查询到该消息的额外消息索引。
+	*/
+	putMemory(botId, message, aliases = []) {
+		const scoped = this.scopedKey(botId, message.contact, message.messageId);
+		this.memory.set(scoped, message);
+		this.directIndex.set(this.globalKey(botId, message.messageId), scoped);
+		for (const alias of new Set(aliases.filter((id) => id && id !== message.messageId))) {
+			this.scopedAliasIndex.set(this.scopedKey(botId, message.contact, alias), scoped);
+			this.aliasIndex.set(this.globalKey(botId, alias), scoped);
+		}
+	}
+	/**
+	* 从内存热缓存读取消息。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param messageId 真实消息 ID 或 alias。
+	* @param contact 可选会话范围。
+	* @returns 命中的缓存消息；未命中或过期时返回 null。
+	*/
+	getFromMemory(botId, messageId, contact) {
+		const scoped = contact ? this.scopedKey(botId, contact, messageId) : this.directIndex.get(this.globalKey(botId, messageId));
+		const alias = contact ? this.scopedAliasIndex.get(this.scopedKey(botId, contact, messageId)) : this.aliasIndex.get(this.globalKey(botId, messageId));
+		const key = scoped && this.memory.has(scoped) ? scoped : alias;
+		if (!key) return null;
+		const message = this.memory.get(key);
+		if (!message) return null;
+		if (!this.isExpired(message)) return message;
+		this.cleanupMemory();
+		return null;
+	}
+	/**
+	* 到达清理间隔时清理内存缓存。
+	*/
+	cleanupMemoryIfDue() {
+		if (Date.now() - this.lastCleanup < 6e5) return;
+		this.cleanupMemory();
+	}
+	/**
+	* 清理一天前的内存消息，并同步清理失效索引。
+	*/
+	cleanupMemory() {
+		const deadline = Date.now() - MESSAGE_TTL;
+		for (const [key, message] of this.memory) if (message.time <= deadline) this.memory.delete(key);
+		this.cleanIndex(this.directIndex);
+		this.cleanIndex(this.aliasIndex);
+		this.cleanIndex(this.scopedAliasIndex);
+	}
+	/**
+	* 清理指向已删除内存消息的索引。
+	*
+	* @param index 需要清理的索引 Map。
+	*/
+	cleanIndex(index) {
+		for (const [key, scoped] of index) if (!this.memory.has(scoped)) index.delete(key);
+	}
+	/**
+	* 浅拷贝消息缓存，避免后续事件对象被插件侧修改后污染缓存。
+	*
+	* @param message 原始缓存消息。
+	* @returns 可安全放入缓存的消息副本。
+	*/
+	cloneMessage(message) {
+		return {
+			...message,
+			contact: { ...message.contact },
+			sender: { ...message.sender },
+			elements: message.elements.map((element) => ({ ...element }))
+		};
+	}
+	/**
+	* 将内存缓存转换为 Karin `MessageResponse`。
+	*
+	* @param message 内存缓存消息。
+	* @returns Karin 标准消息查询结果。
+	*/
+	toResponse(message) {
+		return {
+			messageId: message.messageId,
+			messageSeq: message.messageSeq,
+			time: message.time,
+			contact: { ...message.contact },
+			sender: { ...message.sender },
+			elements: message.elements.map((element) => ({ ...element }))
+		};
+	}
+	/**
+	* 执行数据库版本迁移。
+	*
+	* 使用 SQLite `PRAGMA user_version` 记录已应用的 schema 版本。
+	* 版本 0 只表示“未初始化或开发期旧库”，首个 alpha 发布基线为 v1。
+	*
+	* @returns 迁移完成 Promise。
+	*/
+	async migrate() {
+		const latest = migrations.at(-1)?.version || 0;
+		if (latest !== 1) throw new Error(`消息缓存数据库迁移版本不一致: 常量 v${1}，迁移入口 v${latest}`);
+		const current = await this.getUserVersion();
+		if (current > 1) throw new Error(`消息缓存数据库版本过高: 当前 v${current}，适配器支持 v${1}`);
+		for (let version = current + 1; version <= 1; 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.run(sql, params),
+				tableColumns: (name) => this.tableColumns(name),
+				tableExists: (name) => this.tableExists(name),
+				markVacuum: () => {
+					this.shouldVacuum = true;
+				}
+			}));
+			await this.setUserVersion(version);
+		}
+		if (this.shouldVacuum) {
+			await this.run("VACUUM");
+			this.shouldVacuum = false;
+		}
+	}
+	/**
+	* 获取或创建 bot 映射 ID。
+	*
+	* @param botId 当前 QQBot appId。
+	* @returns `qqbot_bots.id`。
+	*/
+	async ensureBot(botId) {
+		const cached = this.botRefCache.get(botId);
+		if (cached) return cached;
+		await this.run(SQL.insertBot, [botId]);
+		const row = await this.getRow(SQL.selectBotId, [botId]);
+		if (!row) throw new Error(`消息缓存 bot 映射写入失败: ${botId}`);
+		this.botRefCache.set(botId, row.id);
+		return row.id;
+	}
+	/**
+	* 获取或创建会话映射 ID。
+	*
+	* @param botRef `qqbot_bots.id`。
+	* @param contact Karin 会话对象。
+	* @returns `qqbot_contacts.id`。
+	*/
+	async ensureContact(botRef, contact) {
+		const key = [
+			botRef,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || ""
+		].join("");
+		const cached = this.contactRefCache.get(key);
+		if (cached) return cached;
+		const values = [
+			botRef,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			contact.name || "",
+			contact.subName || ""
+		];
+		await this.run(SQL.upsertContact, values);
+		const row = await this.getRow(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。
+	*
+	* @param botRef `qqbot_bots.id`。
+	* @param sender Karin sender 对象。
+	* @returns `qqbot_senders.id`。
+	*/
+	async ensureSender(botRef, sender) {
+		const role = sender.role || "member";
+		const values = [
+			botRef,
+			sender.userId || "",
+			sender.nick || "",
+			sender.name || "",
+			role
+		];
+		const key = values.join("");
+		const cached = this.senderRefCache.get(key);
+		if (cached) return cached;
+		await this.run(SQL.upsertSender, values);
+		const row = await this.getRow(SQL.selectSenderId, values);
+		if (!row) throw new Error(`消息缓存发送者映射写入失败: ${sender.userId || ""}`);
+		this.senderRefCache.set(key, row.id);
+		return row.id;
+	}
+	/**
+	* 获取或创建消息主记录。
+	*
+	* @param botRef `qqbot_bots.id`。
+	* @param contactRef `qqbot_contacts.id`。
+	* @param senderRef `qqbot_senders.id`。
+	* @param message 消息缓存。
+	* @returns `qqbot_messages.id`。
+	*/
+	async ensureMessage(botRef, contactRef, senderRef, message) {
+		await this.run(SQL.upsertMessage, [
+			botRef,
+			contactRef,
+			senderRef,
+			message.messageId,
+			message.messageSeq,
+			message.time
+		]);
+		const row = await this.getRow(SQL.selectMessageRef, [
+			botRef,
+			contactRef,
+			message.messageId
+		]);
+		if (!row) throw new Error(`消息缓存主记录写入失败: ${message.messageId}`);
+		return row.id;
+	}
+	/**
+	* 从查询行还原 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
+			};
+		}
+	}
+	/**
+	* 将数据库行还原为 Karin `MessageResponse`。
+	*
+	* @param row 消息主查询结果。
+	* @returns Karin 标准消息查询结果。
+	*/
+	async rowToResponse(row) {
+		return {
+			messageId: row.message_id,
+			messageSeq: row.message_seq,
+			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: await loadElements((sql, params) => this.getRows(sql, params), row.message_ref)
+		};
+	}
+	/**
+	* 在指定会话中解析消息 ID 或 alias 到消息主表行。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact Karin 会话对象。
+	* @param messageId 真实消息 ID 或 alias。
+	* @returns 命中的消息行；未命中时返回 null。
+	*/
+	async resolveMessageRow(botId, contact, messageId) {
+		const key = this.contactKey(botId, contact, messageId);
+		const direct = await this.getRow(SQL.selectMessage, key);
+		const alias = direct ? void 0 : await this.getRow(SQL.selectAlias, key);
+		if (!direct && !alias) return null;
+		const row = direct || await this.getRow(SQL.selectMessageByRef, [alias.message_ref]);
+		if (!row) return null;
+		if (!direct && await this.hasReplyTo(row.message_ref, messageId)) {
+			await this.deleteAlias(botId, this.contactFromRow(row), messageId);
+			return null;
+		}
+		return row;
+	}
+	/**
+	* 构造会话级查询键。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact Karin 会话对象。
+	* @param messageId 消息 ID 或 alias。
+	* @returns 用于 SQL 参数或内存 key 的字段数组。
+	*/
+	contactKey(botId, contact, messageId) {
+		return [
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			messageId
+		];
+	}
+	/**
+	* 构造内存会话级 key。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact Karin 会话对象。
+	* @param messageId 消息 ID 或 alias。
+	* @returns 内存 Map 使用的稳定 key。
+	*/
+	scopedKey(botId, contact, messageId) {
+		return this.contactKey(botId, contact, messageId).join("");
+	}
+	/**
+	* 构造内存全局 key。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param messageId 消息 ID 或 alias。
+	* @returns 不限定会话时使用的内存 key。
+	*/
+	globalKey(botId, messageId) {
+		return `${botId}\x1f${messageId}`;
+	}
+	/**
+	* 删除指定会话下的 alias。
+	*
+	* @param botId 当前 QQBot appId。
+	* @param contact Karin 会话对象。
+	* @param messageId 需要删除的 alias ID。
+	*/
+	async deleteAlias(botId, contact, messageId) {
+		await this.run(SQL.deleteAlias, [
+			botId,
+			botId,
+			contact.scene,
+			contact.peer,
+			contact.subPeer || "",
+			messageId
+		]);
+	}
+	/**
+	* 判断某条消息是否包含指向指定 ID 的 reply 段。
+	*
+	* @param messageRef `qqbot_messages.id`。
+	* @param replyId 被引用的消息 ID。
+	* @returns true 表示该消息包含对应 reply 段。
+	*/
+	async hasReplyTo(messageRef, replyId) {
+		return !!await this.getRow(SQL.hasReply, [messageRef, replyElementValue(replyId)]);
+	}
+	/**
+	* 判断消息是否已经超过本地缓存 TTL。
+	*
+	* @param row 带 `time` 字段的消息对象。
+	* @returns true 表示已经超过一天缓存窗口。
+	*/
+	isExpired(row) {
+		return row.time <= Date.now() - MESSAGE_TTL;
+	}
+	/**
+	* 到达清理间隔时清理内存和 SQLite 过期消息。
+	*/
+	async cleanupIfDue() {
+		if (Date.now() - this.lastCleanup < 6e5) return;
+		await this.cleanup();
+	}
+	/**
+	* 清理一天前的缓存消息。
+	*
+	* SQLite 只删除主消息表，消息段和 alias 通过外键级联删除。
+	*/
+	async cleanup() {
+		this.cleanupMemory();
+		await this.run(SQL.cleanup, [Date.now() - MESSAGE_TTL]);
+		await cleanupMessageMediaCache();
+		this.lastCleanup = Date.now();
+	}
+	/**
+	* 判断 SQLite 表是否存在。
+	*
+	* @param name 表名。
+	* @returns true 表示表存在。
+	*/
+	async tableExists(name) {
+		return !!await this.getRow("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.getRows(`PRAGMA table_info(${name})`)).map((row) => row.name);
+	}
+	/**
+	* 读取 SQLite schema 版本。
+	*
+	* @returns 当前 `PRAGMA user_version`；新库默认为 0。
+	*/
+	async getUserVersion() {
+		return (await this.getRow("PRAGMA user_version"))?.user_version || 0;
+	}
+	/**
+	* 写入 SQLite schema 版本。
+	*
+	* @param version 已成功应用的数据库版本号。
+	*/
+	async setUserVersion(version) {
+		await this.run(`PRAGMA user_version = ${version}`);
+	}
+	/**
+	* 在 `BEGIN IMMEDIATE` 事务中执行写操作。
+	*
+	* @param fn 事务内执行的异步函数。
+	*/
+	async transaction(fn) {
+		await this.run("BEGIN IMMEDIATE");
+		try {
+			await fn();
+			await this.run("COMMIT");
+		} catch (err) {
+			await this.run("ROLLBACK").catch(() => void 0);
+			throw err;
+		}
+	}
+	/**
+	* 执行不返回行的 SQL。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	*/
+	async run(sql, params = []) {
+		const db = this.db;
+		if (!db) throw new Error("消息缓存数据库尚未初始化");
+		await new Promise((resolve, reject) => {
+			db.run(sql, params, (err) => err ? reject(err) : resolve());
+		});
+	}
+	/**
+	* 查询单行数据。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	* @returns 查询结果；未命中时返回 undefined。
+	*/
+	async getRow(sql, params = []) {
+		const db = this.db;
+		if (!db) throw new Error("消息缓存数据库尚未初始化");
+		return new Promise((resolve, reject) => {
+			db.get(sql, params, (err, row) => err ? reject(err) : resolve(row));
+		});
+	}
+	/**
+	* 查询多行数据。
+	*
+	* @param sql SQL 字符串。
+	* @param params SQL 参数。
+	* @returns 查询结果数组。
+	*/
+	async getRows(sql, params = []) {
+		const db = this.db;
+		if (!db) throw new Error("消息缓存数据库尚未初始化");
+		return new Promise((resolve, reject) => {
+			db.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 };