@karinjs/adapter-qqbot 3.0.8 → 3.2.0

package/dist/index.js

@@ -1,13 +1,14 @@
 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 FormData from "form-data";
 import axios from "node-karin/axios";
+import FormData from "form-data";
 import crypto from "node:crypto";
 import { open, readFile, stat } from "node:fs/promises";
 import path from "node:path";
@@ -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 错误码映射表
@@ -274,7 +366,25 @@ const errorCodeMap = {
 	1100307: "非白名单应用子频道",
 	1100308: "触发频道内限频",
 	1100499: "其他错误",
-	3300006: "安全打击"
+	3300006: "安全打击",
+	40030001: "参数错误，请检查请求参数是否正确",
+	40030006: "指令面板不存在，请确认 panel_id 是否正确",
+	40030008: "URL 格式错误，请确认 URL 以 https:// 开头",
+	40030009: "指令面板操作进行中，存在并发操作冲突，请稍后重试",
+	40030011: "生效场景不合法，scope 仅支持 c2c/group/channel/dm",
+	40030012: "生效范围不合法，target_type 仅支持 all/specific，channel/dm 场景仅支持 all",
+	40030013: "超出数量限制，具体限制值见返回信息中的 limit",
+	40030014: "菜单类型不合法，menu.type 仅支持 switch/send_message/link/menu",
+	40030015: "面板元素类型不合法，panel_item.type 仅支持 command/link",
+	40030016: "必填字段缺失，请检查必填字段是否全部正确传入",
+	40030017: "操作类型不合法，op 仅支持 add/del",
+	40030018: "当前场景不支持此操作，请检查 scope 是否支持当前操作",
+	40030020: "内容存在安全风险，请检查菜单/面板内容是否包含敏感信息",
+	40030021: "全局面板不支持添加指定关联对象，请使用 specific 模式",
+	40061001: "请求参数无效，请检查请求参数格式",
+	40062003: "无操作权限，请检查机器人是否为群管理员，或发消息的用户是否为普通用户",
+	40064004: "已超出消息撤回时限，消息发送超过 2 分钟后不可撤回",
+	50065001: "消息撤回失败，请稍后重试"
 };
 const rangeDefs = [
 	{
@@ -357,6 +467,23 @@ const formatOpenAPIError = (status, code, message) => {
 //#endregion
 //#region src/core/api/http.ts
 /**
+* 把 {@link RequestOptions} 转为 axios 请求配置。
+*
+* @param options 请求可选配置。
+* @returns axios 请求配置。
+*/
+const toAxiosConfig = (options) => {
+	if (!options) return {};
+	const { headers, timeout, params, signal, responseType } = options;
+	return {
+		headers,
+		timeout,
+		params,
+		signal,
+		responseType
+	};
+};
+/**
 * 包装 axios 错误为可读多行 message
 * 如果响应中包含 QQ 官方错误码(err_code)，会自动映射为中文描述
 */
@@ -400,56 +527,199 @@ const redactRequestData = (value) => {
 };
 /**
 * Http 基础类，子模块继承此类共享 axios 实例与错误格式化
+*
+* 各请求方法均为 `protected`，只供各领域 API 子类内部使用；
+* 需要给下游插件开放的裸请求入口见 {@link RequestApi}。
 */
 var Http = class {
 	axios;
 	constructor(axios) {
 		this.axios = axios;
 	}
-	async get(path) {
+	async get(path, options) {
 		try {
-			const { data } = await this.axios.get(path);
+			const { data } = await this.axios.get(path, toAxiosConfig(options));
 			return data;
 		} catch (err) {
 			throw formatError(path, void 0, err);
 		}
 	}
-	async post(path, body = {}, headers, timeout) {
+	async post(path, body = {}, options) {
 		try {
-			const { data } = await this.axios.post(path, body, {
-				headers,
-				timeout
-			});
+			const { data } = await this.axios.post(path, body, toAxiosConfig(options));
 			return data;
 		} catch (err) {
 			throw formatError(path, body, err);
 		}
 	}
-	async put(path, body = {}, headers, timeout) {
+	async put(path, body = {}, options) {
 		try {
-			const { data } = await this.axios.put(path, body, {
-				headers,
-				timeout
-			});
+			const { data } = await this.axios.put(path, body, toAxiosConfig(options));
 			return data;
 		} catch (err) {
 			throw formatError(path, body, err);
 		}
 	}
-	async delete(path) {
+	async patch(path, body = {}, options) {
 		try {
-			const { data } = await this.axios.delete(path);
+			const { data } = await this.axios.patch(path, body, toAxiosConfig(options));
+			return data;
+		} catch (err) {
+			throw formatError(path, body, err);
+		}
+	}
+	async delete(path, options) {
+		try {
+			const { data } = await this.axios.delete(path, toAxiosConfig(options));
 			return data;
 		} catch (err) {
 			throw formatError(path, void 0, err);
 		}
 	}
+	/**
+	* 任意 method 的裸请求，返回响应体。
+	*
+	* @param config axios 请求配置，`url` 相对 `baseURL`。
+	* @returns 响应体 `data`。
+	*/
+	async request(config) {
+		const label = `${String(config.method ?? "GET").toUpperCase()} ${config.url ?? ""}`;
+		try {
+			const { data } = await this.axios.request(config);
+			return data;
+		} catch (err) {
+			throw formatError(label, config.data, err);
+		}
+	}
+	/**
+	* 任意 method 的裸请求，返回完整 axios 响应。
+	*
+	* 需要读取响应头或状态码时使用。
+	*
+	* @param config axios 请求配置，`url` 相对 `baseURL`。
+	* @returns 完整 axios 响应。
+	*/
+	async requestRaw(config) {
+		const label = `${String(config.method ?? "GET").toUpperCase()} ${config.url ?? ""}`;
+		try {
+			return await this.axios.request(config);
+		} catch (err) {
+			throw formatError(label, config.data, err);
+		}
+	}
+};
+
+//#endregion
+//#region src/core/api/request.ts
+/**
+* 裸请求入口，供下游插件直接调用官方 OpenAPI。
+*
+* {@link Http} 的请求方法是 `protected`，只供各领域 API 子类内部使用；
+* 本类把同一套方法以 `public` 暴露出来，用于官方新接口尚未被适配器封装、
+* 或需要传自定义参数的场景：
+*
+* ```ts
+* const bot = e.bot as AdapterQQBot
+*
+* // GET，query 走 params
+* const menu = await bot.super.request.get('/v2/menu')
+* const list = await bot.super.request.get('/v2/panels', { params: { scope: 'group', limit: 20 } })
+*
+* // POST / PUT / PATCH / DELETE
+* await bot.super.request.post(`/v2/groups/${groupId}/messages`, { content: 'hi', msg_type: 0 })
+* await bot.super.request.put('/v2/menu', { menu })
+*
+* // 任意 method
+* await bot.super.request.request({ method: 'POST', url: '/v2/xxx', data: {} })
+* ```
+*
+* 与直接用 `bot.super.axios` 的区别：
+* - 自动解包 `response.data`；
+* - 失败时抛出的 Error 已带请求路径、脱敏请求体、QQ 错误码中文描述和 TraceID。
+*
+* 需要读响应头或状态码时用 {@link RequestApi.requestRaw}；
+* 需要完全裸的 axios 时用 `bot.super.axios`。
+*
+* 路径相对官方 API baseURL，鉴权头由拦截器自动注入，无需自己传 Authorization。
+*/
+var RequestApi = class extends Http {
+	/**
+	* GET 请求。
+	*
+	* @param path 接口路径，相对 baseURL。
+	* @param options 可选配置（params / headers / timeout 等）。
+	* @returns 响应体。
+	*/
+	get(path, options) {
+		return super.get(path, options);
+	}
+	/**
+	* POST 请求。
+	*
+	* @param path 接口路径，相对 baseURL。
+	* @param body 请求体，默认空对象。
+	* @param options 可选配置（params / headers / timeout 等）。
+	* @returns 响应体。
+	*/
+	post(path, body, options) {
+		return super.post(path, body, options);
+	}
+	/**
+	* PUT 请求。
+	*
+	* @param path 接口路径，相对 baseURL。
+	* @param body 请求体，默认空对象。
+	* @param options 可选配置（params / headers / timeout 等）。
+	* @returns 响应体。
+	*/
+	put(path, body, options) {
+		return super.put(path, body, options);
+	}
+	/**
+	* PATCH 请求。
+	*
+	* @param path 接口路径，相对 baseURL。
+	* @param body 请求体，默认空对象。
+	* @param options 可选配置（params / headers / timeout 等）。
+	* @returns 响应体。
+	*/
+	patch(path, body, options) {
+		return super.patch(path, body, options);
+	}
+	/**
+	* DELETE 请求。
+	*
+	* @param path 接口路径，相对 baseURL。
+	* @param options 可选配置（params / headers / timeout 等）。
+	* @returns 响应体。
+	*/
+	delete(path, options) {
+		return super.delete(path, options);
+	}
+	/**
+	* 任意 method 的请求，返回响应体。
+	*
+	* @param config axios 请求配置，`url` 相对 baseURL。
+	* @returns 响应体。
+	*/
+	request(config) {
+		return super.request(config);
+	}
+	/**
+	* 任意 method 的请求，返回完整 axios 响应。
+	*
+	* 需要读取响应头或状态码时使用。
+	*
+	* @param config axios 请求配置，`url` 相对 baseURL。
+	* @returns 完整 axios 响应。
+	*/
+	requestRaw(config) {
+		return super.requestRaw(config);
+	}
 };
 
 //#endregion
 //#region src/core/api/messages.ts
-/** 输入中状态默认展示时长（秒），平台 typing 窗口约 60s */
-const INPUT_NOTIFY_DEFAULT_SECOND = 60;
 /**
 * 消息发送 + 撤回
 */
@@ -468,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: {
@@ -492,7 +762,7 @@ var MessagesApi = class extends Http {
 	/** 文字子频道消息 */
 	sendChannelMsg(channelId, body) {
 		const headers = body instanceof FormData ? body.getHeaders() : void 0;
-		return this.post(`/channels/${channelId}/messages`, body, headers);
+		return this.post(`/channels/${channelId}/messages`, body, { headers });
 	}
 	async sendDmsMsg(a, b, c) {
 		if (typeof b === "string") {
@@ -501,10 +771,10 @@ var MessagesApi = class extends Http {
 				source_guild_id: b
 			});
 			const headers = c instanceof FormData ? c.getHeaders() : void 0;
-			return this.post(`/dms/${dms.guild_id}/messages`, c, headers);
+			return this.post(`/dms/${dms.guild_id}/messages`, c, { headers });
 		}
 		const headers = b instanceof FormData ? b.getHeaders() : void 0;
-		return this.post(`/dms/${a}/messages`, b, headers);
+		return this.post(`/dms/${a}/messages`, b, { headers });
 	}
 	async recall(type, peer, messageId, hidetip = false) {
 		const path = type === "user" || type === "group" ? `/v2/${type}s/${peer}/messages/${messageId}` : `/${type}/${peer}/messages/${messageId}?hidetip=${hidetip}`;
@@ -531,7 +801,7 @@ const MIN_EFFECTIVE_TTL_SECONDS = 10;
 * @param contentHash 文件内容 hash。
 * @returns 缓存键。
 */
-const cacheKey = (scene, peer, type, contentHash) => [
+const cacheKey$1 = (scene, peer, type, contentHash) => [
 	scene,
 	peer,
 	type,
@@ -551,7 +821,7 @@ const cacheKey = (scene, peer, type, contentHash) => [
 */
 const getCachedUpload = async (scene, peer, type, contentHash) => {
 	try {
-		const raw = await getMessageStore().getUploadCache(cacheKey(scene, peer, type, contentHash));
+		const raw = await getMessageStore().getUploadCache(cacheKey$1(scene, peer, type, contentHash));
 		if (!raw) return null;
 		return JSON.parse(raw);
 	} catch {
@@ -572,79 +842,56 @@ const setCachedUpload = async (scene, peer, type, contentHash, response) => {
 	const ttl = Number(response.ttl);
 	const expiresAt = ttl > 0 ? Date.now() + Math.max(ttl - TTL_SAFETY_MARGIN_SECONDS, MIN_EFFECTIVE_TTL_SECONDS) * 1e3 : 0;
 	try {
-		await getMessageStore().setUploadCache(cacheKey(scene, peer, type, contentHash), JSON.stringify(response), expiresAt);
+		await getMessageStore().setUploadCache(cacheKey$1(scene, peer, type, contentHash), JSON.stringify(response), expiresAt);
 	} catch {}
 };
 
 //#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 兼容处理，避免破坏旧调用方式。
@@ -686,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 对应类型上限。
@@ -736,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 };
@@ -752,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",
@@ -810,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) => {
@@ -866,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",
@@ -879,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)}`);
 };
@@ -960,7 +1207,7 @@ var MediaApi = class extends Http {
 		if (type === "file" && fileName) body.file_name = fileName;
 		const path = `/v2/${scene}s/${peer}/files`;
 		try {
-			return await this.post(path, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+			return await this.post(path, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 		} catch (err) {
 			if (!sourceBody.url) throw err;
 			const fallbackBody = {
@@ -968,7 +1215,7 @@ var MediaApi = class extends Http {
 				file_data: await downloadRemoteAsBase64(sourceBody.url)
 			};
 			delete fallbackBody.url;
-			return this.post(path, fallbackBody, void 0, MEDIA_UPLOAD_TIMEOUT);
+			return this.post(path, fallbackBody, { timeout: MEDIA_UPLOAD_TIMEOUT });
 		}
 	}
 	/**
@@ -993,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;
@@ -1004,11 +1251,44 @@ var MediaApi = class extends Http {
 			file_data: await readFallbackSourceAsBase64(fallbackSource)
 		};
 		if (type === "file") body.file_name = fallbackSource.fileName;
-		const response = await this.post(`/v2/${scene}s/${peer}/files`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+		const response = await this.post(`/v2/${scene}s/${peer}/files`, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 		if (hashes) await setCachedUpload(scene, peer, type, hashes.md5, response);
 		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，此时需要在服务端给出的
@@ -1021,8 +1301,8 @@ var MediaApi = class extends Http {
 	*/
 	async finishUploadPart(scene, peer, body, retryTimeout) {
 		let lastError;
-		for (let attempt = 0; attempt <= PART_FINISH_RETRIES; attempt++) try {
-			await this.post(`/v2/${scene}s/${peer}/upload_part_finish`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+		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) {
 			if (shouldRetryPartFinishPersistently(err)) {
@@ -1030,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);
 	}
@@ -1048,7 +1328,7 @@ var MediaApi = class extends Http {
 		let attempts = 0;
 		let lastError;
 		while (Date.now() < deadline) try {
-			await this.post(`/v2/${scene}s/${peer}/upload_part_finish`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+			await this.post(`/v2/${scene}s/${peer}/upload_part_finish`, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 			return;
 		} catch (err) {
 			lastError = err;
@@ -1069,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 {
-			return await this.post(`/v2/${scene}s/${peer}/files`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+		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);
 	}
@@ -1099,12 +1379,12 @@ var MediaApi = class extends Http {
 			sha1: hashes.sha1
 		};
 		prepareBody["md5_10m"] = hashes.md510m;
-		const prepare = await this.post(`/v2/${scene}s/${peer}/upload_prepare`, prepareBody, void 0, 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)})`);
+		const prepare = await this.post(`/v2/${scene}s/${peer}/upload_prepare`, prepareBody, { timeout: MEDIA_UPLOAD_TIMEOUT }).catch((err) => {
+			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 () => {
@@ -1130,89 +1410,409 @@ var MediaApi = class extends Http {
 
 //#endregion
 //#region src/core/api/interaction.ts
-/** QQ 客户端回调按钮需要快速 ACK，超时必须小于平台等待窗口。 */
-const INTERACTION_ACK_TIMEOUT = 2800;
 /**
 * INTERACTION_CREATE 回应
 */
 var InteractionApi = class extends Http {
 	/**
-	* @param interactionId INTERACTION_CREATE 事件中的 id
-	* @param code 0 成功 / 1 操作失败 / 2 操作频繁 / 3 重复操作 / 4 无权限 / 5 仅管理员
+	* @param interactionId INTERACTION_CREATE 事件中的 id
+	* @param code 0 成功 / 1 操作失败 / 2 操作频繁 / 3 重复操作 / 4 无权限 / 5 仅管理员
+	*/
+	async ack(interactionId, code = 0) {
+		await this.put(`/interactions/${interactionId}`, { code }, { timeout: INTERACTION_ACK_TIMEOUT });
+	}
+};
+
+//#endregion
+//#region src/core/api/meta.ts
+/**
+* 元信息接口：@me / dms / gateway / 分享链接
+*/
+var MetaApi = class extends Http {
+	/** 当前机器人详情 */
+	getMe() {
+		return this.get("/users/@me");
+	}
+	/** 创建频道私信会话 */
+	createDms(recipientId, srcGuildId) {
+		return this.post("/users/@me/dms", {
+			recipient_id: recipientId,
+			source_guild_id: srcGuildId
+		});
+	}
+	/** 获取通用 WSS 地址 */
+	getGateway() {
+		return this.get("/gateway");
+	}
+	/**
+	* 生成机器人分享链接
+	*
+	* 用于邀请用户添加机器人为好友；`callback_data`（最长 32 字符）会在用户通过该
+	* 链接添加机器人时透传到 `FRIEND_ADD` 事件的 `scene_param`。
+	*
+	* @param body 分享链接参数，均为可选
+	*/
+	generateUrlLink(body = {}) {
+		return this.post("/v2/generate_url_link", body);
+	}
+};
+
+//#endregion
+//#region src/core/api/groups.ts
+/**
+* QQ 群信息接口
+*
+* 注意：以下接口均为白名单接口，未开通权限时平台返回错误码 11253，
+* 需要向平台运营申请后可用。
+*/
+var GroupsApi = class extends Http {
+	/**
+	* 获取群基础信息
+	* @param groupOpenid 群 openid
+	*/
+	getGroupInfo(groupOpenid) {
+		return this.get(`/v2/groups/${groupOpenid}/info`);
+	}
+	/**
+	* 获取机器人在群内的状态（角色、入群时间、主动消息开关等）
+	* @param groupOpenid 群 openid
+	*/
+	getBotState(groupOpenid) {
+		return this.get(`/v2/groups/${groupOpenid}/bot_state`);
+	}
+	/**
+	* 获取群成员详情
+	*
+	* @param groupOpenid 群 openid
+	* @param memberOpenid 群成员 openid
+	*/
+	getGroupMember(groupOpenid, memberOpenid) {
+		return this.get(`/v2/groups/${groupOpenid}/members/${memberOpenid}`);
+	}
+	/**
+	* 设置群成员禁言
+	*
+	* 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天。
+	*
+	* @param groupOpenid 群 openid
+	* @param memberOpenid 群成员 openid
+	* @param op 操作: add 增加禁言，update 更新禁言到期时间，del 解除禁言
+	* @param duration 禁言时间使用RFC3339 格式
+	*/
+	setGroupMute(groupOpenid, memberOpenid, op, duration) {
+		return this.post(`/v2/groups/${groupOpenid}/restrict_chat_setting`, { members: [{
+			op,
+			member_openid: memberOpenid,
+			mute_expire_at: duration
+		}] });
+	}
+	/**
+	* 设置群成员禁言
+	* @deprecated 方法名拼写错误，请使用 {@link GroupsApi.setGroupMute}
+	*/
+	setGroupMetu(groupOpenid, memberOpenid, op, duration) {
+		return this.setGroupMute(groupOpenid, memberOpenid, op, duration);
+	}
+	/**
+	* 查询群禁言状态
+	*
+	* 返回全员禁言模式（含定时 / 周期规则）与当前禁言中的成员列表（不含已过期）。
+	* 机器人需拥有群管理员身份。
+	*
+	* @param groupOpenid 群 openid
+	*/
+	getGroupMuteSetting(groupOpenid) {
+		return this.get(`/v2/groups/${groupOpenid}/restrict_chat_setting`);
+	}
+	/**
+	* 拉取入群申请列表
+	*
+	* 机器人需拥有群管理员身份。
+	*
+	* @param groupOpenid 群 openid
+	* @param params 分页参数，`limit` 默认 20、最大 100
+	*/
+	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));
+		const search = query.toString();
+		return this.get(`/v2/groups/${groupOpenid}/join_request_list${search ? `?${search}` : ""}`);
+	}
+	/**
+	* 审批入群申请
+	*
+	* 机器人需拥有群管理员身份。
+	*
+	* @param groupOpenid 群 openid
+	* @param memberOpenid 申请人 openid
+	* @param body 审批动作，`op=decline` 时可附带拒绝理由与拉黑标记
+	*/
+	approvalJoinRequest(groupOpenid, memberOpenid, body) {
+		return this.post(`/v2/groups/${groupOpenid}/approval_join_request/${memberOpenid}`, body);
+	}
+};
+
+//#endregion
+//#region src/core/api/guilds.ts
+/**
+* 频道 / 子频道接口
+*
+* 子频道的创建、修改、删除均需要管理员权限且属于私域接口，
+* 操作成功后会触发 `CHANNEL_CREATE` / `CHANNEL_UPDATE` / `CHANNEL_DELETE` 事件。
+*/
+var GuildsApi = class extends Http {
+	/**
+	* 获取机器人加入的频道列表
+	*
+	* 官方文档响应体标注为 `{ guilds: [] }`，但示例与实际返回均为裸数组；
+	* 这里对两种形态都做兼容。
+	*
+	* @param params 分页参数，`limit` 默认 100、最大 100
+	*/
+	async getGuildList(params = {}) {
+		const query = new URLSearchParams();
+		if (params.before) query.set("before", params.before);
+		if (params.after) query.set("after", params.after);
+		if (params.limit !== void 0) query.set("limit", String(params.limit));
+		const search = query.toString();
+		const data = await this.get(`/users/@me/guilds${search ? `?${search}` : ""}`);
+		if (Array.isArray(data)) return data;
+		return data?.guilds ?? [];
+	}
+	/**
+	* 获取频道详情
+	* @param guildId 频道 ID
+	*/
+	getGuild(guildId) {
+		return this.get(`/guilds/${guildId}`);
+	}
+	/**
+	* 获取子频道列表
+	*
+	* 官方文档响应体标注为 `{ channels: [] }`，但示例与实际返回均为裸数组；
+	* 这里对两种形态都做兼容。
+	*
+	* @param guildId 频道 ID
+	*/
+	async getChannelList(guildId) {
+		const data = await this.get(`/guilds/${guildId}/channels`);
+		if (Array.isArray(data)) return data;
+		return data?.channels ?? [];
+	}
+	/**
+	* 创建子频道（需要管理员权限，私域接口）
+	* @param guildId 频道 ID
+	* @param body 子频道配置
+	*/
+	createChannel(guildId, body) {
+		return this.post(`/guilds/${guildId}/channels`, body);
+	}
+	/**
+	* 获取子频道详情
+	* @param channelId 子频道 ID
+	*/
+	getChannel(channelId) {
+		return this.get(`/channels/${channelId}`);
+	}
+	/**
+	* 修改子频道（需要管理员权限，私域接口）
+	*
+	* 只需传入要修改的字段。
+	* @param channelId 子频道 ID
+	* @param body 待修改的字段
+	*/
+	updateChannel(channelId, body) {
+		return this.patch(`/channels/${channelId}`, body);
+	}
+	/**
+	* 删除子频道（需要管理员权限，私域接口）
+	*
+	* 子频道删除后无法恢复。
+	* @param channelId 子频道 ID
+	*/
+	deleteChannel(channelId) {
+		return this.delete(`/channels/${channelId}`);
+	}
+};
+
+//#endregion
+//#region src/core/api/menu.ts
+/**
+* 全局自定义菜单接口
+*
+* 自定义菜单展示在机器人单聊窗口底部，仅支持 C2C（单聊）场景，
+* 设置后对所有用户生效，不支持按用户维度区分。
+*
+* {@link https://bot.q.qq.com/wiki/develop/api-v2/server-inter/menu-panel/}
+*/
+var MenuApi = class extends Http {
+	/**
+	* 查询全局自定义菜单
+	*
+	* 未设置过菜单时响应的 `menu` 字段为空。
+	* @returns 当前生效的菜单配置与版本号
+	*/
+	getMenu() {
+		return this.get("/v2/menu");
+	}
+	/**
+	* 修改全局自定义菜单
+	*
+	* 传入后会覆盖原有的完整菜单配置；不传 `menu` 表示清空菜单。
+	* @param menu 菜单配置，最多 10 个一级菜单项
+	* @returns 本次修改后的菜单版本号
+	*/
+	updateMenu(menu) {
+		return this.put("/v2/menu", menu ? { menu } : {});
+	}
+};
+
+//#endregion
+//#region src/core/api/panels.ts
+/**
+* 指令面板接口
+*
+* 指令面板以面板形式展示指令或链接，支持 c2c（单聊）、group（群聊）、
+* channel（文字子频道）、dm（频道私信）四种场景；其中 c2c / group 支持
+* 按指定用户或群生效（target_type=specific），channel / dm 仅支持全局配置。
+*
+* 一个机器人最多创建 20 个指令面板。
+*
+* {@link https://bot.q.qq.com/wiki/develop/api-v2/server-inter/menu-panel/}
+*/
+var PanelsApi = class extends Http {
+	/**
+	* 查询指令面板列表
+	*
+	* 分页拉取指定场景下已生效的面板，按设置时间倒序排列。
+	* @param params 查询参数，`scope` 必填
+	* @returns 面板记录列表与分页游标
+	*/
+	getPanelList(params) {
+		const query = new URLSearchParams({ scope: params.scope });
+		if (params.cursor) query.set("cursor", params.cursor);
+		if (params.limit !== void 0) query.set("limit", String(params.limit));
+		return this.get(`/v2/panels?${query.toString()}`);
+	}
+	/**
+	* 创建指令面板
+	* @param body 面板场景、作用范围与配置内容
+	* @returns 新创建的面板 ID
+	*/
+	createPanel(body) {
+		return this.post("/v2/panels", body);
+	}
+	/**
+	* 查询指令面板详情
+	*
+	* 返回面板完整配置，target_type=specific 时同时返回关联的用户 / 群 openid 列表。
+	* @param panelId 面板 ID
+	*/
+	getPanel(panelId) {
+		return this.get(`/v2/panels/${panelId}`);
+	}
+	/**
+	* 修改指令面板
+	*
+	* 传入后会覆盖原有的面板元素列表和备注，不影响已关联的用户 / 群列表。
+	* @param panelId 面板 ID
+	* @param panel 面板配置内容
+	* @returns 本次修改后的面板版本号
+	*/
+	updatePanel(panelId, panel) {
+		return this.put(`/v2/panels/${panelId}`, { panel });
+	}
+	/**
+	* 删除指令面板
+	*
+	* 删除后该面板不再对任何用户或群生效。
+	* @param panelId 面板 ID
+	*/
+	deletePanel(panelId) {
+		return this.delete(`/v2/panels/${panelId}`);
+	}
+	/**
+	* 修改指令面板关联对象
+	*
+	* c2c 场景操作 `user_openids`，group 场景操作 `group_openids`，一次最多 20 个；
+	* channel / dm 场景为全局配置，不支持此操作。
+	* @param panelId 面板 ID
+	* @param body 操作类型与关联对象列表
 	*/
-	async ack(interactionId, code = 0) {
-		await this.put(`/interactions/${interactionId}`, { code }, void 0, INTERACTION_ACK_TIMEOUT);
+	updatePanelTarget(panelId, body) {
+		return this.put(`/v2/panels/${panelId}/target`, body);
 	}
 };
 
 //#endregion
-//#region src/core/api/meta.ts
+//#region src/core/api/join-approval.ts
 /**
-* 元信息接口：@me / dms / gateway
+* 入群自动审批策略接口
+*
+* 策略把「关联群 + 白名单 QQ 号码」绑在一起，命中白名单的入群申请会自动审批通过。
+* 规则仅在机器人拥有群管理员身份时才会实际运行；一个机器人最多 20 个策略。
 */
-var MetaApi = class extends Http {
-	/** 当前机器人详情 */
-	getMe() {
-		return this.get("/users/@me");
-	}
-	/** 创建频道私信会话 */
-	createDms(recipientId, srcGuildId) {
-		return this.post("/users/@me/dms", {
-			recipient_id: recipientId,
-			source_guild_id: srcGuildId
-		});
+var JoinApprovalApi = class extends Http {
+	/**
+	* 查询入群自动审批策略列表
+	*
+	* 按创建时间倒序，支持分页。
+	* @param params 分页参数，`limit` 默认 20、最大 100
+	*/
+	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));
+		const search = query.toString();
+		return this.get(`/v2/groups/join_approval_strategy${search ? `?${search}` : ""}`);
 	}
-	/** 获取通用 WSS 地址 */
-	getGateway() {
-		return this.get("/gateway");
+	/**
+	* 创建入群自动审批策略
+	*
+	* `group_openids` 与 `group_ids` 二选一必填，同时传入或均未传入都会报错。
+	* @param body 策略配置
+	*/
+	createStrategy(body) {
+		return this.post("/v2/groups/join_approval_strategy", body);
 	}
-};
-
-//#endregion
-//#region src/core/api/groups.ts
-/**
-* QQ 群信息接口
-*
-* 注意：以下接口均为白名单接口，未开通权限时平台返回错误码 11253，
-* 需要向平台运营申请后可用。
-*/
-var GroupsApi = class extends Http {
 	/**
-	* 获取群基础信息
-	* @param groupOpenid 群 openid
+	* 修改入群自动审批策略
+	*
+	* 可修改生效状态、失效时间、备注，或增删关联群；
+	* 增删关联群时的群标识形式必须与创建时一致。
+	* @param strategyId 策略 ID
+	* @param body 待修改的字段
 	*/
-	getGroupInfo(groupOpenid) {
-		return this.get(`/v2/groups/${groupOpenid}/info`);
+	updateStrategy(strategyId, body) {
+		return this.patch(`/v2/groups/join_approval_strategy/${strategyId}`, body);
 	}
 	/**
-	* 获取机器人在群内的状态（角色、入群时间、主动消息开关等）
-	* @param groupOpenid 群 openid
+	* 删除入群自动审批策略
+	* @param strategyId 策略 ID
 	*/
-	getBotState(groupOpenid) {
-		return this.get(`/v2/groups/${groupOpenid}/bot_state`);
+	deleteStrategy(strategyId) {
+		return this.delete(`/v2/groups/join_approval_strategy/${strategyId}`);
 	}
 	/**
-	* 获取群成员详情
+	* 执行入群自动审批策略
 	*
-	* @param groupOpenid 群 openid
-	* @param memberOpenid 群成员 openid
+	* 对策略关联的全部群发起全量扫描，命中白名单号码的入群申请自动审批通过。
+	* 异步执行，约 10 分钟完成。
+	* @param strategyId 策略 ID
 	*/
-	getGroupMember(groupOpenid, memberOpenid) {
-		return this.get(`/v2/groups/${groupOpenid}/members/${memberOpenid}`);
+	executeStrategy(strategyId) {
+		return this.post(`/v2/groups/join_approval_strategy/${strategyId}/execute`);
 	}
 	/**
-	* 设置群成员禁言
-	* @param groupOpenid 群 openid
-	* @param memberOpenid 群成员 openid
-	* @param op 操作: add 增加禁言，update 更新禁言到期时间，del 解除禁言
-	* @param duration 禁言时间使用RFC3339 格式
+	* 修改入群自动审批策略的白名单号码
+	*
+	* 单次最多 10000 个，策略号码上限 10W。
+	* @param strategyId 策略 ID
+	* @param body 操作类型与号码列表
 	*/
-	setGroupMetu(groupOpenid, memberOpenid, op, duration) {
-		return this.post(`/v2/groups/${groupOpenid}/restrict_chat_setting`, { members: [{
-			op,
-			member_openid: memberOpenid,
-			mute_expire_at: duration
-		}] });
+	updateWhitelistUsers(strategyId, body) {
+		return this.post(`/v2/groups/join_approval_strategy/${strategyId}/whitelist_users`, body);
 	}
 };
 
@@ -1241,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
 		};
 	}
 };
@@ -1296,28 +1902,56 @@ const buildGuildMsg = {
 * - messages：发送 / 撤回
 * - media：富媒体上传
 * - interaction：按钮回调 ack
-* - meta：@me / dms / gateway
-* - groups：群基础信息 / 机器人群内状态（白名单接口）
+* - meta：@me / dms / gateway / 分享链接
+* - groups：群基础信息 / 机器人群内状态 / 禁言 / 入群申请（部分为白名单接口）
+* - guilds：频道与子频道的查询和增删改
+* - menu：全局自定义菜单（仅单聊）
+* - panels：指令面板
+* - joinApproval：入群自动审批策略
+* - request：裸请求入口，用于调用尚未封装的官方接口
 *
 * 请求体构造器 {@link buildQQMsg} / {@link buildGuildMsg} 独立导出，避免与 HTTP 调用耦合
 */
 var QQBotApi = class {
 	axios;
+	/**
+	* 裸请求入口，直接调用官方 OpenAPI。
+	*
+	* 官方新接口还没被适配器封装时可用它兜底，会自动带鉴权、解包 `data`、
+	* 格式化错误码：
+	*
+	* ```ts
+	* await bot.super.request.get('/v2/menu')
+	* await bot.super.request.post('/v2/xxx', { foo: 1 })
+	* ```
+	*
+	* @see {@link RequestApi}
+	*/
+	request;
 	messages;
 	media;
 	interaction;
 	meta;
 	groups;
+	guilds;
+	menu;
+	panels;
+	joinApproval;
 	/** 请求体构造器（静态便利） */
 	qq = buildQQMsg;
 	guild = buildGuildMsg;
 	constructor(axios) {
 		this.axios = axios;
+		this.request = new RequestApi(axios);
 		this.messages = new MessagesApi(axios);
 		this.media = new MediaApi(axios);
 		this.interaction = new InteractionApi(axios);
 		this.meta = new MetaApi(axios);
 		this.groups = new GroupsApi(axios);
+		this.guilds = new GuildsApi(axios);
+		this.menu = new MenuApi(axios);
+		this.panels = new PanelsApi(axios);
+		this.joinApproval = new JoinApprovalApi(axios);
 	}
 };
 
@@ -1582,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 处理器。
@@ -1600,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"
 		};
 	}
@@ -1638,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) => {
@@ -1667,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;
 	}
@@ -1689,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 场景（单聊 + 群聊）的发送
 */
@@ -1731,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);
 };
@@ -1781,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);
 };
@@ -1805,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;
@@ -1821,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") {
@@ -1830,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;
 };
@@ -1847,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));
 };
 /**
 * 判断显式引用回复是否应降级为普通文本消息。
@@ -1902,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;
@@ -1942,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);
@@ -1970,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 };
@@ -1979,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，因此这里基于官方错误码和中文错误信息兜底识别。
@@ -2055,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 = "​";
 /**
 * 处理频道场景（子频道 + 私信）的发送
 *
@@ -2078,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);
 };
@@ -2125,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 {
@@ -2159,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;
@@ -2415,10 +3243,101 @@ const responseTime = (timestamp) => {
 };
 
 //#endregion
-//#region src/core/adapter/base.ts
+//#region src/core/adapter/join-request-cache.ts
+/** 入群申请索引缓存上限，仅用于把 Karin 的 flag 还原成群 / 成员 openid */
+const JOIN_REQUEST_CACHE_MAX = 1e3;
+/**
+* `appId:join_request_id` -> 群 / 申请人 openid。
+*
+* Karin 的 `setGroupApplyResult` / `setInvitedJoinGroupResult` 只透传 flag
+* （即 `join_request_id`），而官方审批接口的路径需要 group_openid 与
+* member_openid，因此在收到入群申请事件时先把对应关系记下来。
+*
+* 按 appId 加前缀，避免多 bot 共用进程时互相覆盖。
+*/
+const joinRequests = /* @__PURE__ */ new Map();
+/**
+* 拼接缓存键。
+* @param appId 机器人 appId。
+* @param joinRequestId 申请 ID。
+*/
+const cacheKey = (appId, joinRequestId) => `${appId}:${joinRequestId}`;
+/**
+* 记录入群申请索引，供后续审批接口还原群 / 申请人 openid。
+*
+* 超出上限时按写入顺序淘汰最旧的一条。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param joinRequestId 申请 ID，同时是 Karin 请求事件的 flag。
+* @param target 该申请对应的群与申请人 openid。
+*/
+const cacheJoinRequest = (ctx, joinRequestId, target) => {
+	if (!joinRequestId) return;
+	if (joinRequests.size >= JOIN_REQUEST_CACHE_MAX) {
+		const oldest = joinRequests.keys().next().value;
+		if (oldest !== void 0) joinRequests.delete(oldest);
+	}
+	joinRequests.set(cacheKey(String(ctx.cfg.appId), joinRequestId), target);
+};
+/**
+* 读取入群申请索引。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param joinRequestId 申请 ID。
+* @returns 命中的群 / 申请人 openid；未命中返回 undefined。
+*/
+const getJoinRequest = (ctx, joinRequestId) => {
+	return joinRequests.get(cacheKey(String(ctx.cfg.appId), joinRequestId));
+};
+/**
+* 审批完成后移除索引。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param joinRequestId 申请 ID。
+*/
+const removeJoinRequest = (ctx, joinRequestId) => {
+	joinRequests.delete(cacheKey(String(ctx.cfg.appId), joinRequestId));
+};
+/**
+* 清理某个 bot 的全部入群申请索引，销毁 bot 时调用。
+*
+* @param appId 机器人 appId。
+*/
+const clearJoinRequests = (appId) => {
+	const prefix = `${appId}:`;
+	for (const key of joinRequests.keys()) if (key.startsWith(prefix)) joinRequests.delete(key);
+};
+
+//#endregion
+//#region src/core/adapter/config-store.ts
+/**
+* 适配器实例的真实配置存储。
+*
+* 配置挂在 WeakMap 而不是实例字段上：系统接口序列化整个适配器时不会把
+* appSecret 等敏感配置带出去。
+*/
 const adapterConfigStore = /* @__PURE__ */ new WeakMap();
-/** HTTP(S) URL 可直接交给 QQ 平台拉取上传 */
-const HTTP_URL_RE = /^https?:\/\//i;
+/**
+* 绑定适配器实例与其配置。
+* @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 适配器
 *
@@ -2432,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";
@@ -2441,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() {
@@ -2463,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;
 		}
@@ -2558,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 />");
@@ -2729,20 +3670,31 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 禁言群成员
+	*
+	* 机器人需拥有群管理员身份；平台限制最大禁言时长为 30 天，
+	* 超出部分会被截断到 30 天而不是直接失败。
+	*
+	* @param _groupId 群 openid
+	* @param _targetId 群成员 openid
+	* @param duration 禁言时长（秒），传 0 或负数表示解除禁言
 	*/
 	async setGroupMute(_groupId, _targetId, duration) {
 		let rfc3339 = "";
 		if (duration > 0) {
-			const time = Date.now() + duration * 1e3;
-			rfc3339 = new Date(time).toISOString();
+			let seconds = duration;
+			if (seconds > 2592e3) {
+				this.logger("warn", `[setGroupMute] 禁言时长 ${seconds}s 超出平台上限 30 天，已截断为 ${MAX_GROUP_MUTE_SECONDS}s`);
+				seconds = MAX_GROUP_MUTE_SECONDS;
+			}
+			rfc3339 = new Date(Date.now() + seconds * 1e3).toISOString();
 		}
-		this.super.groups.setGroupMetu(_groupId, _targetId, rfc3339 ? "add" : "del", rfc3339);
+		await this.super.groups.setGroupMute(_groupId, _targetId, rfc3339 ? "add" : "del", rfc3339);
 	}
 	/**
 	* 群全员禁言
 	*/
 	async setGroupAllMute(_groupId, _isBan) {
-		this.logger("warn", "[setGroupAllMute] QQ Official Bot API 暂不支持群全员禁言");
+		this.logger("warn", "[setGroupAllMute] QQ Official Bot API 暂不支持设置群全员禁言，仅可通过 bot.super.groups.getGroupMuteSetting() 查询 global_rule");
 	}
 	/**
 	* 设置群管理员
@@ -2794,8 +3746,11 @@ var AdapterQQBot = class extends AdapterBase {
 	/**
 	* 获取群信息
 	*
-	* 走官方 `GET /v2/groups/{group_openid}/info`（白名单接口）。
-	* 未开通权限（11253）或查询失败时降级为空结构并告警。
+	* QQ 群走官方 `GET /v2/groups/{group_openid}/info`（白名单接口）；传入的是频道
+	* ID 时退回 `GET /guilds/{guild_id}`，这样频道场景下的插件调用也能拿到名称和
+	* 人数。两者都不可用（如白名单未开通返回 11253）时降级为空结构并告警。
+	*
+	* @param _groupId 群 openid 或频道 ID。
 	*/
 	async getGroupInfo(_groupId, _noCache) {
 		const empty = {
@@ -2819,15 +3774,28 @@ var AdapterQQBot = class extends AdapterBase {
 				avatar: await this.getGroupAvatarUrl(_groupId)
 			};
 		} catch (err) {
+			const guild = await this.super.guilds.getGuild(_groupId).catch(() => null);
+			if (guild) return {
+				...empty,
+				groupName: guild.name || "",
+				owner: guild.owner_id || "",
+				memberCount: guild.member_count ?? 0,
+				maxMemberCount: guild.max_members ?? 0,
+				groupDesc: guild.description || "",
+				avatar: guild.icon || ""
+			};
 			this.logger("warn", `[getGroupInfo] 获取群信息失败: ${err instanceof Error ? err.message : err}`);
 			return empty;
 		}
 	}
 	/**
 	* 获取群列表
+	*
+	* 官方没有 QQ 群列表接口。频道列表可用 `bot.super.guilds.getGuildList()` 获取，
+	* 但频道在 Karin 里属于 guild 场景，与 QQ 群不是同一类会话，因此不在此处混用。
 	*/
 	async getGroupList(_refresh) {
-		this.logger("warn", "[getGroupList] QQ Official Bot API 暂不支持获取群列表");
+		this.logger("warn", "[getGroupList] QQ Official Bot API 暂不支持获取群列表，频道列表请用 bot.super.guilds.getGuildList()");
 		return [];
 	}
 	/**
@@ -2891,16 +3859,46 @@ var AdapterQQBot = class extends AdapterBase {
 		this.logger("warn", "[setFriendApplyResult] QQ Official Bot API 暂不支持设置好友请求结果");
 	}
 	/**
-	* 设置申请加入群请求结果
+	* 审批入群申请。
+	*
+	* 走官方 `POST /v2/groups/{group_openid}/approval_join_request/{member_openid}`，
+	* 机器人需拥有群管理员身份。Karin 只透传 flag（`join_request_id`），群与申请人
+	* openid 由 `join-request-cache` 在收到申请事件时记录，因此仅支持审批本次运行
+	* 期间收到过的申请；历史申请请改用
+	* `bot.super.groups.getJoinRequestList()` + `bot.super.groups.approvalJoinRequest()`。
+	*
+	* @param requestId 申请 ID（Karin 请求事件的 flag）。
+	* @param isApprove 是否通过。
+	* @param denyReason 拒绝理由，仅拒绝时生效。
 	*/
-	async setGroupApplyResult(_requestId, _isApprove, _denyReason) {
-		this.logger("warn", "[setGroupApplyResult] QQ Official Bot API 暂不支持设置群申请结果");
+	async setGroupApplyResult(requestId, isApprove, denyReason) {
+		const cached = getJoinRequest(this, requestId);
+		if (!cached) {
+			this.logger("warn", `[setGroupApplyResult] 未找到入群申请索引，无法还原群/申请人 openid: ${requestId || "(empty)"}`);
+			return;
+		}
+		try {
+			await this.super.groups.approvalJoinRequest(cached.groupId, cached.memberId, {
+				op: isApprove ? "approve" : "decline",
+				join_request_id: requestId,
+				...isApprove ? {} : { reject_reason: denyReason }
+			});
+			removeJoinRequest(this, requestId);
+		} catch (err) {
+			this.logger("error", "[setGroupApplyResult] 审批入群申请失败:", err);
+		}
 	}
 	/**
-	* 设置邀请加入群请求结果
+	* 设置邀请加入群请求结果。
+	*
+	* 机器人被邀请入群与用户主动申请入群在官方侧是同一条 `GROUP_JOIN_REQUEST`
+	* 事件，审批走同一个接口，因此直接复用 {@link AdapterQQBot.setGroupApplyResult}。
+	*
+	* @param requestId 申请 ID（Karin 请求事件的 flag）。
+	* @param isApprove 是否通过。
 	*/
-	async setInvitedJoinGroupResult(_requestId, _isApprove) {
-		this.logger("warn", "[setInvitedJoinGroupResult] QQ Official Bot API 暂不支持设置邀请入群结果");
+	async setInvitedJoinGroupResult(requestId, isApprove) {
+		await this.setGroupApplyResult(requestId, isApprove);
 	}
 	/**
 	* 设置消息表情回应
@@ -3043,10 +4041,30 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 获取群被禁言用户列表
+	*
+	* 走官方 `GET /v2/groups/{group_openid}/restrict_chat_setting`，只返回仍在
+	* 禁言中的成员（不含已过期）。机器人需拥有群管理员身份，无权限或查询失败时
+	* 降级为空数组并告警。
+	*
+	* `muteTime` 为禁言到期时间的 Unix 秒，而非剩余时长；全员禁言规则不在该返回
+	* 结构内，需要时请用 `bot.super.groups.getGroupMuteSetting()` 读取 `global_rule`。
+	*
+	* @param _groupId 群 openid
 	*/
 	async getGroupMuteList(_groupId) {
-		this.logger("warn", "[getGroupMuteList] QQ Official Bot API 暂不支持获取群被禁言用户列表");
-		return [];
+		try {
+			return ((await this.super.groups.getGroupMuteSetting(_groupId)).members ?? []).map((member) => {
+				if (member.username) this.nicknameCache.set(member.member_openid, member.username);
+				const expireAt = member.mute_expire_at ? Date.parse(member.mute_expire_at) : NaN;
+				return {
+					userId: member.member_openid,
+					muteTime: Number.isNaN(expireAt) ? 0 : Math.floor(expireAt / 1e3)
+				};
+			});
+		} catch (err) {
+			this.logger("warn", `[getGroupMuteList] 获取群禁言列表失败（需机器人具备群管理员身份）: ${err instanceof Error ? err.message : err}`);
+			return [];
+		}
 	}
 	/**
 	* 戳一戳用户
@@ -3768,6 +4786,12 @@ const onGroupJoinRequest = (client, event) => {
 	const contact = karin$1.contactGroup(event.d.group_openid);
 	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
 	const time = Date.parse(event.d.apply_at);
+	/** 审批接口需要群 / 申请人 openid，而 Karin 只透传 join_request_id */
+	cacheJoinRequest(client, event.d.join_request_id, {
+		groupId: event.d.group_openid,
+		memberId: event.d.member_openid
+	});
+	if (event.d.username) client.nicknameCache.set(event.d.member_openid, event.d.username);
 	if (event.d.member_openid === client.selfId) createGroupInviteRequest({
 		bot: client,
 		time,
@@ -3813,12 +4837,16 @@ const onGroupJoinRequest = (client, event) => {
 * 取得互动事件真正用于 ACK 的平台 ID。
 *
 * WebSocket Dispatch 外层也有一个 `id`，形如 `INTERACTION_CREATE:uuid`；按钮 ACK
-* 接口需要的是事件体内的 `d.id`，也就是不带事件名前缀的 uuid。
+* 接口需要的是事件体内的 `d.id`，也就是不带事件名前缀的 uuid。缺少 `d.id` 时
+* 退回外层 `id`，并按官方要求剥掉 `INTERACTION_CREATE:` 前缀。
 *
 * @param ev QQBot 原始互动事件。
 * @returns 可传给 `/interactions/{interaction_id}` 的 ID。
 */
-const getInteractionId = (ev) => ev.d.id || ev.id;
+const getInteractionId = (ev) => {
+	if (ev.d.id) return ev.d.id;
+	return ev.id.replace(/^INTERACTION_CREATE:/, "");
+};
 /**
 * 构造按钮回调附加给 Karin 消息的元信息。
 *
@@ -4723,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;
@@ -4753,13 +5781,14 @@ const createBot = async (input) => {
 	return promise;
 };
 /**
-* 销毁 bot：注销 + 关 WS + 取消监听 + 停止 token 刷新
+* 销毁 bot：注销 + 关 WS + 取消监听 + 停止 token 刷新 + 清理入群申请索引
 */
 const destroyBot = (appId) => {
 	unregisterBot("selfId", appId);
 	stop(appId);
 	offAll(appId);
 	stopTokenRefresh(appId);
+	clearJoinRequests(appId);
 };
 bindHandlers(createBot, destroyBot);
 
@@ -4909,4 +5938,4 @@ const bootstrap = async () => {
 bootstrap();
 
 //#endregion
-export {  };
+export { Http, QQBotApi, RequestApi };