@karinjs/adapter-qqbot 2.1.0 → 3.0.0

package/dist/index.js

@@ -1,9 +1,9 @@
-import { c as log, l as basename, n as config, o as pkg, r as getConfig, t as bindHandlers } from "./config-DKa7596f.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-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 "./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);
 	}
 };
 
@@ -1280,9 +1328,10 @@ const tokens = /* @__PURE__ */ new Map();
 * - 同一 appId 旧定时器会被清理，避免并发刷新链
 */
 const getAccessToken = async (url, appId, secret) => {
+	const tokenUrl = normalizeHttpUrl(url);
 	let res;
 	try {
-		res = await axios.post(url, {
+		res = await axios.post(tokenUrl, {
 			appId: String(appId),
 			clientSecret: secret
 		}, { headers: { "User-Agent": getUserAgent() } });
@@ -1304,7 +1353,7 @@ const getAccessToken = async (url, appId, secret) => {
 	tokens.set(appId, state);
 	const delay = Math.max(5e3, expiresIn * 1e3 - 5e4);
 	state.refreshTimer = setTimeout(() => {
-		getAccessToken(url, appId, secret).catch(() => {});
+		getAccessToken(tokenUrl, appId, secret).catch(() => {});
 	}, delay);
 	return {
 		accessToken,
@@ -1331,7 +1380,7 @@ const stopTokenRefresh = (appId) => {
 */
 const createAxiosInstance = (baseURL, appId) => {
 	const instance = axios.create({
-		baseURL,
+		baseURL: normalizeHttpUrl(baseURL),
 		headers: {
 			"Content-Type": "application/json",
 			"User-Agent": getUserAgent()
@@ -1521,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",
@@ -1539,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；没有处理器或转换失败时返回原始来源。
 *
@@ -1575,160 +1624,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 列表
 *
@@ -1769,6 +1668,40 @@ const imagesToMarkdown = async (urls) => {
 		return `![karin #${width}px #${height}px](${url})`;
 	}));
 };
+/**
+* 将 markdown 文本拆为普通文本片段与图片来源。
+*/
+const splitMarkdownImages = (markdown) => {
+	const parts = [];
+	let lastIndex = 0;
+	for (const match of markdown.matchAll(MARKDOWN_IMAGE_RE)) {
+		const index = match.index ?? 0;
+		if (index > lastIndex) {
+			const text = markdown.slice(lastIndex, index);
+			if (text) parts.push({
+				type: "text",
+				value: text
+			});
+		}
+		const source = (match[1] || "").trim().replace(/^<|>$/g, "");
+		if (source) parts.push({
+			type: "image",
+			source
+		});
+		lastIndex = index + match[0].length;
+	}
+	if (lastIndex < markdown.length) {
+		const text = markdown.slice(lastIndex);
+		if (text) parts.push({
+			type: "text",
+			value: text
+		});
+	}
+	return parts.length ? parts : [{
+		type: "text",
+		value: markdown
+	}];
+};
 
 //#endregion
 //#region src/core/adapter/pipeline-qq.ts
@@ -1797,19 +1730,22 @@ 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.keyboard.enable && grouping.text.length) {
+	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];
 		grouping.buttons.push(...buttons);
 	}
 	/**
-	* 默认走 markdown 通道：
+	* 自动 Markdown 通道：
 	* text / at / 可转换为公网 URL 的图片通过 markdown content 渲染；无法转换的图片
 	* 与视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 单独补发。所有富媒体
 	* 都会优先通过 fileToUrl 取得公网地址，QQ 上传只做兜底。只有显式引用的
 	* 纯文本消息会降级为 msg_type=0，以保证 QQ 客户端能稳定显示引用气泡。
+	* 显式 segment.markdown 不受该自动通道开关影响。
 	*/
-	return sendQQMarkdown(ctx, contact, grouping, target);
+	if (ctx.cfg.markdown.enable) return sendQQMarkdown(ctx, contact, grouping, target);
+	return sendQQClassic(ctx, contact, grouping, target);
 };
 /**
 * Markdown 通道：合成一条 msg_type=2 + 可选 keyboard
@@ -1819,12 +1755,13 @@ const sendQQMarkdown = async (ctx, contact, grouping, target) => {
 	const lines = [];
 	if (grouping.text.length) lines.push(grouping.text.join(""));
 	const fallbackImages = await appendMarkdownImages(ctx, lines, grouping.qqImages);
-	if (grouping.markdowns.length) grouping.markdowns.forEach((m) => lines.push(m.markdown));
+	const markdownFallbackImages = await appendExplicitMarkdown(ctx, lines, grouping);
+	fallbackImages.push(...markdownFallbackImages);
 	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")));
+	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;
@@ -1843,6 +1780,47 @@ const sendQQMarkdown = async (ctx, contact, grouping, target) => {
 	return flushQQ(ctx, contact, grouping, items);
 };
 /**
+* 经典通道：文本走 msg_type=0，图片 / 富媒体走 msg_type=7。
+*/
+const sendQQClassic = async (ctx, contact, grouping, target) => {
+	const items = [];
+	const lines = [];
+	const images = [...grouping.qqImages];
+	if (grouping.text.length) lines.push(grouping.text.join(""));
+	if (!grouping.markdowns.length && (grouping.buttons.length || grouping.keyboards.length)) ctx.logger("warn", "Markdown 通道已关闭，button / keyboard 无法随普通文本发送，已跳过");
+	const content = lines.join("\n").trim();
+	if (content) items.push(ctx.super.qq.text(content));
+	for (const image of images) items.push(await buildQQMediaItem(ctx, target, contact.peer, "image", image));
+	for (const m of grouping.media) items.push(await buildQQMediaItem(ctx, target, contact.peer, m.kind, m.source, m.name));
+	await appendExplicitMarkdownItems(ctx, contact, grouping, target, items);
+	if (!items.length) items.push(ctx.super.qq.text("不支持发送的消息类型"));
+	return flushQQ(ctx, contact, grouping, items);
+};
+/**
+* 显式 `segment.markdown` 是调用方指定的发送类型，不受 Markdown 自动通道开关影响。
+*/
+const appendExplicitMarkdownItems = async (ctx, contact, grouping, target, items) => {
+	if (!grouping.markdowns.length) return;
+	const lines = [];
+	const fallbackImages = await appendExplicitMarkdown(ctx, lines, grouping);
+	if (contact.scene === "group") {
+		warnUnsupportedCommandEnterButtons$1(ctx, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
+		warnUnsupportedCommandEnterMarkdowns$1(ctx, grouping.markdowns.map((m) => m.markdown));
+	}
+	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));
+	}
+};
+const buildQQMediaItem = async (ctx, target, peer, type, source, name) => {
+	const resolved = await resolvePreferredMediaSource(ctx, type, source, name);
+	const res = resolved.via === "fallback" ? await ctx.super.media.uploadFallback(target, peer, type, resolved.source, false, name) : await ctx.super.media.upload(target, peer, type, resolved.source, false, name);
+	return ctx.super.qq.media(res.file_info);
+};
+/**
 * 将能转成公网 URL 的图片追加到 markdown 行，无法转换的图片返回给富媒体 fallback。
 *
 * @param ctx 适配器实例，用于输出降级日志。
@@ -1863,6 +1841,26 @@ const appendMarkdownImages = async (ctx, lines, files) => {
 	return fallback;
 };
 /**
+* 处理显式 segment.markdown 中的图片：可转公网 URL 的继续嵌入，无法转的改走富媒体。
+*/
+const appendExplicitMarkdown = async (ctx, lines, grouping) => {
+	const fallback = [];
+	for (const markdown of grouping.markdowns) for (const part of splitMarkdownImages(markdown.markdown)) {
+		if (part.type === "text") {
+			const text = part.value.trim();
+			if (text) lines.push(text);
+			continue;
+		}
+		const resolved = await resolvePreferredMediaSource(ctx, "image", part.source);
+		if (resolved.via === "fallback") {
+			fallback.push(part.source);
+			continue;
+		}
+		await appendImageUrlLine(lines, resolved.source);
+	}
+	return fallback;
+};
+/**
 * 生成单张 markdown 图片行。
 * 尺寸获取失败时使用保守默认尺寸，保证 fileToUrl 成功的图片仍走 markdown。
 *
@@ -1886,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。
@@ -1900,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) => {
@@ -1953,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);
@@ -2015,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;
@@ -2071,17 +2084,18 @@ const BUTTON_ONLY_MARKDOWN = "​";
 /**
 * 处理频道场景（子频道 + 私信）的发送
 *
-* 永远走 markdown 通道（msg_type=2），文本 / at / 图片均通过 markdown
-* 渲染。Markdown / Keyboard 已全量开放，老的 type=text/image 通道不再使用。
+* 默认把普通文本 / at / 图片通过 markdown 渲染。关闭自动 Markdown 通道后，
+* 普通文本和图片改走经典发送；显式 segment.markdown 仍按调用方指定走 Markdown。
 */
 const sendGuild = async (ctx, contact, elements) => {
 	const grouping = groupElements(contact.scene, elements);
-	if (ctx.cfg.keyboard.enable && grouping.text.length) {
+	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);
 	}
-	return sendGuildMarkdown(ctx, contact, grouping);
+	if (ctx.cfg.markdown.enable) return sendGuildMarkdown(ctx, contact, grouping);
+	return sendGuildClassic(ctx, contact, grouping);
 };
 /**
 * Markdown 通道
@@ -2099,7 +2113,13 @@ const sendGuildMarkdown = async (ctx, contact, grouping) => {
 		const mdImages = await imagesToMarkdown(allImages);
 		lines.push(...mdImages);
 	}
-	grouping.markdowns.forEach((m) => lines.push(m.markdown));
+	for (const markdown of grouping.markdowns) for (const part of splitMarkdownImages(markdown.markdown)) if (part.type === "text") {
+		const text = part.value.trim();
+		if (text) lines.push(text);
+	} else {
+		const [mdImage] = await imagesToMarkdown([part.source]);
+		lines.push(mdImage);
+	}
 	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) {
@@ -2110,6 +2130,55 @@ const sendGuildMarkdown = async (ctx, contact, grouping) => {
 	if (!items.length) items.push(ctx.super.guild.text("不支持发送的消息类型"));
 	return flushGuild(ctx, contact, grouping, items);
 };
+/**
+* 经典通道：文本走 content，图片按文档走 image / file_image 单独发送。
+*/
+const sendGuildClassic = async (ctx, contact, grouping) => {
+	const items = [];
+	const lines = [];
+	const images = [...grouping.guildImageUrls, ...grouping.guildImageFiles];
+	if (grouping.text.length) lines.push(grouping.text.join(""));
+	if (!grouping.markdowns.length && (grouping.buttons.length || grouping.keyboards.length)) ctx.logger("warn", "Markdown 通道已关闭，button / keyboard 无法随普通文本发送，已跳过");
+	const content = lines.join("\n").trim();
+	if (content) items.push(ctx.super.guild.text(content));
+	for (const image of images) items.push(await buildGuildImageItem(image));
+	await appendExplicitGuildMarkdownItems(ctx, contact, grouping, items);
+	if (!items.length) items.push(ctx.super.guild.text("不支持发送的消息类型"));
+	return flushGuild(ctx, contact, grouping, items);
+};
+/**
+* 显式 `segment.markdown` 是调用方指定的发送类型，不受 Markdown 自动通道开关影响。
+*/
+const appendExplicitGuildMarkdownItems = async (ctx, contact, grouping, items) => {
+	if (!grouping.markdowns.length) return;
+	const lines = [];
+	for (const markdown of grouping.markdowns) for (const part of splitMarkdownImages(markdown.markdown)) if (part.type === "text") {
+		const text = part.value.trim();
+		if (text) lines.push(text);
+	} else {
+		const [mdImage] = await imagesToMarkdown([part.source]);
+		lines.push(mdImage);
+	}
+	warnUnsupportedCommandEnterButtons(ctx, contact.scene, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
+	warnUnsupportedCommandEnterMarkdowns(ctx, contact.scene, grouping.markdowns.map((m) => m.markdown));
+	const keyboard = buildKeyboard(grouping);
+	const content = lines.length ? lines.join("\n") : BUTTON_ONLY_MARKDOWN;
+	items.push(ctx.super.guild.markdown({ content }, keyboard));
+};
+const buildGuildImageItem = async (source) => {
+	if (/^https?:\/\//i.test(source)) return {
+		type: "image",
+		image: source
+	};
+	const form = new FormData();
+	form.append("file_image", await common.buffer(source, { http: false }), { filename: resolveImageFilename(source) });
+	return form;
+};
+const resolveImageFilename = (source) => {
+	const file = source.split(/[?#]/)[0] || "";
+	const name = path.basename(file);
+	return name.includes(".") ? name : "image.jpg";
+};
 const buildKeyboard = (grouping) => {
 	const rows = [];
 	grouping.buttons.forEach((b) => rows.push(...karinToQQBot(b)));
@@ -2221,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));
 	}
 };
 /**
@@ -2367,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 适配器
 *
@@ -2411,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}`);
@@ -2431,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;
 				}
@@ -2731,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: "",
@@ -2745,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;
+		}
 	}
 	/**
 	* 获取群列表
@@ -2755,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");
+		}
 	}
 	/**
 	* 获取群成员列表
@@ -2803,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);
 	}
 	/**
 	* 下载文件到协议端本地
@@ -2840,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
@@ -3207,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,
@@ -3218,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));
 };
 /**
 * 写入引用消息上下文缓存。
@@ -3252,7 +3405,26 @@ 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。
+*
+* Karin 核心只能根据 `e.message_id` 生成 `segment.reply(e.message_id)`；而 QQ 群/单聊
+* 的可见引用需要 `message_scene.ext` 里的 `msg_idx=REFIDX_xxx`。这里仅转换
+* `reply.messageId === ev.d.id` 的那一个自动引用段，保留 `ev.d.id` 作为 Karin 标准
+* messageId，避免影响 getMsg / recallMsg / 被动回复 msg_id 等主链路。
+*/
+const normalizeQuickReplyReference = (elements, sourceMessageId, referenceMessageId) => {
+	if (!sourceMessageId || !referenceMessageId) return elements;
+	let normalized = false;
+	return elements.map((element) => {
+		if (!normalized && element.type === "reply" && element.messageId === sourceMessageId) {
+			normalized = true;
+			return segment.reply(referenceMessageId);
+		}
+		return element;
+	});
 };
 /**
 * 群消息（@机器人 / 普通消息合并入口）
@@ -3271,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, {
@@ -3280,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,
@@ -3299,7 +3470,7 @@ const onGroupMsg = (client, ev, opts) => {
 		time,
 		contact,
 		sender,
-		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
+		srcReply: (elements) => client.srcReply(e, [...normalizeQuickReplyReference(elements, karinMessageId, messageIndex), segment.pasmsg(ev.d.id)])
 	});
 	return e;
 };
@@ -3317,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, {
@@ -3326,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,
@@ -3345,7 +3515,7 @@ const onFriendMsg = (client, ev) => {
 		time,
 		contact,
 		sender,
-		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
+		srcReply: (elements) => client.srcReply(e, [...normalizeQuickReplyReference(elements, karinMessageId, messageIndex), segment.pasmsg(ev.d.id)])
 	});
 	return e;
 };
@@ -4249,25 +4419,34 @@ const QUICK_DISCONNECT_THRESHOLD_MS = 5e3;
 const QUICK_DISCONNECT_LIMIT = 3;
 const QUICK_DISCONNECT_DELAY_MS = 6e4;
 /**
-* 从 prodApi / sandboxApi 推导兜底的 WSS 地址
+* 从 proxy.prodApi / proxy.sandboxApi 推导兜底的 WS 地址
 * 官方实际长期返回的也是 wss://{host}/websocket/，不依赖 /gateway 也能直连
 */
-const buildFallbackWssUrl = (cfg) => {
-	return `${(cfg.sandbox ? cfg.sandboxApi : cfg.prodApi).replace(/^https?:\/\//i, "wss://").replace(/\/+$/, "")}/websocket/`;
+const buildFallbackWsUrl = (cfg) => {
+	return buildFallbackWsUrlFromApi(cfg.sandbox ? cfg.proxy.sandboxApi : cfg.proxy.prodApi);
 };
 /**
 * 获取网关地址：优先调 /gateway；失败 / 超时 / 限频 → 直接 fallback 到硬编码
 */
 const fetchGateway = async (cfg) => {
-	const apiUrl = cfg.sandbox ? cfg.sandboxApi : cfg.prodApi;
-	const fallback = buildFallbackWssUrl(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 accessToken = getBotAccessToken(cfg.appId);
 	if (!accessToken) {
-		log("warn", `${cfg.appId}: 无 access_token，使用硬编码 WSS ${fallback}`);
+		log("warn", `${cfg.appId}: 无 access_token，使用硬编码 WS ${fallback}`);
 		return fallback;
 	}
 	try {
-		const { data } = await axios.get(`${apiUrl}/gateway`, {
+		const { data } = await axios.get(joinHttpPath(apiUrl, "gateway"), {
 			headers: {
 				Authorization: `QQBot ${accessToken}`,
 				"User-Agent": getUserAgent()
@@ -4275,18 +4454,18 @@ const fetchGateway = async (cfg) => {
 			timeout: GATEWAY_FETCH_TIMEOUT_MS
 		});
 		if (data?.url) return data.url;
-		log("warn", `${cfg.appId}: /gateway 返回为空，使用硬编码 WSS ${fallback}`);
+		log("warn", `${cfg.appId}: /gateway 返回为空，使用硬编码 WS ${fallback}`);
 		return fallback;
 	} 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}，使用硬编码 WSS ${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 ${fallback}`);
 		} else {
 			const reason = err?.message || "unknown";
-			log("warn", `${cfg.appId}: /gateway 调用失败 (${reason})，使用硬编码 WSS ${fallback}`);
+			log("warn", `${cfg.appId}: /gateway 调用失败 (${reason})，使用硬编码 WS ${fallback}`);
 		}
 		return fallback;
 	}
@@ -4418,7 +4597,7 @@ const onClose = (cfg, intents, attempt, event, client) => {
 	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(() => {
+			getAccessToken(cfg.proxy.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));
 			});
@@ -4499,18 +4678,21 @@ const initState = /* @__PURE__ */ new Map();
 const hashConfig = (bot) => JSON.stringify({
 	appId: bot.appId,
 	secret: bot.secret,
-	tokenApi: bot.tokenApi,
-	prodApi: bot.prodApi,
-	sandboxApi: bot.sandboxApi,
+	proxy: bot.proxy,
 	sandbox: bot.sandbox,
 	event: bot.event,
 	keyboard: bot.keyboard,
+	markdown: bot.markdown,
 	messageCache: bot.messageCache
 });
 /**
 * 创建单个 Bot 实例
 */
-const createBot = async (bot) => {
+const createBot = async (input) => {
+	const bot = {
+		...input,
+		proxy: normalizeProxyConfig(input.proxy)
+	};
 	const appId = String(bot.appId);
 	if (!appId) {
 		logger.warn("[QQ Official Bot] 配置缺少 appId，跳过");
@@ -4532,8 +4714,8 @@ const createBot = async (bot) => {
 		offAll(appId);
 		stopTokenRefresh(appId);
 		logger.info(`[QQ Official Bot][${appId}] 获取 access_token...`);
-		await getAccessToken(bot.tokenApi, appId, bot.secret);
-		const baseUrl = bot.sandbox ? bot.sandboxApi : bot.prodApi;
+		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));
 		const me = await api.meta.getMe();
 		const client = new AdapterQQBot(bot, api);