@karinjs/adapter-qqbot 2.0.0 → 2.1.0

package/dist/index.js

@@ -1,13 +1,20 @@
-import { a as pkg, c as getImageSize, f as log, l as handleUrl, n as config, p as basename, r as getConfig, s as fakeEvent, t as bindHandlers, u as random } from "./config-H7LrvlNU.js";
-import "./utils-DO4gEkVN.js";
-import { t as needQrOnboard } from "./onboard-BX8g8Wik.js";
-import { AdapterBase, app, buttonHandle, createDirectMessage, createFriendDecreaseNotice, createFriendIncreaseNotice, createFriendMessage, createGroupMemberAddNotice, createGroupMemberDelNotice, createGroupMessage, createGuildMessage, fileToUrl, karin, karinToQQBot, logger, registerBot, segment, unregisterBot } from "node-karin";
+import { c as log, l as basename, n as config, o as pkg, r as getConfig, t as bindHandlers } from "./config-DKa7596f.js";
+import { i as random, n as getImageSize, r as handleUrl, t as fakeEvent } from "./common-by1GpV0b.js";
+import "./utils-BPbnNAix.js";
+import { t as getMessageStore } from "./message-O73AeL_P.js";
+import { t as needQrOnboard } from "./onboard-DPWgX39H.js";
+import { AdapterBase, app, buttonHandle, createDirectMessage, createFriendDecreaseNotice, createFriendIncreaseNotice, createFriendMessage, createGroupMemberAddNotice, createGroupMemberDelNotice, createGroupMessage, createGuildMessage, fileToUrl, fileToUrlHandlerKey, handler, karin as karin$1, karinToQQBot, logger, registerBot, segment, unregisterBot } from "node-karin";
 import { URL } from "url";
 import lodash from "node-karin/lodash";
+import { createReadStream } from "node:fs";
 import FormData from "form-data";
 import axios from "node-karin/axios";
-import EventEmitter from "node:events";
+import crypto from "node:crypto";
+import { open, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath as fileURLToPath$1 } from "node:url";
 import os from "node:os";
+import EventEmitter from "node:events";
 import { WebSocket } from "node-karin/ws";
 import express from "node-karin/express";
 import nacl from "tweetnacl";
