@karinjs/adapter-qqbot 2.2.1 → 3.0.1

package/dist/index.js

@@ -1,9 +1,9 @@
-import { c as joinHttpPath, d as normalizeWsGatewayUrl, f as pkg, h as basename, l as normalizeHttpUrl, m as log, n as config, r as getConfig, s as buildFallbackWsUrlFromApi, t as bindHandlers, u as normalizeProxyConfig } from "./config-B_Gc9JKZ.js";
-import { i as random, n as getImageSize, r as handleUrl, t as fakeEvent } from "./common-by1GpV0b.js";
-import "./utils-DIq0lGMt.js";
-import { t as getMessageStore } from "./message-Dt4QkDYn.js";
-import { t as needQrOnboard } from "./onboard-BXQ1cG8h.js";
-import { AdapterBase, app, buttonHandle, common, createDirectMessage, createFriendDecreaseNotice, createFriendIncreaseNotice, createFriendMessage, createGroupMemberAddNotice, createGroupMemberDelNotice, createGroupMessage, createGuildMessage, fileToUrl, fileToUrlHandlerKey, handler, karin as karin$1, karinToQQBot, logger, registerBot, segment, unregisterBot } from "node-karin";
+import { l as basename, n as config, r as getConfig, s as pkg, t as bindHandlers } from "./config-D1_LqrcJ.js";
+import { t as log } from "./logger-sza6kuy3.js";
+import { i as random, n as fakeEvent, r as getImageSize, t as QQAPIBASEURL } from "./utils-lb9ZdWay.js";
+import { t as getMessageStore } from "./message-CVJVFAGR.js";
+import karin, { AdapterBase, app, buttonHandle, common, createDirectMessage, createFriendDecreaseNotice, createFriendIncreaseNotice, createFriendMessage, createGroupApplyRequest, createGroupInviteRequest, createGroupMemberAddNotice, createGroupMemberDelNotice, createGroupMessage, createGuildMessage, fileToUrl, fileToUrlHandlerKey, handler, karin as karin$1, karinToQQBot, logger, registerBot, segment, senderGroup, unregisterBot } from "node-karin";
+import path from "path";
 import { URL } from "url";
 import lodash from "node-karin/lodash";
 import { createReadStream } from "node:fs";
@@ -11,7 +11,7 @@ import FormData from "form-data";
 import axios from "node-karin/axios";
 import crypto from "node:crypto";
 import { open, readFile, stat } from "node:fs/promises";
-import path from "node:path";
+import path$1 from "node:path";
 import { fileURLToPath as fileURLToPath$1 } from "node:url";
 import os from "node:os";
 import EventEmitter from "node:events";
