@karinjs/adapter-qqbot 3.1.0 → 3.2.0

package/dist/index.js

@@ -1,9 +1,10 @@
 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-QpIUJhxK.js";
+import { a as DATA_URL_BASE64_RE, i as BASE64_PREFIX_RE, n as getImageSize, o as HTTP_URL_RE, r as random, t as fakeEvent } from "./common-OHGAoohl.js";
+import "./utils-C0oZi6PR.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 { URL } from "url";
+import karin, { AdapterBase, app, buttonHandle, common, createDirectMessage, createFriendDecreaseNotice, createFriendIncreaseNotice, createFriendMessage, createGroupApplyRequest, createGroupInviteRequest, createGroupMemberAddNotice, createGroupMemberDelNotice, createGroupMessage, createGuildMessage, fileToUrl, fileToUrlHandlerKey, getMimeType, handler, karin as karin$1, karinToQQBot, logger, registerBot, segment, senderGroup, unregisterBot } from "node-karin";
+import { URL as URL$1 } from "url";
 import lodash from "node-karin/lodash";
 import { createReadStream } from "node:fs";
 import axios from "node-karin/axios";
@@ -18,6 +19,97 @@ import { WebSocket } from "node-karin/ws";
 import express from "node-karin/express";
 import nacl from "tweetnacl";
 
+//#region src/core/constants/api.ts
+/** QQBot 统一 API 地址 */
+const QQAPIBASEURL = "https://api.bot.qq.com";
+
+//#endregion
+//#region src/core/constants/media.ts
+/** QQ 上传接口的 file_type 取值。 */
+const FILE_TYPE = {
+	image: 1,
+	video: 2,
+	record: 3,
+	file: 4
+};
+/** 各类资源的 QQ 上传上限。 */
+const MAX_UPLOAD_SIZE = {
+	image: 30 * 1024 * 1024,
+	video: 100 * 1024 * 1024,
+	record: 20 * 1024 * 1024,
+	file: 100 * 1024 * 1024
+};
+/** 上传错误中展示的资源类型名称。 */
+const MEDIA_TYPE_LABEL = {
+	image: "图片",
+	video: "视频",
+	record: "语音",
+	file: "文件"
+};
+/** fileToUrl / 分片上传没有业务文件名时使用的默认值。 */
+const DEFAULT_FILENAME = {
+	image: "image.jpg",
+	video: "video.mp4",
+	record: "record.mp3",
+	file: "file.bin"
+};
+/**
+* 无法从文件名推断类型时，各富媒体类型使用的兜底 MIME。
+*
+* `file` 不在表内：QQ 对 `file_type=4` 不返回 `raw_url`，拿不到直链。
+*/
+const DEFAULT_MIME = {
+	image: "image/jpeg",
+	video: "video/mp4",
+	record: "audio/mpeg"
+};
+/** fallback 上传超过该大小时走 QQ 分片上传。 */
+const LARGE_UPLOAD_THRESHOLD = 5 * 1024 * 1024;
+/** COS 用于覆盖下载响应类型的 query 参数名。 */
+const RESPONSE_TYPE_PARAM = "response-content-type";
+/** QQ upload_prepare 需要的前 10,002,432 字节 MD5。 */
+const MD5_10M_SIZE = 10002432;
+/** 富媒体上传比普通接口慢，尤其本地视频会走 file_data。 */
+const MEDIA_UPLOAD_TIMEOUT = 12e4;
+/** URL 回源下载兜底超时。 */
+const MEDIA_DOWNLOAD_TIMEOUT = 12e4;
+/** 每个分片 PUT 到 QQ 临时地址的超时时间。 */
+const PART_UPLOAD_TIMEOUT = 3e5;
+/** upload_part_finish 普通失败重试基础间隔。 */
+const PART_FINISH_BASE_DELAY = 1e3;
+/** upload_part_finish 命中这些业务码时，需要按服务端给出的窗口持续重试。 */
+const PART_FINISH_RETRYABLE_CODES = /* @__PURE__ */ new Set([40093001]);
+/** 服务端未返回 retry_timeout 时，持续重试的默认时间。 */
+const PART_FINISH_DEFAULT_RETRY_TIMEOUT = 120 * 1e3;
+/** 持续重试窗口上限，避免服务端返回异常值导致任务长时间占用。 */
+const PART_FINISH_MAX_RETRY_TIMEOUT = 600 * 1e3;
+/** 持续重试时的固定间隔。 */
+const PART_FINISH_RETRY_INTERVAL = 1e3;
+/** 分片完成接口失败重试基础间隔。 */
+const COMPLETE_UPLOAD_BASE_DELAY = 2e3;
+/** upload_prepare 返回该业务码时表示大文件上传额度受限。 */
+const UPLOAD_PREPARE_DAILY_LIMIT_CODE = 40093002;
+
+//#endregion
+//#region src/core/constants/message.ts
+/** 群聊 event_id 白名单 */
+const GROUP_EVENT_WHITELIST = /* @__PURE__ */ new Set([
+	"INTERACTION_CREATE",
+	"GROUP_ADD_ROBOT",
+	"GROUP_MSG_RECEIVE"
+]);
+/** 单聊 event_id 白名单 */
+const FRIEND_EVENT_WHITELIST = /* @__PURE__ */ new Set([
+	"INTERACTION_CREATE",
+	"C2C_MSG_RECEIVE",
+	"FRIEND_ADD"
+]);
+/** 平台限制的最大禁言时长：30 天 */
+const MAX_GROUP_MUTE_SECONDS = 720 * 60 * 60;
+/** QQ 客户端回调按钮需要快速 ACK，超时必须小于平台等待窗口。 */
+const INTERACTION_ACK_TIMEOUT = 2800;
+
+//#endregion
 //#region src/core/api/error.ts
 /**
 * OpenAPI 错误码映射表
@@ -628,8 +720,6 @@ var RequestApi = class extends Http {
 
 //#endregion
 //#region src/core/api/messages.ts
-/** 输入中状态默认展示时长（秒），平台 typing 窗口约 60s */
-const INPUT_NOTIFY_DEFAULT_SECOND = 60;
 /**
 * 消息发送 + 撤回
 */