@@ -364,7 +371,11 @@ const formatError = (path, options, err) => {
 		const lines = [];
 		lines.push("[axios] 请求失败");
 		lines.push(`请求路径: ${path}`);
-		lines.push(`请求数据: ${lodash.truncate(JSON.stringify(options), { length: 500 })}`);
+		lines.push(`请求数据: ${lodash.truncate(JSON.stringify(redactRequestData(options)), { length: 500 })}`);
+		if (!response) {
+			const reason = [err.code, err.message].filter(Boolean).join(" | ");
+			if (reason) lines.push(`请求错误: ${reason}`);
+		}
 		if (code !== void 0 || status > 0) lines.push(`错误详情: ${formatOpenAPIError(status, code, msg)}`);
 		lines.push(`响应数据: ${JSON.stringify(data)}`);
 		return new Error(lines.join("\n"));
@@ -373,6 +384,20 @@ const formatError = (path, options, err) => {
 	return new Error(typeof err === "string" ? err : JSON.stringify(err));
 };
 /**
+* 请求失败日志脱敏，避免富媒体 file_data/base64 被完整 stringify。
+* @param value 请求数据。
+* @returns 脱敏后的请求数据。
+*/
+const redactRequestData = (value) => {
+	if (!value || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map((item) => redactRequestData(item));
+	const source = value;
+	const result = {};
+	for (const [key, item] of Object.entries(source)) if (key === "file_data" && typeof item === "string") result[key] = `<redacted ${item.length} chars>`;
+	else result[key] = redactRequestData(item);
+	return result;
+};
+/**
 * Http 基础类，子模块继承此类共享 axios 实例与错误格式化
 */
 var Http = class {
@@ -388,17 +413,23 @@ var Http = class {
 			throw formatError(path, void 0, err);
 		}
 	}
-	async post(path, body = {}, headers) {
+	async post(path, body = {}, headers, timeout) {
 		try {
-			const { data } = await this.axios.post(path, body, { headers });
+			const { data } = await this.axios.post(path, body, {
+				headers,
+				timeout
+			});
 			return data;
 		} catch (err) {
 			throw formatError(path, body, err);
 		}
 	}
-	async put(path, body = {}, headers) {
+	async put(path, body = {}, headers, timeout) {
 		try {
-			const { data } = await this.axios.put(path, body, { headers });
+			const { data } = await this.axios.put(path, body, {
+				headers,
+				timeout
+			});
 			return data;
 		} catch (err) {
 			throw formatError(path, body, err);
@@ -452,6 +483,92 @@ var MessagesApi = class extends Http {
 	}
 };
 
+//#endregion
+//#region src/core/api/upload-cache.ts
+/** 单进程内最多缓存的 file_info 数量，避免长期运行时内存无限增长。 */
+const MAX_CACHE_SIZE = 500;
+/** 比 QQ 返回的 ttl 提前失效，避免临界点使用到刚过期的 file_info。 */
+const TTL_SAFETY_MARGIN_SECONDS = 60;
+/** QQ 返回极短 ttl 时仍保留一个最小可用窗口。 */
+const MIN_EFFECTIVE_TTL_SECONDS = 10;
+const cache = /* @__PURE__ */ new Map();
+/**
+* 构建 file_info 缓存键。
+*
+* 虽然 QQ 文档说同一类会话内 file_info 可复用，但这里仍按 peer 隔离，
+* 以避开未文档化的服务端限制。
+*
+* @param scene 上传场景。
+* @param peer openid 或 group_openid。
+* @param type 富媒体类型。
+* @param contentHash 文件内容 hash。
+* @returns 缓存键。
+*/
+const cacheKey = (scene, peer, type, contentHash) => [
+	scene,
+	peer,
+	type,
+	contentHash
+].join("");
+/**
+* 惰性清理过期缓存。
+* @param now 当前时间戳。
+*/
+const cleanupExpired = (now = Date.now()) => {
+	for (const [key, entry] of cache) if (entry.expiresAt <= now) cache.delete(key);
+};
+/**
+* 缓存满时淘汰最旧的一批条目。
+*/
+const evictOldest = () => {
+	if (cache.size < MAX_CACHE_SIZE) return;
+	cleanupExpired();
+	if (cache.size < MAX_CACHE_SIZE) return;
+	const entries = [...cache.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+	const removeCount = Math.max(1, Math.ceil(MAX_CACHE_SIZE / 2));
+	for (const [key] of entries.slice(0, removeCount)) cache.delete(key);
+};
+/**
+* 读取可复用的上传结果。
+*
+* @param scene 上传场景。
+* @param peer openid 或 group_openid。
+* @param type 富媒体类型。
+* @param contentHash 文件内容 hash。
+* @returns 未命中或过期时返回 null。
+*/
+const getCachedUpload = (scene, peer, type, contentHash) => {
+	const key = cacheKey(scene, peer, type, contentHash);
+	const entry = cache.get(key);
+	if (!entry) return null;
+	if (entry.expiresAt <= Date.now()) {
+		cache.delete(key);
+		return null;
+	}
+	return { ...entry.response };
+};
+/**
+* 写入上传结果缓存。
+*
+* @param scene 上传场景。
+* @param peer openid 或 group_openid。
+* @param type 富媒体类型。
+* @param contentHash 文件内容 hash。
+* @param response 上传接口返回。
+*/
+const setCachedUpload = (scene, peer, type, contentHash, response) => {
+	if (!response.file_info) return;
+	evictOldest();
+	const now = Date.now();
+	const ttl = Number(response.ttl);
+	const effectiveTtl = ttl > 0 ? Math.max(ttl - TTL_SAFETY_MARGIN_SECONDS, MIN_EFFECTIVE_TTL_SECONDS) * 1e3 : Number.POSITIVE_INFINITY;
+	cache.set(cacheKey(scene, peer, type, contentHash), {
+		response: { ...response },
+		expiresAt: ttl > 0 ? now + effectiveTtl : Number.POSITIVE_INFINITY,
+		createdAt: now
+	});
+};
+
 //#endregion
 //#region src/core/api/media.ts
 const FILE_TYPE = {
@@ -460,6 +577,360 @@ const FILE_TYPE = {
 	record: 3,
 	file: 4
 };
+/** 各类资源的 QQ 上传上限。 */
+const MAX_UPLOAD_SIZE = {
+	image: 30 * 1024 * 1024,
+	video: 100 * 1024 * 1024,
+	record: 20 * 1024 * 1024,
+	file: 100 * 1024 * 1024
+};
+/** 上传错误中展示的资源类型名称。 */
+const MEDIA_TYPE_LABEL = {
+	image: "图片",
+	video: "视频",
+	record: "语音",
+	file: "文件"
+};
+/** fallback 上传超过该大小时走 QQ 分片上传。 */
+const LARGE_UPLOAD_THRESHOLD = 5 * 1024 * 1024;
+/** QQ upload_prepare 需要的前 10,002,432 字节 MD5。 */
+const MD5_10M_SIZE = 10002432;
+/** 分片上传时没有业务文件名的默认值。 */
+const DEFAULT_FILENAME$1 = {
+	image: "image.jpg",
+	video: "video.mp4",
+	record: "record.mp3",
+	file: "file.bin"
+};
+/** 富媒体上传比普通接口慢，尤其本地视频会走 file_data。 */
+const MEDIA_UPLOAD_TIMEOUT = 12e4;
+/** URL 回源下载兜底超时。 */
+const MEDIA_DOWNLOAD_TIMEOUT = 12e4;
+/** 每个分片 PUT 到 QQ 临时地址的超时时间。 */
+const PART_UPLOAD_TIMEOUT = 3e5;
+/** 每个分片 PUT 失败后的重试次数。 */
+const PART_UPLOAD_RETRIES = 2;
+/** upload_part_finish 普通失败重试次数。 */
+const PART_FINISH_RETRIES = 2;
+/** upload_part_finish 普通失败重试基础间隔。 */
+const PART_FINISH_BASE_DELAY = 1e3;
+/** upload_part_finish 命中这些业务码时，需要按服务端给出的窗口持续重试。 */
+const PART_FINISH_RETRYABLE_CODES = /* @__PURE__ */ new Set([40093001]);
+/** 服务端未返回 retry_timeout 时，持续重试的默认时间。 */
+const PART_FINISH_DEFAULT_RETRY_TIMEOUT = 120 * 1e3;
+/** 持续重试窗口上限，避免服务端返回异常值导致任务长时间占用。 */
+const PART_FINISH_MAX_RETRY_TIMEOUT = 600 * 1e3;
+/** 持续重试时的固定间隔。 */
+const PART_FINISH_RETRY_INTERVAL = 1e3;
+/** 分片完成接口失败重试次数。 */
+const COMPLETE_UPLOAD_RETRIES = 2;
+/** 分片完成接口失败重试基础间隔。 */
+const COMPLETE_UPLOAD_BASE_DELAY = 2e3;
+/** upload_prepare 返回该业务码时表示大文件上传额度受限。 */
+const UPLOAD_PREPARE_DAILY_LIMIT_CODE = 40093002;
+/** QQ 没返回建议并发数时的默认并发。 */
+const DEFAULT_PART_CONCURRENCY = 1;
+/** 本地限制的最大分片并发，避免服务端返回过大值。 */
+const MAX_PART_CONCURRENCY = 10;
+/** HTTP(S) URL 可直接交给 QQ 平台拉取。 */
+const HTTP_URL_RE$1 = /^https?:\/\//i;
+/** Karin 常见 base64 图片/媒体前缀。 */
+const BASE64_PREFIX_RE = /^base64:\/\//i;
+/** 标准 data URL 的 base64 前缀。 */
+const DATA_URL_BASE64_RE = /^data:[^;,]+;base64,/i;
+/**
+* 判断字符串是否明显是本地文件路径。
+* 不明显的字符串按裸 base64 兼容处理，避免破坏旧调用方式。
+*/
+const isLocalPathSource = (source) => {
+	return source.startsWith("file://") || /^[a-zA-Z]:[\\/]/.test(source) || source.startsWith("/") || source.startsWith("\\") || source.startsWith("./") || source.startsWith("../") || source.startsWith(".\\") || source.startsWith("..\\");
+};
+/**
+* 将 file:// 或普通路径统一为本地文件系统路径。
+* @param source 本地路径或 file:// URL。
+* @returns 可直接传给 fs 的本地路径。
+*/
+const normalizeLocalPath = (source) => {
+	return source.startsWith("file://") ? fileURLToPath$1(source) : source;
+};
+/**
+* 去掉 Karin/标准 data URL 的 base64 前缀。
+* @param source base64 字符串。
+* @returns QQ 上传接口需要的纯 base64 数据。
+*/
+const stripBase64Prefix = (source) => {
+	return source.replace(DATA_URL_BASE64_RE, "").replace(BASE64_PREFIX_RE, "");
+};
+/**
+* 将文件大小格式化为便于阅读的字符串。
+* @param bytes 文件字节数。
+* @returns 格式化后的文件大小。
+*/
+const formatBytes = (bytes) => {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+};
+/**
+* 规范化上传文件名，避免把路径当成文件名交给 QQ。
+* @param type 富媒体类型。
+* @param name 候选文件名。
+* @returns 安全的基础文件名。
+*/
+const normalizeUploadFileName = (type, name) => {
+	const value = name?.trim();
+	if (!value) return DEFAULT_FILENAME$1[type];
+	return path.basename(value) || DEFAULT_FILENAME$1[type];
+};
+/**
+* 检查 fallback 资源大小是否超过 QQ 对应类型上限。
+* @param type 富媒体类型。
+* @param size 文件大小。
+*/
+const assertUploadSize = (type, size) => {
+	const limit = MAX_UPLOAD_SIZE[type];
+	if (size <= limit) return;
+	throw new Error(`${MEDIA_TYPE_LABEL[type]}过大：${formatBytes(size)}，QQ 上传上限为 ${formatBytes(limit)}`);
+};
+/**
+* 读取本地媒体文件并转为 QQ 上传接口需要的 base64。
+* @param source 本地路径或 file:// URL。
+* @returns 文件内容的 base64 字符串。
+*/
+const readLocalFileAsBase64 = async (source) => {
+	return readFile(normalizeLocalPath(source), "base64");
+};
+/**
+* 下载远程媒体并返回 Buffer。
+* @param url 远程媒体 URL。
+* @returns 文件内容。
+*/
+const downloadRemoteAsBuffer = async (url) => {
+	const { data } = await axios.get(url, {
+		responseType: "arraybuffer",
+		timeout: MEDIA_DOWNLOAD_TIMEOUT,
+		maxBodyLength: Infinity,
+		maxContentLength: Infinity
+	});
+	return Buffer.from(data);
+};
+/**
+* 下载远程媒体并转为 QQ 上传接口需要的 base64。
+* @param url 远程媒体 URL。
+* @returns 文件内容的 base64 字符串。
+*/
+const downloadRemoteAsBase64 = async (url) => {
+	return (await downloadRemoteAsBuffer(url)).toString("base64");
+};
+/**
+* 将 Karin 的 file 字段归一为 QQ 上传接口支持的 url / file_data。
+* @param source HTTP URL、本地路径、data URL、base64:// 或裸 base64。
+* @returns 可合并进上传请求体的来源字段。
+*/
+const buildUploadSource = async (source) => {
+	const value = source.trim();
+	if (HTTP_URL_RE$1.test(value)) return { url: value };
+	if (DATA_URL_BASE64_RE.test(value) || BASE64_PREFIX_RE.test(value)) return { file_data: stripBase64Prefix(value) };
+	if (isLocalPathSource(value)) return { file_data: await readLocalFileAsBase64(value) };
+	return { file_data: value };
+};
+/**
+* 将 fallback 来源归一为可判断大小、可分片读取的形式。
+*
+* @param type 富媒体类型。
+* @param source Karin 消息段里的 file 字段。
+* @param fileName 可选文件名。
+* @returns 可用于普通上传或分片上传的来源。
+*/
+const buildFallbackSource = async (type, source, fileName) => {
+	const value = source.trim();
+	const normalizedName = normalizeUploadFileName(type, fileName);
+	if (HTTP_URL_RE$1.test(value)) {
+		const buffer = await downloadRemoteAsBuffer(value);
+		return {
+			kind: "buffer",
+			buffer,
+			size: buffer.length,
+			fileName: normalizedName
+		};
+	}
+	if (DATA_URL_BASE64_RE.test(value) || BASE64_PREFIX_RE.test(value)) {
+		const buffer = Buffer.from(stripBase64Prefix(value), "base64");
+		return {
+			kind: "buffer",
+			buffer,
+			size: buffer.length,
+			fileName: normalizedName
+		};
+	}
+	if (isLocalPathSource(value)) {
+		const file = normalizeLocalPath(value);
+		const info = await stat(file);
+		const name = normalizeUploadFileName(type, fileName || path.basename(file));
+		return {
+			kind: "local",
+			file,
+			size: info.size,
+			fileName: name
+		};
+	}
+	const buffer = Buffer.from(value, "base64");
+	return {
+		kind: "buffer",
+		buffer,
+		size: buffer.length,
+		fileName: normalizedName
+	};
+};
+/**
+* 读取 fallback 来源的小文件内容并转成 base64。
+* @param source fallback 来源。
+* @returns base64 字符串。
+*/
+const readFallbackSourceAsBase64 = async (source) => {
+	if (source.kind === "buffer") return source.buffer.toString("base64");
+	return readFile(source.file, "base64");
+};
+/**
+* 计算 QQ upload_prepare 所需的 hash。
+*
+* @param source fallback 来源。
+* @returns 完整 MD5、完整 SHA1 与前 10MB MD5。
+*/
+const computeUploadHashes = async (source) => {
+	if (source.kind === "buffer") {
+		const md5 = crypto.createHash("md5").update(source.buffer).digest("hex");
+		return {
+			md5,
+			sha1: crypto.createHash("sha1").update(source.buffer).digest("hex"),
+			md510m: source.size > MD5_10M_SIZE ? crypto.createHash("md5").update(source.buffer.subarray(0, MD5_10M_SIZE)).digest("hex") : md5
+		};
+	}
+	return new Promise((resolve, reject) => {
+		const md5 = crypto.createHash("md5");
+		const sha1 = crypto.createHash("sha1");
+		const md510m = crypto.createHash("md5");
+		const needsMd510m = source.size > MD5_10M_SIZE;
+		let consumed = 0;
+		const stream = createReadStream(source.file);
+		stream.on("data", (chunk) => {
+			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			md5.update(buffer);
+			sha1.update(buffer);
+			if (needsMd510m) {
+				const remaining = MD5_10M_SIZE - consumed;
+				if (remaining > 0) md510m.update(remaining >= buffer.length ? buffer : buffer.subarray(0, remaining));
+			}
+			consumed += buffer.length;
+		});
+		stream.on("end", () => {
+			const md5Hex = md5.digest("hex");
+			resolve({
+				md5: md5Hex,
+				sha1: sha1.digest("hex"),
+				md510m: needsMd510m ? md510m.digest("hex") : md5Hex
+			});
+		});
+		stream.on("error", reject);
+	});
+};
+/**
+* 从 fallback 来源读取指定分片。
+* @param source fallback 来源。
+* @param handle 本地文件句柄，buffer 来源不需要。
+* @param offset 分片起始位置。
+* @param length 分片长度。
+* @returns 分片内容。
+*/
+const readPart = async (source, handle, offset, length) => {
+	if (source.kind === "buffer") return source.buffer.subarray(offset, offset + length);
+	if (!handle) throw new Error("读取分片失败：文件句柄不存在");
+	const buffer = Buffer.alloc(length);
+	const { bytesRead } = await handle.read(buffer, 0, length, offset);
+	return bytesRead === length ? buffer : buffer.subarray(0, bytesRead);
+};
+/**
+* 带有限重试地把单个分片 PUT 到 QQ 返回的临时地址。
+*
+* @param url QQ 返回的分片上传地址。
+* @param data 分片内容。
+* @param partIndex 分片序号。
+* @param totalParts 总分片数。
+*/
+const putPart = async (url, data, partIndex, totalParts) => {
+	let lastError;
+	for (let attempt = 0; attempt <= PART_UPLOAD_RETRIES; attempt++) try {
+		await axios.put(url, data, {
+			headers: {
+				"Content-Type": "application/octet-stream",
+				"Content-Length": String(data.length)
+			},
+			timeout: PART_UPLOAD_TIMEOUT,
+			maxBodyLength: Infinity,
+			maxContentLength: Infinity
+		});
+		return;
+	} catch (err) {
+		lastError = err;
+		if (attempt < PART_UPLOAD_RETRIES) await new Promise((resolve) => setTimeout(resolve, 500 * (attempt + 1)));
+	}
+	throw new Error(`上传分片失败：${partIndex}/${totalParts}，${lastError instanceof Error ? lastError.message : String(lastError)}`);
+};
+/**
+* 使用固定并发执行异步任务。
+* @param tasks 待执行任务。
+* @param concurrency 最大并发。
+*/
+const runWithConcurrency = async (tasks, concurrency) => {
+	let index = 0;
+	const workerCount = Math.max(1, Math.min(concurrency, tasks.length));
+	const workers = Array.from({ length: workerCount }, async () => {
+		while (index < tasks.length) {
+			const current = index;
+			index += 1;
+			await tasks[current]();
+		}
+	});
+	await Promise.all(workers);
+};
+/**
+* 等待指定时间。
+* @param ms 毫秒数。
+*/
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* 从 axios 原始错误或已格式化错误文本里提取 QQ 业务错误码。
+* @param err 待检查的错误。
+* @returns 业务错误码。
+*/
+const openApiCode = (err) => {
+	if (axios.isAxiosError(err)) {
+		const data = err.response?.data;
+		const code = typeof data?.code === "number" ? data.code : typeof data?.err_code === "number" ? data.err_code : void 0;
+		if (code !== void 0) return code;
+	}
+	if (err instanceof Error) {
+		const match = err.message.match(/\[Code\s+(\d+)\]/);
+		if (match) return Number(match[1]);
+	}
+};
+/**
+* 判断 upload_part_finish 是否命中需要持续重试的服务端状态。
+* @param err 请求错误。
+* @returns 是否需要持续重试。
+*/
+const shouldRetryPartFinishPersistently = (err) => {
+	const code = openApiCode(err);
+	return code !== void 0 && PART_FINISH_RETRYABLE_CODES.has(code);
+};
+/**
+* 将未知错误重新抛出为 Error。
+* @param err 原始错误。
+*/
+const throwError = (err) => {
+	if (err instanceof Error) throw err;
+	throw new Error(typeof err === "string" ? err : JSON.stringify(err));
+};
 /**
 * 富媒体上传
 */
@@ -468,22 +939,190 @@ var MediaApi = class extends Http {
 	* @param scene user(单聊) / group(群聊)
 	* @param peer openid 或 group_openid
 	* @param type 文件类型
-	* @param source 必须是 http url 或 base64 字符串
+	* @param source http url、本地路径或 base64 字符串
 	* @param srvSendMsg 上传后是否由服务端直接发送
+	* @param fileName 文件消息的展示文件名
 	*/
-	upload(scene, peer, type, source, srvSendMsg = false) {
+	async upload(scene, peer, type, source, srvSendMsg = false, fileName) {
+		const sourceBody = await buildUploadSource(source);
 		const body = {
 			file_type: FILE_TYPE[type],
 			srv_send_msg: srvSendMsg
 		};
-		if (source.startsWith("http")) body.url = source;
-		else body.file_data = source.replace(/^data:[\w/+-]+;base64,|^base64:\/\//, "");
-		return this.post(`/v2/${scene}s/${peer}/files`, body);
+		Object.assign(body, sourceBody);
+		if (type === "file" && fileName) body.file_name = fileName;
+		const path = `/v2/${scene}s/${peer}/files`;
+		try {
+			return await this.post(path, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+		} catch (err) {
+			if (!sourceBody.url) throw err;
+			const fallbackBody = {
+				...body,
+				file_data: await downloadRemoteAsBase64(sourceBody.url)
+			};
+			delete fallbackBody.url;
+			return this.post(path, fallbackBody, void 0, MEDIA_UPLOAD_TIMEOUT);
+		}
+	}
+	/**
+	* 上传没有公网 URL 处理器可用时的 fallback 富媒体资源。
+	*
+	* 较大的 fallback 资源会优先使用 QQ 分片上传，提高直接发送成功率。
+	* `srvSendMsg` 为 true 时保留普通上传路径，避免分片完成接口与服务端直接发送语义冲突。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param type 文件类型
+	* @param source 本地路径、http url、data URL、base64:// 或裸 base64
+	* @param srvSendMsg 上传后是否由服务端直接发送
+	* @param fileName 文件消息的展示文件名
+	* @returns 上传结果，包含后续发送消息所需的 file_info
+	*/
+	async uploadFallback(scene, peer, type, source, srvSendMsg = false, fileName) {
+		const fallbackSource = await buildFallbackSource(type, source, fileName);
+		assertUploadSize(type, fallbackSource.size);
+		const hashes = !srvSendMsg ? await computeUploadHashes(fallbackSource) : void 0;
+		if (hashes) {
+			const cached = getCachedUpload(scene, peer, type, hashes.md5);
+			if (cached) return cached;
+		}
+		if (!srvSendMsg && fallbackSource.size >= LARGE_UPLOAD_THRESHOLD) {
+			const response = await this.uploadChunked(scene, peer, type, fallbackSource, hashes);
+			if (hashes) setCachedUpload(scene, peer, type, hashes.md5, response);
+			return response;
+		}
+		const body = {
+			file_type: FILE_TYPE[type],
+			srv_send_msg: srvSendMsg,
+			file_data: await readFallbackSourceAsBase64(fallbackSource)
+		};
+		if (type === "file") body.file_name = fallbackSource.fileName;
+		const response = await this.post(`/v2/${scene}s/${peer}/files`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+		if (hashes) setCachedUpload(scene, peer, type, hashes.md5, response);
+		return response;
+	}
+	/**
+	* 确认单个分片已完成上传。
+	*
+	* QQ 有时会在分片刚 PUT 完时短暂返回 40093001，此时需要在服务端给出的
+	* retry_timeout 窗口内持续重试，而不是直接判定整个大文件上传失败。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param body upload_part_finish 请求体
+	* @param retryTimeout 服务端返回的持续重试秒数
+	*/
+	async finishUploadPart(scene, peer, body, retryTimeout) {
+		let lastError;
+		for (let attempt = 0; attempt <= PART_FINISH_RETRIES; attempt++) try {
+			await this.post(`/v2/${scene}s/${peer}/upload_part_finish`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+			return;
+		} catch (err) {
+			if (shouldRetryPartFinishPersistently(err)) {
+				await this.retryUploadPartFinish(scene, peer, body, retryTimeout);
+				return;
+			}
+			lastError = err;
+			if (attempt < PART_FINISH_RETRIES) await sleep(PART_FINISH_BASE_DELAY * 2 ** attempt);
+		}
+		throwError(lastError);
+	}
+	/**
+	* 持续重试 upload_part_finish 的短暂服务端状态。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param body upload_part_finish 请求体
+	* @param retryTimeout 服务端返回的持续重试秒数
+	*/
+	async retryUploadPartFinish(scene, peer, body, retryTimeout) {
+		const retryTimeoutMs = retryTimeout ? Math.min(Number(retryTimeout) * 1e3, PART_FINISH_MAX_RETRY_TIMEOUT) : PART_FINISH_DEFAULT_RETRY_TIMEOUT;
+		const deadline = Date.now() + retryTimeoutMs;
+		let attempts = 0;
+		let lastError;
+		while (Date.now() < deadline) try {
+			await this.post(`/v2/${scene}s/${peer}/upload_part_finish`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+			return;
+		} catch (err) {
+			lastError = err;
+			if (!shouldRetryPartFinishPersistently(err)) throwError(err);
+			attempts += 1;
+			await sleep(Math.min(PART_FINISH_RETRY_INTERVAL, Math.max(0, deadline - Date.now())));
+		}
+		throw new Error(`upload_part_finish 持续重试超时：${Math.round(retryTimeoutMs / 1e3)}s，已重试 ${attempts} 次，最后错误：${lastError instanceof Error ? lastError.message : String(lastError)}`);
+	}
+	/**
+	* 完成 QQ 分片上传，并对短暂失败做有限重试。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param uploadId upload_prepare 返回的上传任务 ID
+	* @returns 上传结果
+	*/
+	async completeChunkedUpload(scene, peer, uploadId) {
+		let lastError;
+		const body = { upload_id: uploadId };
+		for (let attempt = 0; attempt <= COMPLETE_UPLOAD_RETRIES; attempt++) try {
+			return await this.post(`/v2/${scene}s/${peer}/files`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+		} catch (err) {
+			lastError = err;
+			if (attempt < COMPLETE_UPLOAD_RETRIES) await sleep(COMPLETE_UPLOAD_BASE_DELAY * 2 ** attempt);
+		}
+		return throwError(lastError);
+	}
+	/**
+	* 使用 QQ 官方分片协议上传 fallback 大资源。
+	*
+	* 流程为：准备上传 -> PUT 每个分片 -> 确认每个分片 -> 完成上传。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param type 文件类型
+	* @param source 已归一化的 fallback 来源
+	* @param preparedHashes 预计算的文件 hash
+	* @returns 上传结果，包含后续发送消息所需的 file_info
+	*/
+	async uploadChunked(scene, peer, type, source, preparedHashes) {
+		const hashes = preparedHashes || await computeUploadHashes(source);
+		const prepareBody = {
+			file_type: FILE_TYPE[type],
+			file_name: source.fileName,
+			file_size: source.size,
+			md5: hashes.md5,
+			sha1: hashes.sha1
+		};
+		prepareBody["md5_10m"] = hashes.md510m;
+		const prepare = await this.post(`/v2/${scene}s/${peer}/upload_prepare`, prepareBody, void 0, MEDIA_UPLOAD_TIMEOUT).catch((err) => {
+			if (openApiCode(err) === UPLOAD_PREPARE_DAILY_LIMIT_CODE) throw new Error(`QQ 大文件上传额度已达上限，${MEDIA_TYPE_LABEL[type]}暂时无法通过 fallback 直传：${source.fileName} (${formatBytes(source.size)})`);
+			return throwError(err);
+		});
+		if (!prepare.parts.length) throw new Error("分片上传准备失败：QQ 未返回分片信息");
+		const concurrency = Math.min(prepare.concurrency || DEFAULT_PART_CONCURRENCY, MAX_PART_CONCURRENCY, prepare.parts.length);
+		const handle = source.kind === "local" ? await open(source.file, "r") : void 0;
+		try {
+			await runWithConcurrency(prepare.parts.map((part) => async () => {
+				const offset = (part.index - 1) * prepare.block_size;
+				const data = await readPart(source, handle, offset, Math.min(prepare.block_size, source.size - offset));
+				const md5 = crypto.createHash("md5").update(data).digest("hex");
+				await putPart(part.presigned_url, data, part.index, prepare.parts.length);
+				await this.finishUploadPart(scene, peer, {
+					upload_id: prepare.upload_id,
+					part_index: part.index,
+					block_size: data.length,
+					md5
+				}, prepare.retry_timeout);
+			}), concurrency);
+		} finally {
+			await handle?.close().catch(() => void 0);
+		}
+		return this.completeChunkedUpload(scene, peer, prepare.upload_id);
 	}
 };
 
 //#endregion
 //#region src/core/api/interaction.ts
+/** QQ 客户端回调按钮需要快速 ACK，超时必须小于平台等待窗口。 */
+const INTERACTION_ACK_TIMEOUT = 2800;
 /**
 * INTERACTION_CREATE 回应
 */
@@ -493,7 +1132,7 @@ var InteractionApi = class extends Http {
 	* @param code 0 成功 / 1 操作失败 / 2 操作频繁 / 3 重复操作 / 4 无权限 / 5 仅管理员
 	*/
 	async ack(interactionId, code = 0) {
-		await this.put(`/interactions/${interactionId}`, { code });
+		await this.put(`/interactions/${interactionId}`, { code }, void 0, INTERACTION_ACK_TIMEOUT);
 	}
 };
 
@@ -545,12 +1184,11 @@ const buildQQMsg = {
 			ark
 		};
 	},
-	/** msg_type=7 时 content 字段必填，传一个空格占位 */
+	/** 构造 msg_type=7 富媒体消息体 */
 	media(fileInfo) {
 		return {
 			msg_type: 7,
-			media: { file_info: fileInfo },
-			content: " "
+			media: { file_info: fileInfo }
 		};
 	}
 };
@@ -623,6 +1261,16 @@ var QQBotApi = class {
 	}
 };
 
+//#endregion
+//#region src/utils/user-agent.ts
+const USER_AGENT_SUFFIX = "Karin";
+/**
+* 构建 QQBot HTTP / WebSocket 使用的 User-Agent。
+*/
+const getUserAgent = () => {
+	return `QQBotAdapter/${String(pkg().version || "unknown")} (Node/${process.versions.node}; ${os.platform()}; ${USER_AGENT_SUFFIX}/${process.env.KARIN_VERSION || "unknown"})`;
+};
+
 //#endregion
 //#region src/core/internal/axios.ts
 const tokens = /* @__PURE__ */ new Map();
@@ -637,7 +1285,7 @@ const getAccessToken = async (url, appId, secret) => {
 		res = await axios.post(url, {
 			appId: String(appId),
 			clientSecret: secret
-		});
+		}, { headers: { "User-Agent": getUserAgent() } });
 	} catch (err) {
 		if (axios.isAxiosError(err)) {
 			const response = err.response;
@@ -684,7 +1332,10 @@ const stopTokenRefresh = (appId) => {
 const createAxiosInstance = (baseURL, appId) => {
 	const instance = axios.create({
 		baseURL,
-		headers: { "Content-Type": "application/json" },
+		headers: {
+			"Content-Type": "application/json",
+			"User-Agent": getUserAgent()
+		},
 		timeout: 5500
 	});
 	instance.interceptors.request.use((config) => {
@@ -695,9 +1346,92 @@ const createAxiosInstance = (baseURL, appId) => {
 	return instance;
 };
 
+//#endregion
+//#region src/core/adapter/button-enter.ts
+/** QQ 私聊直发文本链标签。 */
+const COMMAND_ENTER_TEXT_CHAIN_REGEXP = /<\s*qqbot-cmd-enter\b/i;
+/**
+* 判断按钮是否是 `enter: true` 指令按钮。
+*
+* 链接按钮和回调按钮有自己的平台行为，只有普通指令按钮才需要提示
+* `enter: true` 在非私聊场景不生效。
+*
+* @param button Karin 按钮配置。
+* @returns 是否为直发指令按钮。
+*/
+const isCommandEnterButton = (button) => {
+	if (button.link || button.callback) return false;
+	return (button.type ?? 2) === 2 && button.enter === true;
+};
+/**
+* 判断 markdown 内容是否手写了 QQ 私聊直发文本链。
+*
+* @param markdown markdown 内容。
+* @returns 是否包含 `<qqbot-cmd-enter ...>`。
+*/
+const hasCommandEnterTextChain = (markdown) => {
+	return COMMAND_ENTER_TEXT_CHAIN_REGEXP.test(markdown);
+};
+/**
+* 收集 button/keyboard 中所有 `enter: true` 指令按钮。
+*
+* @param buttons 单行按钮元素列表。
+* @param keyboards 多行 keyboard 元素列表。
+* @returns 需要特殊处理的直发指令按钮。
+*/
+const collectCommandEnterButtons = (buttons, keyboards) => {
+	const result = [];
+	buttons.forEach((element) => {
+		element.data.forEach((button) => {
+			if (isCommandEnterButton(button)) result.push(button);
+		});
+	});
+	keyboards.forEach((element) => {
+		element.rows.forEach((row) => {
+			row.forEach((button) => {
+				if (isCommandEnterButton(button)) result.push(button);
+			});
+		});
+	});
+	return result;
+};
+/**
+* 归一 QQ keyboard 按钮字段。
+*
+* @param button node-karin 转换后的 QQBot 按钮。
+* @param id 当前 keyboard 内唯一按钮序号。
+* @returns 可直接放入 QQ 官方 keyboard 的按钮对象。
+*/
+const normalizeQQBotButton = (button, id) => {
+	return {
+		...button,
+		id: String(id)
+	};
+};
+/**
+* 生成直发按钮不支持提示中的按钮名称列表。
+*
+* @param buttons 直发指令按钮列表。
+* @returns 便于写入日志的按钮名称。
+*/
+const formatCommandEnterButtonNames = (buttons) => {
+	return buttons.map((button) => button.text || button.data || "未命名按钮").join("、");
+};
+
 //#endregion
 //#region src/core/adapter/grouping.ts
 /**
+* 生成 QQ 被动回复使用的 msg_seq 种子。
+*
+* QQ 官方使用 `msg_id + msg_seq` 判重。这里和 openclaw qqbot 适配器一样限制在
+* 16-bit 范围内，后续每发一条再递增取模。
+*
+* @returns 0..65535 范围内的初始 msg_seq。
+*/
+const createMsgSeqSeed = () => {
+	return (Date.now() % 1e8 ^ Math.floor(Math.random() * 65536)) % 65536;
+};
+/**
 * 创建空容器
 */
 const createGrouping = () => ({
@@ -713,7 +1447,7 @@ const createGrouping = () => ({
 	pasmsg: {
 		type: "msg",
 		id: "",
-		seq: random(1, 9999999)
+		seq: createMsgSeqSeed()
 	},
 	faces: []
 });
@@ -761,19 +1495,22 @@ const groupElements = (scene, elements) => {
 		case "video":
 			g.media.push({
 				kind: "video",
-				source: v.file
+				source: v.file,
+				name: v.name
 			});
 			break;
 		case "record":
 			g.media.push({
 				kind: "record",
-				source: v.file
+				source: v.file,
+				name: v.name
 			});
 			break;
 		case "file":
 			g.media.push({
 				kind: "file",
-				source: v.file
+				source: v.file,
+				name: v.name
 			});
 			break;
 		default: break;
@@ -781,6 +1518,214 @@ const groupElements = (scene, elements) => {
 	return g;
 };
 
+//#endregion
+//#region src/core/adapter/media-source.ts
+/** HTTP(S) 资源已经是可直接传给 QQ 平台的公网地址。 */
+const HTTP_URL_RE = /^https?:\/\//i;
+/** fileToUrl 需要文件名来推断上传类型；没有业务文件名时使用这些默认值。 */
+const DEFAULT_FILENAME = {
+	image: "image.jpg",
+	video: "video.mp4",
+	record: "record.mp3",
+	file: "file.bin"
+};
+/**
+* 当前 Karin 运行时是否注册了 fileToUrl 处理器。
+* @returns true 表示可以优先通过 fileToUrl 产出公网 URL。
+*/
+const hasFileToUrlHandler = () => handler.has(fileToUrlHandlerKey);
+/**
+* 判断一个来源是否已经是公网 HTTP(S) 地址。
+* @param source Karin 消息段里的 file 字段。
+* @returns 是否为 HTTP(S) URL。
+*/
+const isHttpMediaSource = (source) => HTTP_URL_RE.test(source);
+/**
+* 优先把本地/base64 富媒体转换为公网 URL；没有处理器或转换失败时返回原始来源。
+*
+* QQ 官方的普通 file_data 上传对视频等资源更容易失败，因此 adapter 层始终把
+* fileToUrl 作为主路径，QQ 上传只做兜底。
+*
+* @param ctx 适配器实例，用于记录降级日志。
+* @param type 富媒体类型。
+* @param source Karin 消息段里的 file 字段。
+* @param filename 可选文件名，主要用于 file 消息。
+* @returns 解析后的首选来源和来源类型。
+*/
+const resolvePreferredMediaSource = async (ctx, type, source, filename) => {
+	if (isHttpMediaSource(source)) return {
+		source,
+		via: "public-url"
+	};
+	if (!hasFileToUrlHandler()) return {
+		source,
+		via: "fallback"
+	};
+	try {
+		return {
+			source: (await fileToUrl(type, source, filename || DEFAULT_FILENAME[type])).url,
+			via: "file-to-url"
+		};
+	} catch (err) {
+		ctx.logger("warn", `[sendQQ] ${type} 转 URL 失败，改用 QQ 上传兜底:`, err);
+		return {
+			source,
+			via: "fallback"
+		};
+	}
+};
+
+//#endregion
+//#region src/core/adapter/message-id-map.ts
+/** QQ 消息 ID 与 REFIDX 映射的短期缓存时长，和本地消息缓存窗口保持一致。 */
+const MESSAGE_ID_LINK_CACHE_TTL = 1440 * 60 * 1e3;
+/** QQ 消息 ID 映射表清理间隔。 */
+const MESSAGE_ID_LINK_CLEANUP_INTERVAL = 60 * 1e3;
+/** 按适配器实例隔离的消息 ID 映射状态。 */
+const states = /* @__PURE__ */ new WeakMap();
+/**
+* 获取适配器实例对应的消息 ID 映射状态。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @returns 该实例的映射状态。
+*/
+const getState = (ctx) => {
+	const existing = states.get(ctx);
+	if (existing) return existing;
+	const created = {
+		apiMessageIdCache: /* @__PURE__ */ new Map(),
+		referenceMessageIdCache: /* @__PURE__ */ new Map(),
+		ownMessageIdCache: /* @__PURE__ */ new Map(),
+		lastCleanup: 0
+	};
+	states.set(ctx, created);
+	return created;
+};
+/**
+* 构造 REFIDX/API ID 映射的会话级 key。
+*
+* @param contact 消息所在会话。
+* @param messageId 消息 ID。
+* @returns 可用于 Map 的稳定 key。
+*/
+const messageIdKey = (contact, messageId) => {
+	return [
+		contact.scene,
+		contact.peer,
+		contact.subPeer || "",
+		messageId
+	].join("");
+};
+/**
+* 清理过期的消息 ID 映射。
+*
+* @param ctx 当前 QQBot 适配器实例。
+*/
+const cleanup = (ctx) => {
+	const state = getState(ctx);
+	const now = Date.now();
+	if (now - state.lastCleanup < MESSAGE_ID_LINK_CLEANUP_INTERVAL) return;
+	state.lastCleanup = now;
+	for (const [key, entry] of state.apiMessageIdCache) if (entry.expiresAt <= now) state.apiMessageIdCache.delete(key);
+	for (const [key, entry] of state.referenceMessageIdCache) if (entry.expiresAt <= now) state.referenceMessageIdCache.delete(key);
+	for (const [key, entry] of state.ownMessageIdCache) if (entry.expiresAt <= now) state.ownMessageIdCache.delete(key);
+};
+/**
+* 记住机器人自己发送的 QQ API 消息 ID。
+*
+* 单聊场景只允许撤回机器人自己发送的消息。收到用户消息时的 `e.messageId`
+* 也是 API 消息 ID，但不能用于单聊撤回，因此需要独立标记来源。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param apiMessageId QQ API 消息 ID，通常为 ROBOT1.0_...。
+*/
+const rememberOwnMessageId = (ctx, contact, apiMessageId) => {
+	if (!apiMessageId) return;
+	cleanup(ctx);
+	getState(ctx).ownMessageIdCache.set(messageIdKey(contact, apiMessageId), { expiresAt: Date.now() + MESSAGE_ID_LINK_CACHE_TTL });
+};
+/**
+* 判断给定 QQ API 消息 ID 是否由机器人自己发送。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param apiMessageId QQ API 消息 ID。
+* @returns true 表示这条消息是当前适配器实例发送的。
+*/
+const isOwnMessageId = (ctx, contact, apiMessageId) => {
+	cleanup(ctx);
+	const state = getState(ctx);
+	const key = messageIdKey(contact, apiMessageId);
+	const cached = state.ownMessageIdCache.get(key);
+	if (!cached) return false;
+	if (cached.expiresAt > Date.now()) return true;
+	state.ownMessageIdCache.delete(key);
+	return false;
+};
+/**
+* 记住 QQ 引用索引对应的 API 消息 ID。
+*
+* QQ 群聊/单聊的 `message_reference.message_id` 使用 REFIDX，但撤回等 API 路径使用
+* ROBOT1.0 开头的消息 ID。映射按适配器实例和会话隔离，避免不同群里的 REFIDX 冲突。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param referenceMessageId QQ 引用索引，通常为 REFIDX_...。
+* @param apiMessageId QQ API 消息 ID，通常为 ROBOT1.0_...。
+*/
+const rememberApiMessageId = (ctx, contact, referenceMessageId, apiMessageId) => {
+	if (!referenceMessageId || !apiMessageId) return;
+	if (referenceMessageId === apiMessageId) return;
+	cleanup(ctx);
+	const state = getState(ctx);
+	const expiresAt = Date.now() + MESSAGE_ID_LINK_CACHE_TTL;
+	state.apiMessageIdCache.set(messageIdKey(contact, referenceMessageId), {
+		apiMessageId,
+		expiresAt
+	});
+	state.referenceMessageIdCache.set(messageIdKey(contact, apiMessageId), {
+		referenceMessageId,
+		expiresAt
+	});
+};
+/**
+* 将 QQ API 消息 ID 解析为客户端可见引用使用的 REFIDX。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param messageId Karin 侧传入的消息 ID，可能是 ROBOT1.0 或 REFIDX。
+* @returns 可用于 `message_reference.message_id` 的 ID；没有映射时返回原值。
+*/
+const resolveReferenceMessageId = (ctx, contact, messageId) => {
+	cleanup(ctx);
+	const state = getState(ctx);
+	const key = messageIdKey(contact, messageId);
+	const cached = state.referenceMessageIdCache.get(key);
+	if (!cached) return messageId;
+	if (cached.expiresAt > Date.now()) return cached.referenceMessageId;
+	state.referenceMessageIdCache.delete(key);
+	return messageId;
+};
+/**
+* 将 Karin 侧传入的消息 ID 解析为 QQ API 可用的消息 ID。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param messageId Karin 侧传入的消息 ID，可能是 REFIDX。
+* @returns QQ API 路径可用的消息 ID；没有映射时返回原值。
+*/
+const resolveApiMessageId = (ctx, contact, messageId) => {
+	cleanup(ctx);
+	const state = getState(ctx);
+	const key = messageIdKey(contact, messageId);
+	const cached = state.apiMessageIdCache.get(key);
+	if (!cached) return messageId;
+	if (cached.expiresAt > Date.now()) return cached.apiMessageId;
+	state.apiMessageIdCache.delete(key);
+	return messageId;
+};
+
 //#endregion
 //#region src/core/adapter/text-to-md.ts
 const MAX_BUTTONS = 5;
@@ -827,14 +1772,21 @@ const imagesToMarkdown = async (urls) => {
 
 //#endregion
 //#region src/core/adapter/pipeline-qq.ts
+/** QQ 官方限制：单聊中同一 `msg_id` 最多发送四次被动回复。 */
+const C2C_PASSIVE_REPLY_LIMIT = 4;
+/** QQ keyboard 限制：最多 5 行，每行最多 5 个按钮。 */
+const KEYBOARD_MAX_ROWS$1 = 5;
+const KEYBOARD_MAX_BUTTONS_PER_ROW$1 = 5;
+/** 只有按钮没有文本时仍需提供非空 markdown 内容。 */
+const BUTTON_ONLY_MARKDOWN$1 = "​";
 /** 群聊 event_id 白名单 */
-const GROUP_EVENT_WHITELIST = new Set([
+const GROUP_EVENT_WHITELIST = /* @__PURE__ */ new Set([
 	"INTERACTION_CREATE",
 	"GROUP_ADD_ROBOT",
 	"GROUP_MSG_RECEIVE"
 ]);
 /** 单聊 event_id 白名单 */
-const FRIEND_EVENT_WHITELIST = new Set([
+const FRIEND_EVENT_WHITELIST = /* @__PURE__ */ new Set([
 	"INTERACTION_CREATE",
 	"C2C_MSG_RECEIVE",
 	"FRIEND_ADD"
@@ -851,10 +1803,11 @@ const sendQQ = async (ctx, contact, elements) => {
 		grouping.buttons.push(...buttons);
 	}
 	/**
-	* 永远走 markdown 通道：
-	* text / at / image 通过 markdown content 渲染（at 用内嵌标签）；
-	* 视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 并发补发。
-	* Markdown / Keyboard 已全量开放，无需再走老的 msg_type=0 文本通道。
+	* 默认走 markdown 通道：
+	* text / at / 可转换为公网 URL 的图片通过 markdown content 渲染；无法转换的图片
+	* 与视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 单独补发。所有富媒体
+	* 都会优先通过 fileToUrl 取得公网地址，QQ 上传只做兜底。只有显式引用的
+	* 纯文本消息会降级为 msg_type=0，以保证 QQ 客户端能稳定显示引用气泡。
 	*/
 	return sendQQMarkdown(ctx, contact, grouping, target);
 };
@@ -865,87 +1818,256 @@ const sendQQMarkdown = async (ctx, contact, grouping, target) => {
 	const items = [];
 	const lines = [];
 	if (grouping.text.length) lines.push(grouping.text.join(""));
-	if (grouping.qqImages.length) {
-		const urlImages = [];
-		for (const file of grouping.qqImages) if (file.startsWith("http")) urlImages.push(file);
-		else {
-			const { url } = await fileToUrl("image", file, "image.jpg");
-			urlImages.push(url);
-		}
-		const mdImages = await imagesToMarkdown(urlImages);
-		lines.push(...mdImages);
-	}
+	const fallbackImages = await appendMarkdownImages(ctx, lines, grouping.qqImages);
 	if (grouping.markdowns.length) grouping.markdowns.forEach((m) => lines.push(m.markdown));
-	if (lines.length || grouping.buttons.length || grouping.keyboards.length) {
-		const content = lines.join("\n");
+	if (contact.scene === "group") {
+		warnUnsupportedCommandEnterButtons$1(ctx, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
+		warnUnsupportedCommandEnterMarkdowns$1(ctx, grouping.markdowns.map((m) => m.markdown));
+	}
+	if (lines.length || grouping.buttons.length || grouping.keyboards.length) if (shouldUseTextForReference(ctx, contact, grouping)) items.push(ctx.super.qq.text(lines.join("\n")));
+	else {
 		const keyboard = buildKeyboard$1(grouping);
+		const content = lines.length ? lines.join("\n") : BUTTON_ONLY_MARKDOWN$1;
 		items.push(ctx.super.qq.markdown({ content }, keyboard));
 	}
+	for (const file of fallbackImages) {
+		const res = await ctx.super.media.uploadFallback(target, contact.peer, "image", file, false);
+		items.push(ctx.super.qq.media(res.file_info));
+	}
 	for (const m of grouping.media) {
-		let url = m.source;
-		if (!url.startsWith("http")) {
-			const ext = m.kind === "record" ? "mp3" : m.kind === "video" ? "mp4" : "bin";
-			url = (await fileToUrl(m.kind, url, `${m.kind}.${ext}`)).url;
-		}
-		const res = await ctx.super.media.upload(target, contact.peer, m.kind, url, false);
+		const source = await resolvePreferredMediaSource(ctx, m.kind, m.source, m.name);
+		const res = source.via === "fallback" ? await ctx.super.media.uploadFallback(target, contact.peer, m.kind, source.source, false, m.name) : await ctx.super.media.upload(target, contact.peer, m.kind, source.source, false, m.name);
 		items.push(ctx.super.qq.media(res.file_info));
 	}
 	if (!items.length) items.push(ctx.super.qq.text("不支持发送的消息类型"));
 	return flushQQ(ctx, contact, grouping, items);
 };
 /**
+* 将能转成公网 URL 的图片追加到 markdown 行，无法转换的图片返回给富媒体 fallback。
+*
+* @param ctx 适配器实例，用于输出降级日志。
+* @param lines markdown 行数组。
+* @param files QQ 图片消息段的 file 字段。
+* @returns 需要改走 msg_type=7 富媒体发送的图片列表。
+*/
+const appendMarkdownImages = async (ctx, lines, files) => {
+	const fallback = [];
+	for (const file of files) {
+		const resolved = await resolvePreferredMediaSource(ctx, "image", file);
+		if (resolved.via === "fallback") {
+			fallback.push(file);
+			continue;
+		}
+		await appendImageUrlLine(lines, resolved.source);
+	}
+	return fallback;
+};
+/**
+* 生成单张 markdown 图片行。
+* 尺寸获取失败时使用保守默认尺寸，保证 fileToUrl 成功的图片仍走 markdown。
+*
+* @param lines markdown 行数组。
+* @param url 图片 URL。
+*/
+const appendImageUrlLine = async (lines, url) => {
+	try {
+		const [line] = await imagesToMarkdown([url]);
+		lines.push(line);
+	} catch {
+		lines.push(`![karin #300px #300px](${url})`);
+	}
+};
+/**
+* 判断显式引用回复是否应降级为普通文本消息。
+*
+* QQ 的 `message_reference` 对普通文本最稳定；markdown 带引用在客户端渲染上存在兼容问题。
+* 因此只有纯文本显式引用回复会走 msg_type=0，图片、按钮、keyboard、markdown 段仍走原通道。
+*
+* @param grouping 已归类的消息段。
+* @returns 是否使用普通文本发送主消息。
+*/
+const shouldUseTextForReference = (ctx, contact, grouping) => {
+	return isQQReferenceMessageId(resolveReferenceMessageId(ctx, contact, grouping.reply.messageId)) && !grouping.qqImages.length && !grouping.buttons.length && !grouping.keyboards.length && !grouping.markdowns.length;
+};
+/**
+* 判断给定 ID 是否是 QQ 客户端引用使用的 REFIDX。
+*
+* `ROBOT1.0_...` 这类官方消息 ID 只能作为被动发送的 `msg_id`，不能放进
+* `message_reference.message_id`。
+*
+* @param messageId 待判断的消息 ID。
+* @returns 是否为 QQ 引用索引。
+*/
+const isQQReferenceMessageId = (messageId) => messageId.startsWith("REFIDX_");
+/**
 * 构造 keyboard 字段（buttons + keyboards 合并）
 */
 const buildKeyboard$1 = (grouping) => {
 	const rows = [];
 	grouping.buttons.forEach((b) => rows.push(...karinToQQBot(b)));
 	grouping.keyboards.forEach((k) => rows.push(...karinToQQBot(k)));
-	if (!rows.length) return void 0;
-	return { content: { rows } };
+	const normalizedRows = [];
+	let id = 0;
+	for (const row of rows.slice(0, KEYBOARD_MAX_ROWS$1)) {
+		const buttons = row.buttons.slice(0, KEYBOARD_MAX_BUTTONS_PER_ROW$1).map((button) => normalizeQQBotButton(button, id++));
+		if (buttons.length) normalizedRows.push({ buttons });
+	}
+	if (!normalizedRows.length) return void 0;
+	return { content: { rows: normalizedRows } };
+};
+/**
+* 群聊不支持 `enter: true` 直发按钮，只输出提示，不拦截 keyboard 发送。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param buttons 本次消息中的直发指令按钮。
+*/
+const warnUnsupportedCommandEnterButtons$1 = (ctx, buttons) => {
+	if (!buttons.length) return;
+	const names = formatCommandEnterButtonNames(buttons);
+	ctx.logger("debug", `群聊不支持 enter: true 直接发送，按钮仍会按原样发送: ${names}`);
+};
+/**
+* 群聊不支持 `<qqbot-cmd-enter>` 文本链，只输出提示，不拦截 markdown 发送。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param markdowns 本次消息中的 markdown 内容。
+*/
+const warnUnsupportedCommandEnterMarkdowns$1 = (ctx, markdowns) => {
+	if (!markdowns.some(hasCommandEnterTextChain)) return;
+	ctx.logger("debug", "群聊不支持 <qqbot-cmd-enter> 直接发送，markdown 仍会按原样发送");
 };
 /**
 * 逐条发送 + 被动消息附加 + 引用回复
 */
-const flushQQ = async (ctx, contact, grouping, items) => {
-	const result = ctx.initSendMsgResults();
-	const passive = buildPassiveQQ(contact.scene, grouping);
-	const send = contact.scene === "friend" ? (peer, item) => ctx.super.messages.sendFriendMsg(peer, item) : (peer, item) => ctx.super.messages.sendGroupMsg(peer, item);
-	let replyHandled = false;
-	for (const item of items) {
-		passive(item);
-		if (!replyHandled && grouping.reply.messageId) {
-			item.message_reference = { message_id: grouping.reply.messageId };
-			replyHandled = true;
-		}
-		const res = await send(contact.peer, item);
-		result.rawData.push(res);
-	}
-	return ctx.handleResponse(result);
+const flushQQ = async (ctx, contact, grouping, items) => {
+	const result = ctx.initSendMsgResults();
+	const passiveSource = resolvePassiveQQ(grouping);
+	const passive = buildPassiveQQ(ctx, contact.scene, grouping);
+	const send = contact.scene === "friend" ? (peer, item) => ctx.super.messages.sendFriendMsg(peer, item) : (peer, item) => ctx.super.messages.sendGroupMsg(peer, item);
+	/**
+	* 仅单聊 `msg_id` 回复受四次上限约束。`event_id` 事件回复和群聊不适用该限制。
+	* 这是 QQ 官方 2026-01-10 更新后的限制，超出部分不请求平台接口。
+	*/
+	const maxItems = contact.scene === "friend" && passiveSource?.type === "msg" && passiveSource.id ? C2C_PASSIVE_REPLY_LIMIT : Infinity;
+	if (items.length > maxItems) ctx.logger("warn", `单聊被动回复最多 ${C2C_PASSIVE_REPLY_LIMIT} 条，已跳过 ${items.length - maxItems} 条`);
+	let referenceHandled = false;
+	for (const item of items.slice(0, maxItems)) {
+		passive(item);
+		if (!referenceHandled) referenceHandled = attachVisibleReferenceQQ(ctx, contact, item, grouping);
+		const res = await sendQQWithEventFallback(ctx, contact, send, item);
+		rememberOwnMessageId(ctx, contact, res.id);
+		if (res.ext_info?.ref_idx) rememberApiMessageId(ctx, contact, res.ext_info.ref_idx, res.id);
+		result.rawData.push(res);
+	}
+	return ctx.handleResponse(result);
+};
+/**
+* 发送 QQ 消息，并在平台拒绝 `event_id` 时降级为普通消息重试。
+*
+* QQ 文档说明 `INTERACTION_CREATE.d.id` 可用于被动消息发送，但实测群聊接口会出现
+* 40034025。为了避免按钮回调业务回复把 Karin 命令链路打断，这里只对
+* `event_id` 参数无效做一次无 `event_id` 重试。
+*
+* @param ctx 适配器实例，用于输出降级日志。
+* @param contact 消息目标。
+* @param send 当前场景的发送函数。
+* @param item 即将发送的 QQ 消息体。
+* @returns QQ 消息发送响应。
+*/
+const sendQQWithEventFallback = async (ctx, contact, send, item) => {
+	try {
+		return await send(contact.peer, item);
+	} catch (err) {
+		if (!item.event_id || !isInvalidEventIdError(err)) throw err;
+		ctx.logger("warn", `event_id 被 QQ 拒绝，已改用普通消息重试: ${item.event_id}`);
+		const retryItem = { ...item };
+		delete retryItem.event_id;
+		delete retryItem.msg_seq;
+		return send(contact.peer, retryItem);
+	}
+};
+/**
+* 判断发送失败是否来自 QQ 对 `event_id` 的参数校验。
+*
+* 当前错误由 Http 层格式化为普通 Error，因此这里基于官方错误码和中文错误信息兜底识别。
+*
+* @param err 捕获到的发送异常。
+* @returns 是否可以通过移除 `event_id` 重试。
+*/
+const isInvalidEventIdError = (err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	return message.includes("40034025") || message.includes("请求参数event_id无效");
+};
+/**
+* 解析 QQ 场景应使用的被动回复来源。
+*
+* `msg_id/event_id` 是 QQBot 被动发送凭证，不等于客户端展示引用使用的
+* `message_reference.message_id`。因此这里只读取事件入口追加的 pasmsg，显式
+* `segment.reply` 交给 `attachVisibleReferenceQQ` 处理。
+*
+* @param grouping 已归类的消息段。
+* @returns 可附加到发送体的被动回复来源；没有可用来源时返回 undefined。
+*/
+const resolvePassiveQQ = (grouping) => {
+	if (grouping.pasmsg.id) return grouping.pasmsg;
+};
+/**
+* 附加 QQ 客户端可见的引用对象。
+*
+* 群聊/单聊里真正发给 QQ 的值必须是 `message_scene.ext` 的 `msg_idx=REFIDX_xxx`。
+* 如果插件传入的是 Karin 暴露的官方 API 消息 ID，这里会先按同会话映射转换。
+*
+* @param item 即将发送的 QQ 消息体。
+* @param grouping 已归类的消息段。
+* @returns 是否已经消费一次显式引用。
+*/
+const attachVisibleReferenceQQ = (ctx, contact, item, grouping) => {
+	const messageId = resolveReferenceMessageId(ctx, contact, grouping.reply.messageId);
+	if (!isQQReferenceMessageId(messageId)) return false;
+	item.message_reference = { message_id: messageId };
+	return true;
+};
+/**
+* 递增并返回下一条 QQ 被动回复序号。
+*
+* @param grouping 已归类的消息段。
+* @returns 0..65535 范围内的 msg_seq。
+*/
+const nextPassiveMsgSeq = (grouping) => {
+	grouping.pasmsg.seq = (grouping.pasmsg.seq + 1) % 65536;
+	return grouping.pasmsg.seq;
 };
 /**
 * 构造被动消息附加器（含白名单校验）
 */
-const buildPassiveQQ = (scene, grouping) => {
-	if (!grouping.pasmsg.id) return (_item) => void 0;
+const buildPassiveQQ = (ctx, scene, grouping) => {
+	const source = resolvePassiveQQ(grouping);
+	if (!source?.id) return (_item) => void 0;
 	const whitelist = scene === "friend" ? FRIEND_EVENT_WHITELIST : GROUP_EVENT_WHITELIST;
-	if (grouping.pasmsg.type === "event") {
-		const eventName = grouping.pasmsg.id.split(":")[0];
-		if (eventName && !whitelist.has(eventName)) {}
+	if (source.type === "event") {
+		const eventName = source.id.split(":")[0];
+		if (eventName && !whitelist.has(eventName)) {
+			ctx.logger("warn", `跳过无效 event_id: ${source.id}`);
+			return (_item) => void 0;
+		}
 		return (item) => {
-			grouping.pasmsg.seq++;
-			item.msg_seq = grouping.pasmsg.seq;
-			item.event_id = grouping.pasmsg.id;
+			item.msg_seq = nextPassiveMsgSeq(grouping);
+			item.event_id = source.id;
 		};
 	}
 	return (item) => {
-		grouping.pasmsg.seq++;
-		item.msg_seq = grouping.pasmsg.seq;
-		item.msg_id = grouping.pasmsg.id;
+		item.msg_seq = nextPassiveMsgSeq(grouping);
+		item.msg_id = source.id;
 	};
 };
 
 //#endregion
 //#region src/core/adapter/pipeline-guild.ts
+/** QQ keyboard 限制：最多 5 行，每行最多 5 个按钮。 */
+const KEYBOARD_MAX_ROWS = 5;
+const KEYBOARD_MAX_BUTTONS_PER_ROW = 5;
+/** 只有按钮没有文本时仍需提供非空 markdown 内容。 */
+const BUTTON_ONLY_MARKDOWN = "​";
 /**
 * 处理频道场景（子频道 + 私信）的发送
 *
@@ -978,9 +2100,12 @@ const sendGuildMarkdown = async (ctx, contact, grouping) => {
 		lines.push(...mdImages);
 	}
 	grouping.markdowns.forEach((m) => lines.push(m.markdown));
+	warnUnsupportedCommandEnterButtons(ctx, contact.scene, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
+	warnUnsupportedCommandEnterMarkdowns(ctx, contact.scene, grouping.markdowns.map((m) => m.markdown));
 	if (lines.length || grouping.buttons.length || grouping.keyboards.length) {
 		const keyboard = buildKeyboard(grouping);
-		items.push(ctx.super.guild.markdown({ content: lines.join("\n") }, keyboard));
+		const content = lines.length ? lines.join("\n") : BUTTON_ONLY_MARKDOWN;
+		items.push(ctx.super.guild.markdown({ content }, keyboard));
 	}
 	if (!items.length) items.push(ctx.super.guild.text("不支持发送的消息类型"));
 	return flushGuild(ctx, contact, grouping, items);
@@ -989,39 +2114,259 @@ const buildKeyboard = (grouping) => {
 	const rows = [];
 	grouping.buttons.forEach((b) => rows.push(...karinToQQBot(b)));
 	grouping.keyboards.forEach((k) => rows.push(...karinToQQBot(k)));
-	if (!rows.length) return void 0;
-	return { content: { rows } };
+	const normalizedRows = [];
+	let id = 0;
+	for (const row of rows.slice(0, KEYBOARD_MAX_ROWS)) {
+		const buttons = row.buttons.slice(0, KEYBOARD_MAX_BUTTONS_PER_ROW).map((button) => normalizeQQBotButton(button, id++));
+		if (buttons.length) normalizedRows.push({ buttons });
+	}
+	if (!normalizedRows.length) return void 0;
+	return { content: { rows: normalizedRows } };
+};
+/**
+* 频道消息不支持 `enter: true` 直发按钮，只输出提示，不拦截 keyboard 发送。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param scene 频道消息场景。
+* @param buttons 本次消息中的直发指令按钮。
+*/
+const warnUnsupportedCommandEnterButtons = (ctx, scene, buttons) => {
+	if (!buttons.length) return;
+	const names = formatCommandEnterButtonNames(buttons);
+	const name = scene === "guild" ? "频道" : "频道私信";
+	ctx.logger("debug", `${name}不支持 enter: true 直接发送，按钮仍会按原样发送: ${names}`);
+};
+/**
+* 频道消息不支持 `<qqbot-cmd-enter>` 文本链，只输出提示，不拦截 markdown 发送。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param scene 频道消息场景。
+* @param markdowns 本次消息中的 markdown 内容。
+*/
+const warnUnsupportedCommandEnterMarkdowns = (ctx, scene, markdowns) => {
+	if (!markdowns.some(hasCommandEnterTextChain)) return;
+	const name = scene === "guild" ? "频道" : "频道私信";
+	ctx.logger("debug", `${name}不支持 <qqbot-cmd-enter> 直接发送，markdown 仍会按原样发送`);
 };
 const flushGuild = async (ctx, contact, grouping, items) => {
 	const result = ctx.initSendMsgResults();
 	const passive = buildPassiveGuild(grouping);
 	const send = contact.scene === "guild" ? (peer, subPeer, item) => ctx.super.messages.sendChannelMsg(subPeer, item) : (peer, _subPeer, item) => ctx.super.messages.sendDmsMsg(peer, item);
-	let replyHandled = false;
 	for (const item of items) {
 		passive(item);
-		if (!replyHandled && grouping.reply.messageId && !(item instanceof FormData)) {
-			item.message_reference = { message_id: grouping.reply.messageId };
-			replyHandled = true;
-		}
 		const res = await send(contact.peer, contact.subPeer, item);
 		result.rawData.push(res);
 	}
 	return ctx.handleResponse(result);
 };
+/**
+* 解析频道/私信场景的被动回复来源。
+*
+* openclaw 的 qqbot 适配器对 channel/dm 也只传 `msg_id`。这里让显式
+* `segment.reply` 优先，其次使用事件入口追加的 pasmsg。
+*
+* @param grouping 已归类的消息段。
+* @returns 被动回复来源；没有可用来源时返回 undefined。
+*/
+const resolvePassiveGuild = (grouping) => {
+	if (grouping.reply.messageId) return {
+		type: "msg",
+		id: grouping.reply.messageId
+	};
+	if (grouping.pasmsg.id) return grouping.pasmsg;
+};
+/**
+* 构造频道/私信被动消息附加器。
+*
+* @param grouping 已归类的消息段。
+* @returns 可直接修改发送体或 FormData 的附加函数。
+*/
 const buildPassiveGuild = (grouping) => {
-	if (!grouping.pasmsg.id) return (_item) => void 0;
-	if (grouping.pasmsg.type === "event") return (item) => {
-		if (item instanceof FormData) item.append("event_id", grouping.pasmsg.id);
-		else item.event_id = grouping.pasmsg.id;
+	const source = resolvePassiveGuild(grouping);
+	if (!source?.id) return (_item) => void 0;
+	if (source.type === "event") return (item) => {
+		if (item instanceof FormData) item.append("event_id", source.id);
+		else item.event_id = source.id;
 	};
 	return (item) => {
-		if (item instanceof FormData) item.append("msg_id", grouping.pasmsg.id);
-		else item.msg_id = grouping.pasmsg.id;
+		if (item instanceof FormData) item.append("msg_id", source.id);
+		else item.msg_id = source.id;
+	};
+};
+
+//#endregion
+//#region src/core/adapter/self-message-cache.ts
+/**
+* 只有两个缓存开关同时开启时才需要等待发送结果并缓存自己消息。
+*/
+const shouldCacheSelfMessage = (ctx) => {
+	return ctx.cfg.messageCache.enable && ctx.cfg.messageCache.self;
+};
+/**
+* 预处理自己消息元素。
+*
+* 静态资源只在这里转一次 HTTP URL，之后发送 pipeline 和缓存都复用该 URL。
+*/
+const prepareSelfMessageCache = async (ctx, elements) => {
+	const sendElements = [];
+	const cacheElements = [];
+	for (const element of elements) {
+		const prepared = await prepareSelfCacheElement(ctx, element);
+		sendElements.push(prepared.send);
+		if (prepared.cache) cacheElements.push(prepared.cache);
+	}
+	return {
+		sendElements,
+		cacheElements
 	};
 };
+/**
+* 发送成功后缓存机器人自己的消息，供 bot.getMsg(messageId) 查询。
+*/
+const cacheSelfMessage = (ctx, contact, cacheElements, result) => {
+	if (!shouldCacheSelfMessage(ctx)) return;
+	if (!cacheElements.length) return;
+	const responses = (Array.isArray(result.rawData) ? result.rawData : [result.rawData]).filter((item) => item?.id);
+	if (!responses.length) return;
+	const sender = selfSender(ctx, contact);
+	const seen = /* @__PURE__ */ new Set();
+	for (const response of responses) {
+		const apiMessageId = String(response.id);
+		const referenceMessageId = typeof response.ext_info?.ref_idx === "string" ? response.ext_info.ref_idx : "";
+		const messageId = apiMessageId;
+		const aliases = [referenceMessageId].filter((id) => id && id !== messageId);
+		if (!messageId || seen.has(messageId)) continue;
+		seen.add(messageId);
+		if (referenceMessageId) rememberApiMessageId(ctx, contact, referenceMessageId, apiMessageId);
+		ctx.messageStore.save(String(ctx.cfg.appId), {
+			messageId,
+			messageSeq: 0,
+			time: responseTime(response.timestamp),
+			contact,
+			sender,
+			elements: cacheElements
+		}, aliases).catch((err) => ctx.logger("warn", `[getMsg] 写入自己消息缓存失败: ${messageId}`, err));
+	}
+};
+/**
+* 转换单个自己消息元素为缓存安全形态。
+*/
+const prepareSelfCacheElement = async (ctx, element) => {
+	switch (element.type) {
+		case "text":
+		case "at":
+		case "reply":
+		case "face":
+		case "markdown": {
+			const cached = { ...element };
+			return {
+				send: cached,
+				cache: cached
+			};
+		}
+		case "image":
+		case "video":
+		case "record":
+		case "file": return prepareStaticElement(ctx, element);
+		default: return {
+			send: element,
+			cache: null
+		};
+	}
+};
+/**
+* 静态资源统一转 HTTP URL 后再缓存；转换失败时跳过该元素。
+*/
+const prepareStaticElement = async (ctx, element) => {
+	if (element.file.startsWith("http")) {
+		const cached = { ...element };
+		return {
+			send: cached,
+			cache: cached
+		};
+	}
+	try {
+		switch (element.type) {
+			case "image": {
+				const res = await fileToUrl("image", element.file, element.name || "image.jpg");
+				const cached = {
+					...element,
+					file: res.url,
+					width: res.width,
+					height: res.height
+				};
+				return {
+					send: cached,
+					cache: cached
+				};
+			}
+			case "video": {
+				const res = await fileToUrl("video", element.file, element.name || "video.mp4");
+				const cached = {
+					...element,
+					file: res.url
+				};
+				return {
+					send: cached,
+					cache: cached
+				};
+			}
+			case "record": {
+				const res = await fileToUrl("record", element.file, element.name || "record.mp3");
+				const cached = {
+					...element,
+					file: res.url
+				};
+				return {
+					send: cached,
+					cache: cached
+				};
+			}
+			case "file": {
+				const res = await fileToUrl("file", element.file, element.name || "file.bin");
+				const cached = {
+					...element,
+					file: res.url
+				};
+				return {
+					send: cached,
+					cache: cached
+				};
+			}
+		}
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		ctx.logger("debug", `[getMsg] 跳过自己消息资源缓存: ${element.type} ${message}`);
+		return {
+			send: element,
+			cache: null
+		};
+	}
+};
+/**
+* 构造机器人自己的 sender。
+*/
+const selfSender = (ctx, contact) => {
+	const userId = ctx.selfSubId("id") || ctx.selfId;
+	const name = ctx.selfName || ctx.cfg.name || "";
+	if (contact.scene === "friend" || contact.scene === "direct") return karin$1.friendSender(userId, name);
+	return karin$1.groupSender(userId, "member", name);
+};
+/**
+* QQ / 频道发送接口 timestamp 格式不同，统一转成毫秒时间戳。
+*/
+const responseTime = (timestamp) => {
+	if (typeof timestamp === "string") {
+		const time = new Date(timestamp).getTime();
+		return Number.isFinite(time) ? time : Date.now();
+	}
+	if (typeof timestamp === "number") return timestamp < 0xe8d4a51000 ? timestamp * 1e3 : timestamp;
+	return Date.now();
+};
 
 //#endregion
 //#region src/core/adapter/base.ts
+const adapterConfigStore = /* @__PURE__ */ new WeakMap();
 /**
 * QQ Official Bot 适配器
 *
@@ -1031,19 +2376,27 @@ const buildPassiveGuild = (grouping) => {
 var AdapterQQBot = class extends AdapterBase {
 	/** 与官方 API 交互 */
 	super;
-	/** 当前 bot 配置 */
-	cfg;
 	/** openId / member_openid -> 昵称 缓存 */
 	nicknameCache = /* @__PURE__ */ new Map();
 	constructor(cfg, api) {
 		super();
-		this.cfg = cfg;
+		adapterConfigStore.set(this, cfg);
 		this.super = api;
 		this.adapter.name = "QQ Official Bot";
 		this.adapter.protocol = "qqbot";
 		this.adapter.platform = "qq";
 		this.adapter.standard = "other";
 	}
+	/** 当前 bot 配置。真实配置存放在 WeakMap，避免被系统接口序列化整个适配器时带出。 */
+	get cfg() {
+		const cfg = adapterConfigStore.get(this);
+		if (!cfg) throw new Error("QQBot adapter config missing");
+		return cfg;
+	}
+	/** 接收消息的一天热缓存 + SQLite 缓存，用于实现 Karin 标准 `getMsg`。 */
+	get messageStore() {
+		return getMessageStore();
+	}
 	logger(level, ...args) {
 		logger.bot(level, this.selfId, ...args);
 	}
@@ -1051,26 +2404,46 @@ var AdapterQQBot = class extends AdapterBase {
 	* 主消息回复入口（karin 调用）
 	*/
 	async srcReply(e, elements) {
-		const extra = this.cfg.keyboard.enable ? await buttonHandle(e.msg, { e }) : [];
+		const extra = await buttonHandle(e.msg, { e });
 		return this.sendMsg(e.contact, [...elements, ...extra]);
 	}
 	/**
 	* 发送消息
 	*/
 	async sendMsg(contact, elements, _retryCount) {
-		if (contact.scene === "direct" || contact.scene === "guild") return sendGuild(this, contact, elements);
-		if (contact.scene === "group" || contact.scene === "friend") return sendQQ(this, contact, elements);
+		if (contact.scene === "direct" || contact.scene === "guild") {
+			if (!shouldCacheSelfMessage(this)) return sendGuild(this, contact, elements);
+			const prepared = await prepareSelfMessageCache(this, elements);
+			const result = await sendGuild(this, contact, prepared.sendElements);
+			cacheSelfMessage(this, contact, prepared.cacheElements, result);
+			return result;
+		}
+		if (contact.scene === "group" || contact.scene === "friend") {
+			if (!shouldCacheSelfMessage(this)) return sendQQ(this, contact, elements);
+			const prepared = await prepareSelfMessageCache(this, elements);
+			const result = await sendQQ(this, contact, prepared.sendElements);
+			cacheSelfMessage(this, contact, prepared.cacheElements, result);
+			return result;
+		}
 		throw new Error(`不支持的消息场景: ${contact.scene}`);
 	}
 	/**
 	* 撤回消息
+	*
+	* 群聊中机器人被群主设为管理员后，也可撤回成员消息；平台仍限制消息发送后两分钟内。
 	*/
 	async recallMsg(contact, messageId) {
+		const apiMessageId = resolveApiMessageId(this, contact, messageId);
 		try {
-			if (contact.scene === "friend") await this.super.messages.recall("user", contact.peer, messageId);
-			else if (contact.scene === "group") await this.super.messages.recall("group", contact.peer, messageId);
-			else if (contact.scene === "direct") await this.super.messages.recall("dms", contact.peer, messageId);
-			else if (contact.scene === "guild") await this.super.messages.recall("channels", contact.peer, messageId);
+			if (contact.scene === "friend") {
+				if (!isOwnMessageId(this, contact, apiMessageId)) {
+					this.logger("warn", `[recallMsg] QQ 单聊只能撤回机器人自己发送的消息，已跳过撤回: ${messageId}`);
+					return;
+				}
+				await this.super.messages.recall("user", contact.peer, apiMessageId);
+			} else if (contact.scene === "group") await this.super.messages.recall("group", contact.peer, apiMessageId);
+			else if (contact.scene === "direct") await this.super.messages.recall("dms", contact.peer, apiMessageId);
+			else if (contact.scene === "guild") await this.super.messages.recall("channels", contact.peer, apiMessageId);
 		} catch (err) {
 			logger.error("撤回消息失败:", err);
 		}
@@ -1187,20 +2560,54 @@ var AdapterQQBot = class extends AdapterBase {
 		return `https://p.qlogo.cn/gh/${_groupId}/${_groupId}/${_size || 100}`;
 	}
 	/**
-	* 获取消息
+	* 按消息 ID 获取已接收的消息。
+	*
+	* QQ 官方 Bot API 没有历史消息查询接口，因此仅从本地缓存读取。
+	* 消息在接收时已转换为 Karin elements，最长保留一天；引用消息的 `REFIDX`
+	* 索引同样可作为 `messageId` 查询。
+	*
+	* @param input OneBot v11 标准单参 messageId，或用于限定查询范围的 Contact。
+	* @param messageId 当 input 是 Contact 时传入的目标消息 ID。
+	* @returns 命中的消息；未命中时返回空消息结构。
 	*/
-	async getMsg(_contact, _messageId) {
-		this.logger("warn", "[getMsg] QQ Official Bot API 暂不支持获取消息内容");
+	async getMsg(input, messageId) {
+		/** OneBot v11 标准单参形式：bot.getMsg(messageId)。 */
+		const targetId = typeof input === "string" ? input : messageId || "";
+		const contact = typeof input === "string" ? void 0 : input;
+		if (!this.cfg.messageCache.enable) {
+			this.logger("debug", `[getMsg] 消息缓存已关闭: ${targetId || "(empty)"}`);
+			return {
+				time: 0,
+				messageId: targetId,
+				messageSeq: 0,
+				contact: contact || {
+					scene: "group",
+					peer: "",
+					subPeer: "",
+					name: ""
+				},
+				sender: {
+					userId: "",
+					nick: "",
+					name: "",
+					role: "member"
+				},
+				elements: []
+			};
+		}
+		const cached = await this.messageStore.get(String(this.cfg.appId), targetId, contact);
+		if (cached) return cached;
+		this.logger("debug", `[getMsg] 本地一天消息缓存未命中: ${targetId || "(empty)"}`);
 		return {
 			time: 0,
-			messageId: _messageId || "",
+			messageId: targetId,
 			messageSeq: 0,
-			contact: typeof _contact === "string" ? {
+			contact: contact || {
 				scene: "group",
-				peer: _contact,
+				peer: "",
 				subPeer: "",
 				name: ""
-			} : _contact,
+			},
 			sender: {
 				userId: "",
 				nick: "",
@@ -1211,9 +2618,18 @@ var AdapterQQBot = class extends AdapterBase {
 		};
 	}
 	/** @internal */
-	async getHistoryMsg(_contact, _start, _count) {
-		this.logger("warn", "[getHistoryMsg] QQ Official Bot API 暂不支持获取历史消息");
-		return [];
+	async getHistoryMsg(contact, start, count = 1) {
+		if (typeof start === "number") {
+			this.logger("warn", "[getHistoryMsg] QQ Official Bot 仅支持通过 message_id 获取历史消息，不支持 message_seq");
+			return [];
+		}
+		if (!this.cfg.messageCache.enable) {
+			this.logger("warn", "[getHistoryMsg] 历史消息缓存为空，请打开“启用数据库缓存消息”开关后再记录历史消息");
+			return [];
+		}
+		const history = await this.messageStore.getHistory(String(this.cfg.appId), contact, start, count);
+		if (!history.length) this.logger("debug", `[getHistoryMsg] 本地一天历史消息缓存未命中: ${start || "(empty)"}`);
+		return history;
 	}
 	/**
 	* 获取合并转发消息
@@ -1571,6 +2987,94 @@ var AdapterQQBot = class extends AdapterBase {
 //#region src/core/event/conver.ts
 /** 反转义 HTML 实体 */
 const unescape = (text) => text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+/** 从 QQ `message_scene.ext` 中提取消息索引。 */
+const getMessageSceneIndex = (scene, key) => {
+	const prefix = `${key}=`;
+	return scene?.ext?.find((item) => item.startsWith(prefix))?.slice(prefix.length) || "";
+};
+/** 原生 Markdown 不能从 QQ 回显中完全区分，只识别适配器发送后可稳定还原的常用语法。 */
+const isNativeMarkdown = (text) => {
+	return /(^|\n)\s{0,3}(?:#{1,6}\s|[-*+]\s|\d+\.\s|>\s)|\*\*|__|~~|`{1,3}|\[[^\]]+\]\([^\s)]+\)|(^|\n)\s*\|.+\|\s*\n\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?/m.test(text);
+};
+/** 将非图片 Markdown 片段恢复为 text 或 markdown 元素。 */
+const pushMarkdownText = (text, elements) => {
+	if (!text) return;
+	elements.push(isNativeMarkdown(text) ? segment.markdown(text) : segment.text(text));
+};
+/**
+* 反向解析适配器发送的 QQ Markdown。
+*
+* 发送侧会将 Karin 图片编码为 `![名称 #宽px #高px](URL)`，并以换行拼接文本、
+* 图片和原生 Markdown；这里按原顺序恢复为 Karin `text`、`image`、`markdown`。
+*/
+const pushQQMarkdown = (text, elements) => {
+	const imageReg = /!\[([^\]]*)\]\((https?:\/\/[^\s)]+)\)/g;
+	let lastIndex = 0;
+	let matched = false;
+	let match;
+	while (match = imageReg.exec(text)) {
+		matched = true;
+		if (match.index > lastIndex) pushMarkdownText(text.slice(lastIndex, match.index), elements);
+		const alt = match[1];
+		const dimension = alt.match(/\s+#(\d+)px\s+#(\d+)px\s*$/);
+		const name = alt.replace(/\s+#\d+px\s+#\d+px\s*$/, "") || "图片";
+		elements.push(segment.image(match[2], {
+			name,
+			width: dimension ? Number(dimension[1]) : void 0,
+			height: dimension ? Number(dimension[2]) : void 0
+		}));
+		lastIndex = imageReg.lastIndex;
+	}
+	if (matched && lastIndex < text.length) pushMarkdownText(text.slice(lastIndex), elements);
+	return matched;
+};
+/**
+* 只拆 QQ 协议标签，保留普通文本中的 HTML/Markdown 片段。
+*
+* 普通文本或 Markdown 里可能包含 `<br>`、`<table>` 等内容；如果用 `[^<]+`
+* 直接切分，会把这些内容误当成协议标签边界，导致一条文本被拆成多段甚至丢失 `<`。
+*/
+const tokenizeContent = (content = "") => {
+	const tokens = [];
+	const knownTag = /<faceType=\d+,faceId="[^"]*",ext="[^"]*">|<qqbot-at-user id="[^"]+"\s*\/?>|<qqbot-at-everyone\s*\/?>|<@!?[A-Za-z0-9]+>/g;
+	let lastIndex = 0;
+	let match;
+	while (match = knownTag.exec(content)) {
+		if (match.index > lastIndex) tokens.push(content.slice(lastIndex, match.index));
+		tokens.push(match[0]);
+		lastIndex = knownTag.lastIndex;
+	}
+	if (lastIndex < content.length) tokens.push(content.slice(lastIndex));
+	return tokens;
+};
+/**
+* 判断 QQ 回显内容是否应恢复成 Karin markdown 段。
+*
+* QQBot 自己收到自己发出的 markdown 时可能是 `message_type=103`；收到其他
+* QQBot 发出的 markdown 时，官方报文仍可能给 `message_type=0`，只能结合
+* `author.bot` 与内容语法做保守识别。
+*/
+const shouldUseMarkdown = (messageType, fromBot, text) => {
+	return (messageType === 103 || fromBot) && isNativeMarkdown(text);
+};
+/**
+* 从 QQ 表情标签的 base64 ext 中提取可读文本。
+*
+* faceType=4 的表情包套图没有图片附件，只能通过 ext 中的 JSON 文本展示。
+*
+* @param ext QQ 表情标签里的 base64 字段。
+* @returns ext JSON 中的 text；解析失败时返回空字符串。
+*/
+const getFaceExtText = (ext) => {
+	if (!ext) return "";
+	try {
+		const decoded = Buffer.from(ext, "base64").toString("utf-8");
+		const payload = JSON.parse(decoded);
+		return typeof payload.text === "string" ? payload.text : "";
+	} catch {
+		return "";
+	}
+};
 /**
 * QQ Bot 报文 → karin elements
 *
@@ -1582,17 +3086,39 @@ const unescape = (text) => text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").rep
 const convertToKarin = (appid, ev, selfSubId, options = {}) => {
 	const elements = [];
 	const data = ev.d;
+	const messageType = "message_type" in data ? data.message_type : void 0;
+	const fromBot = !!data.author?.bot;
 	/** mentions 索引 id -> displayName */
 	const mentionMap = /* @__PURE__ */ new Map();
+	const selfMentionIds = new Set([appid, selfSubId].filter(Boolean));
 	if (ev.t === "MESSAGE_CREATE" || ev.t === "AT_MESSAGE_CREATE") ev.d.mentions?.forEach((v) => {
 		mentionMap.set(v.id, v.username);
+		if (v.id === selfSubId) selfMentionIds.add(v.id);
 	});
 	else if (ev.t === "GROUP_MESSAGE_CREATE" || ev.t === "GROUP_AT_MESSAGE_CREATE") ev.d.mentions?.forEach((v) => {
 		mentionMap.set(v.id, v.username);
 		mentionMap.set(v.member_openid, v.username);
+		if (v.is_you) {
+			selfMentionIds.add(v.id);
+			selfMentionIds.add(v.member_openid);
+		}
 	});
-	/** 附件 */
-	for (const v of data.attachments || []) {
+	const isSelfAt = (element) => element.type === "at" && selfMentionIds.has(element.targetId);
+	const hasSelfAt = () => elements.some(isSelfAt);
+	const pushAt = (id, name = "") => {
+		const targetId = selfMentionIds.has(id) ? appid : id;
+		if (targetId === appid && hasSelfAt()) {
+			const prev = elements.at(-1);
+			const beforePrev = elements.at(-2);
+			if (prev?.type === "text" && !prev.text.trim() && beforePrev && isSelfAt(beforePrev)) elements.pop();
+			return;
+		}
+		elements.push(segment.at(targetId, name));
+	};
+	/** 将 QQ 附件转换为 Karin 元素。 */
+	const attachments = data.attachments || [];
+	let attachmentIndex = 0;
+	const pushAttachment = (v) => {
 		const url = v.url.startsWith("http") ? v.url : `https://${v.url}`;
 		if (v.content_type.startsWith("image/")) elements.push(segment.image(url, {
 			subType: v.content_type.split("/")[1],
@@ -1602,29 +3128,49 @@ const convertToKarin = (appid, ev, selfSubId, options = {}) => {
 		}));
 		else if (v.content_type === "video/mp4") elements.push(segment.video(url));
 		else if (v.content_type === "voice") elements.push(segment.record(v.voice_wav_url || url));
-		else if (v.content_type === "file") elements.push(segment.json(JSON.stringify({
-			type: "file",
-			attachment: v
-		})));
-	}
-	const tokens = data?.content?.match(/<faceType=\d+,faceId="\d+",ext="[^"]+">|<@!\d+>|<qqbot-at-user id="[^"]+"\s*\/?>|<qqbot-at-everyone\s*\/?>|[^<]+/g) || [];
+		else if (v.content_type === "file") elements.push(segment.file(url, {
+			name: v.filename,
+			size: v.size
+		}));
+	};
+	/** content 解析 */
+	const tokens = tokenizeContent(data?.content);
 	const cfg = getConfig(appid);
 	for (const tok of tokens) {
 		if (tok.startsWith("<faceType=")) {
-			const m = tok.match(/faceId="(\d+)"/);
-			if (m) elements.push(segment.face(Number(m[1])));
+			const m = tok.match(/faceType=(\d+),faceId="([^"]*)",ext="([^"]*)"/);
+			const faceType = Number(m?.[1]);
+			const faceIdText = m?.[2] || "";
+			const faceId = Number(faceIdText);
+			const attachment = attachments[attachmentIndex];
+			if (!faceIdText) {
+				if (attachment?.content_type.startsWith("image/")) {
+					pushAttachment(attachment);
+					attachmentIndex++;
+				} else {
+					const text = getFaceExtText(m?.[3] || "");
+					if (text) elements.push(segment.text(text));
+				}
+				continue;
+			}
+			/**
+			* QQ 将用户收藏表情图片编码为 `faceId=0` + 图片附件。附件在 content 中
+			* 没有独立标签，必须在这个占位符位置消费，才能保留原始元素顺序。
+			*/
+			if (faceId === 0 && (messageType === 103 || faceType === 6) && attachment?.content_type.startsWith("image/")) {
+				pushAttachment(attachment);
+				attachmentIndex++;
+			} else if (faceType === 6 && faceId === 0) {} else if (m) elements.push(segment.face(faceId, faceType === 3));
 			continue;
 		}
-		if (tok.startsWith("<@!")) {
-			const id = tok.replace(/^<@!|>$/g, "");
-			const name = mentionMap.get(id) || "";
-			elements.push(segment.at(id === selfSubId ? appid : id, name));
+		if (tok.startsWith("<@")) {
+			const id = tok.replace(/^<@!?|>$/g, "");
+			pushAt(id, mentionMap.get(id) || "");
 			continue;
 		}
 		if (tok.startsWith("<qqbot-at-user")) {
 			const id = tok.match(/id="([^"]+)"/)?.[1] || "";
-			const name = mentionMap.get(id) || "";
-			elements.push(segment.at(id === selfSubId ? appid : id, name));
+			pushAt(id, mentionMap.get(id) || "");
 			continue;
 		}
 		if (tok.startsWith("<qqbot-at-everyone")) {
@@ -1634,10 +3180,18 @@ const convertToKarin = (appid, ev, selfSubId, options = {}) => {
 		let text = unescape(tok);
 		if (cfg?.regex) for (const r of cfg.regex) {
 			const reg = r.reg instanceof RegExp ? r.reg : new RegExp(r.reg);
-			text = text.trim().replace(reg, r.rep);
+			text = text.replace(reg, r.rep);
+		}
+		if (!text) continue;
+		if (messageType === 103 && pushQQMarkdown(text, elements)) continue;
+		if (shouldUseMarkdown(messageType, fromBot, text)) {
+			elements.push(segment.markdown(text));
+			continue;
 		}
 		elements.push(segment.text(text));
 	}
+	/** content 中未出现占位符的普通附件，按 QQ 报文顺序追加。 */
+	for (; attachmentIndex < attachments.length; attachmentIndex++) pushAttachment(attachments[attachmentIndex]);
 	/** 群消息是否需要在头部补 self at */
 	if (ev.t === "GROUP_AT_MESSAGE_CREATE" || ev.t === "GROUP_MESSAGE_CREATE") {
 		const youMention = (ev.d.mentions || []).find((m) => m.is_you);
@@ -1647,10 +3201,60 @@ const convertToKarin = (appid, ev, selfSubId, options = {}) => {
 	}
 	return elements;
 };
+/**
+* 将 QQ 引用上下文转换为 Karin 元素。
+*
+* QQ 不会提供引用消息的正式消息 ID；调用方应以 `msg_idx` 作为缓存键。
+*/
+const convertReferenceToKarin = (appid, ev, selfSubId, reference) => {
+	return convertToKarin(appid, {
+		...ev,
+		d: {
+			...ev.d,
+			content: reference.content,
+			attachments: reference.attachments,
+			mentions: void 0,
+			message_scene: void 0,
+			msg_elements: void 0,
+			message_type: reference.message_type
+		}
+	}, selfSubId);
+};
 
 //#endregion
 //#region src/core/event/message.ts
 /**
+* 写入 getMsg 热缓存并投递 SQLite 后台队列。
+*
+* 不等待数据库落库，避免缓存特性拖慢 Karin 消息事件下发。
+*
+* @param client 当前 QQBot 适配器实例。
+* @param message 需要缓存的消息快照。
+* @param aliases 可用于查询同一消息的 QQ 侧索引，例如 msg_idx。
+*/
+const cacheMessage = (client, message, aliases = []) => {
+	if (!client.cfg.messageCache.enable) return;
+	client.messageStore.save(String(client.cfg.appId), {
+		...message,
+		messageSeq: 0
+	}, aliases).catch((err) => log("warn", `[getMsg] 写入消息缓存失败: ${message.messageId}`, err));
+};
+/**
+* 写入引用消息上下文缓存。
+*
+* 引用上下文没有正式消息 ID 时，以 QQ 的 `ref_msg_idx` 建立只写入一次的缓存。
+*
+* @param client 当前 QQBot 适配器实例。
+* @param message 以 ref_msg_idx 作为 messageId 的引用消息快照。
+*/
+const cacheReference = (client, message) => {
+	if (!client.cfg.messageCache.enable) return;
+	client.messageStore.saveReferenceIfAbsent(String(client.cfg.appId), {
+		...message,
+		messageSeq: 0
+	}).catch((err) => log("warn", `[getMsg] 写入引用上下文失败: ${message.messageId}`, err));
+};
+/**
 * 群消息（@机器人 / 普通消息合并入口）
 */
 const onGroupMsg = (client, ev, opts) => {
@@ -1661,16 +3265,38 @@ const onGroupMsg = (client, ev, opts) => {
 	ev.d.mentions?.forEach((m) => {
 		if (m.member_openid && m.username) client.nicknameCache.set(m.member_openid, m.username);
 	});
-	const contact = karin.contactGroup(ev.d.group_openid || ev.d.group_id);
-	const sender = karin.groupSender(userId, "member", username);
+	const contact = karin$1.contactGroup(ev.d.group_openid || ev.d.group_id);
+	const sender = karin$1.groupSender(userId, ev.d.author.member_role || "unknown", username);
+	const elements = convertToKarin(selfId, ev, client.selfSubId("id"), { forceAtSelf: opts.forceAtSelf });
+	const messageIndex = getMessageSceneIndex(ev.d.message_scene, "msg_idx");
+	const referenceIndex = getMessageSceneIndex(ev.d.message_scene, "ref_msg_idx");
+	const karinMessageId = ev.d.id;
+	if (messageIndex) rememberApiMessageId(client, contact, messageIndex, ev.d.id);
+	if (referenceIndex) elements.unshift(segment.reply(referenceIndex));
+	const time = Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp);
+	cacheMessage(client, {
+		messageId: karinMessageId,
+		time,
+		contact,
+		sender,
+		elements
+	}, [ev.d.id, messageIndex].filter((id) => !!id && id !== karinMessageId && id !== referenceIndex));
+	const reference = ev.d.msg_elements?.find((item) => item.msg_idx === referenceIndex);
+	if (reference && referenceIndex) cacheReference(client, {
+		messageId: referenceIndex,
+		time,
+		contact,
+		sender: karin$1.groupSender("", "member", reference.author?.username || ""),
+		elements: convertReferenceToKarin(selfId, ev, client.selfSubId("id"), reference)
+	});
 	const e = createGroupMessage({
 		bot: client,
-		elements: convertToKarin(selfId, ev, client.selfSubId("id"), { forceAtSelf: opts.forceAtSelf }),
+		elements,
 		eventId: ev.id,
-		messageId: ev.d.id,
+		messageId: karinMessageId,
 		messageSeq: 0,
 		rawEvent: ev,
-		time: Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp),
+		time,
 		contact,
 		sender,
 		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
@@ -1685,16 +3311,38 @@ const onFriendMsg = (client, ev) => {
 	const userId = ev.d.author.user_openid || ev.d.author.id;
 	const username = ev.d.author.username || "";
 	if (userId && username) client.nicknameCache.set(userId, username);
-	const contact = karin.contactFriend(userId);
-	const sender = karin.friendSender(userId, username);
+	const contact = karin$1.contactFriend(userId);
+	const sender = karin$1.friendSender(userId, username);
+	const elements = convertToKarin(selfId, ev, client.selfSubId("id"));
+	const messageIndex = getMessageSceneIndex(ev.d.message_scene, "msg_idx");
+	const referenceIndex = getMessageSceneIndex(ev.d.message_scene, "ref_msg_idx");
+	const karinMessageId = ev.d.id;
+	if (messageIndex) rememberApiMessageId(client, contact, messageIndex, ev.d.id);
+	if (referenceIndex) elements.unshift(segment.reply(referenceIndex));
+	const time = Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp);
+	cacheMessage(client, {
+		messageId: karinMessageId,
+		time,
+		contact,
+		sender,
+		elements
+	}, [ev.d.id, messageIndex].filter((id) => !!id && id !== karinMessageId && id !== referenceIndex));
+	const reference = ev.d.msg_elements?.find((item) => item.msg_idx === referenceIndex);
+	if (reference && referenceIndex) cacheReference(client, {
+		messageId: referenceIndex,
+		time,
+		contact,
+		sender: karin$1.friendSender("", reference.author?.username || ""),
+		elements: convertReferenceToKarin(selfId, ev, client.selfSubId("id"), reference)
+	});
 	const e = createFriendMessage({
 		bot: client,
-		elements: convertToKarin(selfId, ev, client.selfSubId("id")),
+		elements,
 		eventId: ev.id,
-		messageId: ev.d.id,
+		messageId: karinMessageId,
 		messageSeq: 0,
 		rawEvent: ev,
-		time: Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp),
+		time,
 		contact,
 		sender,
 		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
@@ -1707,16 +3355,25 @@ const onFriendMsg = (client, ev) => {
 const onChannelMsg = (client, ev) => {
 	const selfId = client.selfId;
 	const userId = ev.d.author.id;
-	const contact = karin.contact("guild", ev.d.guild_id, ev.d.channel_id);
-	const sender = karin.groupSender(userId, "unknown", ev.d.author.username || "");
+	const contact = karin$1.contact("guild", ev.d.guild_id, ev.d.channel_id);
+	const sender = karin$1.groupSender(userId, "unknown", ev.d.author.username || "");
+	const elements = convertToKarin(selfId, ev, client.selfSubId("id"));
+	const time = Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp);
+	cacheMessage(client, {
+		messageId: ev.d.id,
+		time,
+		contact,
+		sender,
+		elements
+	});
 	const e = createGuildMessage({
 		bot: client,
-		elements: convertToKarin(selfId, ev, client.selfSubId("id")),
+		elements,
 		eventId: ev.id,
 		messageId: ev.d.id,
 		messageSeq: 0,
 		rawEvent: ev,
-		time: Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp),
+		time,
 		contact,
 		sender,
 		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
@@ -1729,16 +3386,25 @@ const onChannelMsg = (client, ev) => {
 const onDirectMsg = (client, ev) => {
 	const selfId = client.selfId;
 	const userId = ev.d.author.id;
-	const contact = karin.contact("direct", ev.d.guild_id, ev.d.channel_id);
-	const sender = karin.friendSender(userId, ev.d.author.username || "");
+	const contact = karin$1.contact("direct", ev.d.guild_id, ev.d.channel_id);
+	const sender = karin$1.friendSender(userId, ev.d.author.username || "");
+	const elements = convertToKarin(selfId, ev, client.selfSubId("id"));
+	const time = Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp);
+	cacheMessage(client, {
+		messageId: ev.d.id,
+		time,
+		contact,
+		sender,
+		elements
+	});
 	const e = createDirectMessage({
 		bot: client,
-		elements: convertToKarin(selfId, ev, client.selfSubId("id")),
+		elements,
 		eventId: ev.id,
 		messageId: ev.d.id,
 		messageSeq: 0,
 		rawEvent: ev,
-		time: Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp),
+		time,
 		contact,
 		sender,
 		srcGuildId: ev.d.src_guild_id,
@@ -1758,8 +3424,8 @@ const onGroupAddRobot = (client, event) => {
 	const selfId = client.selfId;
 	const userId = event.d.op_member_openid;
 	const groupId = event.d.group_openid;
-	const contact = karin.contactGroup(groupId);
-	const sender = karin.groupSender(userId, "unknown");
+	const contact = karin$1.contactGroup(groupId);
+	const sender = karin$1.groupSender(selfId, "member");
 	const eventId = event.id;
 	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
 	createGroupMemberAddNotice({
@@ -1786,8 +3452,8 @@ const onGroupDelRobot = (client, event) => {
 	const selfId = client.selfId;
 	const userId = event.d.op_member_openid;
 	const groupId = event.d.group_openid;
-	const contact = karin.contactGroup(groupId);
-	const sender = karin.groupSender(userId, "unknown");
+	const contact = karin$1.contactGroup(groupId);
+	const sender = karin$1.groupSender(selfId, "unknown");
 	const eventId = event.id;
 	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
 	createGroupMemberDelNotice({
@@ -1806,6 +3472,64 @@ const onGroupDelRobot = (client, event) => {
 	});
 };
 /**
+* 群成员加入事件。
+*
+* QQ 官方仅下发加入成员，未提供操作人和加入方式；Karin 的通知模型要求
+* `type`，因此以 `approve` 表示已加入，并将 `operatorId` 留空。
+* 该事件不能作为 QQ 被动消息的 `event_id`，回复会按普通消息发送。
+*
+* @param client 机器人实例
+* @param event 官方群成员加入事件
+*/
+const onGroupMemberAdd = (client, event) => {
+	const memberId = event.d.member_openid;
+	const contact = karin$1.contactGroup(event.d.group_openid);
+	const sender = karin$1.groupSender(memberId, "member");
+	createGroupMemberAddNotice({
+		contact,
+		eventId: event.id,
+		sender,
+		srcReply: (elements) => client.sendMsg(contact, elements),
+		bot: client,
+		rawEvent: event,
+		time: event.d.timestamp,
+		content: {
+			operatorId: "",
+			targetId: memberId,
+			type: "approve"
+		}
+	});
+};
+/**
+* 群成员退出事件。
+*
+* QQ 官方仅下发退出成员，未提供操作人和退出原因；Karin 的通知模型要求
+* `type`，因此以 `leave` 表示成员已离开，并将 `operatorId` 留空。
+* 该事件不能作为 QQ 被动消息的 `event_id`，回复会按普通消息发送。
+*
+* @param client 机器人实例
+* @param event 官方群成员退出事件
+*/
+const onGroupMemberRemove = (client, event) => {
+	const memberId = event.d.member_openid;
+	const contact = karin$1.contactGroup(event.d.group_openid);
+	const sender = karin$1.groupSender(memberId, "unknown");
+	createGroupMemberDelNotice({
+		contact,
+		eventId: event.id,
+		sender,
+		srcReply: (elements) => client.sendMsg(contact, elements),
+		bot: client,
+		rawEvent: event,
+		time: event.d.timestamp,
+		content: {
+			operatorId: "",
+			targetId: memberId,
+			type: "leave"
+		}
+	});
+};
+/**
 * 群聊接受机器人主动消息
 * @param client 机器人实例
 * @param event 事件
@@ -1833,8 +3557,8 @@ const onGroupMsgReject = (client, event) => {
 const onFriendAdd = (client, event) => {
 	const selfId = client.selfId;
 	const userId = event.d.openid;
-	const contact = karin.contactFriend(userId);
-	const sender = karin.friendSender(userId, "");
+	const contact = karin$1.contactFriend(userId);
+	const sender = karin$1.friendSender(userId, "");
 	const eventId = event.id;
 	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
 	createFriendIncreaseNotice({
@@ -1856,8 +3580,8 @@ const onFriendAdd = (client, event) => {
 const onFriendDel = (client, event) => {
 	const selfId = client.selfId;
 	const userId = event.d.openid;
-	const contact = karin.contactFriend(userId);
-	const sender = karin.friendSender(userId, "");
+	const contact = karin$1.contactFriend(userId);
+	const sender = karin$1.friendSender(userId, "");
 	const eventId = event.id;
 	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
 	createFriendDecreaseNotice({
@@ -1893,46 +3617,103 @@ const onC2CMsgReject = (client, event) => {
 //#endregion
 //#region src/core/event/interaction.ts
 /**
+* 取得互动事件真正用于 ACK 的平台 ID。
+*
+* WebSocket Dispatch 外层也有一个 `id`，形如 `INTERACTION_CREATE:uuid`；按钮 ACK
+* 接口需要的是事件体内的 `d.id`，也就是不带事件名前缀的 uuid。
+*
+* @param ev QQBot 原始互动事件。
+* @returns 可传给 `/interactions/{interaction_id}` 的 ID。
+*/
+const getInteractionId = (ev) => ev.d.id || ev.id;
+/**
+* 构造按钮回调附加给 Karin 消息的元信息。
+*
+* QQBot 不同场景下下发字段差异很大：群聊通常只有 button_data/button_id，
+* 频道才可能带 user_id/message_id/feature_id。这里只写入实际存在的字段，
+* 避免插件侧看到一堆语义不明的空值。
+*
+* @param ev QQBot 原始互动事件。
+* @param interactionId 已确认可用于 ACK 的平台互动 ID。
+* @returns 可放入 segment.json 的精简元信息。
+*/
+const createInteractionMeta = (ev, interactionId) => {
+	const resolved = ev.d.data?.resolved;
+	const meta = {
+		tag: "qqbot-button-click",
+		interaction_id: interactionId,
+		dispatch_id: ev.id,
+		interaction_type: ev.d.type
+	};
+	const optional = {
+		data_type: ev.d.data?.type,
+		chat_type: ev.d.chat_type,
+		scene: ev.d.scene,
+		button_id: resolved?.button_id,
+		button_data: resolved?.button_data,
+		application_id: ev.d.application_id,
+		group_openid: ev.d.group_openid,
+		group_member_openid: ev.d.group_member_openid,
+		user_openid: ev.d.user_openid,
+		guild_id: ev.d.guild_id,
+		channel_id: ev.d.channel_id,
+		guild_user_id: resolved?.user_id,
+		feature_id: resolved?.feature_id,
+		message_id: resolved?.message_id,
+		require_mention: resolved?.require_mention,
+		group_policy: resolved?.group_policy,
+		mention_patterns: resolved?.mention_patterns,
+		version: ev.d.version
+	};
+	for (const [key, value] of Object.entries(optional)) if (value !== void 0 && value !== "") meta[key] = value;
+	return meta;
+};
+/**
 * INTERACTION_CREATE 处理
 *
 * - 先 ack 客户端（必须在 3s 内），失败仅 warn
 * - 借用普通消息事件投递给业务层，业务层通过 e.rawEvent.t === 'INTERACTION_CREATE' 区分
-* - elements: [self at] + text(button_data) + json(meta) + pasmsg(event_id, 'event')
+* - elements 只放 button_data 文本，避免 at/json 段污染 e.msg 导致 command 无法精确匹配
 */
 const onInteraction = (client, ev) => {
-	client.super.interaction.ack(ev.id, 0).catch((err) => {
+	const interactionId = getInteractionId(ev);
+	const ackStart = Date.now();
+	client.logger("debug", `[INTERACTION] ack 准备: ${interactionId} dispatch=${ev.id}`);
+	client.super.interaction.ack(interactionId, 0).then(() => {
+		client.logger("debug", `[INTERACTION] ack 成功: ${interactionId} (${Date.now() - ackStart}ms)`);
+	}).catch((err) => {
 		client.logger("warn", "[INTERACTION] ack 失败:", err);
+	}).finally(() => {
+		emitInteractionMessage(client, ev, interactionId);
 	});
-	const selfId = client.selfId;
+};
+/**
+* 将按钮互动事件转换为 Karin 消息事件。
+*
+* ACK 请求先发出并结束后再投递业务层，避免业务回复请求抢在 ACK 前占用回调窗口。
+*
+* @param client 当前 QQBot 适配器实例。
+* @param ev QQBot 原始互动事件。
+* @param interactionId 已确认可用于 ACK 的平台互动 ID。
+*/
+const emitInteractionMessage = (client, ev, interactionId) => {
 	const buttonData = ev.d.data?.resolved?.button_data || "";
-	const meta = segment.json(JSON.stringify({
-		tag: "qqbot-button-click",
-		type: ev.d.type,
-		chat_type: ev.d.chat_type,
-		scene: ev.d.scene,
-		button_id: ev.d.data?.resolved?.button_id,
-		button_data: ev.d.data?.resolved?.button_data,
-		feature_id: ev.d.data?.resolved?.feature_id,
-		message_id: ev.d.data?.resolved?.message_id,
-		user_id: ev.d.data?.resolved?.user_id,
-		version: ev.d.version
-	}));
-	const time = Number(new Date(ev.d.timestamp).getTime() || Date.now());
+	const rawEvent = {
+		...ev,
+		buttonMeta: createInteractionMeta(ev, interactionId)
+	};
+	const time = Number(ev.d.timestamp ? new Date(ev.d.timestamp).getTime() : Date.now()) || Date.now();
 	if (ev.d.chat_type === 1 && ev.d.group_openid) {
 		const userId = ev.d.group_member_openid || "";
-		const contact = karin.contactGroup(ev.d.group_openid);
-		const sender = karin.groupSender(userId, "unknown");
+		const contact = karin$1.contactGroup(ev.d.group_openid);
+		const sender = karin$1.groupSender(userId, "unknown");
 		const e = createGroupMessage({
 			bot: client,
-			elements: [
-				segment.at(selfId),
-				segment.text(buttonData),
-				meta
-			],
+			elements: [segment.text(buttonData)],
 			eventId: ev.id,
-			messageId: ev.id,
+			messageId: interactionId,
 			messageSeq: 0,
-			rawEvent: ev,
+			rawEvent,
 			time,
 			contact,
 			sender,
@@ -1942,19 +3723,15 @@ const onInteraction = (client, ev) => {
 	}
 	if (ev.d.chat_type === 2 && ev.d.user_openid) {
 		const userId = ev.d.user_openid;
-		const contact = karin.contactFriend(userId);
-		const sender = karin.friendSender(userId, "");
+		const contact = karin$1.contactFriend(userId);
+		const sender = karin$1.friendSender(userId, "");
 		const e = createFriendMessage({
 			bot: client,
-			elements: [
-				segment.at(selfId),
-				segment.text(buttonData),
-				meta
-			],
+			elements: [segment.text(buttonData)],
 			eventId: ev.id,
-			messageId: ev.id,
+			messageId: interactionId,
 			messageSeq: 0,
-			rawEvent: ev,
+			rawEvent,
 			time,
 			contact,
 			sender,
@@ -1964,15 +3741,15 @@ const onInteraction = (client, ev) => {
 	}
 	if (ev.d.chat_type === 0 && ev.d.guild_id && ev.d.channel_id) {
 		const userId = ev.d.data?.resolved?.user_id || "";
-		const contact = karin.contact("guild", ev.d.guild_id, ev.d.channel_id);
-		const sender = karin.groupSender(userId, "unknown");
+		const contact = karin$1.contact("guild", ev.d.guild_id, ev.d.channel_id);
+		const sender = karin$1.groupSender(userId, "unknown");
 		const e = createGuildMessage({
 			bot: client,
-			elements: [segment.text(buttonData), meta],
+			elements: [segment.text(buttonData)],
 			eventId: ev.id,
-			messageId: ev.id,
+			messageId: interactionId,
 			messageSeq: 0,
-			rawEvent: ev,
+			rawEvent,
 			time,
 			contact,
 			sender,
@@ -1997,6 +3774,8 @@ const eventLabel = {
 	["DIRECT_MESSAGE_CREATE"]: "频道私信",
 	["GROUP_ADD_ROBOT"]: "机器人入群",
 	["GROUP_DEL_ROBOT"]: "机器人退群",
+	["GROUP_MEMBER_ADD"]: "群成员加入",
+	["GROUP_MEMBER_REMOVE"]: "群成员退出",
 	["GROUP_MSG_RECEIVE"]: "群聊开启通知",
 	["GROUP_MSG_REJECT"]: "群聊关闭通知",
 	["FRIEND_ADD"]: "添加好友",
@@ -2039,6 +3818,12 @@ const dispatch$1 = (client, ev) => {
 		case "GROUP_DEL_ROBOT":
 			onGroupDelRobot(client, ev);
 			return;
+		case "GROUP_MEMBER_ADD":
+			onGroupMemberAdd(client, ev);
+			return;
+		case "GROUP_MEMBER_REMOVE":
+			onGroupMemberRemove(client, ev);
+			return;
 		case "GROUP_MSG_RECEIVE":
 			onGroupMsgReceive(client, ev);
 			return;
@@ -2062,7 +3847,7 @@ const dispatch$1 = (client, ev) => {
 			return;
 		case "MESSAGE_AUDIT_PASS": return client.logger("debug", `消息审核通过: audit_id=${ev.d.audit_id}`);
 		case "MESSAGE_AUDIT_REJECT": return client.logger("debug", `消息审核不通过: audit_id=${ev.d.audit_id}`);
-		default: logger.debug(`[QQ Official Bot] 未处理事件: ${ev.t}`);
+		default: client.logger("debug", `[QQ Official Bot] 未处理事件: ${ev.t}`);
 	}
 };
 
@@ -2105,6 +3890,11 @@ const wsErrorMap = {
 		canResume: false,
 		canIdentify: false
 	},
+	4004: {
+		message: "鉴权失败或 access_token 无效",
+		canResume: false,
+		canIdentify: true
+	},
 	4007: {
 		message: "seq 错误",
 		canResume: false,
@@ -2215,6 +4005,8 @@ var WSClient = class {
 	seq = 0;
 	closed = false;
 	closedReason = "manual";
+	openedAt = 0;
+	lastAuthAction;
 	constructor(opts) {
 		this.opts = opts;
 		if (opts.resume) {
@@ -2230,21 +4022,30 @@ var WSClient = class {
 		};
 	}
 	start() {
-		const ws = new WebSocket(this.opts.gatewayUrl);
+		const ws = new WebSocket(this.opts.gatewayUrl, { headers: { "User-Agent": this.opts.userAgent } });
 		this.socket = ws;
 		ws.on("open", () => {
+			this.openedAt = Date.now();
 			log("debug", `${this.opts.appId}: WebSocket opened (${this.opts.gatewayUrl})`);
 		});
 		ws.on("close", (code, reason) => {
-			const closeInfo = formatWSClose(code, reason?.toString() || "(empty)");
+			const remoteReason = reason?.toString() || "";
+			const closeInfo = formatWSClose(code, remoteReason);
+			const info = getWSErrorInfo(code);
 			log("error", `${this.opts.appId}: WebSocket 关闭 | ${closeInfo}`);
 			if (this.closed) return;
-			this.close("closed");
+			this.close("closed", {
+				code,
+				remoteReason: remoteReason || void 0,
+				durationMs: this.durationMs(),
+				canResume: info?.canResume,
+				canIdentify: info?.canIdentify
+			});
 		});
 		ws.on("error", (err) => {
 			log("error", `${this.opts.appId}: WebSocket error:`, err);
 			if (this.closed) return;
-			this.close("error");
+			this.close("error", { durationMs: this.durationMs() });
 		});
 		ws.on("unexpected-response", (_req, res) => {
 			log("error", `${this.opts.appId}: WebSocket unexpected-response status=${res.statusCode} ${res.statusMessage}`);
@@ -2257,7 +4058,7 @@ var WSClient = class {
 	stop() {
 		this.close("manual");
 	}
-	close(reason) {
+	close(reason, event = {}) {
 		if (this.closed) return;
 		this.closed = true;
 		this.closedReason = reason;
@@ -2269,7 +4070,13 @@ var WSClient = class {
 			this.socket?.removeAllListeners();
 			this.socket?.close();
 		} catch {}
-		this.opts.onClose(reason);
+		this.opts.onClose({
+			reason,
+			...event
+		});
+	}
+	durationMs() {
+		return this.openedAt ? Date.now() - this.openedAt : void 0;
 	}
 	send(payload) {
 		try {
@@ -2289,6 +4096,7 @@ var WSClient = class {
 		}, this.heartbeatInterval);
 	}
 	identify() {
+		this.lastAuthAction = "identify";
 		this.send({
 			op: 2,
 			d: {
@@ -2305,6 +4113,7 @@ var WSClient = class {
 		log("debug", `${this.opts.appId}: Identify sent, intents=${this.opts.intents}`);
 	}
 	resume() {
+		this.lastAuthAction = "resume";
 		this.send({
 			op: 6,
 			d: {
@@ -2339,6 +4148,7 @@ var WSClient = class {
 			case 0:
 				if (typeof msg.s === "number") this.seq = msg.s;
 				if (msg.t === "READY") {
+					this.lastAuthAction = void 0;
 					this.sessionId = msg.d?.session_id || "";
 					log("debug", `${this.opts.appId}: READY received, session_id=${this.sessionId}`);
 				}
@@ -2352,17 +4162,31 @@ var WSClient = class {
 				log("debug", `${this.opts.appId}: server asked reconnect (op:7)`);
 				this.close("reconnect");
 				break;
-			case 9:
-				if (this.sessionId) {
-					log("debug", `${this.opts.appId}: invalid session, will retry with fresh identify`);
+			case 9: {
+				const canResume = msg.d === true;
+				if (this.lastAuthAction === "identify") {
+					log("error", `${this.opts.appId}: identify rejected (op:9), will try fallback intents, canResume=${canResume}`);
+					this.close("auth_fail", {
+						durationMs: this.durationMs(),
+						invalidSessionCanResume: canResume
+					});
+				} else if (canResume && this.sessionId) {
+					log("debug", `${this.opts.appId}: invalid session, server allows resume`);
+					this.close("reconnect", {
+						durationMs: this.durationMs(),
+						invalidSessionCanResume: true
+					});
+				} else {
+					log("debug", `${this.opts.appId}: invalid session, will retry with fresh identify, canResume=${canResume}`);
 					this.sessionId = "";
 					this.seq = 0;
-					this.close("session_lost");
-				} else {
-					log("error", `${this.opts.appId}: auth_fail (op:9 with no prior session)`);
-					this.close("auth_fail");
+					this.close("session_lost", {
+						durationMs: this.durationMs(),
+						invalidSessionCanResume: canResume
+					});
 				}
 				break;
+			}
 			default: log("debug", `${this.opts.appId}: unhandled opcode ${msg.op}`);
 		}
 	}
@@ -2378,7 +4202,9 @@ const intentBitMap = {
 	[2]: "GUILD_MEMBERS        (频道成员变更)",
 	[512]: "GUILD_MESSAGES       (频道消息-私域)",
 	[4096]: "DIRECT_MESSAGE       (频道私信)",
+	[1 << 24]: "群成员进退群事件",
 	[1 << 25]: "GROUP_AND_C2C_EVENT (群聊/单聊消息)",
+	[1 << 26]: "INTERACTION          (按钮交互回调)",
 	[1 << 30]: "PUBLIC_GUILD_MESSAGES (频道消息-公域)"
 };
 /** 优先级从高到低，回退时从最前面剥离 */
@@ -2387,6 +4213,8 @@ const priorityIntents = [
 	512,
 	1 << 30,
 	4096,
+	1 << 24,
+	1 << 26,
 	1 << 25,
 	1
 ];
@@ -2416,6 +4244,10 @@ const formatIntentNames = (intents, prefix = "") => {
 const conns = /* @__PURE__ */ new Map();
 /** /gateway 接口超时（毫秒） */
 const GATEWAY_FETCH_TIMEOUT_MS = 5e3;
+const RATE_LIMIT_DELAY_MS = 6e4;
+const QUICK_DISCONNECT_THRESHOLD_MS = 5e3;
+const QUICK_DISCONNECT_LIMIT = 3;
+const QUICK_DISCONNECT_DELAY_MS = 6e4;
 /**
 * 从 prodApi / sandboxApi 推导兜底的 WSS 地址
 * 官方实际长期返回的也是 wss://{host}/websocket/，不依赖 /gateway 也能直连
@@ -2436,7 +4268,10 @@ const fetchGateway = async (cfg) => {
 	}
 	try {
 		const { data } = await axios.get(`${apiUrl}/gateway`, {
-			headers: { Authorization: `QQBot ${accessToken}` },
+			headers: {
+				Authorization: `QQBot ${accessToken}`,
+				"User-Agent": getUserAgent()
+			},
 			timeout: GATEWAY_FETCH_TIMEOUT_MS
 		});
 		if (data?.url) return data.url;
@@ -2493,6 +4328,7 @@ const start = async (cfg) => {
 		cfg,
 		intents,
 		intentHistory: [intents],
+		quickDisconnects: 0,
 		aborted: false
 	});
 	await connect(cfg, intents, 0);
@@ -2516,12 +4352,15 @@ const schedule = (appId, delay, fn) => {
 const connect = async (cfg, intents, attempt, resume) => {
 	let conn = conns.get(cfg.appId);
 	if (!conn || conn.aborted) return;
-	const gatewayUrl = await fetchGateway(cfg);
+	let gatewayUrl = conn.gatewayUrl;
+	if (!gatewayUrl) gatewayUrl = await fetchGateway(cfg);
 	conn = conns.get(cfg.appId);
 	if (!conn || conn.aborted) return;
+	conn.gatewayUrl = gatewayUrl;
 	const client = new WSClient({
 		appId: cfg.appId,
 		gatewayUrl,
+		userAgent: getUserAgent(),
 		getAccessToken: () => getBotAccessToken(cfg.appId) || "",
 		intents,
 		resume,
@@ -2529,7 +4368,7 @@ const connect = async (cfg, intents, attempt, resume) => {
 			if (ev.t === "READY") summarize(cfg.appId, intents, true);
 			dispatch(cfg.appId, ev);
 		},
-		onClose: (reason) => onClose(cfg, intents, attempt, reason, client)
+		onClose: (event) => onClose(cfg, intents, attempt, event, client)
 	});
 	conn.client = client;
 	conn.cfg = cfg;
@@ -2540,16 +4379,19 @@ const connect = async (cfg, intents, attempt, resume) => {
 /**
 * 关闭回调处理
 */
-const onClose = (cfg, intents, attempt, reason, client) => {
-	if (reason === "manual") {
+const onClose = (cfg, intents, attempt, event, client) => {
+	if (event.reason === "manual") {
 		log("debug", `${cfg.appId}: WebSocket 已主动关闭`);
 		return;
 	}
 	const conn = conns.get(cfg.appId);
 	if (!conn || conn.aborted) return;
-	if (reason === "auth_fail") {
+	const code = event.code;
+	const closeLabel = formatCloseLabel(event);
+	if (event.reason === "auth_fail" || code === 4013 || code === 4014) {
 		const fallback = computeFallback(intents);
 		if (fallback && fallback !== intents) {
+			log("warn", `${cfg.appId}: Identify 被拒，尝试降级 intents ${intents} -> ${fallback}`);
 			schedule(cfg.appId, 1e3, () => connect(cfg, fallback, 0));
 			return;
 		}
@@ -2559,11 +4401,64 @@ const onClose = (cfg, intents, attempt, reason, client) => {
 		conns.delete(cfg.appId);
 		return;
 	}
+	if (code === 4914 || code === 4915) {
+		summarize(cfg.appId, intents, false);
+		log("error", `${cfg.appId}: WebSocket 断开 (${closeLabel})，机器人状态不允许连接，已停止自动重连`);
+		conn.aborted = true;
+		conns.delete(cfg.appId);
+		return;
+	}
+	if (event.canResume === false && event.canIdentify === false) {
+		summarize(cfg.appId, intents, false);
+		log("error", `${cfg.appId}: WebSocket 断开 (${closeLabel})，该错误不建议重试，已停止自动重连`);
+		conn.aborted = true;
+		conns.delete(cfg.appId);
+		return;
+	}
+	if (code === 4004) {
+		log("warn", `${cfg.appId}: access_token 已失效，刷新 token 后重连...`);
+		schedule(cfg.appId, 1e3, () => {
+			getAccessToken(cfg.tokenApi, cfg.appId, cfg.secret).then(() => connect(cfg, intents, 0)).catch(() => {
+				log("error", `${cfg.appId}: access_token 刷新失败，${RATE_LIMIT_DELAY_MS}ms 后重试连接...`);
+				schedule(cfg.appId, RATE_LIMIT_DELAY_MS, () => connect(cfg, intents, attempt + 1));
+			});
+		});
+		return;
+	}
 	const snap = client.snapshot();
-	const resume = reason === "session_lost" ? void 0 : snap.sessionId ? snap : void 0;
-	const delay = backoff(attempt);
-	log("error", `${cfg.appId}: WebSocket 断开 (${reason})，${delay}ms 后重连...`);
-	schedule(cfg.appId, delay, () => connect(cfg, intents, attempt + 1, resume));
+	const resume = event.reason === "session_lost" || shouldFreshIdentify(code) ? void 0 : snap.sessionId ? snap : void 0;
+	const delay = reconnectDelay(conn, attempt, event, code === 4008 ? RATE_LIMIT_DELAY_MS : void 0);
+	const nextAttempt = shouldResetAttempt(event) ? 0 : attempt + 1;
+	log("error", `${cfg.appId}: WebSocket 断开 (${closeLabel})，${delay}ms 后${resume ? "Resume" : "Identify"}重连...`);
+	schedule(cfg.appId, delay, () => connect(cfg, intents, nextAttempt, resume));
+};
+const shouldFreshIdentify = (code) => {
+	if (code === 4006 || code === 4007 || code === 4009) return true;
+	return typeof code === "number" && code >= 4900 && code <= 4913;
+};
+const shouldResetAttempt = (event) => {
+	return typeof event.durationMs === "number" && event.durationMs >= QUICK_DISCONNECT_THRESHOLD_MS;
+};
+const reconnectDelay = (conn, attempt, event, forcedDelay) => {
+	const stable = shouldResetAttempt(event);
+	let delay = forcedDelay ?? backoff(stable ? 0 : attempt);
+	if (typeof event.durationMs !== "number") return delay;
+	if (event.durationMs >= QUICK_DISCONNECT_THRESHOLD_MS) {
+		conn.quickDisconnects = 0;
+		return delay;
+	}
+	conn.quickDisconnects += 1;
+	if (conn.quickDisconnects >= QUICK_DISCONNECT_LIMIT) {
+		delay = Math.max(delay, QUICK_DISCONNECT_DELAY_MS);
+		log("warn", `${conn.cfg.appId}: WebSocket 连续快速断开 ${conn.quickDisconnects} 次，延长重连间隔到 ${delay}ms`);
+	}
+	return delay;
+};
+const formatCloseLabel = (event) => {
+	const parts = [event.reason];
+	if (typeof event.code === "number") parts.push(String(event.code));
+	if (event.remoteReason) parts.push(event.remoteReason);
+	return parts.join(" / ");
 };
 /**
 * 停止连接（同步：标记 abort + 清 pendingTimer + 关 client）
@@ -2609,7 +4504,8 @@ const hashConfig = (bot) => JSON.stringify({
 	sandboxApi: bot.sandboxApi,
 	sandbox: bot.sandbox,
 	event: bot.event,
-	keyboard: bot.keyboard
+	keyboard: bot.keyboard,
+	messageCache: bot.messageCache
 });
 /**
 * 创建单个 Bot 实例
@@ -2649,9 +4545,11 @@ const createBot = async (bot) => {
 		client.account.subId.qq = qq;
 		client.account.subId.appid = appId;
 		client.account.subId.union_openid = me.union_openid;
-		bus.on(appId, (ev) => dispatch$1(client, ev));
+		bus.on(appId, (ev) => {
+			dispatch$1(client, ev);
+		});
 		client.adapter.address = baseUrl;
-		client.adapter.secret = bot.secret;
+		client.adapter.secret = "*********";
 		client.adapter.version = pkg().version;
 		if (bot.event.type === 2) {
 			client.adapter.index = registerBot("webSocketClient", client);