@karinjs/adapter-qqbot 3.0.7 → 3.1.0

package/dist/index.js

@@ -6,8 +6,8 @@ import karin, { AdapterBase, app, buttonHandle, common, createDirectMessage, cre
 import { URL } 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";
@@ -274,7 +274,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 +375,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,50 +435,195 @@ 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
@@ -492,7 +672,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 +681,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 +711,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 +731,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,7 +752,7 @@ 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 {}
 };
 
@@ -960,7 +1140,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 +1148,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 });
 		}
 	}
 	/**
@@ -1004,7 +1184,7 @@ 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;
 	}
@@ -1022,7 +1202,7 @@ 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);
+			await this.post(`/v2/${scene}s/${peer}/upload_part_finish`, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 			return;
 		} catch (err) {
 			if (shouldRetryPartFinishPersistently(err)) {
@@ -1048,7 +1228,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;
@@ -1070,7 +1250,7 @@ var MediaApi = class extends Http {
 		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);
+			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);
@@ -1099,7 +1279,7 @@ 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) => {
+		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)})`);
 			return throwError(err);
 		});
@@ -1141,14 +1321,14 @@ var InteractionApi = class extends Http {
 	* @param code 0 成功 / 1 操作失败 / 2 操作频繁 / 3 重复操作 / 4 无权限 / 5 仅管理员
 	*/
 	async ack(interactionId, code = 0) {
-		await this.put(`/interactions/${interactionId}`, { code }, void 0, INTERACTION_ACK_TIMEOUT);
+		await this.put(`/interactions/${interactionId}`, { code }, { timeout: INTERACTION_ACK_TIMEOUT });
 	}
 };
 
 //#endregion
 //#region src/core/api/meta.ts
 /**
-* 元信息接口：@me / dms / gateway
+* 元信息接口：@me / dms / gateway / 分享链接
 */
 var MetaApi = class extends Http {
 	/** 当前机器人详情 */
@@ -1166,6 +1346,17 @@ var MetaApi = class extends Http {
 	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
@@ -1202,18 +1393,329 @@ var GroupsApi = class extends Http {
 	}
 	/**
 	* 设置群成员禁言
+	*
+	* 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天。
+	*
 	* @param groupOpenid 群 openid
 	* @param memberOpenid 群成员 openid
 	* @param op 操作: add 增加禁言，update 更新禁言到期时间，del 解除禁言
 	* @param duration 禁言时间使用RFC3339 格式
 	*/
-	setGroupMetu(groupOpenid, memberOpenid, op, duration) {
+	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 操作类型与关联对象列表
+	*/
+	updatePanelTarget(panelId, body) {
+		return this.put(`/v2/panels/${panelId}/target`, body);
+	}
+};
+
+//#endregion
+//#region src/core/api/join-approval.ts
+/**
+* 入群自动审批策略接口
+*
+* 策略把「关联群 + 白名单 QQ 号码」绑在一起，命中白名单的入群申请会自动审批通过。
+* 规则仅在机器人拥有群管理员身份时才会实际运行；一个机器人最多 20 个策略。
+*/
+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}` : ""}`);
+	}
+	/**
+	* 创建入群自动审批策略
+	*
+	* `group_openids` 与 `group_ids` 二选一必填，同时传入或均未传入都会报错。
+	* @param body 策略配置
+	*/
+	createStrategy(body) {
+		return this.post("/v2/groups/join_approval_strategy", body);
+	}
+	/**
+	* 修改入群自动审批策略
+	*
+	* 可修改生效状态、失效时间、备注，或增删关联群；
+	* 增删关联群时的群标识形式必须与创建时一致。
+	* @param strategyId 策略 ID
+	* @param body 待修改的字段
+	*/
+	updateStrategy(strategyId, body) {
+		return this.patch(`/v2/groups/join_approval_strategy/${strategyId}`, body);
+	}
+	/**
+	* 删除入群自动审批策略
+	* @param strategyId 策略 ID
+	*/
+	deleteStrategy(strategyId) {
+		return this.delete(`/v2/groups/join_approval_strategy/${strategyId}`);
+	}
+	/**
+	* 执行入群自动审批策略
+	*
+	* 对策略关联的全部群发起全量扫描，命中白名单号码的入群申请自动审批通过。
+	* 异步执行，约 10 分钟完成。
+	* @param strategyId 策略 ID
+	*/
+	executeStrategy(strategyId) {
+		return this.post(`/v2/groups/join_approval_strategy/${strategyId}/execute`);
+	}
+	/**
+	* 修改入群自动审批策略的白名单号码
+	*
+	* 单次最多 10000 个，策略号码上限 10W。
+	* @param strategyId 策略 ID
+	* @param body 操作类型与号码列表
+	*/
+	updateWhitelistUsers(strategyId, body) {
+		return this.post(`/v2/groups/join_approval_strategy/${strategyId}/whitelist_users`, body);
+	}
 };
 
 //#endregion
@@ -1296,28 +1798,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);
 	}
 };
 
@@ -2414,11 +2944,79 @@ const responseTime = (timestamp) => {
 	return Date.now();
 };
 
+//#endregion
+//#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/base.ts
 const adapterConfigStore = /* @__PURE__ */ new WeakMap();
 /** HTTP(S) URL 可直接交给 QQ 平台拉取上传 */
 const HTTP_URL_RE = /^https?:\/\//i;
+/** 平台限制的最大禁言时长：30 天 */
+const MAX_GROUP_MUTE_SECONDS = 720 * 60 * 60;
 /**
 * QQ Official Bot 适配器
 *
@@ -2729,20 +3327,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 > MAX_GROUP_MUTE_SECONDS) {
+				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 +3403,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 +3431,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 +3516,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 +3698,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 +4443,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 +4494,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 消息的元信息。
 *
@@ -4448,14 +5133,13 @@ const QUICK_DISCONNECT_DELAY_MS = 6e4;
 * 获取网关地址：优先调 /gateway；失败 / 超时 / 限频 → 直接 fallback 到硬编码
 */
 const fetchGateway = async (cfg) => {
-	const apiUrl = "https://api.bot.qq.com";
 	const accessToken = getBotAccessToken(cfg.appId);
 	if (!accessToken) {
 		log("warn", `${cfg.appId}: 无 access_token，使用硬编码 WS`);
 		return "wss://api.bot.qq.com/websocket";
 	}
 	try {
-		const { data } = await axios.get(path.join(apiUrl, "gateway"), {
+		const { data } = await axios.get(`${QQAPIBASEURL}/gateway`, {
 			headers: {
 				Authorization: `QQBot ${accessToken}`,
 				"User-Agent": getUserAgent()
@@ -4754,13 +5438,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);
 
@@ -4910,4 +5595,4 @@ const bootstrap = async () => {
 bootstrap();
 
 //#endregion
-export {  };
+export { Http, QQBotApi, RequestApi };