@karinjs/adapter-qqbot 2.2.1 → 3.0.0

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 { 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-BUuU6FnQ.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 "./utils-N9PNiHjE.js";
+import { t as getMessageStore } from "./message-BTGL3TSn.js";
+import { t as needQrOnboard } from "./onboard-vIEoe9dB.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, senderGroup, unregisterBot } from "node-karin";
 import { URL } from "url";
 import lodash from "node-karin/lodash";
 import { createReadStream } from "node:fs";
@@ -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 前缀。 */
@@ -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",
@@ -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,41 @@ 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`);
+	}
+	/**
+	* 获取群成员详情
+	*
+	* 未公开文档，来自腾讯官方 openclaw 插件（v2.0.0）的接口速查。
+	* @param groupOpenid 群 openid
+	* @param memberOpenid 群成员 openid
+	*/
+	getGroupMember(groupOpenid, memberOpenid) {
+		return this.get(`/v2/groups/${groupOpenid}/members/${memberOpenid}`);
+	}
+};
+
 //#endregion
 //#region src/core/api/builders.ts
 /**
@@ -1240,6 +1285,7 @@ const buildGuildMsg = {
 * - media：富媒体上传
 * - interaction：按钮回调 ack
 * - meta：@me / dms / gateway
+* - groups：群基础信息 / 机器人群内状态（白名单接口）
 *
 * 请求体构造器 {@link buildQQMsg} / {@link buildGuildMsg} 独立导出，避免与 HTTP 调用耦合
 */
@@ -1249,6 +1295,7 @@ var QQBotApi = class {
 	media;
 	interaction;
 	meta;
+	groups;
 	/** 请求体构造器（静态便利） */
 	qq = buildQQMsg;
 	guild = buildGuildMsg;
@@ -1258,6 +1305,7 @@ var QQBotApi = class {
 		this.media = new MediaApi(axios);
 		this.interaction = new InteractionApi(axios);
 		this.meta = new MetaApi(axios);
+		this.groups = new GroupsApi(axios);
 	}
 };
 
@@ -1522,7 +1570,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 +1588,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,157 +1624,6 @@ 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;
@@ -1833,6 +1730,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);
+	await resolveOutgoingReferenceQQ(ctx, contact, grouping);
 	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];
@@ -1863,7 +1761,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 +1884,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 +1898,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 +1968,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 +2028,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;
@@ -2377,31 +2290,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));
 	}
 };
 /**
@@ -2523,6 +2443,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 +2489,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 +2508,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;
 				}
@@ -2887,10 +2814,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 +2830,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] 获取群信息失败（该接口为白名单接口，未开通权限会返回 11253）: ${err instanceof Error ? err.message : err}`);
+			return empty;
+		}
 	}
 	/**
 	* 获取群列表
@@ -2911,13 +2853,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 +2931,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 +2978,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 +3353,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 +3364,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 +3405,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 +3443,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 +3451,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 +3488,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 +3496,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,
@@ -4466,7 +4461,7 @@ const fetchGateway = async (cfg) => {
 			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);
+			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 ${fallback}`);
 		} else {
 			const reason = err?.message || "unknown";