@karinjs/adapter-qqbot 3.1.0 → 3.3.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 { l as basename, n as config, r as getConfig, s as pkg, t as bindHandlers } from "./config-BgCU6apn.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 { 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 { a as DATA_URL_BASE64_RE, i as BASE64_PREFIX_RE, n as getImageSize, o as HTTP_URL_RE, r as random, s as QQ_NUMBER_RE, t as fakeEvent } from "./common-DwVsAvIo.js";
+import "./utils-u17tvC2U.js";
+import { t as getMessageStore } from "./message-CydR-wrX.js";
+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 回应
 */
@@ -1362,10 +1460,12 @@ var MetaApi = class extends Http {
 //#endregion
 //#region src/core/api/groups.ts
 /**
-* QQ 群信息接口
+* QQ 群信息与群成员管理接口
 *
 * 注意：以下接口均为白名单接口，未开通权限时平台返回错误码 11253，
-* 需要向平台运营申请后可用。
+* 需要向平台运营申请后可用。接口文档 v1.28.0（2026-09-03）新增的群成员管理
+* 接口（成员列表 / 批量移除 / 黑名单）官方标注为「正在内邀接入中」，
+* 开放范围可能比其它白名单接口更窄。
 */
 var GroupsApi = class extends Http {
 	/**
@@ -1383,8 +1483,25 @@ var GroupsApi = class extends Http {
 		return this.get(`/v2/groups/${groupOpenid}/bot_state`);
 	}
 	/**
+	* 获取群成员列表
+	*
+	* 每次最多返回 30 条，只支持 cursor 翻页：首次不传 `cursor`，之后回传上一次
+	* 响应的 `next_cursor`，`next_cursor` 为空串表示已到末页。
+	*
+	* @param groupOpenid 群 openid
+	* @param params 分页参数
+	*/
+	getGroupMemberList(groupOpenid, params = {}) {
+		const query = new URLSearchParams();
+		if (params.cursor) query.set("cursor", params.cursor);
+		const search = query.toString();
+		return this.get(`/v2/groups/${groupOpenid}/members${search ? `?${search}` : ""}`);
+	}
+	/**
 	* 获取群成员详情
 	*
+	* 昵称字段为 `username`；`nick` 是该接口转为公开文档之前的字段名，仅作兼容。
+	*
 	* @param groupOpenid 群 openid
 	* @param memberOpenid 群成员 openid
 	*/
@@ -1392,9 +1509,48 @@ var GroupsApi = class extends Http {
 		return this.get(`/v2/groups/${groupOpenid}/members/${memberOpenid}`);
 	}
 	/**
+	* 群成员批量移除
+	*
+	* 单次最多 20 个成员，可通过 `add_to_member_blacklist` 在移除的同时拉黑。
+	* 机器人需拥有群管理员身份。
+	*
+	* @param groupOpenid 群 openid
+	* @param body 待移除的成员列表与是否同时拉黑
+	*/
+	batchRemoveGroupMembers(groupOpenid, body) {
+		return this.post(`/v2/groups/${groupOpenid}/batch_remove_members`, body);
+	}
+	/**
+	* 查询群黑名单
+	*
+	* @param groupOpenid 群 openid
+	* @param params 分页参数，`limit` 默认 20、最大 100
+	*/
+	getGroupMemberBlacklist(groupOpenid, params = {}) {
+		const query = new URLSearchParams();
+		if (params.cursor) query.set("cursor", params.cursor);
+		if (params.limit !== void 0) query.set("limit", String(params.limit));
+		const search = query.toString();
+		return this.get(`/v2/groups/${groupOpenid}/member_blacklist${search ? `?${search}` : ""}`);
+	}
+	/**
+	* 群黑名单操作
+	*
+	* 只有目标用户不在群中时才能加入黑名单，需要先移除再拉黑；单次最多 20 个。
+	* 返回的 `fail_openids` 在 `op=add` / `op=del` 下同义，都是操作失败的 openid。
+	*
+	* @param groupOpenid 群 openid
+	* @param body 操作类型与目标成员列表
+	*/
+	setGroupMemberBlacklist(groupOpenid, body) {
+		return this.post(`/v2/groups/${groupOpenid}/member_blacklist`, body);
+	}
+	/**
 	* 设置群成员禁言
 	*
-	* 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天。
+	* 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天；
+	* 只能操作普通成员，不能操作群主、管理员与机器人。
+	* 需要一次设置多个成员时用 {@link GroupsApi.setGroupMuteBatch}。
 	*
 	* @param groupOpenid 群 openid
 	* @param memberOpenid 群成员 openid
@@ -1402,11 +1558,24 @@ var GroupsApi = class extends Http {
 	* @param duration 禁言时间使用RFC3339 格式
 	*/
 	setGroupMute(groupOpenid, memberOpenid, op, duration) {
-		return this.post(`/v2/groups/${groupOpenid}/restrict_chat_setting`, { members: [{
+		return this.setGroupMuteBatch(groupOpenid, [{
 			op,
 			member_openid: memberOpenid,
 			mute_expire_at: duration
-		}] });
+		}]);
+	}
+	/**
+	* 批量设置群成员禁言
+	*
+	* 每项通过自身的 `op` 控制增 / 改 / 删，可以在一次请求里混用。
+	* 平台限制单次最多 20 个成员（接口文档 v1.28.0 由 10 提升至 20），
+	* 超出时平台会直接拒绝整个请求。
+	*
+	* @param groupOpenid 群 openid
+	* @param members 成员禁言设置列表
+	*/
+	setGroupMuteBatch(groupOpenid, members) {
+		return this.post(`/v2/groups/${groupOpenid}/restrict_chat_setting`, { members });
 	}
 	/**
 	* 设置群成员禁言
@@ -1432,12 +1601,13 @@ var GroupsApi = class extends Http {
 	* 机器人需拥有群管理员身份。
 	*
 	* @param groupOpenid 群 openid
-	* @param params 分页参数，`limit` 默认 20、最大 100
+	* @param params 分页参数，`limit` 默认 20、最大 50（接口文档 v1.28.0 由 100 下调），
+	* 传入更大的值会被收敛到 50，避免平台直接拒绝
 	*/
 	getJoinRequestList(groupOpenid, params = {}) {
 		const query = new URLSearchParams();
 		if (params.cursor) query.set("cursor", params.cursor);
-		if (params.limit !== void 0) query.set("limit", String(params.limit));
+		if (params.limit !== void 0) query.set("limit", String(Math.min(params.limit, 50)));
 		const search = query.toString();
 		return this.get(`/v2/groups/${groupOpenid}/join_request_list${search ? `?${search}` : ""}`);
 	}
@@ -1660,12 +1830,13 @@ var JoinApprovalApi = class extends Http {
 	* 查询入群自动审批策略列表
 	*
 	* 按创建时间倒序，支持分页。
-	* @param params 分页参数，`limit` 默认 20、最大 100
+	* @param params 分页参数，`limit` 默认 20、最大 50（接口文档 v1.28.0 由 100 下调），
+	* 传入更大的值会被收敛到 50，避免平台直接拒绝
 	*/
 	getStrategyList(params = {}) {
 		const query = new URLSearchParams();
 		if (params.cursor) query.set("cursor", params.cursor);
-		if (params.limit !== void 0) query.set("limit", String(params.limit));
+		if (params.limit !== void 0) query.set("limit", String(Math.min(params.limit, 50)));
 		const search = query.toString();
 		return this.get(`/v2/groups/join_approval_strategy${search ? `?${search}` : ""}`);
 	}
@@ -1743,11 +1914,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
 		};
 	}
 };