@@ -648,7 +738,7 @@ var MessagesApi = class extends Http {
 	* @param inputSecond 展示时长（秒），默认 60
 	* @param passive 被动消息参数（msg_id / event_id / msg_seq），可选
 	*/
-	sendFriendInputNotify(openid, inputSecond = INPUT_NOTIFY_DEFAULT_SECOND, passive) {
+	sendFriendInputNotify(openid, inputSecond = 60, passive) {
 		return this.post(`/v2/users/${openid}/messages`, {
 			msg_type: 6,
 			input_notify: {
@@ -758,73 +848,50 @@ const setCachedUpload = async (scene, peer, type, contentHash, response) => {
 
 //#endregion
 //#region src/core/api/media.ts
-const FILE_TYPE = {
-	image: 1,
-	video: 2,
-	record: 3,
-	file: 4
-};
-/** 各类资源的 QQ 上传上限。 */
-const MAX_UPLOAD_SIZE = {
-	image: 30 * 1024 * 1024,
-	video: 100 * 1024 * 1024,
-	record: 20 * 1024 * 1024,
-	file: 100 * 1024 * 1024
-};
-/** 上传错误中展示的资源类型名称。 */
-const MEDIA_TYPE_LABEL = {
-	image: "图片",
-	video: "视频",
-	record: "语音",
-	file: "文件"
+/**
+* 推断直链应当声明的 MIME。
+*
+* 优先按文件名判断，这样 png / gif 不会被统一说成 jpeg；文件名没有扩展名或
+* 扩展名不认识时，退回该富媒体类型的兜底值。
+*
+* @param type 富媒体类型。
+* @param fileName 可选文件名。
+* @returns MIME 字符串；该类型拿不到直链时返回 undefined。
+*/
+const resolveDirectLinkMime = (type, fileName) => {
+	const fallback = DEFAULT_MIME[type];
+	if (!fallback) return void 0;
+	if (!fileName) return fallback;
+	const guessed = getMimeType(fileName);
+	/** karin 认不出的扩展名会返回 octet-stream，此时用类型兜底更准确。 */
+	if (!guessed || guessed === "application/octet-stream") return fallback;
+	/** 扩展名与富媒体类型不是同一族时同样以类型为准，避免声明成错误的族。 */
+	const family = fallback.split("/")[0];
+	return guessed.startsWith(`${family}/`) ? guessed : fallback;
 };
-/** fallback 上传超过该大小时走 QQ 分片上传。 */
-const LARGE_UPLOAD_THRESHOLD = 5 * 1024 * 1024;
-/** QQ upload_prepare 需要的前 10,002,432 字节 MD5。 */
-const MD5_10M_SIZE = 10002432;
-/** 分片上传时没有业务文件名的默认值。 */
-const DEFAULT_FILENAME$1 = {
-	image: "image.jpg",
-	video: "video.mp4",
-	record: "record.mp3",
-	file: "file.bin"
+/**
+* 把 QQ 返回的下载直链改造成可直接嵌入消息的地址。
+*
+* 直链本身不声明 Content-Type，客户端可能因此拒绝按图片/视频渲染，所以要追加
+* COS 的响应类型参数。这里用 URL 对象改写 query，避免手工拼接破坏预签名参数。
+*
+* @param rawUrl QQ 分片合并返回的下载直链。
+* @param type 富媒体类型。
+* @param fileName 可选文件名，用于推断更精确的 MIME。
+* @returns 已声明响应类型的直链；类型不支持或直链无法解析时原样返回。
+*/
+const buildDirectLink = (rawUrl, type, fileName) => {
+	const mime = resolveDirectLinkMime(type, fileName);
+	if (!mime) return rawUrl;
+	try {
+		const url = new URL(rawUrl);
+		url.searchParams.set(RESPONSE_TYPE_PARAM, mime);
+		return url.toString();
+	} catch {
+		/** QQ 返回了非法 URL 时不做改写，交给调用方按原样使用。 */
+		return rawUrl;
+	}
 };
-/** 富媒体上传比普通接口慢，尤其本地视频会走 file_data。 */
-const MEDIA_UPLOAD_TIMEOUT = 12e4;
-/** URL 回源下载兜底超时。 */
-const MEDIA_DOWNLOAD_TIMEOUT = 12e4;
-/** 每个分片 PUT 到 QQ 临时地址的超时时间。 */
-const PART_UPLOAD_TIMEOUT = 3e5;
-/** 每个分片 PUT 失败后的重试次数。 */
-const PART_UPLOAD_RETRIES = 2;
-/** upload_part_finish 普通失败重试次数。 */
-const PART_FINISH_RETRIES = 2;
-/** upload_part_finish 普通失败重试基础间隔。 */
-const PART_FINISH_BASE_DELAY = 1e3;
-/** upload_part_finish 命中这些业务码时，需要按服务端给出的窗口持续重试。 */
-const PART_FINISH_RETRYABLE_CODES = /* @__PURE__ */ new Set([40093001]);
-/** 服务端未返回 retry_timeout 时，持续重试的默认时间。 */
-const PART_FINISH_DEFAULT_RETRY_TIMEOUT = 120 * 1e3;
-/** 持续重试窗口上限，避免服务端返回异常值导致任务长时间占用。 */
-const PART_FINISH_MAX_RETRY_TIMEOUT = 600 * 1e3;
-/** 持续重试时的固定间隔。 */
-const PART_FINISH_RETRY_INTERVAL = 1e3;
-/** 分片完成接口失败重试次数。 */
-const COMPLETE_UPLOAD_RETRIES = 2;
-/** 分片完成接口失败重试基础间隔。 */
-const COMPLETE_UPLOAD_BASE_DELAY = 2e3;
-/** upload_prepare 返回该业务码时表示大文件上传额度受限。 */
-const UPLOAD_PREPARE_DAILY_LIMIT_CODE = 40093002;
-/** QQ 没返回建议并发数时的默认并发。 */
-const DEFAULT_PART_CONCURRENCY = 1;
-/** 本地限制的最大分片并发，避免服务端返回过大值。 */
-const MAX_PART_CONCURRENCY = 10;
-/** HTTP(S) URL 可直接交给 QQ 平台拉取。 */
-const HTTP_URL_RE$2 = /^https?:\/\//i;
-/** Karin 常见 base64 图片/媒体前缀。 */
-const BASE64_PREFIX_RE = /^base64:\/\//i;
-/** 标准 data URL 的 base64 前缀。 */
-const DATA_URL_BASE64_RE = /^data:[^;,]+;base64,/i;
 /**
 * 判断字符串是否明显是本地文件路径。
 * 不明显的字符串按裸 base64 兼容处理，避免破坏旧调用方式。
@@ -866,8 +933,8 @@ 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];
+	if (!value) return DEFAULT_FILENAME[type];
+	return path.basename(value) || DEFAULT_FILENAME[type];
 };
 /**
 * 检查 fallback 资源大小是否超过 QQ 对应类型上限。
@@ -916,7 +983,7 @@ const downloadRemoteAsBase64 = async (url) => {
 */
 const buildUploadSource = async (source) => {
 	const value = source.trim();
-	if (HTTP_URL_RE$2.test(value)) return { url: value };
+	if (HTTP_URL_RE.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 };
@@ -932,7 +999,7 @@ const buildUploadSource = async (source) => {
 const buildFallbackSource = async (type, source, fileName) => {
 	const value = source.trim();
 	const normalizedName = normalizeUploadFileName(type, fileName);
-	if (HTTP_URL_RE$2.test(value)) {
+	if (HTTP_URL_RE.test(value)) {
 		const buffer = await downloadRemoteAsBuffer(value);
 		return {
 			kind: "buffer",
@@ -990,7 +1057,7 @@ const computeUploadHashes = async (source) => {
 		return {
 			md5,
 			sha1: crypto.createHash("sha1").update(source.buffer).digest("hex"),
-			md510m: source.size > MD5_10M_SIZE ? crypto.createHash("md5").update(source.buffer.subarray(0, MD5_10M_SIZE)).digest("hex") : md5
+			md510m: source.size > 10002432 ? crypto.createHash("md5").update(source.buffer.subarray(0, MD5_10M_SIZE)).digest("hex") : md5
 		};
 	}
 	return new Promise((resolve, reject) => {
@@ -1046,7 +1113,7 @@ const readPart = async (source, handle, offset, length) => {
 */
 const putPart = async (url, data, partIndex, totalParts) => {
 	let lastError;
-	for (let attempt = 0; attempt <= PART_UPLOAD_RETRIES; attempt++) try {
+	for (let attempt = 0; attempt <= 2; attempt++) try {
 		await axios.put(url, data, {
 			headers: {
 				"Content-Type": "application/octet-stream",
@@ -1059,7 +1126,7 @@ const putPart = async (url, data, partIndex, totalParts) => {
 		return;
 	} catch (err) {
 		lastError = err;
-		if (attempt < PART_UPLOAD_RETRIES) await new Promise((resolve) => setTimeout(resolve, 500 * (attempt + 1)));
+		if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 500 * (attempt + 1)));
 	}
 	throw new Error(`上传分片失败：${partIndex}/${totalParts}，${lastError instanceof Error ? lastError.message : String(lastError)}`);
 };
@@ -1173,7 +1240,7 @@ var MediaApi = class extends Http {
 			const cached = await getCachedUpload(scene, peer, type, hashes.md5);
 			if (cached) return cached;
 		}
-		if (!srvSendMsg && fallbackSource.size >= LARGE_UPLOAD_THRESHOLD) {
+		if (!srvSendMsg && fallbackSource.size >= 5242880) {
 			const response = await this.uploadChunked(scene, peer, type, fallbackSource, hashes);
 			if (hashes) await setCachedUpload(scene, peer, type, hashes.md5, response);
 			return response;
@@ -1189,6 +1256,39 @@ var MediaApi = class extends Http {
 		return response;
 	}
 	/**
+	* 上传资源并取回它的公网直链。
+	*
+	* 分片上传的合并响应里带 `raw_url`，等价于一个临时图床：拿到地址后图片就能以
+	* markdown 图片语法嵌进 msg_type=2，和文本、按钮合成一条消息，不必退化成
+	* 独立的 msg_type=7 富媒体消息。
+	*
+	* 与 `uploadFallback` 的差别只有一处：那边按体积决定是否分片，目标是拿
+	* `file_info`；这里必须无条件分片，否则服务端不会给出 `raw_url`。
+	*
+	* 直链的存活时间等于响应里的 `ttl`，属于临时地址，只适合当次发送使用。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid，决定上传归属的会话
+	* @param type 文件类型；`file` 无直链可取
+	* @param source 本地路径、http url、data URL、base64:// 或裸 base64
+	* @param fileName 文件名，同时用于推断直链声明的 MIME
+	* @returns 可直接嵌入消息的直链，以及原始上传响应
+	*/
+	async uploadForUrl(scene, peer, type, source, fileName) {
+		if (type === "file") throw new Error(`QQ 不为${MEDIA_TYPE_LABEL.file}类型返回下载直链，无法当图床使用`);
+		const prepared = await buildFallbackSource(type, source, fileName);
+		assertUploadSize(type, prepared.size);
+		const hashes = await computeUploadHashes(prepared);
+		const reused = await getCachedUpload(scene, peer, type, hashes.md5);
+		const response = reused?.raw_url ? reused : await this.uploadChunked(scene, peer, type, prepared, hashes);
+		if (!response.raw_url) throw new Error(`${MEDIA_TYPE_LABEL[type]}上传完成但未返回下载直链，无法当图床使用`);
+		if (response !== reused) await setCachedUpload(scene, peer, type, hashes.md5, response);
+		return {
+			url: buildDirectLink(response.raw_url, type, prepared.fileName),
+			response
+		};
+	}
+	/**
 	* 确认单个分片已完成上传。
 	*
 	* QQ 有时会在分片刚 PUT 完时短暂返回 40093001，此时需要在服务端给出的
@@ -1201,7 +1301,7 @@ var MediaApi = class extends Http {
 	*/
 	async finishUploadPart(scene, peer, body, retryTimeout) {
 		let lastError;
-		for (let attempt = 0; attempt <= PART_FINISH_RETRIES; attempt++) try {
+		for (let attempt = 0; attempt <= 2; attempt++) try {
 			await this.post(`/v2/${scene}s/${peer}/upload_part_finish`, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 			return;
 		} catch (err) {
@@ -1210,7 +1310,7 @@ var MediaApi = class extends Http {
 				return;
 			}
 			lastError = err;
-			if (attempt < PART_FINISH_RETRIES) await sleep(PART_FINISH_BASE_DELAY * 2 ** attempt);
+			if (attempt < 2) await sleep(PART_FINISH_BASE_DELAY * 2 ** attempt);
 		}
 		throwError(lastError);
 	}
@@ -1249,11 +1349,11 @@ var MediaApi = class extends Http {
 	async completeChunkedUpload(scene, peer, uploadId) {
 		let lastError;
 		const body = { upload_id: uploadId };
-		for (let attempt = 0; attempt <= COMPLETE_UPLOAD_RETRIES; attempt++) try {
+		for (let attempt = 0; attempt <= 2; attempt++) try {
 			return await this.post(`/v2/${scene}s/${peer}/files`, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 		} catch (err) {
 			lastError = err;
-			if (attempt < COMPLETE_UPLOAD_RETRIES) await sleep(COMPLETE_UPLOAD_BASE_DELAY * 2 ** attempt);
+			if (attempt < 2) await sleep(COMPLETE_UPLOAD_BASE_DELAY * 2 ** attempt);
 		}
 		return throwError(lastError);
 	}
@@ -1280,11 +1380,11 @@ var MediaApi = class extends Http {
 		};
 		prepareBody["md5_10m"] = hashes.md510m;
 		const prepare = await this.post(`/v2/${scene}s/${peer}/upload_prepare`, prepareBody, { timeout: MEDIA_UPLOAD_TIMEOUT }).catch((err) => {
-			if (openApiCode(err) === UPLOAD_PREPARE_DAILY_LIMIT_CODE) throw new Error(`QQ 大文件上传额度已达上限，${MEDIA_TYPE_LABEL[type]}暂时无法通过 fallback 直传：${source.fileName} (${formatBytes(source.size)})`);
+			if (openApiCode(err) === 40093002) throw new Error(`QQ 大文件上传额度已达上限，${MEDIA_TYPE_LABEL[type]}暂时无法通过 fallback 直传：${source.fileName} (${formatBytes(source.size)})`);
 			return throwError(err);
 		});
 		if (!prepare.parts.length) throw new Error("分片上传准备失败：QQ 未返回分片信息");
-		const concurrency = Math.min(prepare.concurrency || DEFAULT_PART_CONCURRENCY, MAX_PART_CONCURRENCY, prepare.parts.length);
+		const concurrency = Math.min(prepare.concurrency || 1, 10, prepare.parts.length);
 		const handle = source.kind === "local" ? await open(source.file, "r") : void 0;
 		try {
 			const tasks = prepare.parts.map((part) => async () => {
@@ -1310,8 +1410,6 @@ var MediaApi = class extends Http {
 
 //#endregion
 //#region src/core/api/interaction.ts
-/** QQ 客户端回调按钮需要快速 ACK，超时必须小于平台等待窗口。 */
-const INTERACTION_ACK_TIMEOUT = 2800;
 /**
 * INTERACTION_CREATE 回应
 */
@@ -1743,11 +1841,17 @@ const buildQQMsg = {
 			ark
 		};
 	},
-	/** 构造 msg_type=7 富媒体消息体 */
-	media(fileInfo) {
+	/**
+	* 构造 msg_type=7 富媒体消息体
+	*
+	* @param fileInfo 上传富媒体返回的 file_info。
+	* @param keyboard 可选内嵌键盘，用于按钮随富媒体一起发送。
+	*/
+	media(fileInfo, keyboard) {
 		return {
 			msg_type: 7,
-			media: { file_info: fileInfo }
+			media: { file_info: fileInfo },
+			keyboard
 		};
 	}
 };
@@ -2112,13 +2216,46 @@ const groupElements = (scene, elements) => {
 //#endregion
 //#region src/core/adapter/media-source.ts
 /** HTTP(S) 资源已经是可直接传给 QQ 平台的公网地址。 */
-const HTTP_URL_RE$1 = /^https?:\/\//i;
-/** fileToUrl 需要文件名来推断上传类型；没有业务文件名时使用这些默认值。 */
-const DEFAULT_FILENAME = {
-	image: "image.jpg",
-	video: "video.mp4",
-	record: "record.mp3",
-	file: "file.bin"
+/**
+* 把带 MIME 头的完整 data URL（`data:image/png;base64,...`）归一为 Karin 标准
+* 的 `base64://` 形式，其余来源原样返回。
+*
+* 下游插件经常直接给出完整 data URL；QQ 上传层认识它，但 karin 的
+* `common.buffer` 和不少第三方 fileToUrl 处理器只认 `base64://`，因此在进入
+* 发送链路时统一归一，避免同一资源在不同环节表现不一致。
+*
+* @param source Karin 消息段里的 file 字段。
+* @returns 归一后的来源字符串。
+*/
+const normalizeMediaSource = (source) => {
+	return DATA_URL_BASE64_RE.test(source) ? source.replace(DATA_URL_BASE64_RE, "base64://") : source;
+};
+/** 带 file 字段的富媒体消息段类型。 */
+const MEDIA_ELEMENT_TYPES = /* @__PURE__ */ new Set([
+	"image",
+	"video",
+	"record",
+	"file"
+]);
+/**
+* 把消息段里带 MIME 头的完整 data URL（`data:image/png;base64,...`）统一归一为
+* Karin 标准的 `base64://` 形式。下游的 fileToUrl 处理器与 karin `common.buffer`
+* 大多只认后者，在进入发送链路前归一可以保证各环节行为一致。
+*
+* @param elements 待发送的消息段。
+* @returns 归一后的消息段；无需归一时返回原数组。
+*/
+const normalizeMediaElements = (elements) => {
+	return elements.map((el) => {
+		if (!MEDIA_ELEMENT_TYPES.has(el.type)) return el;
+		const file = el.file;
+		if (typeof file !== "string") return el;
+		const normalized = normalizeMediaSource(file);
+		return normalized === file ? el : {
+			...el,
+			file: normalized
+		};
+	});
 };
 /**
 * 当前 Karin 运行时是否注册了 fileToUrl 处理器。
@@ -2130,37 +2267,58 @@ const hasFileToUrlHandler = () => handler.has(fileToUrlHandlerKey);
 * @param source Karin 消息段里的 file 字段。
 * @returns 是否为 HTTP(S) URL。
 */
-const isHttpMediaSource = (source) => HTTP_URL_RE$1.test(source);
+const isHttpMediaSource = (source) => HTTP_URL_RE.test(source);
 /**
 * 优先把本地/base64 富媒体转换为公网 URL；没有处理器或转换失败时返回原始来源。
 *
 * QQ 官方的普通 file_data 上传对视频等资源更容易失败，因此 adapter 层始终把
 * fileToUrl 作为主路径，QQ 上传只做兜底。
 *
-* @param ctx 适配器实例，用于记录降级日志。
+* @param ctx 适配器实例，用于记录降级日志并标明执行发送的 bot。
 * @param type 富媒体类型。
 * @param source Karin 消息段里的 file 字段。
 * @param filename 可选文件名，主要用于 file 消息。
+* @param origin 本次发送归属的上传会话，供需要借 QQ 通道上传的处理器使用。
+* @param purpose 拿到 URL 之后的用途，默认按富媒体上传处理。
 * @returns 解析后的首选来源和来源类型。
 */
-const resolvePreferredMediaSource = async (ctx, type, source, filename) => {
-	if (isHttpMediaSource(source)) return {
-		source,
+const resolvePreferredMediaSource = async (ctx, type, source, filename, origin, purpose = "media") => {
+	const normalized = normalizeMediaSource(source);
+	if (isHttpMediaSource(normalized)) return {
+		source: normalized,
 		via: "public-url"
 	};
 	if (!hasFileToUrlHandler()) return {
-		source,
+		source: normalized,
 		via: "fallback"
 	};
 	try {
+		const extra = {
+			selfId: ctx.selfId,
+			purpose,
+			origin
+		};
+		const result = await fileToUrl(type, normalized, filename || DEFAULT_FILENAME[type], extra);
+		/**
+		* `handler.has` 只判断该 key 下是否注册过处理器，不代表真的有处理器接手：
+		* 所有处理器都调用 next() 放行时，fileToUrl 会返回 undefined。此时不属于
+		* 异常，安静地走 QQ 上传兜底即可，不必输出 warn 噪音。
+		*/
+		if (!result?.url) {
+			ctx.logger("debug", `[sendQQ] 没有 fileToUrl 处理器接手 ${type}，改用 QQ 上传兜底`);
+			return {
+				source: normalized,
+				via: "fallback"
+			};
+		}
 		return {
-			source: (await fileToUrl(type, source, filename || DEFAULT_FILENAME[type])).url,
+			source: result.url,
 			via: "file-to-url"
 		};
 	} catch (err) {
 		ctx.logger("warn", `[sendQQ] ${type} 转 URL 失败，改用 QQ 上传兜底:`, err);
 		return {
-			source,
+			source: normalized,
 			via: "fallback"
 		};
 	}
@@ -2168,21 +2326,87 @@ const resolvePreferredMediaSource = async (ctx, type, source, filename) => {
 
 //#endregion
 //#region src/core/adapter/text-to-md.ts
-const MARKDOWN_IMAGE_RE = /!\[[^\]]*]\(\s*(<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\s*\)/g;
+const MARKDOWN_IMAGE_RE = /!\[([^\]]*)]\(\s*(<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\s*\)/g;
+/**
+* QQ markdown 图片语法里的显式尺寸：`#100px #100px`。
+*
+* `#` 是必需的——`100px 100px` 这种省略写法 QQ 前端不会按尺寸渲染，只能算
+* 普通描述文本。QQ 客户端按这个声明尺寸渲染而不是图片的物理分辨率——开发者
+* 显式写出尺寸是有布局意图的（比如把一张高清图当头像展示），重建时必须原样
+* 保留。
+*/
+const EXPLICIT_IMAGE_SIZE_RE = /#(\d+)px\s+#(\d+)px/;
+/**
+* 调用 fileToUrl 并确认真的拿到了 URL。
+*
+* Karin 的 handler 链允许每个处理器调用 next() 放行，全部放行时 fileToUrl 会
+* 返回 undefined 而不是抛错。这里统一转成明确的错误信息，避免调用方拿到
+* undefined 后在解构处报出难以定位的 TypeError。
+*
+* @param source 图片来源。
+* @param extra 传给处理器的附加信息，至少标明执行发送的 bot。
+* @returns fileToUrl 的图片结果。
+*/
+const imageToUrl = async (source, extra) => {
+	const result = await fileToUrl("image", normalizeMediaSource(source), "image.jpg", extra);
+	if (!result?.url) throw new Error("[Handler][Error]: 没有 fileToUrl 处理器接手图片转 URL");
+	return result;
+};
+/**
+* 生成一行 markdown 图片。
+*
+* alt 里带显式尺寸（`#100px #100px`）时原样保留，不探测图片真实尺寸——QQ 按
+* 声明尺寸渲染，覆盖它会破坏开发者的布局意图。没有显式尺寸时才用传入的或
+* 探测到的真实宽高补全。
+*
+* @param url 图片的最终公网 URL。
+* @param alt 原始 alt 文本，可能包含显式尺寸声明。
+* @param size 已知的图片真实尺寸；未提供且 alt 无显式尺寸时探测 URL。
+* @returns markdown 图片行。
+*/
+const buildMarkdownImageLine = async (url, alt = "", size) => {
+	const explicit = alt.match(EXPLICIT_IMAGE_SIZE_RE);
+	if (explicit) return `![${alt.replace(EXPLICIT_IMAGE_SIZE_RE, "").trim()} #${explicit[1]}px #${explicit[2]}px](${url})`;
+	const desc = alt.trim() || "karin";
+	const resolved = size ?? await getImageSize(url).catch(() => ({
+		width: 300,
+		height: 300
+	}));
+	return `![${desc} #${resolved.width}px #${resolved.height}px](${url})`;
+};
 /**
 * 将图片列表合并到一段 markdown 文本内（每张图占一行）
+*
+* @param urls 图片来源列表。
+* @param extra 传给 fileToUrl 处理器的附加信息。
+* @returns markdown 图片行。
 */
-const imagesToMarkdown = async (urls) => {
+const imagesToMarkdown = async (urls, extra) => {
 	return Promise.all(urls.map(async (file) => {
-		if (file.startsWith("http")) {
-			const { width, height } = await getImageSize(file);
-			return `![karin #${width}px #${height}px](${file})`;
-		}
-		const { url, width, height } = await fileToUrl("image", file, "image.jpg");
-		return `![karin #${width}px #${height}px](${url})`;
+		if (file.startsWith("http")) return buildMarkdownImageLine(file);
+		const { url, width, height } = await imageToUrl(file, extra);
+		return buildMarkdownImageLine(url, "", {
+			width,
+			height
+		});
 	}));
 };
 /**
+* 把一个拆分出来的 markdown 图片转成图片行，保留原始 alt 与显式尺寸。
+*
+* @param part splitMarkdownImages 拆出的图片片段。
+* @param extra 传给 fileToUrl 处理器的附加信息。
+* @returns markdown 图片行。
+*/
+const markdownPartToLine = async (part, extra) => {
+	if (part.source.startsWith("http")) return buildMarkdownImageLine(part.source, part.alt);
+	const { url, width, height } = await imageToUrl(part.source, extra);
+	return buildMarkdownImageLine(url, part.alt, {
+		width,
+		height
+	});
+};
+/**
 * 将 markdown 文本拆为普通文本片段与图片来源。
 */
 const splitMarkdownImages = (markdown) => {
@@ -2197,10 +2421,12 @@ const splitMarkdownImages = (markdown) => {
 				value: text
 			});
 		}
-		const source = (match[1] || "").trim().replace(/^<|>$/g, "");
+		const alt = match[1] ?? "";
+		const source = (match[2] || "").trim().replace(/^<|>$/g, "");
 		if (source) parts.push({
 			type: "image",
-			source
+			source: normalizeMediaSource(source),
+			alt
 		});
 		lastIndex = index + match[0].length;
 	}
@@ -2219,25 +2445,6 @@ const splitMarkdownImages = (markdown) => {
 
 //#endregion
 //#region src/core/adapter/pipeline-qq.ts
-/** QQ 官方限制：单聊中同一 `msg_id` 最多发送四次被动回复。 */
-const C2C_PASSIVE_REPLY_LIMIT = 4;
-/** QQ keyboard 限制：最多 5 行，每行最多 5 个按钮。 */
-const KEYBOARD_MAX_ROWS$1 = 5;
-const KEYBOARD_MAX_BUTTONS_PER_ROW$1 = 5;
-/** 只有按钮没有文本时仍需提供非空 markdown 内容。 */
-const BUTTON_ONLY_MARKDOWN$1 = "​";
-/** 群聊 event_id 白名单 */
-const GROUP_EVENT_WHITELIST = /* @__PURE__ */ new Set([
-	"INTERACTION_CREATE",
-	"GROUP_ADD_ROBOT",
-	"GROUP_MSG_RECEIVE"
-]);
-/** 单聊 event_id 白名单 */
-const FRIEND_EVENT_WHITELIST = /* @__PURE__ */ new Set([
-	"INTERACTION_CREATE",
-	"C2C_MSG_RECEIVE",
-	"FRIEND_ADD"
-]);
 /**
 * 处理 QQ 场景（单聊 + 群聊）的发送
 */
@@ -2261,30 +2468,34 @@ const sendQQ = async (ctx, contact, elements) => {
 */
 const sendQQMarkdown = async (ctx, contact, grouping, target) => {
 	const items = [];
+	/** 上传归属会话固定为本次发送目标，保证 openid 与执行发送的 bot 同域。 */
+	const origin = {
+		scene: target,
+		peer: contact.peer
+	};
 	const lines = [];
 	if (grouping.text.length) lines.push(grouping.text.join(""));
-	const fallbackImages = await appendMarkdownImages(ctx, lines, grouping.qqImages);
-	const markdownFallbackImages = await appendExplicitMarkdown(ctx, lines, grouping);
+	const fallbackImages = await appendMarkdownImages(ctx, lines, grouping.qqImages, origin);
+	const markdownFallbackImages = await appendExplicitMarkdown(ctx, lines, grouping, origin);
 	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(grouping)) items.push(ctx.super.qq.text(lines.join("\n")));
-	else {
-		const keyboard = buildKeyboard$1(grouping);
-		const content = lines.length ? lines.join("\n") : BUTTON_ONLY_MARKDOWN$1;
-		items.push(ctx.super.qq.markdown({ content }, keyboard));
-	}
+	const mediaItems = [];
 	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));
+		mediaItems.push(ctx.super.qq.media(res.file_info));
 	}
 	for (const m of grouping.media) {
-		const source = await resolvePreferredMediaSource(ctx, m.kind, m.source, m.name);
+		const source = await resolvePreferredMediaSource(ctx, m.kind, m.source, m.name, origin);
 		const res = source.via === "fallback" ? await ctx.super.media.uploadFallback(target, contact.peer, m.kind, source.source, false, m.name) : await ctx.super.media.upload(target, contact.peer, m.kind, source.source, false, m.name);
-		items.push(ctx.super.qq.media(res.file_info));
+		mediaItems.push(ctx.super.qq.media(res.file_info));
 	}
+	if (lines.length || grouping.buttons.length || grouping.keyboards.length) if (shouldUseTextForReference(grouping)) items.push(ctx.super.qq.text(lines.join("\n")));
+	else if (lines.length) items.push(ctx.super.qq.markdown({ content: lines.join("\n") }, buildKeyboard$1(grouping)));
+	else attachKeyboardWithoutMarkdown(ctx, grouping, mediaItems, items);
+	items.push(...mediaItems);
 	if (!items.length) items.push(ctx.super.qq.text("不支持发送的消息类型"));
 	return flushQQ(ctx, contact, grouping, items);
 };
@@ -2311,21 +2522,55 @@ const sendQQClassic = async (ctx, contact, grouping, target) => {
 const appendExplicitMarkdownItems = async (ctx, contact, grouping, target, items) => {
 	if (!grouping.markdowns.length) return;
 	const lines = [];
-	const fallbackImages = await appendExplicitMarkdown(ctx, lines, grouping);
+	const fallbackImages = await appendExplicitMarkdown(ctx, lines, grouping, {
+		scene: target,
+		peer: contact.peer
+	});
 	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));
+	const mediaItems = [];
 	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));
+		mediaItems.push(ctx.super.qq.media(res.file_info));
 	}
+	if (lines.length) items.push(ctx.super.qq.markdown({ content: lines.join("\n") }, buildKeyboard$1(grouping)));
+	else attachKeyboardWithoutMarkdown(ctx, grouping, mediaItems, items);
+	items.push(...mediaItems);
+};
+/**
+* 处理「没有任何 markdown 正文，但存在按钮」的边缘情况。
+*
+* 典型触发路径：下游只发一张 markdown 语法图片 + 若干按钮，而这张图片没能通过
+* `fileToUrl` 取到公网地址，被降级成 msg_type=7 富媒体。此时 markdown 正文为空，
+* 旧实现会补一个零宽字符当正文，把按钮单独发成一条消息，客户端就会看到
+* 「一条空的按钮消息 + 一条富媒体消息」两条消息。
+*
+* 这里改为把 keyboard 挂到第一条富媒体上，合并成一条消息；只有在连富媒体都没有时，
+* 才保留零宽字符 markdown 兜底（纯按钮消息是正常用法，不能丢）。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param grouping 已归类的消息段。
+* @param mediaItems 本次待发送的富媒体消息体，keyboard 会挂到第一条上。
+* @param items 最终发送队列，仅在没有富媒体时追加纯按钮 markdown。
+*/
+const attachKeyboardWithoutMarkdown = (ctx, grouping, mediaItems, items) => {
+	const keyboard = buildKeyboard$1(grouping);
+	if (!keyboard) return;
+	const [first] = mediaItems;
+	if (!first) {
+		items.push(ctx.super.qq.markdown({ content: "​" }, keyboard));
+		return;
+	}
+	first.keyboard = keyboard;
+	ctx.logger("debug", "图片未能进入 markdown 通道，按钮已随富媒体一起发送，避免拆成两条消息");
 };
 const buildQQMediaItem = async (ctx, target, peer, type, source, name) => {
-	const resolved = await resolvePreferredMediaSource(ctx, type, source, name);
+	const resolved = await resolvePreferredMediaSource(ctx, type, source, name, {
+		scene: target,
+		peer
+	});
 	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);
 };
@@ -2335,12 +2580,13 @@ const buildQQMediaItem = async (ctx, target, peer, type, source, name) => {
 * @param ctx 适配器实例，用于输出降级日志。
 * @param lines markdown 行数组。
 * @param files QQ 图片消息段的 file 字段。
+* @param origin 本次发送归属的上传会话。
 * @returns 需要改走 msg_type=7 富媒体发送的图片列表。
 */
-const appendMarkdownImages = async (ctx, lines, files) => {
+const appendMarkdownImages = async (ctx, lines, files, origin) => {
 	const fallback = [];
 	for (const file of files) {
-		const resolved = await resolvePreferredMediaSource(ctx, "image", file);
+		const resolved = await resolvePreferredMediaSource(ctx, "image", file, void 0, origin, "markdown");
 		if (resolved.via === "fallback") {
 			fallback.push(file);
 			continue;
@@ -2351,8 +2597,14 @@ const appendMarkdownImages = async (ctx, lines, files) => {
 };
 /**
 * 处理显式 segment.markdown 中的图片：可转公网 URL 的继续嵌入，无法转的改走富媒体。
+*
+* @param ctx 适配器实例，用于输出降级日志。
+* @param lines markdown 行数组。
+* @param grouping 已归类的消息段。
+* @param origin 本次发送归属的上传会话。
+* @returns 需要改走 msg_type=7 富媒体发送的图片列表。
 */
-const appendExplicitMarkdown = async (ctx, lines, grouping) => {
+const appendExplicitMarkdown = async (ctx, lines, grouping, origin) => {
 	const fallback = [];
 	for (const markdown of grouping.markdowns) for (const part of splitMarkdownImages(markdown.markdown)) {
 		if (part.type === "text") {
@@ -2360,12 +2612,13 @@ const appendExplicitMarkdown = async (ctx, lines, grouping) => {
 			if (text) lines.push(text);
 			continue;
 		}
-		const resolved = await resolvePreferredMediaSource(ctx, "image", part.source);
+		const resolved = await resolvePreferredMediaSource(ctx, "image", part.source, void 0, origin, "markdown");
 		if (resolved.via === "fallback") {
 			fallback.push(part.source);
 			continue;
 		}
-		await appendImageUrlLine(lines, resolved.source);
+		/** 保留开发者写下的 alt 与显式尺寸，只替换图片来源 */
+		lines.push(await buildMarkdownImageLine(resolved.source, part.alt));
 	}
 	return fallback;
 };
@@ -2377,12 +2630,7 @@ const appendExplicitMarkdown = async (ctx, lines, grouping) => {
 * @param url 图片 URL。
 */
 const appendImageUrlLine = async (lines, url) => {
-	try {
-		const [line] = await imagesToMarkdown([url]);
-		lines.push(line);
-	} catch {
-		lines.push(`![karin #300px #300px](${url})`);
-	}
+	lines.push(await buildMarkdownImageLine(url));
 };
 /**
 * 判断显式引用回复是否应降级为普通文本消息。
@@ -2432,8 +2680,8 @@ const buildKeyboard$1 = (grouping) => {
 	grouping.keyboards.forEach((k) => rows.push(...karinToQQBot(k)));
 	const normalizedRows = [];
 	let id = 0;
-	for (const row of rows.slice(0, KEYBOARD_MAX_ROWS$1)) {
-		const buttons = row.buttons.slice(0, KEYBOARD_MAX_BUTTONS_PER_ROW$1).map((button) => normalizeQQBotButton(button, id++));
+	for (const row of rows.slice(0, 5)) {
+		const buttons = row.buttons.slice(0, 5).map((button) => normalizeQQBotButton(button, id++));
 		if (buttons.length) normalizedRows.push({ buttons });
 	}
 	if (!normalizedRows.length) return void 0;
@@ -2472,8 +2720,8 @@ const flushQQ = async (ctx, contact, grouping, items) => {
 	* 仅单聊 `msg_id` 回复受四次上限约束。`event_id` 事件回复和群聊不适用该限制。
 	* 这是 QQ 官方 2026-01-10 更新后的限制，超出部分不请求平台接口。
 	*/
-	const maxItems = contact.scene === "friend" && passiveSource?.type === "msg" && passiveSource.id ? C2C_PASSIVE_REPLY_LIMIT : Infinity;
-	if (items.length > maxItems) ctx.logger("warn", `单聊被动回复最多 ${C2C_PASSIVE_REPLY_LIMIT} 条，已跳过 ${items.length - maxItems} 条`);
+	const maxItems = contact.scene === "friend" && passiveSource?.type === "msg" && passiveSource.id ? 4 : Infinity;
+	if (items.length > maxItems) ctx.logger("warn", `单聊被动回复最多 ${4} 条，已跳过 ${items.length - maxItems} 条`);
 	let referenceHandled = false;
 	for (const item of items.slice(0, maxItems)) {
 		passive(item);
@@ -2500,6 +2748,12 @@ const sendQQWithEventFallback = async (ctx, contact, send, item) => {
 	try {
 		return await send(contact.peer, item);
 	} catch (err) {
+		if (item.msg_type === 7 && item.keyboard && isInvalidKeyboardError(err)) {
+			ctx.logger("warn", "富媒体消息附带 keyboard 被 QQ 拒绝，已去掉按钮重试，本条消息将不显示按钮");
+			const retryItem = { ...item };
+			delete retryItem.keyboard;
+			return send(contact.peer, retryItem);
+		}
 		if (!item.event_id || !isInvalidEventIdError(err)) throw err;
 		ctx.logger("warn", `event_id 被 QQ 拒绝，已改用普通消息重试: ${item.event_id}`);
 		const retryItem = { ...item };
@@ -2509,6 +2763,19 @@ const sendQQWithEventFallback = async (ctx, contact, send, item) => {
 	}
 };
 /**
+* 判断发送失败是否来自 QQ 对 `keyboard` 的参数校验。
+*
+* 官方文档未声明 `keyboard` 与 `media` 互斥，但实际平台行为无法完全确认，
+* 因此富媒体带按钮失败时基于键盘相关错误码兜底降级，保证图片本身能发出去。
+*
+* @param err 捕获到的发送异常。
+* @returns 是否可以通过移除 `keyboard` 重试。
+*/
+const isInvalidKeyboardError = (err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	return message.includes("305007") || message.includes("键盘") || message.includes("keyboard");
+};
+/**
 * 判断发送失败是否来自 QQ 对 `event_id` 的参数校验。
 *
 * 当前错误由 Http 层格式化为普通 Error，因此这里基于官方错误码和中文错误信息兜底识别。
@@ -2585,11 +2852,6 @@ const buildPassiveQQ = (ctx, scene, grouping) => {
 
 //#endregion
 //#region src/core/adapter/pipeline-guild.ts
-/** QQ keyboard 限制：最多 5 行，每行最多 5 个按钮。 */
-const KEYBOARD_MAX_ROWS = 5;
-const KEYBOARD_MAX_BUTTONS_PER_ROW = 5;
-/** 只有按钮没有文本时仍需提供非空 markdown 内容。 */
-const BUTTON_ONLY_MARKDOWN = "​";
 /**
 * 处理频道场景（子频道 + 私信）的发送
 *
@@ -2608,29 +2870,52 @@ const sendGuildMarkdown = async (ctx, contact, grouping) => {
 	const items = [];
 	const lines = [];
 	if (grouping.text.length) lines.push(grouping.text.join(""));
+	/**
+	* 频道用的是 channel_id，不存在 QQ 上传接口要求的 group_openid / user_openid，
+	* 所以只能标明执行发送的 bot，拿不出可用的上传会话。
+	*/
+	const extra = {
+		selfId: ctx.selfId,
+		purpose: "markdown"
+	};
 	const allImages = [...grouping.guildImageUrls];
+	/** 没有 fileToUrl 处理器接手的本地图片，降级为 file_image 单独发送。 */
+	const fallbackImages = [];
 	for (const file of grouping.guildImageFiles) {
-		const { url } = await fileToUrl("image", file, "image.jpg");
-		allImages.push(url);
+		const result = await fileToUrl("image", file, "image.jpg", extra);
+		if (!result?.url) {
+			ctx.logger("debug", "[sendGuild] 没有 fileToUrl 处理器接手图片转 URL，改走 file_image 单独发送");
+			fallbackImages.push(file);
+			continue;
+		}
+		allImages.push(result.url);
 	}
 	if (allImages.length) {
-		const mdImages = await imagesToMarkdown(allImages);
+		const mdImages = await imagesToMarkdown(allImages, extra);
 		lines.push(...mdImages);
 	}
-	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);
+	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;
+		}
+		try {
+			/** 保留开发者写下的 alt 与显式尺寸，只替换图片来源 */
+			lines.push(await markdownPartToLine(part, extra));
+		} catch {
+			ctx.logger("debug", "[sendGuild] markdown 内嵌图片转 URL 失败，改走 file_image 单独发送");
+			fallbackImages.push(part.source);
+		}
 	}
 	warnUnsupportedCommandEnterButtons(ctx, contact.scene, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
 	warnUnsupportedCommandEnterMarkdowns(ctx, contact.scene, grouping.markdowns.map((m) => m.markdown));
 	if (lines.length || grouping.buttons.length || grouping.keyboards.length) {
 		const keyboard = buildKeyboard(grouping);
-		const content = lines.length ? lines.join("\n") : BUTTON_ONLY_MARKDOWN;
+		const content = lines.length ? lines.join("\n") : "​";
 		items.push(ctx.super.guild.markdown({ content }, keyboard));
 	}
+	for (const file of fallbackImages) items.push(await buildGuildImageItem(file));
 	if (!items.length) items.push(ctx.super.guild.text("不支持发送的消息类型"));
 	return flushGuild(ctx, contact, grouping, items);
 };
@@ -2655,19 +2940,32 @@ const sendGuildClassic = async (ctx, contact, grouping) => {
 */
 const appendExplicitGuildMarkdownItems = async (ctx, contact, grouping, items) => {
 	if (!grouping.markdowns.length) return;
+	const extra = {
+		selfId: ctx.selfId,
+		purpose: "markdown"
+	};
 	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);
+	const fallbackImages = [];
+	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;
+		}
+		try {
+			/** 保留开发者写下的 alt 与显式尺寸，只替换图片来源 */
+			lines.push(await markdownPartToLine(part, extra));
+		} catch {
+			ctx.logger("debug", "[sendGuild] markdown 内嵌图片转 URL 失败，改走 file_image 单独发送");
+			fallbackImages.push(part.source);
+		}
 	}
 	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;
+	const content = lines.length ? lines.join("\n") : "​";
 	items.push(ctx.super.guild.markdown({ content }, keyboard));
+	for (const file of fallbackImages) items.push(await buildGuildImageItem(file));
 };
 const buildGuildImageItem = async (source) => {
 	if (/^https?:\/\//i.test(source)) return {
@@ -2689,8 +2987,8 @@ const buildKeyboard = (grouping) => {
 	grouping.keyboards.forEach((k) => rows.push(...karinToQQBot(k)));
 	const normalizedRows = [];
 	let id = 0;
-	for (const row of rows.slice(0, KEYBOARD_MAX_ROWS)) {
-		const buttons = row.buttons.slice(0, KEYBOARD_MAX_BUTTONS_PER_ROW).map((button) => normalizeQQBotButton(button, id++));
+	for (const row of rows.slice(0, 5)) {
+		const buttons = row.buttons.slice(0, 5).map((button) => normalizeQQBotButton(button, id++));
 		if (buttons.length) normalizedRows.push({ buttons });
 	}
 	if (!normalizedRows.length) return void 0;
@@ -3011,12 +3309,35 @@ const clearJoinRequests = (appId) => {
 };
 
 //#endregion
-//#region src/core/adapter/base.ts
+//#region src/core/adapter/config-store.ts
+/**
+* 适配器实例的真实配置存储。
+*
+* 配置挂在 WeakMap 而不是实例字段上：系统接口序列化整个适配器时不会把
+* appSecret 等敏感配置带出去。
+*/
 const adapterConfigStore = /* @__PURE__ */ new WeakMap();
-/** HTTP(S) URL 可直接交给 QQ 平台拉取上传 */
-const HTTP_URL_RE = /^https?:\/\//i;
-/** 平台限制的最大禁言时长：30 天 */
-const MAX_GROUP_MUTE_SECONDS = 720 * 60 * 60;
+/**
+* 绑定适配器实例与其配置。
+* @param bot 适配器实例。
+* @param cfg 该实例的 QQBot 配置。
+*/
+const setAdapterConfig = (bot, cfg) => {
+	adapterConfigStore.set(bot, cfg);
+};
+/**
+* 读取适配器实例的配置。
+* @param bot 适配器实例。
+* @returns 该实例的 QQBot 配置；未绑定时抛错。
+*/
+const getAdapterConfig = (bot) => {
+	const cfg = adapterConfigStore.get(bot);
+	if (!cfg) throw new Error("QQBot adapter config missing");
+	return cfg;
+};
+
+//#endregion
+//#region src/core/adapter/base.ts
 /**
 * QQ Official Bot 适配器
 *
@@ -3030,7 +3351,7 @@ var AdapterQQBot = class extends AdapterBase {
 	nicknameCache = /* @__PURE__ */ new Map();
 	constructor(cfg, api) {
 		super();
-		adapterConfigStore.set(this, cfg);
+		setAdapterConfig(this, cfg);
 		this.super = api;
 		this.adapter.name = "QQ Official Bot";
 		this.adapter.protocol = "qqbot";
@@ -3039,9 +3360,7 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/** 当前 bot 配置。真实配置存放在 WeakMap，避免被系统接口序列化整个适配器时带出。 */
 	get cfg() {
-		const cfg = adapterConfigStore.get(this);
-		if (!cfg) throw new Error("QQBot adapter config missing");
-		return cfg;
+		return getAdapterConfig(this);
 	}
 	/** 接收消息的一天热缓存 + SQLite 缓存，用于实现 Karin 标准 `getMsg`。 */
 	get messageStore() {
@@ -3061,16 +3380,17 @@ var AdapterQQBot = class extends AdapterBase {
 	* 发送消息
 	*/
 	async sendMsg(contact, elements, _retryCount) {
+		const normalizedElements = normalizeMediaElements(elements);
 		/** 发送成功后始终记录消息 ID 映射；正文是否入库由 cacheSelfMessage 内部按开关决定。 */
 		if (contact.scene === "direct" || contact.scene === "guild") {
-			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, elements) : void 0;
-			const result = await sendGuild(this, contact, prepared?.sendElements ?? elements);
+			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, normalizedElements) : void 0;
+			const result = await sendGuild(this, contact, prepared?.sendElements ?? normalizedElements);
 			cacheSelfMessage(this, contact, prepared?.cacheElements ?? [], result);
 			return result;
 		}
 		if (contact.scene === "group" || contact.scene === "friend") {
-			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, elements) : void 0;
-			const result = await sendQQ(this, contact, prepared?.sendElements ?? elements);
+			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, normalizedElements) : void 0;
+			const result = await sendQQ(this, contact, prepared?.sendElements ?? normalizedElements);
 			cacheSelfMessage(this, contact, prepared?.cacheElements ?? [], result);
 			return result;
 		}
@@ -3156,20 +3476,43 @@ var AdapterQQBot = class extends AdapterBase {
 					case "text":
 						lines.push(el.text);
 						break;
-					case "image":
-						if (el.file.startsWith("http")) try {
-							const { width, height } = await getImageSize(el.file);
-							lines.push(`![${el.name || "图片"} #${width}px #${height}px](${el.file})`);
+					case "image": {
+						const imageSource = typeof el.file === "string" ? normalizeMediaSource(el.file) : el.file;
+						if (typeof imageSource === "string" && imageSource.startsWith("http")) try {
+							const { width, height } = await getImageSize(imageSource);
+							lines.push(`![${el.name || "图片"} #${width}px #${height}px](${imageSource})`);
 						} catch {
-							lines.push(`![${el.name || "图片"} #300px #300px](${el.file})`);
+							lines.push(`![${el.name || "图片"} #300px #300px](${imageSource})`);
 						}
-						else try {
-							const { url, width, height } = await fileToUrl("image", el.file, el.name || "image.jpg");
-							lines.push(`![${el.name || "图片"} #${width}px #${height}px](${url})`);
-						} catch {
-							lines.push(`![${el.name || "图片"} #300px #300px]()`);
+						else {
+							/**
+							* 必须带上 selfId / purpose / origin：内置图床按这三个字段决定
+							* 是否接手，缺任何一个都会直接放行给后续处理器。频道场景没有
+							* 可用的 openid，origin 只能是 undefined。
+							*/
+							const origin = contact.scene === "group" ? {
+								scene: "group",
+								peer: contact.peer
+							} : contact.scene === "friend" ? {
+								scene: "user",
+								peer: contact.peer
+							} : void 0;
+							try {
+								const result = await fileToUrl("image", imageSource, el.name || "image.jpg", {
+									selfId: this.selfId,
+									purpose: "markdown",
+									origin
+								});
+								if (result?.url) lines.push(`![${el.name || "图片"} #${result.width || 300}px #${result.height || 300}px](${result.url})`);
+								else
+ /** 没有处理器接手时不能留空 URL 的图片语法（客户端渲染为空白），改走富媒体补发 */
+								mediaElements.push(el);
+							} catch {
+								mediaElements.push(el);
+							}
 						}
 						break;
+					}
 					case "at":
 						if (contact.scene === "friend" || contact.scene === "direct") break;
 						if (el.targetId === "all") lines.push("<qqbot-at-everyone />");
@@ -3339,7 +3682,7 @@ var AdapterQQBot = class extends AdapterBase {
 		let rfc3339 = "";
 		if (duration > 0) {
 			let seconds = duration;
-			if (seconds > MAX_GROUP_MUTE_SECONDS) {
+			if (seconds > 2592e3) {
 				this.logger("warn", `[setGroupMute] 禁言时长 ${seconds}s 超出平台上限 30 天，已截断为 ${MAX_GROUP_MUTE_SECONDS}s`);
 				seconds = MAX_GROUP_MUTE_SECONDS;
 			}
@@ -5408,7 +5751,7 @@ const createBot = async (input) => {
 		client.account.name = me.username;
 		client.account.avatar = me.avatar;
 		client.account.selfId = appId;
-		const qq = new URL(me.share_url).searchParams.get("robot_uin");
+		const qq = new URL$1(me.share_url).searchParams.get("robot_uin");
 		client.account.subId.id = me.id;
 		client.account.subId.qq = qq;
 		client.account.subId.appid = appId;