@@ -22,7 +22,7 @@ import nacl from "tweetnacl";
 //#region src/core/api/error.ts
 /**
 * OpenAPI 错误码映射表
-* 来源: api-v2/openapi/error/error.md
+* 来源: api-docs/openapi/error/error.md
 *
 * 规则:
 * - 区间码 (如 301000~301099) 用范围匹配
@@ -41,7 +41,7 @@ const httpStatusMap = {
 	500: "处理失败",
 	504: "处理失败"
 };
-/** 业务错误码(code)映射 */
+/** 业务错误码(err_code)映射 */
 const errorCodeMap = {
 	10001: "UnknownAccount 账号异常",
 	10003: "UnknownChannel 子频道异常",
@@ -359,15 +359,16 @@ const formatOpenAPIError = (status, code, message) => {
 //#region src/core/api/http.ts
 /**
 * 包装 axios 错误为可读多行 message
-* 如果响应中包含 QQ 官方错误码(code)，会自动映射为中文描述
+* 如果响应中包含 QQ 官方错误码(err_code)，会自动映射为中文描述
 */
 const formatError = (path, options, err) => {
 	if (axios.isAxiosError(err)) {
 		const response = err.response;
 		const status = response?.status ?? 0;
 		const data = response?.data;
-		const code = typeof data?.code === "number" ? data.code : void 0;
+		const code = typeof data?.err_code === "number" ? data.err_code : typeof data?.code === "number" ? data.code : void 0;
 		const msg = typeof data?.message === "string" ? data.message : void 0;
+		const traceId = typeof data?.trace_id === "string" ? data.trace_id : void 0;
 		const lines = [];
 		lines.push("[axios] 请求失败");
 		lines.push(`请求路径: ${path}`);
@@ -377,6 +378,7 @@ const formatError = (path, options, err) => {
 			if (reason) lines.push(`请求错误: ${reason}`);
 		}
 		if (code !== void 0 || status > 0) lines.push(`错误详情: ${formatOpenAPIError(status, code, msg)}`);
+		if (traceId) lines.push(`TraceID: ${traceId}`);
 		lines.push(`响应数据: ${JSON.stringify(data)}`);
 		return new Error(lines.join("\n"));
 	}
@@ -447,6 +449,8 @@ var Http = class {
 
 //#endregion
 //#region src/core/api/messages.ts
+/** 输入中状态默认展示时长（秒），平台 typing 窗口约 60s */
+const INPUT_NOTIFY_DEFAULT_SECOND = 60;
 /**
 * 消息发送 + 撤回
 */
@@ -459,6 +463,33 @@ var MessagesApi = class extends Http {
 	sendGroupMsg(groupOpenid, body) {
 		return this.post(`/v2/groups/${groupOpenid}/messages`, body);
 	}
+	/**
+	* 单聊输入中状态（msg_type=6，仅单聊）
+	* @param openid 用户 openid
+	* @param inputSecond 展示时长（秒），默认 60
+	* @param passive 被动消息参数（msg_id / event_id / msg_seq），可选
+	*/
+	sendFriendInputNotify(openid, inputSecond = INPUT_NOTIFY_DEFAULT_SECOND, passive) {
+		return this.post(`/v2/users/${openid}/messages`, {
+			msg_type: 6,
+			input_notify: {
+				input_type: 1,
+				input_second: inputSecond
+			},
+			...passive
+		});
+	}
+	/**
+	* 单聊流式消息（仅单聊）
+	*
+	* 首帧不带 stream_msg_id，响应的 id 作为后续帧的 stream_msg_id 回传；
+	* 同一次流 index 从 0 递增、msg_seq 保持一致；建议帧间隔 300~500ms。
+	* @param openid 用户 openid
+	* @param body 流式消息帧
+	*/
+	sendFriendStreamMsg(openid, body) {
+		return this.post(`/v2/users/${openid}/stream_messages`, body);
+	}
 	/** 文字子频道消息 */
 	sendChannelMsg(channelId, body) {
 		const headers = body instanceof FormData ? body.getHeaders() : void 0;
@@ -485,13 +516,10 @@ 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 缓存键。
 *
@@ -511,41 +539,25 @@ const cacheKey = (scene, peer, type, contentHash) => [
 	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);
-};
-/**
 * 读取可复用的上传结果。
 *
+* 缓存持久化在 SQLite（file_info ttl 可达数天），进程重启后同一份媒体
+* 不需要重新上传。缓存层异常一律按未命中处理，不影响上传主链路。
+*
 * @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);
+const getCachedUpload = async (scene, peer, type, contentHash) => {
+	try {
+		const raw = await getMessageStore().getUploadCache(cacheKey(scene, peer, type, contentHash));
+		if (!raw) return null;
+		return JSON.parse(raw);
+	} catch {
 		return null;
 	}
-	return { ...entry.response };
 };
 /**
 * 写入上传结果缓存。
@@ -556,17 +568,13 @@ const getCachedUpload = (scene, peer, type, contentHash) => {
 * @param contentHash 文件内容 hash。
 * @param response 上传接口返回。
 */
-const setCachedUpload = (scene, peer, type, contentHash, response) => {
+const setCachedUpload = async (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
-	});
+	const expiresAt = ttl > 0 ? Date.now() + Math.max(ttl - TTL_SAFETY_MARGIN_SECONDS, MIN_EFFECTIVE_TTL_SECONDS) * 1e3 : 0;
+	try {
+		await getMessageStore().setUploadCache(cacheKey(scene, peer, type, contentHash), JSON.stringify(response), expiresAt);
+	} catch {}
 };
 
 //#endregion
@@ -633,7 +641,7 @@ const DEFAULT_PART_CONCURRENCY = 1;
 /** 本地限制的最大分片并发，避免服务端返回过大值。 */
 const MAX_PART_CONCURRENCY = 10;
 /** HTTP(S) URL 可直接交给 QQ 平台拉取。 */
-const HTTP_URL_RE$1 = /^https?:\/\//i;
+const HTTP_URL_RE$2 = /^https?:\/\//i;
 /** Karin 常见 base64 图片/媒体前缀。 */
 const BASE64_PREFIX_RE = /^base64:\/\//i;
 /** 标准 data URL 的 base64 前缀。 */
@@ -680,7 +688,7 @@ const formatBytes = (bytes) => {
 const normalizeUploadFileName = (type, name) => {
 	const value = name?.trim();
 	if (!value) return DEFAULT_FILENAME$1[type];
-	return path.basename(value) || DEFAULT_FILENAME$1[type];
+	return path$1.basename(value) || DEFAULT_FILENAME$1[type];
 };
 /**
 * 检查 fallback 资源大小是否超过 QQ 对应类型上限。
@@ -729,7 +737,7 @@ const downloadRemoteAsBase64 = async (url) => {
 */
 const buildUploadSource = async (source) => {
 	const value = source.trim();
-	if (HTTP_URL_RE$1.test(value)) return { url: value };
+	if (HTTP_URL_RE$2.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 };
@@ -745,7 +753,7 @@ const buildUploadSource = async (source) => {
 const buildFallbackSource = async (type, source, fileName) => {
 	const value = source.trim();
 	const normalizedName = normalizeUploadFileName(type, fileName);
-	if (HTTP_URL_RE$1.test(value)) {
+	if (HTTP_URL_RE$2.test(value)) {
 		const buffer = await downloadRemoteAsBuffer(value);
 		return {
 			kind: "buffer",
@@ -766,7 +774,7 @@ const buildFallbackSource = async (type, source, fileName) => {
 	if (isLocalPathSource(value)) {
 		const file = normalizeLocalPath(value);
 		const info = await stat(file);
-		const name = normalizeUploadFileName(type, fileName || path.basename(file));
+		const name = normalizeUploadFileName(type, fileName || path$1.basename(file));
 		return {
 			kind: "local",
 			file,
@@ -983,12 +991,12 @@ var MediaApi = class extends Http {
 		assertUploadSize(type, fallbackSource.size);
 		const hashes = !srvSendMsg ? await computeUploadHashes(fallbackSource) : void 0;
 		if (hashes) {
-			const cached = getCachedUpload(scene, peer, type, hashes.md5);
+			const cached = await 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);
+			if (hashes) await setCachedUpload(scene, peer, type, hashes.md5, response);
 			return response;
 		}
 		const body = {
@@ -998,7 +1006,7 @@ var MediaApi = class extends Http {
 		};
 		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);
+		if (hashes) await setCachedUpload(scene, peer, type, hashes.md5, response);
 		return response;
 	}
 	/**
@@ -1100,9 +1108,10 @@ var MediaApi = class extends Http {
 		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 tasks = 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 length = Math.min(prepare.block_size, source.size - offset);
+				const data = await readPart(source, handle, offset, length);
 				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, {
@@ -1111,7 +1120,8 @@ var MediaApi = class extends Http {
 					block_size: data.length,
 					md5
 				}, prepare.retry_timeout);
-			}), concurrency);
+			});
+			await runWithConcurrency(tasks, concurrency);
 		} finally {
 			await handle?.close().catch(() => void 0);
 		}
@@ -1159,6 +1169,54 @@ var MetaApi = class extends Http {
 	}
 };
 
+//#endregion
+//#region src/core/api/groups.ts
+/**
+* QQ 群信息接口
+*
+* 注意：以下接口均为白名单接口，未开通权限时平台返回错误码 11253，
+* 需要向平台运营申请后可用。
+*/
+var GroupsApi = class extends Http {
+	/**
+	* 获取群基础信息
+	* @param groupOpenid 群 openid
+	*/
+	getGroupInfo(groupOpenid) {
+		return this.get(`/v2/groups/${groupOpenid}/info`);
+	}
+	/**
+	* 获取机器人在群内的状态（角色、入群时间、主动消息开关等）
+	* @param groupOpenid 群 openid
+	*/
+	getBotState(groupOpenid) {
+		return this.get(`/v2/groups/${groupOpenid}/bot_state`);
+	}
+	/**
+	* 获取群成员详情
+	*
+	* @param groupOpenid 群 openid
+	* @param memberOpenid 群成员 openid
+	*/
+	getGroupMember(groupOpenid, memberOpenid) {
+		return this.get(`/v2/groups/${groupOpenid}/members/${memberOpenid}`);
+	}
+	/**
+	* 设置群成员禁言
+	* @param groupOpenid 群 openid
+	* @param memberOpenid 群成员 openid
+	* @param op 操作: add 增加禁言，update 更新禁言到期时间，del 解除禁言
+	* @param duration 禁言时间使用RFC3339 格式
+	*/
+	setGroupMetu(groupOpenid, memberOpenid, op, duration) {
+		return this.post(`/v2/groups/${groupOpenid}/restrict_chat_setting`, { members: [{
+			op,
+			member_openid: memberOpenid,
+			mute_expire_at: duration
+		}] });
+	}
+};
+
 //#endregion
 //#region src/core/api/builders.ts
 /**
@@ -1240,6 +1298,7 @@ const buildGuildMsg = {
 * - media：富媒体上传
 * - interaction：按钮回调 ack
 * - meta：@me / dms / gateway
+* - groups：群基础信息 / 机器人群内状态（白名单接口）
 *
 * 请求体构造器 {@link buildQQMsg} / {@link buildGuildMsg} 独立导出，避免与 HTTP 调用耦合
 */
@@ -1249,6 +1308,7 @@ var QQBotApi = class {
 	media;
 	interaction;
 	meta;
+	groups;
 	/** 请求体构造器（静态便利） */
 	qq = buildQQMsg;
 	guild = buildGuildMsg;
@@ -1258,6 +1318,7 @@ var QQBotApi = class {
 		this.media = new MediaApi(axios);
 		this.interaction = new InteractionApi(axios);
 		this.meta = new MetaApi(axios);
+		this.groups = new GroupsApi(axios);
 	}
 };
 
@@ -1279,11 +1340,11 @@ const tokens = /* @__PURE__ */ new Map();
 * - 提前 50s 刷新，防止边界过期
 * - 同一 appId 旧定时器会被清理，避免并发刷新链
 */
-const getAccessToken = async (url, appId, secret) => {
-	const tokenUrl = normalizeHttpUrl(url);
+const getAccessToken = async (appId, secret) => {
 	let res;
 	try {
-		res = await axios.post(tokenUrl, {
+		const tokenurl = path.join(QQAPIBASEURL, "/app/getAppAccessToken");
+		res = await axios.post(tokenurl, {
 			appId: String(appId),
 			clientSecret: secret
 		}, { headers: { "User-Agent": getUserAgent() } });
@@ -1305,7 +1366,7 @@ const getAccessToken = async (url, appId, secret) => {
 	tokens.set(appId, state);
 	const delay = Math.max(5e3, expiresIn * 1e3 - 5e4);
 	state.refreshTimer = setTimeout(() => {
-		getAccessToken(tokenUrl, appId, secret).catch(() => {});
+		getAccessToken(appId, secret).catch(() => {});
 	}, delay);
 	return {
 		accessToken,
@@ -1330,9 +1391,9 @@ const stopTokenRefresh = (appId) => {
 /**
 * 创建 axios 实例，自动从 tokens map 取最新 access_token
 */
-const createAxiosInstance = (baseURL, appId) => {
+const createAxiosInstance = (appId) => {
 	const instance = axios.create({
-		baseURL: normalizeHttpUrl(baseURL),
+		baseURL: QQAPIBASEURL,
 		headers: {
 			"Content-Type": "application/json",
 			"User-Agent": getUserAgent()
@@ -1522,7 +1583,7 @@ const groupElements = (scene, elements) => {
 //#endregion
 //#region src/core/adapter/media-source.ts
 /** HTTP(S) 资源已经是可直接传给 QQ 平台的公网地址。 */
-const HTTP_URL_RE = /^https?:\/\//i;
+const HTTP_URL_RE$1 = /^https?:\/\//i;
 /** fileToUrl 需要文件名来推断上传类型；没有业务文件名时使用这些默认值。 */
 const DEFAULT_FILENAME = {
 	image: "image.jpg",
@@ -1540,7 +1601,7 @@ const hasFileToUrlHandler = () => handler.has(fileToUrlHandlerKey);
 * @param source Karin 消息段里的 file 字段。
 * @returns 是否为 HTTP(S) URL。
 */
-const isHttpMediaSource = (source) => HTTP_URL_RE.test(source);
+const isHttpMediaSource = (source) => HTTP_URL_RE$1.test(source);
 /**
 * 优先把本地/base64 富媒体转换为公网 URL；没有处理器或转换失败时返回原始来源。
 *
@@ -1576,189 +1637,10 @@ const resolvePreferredMediaSource = async (ctx, type, source, filename) => {
 	}
 };
 
-//#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;
 const MARKDOWN_IMAGE_RE = /!\[[^\]]*]\(\s*(<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\s*\)/g;
 /**
-* 提取文本中的 URL，将其替换为 `[按钮 N]` 占位文本并返回 button 列表
-*
-* @param text 文本
-* @param friendly 是否为单聊（true 时清除残余的 at 标签）
-*/
-const extractUrlButtons = (text, friendly = false) => {
-	let str = text.replace(/@everyone/g, "everyone").replace(/\n/g, "\r");
-	if (friendly) str = str.replace(/<qqbot-at-user id="[^"]+"\s*\/?>/g, "").replace(/<@!\d+>/g, "");
-	const urls = handleUrl(str);
-	if (urls.length === 0) return {
-		text: str,
-		buttons: []
-	};
-	const buttons = [];
-	urls.forEach((url, i) => {
-		str = str.replace(new RegExp(url, "g"), `[请点击 按钮${i} 查看]`);
-		buttons.push(segment.button({
-			text: `${i}. ${url}`,
-			link: url
-		}));
-	});
-	return {
-		text: str,
-		buttons: buttons.slice(0, MAX_BUTTONS)
-	};
-};
-/**
 * 将图片列表合并到一段 markdown 文本内（每张图占一行）
 */
 const imagesToMarkdown = async (urls) => {
@@ -1833,11 +1715,7 @@ const FRIEND_EVENT_WHITELIST = /* @__PURE__ */ new Set([
 const sendQQ = async (ctx, contact, elements) => {
 	const target = contact.scene === "friend" ? "user" : "group";
 	const grouping = groupElements(contact.scene, elements);
-	if (ctx.cfg.markdown.enable && ctx.cfg.keyboard.enable && grouping.text.length) {
-		const { text, buttons } = extractUrlButtons(grouping.text.join(""), contact.scene === "friend");
-		grouping.text = [text];
-		grouping.buttons.push(...buttons);
-	}
+	await resolveOutgoingReferenceQQ(ctx, contact, grouping);
 	/**
 	* 自动 Markdown 通道：
 	* text / at / 可转换为公网 URL 的图片通过 markdown content 渲染；无法转换的图片
@@ -1863,7 +1741,7 @@ const sendQQMarkdown = async (ctx, contact, grouping, target) => {
 		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")));
+	if (lines.length || grouping.buttons.length || grouping.keyboards.length) if (shouldUseTextForReference(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;
@@ -1986,8 +1864,8 @@ const appendImageUrlLine = async (lines, url) => {
 * @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;
+const shouldUseTextForReference = (grouping) => {
+	return isQQReferenceMessageId(grouping.reply.messageId) && !grouping.qqImages.length && !grouping.buttons.length && !grouping.keyboards.length && !grouping.markdowns.length;
 };
 /**
 * 判断给定 ID 是否是 QQ 客户端引用使用的 REFIDX。
@@ -2000,6 +1878,23 @@ const shouldUseTextForReference = (ctx, contact, grouping) => {
 */
 const isQQReferenceMessageId = (messageId) => messageId.startsWith("REFIDX_");
 /**
+* 发送前把显式引用的 API 消息 ID 解析为 REFIDX。
+*
+* 映射只存在于 SQLite 消息缓存（ID 映射行不受缓存开关影响，始终落库）。
+* 解析结果直接写回 grouping，后续同步路径（降级判断、message_reference
+* 附加）无需再查库。
+*
+* @param ctx 适配器实例。
+* @param contact 消息目标会话。
+* @param grouping 已归类的消息段。
+*/
+const resolveOutgoingReferenceQQ = async (ctx, contact, grouping) => {
+	const original = grouping.reply.messageId;
+	if (!original || isQQReferenceMessageId(original)) return;
+	const fromStore = await ctx.messageStore.resolveRefIdx(String(ctx.cfg.appId), contact, original).catch(() => null);
+	if (fromStore) grouping.reply.messageId = fromStore;
+};
+/**
 * 构造 keyboard 字段（buttons + keyboards 合并）
 */
 const buildKeyboard$1 = (grouping) => {
@@ -2053,10 +1948,8 @@ const flushQQ = async (ctx, contact, grouping, items) => {
 	let referenceHandled = false;
 	for (const item of items.slice(0, maxItems)) {
 		passive(item);
-		if (!referenceHandled) referenceHandled = attachVisibleReferenceQQ(ctx, contact, item, grouping);
+		if (!referenceHandled) referenceHandled = attachVisibleReferenceQQ(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);
@@ -2115,14 +2008,14 @@ const resolvePassiveQQ = (grouping) => {
 * 附加 QQ 客户端可见的引用对象。
 *
 * 群聊/单聊里真正发给 QQ 的值必须是 `message_scene.ext` 的 `msg_idx=REFIDX_xxx`。
-* 如果插件传入的是 Karin 暴露的官方 API 消息 ID，这里会先按同会话映射转换。
+* API 消息 ID 到 REFIDX 的转换已由 `resolveOutgoingReferenceQQ` 在发送前完成。
 *
 * @param item 即将发送的 QQ 消息体。
 * @param grouping 已归类的消息段。
 * @returns 是否已经消费一次显式引用。
 */
-const attachVisibleReferenceQQ = (ctx, contact, item, grouping) => {
-	const messageId = resolveReferenceMessageId(ctx, contact, grouping.reply.messageId);
+const attachVisibleReferenceQQ = (item, grouping) => {
+	const messageId = grouping.reply.messageId;
 	if (!isQQReferenceMessageId(messageId)) return false;
 	item.message_reference = { message_id: messageId };
 	return true;
@@ -2176,11 +2069,6 @@ const BUTTON_ONLY_MARKDOWN = "​";
 */
 const sendGuild = async (ctx, contact, elements) => {
 	const grouping = groupElements(contact.scene, elements);
-	if (ctx.cfg.markdown.enable && ctx.cfg.keyboard.enable && grouping.text.length) {
-		const { text, buttons } = extractUrlButtons(grouping.text.join(""), false);
-		grouping.text = [text];
-		grouping.buttons.push(...buttons);
-	}
 	if (ctx.cfg.markdown.enable) return sendGuildMarkdown(ctx, contact, grouping);
 	return sendGuildClassic(ctx, contact, grouping);
 };
@@ -2263,7 +2151,7 @@ const buildGuildImageItem = async (source) => {
 };
 const resolveImageFilename = (source) => {
 	const file = source.split(/[?#]/)[0] || "";
-	const name = path.basename(file);
+	const name = path$1.basename(file);
 	return name.includes(".") ? name : "image.jpg";
 };
 const buildKeyboard = (grouping) => {
@@ -2307,7 +2195,7 @@ const warnUnsupportedCommandEnterMarkdowns = (ctx, scene, markdowns) => {
 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);
+	const send = contact.scene === "guild" ? (_peer, subPeer, item) => ctx.super.messages.sendChannelMsg(subPeer, item) : (peer, _subPeer, item) => ctx.super.messages.sendDmsMsg(peer, item);
 	for (const item of items) {
 		passive(item);
 		const res = await send(contact.peer, contact.subPeer, item);
@@ -2377,31 +2265,38 @@ const prepareSelfMessageCache = async (ctx, elements) => {
 	};
 };
 /**
-* 发送成功后缓存机器人自己的消息，供 bot.getMsg(messageId) 查询。
+* 发送成功后记录机器人自己的消息。
+*
+* 无论缓存开关如何，都会落库最小 ID 映射行（msg_id/ref_idx/is_self）——
+* 单聊撤回判定和引用解析没有任何内存映射，完全依赖数据库。
+* 只有 self 缓存开启时才附带消息正文，供 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 withContent = shouldCacheSelfMessage(ctx) && cacheElements.length > 0;
+	const elements = withContent ? cacheElements : [];
+	const level = withContent ? ctx.cfg.messageCache.level : "minimal";
 	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));
+			elements
+		}, {
+			refIdx: referenceMessageId && referenceMessageId !== messageId ? referenceMessageId : void 0,
+			isSelf: true,
+			level
+		}).catch((err) => ctx.logger("warn", `[getMsg] 写入自己消息缓存失败: ${messageId}`, err));
 	}
 };
 /**
@@ -2504,7 +2399,7 @@ const prepareStaticElement = async (ctx, element) => {
 */
 const selfSender = (ctx, contact) => {
 	const userId = ctx.selfSubId("id") || ctx.selfId;
-	const name = ctx.selfName || ctx.cfg.name || "";
+	const name = ctx.selfName || "";
 	if (contact.scene === "friend" || contact.scene === "direct") return karin$1.friendSender(userId, name);
 	return karin$1.groupSender(userId, "member", name);
 };
@@ -2523,6 +2418,8 @@ const responseTime = (timestamp) => {
 //#endregion
 //#region src/core/adapter/base.ts
 const adapterConfigStore = /* @__PURE__ */ new WeakMap();
+/** HTTP(S) URL 可直接交给 QQ 平台拉取上传 */
+const HTTP_URL_RE = /^https?:\/\//i;
 /**
 * QQ Official Bot 适配器
 *
@@ -2567,18 +2464,17 @@ var AdapterQQBot = class extends AdapterBase {
 	* 发送消息
 	*/
 	async sendMsg(contact, elements, _retryCount) {
+		/** 发送成功后始终记录消息 ID 映射；正文是否入库由 cacheSelfMessage 内部按开关决定。 */
 		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);
+			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, elements) : void 0;
+			const result = await sendGuild(this, contact, prepared?.sendElements ?? elements);
+			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);
+			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, elements) : void 0;
+			const result = await sendQQ(this, contact, prepared?.sendElements ?? elements);
+			cacheSelfMessage(this, contact, prepared?.cacheElements ?? [], result);
 			return result;
 		}
 		throw new Error(`不支持的消息场景: ${contact.scene}`);
@@ -2587,12 +2483,18 @@ var AdapterQQBot = class extends AdapterBase {
 	* 撤回消息
 	*
 	* 群聊中机器人被群主设为管理员后，也可撤回成员消息；平台仍限制消息发送后两分钟内。
+	* REFIDX 与 API 消息 ID 的映射、单聊"是否自己发送"的判定都直接查询
+	* SQLite 消息缓存（ID 映射行不受缓存开关影响，始终落库）。
 	*/
 	async recallMsg(contact, messageId) {
-		const apiMessageId = resolveApiMessageId(this, contact, messageId);
+		let apiMessageId = messageId;
+		if (apiMessageId.startsWith("REFIDX_")) {
+			const resolved = await this.messageStore.resolveApiMessageId(String(this.cfg.appId), contact, apiMessageId).catch(() => null);
+			if (resolved) apiMessageId = resolved;
+		}
 		try {
 			if (contact.scene === "friend") {
-				if (!isOwnMessageId(this, contact, apiMessageId)) {
+				if (!await this.messageStore.isSelfMessage(String(this.cfg.appId), contact, apiMessageId).catch(() => false)) {
 					this.logger("warn", `[recallMsg] QQ 单聊只能撤回机器人自己发送的消息，已跳过撤回: ${messageId}`);
 					return;
 				}
@@ -2829,8 +2731,13 @@ var AdapterQQBot = class extends AdapterBase {
 	/**
 	* 禁言群成员
 	*/
-	async setGroupMute(_groupId, _targetId, _duration) {
-		this.logger("warn", "[setGroupMute] QQ Official Bot API 暂不支持禁言群成员");
+	async setGroupMute(_groupId, _targetId, duration) {
+		let rfc3339 = "";
+		if (duration > 0) {
+			const time = Date.now() + duration * 1e3;
+			rfc3339 = new Date(time).toISOString();
+		}
+		this.super.groups.setGroupMetu(_groupId, _targetId, rfc3339 ? "add" : "del", rfc3339);
 	}
 	/**
 	* 群全员禁言
@@ -2887,10 +2794,12 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 获取群信息
+	*
+	* 走官方 `GET /v2/groups/{group_openid}/info`（白名单接口）。
+	* 未开通权限（11253）或查询失败时降级为空结构并告警。
 	*/
 	async getGroupInfo(_groupId, _noCache) {
-		this.logger("warn", "[getGroupInfo] QQ Official Bot API 暂不支持获取群信息");
-		return {
+		const empty = {
 			groupId: _groupId,
 			groupName: "",
 			owner: "",
@@ -2901,6 +2810,19 @@ var AdapterQQBot = class extends AdapterBase {
 			groupDesc: "",
 			avatar: ""
 		};
+		try {
+			const info = await this.super.groups.getGroupInfo(_groupId);
+			return {
+				...empty,
+				groupName: info.group_name || "",
+				memberCount: info.group_member_num ?? 0,
+				groupDesc: info.group_finger_memo || "",
+				avatar: await this.getGroupAvatarUrl(_groupId)
+			};
+		} catch (err) {
+			this.logger("warn", `[getGroupInfo] 获取群信息失败: ${err instanceof Error ? err.message : err}`);
+			return empty;
+		}
 	}
 	/**
 	* 获取群列表
@@ -2911,13 +2833,43 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 获取群成员信息
+	*
+	* - 查询机器人自身（targetId 为 selfId）走官方 `GET /v2/groups/{group_openid}/bot_state`（白名单）。
+	* - 查询其他成员走 `GET /v2/groups/{group_openid}/members/{member_openid}`，
+	*   该接口未公开文档，来自腾讯官方 openclaw 插件 v2.0.0，返回结构以平台实际为准。
+	* 接口不可用（如白名单未开通返回 11253）时降级为占位结构并告警。
 	*/
 	async getGroupMemberInfo(_groupId, _targetId, _refresh) {
-		this.logger("warn", "[getGroupMemberInfo] QQ Official Bot API 暂不支持获取群成员信息");
-		return {
-			userId: _targetId,
-			role: "member"
-		};
+		/** 按 karin 接口约定构造返回值，sender 由 getter 即时构建 */
+		const build = (userId, role, nick, joinTime) => ({
+			userId,
+			role,
+			nick,
+			joinTime,
+			get sender() {
+				return senderGroup({
+					userId,
+					nick: nick || "",
+					name: nick || "",
+					role
+				});
+			}
+		});
+		if (_targetId === this.selfId) try {
+			const state = await this.super.groups.getBotState(_groupId);
+			return build(state.member_openid || _targetId, state.member_role || "member", void 0, state.joined_at ? new Date(state.joined_at).getTime() : void 0);
+		} catch (err) {
+			this.logger("warn", `[getGroupMemberInfo] 获取机器人群内状态失败（该接口为白名单接口，未开通权限会返回 11253）: ${err instanceof Error ? err.message : err}`);
+			return build(_targetId, "member");
+		}
+		try {
+			const member = await this.super.groups.getGroupMember(_groupId, _targetId);
+			if (member.nick) this.nicknameCache.set(_targetId, member.nick);
+			return build(member.member_openid || _targetId, member.member_role || "member", member.nick, member.joined_at ? new Date(member.joined_at).getTime() : void 0);
+		} catch (err) {
+			this.logger("warn", `[getGroupMemberInfo] 获取群成员详情失败（该接口未公开文档，可能不可用）: ${err instanceof Error ? err.message : err}`);
+			return build(_targetId, "member");
+		}
 	}
 	/**
 	* 获取群成员列表
@@ -2959,9 +2911,19 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 上传群文件、私聊文件
+	*
+	* QQ 官方 Bot API 没有群文件系统，上传走 `POST /v2/{users|groups}/{openid}/files`
+	* （file_type=4 + srv_send_msg=true），由服务端直接发送文件消息。
+	* 频道 / 频道私信场景官方无文件接口，暂不支持。
 	*/
 	async uploadFile(_contact, _file, _name, _folder) {
-		this.logger("warn", "[uploadFile] QQ Official Bot API 暂不支持上传文件");
+		if (_contact.scene !== "friend" && _contact.scene !== "group") {
+			this.logger("warn", "[uploadFile] 频道场景 QQ Official Bot API 暂不支持上传文件");
+			return;
+		}
+		const scene = _contact.scene === "friend" ? "user" : "group";
+		if (HTTP_URL_RE.test(_file)) await this.super.media.upload(scene, _contact.peer, "file", _file, true, _name);
+		else await this.super.media.uploadFallback(scene, _contact.peer, "file", _file, true, _name);
 	}
 	/**
 	* 下载文件到协议端本地
@@ -2996,10 +2958,18 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 上传群文件
+	*
+	* 实现同 {@link uploadFile}：官方无群文件系统，走 files 接口由服务端直发文件消息。
 	*/
 	async uploadGroupFile(_groupId, _file, _name) {
-		this.logger("warn", "[uploadGroupFile] QQ Official Bot API 暂不支持上传群文件");
-		return false;
+		try {
+			if (HTTP_URL_RE.test(_file)) await this.super.media.upload("group", _groupId, "file", _file, true, _name);
+			else await this.super.media.uploadFallback("group", _groupId, "file", _file, true, _name);
+			return true;
+		} catch (err) {
+			this.logger("warn", `[uploadGroupFile] 上传群文件失败: ${err instanceof Error ? err.message : err}`);
+			return false;
+		}
 	}
 	/**
 	* 获取文件 url
@@ -3363,7 +3333,7 @@ const convertToKarin = (appid, ev, selfSubId, options = {}) => {
 * QQ 不会提供引用消息的正式消息 ID；调用方应以 `msg_idx` 作为缓存键。
 */
 const convertReferenceToKarin = (appid, ev, selfSubId, reference) => {
-	return convertToKarin(appid, {
+	const referenceEvent = {
 		...ev,
 		d: {
 			...ev.d,
@@ -3374,26 +3344,33 @@ const convertReferenceToKarin = (appid, ev, selfSubId, reference) => {
 			msg_elements: void 0,
 			message_type: reference.message_type
 		}
-	}, selfSubId);
+	};
+	return convertToKarin(appid, referenceEvent, selfSubId);
 };
 
 //#endregion
 //#region src/core/event/message.ts
 /**
-* 写入 getMsg 热缓存并投递 SQLite 后台队列。
+* 把消息投递 SQLite 后台写入队列。
 *
 * 不等待数据库落库，避免缓存特性拖慢 Karin 消息事件下发。
 *
+* 关闭消息缓存时仍按 minimal 级落库最小 ID 映射行（msg_id/ref_idx）——
+* 撤回和引用解析没有任何内存映射，完全依赖数据库。
+*
 * @param client 当前 QQBot 适配器实例。
 * @param message 需要缓存的消息快照。
-* @param aliases 可用于查询同一消息的 QQ 侧索引，例如 msg_idx。
+* @param refIdx QQ `msg_idx` 引用索引，作为该消息的第二查询索引。
 */
-const cacheMessage = (client, message, aliases = []) => {
-	if (!client.cfg.messageCache.enable) return;
+const cacheMessage = (client, message, refIdx) => {
+	const { enable, level } = client.cfg.messageCache;
 	client.messageStore.save(String(client.cfg.appId), {
 		...message,
 		messageSeq: 0
-	}, aliases).catch((err) => log("warn", `[getMsg] 写入消息缓存失败: ${message.messageId}`, err));
+	}, {
+		refIdx,
+		level: enable ? level : "minimal"
+	}).catch((err) => log("warn", `[getMsg] 写入消息缓存失败: ${message.messageId}`, err));
 };
 /**
 * 写入引用消息上下文缓存。
@@ -3408,7 +3385,7 @@ const cacheReference = (client, message) => {
 	client.messageStore.saveReferenceIfAbsent(String(client.cfg.appId), {
 		...message,
 		messageSeq: 0
-	}).catch((err) => log("warn", `[getMsg] 写入引用上下文失败: ${message.messageId}`, err));
+	}, client.cfg.messageCache.level).catch((err) => log("warn", `[getMsg] 写入引用上下文失败: ${message.messageId}`, err));
 };
 /**
 * 将 Karin 快速回复自动生成的当前消息引用 ID 转成 QQ 客户端可见引用 ID。
@@ -3446,7 +3423,6 @@ const onGroupMsg = (client, ev, opts) => {
 	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, {
@@ -3455,7 +3431,7 @@ const onGroupMsg = (client, ev, opts) => {
 		contact,
 		sender,
 		elements
-	}, [ev.d.id, messageIndex].filter((id) => !!id && id !== karinMessageId && id !== referenceIndex));
+	}, messageIndex && messageIndex !== referenceIndex ? messageIndex : void 0);
 	const reference = ev.d.msg_elements?.find((item) => item.msg_idx === referenceIndex);
 	if (reference && referenceIndex) cacheReference(client, {
 		messageId: referenceIndex,
@@ -3492,7 +3468,6 @@ const onFriendMsg = (client, ev) => {
 	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, {
@@ -3501,7 +3476,7 @@ const onFriendMsg = (client, ev) => {
 		contact,
 		sender,
 		elements
-	}, [ev.d.id, messageIndex].filter((id) => !!id && id !== karinMessageId && id !== referenceIndex));
+	}, messageIndex && messageIndex !== referenceIndex ? messageIndex : void 0);
 	const reference = ev.d.msg_elements?.find((item) => item.msg_idx === referenceIndex);
 	if (reference && referenceIndex) cacheReference(client, {
 		messageId: referenceIndex,
@@ -3788,6 +3763,50 @@ const onC2CMsgReject = (client, event) => {
 	const userId = event.d.openid;
 	client.logger("mark", `好友 ${userId} 已拒绝机器人主动发送消息`);
 };
+/** 用户申请加群事件 */
+const onGroupJoinRequest = (client, event) => {
+	const eventId = event.id;
+	const contact = karin$1.contactGroup(event.d.group_openid);
+	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
+	const time = Date.parse(event.d.apply_at);
+	if (event.d.member_openid === client.selfId) createGroupInviteRequest({
+		bot: client,
+		time,
+		eventId,
+		contact,
+		rawEvent: event,
+		subEvent: "groupInvite",
+		sender: karin$1.groupSender(event.d.invited_by, "unknown"),
+		srcReply,
+		content: {
+			inviterId: event.d.invited_by,
+			flag: event.d.join_request_id
+		}
+	});
+	else createGroupApplyRequest({
+		bot: client,
+		time,
+		eventId,
+		contact,
+		rawEvent: event,
+		subEvent: "groupApply",
+		sender: karin$1.groupSender(event.d.member_openid, "unknown"),
+		srcReply,
+		content: {
+			inviterId: event.d.invited_by ?? "",
+			flag: event.d.join_request_id,
+			groupId: event.d.group_openid,
+			applierId: event.d.member_openid,
+			reason: (() => {
+				if (event.d.verify_info) if (event.d.verify_info.method === "admin_review_qa") {
+					const reason = event.d.verify_info.review_qa_list[0];
+					if (reason) return `问题: ${reason.question}\n答案: ${reason.answer}`;
+				} else return event.d.verify_info.verify_message;
+				return "";
+			})()
+		}
+	});
+};
 
 //#endregion
 //#region src/core/event/interaction.ts
@@ -4022,6 +4041,9 @@ 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}`);
+		case "GROUP_JOIN_REQUEST":
+			onGroupJoinRequest(client, ev);
+			return;
 		default: client.logger("debug", `[QQ Official Bot] 未处理事件: ${ev.t}`);
 	}
 };
@@ -4424,34 +4446,17 @@ const QUICK_DISCONNECT_THRESHOLD_MS = 5e3;
 const QUICK_DISCONNECT_LIMIT = 3;
 const QUICK_DISCONNECT_DELAY_MS = 6e4;
 /**
-* 从 proxy.prodApi / proxy.sandboxApi 推导兜底的 WS 地址
-* 官方实际长期返回的也是 wss://{host}/websocket/，不依赖 /gateway 也能直连
-*/
-const buildFallbackWsUrl = (cfg) => {
-	return buildFallbackWsUrlFromApi(cfg.sandbox ? cfg.proxy.sandboxApi : cfg.proxy.prodApi);
-};
-/**
 * 获取网关地址：优先调 /gateway；失败 / 超时 / 限频 → 直接 fallback 到硬编码
 */
 const fetchGateway = async (cfg) => {
-	const apiUrl = normalizeHttpUrl(cfg.sandbox ? cfg.proxy.sandboxApi : cfg.proxy.prodApi);
-	const fallback = buildFallbackWsUrl(cfg);
-	const proxyWsValue = cfg.sandbox ? cfg.proxy.sandboxWs : cfg.proxy.prodWs;
-	if (proxyWsValue.trim()) try {
-		const proxyWsUrl = normalizeWsGatewayUrl(proxyWsValue);
-		log("debug", `${cfg.appId}: 使用自定义 WS ${proxyWsUrl}`);
-		return proxyWsUrl;
-	} catch (err) {
-		const reason = err?.message || "unknown";
-		log("warn", `${cfg.appId}: 自定义 WS 地址无效 (${reason})，尝试获取 /gateway`);
-	}
+	const apiUrl = "https://api.bot.qq.com";
 	const accessToken = getBotAccessToken(cfg.appId);
 	if (!accessToken) {
-		log("warn", `${cfg.appId}: 无 access_token，使用硬编码 WS ${fallback}`);
-		return fallback;
+		log("warn", `${cfg.appId}: 无 access_token，使用硬编码 WS`);
+		return "wss://api.bot.qq.com/websocket";
 	}
 	try {
-		const { data } = await axios.get(joinHttpPath(apiUrl, "gateway"), {
+		const { data } = await axios.get(path$1.join(apiUrl, "gateway"), {
 			headers: {
 				Authorization: `QQBot ${accessToken}`,
 				"User-Agent": getUserAgent()
@@ -4459,20 +4464,20 @@ const fetchGateway = async (cfg) => {
 			timeout: GATEWAY_FETCH_TIMEOUT_MS
 		});
 		if (data?.url) return data.url;
-		log("warn", `${cfg.appId}: /gateway 返回为空，使用硬编码 WS ${fallback}`);
-		return fallback;
+		log("warn", `${cfg.appId}: /gateway 返回为空，使用硬编码 WS`);
+		return "wss://api.bot.qq.com/websocket";
 	} catch (err) {
 		if (axios.isAxiosError(err)) {
 			const response = err.response;
 			const status = response?.status ?? 0;
 			const data = response?.data;
-			const detail = formatOpenAPIError(status, typeof data?.code === "number" ? data.code : void 0, typeof data?.message === "string" ? data.message : void 0);
-			log("warn", `${cfg.appId}: /gateway 调用失败 | ${detail}，使用硬编码 WS ${fallback}`);
+			const detail = formatOpenAPIError(status, typeof data?.err_code === "number" ? data.err_code : typeof data?.code === "number" ? data.code : void 0, typeof data?.message === "string" ? data.message : void 0);
+			log("warn", `${cfg.appId}: /gateway 调用失败 | ${detail}，使用硬编码 WS`);
 		} else {
 			const reason = err?.message || "unknown";
-			log("warn", `${cfg.appId}: /gateway 调用失败 (${reason})，使用硬编码 WS ${fallback}`);
+			log("warn", `${cfg.appId}: /gateway 调用失败 (${reason})，使用硬编码 WS`);
 		}
-		return fallback;
+		return "wss://api.bot.qq.com/websocket";
 	}
 };
 /** 重连退避（毫秒） */
@@ -4602,7 +4607,7 @@ const onClose = (cfg, intents, attempt, event, client) => {
 	if (code === 4004) {
 		log("warn", `${cfg.appId}: access_token 已失效，刷新 token 后重连...`);
 		schedule(cfg.appId, 1e3, () => {
-			getAccessToken(cfg.proxy.tokenApi, cfg.appId, cfg.secret).then(() => connect(cfg, intents, 0)).catch(() => {
+			getAccessToken(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));
 			});
@@ -4683,10 +4688,7 @@ const initState = /* @__PURE__ */ new Map();
 const hashConfig = (bot) => JSON.stringify({
 	appId: bot.appId,
 	secret: bot.secret,
-	proxy: bot.proxy,
-	sandbox: bot.sandbox,
 	event: bot.event,
-	keyboard: bot.keyboard,
 	markdown: bot.markdown,
 	messageCache: bot.messageCache
 });
@@ -4694,10 +4696,7 @@ const hashConfig = (bot) => JSON.stringify({
 * 创建单个 Bot 实例
 */
 const createBot = async (input) => {
-	const bot = {
-		...input,
-		proxy: normalizeProxyConfig(input.proxy)
-	};
+	const bot = { ...input };
 	const appId = String(bot.appId);
 	if (!appId) {
 		logger.warn("[QQ Official Bot] 配置缺少 appId，跳过");
@@ -4714,14 +4713,13 @@ const createBot = async (input) => {
 		await existing.promise.catch(() => {});
 	}
 	const promise = (async () => {
-		unregisterBot("selfId", appId);
+		if (karin.getBot(appId)) unregisterBot("selfId", appId);
 		stop(appId);
 		offAll(appId);
 		stopTokenRefresh(appId);
 		logger.info(`[QQ Official Bot][${appId}] 获取 access_token...`);
-		await getAccessToken(bot.proxy.tokenApi, appId, bot.secret);
-		const baseUrl = bot.sandbox ? bot.proxy.sandboxApi : bot.proxy.prodApi;
-		const api = new QQBotApi(createAxiosInstance(baseUrl, appId));
+		await getAccessToken(appId, bot.secret);
+		const api = new QQBotApi(createAxiosInstance(appId));
 		const me = await api.meta.getMe();
 		const client = new AdapterQQBot(bot, api);
 		client.account.name = me.username;
@@ -4735,7 +4733,7 @@ const createBot = async (input) => {
 		bus.on(appId, (ev) => {
 			dispatch$1(client, ev);
 		});
-		client.adapter.address = baseUrl;
+		client.adapter.address = QQAPIBASEURL;
 		client.adapter.secret = "*********";
 		client.adapter.version = pkg().version;
 		if (bot.event.type === 2) {
@@ -4903,23 +4901,7 @@ const createRouting = () => {
 //#region src/index.ts
 logger.info(`${logger.violet(`[插件:${pkg().version}]`)} ${logger.green(basename)} 初始化完成~`);
 createRouting();
-const printOnboardBanner = () => {
-	console.log();
-	console.log("  ==========================================");
-	console.log("  未检测到 QQBot 配置");
-	console.log("  请使用任意可用 bot（如 OneBot / Console 适配器）");
-	console.log("  对机器人发送指令： #QQ登录");
-	console.log("  扫码授权完成后会自动写入配置并完成初始化");
-	console.log();
-	console.log("  ⚠ 注意：扫码授权会刷新该机器人的 secret，旧 secret 立即失效");
-	console.log("  ==========================================");
-	console.log();
-};
 const bootstrap = async () => {
-	if (needQrOnboard()) {
-		printOnboardBanner();
-		return;
-	}
 	try {
 		await initQQBotAdapter();
 	} catch (err) {