@@ -1799,7 +1976,7 @@ const buildGuildMsg = {
 * - media：富媒体上传
 * - interaction：按钮回调 ack
 * - meta：@me / dms / gateway / 分享链接
-* - groups：群基础信息 / 机器人群内状态 / 禁言 / 入群申请（部分为白名单接口）
+* - groups：群基础信息 / 机器人群内状态 / 群成员列表与详情 / 禁言 / 批量移除 / 群黑名单 / 入群申请（白名单接口）
 * - guilds：频道与子频道的查询和增删改
 * - menu：全局自定义菜单（仅单聊）
 * - panels：指令面板
@@ -1989,6 +2166,9 @@ const collectCommandEnterButtons = (buttons, keyboards) => {
 /**
 * 归一 QQ keyboard 按钮字段。
 *
+* 只重写键盘内唯一的按钮序号，其余字段（含 v1.28.0 新增的 `group_id`、
+* `action.modal`）原样透传。
+*
 * @param button node-karin 转换后的 QQBot 按钮。
 * @param id 当前 keyboard 内唯一按钮序号。
 * @returns 可直接放入 QQ 官方 keyboard 的按钮对象。
@@ -2112,13 +2292,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 +2343,65 @@ 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"
+			};
+		}
+		/** 只有 image 会带宽高，其余类型按声明就没有这两个字段。 */
+		const { width, height } = result;
+		const size = typeof width === "number" && typeof height === "number" ? {
+			width,
+			height
+		} : void 0;
 		return {
-			source: (await fileToUrl(type, source, filename || DEFAULT_FILENAME[type])).url,
-			via: "file-to-url"
+			source: result.url,
+			via: "file-to-url",
+			size
 		};
 	} catch (err) {
 		ctx.logger("warn", `[sendQQ] ${type} 转 URL 失败，改用 QQ 上传兜底:`, err);
 		return {
-			source,
+			source: normalized,
 			via: "fallback"
 		};
 	}
@@ -2168,21 +2409,105 @@ 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 图片。
+*
+* 用于适配器自己拼 markdown 正文的场景（如合并转发）：只把原始来源写进图片语法，
+* 具体走内置图床、第三方 fileToUrl 还是降级成富媒体，留给发送 pipeline 在
+* `splitMarkdownImages` 之后统一决定，避免在 pipeline 之外重复一套上传逻辑。
+*
+* 本地路径可能带空格、`)` 等会截断图片语法的字符，因此来源统一用尖括号包住——
+* `splitMarkdownImages` 取出时会剥掉。
+*
+* @param source 原始来源：本地路径、`base64://` 或 URL。
+* @param alt 图片描述；`]` 与换行会截断语法，统一压成空格。
+* @param size 已知的真实宽高，写成显式尺寸可省掉 pipeline 的一次探测。
+* @returns markdown 图片行，来源仍是原始 file 字段。
+*/
+const buildPendingMarkdownImageLine = (source, alt = "", size) => {
+	return `![${alt.replace(/[[\]\r\n]/g, " ").trim() || "karin"}${size?.width && size?.height ? ` #${size.width}px #${size.height}px` : ""}](<${normalizeMediaSource(source)}>)`;
+};
 /**
 * 将图片列表合并到一段 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 +2522,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,115 +2546,96 @@ 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 场景（单聊 + 群聊）的发送
+*
+* QQ 单聊 / 群聊的自定义 Markdown 自 2026-04-23 起已开放给所有机器人，无需申请
+* （见 `api-docs/server-inter/message/type/markdown.md`），所以这里只保留一条发送通道：
+* text / at / 可转换为公网 URL 的图片通过 markdown content 渲染；无法转换的图片
+* 与视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 紧随主消息补发。所有
+* 富媒体都会优先通过 fileToUrl 取得公网地址，QQ 上传只做兜底。只有显式引用的
+* 纯文本消息会降级为 msg_type=0，以保证 QQ 客户端能稳定显示引用气泡。
 */
 const sendQQ = async (ctx, contact, elements) => {
+	assertOpenIdPeer(contact);
 	const target = contact.scene === "friend" ? "user" : "group";
 	const grouping = groupElements(contact.scene, elements);
 	await resolveOutgoingReferenceQQ(ctx, contact, grouping);
-	/**
-	* 自动 Markdown 通道：
-	* text / at / 可转换为公网 URL 的图片通过 markdown content 渲染；无法转换的图片
-	* 与视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 单独补发。所有富媒体
-	* 都会优先通过 fileToUrl 取得公网地址，QQ 上传只做兜底。只有显式引用的
-	* 纯文本消息会降级为 msg_type=0，以保证 QQ 客户端能稳定显示引用气泡。
-	* 显式 segment.markdown 不受该自动通道开关影响。
-	*/
-	if (ctx.cfg.markdown.enable) return sendQQMarkdown(ctx, contact, grouping, target);
-	return sendQQClassic(ctx, contact, grouping, target);
+	return sendQQMarkdown(ctx, contact, grouping, target);
+};
+/**
+* QQ 官方接口只接受 openid（32 位十六进制或 UUID 形态）寻址。纯数字 peer 一定是
+* QQ 号/群号，继续走下去只会在媒体上传或消息下发时被平台以 40011028
+* 「请求的资源不存在」拒绝，且平台错误信息没有指向性（上游常见场景：把 karin
+* 主人列表里的 QQ 号直接当私聊目标）。这里提前拦截，给出可操作的说明。
+*/
+const assertOpenIdPeer = (contact) => {
+	if (!QQ_NUMBER_RE.test(contact.peer)) return;
+	const sceneLabel = contact.scene === "friend" ? "私聊" : "群聊";
+	throw new Error(`[sendQQ] ${sceneLabel} peer 不是有效 openid: ${contact.peer}。QQ 官方 Bot API 不使用 QQ 号/群号寻址，请让对方先给机器人发一条消息，从事件中获取其 openid 后填入配置`);
 };
 /**
 * Markdown 通道：合成一条 msg_type=2 + 可选 keyboard
 */
 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);
 };
 /**
-* 经典通道：文本走 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 自动通道开关影响。
+* 处理「没有任何 markdown 正文，但存在按钮」的边缘情况。
+*
+* 典型触发路径：下游只发一张 markdown 语法图片 + 若干按钮，而这张图片没能通过
+* `fileToUrl` 取到公网地址，被降级成 msg_type=7 富媒体。此时 markdown 正文为空，
+* 旧实现会补一个零宽字符当正文，把按钮单独发成一条消息，客户端就会看到
+* 「一条空的按钮消息 + 一条富媒体消息」两条消息。
+*
+* 这里改为把 keyboard 挂到第一条富媒体上，合并成一条消息；只有在连富媒体都没有时，
+* 才保留零宽字符 markdown 兜底（纯按钮消息是正常用法，不能丢）。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param grouping 已归类的消息段。
+* @param mediaItems 本次待发送的富媒体消息体，keyboard 会挂到第一条上。
+* @param items 最终发送队列，仅在没有富媒体时追加纯按钮 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 attachKeyboardWithoutMarkdown = (ctx, grouping, mediaItems, items) => {
 	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));
+	if (!keyboard) return;
+	const [first] = mediaItems;
+	if (!first) {
+		items.push(ctx.super.qq.markdown({ content: "​" }, keyboard));
+		return;
 	}
-};
-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);
+	first.keyboard = keyboard;
+	ctx.logger("debug", "图片未能进入 markdown 通道，按钮已随富媒体一起发送，避免拆成两条消息");
 };
 /**
 * 将能转成公网 URL 的图片追加到 markdown 行，无法转换的图片返回给富媒体 fallback。
@@ -2335,24 +2643,31 @@ 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;
 		}
-		await appendImageUrlLine(lines, resolved.source);
+		lines.push(await buildMarkdownImageLine(resolved.source, "", resolved.size));
 	}
 	return fallback;
 };
 /**
 * 处理显式 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,31 +2675,17 @@ 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, resolved.size));
 	}
 	return fallback;
 };
 /**
-* 生成单张 markdown 图片行。
-* 尺寸获取失败时使用保守默认尺寸，保证 fileToUrl 成功的图片仍走 markdown。
-*
-* @param lines markdown 行数组。
-* @param url 图片 URL。
-*/
-const appendImageUrlLine = async (lines, url) => {
-	try {
-		const [line] = await imagesToMarkdown([url]);
-		lines.push(line);
-	} catch {
-		lines.push(`![karin #300px #300px](${url})`);
-	}
-};
-/**
 * 判断显式引用回复是否应降级为普通文本消息。
 *
 * QQ 的 `message_reference` 对普通文本最稳定；markdown 带引用在客户端渲染上存在兼容问题。
@@ -2432,8 +2733,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 +2773,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 +2801,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 +2816,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，因此这里基于官方错误码和中文错误信息兜底识别。
@@ -2583,23 +2903,95 @@ const buildPassiveQQ = (ctx, scene, grouping) => {
 	};
 };
 
+//#endregion
+//#region src/core/adapter/guild-markdown.ts
+/**
+* 频道 Markdown 能力探测。
+*
+* 官方能力说明（`api-docs/server-inter/message/type/markdown.md`）：2026-04-23 起
+* 单聊 / 群聊的自定义 Markdown 已开放到所有机器人，无需申请；**频道场景仍需内邀
+* 开通**。因此单聊 / 群聊直接走 Markdown，频道场景先乐观尝试，被平台以权限类
+* 错误拒绝后记住该 bot 并改走普通消息，避免之后每条消息都白跑一次请求。
+*
+* 状态只存在于当前进程，也不写配置：拿到内邀后重启（或改一次配置触发 bot 重建）
+* 即可重新尝试，用户不需要手动去点任何开关。
+*/
+/** 已确认没有频道 Markdown 权限的 appId。 */
+const forbidden = /* @__PURE__ */ new Set();
+/**
+* 平台拒绝 Markdown 的权限类错误码。
+*
+* - 50056 不允许发送 markdown content；
+* - 304036 没有 markdown 模板的权限。
+*/
+const FORBIDDEN_CODES = [50056, 304036];
+/**
+* 该 bot 当前是否还可以尝试频道 Markdown。
+*
+* @param selfId 机器人 appId。
+* @returns 未被标记为无权限时返回 true。
+*/
+const canSendGuildMarkdown = (selfId) => !forbidden.has(selfId);
+/**
+* 标记该 bot 没有频道 Markdown 权限。
+*
+* @param selfId 机器人 appId。
+* @returns 本次是否是首次标记，供调用方只告警一次。
+*/
+const disableGuildMarkdown = (selfId) => {
+	if (forbidden.has(selfId)) return false;
+	forbidden.add(selfId);
+	return true;
+};
+/**
+* 清除该 bot 的降级标记，让下一条频道消息重新尝试 Markdown。
+*
+* bot 重建（配置变更 / 重新登录）时调用，避免内邀开通后还要重启整个 Karin。
+*
+* @param selfId 机器人 appId。
+*/
+const resetGuildMarkdown = (selfId) => {
+	forbidden.delete(selfId);
+};
+/**
+* 判断发送失败是否来自平台对 Markdown 权限的校验。
+*
+* Http 层把平台错误格式化成普通 Error（`[Code 50056] ...`），这里按错误码优先、
+* 中文文案兜底识别，和 pipeline 里其它降级判断保持一致的做法。
+*
+* @param err 捕获到的发送异常。
+* @returns 是否应降级为普通消息。
+*/
+const isGuildMarkdownForbiddenError = (err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	if (FORBIDDEN_CODES.some((code) => message.includes(`[Code ${code}]`))) return true;
+	return message.includes("不允许发送 markdown") || message.includes("没有 markdown 模板的权限");
+};
+
 //#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 = "​";
 /**
 * 处理频道场景（子频道 + 私信）的发送
 *
-* 默认把普通文本 / at / 图片通过 markdown 渲染。关闭自动 Markdown 通道后，
-* 普通文本和图片改走经典发送；显式 segment.markdown 仍按调用方指定走 Markdown。
+* 频道的自定义 Markdown 目前仍需向 QQ 申请内邀开通（见
+* `api-docs/server-inter/message/type/markdown.md`），所以这里不靠用户配置开关，
+* 而是先乐观走 Markdown：被平台以权限类错误拒绝后记住这个 bot，本次立刻降级重发，
+* 之后的频道消息直接走普通消息通道。
 */
 const sendGuild = async (ctx, contact, elements) => {
 	const grouping = groupElements(contact.scene, elements);
-	if (ctx.cfg.markdown.enable) return sendGuildMarkdown(ctx, contact, grouping);
-	return sendGuildClassic(ctx, contact, grouping);
+	if (!canSendGuildMarkdown(ctx.selfId)) return sendGuildClassic(ctx, contact, grouping);
+	try {
+		return await sendGuildMarkdown(ctx, contact, grouping);
+	} catch (err) {
+		if (!isGuildMarkdownForbiddenError(err)) throw err;
+		/**
+		* markdown 主消息一定是 items[0]，被拒时本次还没有任何消息发出去，
+		* 因此可以安全地整条重发，不会出现重复消息。
+		*/
+		if (disableGuildMarkdown(ctx.selfId)) ctx.logger("warn", "频道 Markdown 未开通（需向 QQ 申请内邀），已降级为普通消息发送；本进程后续频道消息不再尝试 Markdown，开通后重启或改一次配置即可恢复");
+		return sendGuildClassic(ctx, contact, grouping);
+	}
 };
 /**
 * Markdown 通道
@@ -2608,67 +3000,87 @@ 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);
 };
 /**
-* 经典通道：文本走 content，图片按文档走 image / file_image 单独发送。
+* 降级通道：频道 Markdown 权限不可用时使用。
+*
+* 文本走 content，图片按文档走 image / file_image 单独发送。这条通道不会产出任何
+* markdown 消息体——显式 `segment.markdown` 也一样：内嵌图片被拆出来单独发送，
+* 其余部分按普通文本下发。否则同一条消息只会再被平台以同样的权限错误拒绝一次。
 */
 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 无法随普通文本发送，已跳过");
+	/** 频道 keyboard 只能挂在 markdown 消息体上，没有 markdown 就无处附着。 */
+	if (grouping.buttons.length || grouping.keyboards.length) ctx.logger("warn", "频道 Markdown 不可用，button / keyboard 无法发送，已跳过");
+	if (grouping.markdowns.length) {
+		/** 内容没有丢，只是渲染成纯文本，用 debug 避免每条消息都刷一条 warn。 */
+		ctx.logger("debug", "[sendGuild] Markdown 不可用，segment.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);
+				continue;
+			}
+			images.push(part.source);
+		}
+	}
 	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",
@@ -2689,8 +3101,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;
@@ -2780,11 +3192,12 @@ const shouldCacheSelfMessage = (ctx) => {
 *
 * 静态资源只在这里转一次 HTTP URL，之后发送 pipeline 和缓存都复用该 URL。
 */
-const prepareSelfMessageCache = async (ctx, elements) => {
+const prepareSelfMessageCache = async (ctx, contact, elements) => {
 	const sendElements = [];
 	const cacheElements = [];
+	const origin = resolveUploadOrigin(contact);
 	for (const element of elements) {
-		const prepared = await prepareSelfCacheElement(ctx, element);
+		const prepared = await prepareSelfCacheElement(ctx, element, origin);
 		sendElements.push(prepared.send);
 		if (prepared.cache) cacheElements.push(prepared.cache);
 	}
@@ -2831,7 +3244,7 @@ const cacheSelfMessage = (ctx, contact, cacheElements, result) => {
 /**
 * 转换单个自己消息元素为缓存安全形态。
 */
-const prepareSelfCacheElement = async (ctx, element) => {
+const prepareSelfCacheElement = async (ctx, element, origin) => {
 	switch (element.type) {
 		case "text":
 		case "at":
@@ -2847,7 +3260,7 @@ const prepareSelfCacheElement = async (ctx, element) => {
 		case "image":
 		case "video":
 		case "record":
-		case "file": return prepareStaticElement(ctx, element);
+		case "file": return prepareStaticElement(ctx, element, origin);
 		default: return {
 			send: element,
 			cache: null
@@ -2855,9 +3268,9 @@ const prepareSelfCacheElement = async (ctx, element) => {
 	}
 };
 /**
-* 静态资源统一转 HTTP URL 后再缓存；转换失败时跳过该元素。
+* 静态资源统一转 HTTP URL 后再缓存；转换失败或没有处理器接手时跳过该元素。
 */
-const prepareStaticElement = async (ctx, element) => {
+const prepareStaticElement = async (ctx, element, origin) => {
 	if (element.file.startsWith("http")) {
 		const cached = { ...element };
 		return {
@@ -2866,54 +3279,41 @@ const prepareStaticElement = async (ctx, element) => {
 		};
 	}
 	try {
-		switch (element.type) {
-			case "image": {
-				const res = await fileToUrl("image", element.file, element.name || "image.jpg");
-				const cached = {
-					...element,
-					file: res.url,
-					width: res.width,
-					height: res.height
-				};
-				return {
-					send: cached,
-					cache: cached
-				};
-			}
-			case "video": {
-				const res = await fileToUrl("video", element.file, element.name || "video.mp4");
-				const cached = {
-					...element,
-					file: res.url
-				};
-				return {
-					send: cached,
-					cache: cached
-				};
-			}
-			case "record": {
-				const res = await fileToUrl("record", element.file, element.name || "record.mp3");
-				const cached = {
-					...element,
-					file: res.url
-				};
-				return {
-					send: cached,
-					cache: cached
-				};
-			}
-			case "file": {
-				const res = await fileToUrl("file", element.file, element.name || "file.bin");
-				const cached = {
-					...element,
-					file: res.url
-				};
-				return {
-					send: cached,
-					cache: cached
-				};
-			}
+		/**
+		* 和发送链路传同一套附加信息：处理器需要知道是哪个 bot、哪个会话才能用对
+		* openid。用途是 media —— 缓存要的是能长期访问的地址，内置图床给的是会过期的
+		* 临时直链，按 purpose 主动放行正好。
+		*/
+		const extra = {
+			selfId: ctx.selfId,
+			purpose: "media",
+			origin
+		};
+		const res = await fileToUrl(element.type, element.file, element.name || DEFAULT_FILENAME[element.type], extra);
+		/**
+		* 链路上的处理器全部放行时 fileToUrl 实际返回 undefined（类型声明未涵盖
+		* 这种情况），不属于异常：发送继续使用原始来源，仅跳过该元素的缓存。
+		*/
+		if (!res?.url) {
+			ctx.logger("debug", `[getMsg] 没有 fileToUrl 处理器接手 ${element.type}，跳过该元素的缓存`);
+			return {
+				send: element,
+				cache: null
+			};
+		}
+		const cached = {
+			...element,
+			file: res.url
+		};
+		if (cached.type === "image") {
+			const { width, height } = res;
+			cached.width = width;
+			cached.height = height;
 		}
+		return {
+			send: cached,
+			cache: cached
+		};
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		ctx.logger("debug", `[getMsg] 跳过自己消息资源缓存: ${element.type} ${message}`);
@@ -2924,6 +3324,25 @@ const prepareStaticElement = async (ctx, element) => {
 	}
 };
 /**
+* 解析缓存用 URL 转换的归属会话。
+*
+* QQ 的 openid 按 bot 隔离，上传接口只接受该 bot 可见的 group_openid / user_openid；
+* 频道用 channel_id，没有可用 openid，返回 undefined。
+*
+* @param contact 本次发送目标。
+* @returns 可交给 fileToUrl 处理器的上传会话。
+*/
+const resolveUploadOrigin = (contact) => {
+	if (contact.scene === "group") return {
+		scene: "group",
+		peer: contact.peer
+	};
+	if (contact.scene === "friend") return {
+		scene: "user",
+		peer: contact.peer
+	};
+};
+/**
 * 构造机器人自己的 sender。
 */
 const selfSender = (ctx, contact) => {
@@ -3011,17 +3430,67 @@ 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
+/**
+* 按 Karin 接口约定构造群成员信息。
+*
+* `sender` 用 getter 即时构建，避免整个适配器被系统接口序列化时带出多余引用。
+*
+* @param userId 成员 openid。
+* @param role 群内角色。
+* @param nick 成员昵称。
+* @param joinTime 入群时间戳（毫秒）。
+* @returns Karin 标准群成员信息。
+*/
+const buildGroupMemberInfo = (userId, role, nick, joinTime) => ({
+	userId,
+	role,
+	nick,
+	joinTime,
+	get sender() {
+		return senderGroup({
+			userId,
+			nick: nick || "",
+			name: nick || "",
+			role
+		});
+	}
+});
 /**
 * QQ Official Bot 适配器
 *
-* 全场景统一走 msg_type=2 Markdown 通道（详见 pipeline-qq / pipeline-guild）。
-* 视频 / 语音 / 文件由 pipeline 内部以 msg_type=7 紧随主消息补发。
+* 发送通道由平台能力决定，没有对应的用户配置项：QQ 单聊 / 群聊的自定义 Markdown
+* 已对所有机器人开放，固定走 msg_type=2；频道场景仍需内邀开通，先乐观尝试
+* Markdown，被拒后自动降级为普通消息（详见 pipeline-qq / pipeline-guild 与
+* guild-markdown）。视频 / 语音 / 文件由 pipeline 内部以 msg_type=7 紧随主消息补发。
 */
 var AdapterQQBot = class extends AdapterBase {
 	/** 与官方 API 交互 */
@@ -3030,7 +3499,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 +3508,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 +3528,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, contact, 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, contact, normalizedElements) : void 0;
+			const result = await sendQQ(this, contact, prepared?.sendElements ?? normalizedElements);
 			cacheSelfMessage(this, contact, prepared?.cacheElements ?? [], result);
 			return result;
 		}
@@ -3138,8 +3606,16 @@ var AdapterQQBot = class extends AdapterBase {
 	/**
 	* 发送合并转发消息
 	*
-	* 将 NodeElement 拆解为文本 + 图片等元素，拼接成 markdown 发送。
-	* 节点之间仅用换行隔开，不添加任何前缀提示文本。
+	* QQ 官方没有合并转发能力，这里把各节点摊平成一段 Markdown 正文，节点之间用
+	* 强制换行隔开，不添加任何前缀提示文本。
+	*
+	* 图片以 markdown 图片语法写入，**保留原始来源**（本地路径 / base64 / URL）：
+	* 究竟走内置图床、第三方 fileToUrl，还是降级成 msg_type=7 富媒体，由发送
+	* pipeline 统一决定。这里不自己上传，也不自己判断通道——否则频道场景在没有
+	* Markdown 权限时会绕过降级逻辑，直接被平台拒掉。
+	*
+	* 视频 / 语音 / 文件进不了 markdown，作为普通消息段跟随主消息一起交给 pipeline，
+	* 由它在同一次发送里以 msg_type=7 补发。
 	*/
 	async sendForwardMsg(contact, elements, _options) {
 		const parts = [];
@@ -3157,18 +3633,10 @@ var AdapterQQBot = class extends AdapterBase {
 						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})`);
-						} catch {
-							lines.push(`![${el.name || "图片"} #300px #300px](${el.file})`);
-						}
-						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]()`);
-						}
+						lines.push(buildPendingMarkdownImageLine(el.file, el.name || "图片", el.width && el.height ? {
+							width: el.width,
+							height: el.height
+						} : void 0));
 						break;
 					case "at":
 						if (contact.scene === "friend" || contact.scene === "direct") break;
@@ -3195,10 +3663,21 @@ var AdapterQQBot = class extends AdapterBase {
 			if (block) parts.push(block);
 		}
 		const content = parts.join("\r\r\n\n");
-		const result = await this.sendMsg(contact, [segment.markdown(content)]);
-		if (mediaElements.length) await this.sendMsg(contact, mediaElements);
+		/**
+		* 正文可能整段为空（例如只转发了一个视频节点）。此时不能塞一条空 markdown：
+		* 平台会以 50041「markdown 有空值」拒绝，pipeline 也会因为没有可发内容而
+		* 回落成一条"不支持发送的消息类型"。
+		*/
+		const sendElements = content ? [segment.markdown(content), ...mediaElements] : mediaElements;
+		if (!sendElements.length) {
+			this.logger("warn", "[sendForwardMsg] 转发节点里没有可发送的内容，已跳过");
+			return {
+				messageId: "",
+				forwardId: ""
+			};
+		}
 		return {
-			messageId: result.messageId,
+			messageId: (await this.sendMsg(contact, sendElements)).messageId,
 			forwardId: ""
 		};
 	}
@@ -3321,9 +3800,30 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 群踢人
+	*
+	* 走官方 `POST /v2/groups/{group_openid}/batch_remove_members`，机器人需拥有群
+	* 管理员身份。Karin 的 `rejectAddRequest` 映射为官方的 `add_to_member_blacklist`：
+	* 移除的同时拉入群黑名单，该用户之后无法再次入群。官方接口没有踢人理由字段，
+	* `kickReason` 只会被记录到日志。
+	*
+	* 需要一次移除多人时用 `bot.super.groups.batchRemoveGroupMembers()`，单次最多 20 个。
+	*
+	* @param _groupId 群 openid
+	* @param _targetId 群成员 openid
+	* @param _rejectAddRequest 是否同时拉入群黑名单，默认 false
+	* @param _kickReason 官方不支持，仅在传入时输出提示
 	*/
 	async groupKickMember(_groupId, _targetId, _rejectAddRequest, _kickReason) {
-		this.logger("warn", "[groupKickMember] QQ Official Bot API 暂不支持群踢人");
+		if (_kickReason) this.logger("warn", `[groupKickMember] QQ Official Bot API 不支持踢人理由，已忽略: ${_kickReason}`);
+		try {
+			const failed = (await this.super.groups.batchRemoveGroupMembers(_groupId, {
+				member_openids: [_targetId],
+				..._rejectAddRequest ? { add_to_member_blacklist: true } : {}
+			})).add_to_member_blacklist_fail_openids ?? [];
+			if (failed.length) this.logger("warn", `[groupKickMember] 成员已移除，但加入群黑名单失败: ${failed.join("、")}`);
+		} catch (err) {
+			this.logger("error", "[groupKickMember] 移除群成员失败（该接口为白名单接口，未开通权限会返回 11253）:", err);
+		}
 	}
 	/**
 	* 禁言群成员
@@ -3339,7 +3839,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;
 			}
@@ -3458,49 +3958,63 @@ 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）时降级为占位结构并告警。
+	* - 查询机器人自身（targetId 为 selfId）走官方 `GET /v2/groups/{group_openid}/bot_state`。
+	* - 查询其他成员走 `GET /v2/groups/{group_openid}/members/{member_openid}`，该接口在
+	*   接口文档 v1.28.0（2026-09-03）转为公开文档，昵称字段为 `username`，`nick` 是
+	*   转公开之前的字段名，仅作兼容回退。
+	*
+	* 两者都是白名单接口，未开通权限（11253）或查询失败时降级为占位结构并告警。
 	*/
 	async getGroupMemberInfo(_groupId, _targetId, _refresh) {
-		/** 按 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);
+			return buildGroupMemberInfo(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");
+			return buildGroupMemberInfo(_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);
+			const nick = member.username || member.nick;
+			if (nick) this.nicknameCache.set(_targetId, nick);
+			return buildGroupMemberInfo(member.member_openid || _targetId, member.member_role || "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");
+			this.logger("warn", `[getGroupMemberInfo] 获取群成员详情失败（该接口为白名单接口，未开通权限会返回 11253）: ${err instanceof Error ? err.message : err}`);
+			return buildGroupMemberInfo(_targetId, "member");
 		}
 	}
 	/**
 	* 获取群成员列表
+	*
+	* 走官方 `GET /v2/groups/{group_openid}/members`（白名单接口），每页最多 30 条，
+	* 这里按 `next_cursor` 自动翻完所有页；顺便把昵称写入
+	* {@link AdapterQQBot.nicknameCache}，让后续消息事件能直接取到昵称。
+	*
+	* 为防止平台返回的游标不收敛，翻页数有安全上限（约 6000 人），触顶会告警并返回已取到的部分。
+	* 未开通权限（11253）或查询失败时返回已取到的部分并告警。
+	*
+	* @param _groupId 群 openid
 	*/
 	async getGroupMemberList(_groupId, _refresh) {
-		this.logger("warn", "[getGroupMemberList] QQ Official Bot API 暂不支持获取群成员列表");
-		return [];
+		const result = [];
+		let cursor = "";
+		try {
+			for (let page = 0; page < 200; page++) {
+				const data = await this.super.groups.getGroupMemberList(_groupId, cursor ? { cursor } : {});
+				for (const member of data.members ?? []) {
+					if (member.username) this.nicknameCache.set(member.member_openid, member.username);
+					result.push(buildGroupMemberInfo(member.member_openid, member.member_role || "member", member.username, member.joined_at ? new Date(member.joined_at).getTime() : void 0));
+				}
+				const next = data.next_cursor || "";
+				/** 空游标表示末页；游标不前进说明平台返回异常，直接停止避免死循环 */
+				if (!next || next === cursor) return result;
+				cursor = next;
+			}
+			this.logger("warn", `[getGroupMemberList] 翻页数已达上限 ${200} 页，仅返回前 ${result.length} 名成员`);
+		} catch (err) {
+			this.logger("warn", `[getGroupMemberList] 获取群成员列表失败（该接口为白名单接口，未开通权限会返回 11253）: ${err instanceof Error ? err.message : err}`);
+		}
+		return result;
 	}
 	/**
 	* 获取群荣誉信息
@@ -5083,7 +5597,7 @@ const intentBitMap = {
 	[2]: "GUILD_MEMBERS        (频道成员变更)",
 	[512]: "GUILD_MESSAGES       (频道消息-私域)",
 	[4096]: "DIRECT_MESSAGE       (频道私信)",
-	[1 << 24]: "群成员进退群事件",
+	[1 << 24]: "GROUP_MEMBER_EVENT  (群成员进退群/入群申请)",
 	[1 << 25]: "GROUP_AND_C2C_EVENT (群聊/单聊消息)",
 	[1 << 26]: "INTERACTION          (按钮交互回调)",
 	[1 << 30]: "PUBLIC_GUILD_MESSAGES (频道消息-公域)"
@@ -5372,7 +5886,6 @@ const hashConfig = (bot) => JSON.stringify({
 	appId: bot.appId,
 	secret: bot.secret,
 	event: bot.event,
-	markdown: bot.markdown,
 	messageCache: bot.messageCache
 });
 /**
@@ -5400,6 +5913,8 @@ const createBot = async (input) => {
 		stop(appId);
 		offAll(appId);
 		stopTokenRefresh(appId);
+		/** 重建即重新探测频道 Markdown，拿到内邀后不必重启整个 Karin。 */
+		resetGuildMarkdown(appId);
 		logger.info(`[QQ Official Bot][${appId}] 获取 access_token...`);
 		await getAccessToken(appId, bot.secret);
 		const api = new QQBotApi(createAxiosInstance(appId));
@@ -5408,7 +5923,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;