@karinjs/adapter-qqbot 1.2.10 → 2.0.0

package/dist/index.js

@@ -0,0 +1,2847 @@
+import { a as pkg, c as getImageSize, f as log, l as handleUrl, n as config, p as basename, r as getConfig, s as fakeEvent, t as bindHandlers, u as random } from "./config-H7LrvlNU.js";
+import "./utils-DO4gEkVN.js";
+import { t as needQrOnboard } from "./onboard-BX8g8Wik.js";
+import { AdapterBase, app, buttonHandle, createDirectMessage, createFriendDecreaseNotice, createFriendIncreaseNotice, createFriendMessage, createGroupMemberAddNotice, createGroupMemberDelNotice, createGroupMessage, createGuildMessage, fileToUrl, karin, karinToQQBot, logger, registerBot, segment, unregisterBot } from "node-karin";
+import { URL } from "url";
+import lodash from "node-karin/lodash";
+import FormData from "form-data";
+import axios from "node-karin/axios";
+import EventEmitter from "node:events";
+import os from "node:os";
+import { WebSocket } from "node-karin/ws";
+import express from "node-karin/express";
+import nacl from "tweetnacl";
+
+//#region src/core/api/error.ts
+/**
+* OpenAPI 错误码映射表
+* 来源: api-v2/openapi/error/error.md
+*
+* 规则:
+* - 区间码 (如 301000~301099) 用范围匹配
+* - 精确码直接查表
+*/
+/** HTTP 状态码映射 */
+const httpStatusMap = {
+	200: "成功",
+	204: "成功，但是无包体，一般用于删除操作",
+	201: "异步操作成功，虽然说成功，但是会返回一个 error body，需要特殊处理",
+	202: "异步操作成功，虽然说成功，但是会返回一个 error body，需要特殊处理",
+	401: "认证失败",
+	404: "未找到 API",
+	405: "http method 不允许",
+	429: "频率限制",
+	500: "处理失败",
+	504: "处理失败"
+};
+/** 业务错误码(code)映射 */
+const errorCodeMap = {
+	10001: "UnknownAccount 账号异常",
+	10003: "UnknownChannel 子频道异常",
+	10004: "UnknownGuild 频道异常",
+	11281: "ErrorCheckAdminFailed 检查是否是管理员失败，系统错误，一般重试一次会好，最多只能重试一次",
+	11282: "ErrorCheckAdminNotPass 检查是否是管理员未通过，该接口需要管理员权限，但是用户在添加机器人的时候并未授予该权限，属于逻辑错误，可以提示用户进行授权",
+	11251: "ErrorWrongAppid 参数中的 appid 错误，开发者填的 token 错误，appid 无法识别",
+	11252: "ErrorCheckAppPrivilegeFailed 检查应用权限失败，系统错误，一般重试一次会好，最多只能重试一次",
+	11253: "ErrorCheckAppPrivilegeNotPass 检查应用权限不通过，该机器人应用未获得调用该接口的权限，需要向平台申请",
+	11254: "ErrorInterfaceForbidden 应用接口被封禁，该机器人虽然获得了该接口权限，但是被封禁了",
+	11261: "ErrorWrongAppid 参数中缺少 appid，同 11251",
+	11262: "ErrorCheckRobot 当前接口不支持使用机器人 Bot Token 调用",
+	11263: "ErrorCheckGuildAuth 检查频道权限失败，系统错误，一般重试一次会好，最多只能重试一次",
+	11264: "ErrorGuildAuthNotPass 检查小站权限未通过，管理员添加机器人的时候未授予该接口权限，属于逻辑错误，可提示用户进行授权，如果已经给予授权，请检查传递的 guild id 是否正确",
+	11265: "ErrorRobotHasBaned 机器人已经被封禁",
+	11241: "ErrorWrongToken 参数中缺少 token",
+	11242: "ErrorCheckTokenFailed 校验 token 失败，系统错误，一般重试一次会好，最多只能重试一次",
+	11243: "ErrorCheckTokenNotPass 校验 token 未通过，用户填充的 token 错误，需要开发者进行检查",
+	11273: "ErrorCheckUserAuth 检查用户权限失败，当前接口不支持使用 Bearer Token 调用",
+	11274: "ErrorUserAuthNotPass 检查用户权限未通过，用户 OAuth 授权时未给与该接口权限，可提示用户重新进行授权",
+	11275: "ErrorWrongAppid 无 appid，同 11251",
+	11301: "ErrorGetHTTPHeader HTTP Header 无效",
+	11302: "ErrorGetHeaderUIN HTTP Header 无效",
+	11303: "ErrorGetNick 获取昵称失败",
+	11304: "ErrorGetAvatar 获取头像失败",
+	11305: "ErrorGetGuildID 获取频道 ID 失败",
+	11306: "ErrorGetGuildInfo 获取频道信息失败",
+	12001: "ReplaceIDFailed 替换 id 失败",
+	12002: "RequestInvalid 请求体错误",
+	12003: "ResponseInvalid 回包错误",
+	20028: "ChannelHitWriteRateLimit 子频道消息触发限频",
+	50006: "CannotSendEmptyMessage 消息为空",
+	50035: "InvalidFormBody form-data 内容异常",
+	50037: "带有 markdown 消息只支持 markdown 或者 keyboard 组合",
+	50038: "非同频道同子频道",
+	50039: "获取消息失败",
+	50040: "消息模版类型错误",
+	50041: "markdown 有空值",
+	50042: "markdown 列表长达最大值",
+	50043: "guild_id 转换失败",
+	50045: "不能回复机器人自己产生的消息",
+	50046: "非 at 机器人消息",
+	50047: "非机器人产生的消息 或者 at 机器人消息",
+	50048: "message id 不能为空",
+	50049: "只能修改含有 keyboard 元素的消息",
+	50050: "修改消息时，keyboard 元素不能为空",
+	50051: "只能修改机器人自己发送的消息",
+	50053: "修改消息错误",
+	50054: "markdown 模版参数错误",
+	50055: "无效的 markdown content",
+	50056: "不允许发送 markdown content",
+	50057: "markdown 参数只支持原生语法或者模版二选一",
+	301e3: "参数错误",
+	301001: "查询频道信息错误",
+	301002: "查询子频道权限错误",
+	301003: "修改子频道权限错误",
+	301004: "私密子频道关联的人数到达上限",
+	301005: "调用 Rpc 服务失败",
+	301006: "非群成员没有查询权限",
+	301007: "参数超过数量限制",
+	302e3: "参数错误",
+	302001: "查询频道信息错误",
+	302002: "查询日程列表失败",
+	302003: "查询日程失败",
+	302004: "修改日程失败",
+	302005: "删除日程失败",
+	302006: "创建日程失败",
+	302007: "获取创建者信息失败",
+	302008: "子频道 ID 不能为空",
+	302009: "频道系统错误，请联系客服",
+	302010: "暂无修改日程权限",
+	302011: "日程活动已被删除",
+	302012: "每天只能创建 10 个日程，明天再来吧！",
+	302013: "创建日程触发安全打击",
+	302014: "日程持续时间超过 7 天，请重新选择",
+	302015: "开始时间不能早于当前时间",
+	302016: "结束时间不能早于开始时间",
+	302017: "Schedule 对象为空",
+	302018: "参数类型转换失败",
+	302019: "调用下游失败，请联系客服",
+	302020: "日程内容违规、账号违规",
+	302021: "频道内当日新增活动达上限",
+	302022: "不能绑定非当前频道的子频道",
+	302023: "开始时跳转不可绑定日程子频道",
+	302024: "绑定的子频道不存在",
+	304003: "URL_NOT_ALLOWED url 未报备",
+	304004: "ARK_NOT_ALLOWED 没有发 ark 消息权限",
+	304005: "EMBED_LIMIT embed 长度超限",
+	304006: "SERVER_CONFIG 后台配置错误",
+	304007: "GET_GUILD 查询频道异常",
+	304008: "GET_BOT 查询机器人异常",
+	304009: "GET_CHENNAL 查询子频道异常",
+	304010: "CHANGE_IMAGE_URL 图片转存错误",
+	304011: "NO_TEMPLATE 模板不存在",
+	304012: "GET_TEMPLATE 取模板错误",
+	304014: "TEMPLATE_PRIVILEGE 没有模板权限",
+	304016: "SEND_ERROR 发消息错误",
+	304017: "UPLOAD_IMAGE 图片上传错误",
+	304018: "SESSION_NOT_EXIST 机器人没连上 gateway",
+	304019: "AT_EVERYONE_TIMES @全体成员次数超限",
+	304020: "FILE_SIZE 文件大小超限",
+	304021: "GET_FILE 下载文件错误",
+	304022: "PUSH_TIME 推送消息时间限制",
+	304023: "PUSH_MSG_ASYNC_OK 推送消息异步调用成功，等待人工审核",
+	304024: "REPLY_MSG_ASYNC_OK 回复消息异步调用成功，等待人工审核",
+	304025: "BEAT 消息被打击",
+	304026: "MSG_ID 回复的消息 id 错误",
+	304027: "MSG_EXPIRE 回复的消息过期",
+	304028: "MSG_PROTECT 非 At 当前用户的消息不允许回复",
+	304029: "CORPUS_ERROR 调语料服务错误",
+	304030: "CORPUS_NOT_MATCH 语料不匹配",
+	304031: "私信已关闭",
+	304032: "私信不存在",
+	304033: "拉私信错误",
+	304034: "不是私信成员",
+	304035: "推送消息超过子频道数量限制",
+	304036: "没有 markdown 模板的权限",
+	304037: "没有发消息按钮组件的权限",
+	304038: "消息按钮组件不存在",
+	304039: "消息按钮组件解析错误",
+	304040: "消息按钮组件消息内容错误",
+	304044: "取消息设置错误",
+	304045: "子频道主动消息数限频",
+	304046: "不允许在此子频道发主动消息",
+	304047: "主动消息推送超过限制的子频道数",
+	304048: "不允许在此频道发主动消息",
+	304049: "私信主动消息数限频",
+	304050: "私信主动消息总量限频",
+	304051: "消息设置引导请求构造错误",
+	304052: "发消息设置引导超频",
+	306001: "param invalid 撤回消息参数错误",
+	306002: "msgid error 消息 id 错误",
+	306003: "fail to get message 获取消息错误（可重试）",
+	306004: "no permission to delete message 没有撤回此消息的权限",
+	306005: "retract message error 消息撤回失败（可重试）",
+	306006: "fail to get channel 获取子频道失败（可重试）",
+	501001: "参数校验失败",
+	501002: "创建子频道公告失败（可重试）",
+	501003: "删除子频道公告失败（可重试）",
+	501004: "获取频道信息失败（可重试）",
+	501005: "MessageID 错误",
+	501006: "创建频道全局公告失败（可重试）",
+	501007: "删除频道全局公告失败（可重试）",
+	501008: "MessageID 不存在",
+	501009: "MessageID 解析失败",
+	501010: "此条消息非子频道内消息",
+	501011: "创建精华消息失败（可重试）",
+	501012: "删除精华消息失败（可重试）",
+	501013: "精华消息超过最大数量",
+	501014: "安全打击",
+	501015: "此消息不允许设置",
+	501016: "频道公告子频道推荐超过最大数量",
+	501017: "非频道主或管理员",
+	501018: "推荐子频道 ID 无效",
+	501019: "公告类型错误",
+	501020: "创建推荐子频道类型频道公告失败",
+	502001: "频道 id 无效",
+	502002: "频道 id 为空",
+	502003: "用户 id 无效",
+	502004: "用户 id 为空",
+	502005: "timestamp 不合法",
+	502006: "timestamp 无效",
+	502007: "参数转换错误",
+	502008: "rpc 调用失败",
+	502009: "安全打击",
+	502010: "请求头错误",
+	503001: "频道 id 无效",
+	503002: "频道 id 为空",
+	503003: "获取子频道信息失败",
+	503004: "超出发布帖子的频次限制",
+	503005: "帖子标题为空",
+	503006: "帖子内容为空",
+	503007: "帖子 ID 为空",
+	503008: "获取 X-Uin 失败",
+	503009: "帖子 ID 无效或不合法",
+	503010: "通过 Uin 获取 TinyID 失败",
+	503011: "帖子 ID 里面的时间戳无效或不合法",
+	503012: "帖子不存在或已删除",
+	503013: "服务器内部错误",
+	503014: "帖子 JSON 内容解析失败",
+	503015: "帖子内容转换失败",
+	503016: "链接数量超过限制",
+	503017: "字数超过限制",
+	503018: "图片数量超过限制",
+	503019: "视频数量超过限制",
+	503020: "标题长度超过限制",
+	504001: "请求参数无效错误",
+	504002: "获取 HTTP 头失败",
+	504003: "获取 BOT UIN 错误",
+	504004: "获取消息频率设置信息错误",
+	610001: "获取频道 ID 失败",
+	610002: "获取 HTTP 头失败",
+	610003: "获取机器人号码失败",
+	610004: "获取机器人角色失败",
+	610005: "获取机器人角色内部错误",
+	610006: "拉取机器人权限列表失败",
+	610007: "机器人不在频道内",
+	610008: "无效参数",
+	610009: "获取 API 接口详情失败",
+	610010: "API 接口已授权",
+	610011: "获取机器人信息失败",
+	610012: "限频失败",
+	610013: "已限频",
+	610014: "api 授权链接发送失败",
+	620001: "表情表态无效参数",
+	620002: "已经达到表情反应的类型数量上限",
+	620003: "已经设置过该表情表态",
+	620004: "没有设置过该表情表态",
+	620005: "没有权限设置表情表态",
+	620006: "操作限频",
+	620007: "表情表态操作失败，请重试",
+	630001: "互动回调数据更新无效参数",
+	630002: "互动回调数据更新获取 AppID 失败",
+	630003: "互动回调数据 AppID 不匹配",
+	630004: "互动回调数据更新内部存储错误",
+	630005: "互动回调数据更新内部存储读取错误",
+	630006: "互动回调数据更新读取请求 AppID 失败",
+	630007: "互动回调数据太大",
+	1100100: "安全打击：消息被限频",
+	1100101: "安全打击：内容涉及敏感，请返回修改",
+	1100102: "安全打击：抱歉，暂未获得新功能体验资格",
+	1100103: "安全打击",
+	1100104: "安全打击：该群已失效或当前群已不存在",
+	1100300: "系统内部错误",
+	1100301: "调用方不是群成员",
+	1100302: "获取指定频道名称失败",
+	1100303: "主页频道非管理员不允许发消息",
+	1100304: "@次数鉴权失败",
+	1100305: "TinyId 转换 Uin 失败",
+	1100306: "非私有频道成员",
+	1100307: "非白名单应用子频道",
+	1100308: "触发频道内限频",
+	1100499: "其他错误",
+	3300006: "安全打击"
+};
+const rangeDefs = [
+	{
+		min: 301e3,
+		max: 301099,
+		message: "子频道权限错误"
+	},
+	{
+		min: 501e3,
+		max: 501999,
+		message: "公告错误"
+	},
+	{
+		min: 502e3,
+		max: 502099,
+		message: "禁言相关错误"
+	},
+	{
+		min: 504e3,
+		max: 504999,
+		message: "消息频率相关错误"
+	},
+	{
+		min: 61e4,
+		max: 619999,
+		message: "频道权限错误"
+	},
+	{
+		min: 620001,
+		max: 629999,
+		message: "表情表态错误"
+	},
+	{
+		min: 630001,
+		max: 639999,
+		message: "互动回调数据更新错误"
+	},
+	{
+		min: 1e6,
+		max: 2999999,
+		message: "发消息错误"
+	},
+	{
+		min: 3e6,
+		max: 3999999,
+		message: "编辑消息错误"
+	}
+];
+/**
+* 根据 code 查找对应的中文错误描述
+* @param code - 业务错误码
+* @returns 中文错误描述，未找到则返回 undefined
+*/
+const getErrorMessage = (code) => {
+	const exact = errorCodeMap[code];
+	if (exact) return exact;
+	for (const range of rangeDefs) if (code >= range.min && code <= range.max) return `${range.message} (code: ${code})`;
+};
+/**
+* 格式化 OpenAPI 错误为可读字符串
+* @param status - HTTP 状态码
+* @param code - 业务错误码
+* @param message - 原始消息
+* @returns 格式化后的错误字符串
+*/
+const formatOpenAPIError = (status, code, message) => {
+	const parts = [];
+	const statusText = httpStatusMap[status];
+	if (statusText) parts.push(`[HTTP ${status}] ${statusText}`);
+	else parts.push(`[HTTP ${status}]`);
+	if (code !== void 0) {
+		const codeText = getErrorMessage(code);
+		if (codeText) parts.push(`[Code ${code}] ${codeText}`);
+		else parts.push(`[Code ${code}]`);
+	}
+	if (message) parts.push(message);
+	return parts.join(" | ");
+};
+
+//#endregion
+//#region src/core/api/http.ts
+/**
+* 包装 axios 错误为可读多行 message
+* 如果响应中包含 QQ 官方错误码(code)，会自动映射为中文描述
+*/
+const formatError = (path, options, err) => {
+	if (axios.isAxiosError(err)) {
+		const response = err.response;
+		const status = response?.status ?? 0;
+		const data = response?.data;
+		const code = typeof data?.code === "number" ? data.code : void 0;
+		const msg = typeof data?.message === "string" ? data.message : void 0;
+		const lines = [];
+		lines.push("[axios] 请求失败");
+		lines.push(`请求路径: ${path}`);
+		lines.push(`请求数据: ${lodash.truncate(JSON.stringify(options), { length: 500 })}`);
+		if (code !== void 0 || status > 0) lines.push(`错误详情: ${formatOpenAPIError(status, code, msg)}`);
+		lines.push(`响应数据: ${JSON.stringify(data)}`);
+		return new Error(lines.join("\n"));
+	}
+	if (err instanceof Error) return err;
+	return new Error(typeof err === "string" ? err : JSON.stringify(err));
+};
+/**
+* Http 基础类，子模块继承此类共享 axios 实例与错误格式化
+*/
+var Http = class {
+	axios;
+	constructor(axios) {
+		this.axios = axios;
+	}
+	async get(path) {
+		try {
+			const { data } = await this.axios.get(path);
+			return data;
+		} catch (err) {
+			throw formatError(path, void 0, err);
+		}
+	}
+	async post(path, body = {}, headers) {
+		try {
+			const { data } = await this.axios.post(path, body, { headers });
+			return data;
+		} catch (err) {
+			throw formatError(path, body, err);
+		}
+	}
+	async put(path, body = {}, headers) {
+		try {
+			const { data } = await this.axios.put(path, body, { headers });
+			return data;
+		} catch (err) {
+			throw formatError(path, body, err);
+		}
+	}
+	async delete(path) {
+		try {
+			const { data } = await this.axios.delete(path);
+			return data;
+		} catch (err) {
+			throw formatError(path, void 0, err);
+		}
+	}
+};
+
+//#endregion
+//#region src/core/api/messages.ts
+/**
+* 消息发送 + 撤回
+*/
+var MessagesApi = class extends Http {
+	/** 单聊消息 */
+	sendFriendMsg(openid, body) {
+		return this.post(`/v2/users/${openid}/messages`, body);
+	}
+	/** 群聊消息 */
+	sendGroupMsg(groupOpenid, body) {
+		return this.post(`/v2/groups/${groupOpenid}/messages`, body);
+	}
+	/** 文字子频道消息 */
+	sendChannelMsg(channelId, body) {
+		const headers = body instanceof FormData ? body.getHeaders() : void 0;
+		return this.post(`/channels/${channelId}/messages`, body, headers);
+	}
+	async sendDmsMsg(a, b, c) {
+		if (typeof b === "string") {
+			const dms = await this.post("/users/@me/dms", {
+				recipient_id: a,
+				source_guild_id: b
+			});
+			const headers = c instanceof FormData ? c.getHeaders() : void 0;
+			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);
+	}
+	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}`;
+		await this.delete(path);
+		return true;
+	}
+};
+
+//#endregion
+//#region src/core/api/media.ts
+const FILE_TYPE = {
+	image: 1,
+	video: 2,
+	record: 3,
+	file: 4
+};
+/**
+* 富媒体上传
+*/
+var MediaApi = class extends Http {
+	/**
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param type 文件类型
+	* @param source 必须是 http url 或 base64 字符串
+	* @param srvSendMsg 上传后是否由服务端直接发送
+	*/
+	upload(scene, peer, type, source, srvSendMsg = false) {
+		const body = {
+			file_type: FILE_TYPE[type],
+			srv_send_msg: srvSendMsg
+		};
+		if (source.startsWith("http")) body.url = source;
+		else body.file_data = source.replace(/^data:[\w/+-]+;base64,|^base64:\/\//, "");
+		return this.post(`/v2/${scene}s/${peer}/files`, body);
+	}
+};
+
+//#endregion
+//#region src/core/api/interaction.ts
+/**
+* INTERACTION_CREATE 回应
+*/
+var InteractionApi = class extends Http {
+	/**
+	* @param interactionId INTERACTION_CREATE 事件中的 id
+	* @param code 0 成功 / 1 操作失败 / 2 操作频繁 / 3 重复操作 / 4 无权限 / 5 仅管理员
+	*/
+	async ack(interactionId, code = 0) {
+		await this.put(`/interactions/${interactionId}`, { code });
+	}
+};
+
+//#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");
+	}
+};
+
+//#endregion
+//#region src/core/api/builders.ts
+/**
+* 构造 QQ 单聊 / 群聊请求体
+*/
+const buildQQMsg = {
+	text(content) {
+		return {
+			msg_type: 0,
+			content
+		};
+	},
+	markdown(markdown, keyboard) {
+		return {
+			msg_type: 2,
+			markdown,
+			keyboard
+		};
+	},
+	ark(ark) {
+		return {
+			msg_type: 3,
+			ark
+		};
+	},
+	/** msg_type=7 时 content 字段必填，传一个空格占位 */
+	media(fileInfo) {
+		return {
+			msg_type: 7,
+			media: { file_info: fileInfo },
+			content: " "
+		};
+	}
+};
+/**
+* 构造频道请求体
+*/
+const buildGuildMsg = {
+	text(content, image) {
+		return {
+			type: "text",
+			content,
+			image
+		};
+	},
+	image(image) {
+		return {
+			type: "image",
+			image
+		};
+	},
+	embed(embed) {
+		return {
+			type: "embed",
+			embed
+		};
+	},
+	ark(ark) {
+		return {
+			type: "ark",
+			ark
+		};
+	},
+	markdown(markdown, keyboard) {
+		return {
+			type: "markdown",
+			markdown,
+			keyboard
+		};
+	}
+};
+
+//#endregion
+//#region src/core/api/index.ts
+/**
+* QQBot 官方 API 门面
+*
+* 子模块按职能拆分：
+* - messages：发送 / 撤回
+* - media：富媒体上传
+* - interaction：按钮回调 ack
+* - meta：@me / dms / gateway
+*
+* 请求体构造器 {@link buildQQMsg} / {@link buildGuildMsg} 独立导出，避免与 HTTP 调用耦合
+*/
+var QQBotApi = class {
+	axios;
+	messages;
+	media;
+	interaction;
+	meta;
+	/** 请求体构造器（静态便利） */
+	qq = buildQQMsg;
+	guild = buildGuildMsg;
+	constructor(axios) {
+		this.axios = axios;
+		this.messages = new MessagesApi(axios);
+		this.media = new MediaApi(axios);
+		this.interaction = new InteractionApi(axios);
+		this.meta = new MetaApi(axios);
+	}
+};
+
+//#endregion
+//#region src/core/internal/axios.ts
+const tokens = /* @__PURE__ */ new Map();
+/**
+* 拉取 access_token 并安排下一次刷新
+* - 提前 50s 刷新，防止边界过期
+* - 同一 appId 旧定时器会被清理，避免并发刷新链
+*/
+const getAccessToken = async (url, appId, secret) => {
+	let res;
+	try {
+		res = await axios.post(url, {
+			appId: String(appId),
+			clientSecret: secret
+		});
+	} catch (err) {
+		if (axios.isAxiosError(err)) {
+			const response = err.response;
+			const status = response?.status ?? 0;
+			const data = response?.data;
+			log("error", `[${appId}] 获取 access_token 失败 | ${formatOpenAPIError(status, typeof data?.code === "number" ? data.code : void 0, typeof data?.message === "string" ? data.message : void 0)}`);
+		} else log("error", `[${appId}] 获取 access_token 失败:`, err);
+		throw err;
+	}
+	const accessToken = res.data?.access_token;
+	const expiresIn = Number(res.data?.expires_in);
+	if (!accessToken || !expiresIn || Number.isNaN(expiresIn)) throw new Error(`获取 access_token 失败: ${JSON.stringify(res.data)}`);
+	const prev = tokens.get(appId);
+	if (prev?.refreshTimer) clearTimeout(prev.refreshTimer);
+	const state = { accessToken };
+	tokens.set(appId, state);
+	const delay = Math.max(5e3, expiresIn * 1e3 - 5e4);
+	state.refreshTimer = setTimeout(() => {
+		getAccessToken(url, appId, secret).catch(() => {});
+	}, delay);
+	return {
+		accessToken,
+		expiresIn
+	};
+};
+/**
+* 读取已缓存的 access_token
+*/
+const getBotAccessToken = (appId) => {
+	return tokens.get(appId)?.accessToken;
+};
+/**
+* 停止某个 bot 的 token 刷新（销毁 bot 时调用）
+*/
+const stopTokenRefresh = (appId) => {
+	const state = tokens.get(appId);
+	if (!state) return;
+	if (state.refreshTimer) clearTimeout(state.refreshTimer);
+	tokens.delete(appId);
+};
+/**
+* 创建 axios 实例，自动从 tokens map 取最新 access_token
+*/
+const createAxiosInstance = (baseURL, appId) => {
+	const instance = axios.create({
+		baseURL,
+		headers: { "Content-Type": "application/json" },
+		timeout: 5500
+	});
+	instance.interceptors.request.use((config) => {
+		const token = tokens.get(appId)?.accessToken;
+		if (token) config.headers.Authorization = `QQBot ${token}`;
+		return config;
+	});
+	return instance;
+};
+
+//#endregion
+//#region src/core/adapter/grouping.ts
+/**
+* 创建空容器
+*/
+const createGrouping = () => ({
+	text: [],
+	qqImages: [],
+	guildImageUrls: [],
+	guildImageFiles: [],
+	buttons: [],
+	keyboards: [],
+	markdowns: [],
+	media: [],
+	reply: { messageId: "" },
+	pasmsg: {
+		type: "msg",
+		id: "",
+		seq: random(1, 9999999)
+	},
+	faces: []
+});
+/**
+* 将 karin elements 归类到容器
+*/
+const groupElements = (scene, elements) => {
+	const g = createGrouping();
+	const isQQ = scene === "group" || scene === "friend";
+	for (const v of elements) switch (v.type) {
+		case "text":
+			g.text.push(v.text);
+			break;
+		case "image":
+			if (isQQ) g.qqImages.push(v.file);
+			else v.file.startsWith("http") ? g.guildImageUrls.push(v.file) : g.guildImageFiles.push(v.file);
+			break;
+		case "at":
+			if (scene === "friend") break;
+			if (v.targetId === "all") g.text.push("<qqbot-at-everyone />");
+			else g.text.push(`<qqbot-at-user id="${v.targetId}" />`);
+			break;
+		case "face":
+			if (!isQQ) {
+				g.text.push(`<emoji:${v.id}>`);
+				g.faces.push(Number(v.id));
+			}
+			break;
+		case "reply":
+			g.reply.messageId = v.messageId;
+			break;
+		case "pasmsg":
+			if (v.source === "event") g.pasmsg.type = "event";
+			g.pasmsg.id = v.id;
+			break;
+		case "button":
+			g.buttons.push(v);
+			break;
+		case "keyboard":
+			g.keyboards.push(v);
+			break;
+		case "markdown":
+			g.markdowns.push(v);
+			break;
+		case "video":
+			g.media.push({
+				kind: "video",
+				source: v.file
+			});
+			break;
+		case "record":
+			g.media.push({
+				kind: "record",
+				source: v.file
+			});
+			break;
+		case "file":
+			g.media.push({
+				kind: "file",
+				source: v.file
+			});
+			break;
+		default: break;
+	}
+	return g;
+};
+
+//#endregion
+//#region src/core/adapter/text-to-md.ts
+const MAX_BUTTONS = 5;
+/**
+* 提取文本中的 URL，将其替换为 `[按钮 N]` 占位文本并返回 button 列表
+*
+* @param text 文本
+* @param friendly 是否为单聊（true 时清除残余的 at 标签）
+*/
+const extractUrlButtons = (text, friendly = false) => {
+	let str = text.replace(/@everyone/g, "everyone").replace(/\n/g, "\r");
+	if (friendly) str = str.replace(/<qqbot-at-user id="[^"]+"\s*\/?>/g, "").replace(/<@!\d+>/g, "");
+	const urls = handleUrl(str);
+	if (urls.length === 0) return {
+		text: str,
+		buttons: []
+	};
+	const buttons = [];
+	urls.forEach((url, i) => {
+		str = str.replace(new RegExp(url, "g"), `[请点击 按钮${i} 查看]`);
+		buttons.push(segment.button({
+			text: `${i}. ${url}`,
+			link: url
+		}));
+	});
+	return {
+		text: str,
+		buttons: buttons.slice(0, MAX_BUTTONS)
+	};
+};
+/**
+* 将图片列表合并到一段 markdown 文本内（每张图占一行）
+*/
+const imagesToMarkdown = async (urls) => {
+	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})`;
+	}));
+};
+
+//#endregion
+//#region src/core/adapter/pipeline-qq.ts
+/** 群聊 event_id 白名单 */
+const GROUP_EVENT_WHITELIST = new Set([
+	"INTERACTION_CREATE",
+	"GROUP_ADD_ROBOT",
+	"GROUP_MSG_RECEIVE"
+]);
+/** 单聊 event_id 白名单 */
+const FRIEND_EVENT_WHITELIST = new Set([
+	"INTERACTION_CREATE",
+	"C2C_MSG_RECEIVE",
+	"FRIEND_ADD"
+]);
+/**
+* 处理 QQ 场景（单聊 + 群聊）的发送
+*/
+const sendQQ = async (ctx, contact, elements) => {
+	const target = contact.scene === "friend" ? "user" : "group";
+	const grouping = groupElements(contact.scene, elements);
+	if (ctx.cfg.keyboard.enable && grouping.text.length) {
+		const { text, buttons } = extractUrlButtons(grouping.text.join(""), contact.scene === "friend");
+		grouping.text = [text];
+		grouping.buttons.push(...buttons);
+	}
+	/**
+	* 永远走 markdown 通道：
+	* text / at / image 通过 markdown content 渲染（at 用内嵌标签）；
+	* 视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 并发补发。
+	* Markdown / Keyboard 已全量开放，无需再走老的 msg_type=0 文本通道。
+	*/
+	return sendQQMarkdown(ctx, contact, grouping, target);
+};
+/**
+* Markdown 通道：合成一条 msg_type=2 + 可选 keyboard
+*/
+const sendQQMarkdown = async (ctx, contact, grouping, target) => {
+	const items = [];
+	const lines = [];
+	if (grouping.text.length) lines.push(grouping.text.join(""));
+	if (grouping.qqImages.length) {
+		const urlImages = [];
+		for (const file of grouping.qqImages) if (file.startsWith("http")) urlImages.push(file);
+		else {
+			const { url } = await fileToUrl("image", file, "image.jpg");
+			urlImages.push(url);
+		}
+		const mdImages = await imagesToMarkdown(urlImages);
+		lines.push(...mdImages);
+	}
+	if (grouping.markdowns.length) grouping.markdowns.forEach((m) => lines.push(m.markdown));
+	if (lines.length || grouping.buttons.length || grouping.keyboards.length) {
+		const content = lines.join("\n");
+		const keyboard = buildKeyboard$1(grouping);
+		items.push(ctx.super.qq.markdown({ content }, keyboard));
+	}
+	for (const m of grouping.media) {
+		let url = m.source;
+		if (!url.startsWith("http")) {
+			const ext = m.kind === "record" ? "mp3" : m.kind === "video" ? "mp4" : "bin";
+			url = (await fileToUrl(m.kind, url, `${m.kind}.${ext}`)).url;
+		}
+		const res = await ctx.super.media.upload(target, contact.peer, m.kind, url, false);
+		items.push(ctx.super.qq.media(res.file_info));
+	}
+	if (!items.length) items.push(ctx.super.qq.text("不支持发送的消息类型"));
+	return flushQQ(ctx, contact, grouping, items);
+};
+/**
+* 构造 keyboard 字段（buttons + keyboards 合并）
+*/
+const buildKeyboard$1 = (grouping) => {
+	const rows = [];
+	grouping.buttons.forEach((b) => rows.push(...karinToQQBot(b)));
+	grouping.keyboards.forEach((k) => rows.push(...karinToQQBot(k)));
+	if (!rows.length) return void 0;
+	return { content: { rows } };
+};
+/**
+* 逐条发送 + 被动消息附加 + 引用回复
+*/
+const flushQQ = async (ctx, contact, grouping, items) => {
+	const result = ctx.initSendMsgResults();
+	const passive = buildPassiveQQ(contact.scene, grouping);
+	const send = contact.scene === "friend" ? (peer, item) => ctx.super.messages.sendFriendMsg(peer, item) : (peer, item) => ctx.super.messages.sendGroupMsg(peer, item);
+	let replyHandled = false;
+	for (const item of items) {
+		passive(item);
+		if (!replyHandled && grouping.reply.messageId) {
+			item.message_reference = { message_id: grouping.reply.messageId };
+			replyHandled = true;
+		}
+		const res = await send(contact.peer, item);
+		result.rawData.push(res);
+	}
+	return ctx.handleResponse(result);
+};
+/**
+* 构造被动消息附加器（含白名单校验）
+*/
+const buildPassiveQQ = (scene, grouping) => {
+	if (!grouping.pasmsg.id) return (_item) => void 0;
+	const whitelist = scene === "friend" ? FRIEND_EVENT_WHITELIST : GROUP_EVENT_WHITELIST;
+	if (grouping.pasmsg.type === "event") {
+		const eventName = grouping.pasmsg.id.split(":")[0];
+		if (eventName && !whitelist.has(eventName)) {}
+		return (item) => {
+			grouping.pasmsg.seq++;
+			item.msg_seq = grouping.pasmsg.seq;
+			item.event_id = grouping.pasmsg.id;
+		};
+	}
+	return (item) => {
+		grouping.pasmsg.seq++;
+		item.msg_seq = grouping.pasmsg.seq;
+		item.msg_id = grouping.pasmsg.id;
+	};
+};
+
+//#endregion
+//#region src/core/adapter/pipeline-guild.ts
+/**
+* 处理频道场景（子频道 + 私信）的发送
+*
+* 永远走 markdown 通道（msg_type=2），文本 / at / 图片均通过 markdown
+* 渲染。Markdown / Keyboard 已全量开放，老的 type=text/image 通道不再使用。
+*/
+const sendGuild = async (ctx, contact, elements) => {
+	const grouping = groupElements(contact.scene, elements);
+	if (ctx.cfg.keyboard.enable && grouping.text.length) {
+		const { text, buttons } = extractUrlButtons(grouping.text.join(""), false);
+		grouping.text = [text];
+		grouping.buttons.push(...buttons);
+	}
+	return sendGuildMarkdown(ctx, contact, grouping);
+};
+/**
+* Markdown 通道
+*/
+const sendGuildMarkdown = async (ctx, contact, grouping) => {
+	const items = [];
+	const lines = [];
+	if (grouping.text.length) lines.push(grouping.text.join(""));
+	const allImages = [...grouping.guildImageUrls];
+	for (const file of grouping.guildImageFiles) {
+		const { url } = await fileToUrl("image", file, "image.jpg");
+		allImages.push(url);
+	}
+	if (allImages.length) {
+		const mdImages = await imagesToMarkdown(allImages);
+		lines.push(...mdImages);
+	}
+	grouping.markdowns.forEach((m) => lines.push(m.markdown));
+	if (lines.length || grouping.buttons.length || grouping.keyboards.length) {
+		const keyboard = buildKeyboard(grouping);
+		items.push(ctx.super.guild.markdown({ content: lines.join("\n") }, keyboard));
+	}
+	if (!items.length) items.push(ctx.super.guild.text("不支持发送的消息类型"));
+	return flushGuild(ctx, contact, grouping, items);
+};
+const buildKeyboard = (grouping) => {
+	const rows = [];
+	grouping.buttons.forEach((b) => rows.push(...karinToQQBot(b)));
+	grouping.keyboards.forEach((k) => rows.push(...karinToQQBot(k)));
+	if (!rows.length) return void 0;
+	return { content: { rows } };
+};
+const flushGuild = async (ctx, contact, grouping, items) => {
+	const result = ctx.initSendMsgResults();
+	const passive = buildPassiveGuild(grouping);
+	const send = contact.scene === "guild" ? (peer, subPeer, item) => ctx.super.messages.sendChannelMsg(subPeer, item) : (peer, _subPeer, item) => ctx.super.messages.sendDmsMsg(peer, item);
+	let replyHandled = false;
+	for (const item of items) {
+		passive(item);
+		if (!replyHandled && grouping.reply.messageId && !(item instanceof FormData)) {
+			item.message_reference = { message_id: grouping.reply.messageId };
+			replyHandled = true;
+		}
+		const res = await send(contact.peer, contact.subPeer, item);
+		result.rawData.push(res);
+	}
+	return ctx.handleResponse(result);
+};
+const buildPassiveGuild = (grouping) => {
+	if (!grouping.pasmsg.id) return (_item) => void 0;
+	if (grouping.pasmsg.type === "event") return (item) => {
+		if (item instanceof FormData) item.append("event_id", grouping.pasmsg.id);
+		else item.event_id = grouping.pasmsg.id;
+	};
+	return (item) => {
+		if (item instanceof FormData) item.append("msg_id", grouping.pasmsg.id);
+		else item.msg_id = grouping.pasmsg.id;
+	};
+};
+
+//#endregion
+//#region src/core/adapter/base.ts
+/**
+* QQ Official Bot 适配器
+*
+* 全场景统一走 msg_type=2 Markdown 通道（详见 pipeline-qq / pipeline-guild）。
+* 视频 / 语音 / 文件由 pipeline 内部以 msg_type=7 紧随主消息补发。
+*/
+var AdapterQQBot = class extends AdapterBase {
+	/** 与官方 API 交互 */
+	super;
+	/** 当前 bot 配置 */
+	cfg;
+	/** openId / member_openid -> 昵称 缓存 */
+	nicknameCache = /* @__PURE__ */ new Map();
+	constructor(cfg, api) {
+		super();
+		this.cfg = cfg;
+		this.super = api;
+		this.adapter.name = "QQ Official Bot";
+		this.adapter.protocol = "qqbot";
+		this.adapter.platform = "qq";
+		this.adapter.standard = "other";
+	}
+	logger(level, ...args) {
+		logger.bot(level, this.selfId, ...args);
+	}
+	/**
+	* 主消息回复入口（karin 调用）
+	*/
+	async srcReply(e, elements) {
+		const extra = this.cfg.keyboard.enable ? await buttonHandle(e.msg, { e }) : [];
+		return this.sendMsg(e.contact, [...elements, ...extra]);
+	}
+	/**
+	* 发送消息
+	*/
+	async sendMsg(contact, elements, _retryCount) {
+		if (contact.scene === "direct" || contact.scene === "guild") return sendGuild(this, contact, elements);
+		if (contact.scene === "group" || contact.scene === "friend") return sendQQ(this, contact, elements);
+		throw new Error(`不支持的消息场景: ${contact.scene}`);
+	}
+	/**
+	* 撤回消息
+	*/
+	async recallMsg(contact, messageId) {
+		try {
+			if (contact.scene === "friend") await this.super.messages.recall("user", contact.peer, messageId);
+			else if (contact.scene === "group") await this.super.messages.recall("group", contact.peer, messageId);
+			else if (contact.scene === "direct") await this.super.messages.recall("dms", contact.peer, messageId);
+			else if (contact.scene === "guild") await this.super.messages.recall("channels", contact.peer, messageId);
+		} catch (err) {
+			logger.error("撤回消息失败:", err);
+		}
+	}
+	/**
+	* 构造空发送结果，pipeline 内填充 rawData
+	*/
+	initSendMsgResults() {
+		return {
+			messageId: "",
+			message_id: "",
+			time: 0,
+			messageTime: 0,
+			rawData: []
+		};
+	}
+	/**
+	* 将 rawData[0].id / timestamp 同步到顶层字段
+	*/
+	handleResponse(data) {
+		const first = data.rawData[0];
+		if (!first) return data;
+		const { id, timestamp } = first;
+		data.messageId = id;
+		data.message_id = id;
+		data.time = typeof timestamp === "string" ? new Date(timestamp).getTime() : timestamp;
+		data.messageTime = data.time;
+		return data;
+	}
+	/**
+	* 发送长消息
+	*/
+	async sendLongMsg(_contact, _resId) {
+		this.logger("warn", "[sendLongMsg] QQ Official Bot API 暂不支持长消息发送");
+		return this.initSendMsgResults();
+	}
+	/**
+	* 发送合并转发消息
+	*
+	* 将 NodeElement 拆解为文本 + 图片等元素，拼接成 markdown 发送。
+	* 节点之间仅用换行隔开，不添加任何前缀提示文本。
+	*/
+	async sendForwardMsg(contact, elements, _options) {
+		const parts = [];
+		const mediaElements = [];
+		for (const node of elements) {
+			if (node.subType === "messageID") continue;
+			const lines = [];
+			for (const el of node.message) {
+				if (typeof el === "string") {
+					lines.push(el);
+					continue;
+				}
+				switch (el.type) {
+					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})`);
+						} catch {
+							lines.push(`![${el.name || "图片"} #300px #300px](${el.file})`);
+						}
+						else try {
+							const { url, width, height } = await fileToUrl("image", el.file, el.name || "image.jpg");
+							lines.push(`![${el.name || "图片"} #${width}px #${height}px](${url})`);
+						} catch {
+							lines.push(`![${el.name || "图片"} #300px #300px]()`);
+						}
+						break;
+					case "at":
+						if (contact.scene === "friend" || contact.scene === "direct") break;
+						if (el.targetId === "all") lines.push("<qqbot-at-everyone />");
+						else lines.push(`<qqbot-at-user id="${el.targetId}" />`);
+						break;
+					case "markdown":
+						lines.push(el.markdown);
+						break;
+					case "video":
+					case "record":
+					case "file":
+						mediaElements.push(el);
+						break;
+					case "face":
+					case "reply":
+					case "basketball":
+					case "dice":
+					case "rps": break;
+					default: break;
+				}
+			}
+			const block = lines.join("\n");
+			if (block) parts.push(block);
+		}
+		const content = parts.join("\r\r\n\n");
+		const result = await this.sendMsg(contact, [segment.markdown(content)]);
+		if (mediaElements.length) await this.sendMsg(contact, mediaElements);
+		return {
+			messageId: result.messageId,
+			forwardId: ""
+		};
+	}
+	/**
+	* 获取头像 url
+	*/
+	async getAvatarUrl(_userId, _size = 0) {
+		return `https://thirdqq.qlogo.cn/qqapp/${this.cfg.appId}/${_userId}/${_size}`;
+	}
+	/**
+	* 获取群头像 url
+	*/
+	async getGroupAvatarUrl(_groupId, _size = 0, _history) {
+		return `https://p.qlogo.cn/gh/${_groupId}/${_groupId}/${_size || 100}`;
+	}
+	/**
+	* 获取消息
+	*/
+	async getMsg(_contact, _messageId) {
+		this.logger("warn", "[getMsg] QQ Official Bot API 暂不支持获取消息内容");
+		return {
+			time: 0,
+			messageId: _messageId || "",
+			messageSeq: 0,
+			contact: typeof _contact === "string" ? {
+				scene: "group",
+				peer: _contact,
+				subPeer: "",
+				name: ""
+			} : _contact,
+			sender: {
+				userId: "",
+				nick: "",
+				name: "",
+				role: "member"
+			},
+			elements: []
+		};
+	}
+	/** @internal */
+	async getHistoryMsg(_contact, _start, _count) {
+		this.logger("warn", "[getHistoryMsg] QQ Official Bot API 暂不支持获取历史消息");
+		return [];
+	}
+	/**
+	* 获取合并转发消息
+	*/
+	async getForwardMsg(_resId) {
+		this.logger("warn", "[getForwardMsg] QQ Official Bot API 暂不支持获取合并转发消息");
+		return [];
+	}
+	/**
+	* 获取精华消息
+	*/
+	async getGroupHighlights(_groupId, _page, _pageSize) {
+		this.logger("warn", "[getGroupHighlights] QQ Official Bot API 暂不支持获取精华消息");
+		return [];
+	}
+	/**
+	* 构造资源 ID
+	*/
+	async createResId(_contact, _elements) {
+		this.logger("warn", "[createResId] QQ Official Bot API 暂不支持构造资源 ID");
+		return "";
+	}
+	/**
+	* 设置、取消群精华消息
+	*/
+	async setGroupHighlights(_groupId, _messageId, _create) {
+		this.logger("warn", "[setGroupHighlights] QQ Official Bot API 暂不支持设置精华消息");
+	}
+	/**
+	* 发送好友赞
+	*/
+	async sendLike(_targetId, _count) {
+		this.logger("warn", "[sendLike] QQ Official Bot API 暂不支持发送好友赞");
+	}
+	/**
+	* 群踢人
+	*/
+	async groupKickMember(_groupId, _targetId, _rejectAddRequest, _kickReason) {
+		this.logger("warn", "[groupKickMember] QQ Official Bot API 暂不支持群踢人");
+	}
+	/**
+	* 禁言群成员
+	*/
+	async setGroupMute(_groupId, _targetId, _duration) {
+		this.logger("warn", "[setGroupMute] QQ Official Bot API 暂不支持禁言群成员");
+	}
+	/**
+	* 群全员禁言
+	*/
+	async setGroupAllMute(_groupId, _isBan) {
+		this.logger("warn", "[setGroupAllMute] QQ Official Bot API 暂不支持群全员禁言");
+	}
+	/**
+	* 设置群管理员
+	*/
+	async setGroupAdmin(_groupId, _targetId, _isAdmin) {
+		this.logger("warn", "[setGroupAdmin] QQ Official Bot API 暂不支持设置群管理员");
+	}
+	/**
+	* 设置群名片
+	*/
+	async setGroupMemberCard(_groupId, _targetId, _card) {
+		this.logger("warn", "[setGroupMemberCard] QQ Official Bot API 暂不支持设置群名片");
+	}
+	/**
+	* 设置群名
+	*/
+	async setGroupName(_groupId, _groupName) {
+		this.logger("warn", "[setGroupName] QQ Official Bot API 暂不支持设置群名");
+	}
+	/**
+	* 退出群组
+	*/
+	async setGroupQuit(_groupId, _isDismiss) {
+		this.logger("warn", "[setGroupQuit] QQ Official Bot API 暂不支持退出群组");
+	}
+	/**
+	* 设置群专属头衔
+	*/
+	async setGroupMemberTitle(_groupId, _targetId, _title) {
+		this.logger("warn", "[setGroupMemberTitle] QQ Official Bot API 暂不支持设置群专属头衔");
+	}
+	/**
+	* 获取陌生人信息
+	*/
+	async getStrangerInfo(_targetId) {
+		this.logger("warn", "[getStrangerInfo] QQ Official Bot API 暂不支持获取陌生人信息");
+		return {
+			userId: _targetId,
+			nick: ""
+		};
+	}
+	/**
+	* 获取好友列表
+	*/
+	async getFriendList(_refresh) {
+		this.logger("warn", "[getFriendList] QQ Official Bot API 暂不支持获取好友列表");
+		return [];
+	}
+	/**
+	* 获取群信息
+	*/
+	async getGroupInfo(_groupId, _noCache) {
+		this.logger("warn", "[getGroupInfo] QQ Official Bot API 暂不支持获取群信息");
+		return {
+			groupId: _groupId,
+			groupName: "",
+			owner: "",
+			groupRemark: "",
+			admins: [],
+			maxMemberCount: 0,
+			memberCount: 0,
+			groupDesc: "",
+			avatar: ""
+		};
+	}
+	/**
+	* 获取群列表
+	*/
+	async getGroupList(_refresh) {
+		this.logger("warn", "[getGroupList] QQ Official Bot API 暂不支持获取群列表");
+		return [];
+	}
+	/**
+	* 获取群成员信息
+	*/
+	async getGroupMemberInfo(_groupId, _targetId, _refresh) {
+		this.logger("warn", "[getGroupMemberInfo] QQ Official Bot API 暂不支持获取群成员信息");
+		return {
+			userId: _targetId,
+			role: "member"
+		};
+	}
+	/**
+	* 获取群成员列表
+	*/
+	async getGroupMemberList(_groupId, _refresh) {
+		this.logger("warn", "[getGroupMemberList] QQ Official Bot API 暂不支持获取群成员列表");
+		return [];
+	}
+	/**
+	* 获取群荣誉信息
+	*/
+	async getGroupHonor(_groupId) {
+		this.logger("warn", "[getGroupHonor] QQ Official Bot API 暂不支持获取群荣誉信息");
+		return [];
+	}
+	/**
+	* 设置好友请求结果
+	*/
+	async setFriendApplyResult(_requestId, _isApprove, _remark) {
+		this.logger("warn", "[setFriendApplyResult] QQ Official Bot API 暂不支持设置好友请求结果");
+	}
+	/**
+	* 设置申请加入群请求结果
+	*/
+	async setGroupApplyResult(_requestId, _isApprove, _denyReason) {
+		this.logger("warn", "[setGroupApplyResult] QQ Official Bot API 暂不支持设置群申请结果");
+	}
+	/**
+	* 设置邀请加入群请求结果
+	*/
+	async setInvitedJoinGroupResult(_requestId, _isApprove) {
+		this.logger("warn", "[setInvitedJoinGroupResult] QQ Official Bot API 暂不支持设置邀请入群结果");
+	}
+	/**
+	* 设置消息表情回应
+	*/
+	async setMsgReaction(_contact, _messageId, _faceId, _isSet) {
+		this.logger("warn", "[setMsgReaction] QQ Official Bot API 暂不支持设置消息表情回应");
+	}
+	/**
+	* 上传群文件、私聊文件
+	*/
+	async uploadFile(_contact, _file, _name, _folder) {
+		this.logger("warn", "[uploadFile] QQ Official Bot API 暂不支持上传文件");
+	}
+	/**
+	* 下载文件到协议端本地
+	*/
+	async downloadFile(_options) {
+		this.logger("warn", "[downloadFile] QQ Official Bot API 暂不支持下载文件到本地");
+		return { filePath: "" };
+	}
+	/**
+	* 创建群文件夹
+	*/
+	async createGroupFolder(_groupId, _name) {
+		this.logger("warn", "[createGroupFolder] QQ Official Bot API 暂不支持创建群文件夹");
+		return {
+			id: "",
+			usedSpace: "0"
+		};
+	}
+	/**
+	* 重命名群文件夹
+	*/
+	async renameGroupFolder(_groupId, _folderId, _name) {
+		this.logger("warn", "[renameGroupFolder] QQ Official Bot API 暂不支持重命名群文件夹");
+		return false;
+	}
+	/**
+	* 删除群文件夹
+	*/
+	async delGroupFolder(_groupId, _folderId) {
+		this.logger("warn", "[delGroupFolder] QQ Official Bot API 暂不支持删除群文件夹");
+		return false;
+	}
+	/**
+	* 上传群文件
+	*/
+	async uploadGroupFile(_groupId, _file, _name) {
+		this.logger("warn", "[uploadGroupFile] QQ Official Bot API 暂不支持上传群文件");
+		return false;
+	}
+	/**
+	* 获取文件 url
+	*/
+	async getFileUrl(_contact, _fileId) {
+		this.logger("warn", "[getFileUrl] QQ Official Bot API 暂不支持获取文件 url");
+		return "";
+	}
+	/**
+	* 删除群文件
+	*/
+	async delGroupFile(_groupId, _fileId, _busId) {
+		this.logger("warn", "[delGroupFile] QQ Official Bot API 暂不支持删除群文件");
+		return false;
+	}
+	/**
+	* 获取群文件系统信息
+	*/
+	async getGroupFileSystemInfo(_groupId) {
+		this.logger("warn", "[getGroupFileSystemInfo] QQ Official Bot API 暂不支持获取群文件系统信息");
+		return {
+			fileCount: 0,
+			limitCount: 0,
+			usedSpace: 0,
+			totalSpace: 0
+		};
+	}
+	/**
+	* 获取群文件夹下文件列表
+	*/
+	async getGroupFileList(_groupId, _folderId) {
+		this.logger("warn", "[getGroupFileList] QQ Official Bot API 暂不支持获取群文件列表");
+		return {
+			files: [],
+			folders: []
+		};
+	}
+	/**
+	* 设置群备注
+	*/
+	async setGroupRemark(_groupId, _remark) {
+		this.logger("warn", "[setGroupRemark] QQ Official Bot API 暂不支持设置群备注");
+		return false;
+	}
+	/**
+	* 获取陌生群信息
+	*/
+	async getNotJoinedGroupInfo(_groupId) {
+		this.logger("warn", "[getNotJoinedGroupInfo] QQ Official Bot API 暂不支持获取陌生群信息");
+		return {
+			groupId: _groupId,
+			groupName: "",
+			owner: "",
+			groupRemark: "",
+			admins: [],
+			maxMemberCount: 0,
+			memberCount: 0,
+			groupDesc: "",
+			avatar: ""
+		};
+	}
+	/**
+	* 获取艾特全体成员剩余次数
+	*/
+	async getAtAllCount(_groupId) {
+		this.logger("warn", "[getAtAllCount] QQ Official Bot API 暂不支持获取艾特全体成员剩余次数");
+		return {
+			accessAtAll: false,
+			groupRemainCount: 0,
+			userRremainCount: 0
+		};
+	}
+	/**
+	* 获取群被禁言用户列表
+	*/
+	async getGroupMuteList(_groupId) {
+		this.logger("warn", "[getGroupMuteList] QQ Official Bot API 暂不支持获取群被禁言用户列表");
+		return [];
+	}
+	/**
+	* 戳一戳用户
+	*/
+	async pokeUser(_contact, _targetId, _count) {
+		this.logger("warn", "[pokeUser] QQ Official Bot API 暂不支持戳一戳用户");
+		return false;
+	}
+	/**
+	* 获取 Cookies
+	*/
+	async getCookies(_domain) {
+		this.logger("warn", "[getCookies] QQ Official Bot API 暂不支持获取 Cookies");
+		return { cookie: "" };
+	}
+	/**
+	* 获取 QQ 相关接口凭证
+	*/
+	async getCredentials(_domain) {
+		this.logger("warn", "[getCredentials] QQ Official Bot API 暂不支持获取 Credentials");
+		return {
+			cookies: "",
+			csrf_token: 0
+		};
+	}
+	/**
+	* 获取 CSRF Token
+	*/
+	async getCSRFToken() {
+		this.logger("warn", "[getCSRFToken] QQ Official Bot API 暂不支持获取 CSRF Token");
+		return { token: 0 };
+	}
+	/**
+	* 设置头像
+	*/
+	async setAvatar(_file) {
+		this.logger("warn", "[setAvatar] QQ Official Bot API 暂不支持设置头像");
+	}
+	/**
+	* 获取 rkey
+	*/
+	async getRkey() {
+		this.logger("warn", "[getRkey] QQ Official Bot API 暂不支持获取 rkey");
+		return [];
+	}
+	/**
+	* 获取群 Ai 语音可用声色列表
+	*/
+	async getAiCharacters() {
+		this.logger("warn", "[getAiCharacters] QQ Official Bot API 暂不支持获取群 Ai 语音可用声色列表");
+		return [];
+	}
+	/**
+	* 设置群 Ai 语音声色
+	*/
+	async sendAiCharacter(_groupId, _characterId, _text) {
+		this.logger("warn", "[sendAiCharacter] QQ Official Bot API 暂不支持设置群 Ai 语音声色");
+		return { messageId: "" };
+	}
+};
+
+//#endregion
+//#region src/core/event/conver.ts
+/** 反转义 HTML 实体 */
+const unescape = (text) => text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+/**
+* QQ Bot 报文 → karin elements
+*
+* @param appid 应用 ID（与机器人 sub_id 同一值会被替换为 appid）
+* @param ev 事件
+* @param selfSubId 机器人 user id（非 appid）
+* @param options
+*/
+const convertToKarin = (appid, ev, selfSubId, options = {}) => {
+	const elements = [];
+	const data = ev.d;
+	/** mentions 索引 id -> displayName */
+	const mentionMap = /* @__PURE__ */ new Map();
+	if (ev.t === "MESSAGE_CREATE" || ev.t === "AT_MESSAGE_CREATE") ev.d.mentions?.forEach((v) => {
+		mentionMap.set(v.id, v.username);
+	});
+	else if (ev.t === "GROUP_MESSAGE_CREATE" || ev.t === "GROUP_AT_MESSAGE_CREATE") ev.d.mentions?.forEach((v) => {
+		mentionMap.set(v.id, v.username);
+		mentionMap.set(v.member_openid, v.username);
+	});
+	/** 附件 */
+	for (const v of data.attachments || []) {
+		const url = v.url.startsWith("http") ? v.url : `https://${v.url}`;
+		if (v.content_type.startsWith("image/")) elements.push(segment.image(url, {
+			subType: v.content_type.split("/")[1],
+			name: v.filename,
+			width: v.width,
+			height: v.height
+		}));
+		else if (v.content_type === "video/mp4") elements.push(segment.video(url));
+		else if (v.content_type === "voice") elements.push(segment.record(v.voice_wav_url || url));
+		else if (v.content_type === "file") elements.push(segment.json(JSON.stringify({
+			type: "file",
+			attachment: v
+		})));
+	}
+	const tokens = data?.content?.match(/<faceType=\d+,faceId="\d+",ext="[^"]+">|<@!\d+>|<qqbot-at-user id="[^"]+"\s*\/?>|<qqbot-at-everyone\s*\/?>|[^<]+/g) || [];
+	const cfg = getConfig(appid);
+	for (const tok of tokens) {
+		if (tok.startsWith("<faceType=")) {
+			const m = tok.match(/faceId="(\d+)"/);
+			if (m) elements.push(segment.face(Number(m[1])));
+			continue;
+		}
+		if (tok.startsWith("<@!")) {
+			const id = tok.replace(/^<@!|>$/g, "");
+			const name = mentionMap.get(id) || "";
+			elements.push(segment.at(id === selfSubId ? appid : id, name));
+			continue;
+		}
+		if (tok.startsWith("<qqbot-at-user")) {
+			const id = tok.match(/id="([^"]+)"/)?.[1] || "";
+			const name = mentionMap.get(id) || "";
+			elements.push(segment.at(id === selfSubId ? appid : id, name));
+			continue;
+		}
+		if (tok.startsWith("<qqbot-at-everyone")) {
+			elements.push(segment.at("all"));
+			continue;
+		}
+		let text = unescape(tok);
+		if (cfg?.regex) for (const r of cfg.regex) {
+			const reg = r.reg instanceof RegExp ? r.reg : new RegExp(r.reg);
+			text = text.trim().replace(reg, r.rep);
+		}
+		elements.push(segment.text(text));
+	}
+	/** 群消息是否需要在头部补 self at */
+	if (ev.t === "GROUP_AT_MESSAGE_CREATE" || ev.t === "GROUP_MESSAGE_CREATE") {
+		const youMention = (ev.d.mentions || []).find((m) => m.is_you);
+		if (options.forceAtSelf || !!youMention) {
+			if (!elements.some((e) => e.type === "at" && (e.targetId === appid || e.targetId === selfSubId))) elements.unshift(segment.at(appid, youMention?.username || ""));
+		}
+	}
+	return elements;
+};
+
+//#endregion
+//#region src/core/event/message.ts
+/**
+* 群消息（@机器人 / 普通消息合并入口）
+*/
+const onGroupMsg = (client, ev, opts) => {
+	const selfId = client.selfId;
+	const userId = ev.d.author.member_openid || ev.d.author.id;
+	const username = ev.d.author.username || "";
+	if (userId && username) client.nicknameCache.set(userId, username);
+	ev.d.mentions?.forEach((m) => {
+		if (m.member_openid && m.username) client.nicknameCache.set(m.member_openid, m.username);
+	});
+	const contact = karin.contactGroup(ev.d.group_openid || ev.d.group_id);
+	const sender = karin.groupSender(userId, "member", username);
+	const e = createGroupMessage({
+		bot: client,
+		elements: convertToKarin(selfId, ev, client.selfSubId("id"), { forceAtSelf: opts.forceAtSelf }),
+		eventId: ev.id,
+		messageId: ev.d.id,
+		messageSeq: 0,
+		rawEvent: ev,
+		time: Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp),
+		contact,
+		sender,
+		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
+	});
+	return e;
+};
+/**
+* 单聊消息
+*/
+const onFriendMsg = (client, ev) => {
+	const selfId = client.selfId;
+	const userId = ev.d.author.user_openid || ev.d.author.id;
+	const username = ev.d.author.username || "";
+	if (userId && username) client.nicknameCache.set(userId, username);
+	const contact = karin.contactFriend(userId);
+	const sender = karin.friendSender(userId, username);
+	const e = createFriendMessage({
+		bot: client,
+		elements: convertToKarin(selfId, ev, client.selfSubId("id")),
+		eventId: ev.id,
+		messageId: ev.d.id,
+		messageSeq: 0,
+		rawEvent: ev,
+		time: Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp),
+		contact,
+		sender,
+		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
+	});
+	return e;
+};
+/**
+* 频道消息
+*/
+const onChannelMsg = (client, ev) => {
+	const selfId = client.selfId;
+	const userId = ev.d.author.id;
+	const contact = karin.contact("guild", ev.d.guild_id, ev.d.channel_id);
+	const sender = karin.groupSender(userId, "unknown", ev.d.author.username || "");
+	const e = createGuildMessage({
+		bot: client,
+		elements: convertToKarin(selfId, ev, client.selfSubId("id")),
+		eventId: ev.id,
+		messageId: ev.d.id,
+		messageSeq: 0,
+		rawEvent: ev,
+		time: Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp),
+		contact,
+		sender,
+		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
+	});
+	return e;
+};
+/**
+* 频道私信
+*/
+const onDirectMsg = (client, ev) => {
+	const selfId = client.selfId;
+	const userId = ev.d.author.id;
+	const contact = karin.contact("direct", ev.d.guild_id, ev.d.channel_id);
+	const sender = karin.friendSender(userId, ev.d.author.username || "");
+	const e = createDirectMessage({
+		bot: client,
+		elements: convertToKarin(selfId, ev, client.selfSubId("id")),
+		eventId: ev.id,
+		messageId: ev.d.id,
+		messageSeq: 0,
+		rawEvent: ev,
+		time: Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp),
+		contact,
+		sender,
+		srcGuildId: ev.d.src_guild_id,
+		srcReply: (elements) => client.srcReply(e, [...elements, segment.pasmsg(ev.d.id)])
+	});
+	return e;
+};
+
+//#endregion
+//#region src/core/event/notice.ts
+/**
+* 机器人加入群聊事件
+* @param client 机器人实例
+* @param event 事件
+*/
+const onGroupAddRobot = (client, event) => {
+	const selfId = client.selfId;
+	const userId = event.d.op_member_openid;
+	const groupId = event.d.group_openid;
+	const contact = karin.contactGroup(groupId);
+	const sender = karin.groupSender(userId, "unknown");
+	const eventId = event.id;
+	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
+	createGroupMemberAddNotice({
+		contact,
+		eventId,
+		sender,
+		srcReply,
+		bot: client,
+		rawEvent: event,
+		time: event.d.timestamp,
+		content: {
+			operatorId: userId,
+			targetId: selfId,
+			type: "invite"
+		}
+	});
+};
+/**
+* 机器人退出群聊事件
+* @param client 机器人实例
+* @param event 事件
+*/
+const onGroupDelRobot = (client, event) => {
+	const selfId = client.selfId;
+	const userId = event.d.op_member_openid;
+	const groupId = event.d.group_openid;
+	const contact = karin.contactGroup(groupId);
+	const sender = karin.groupSender(userId, "unknown");
+	const eventId = event.id;
+	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
+	createGroupMemberDelNotice({
+		contact,
+		eventId,
+		sender,
+		srcReply,
+		bot: client,
+		rawEvent: event,
+		time: event.d.timestamp,
+		content: {
+			operatorId: userId,
+			targetId: selfId,
+			type: "kick"
+		}
+	});
+};
+/**
+* 群聊接受机器人主动消息
+* @param client 机器人实例
+* @param event 事件
+*/
+const onGroupMsgReceive = (client, event) => {
+	const groupId = event.d.group_openid;
+	const userId = event.d.op_member_openid;
+	client.logger("mark", `群聊 ${groupId} 已允许机器人主动发送消息 操作人: ${userId}`);
+};
+/**
+* 群聊拒绝机器人主动消息
+* @param client 机器人实例
+* @param event 事件
+*/
+const onGroupMsgReject = (client, event) => {
+	const groupId = event.d.group_openid;
+	const userId = event.d.op_member_openid;
+	client.logger("mark", `群聊 ${groupId} 已拒绝机器人主动发送消息 操作人: ${userId}`);
+};
+/**
+* 好友添加事件
+* @param client 机器人实例
+* @param event 事件
+*/
+const onFriendAdd = (client, event) => {
+	const selfId = client.selfId;
+	const userId = event.d.openid;
+	const contact = karin.contactFriend(userId);
+	const sender = karin.friendSender(userId, "");
+	const eventId = event.id;
+	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
+	createFriendIncreaseNotice({
+		contact,
+		eventId,
+		sender,
+		srcReply,
+		bot: client,
+		rawEvent: event,
+		time: event.d.timestamp,
+		content: { targetId: selfId }
+	});
+};
+/**
+* 好友删除事件
+* @param client 机器人实例
+* @param event 事件
+*/
+const onFriendDel = (client, event) => {
+	const selfId = client.selfId;
+	const userId = event.d.openid;
+	const contact = karin.contactFriend(userId);
+	const sender = karin.friendSender(userId, "");
+	const eventId = event.id;
+	const srcReply = (elements) => client.sendMsg(contact, [...elements, segment.pasmsg(eventId, "event")]);
+	createFriendDecreaseNotice({
+		contact,
+		eventId,
+		sender,
+		srcReply,
+		bot: client,
+		rawEvent: event,
+		time: event.d.timestamp,
+		content: { targetId: selfId }
+	});
+};
+/**
+* 好友接受机器人主动消息
+* @param client 机器人实例
+* @param event 事件
+*/
+const onC2CMsgReceive = (client, event) => {
+	const userId = event.d.openid;
+	client.logger("mark", `好友 ${userId} 已允许机器人主动发送消息`);
+};
+/**
+* 好友拒绝机器人主动消息
+* @param client 机器人实例
+* @param event 事件
+*/
+const onC2CMsgReject = (client, event) => {
+	const userId = event.d.openid;
+	client.logger("mark", `好友 ${userId} 已拒绝机器人主动发送消息`);
+};
+
+//#endregion
+//#region src/core/event/interaction.ts
+/**
+* INTERACTION_CREATE 处理
+*
+* - 先 ack 客户端（必须在 3s 内），失败仅 warn
+* - 借用普通消息事件投递给业务层，业务层通过 e.rawEvent.t === 'INTERACTION_CREATE' 区分
+* - elements: [self at] + text(button_data) + json(meta) + pasmsg(event_id, 'event')
+*/
+const onInteraction = (client, ev) => {
+	client.super.interaction.ack(ev.id, 0).catch((err) => {
+		client.logger("warn", "[INTERACTION] ack 失败:", err);
+	});
+	const selfId = client.selfId;
+	const buttonData = ev.d.data?.resolved?.button_data || "";
+	const meta = segment.json(JSON.stringify({
+		tag: "qqbot-button-click",
+		type: ev.d.type,
+		chat_type: ev.d.chat_type,
+		scene: ev.d.scene,
+		button_id: ev.d.data?.resolved?.button_id,
+		button_data: ev.d.data?.resolved?.button_data,
+		feature_id: ev.d.data?.resolved?.feature_id,
+		message_id: ev.d.data?.resolved?.message_id,
+		user_id: ev.d.data?.resolved?.user_id,
+		version: ev.d.version
+	}));
+	const time = Number(new Date(ev.d.timestamp).getTime() || Date.now());
+	if (ev.d.chat_type === 1 && ev.d.group_openid) {
+		const userId = ev.d.group_member_openid || "";
+		const contact = karin.contactGroup(ev.d.group_openid);
+		const sender = karin.groupSender(userId, "unknown");
+		const e = createGroupMessage({
+			bot: client,
+			elements: [
+				segment.at(selfId),
+				segment.text(buttonData),
+				meta
+			],
+			eventId: ev.id,
+			messageId: ev.id,
+			messageSeq: 0,
+			rawEvent: ev,
+			time,
+			contact,
+			sender,
+			srcReply: (els) => client.srcReply(e, [...els, segment.pasmsg(ev.id, "event")])
+		});
+		return;
+	}
+	if (ev.d.chat_type === 2 && ev.d.user_openid) {
+		const userId = ev.d.user_openid;
+		const contact = karin.contactFriend(userId);
+		const sender = karin.friendSender(userId, "");
+		const e = createFriendMessage({
+			bot: client,
+			elements: [
+				segment.at(selfId),
+				segment.text(buttonData),
+				meta
+			],
+			eventId: ev.id,
+			messageId: ev.id,
+			messageSeq: 0,
+			rawEvent: ev,
+			time,
+			contact,
+			sender,
+			srcReply: (els) => client.srcReply(e, [...els, segment.pasmsg(ev.id, "event")])
+		});
+		return;
+	}
+	if (ev.d.chat_type === 0 && ev.d.guild_id && ev.d.channel_id) {
+		const userId = ev.d.data?.resolved?.user_id || "";
+		const contact = karin.contact("guild", ev.d.guild_id, ev.d.channel_id);
+		const sender = karin.groupSender(userId, "unknown");
+		const e = createGuildMessage({
+			bot: client,
+			elements: [segment.text(buttonData), meta],
+			eventId: ev.id,
+			messageId: ev.id,
+			messageSeq: 0,
+			rawEvent: ev,
+			time,
+			contact,
+			sender,
+			srcReply: (els) => client.srcReply(e, [...els, segment.pasmsg(ev.id, "event")])
+		});
+		return;
+	}
+	client.logger("debug", `[INTERACTION] 未识别的 chat_type=${ev.d.chat_type}`);
+};
+
+//#endregion
+//#region src/core/event/dispatcher.ts
+/** 事件名 → 中文标签 */
+const eventLabel = {
+	["READY"]: "就绪",
+	["RESUMED"]: "连接恢复",
+	["GROUP_AT_MESSAGE_CREATE"]: "群聊@消息",
+	["GROUP_MESSAGE_CREATE"]: "群聊消息",
+	["C2C_MESSAGE_CREATE"]: "好友消息",
+	["MESSAGE_CREATE"]: "频道消息",
+	["AT_MESSAGE_CREATE"]: "频道@消息",
+	["DIRECT_MESSAGE_CREATE"]: "频道私信",
+	["GROUP_ADD_ROBOT"]: "机器人入群",
+	["GROUP_DEL_ROBOT"]: "机器人退群",
+	["GROUP_MSG_RECEIVE"]: "群聊开启通知",
+	["GROUP_MSG_REJECT"]: "群聊关闭通知",
+	["FRIEND_ADD"]: "添加好友",
+	["FRIEND_DEL"]: "删除好友",
+	["C2C_MSG_RECEIVE"]: "单聊开启通知",
+	["C2C_MSG_REJECT"]: "单聊关闭通知",
+	["INTERACTION_CREATE"]: "互动事件",
+	["MESSAGE_AUDIT_PASS"]: "消息审核通过",
+	["MESSAGE_AUDIT_REJECT"]: "消息审核不通过"
+};
+/**
+* 事件分发
+*/
+const dispatch$1 = (client, ev) => {
+	const label = eventLabel[ev.t] || ev.t;
+	client.logger("debug", `[事件][${label}]`);
+	log("debug", `${client.selfId}: dispatcher routing t=${ev.t} -> ${label}`);
+	switch (ev.t) {
+		case "READY": return client.logger("info", `WebSocket 就绪: ${ev.d?.user?.username || ""}`);
+		case "RESUMED": return client.logger("info", "WebSocket 连接已恢复");
+		case "GROUP_AT_MESSAGE_CREATE":
+			onGroupMsg(client, ev, { forceAtSelf: true });
+			return;
+		case "GROUP_MESSAGE_CREATE":
+			onGroupMsg(client, ev, { forceAtSelf: false });
+			return;
+		case "C2C_MESSAGE_CREATE":
+			onFriendMsg(client, ev);
+			return;
+		case "MESSAGE_CREATE":
+		case "AT_MESSAGE_CREATE":
+			onChannelMsg(client, ev);
+			return;
+		case "DIRECT_MESSAGE_CREATE":
+			onDirectMsg(client, ev);
+			return;
+		case "GROUP_ADD_ROBOT":
+			onGroupAddRobot(client, ev);
+			return;
+		case "GROUP_DEL_ROBOT":
+			onGroupDelRobot(client, ev);
+			return;
+		case "GROUP_MSG_RECEIVE":
+			onGroupMsgReceive(client, ev);
+			return;
+		case "GROUP_MSG_REJECT":
+			onGroupMsgReject(client, ev);
+			return;
+		case "FRIEND_ADD":
+			onFriendAdd(client, ev);
+			return;
+		case "FRIEND_DEL":
+			onFriendDel(client, ev);
+			return;
+		case "C2C_MSG_RECEIVE":
+			onC2CMsgReceive(client, ev);
+			return;
+		case "C2C_MSG_REJECT":
+			onC2CMsgReject(client, ev);
+			return;
+		case "INTERACTION_CREATE":
+			onInteraction(client, ev);
+			return;
+		case "MESSAGE_AUDIT_PASS": return client.logger("debug", `消息审核通过: audit_id=${ev.d.audit_id}`);
+		case "MESSAGE_AUDIT_REJECT": return client.logger("debug", `消息审核不通过: audit_id=${ev.d.audit_id}`);
+		default: logger.debug(`[QQ Official Bot] 未处理事件: ${ev.t}`);
+	}
+};
+
+//#endregion
+//#region src/connection/transport.ts
+/**
+* 全局事件总线
+* 每个 appId 一个 channel，业务层（dispatcher）通过 on(appId, handler) 订阅
+*/
+const bus = new EventEmitter();
+bus.setMaxListeners(0);
+/**
+* 推送一条事件到业务层
+*/
+const dispatch = (appId, ev) => {
+	const n = bus.listenerCount(appId);
+	log("debug", `${appId}: bus.dispatch t=${ev.t} listeners=${n}`);
+	if (n === 0) log("warn", `${appId}: 收到事件 ${ev.t} 但没有监听器（dispatcher 未注册或已被移除）`);
+	bus.emit(appId, ev);
+};
+/**
+* 注销某个 appId 的所有监听器
+* 重连 / 销毁 bot 时调用
+*/
+const offAll = (appId) => {
+	bus.removeAllListeners(appId);
+};
+
+//#endregion
+//#region src/connection/ws/error.ts
+/** WebSocket 错误码精确映射 */
+const wsErrorMap = {
+	4001: {
+		message: "无效的 opcode",
+		canResume: false,
+		canIdentify: false
+	},
+	4002: {
+		message: "无效的 payload",
+		canResume: false,
+		canIdentify: false
+	},
+	4007: {
+		message: "seq 错误",
+		canResume: false,
+		canIdentify: true
+	},
+	4006: {
+		message: "无效的 session id，无法继续 resume，请 identify",
+		canResume: false,
+		canIdentify: true
+	},
+	4008: {
+		message: "发送 payload 过快，请重新连接，并遵守连接后返回的频控信息",
+		canResume: true,
+		canIdentify: true
+	},
+	4009: {
+		message: "连接过期，请重连并执行 resume 进行重新连接",
+		canResume: true,
+		canIdentify: true
+	},
+	4010: {
+		message: "无效的 shard",
+		canResume: false,
+		canIdentify: false
+	},
+	4011: {
+		message: "连接需要处理的 guild 过多，请进行合理的分片",
+		canResume: false,
+		canIdentify: false
+	},
+	4012: {
+		message: "无效的 version",
+		canResume: false,
+		canIdentify: false
+	},
+	4013: {
+		message: "无效的 intent",
+		canResume: false,
+		canIdentify: false
+	},
+	4014: {
+		message: "intent 无权限",
+		canResume: false,
+		canIdentify: false
+	},
+	4914: {
+		message: "机器人已下架，只允许连接沙箱环境，请断开连接，检验当前连接环境",
+		canResume: false,
+		canIdentify: false
+	},
+	4915: {
+		message: "机器人已封禁，不允许连接，请断开连接，申请解封后再连接",
+		canResume: false,
+		canIdentify: false
+	}
+};
+/**
+* 获取 WebSocket 错误码信息
+* @param code - WebSocket close code
+* @returns 错误信息，未找到则返回 undefined
+*/
+const getWSErrorInfo = (code) => {
+	const exact = wsErrorMap[code];
+	if (exact) return exact;
+	if (code >= 4900 && code <= 4913) return {
+		message: "内部错误，请重连",
+		canResume: false,
+		canIdentify: true
+	};
+};
+/**
+* 格式化 WebSocket 关闭信息为可读字符串
+* @param code - WebSocket close code
+* @param reason - 关闭原因（二进制 payload）
+* @returns 格式化后的错误字符串
+*/
+const formatWSClose = (code, reason) => {
+	const info = getWSErrorInfo(code);
+	const parts = [];
+	if (info) {
+		parts.push(`[${code}] ${info.message}`);
+		if (info.canResume && info.canIdentify) parts.push("建议: 可尝试 Resume 或重新 Identify");
+		else if (info.canResume) parts.push("建议: 可尝试 Resume");
+		else if (info.canIdentify) parts.push("建议: 可尝试重新 Identify");
+		else parts.push("建议: 不可重试，请检查配置或联系官方");
+	} else {
+		parts.push(`[${code}] 未知错误码`);
+		if (code === 1e3) parts.push("正常关闭");
+		else if (code === 1001) parts.push("终端离开");
+		else if (code === 1006) parts.push("异常关闭（连接异常断开）");
+		else if (code === 1011) parts.push("服务器遇到异常");
+	}
+	if (reason) parts.push(`reason: ${reason}`);
+	return parts.join(" | ");
+};
+
+//#endregion
+//#region src/connection/ws/client.ts
+/**
+* 单连接生命周期
+*/
+var WSClient = class {
+	opts;
+	socket;
+	heartbeatTimer;
+	heartbeatInterval = 45e3;
+	sessionId = "";
+	seq = 0;
+	closed = false;
+	closedReason = "manual";
+	constructor(opts) {
+		this.opts = opts;
+		if (opts.resume) {
+			this.sessionId = opts.resume.sessionId;
+			this.seq = opts.resume.seq;
+		}
+	}
+	/** 连接的快照，用于上层 Resume */
+	snapshot() {
+		return {
+			sessionId: this.sessionId,
+			seq: this.seq
+		};
+	}
+	start() {
+		const ws = new WebSocket(this.opts.gatewayUrl);
+		this.socket = ws;
+		ws.on("open", () => {
+			log("debug", `${this.opts.appId}: WebSocket opened (${this.opts.gatewayUrl})`);
+		});
+		ws.on("close", (code, reason) => {
+			const closeInfo = formatWSClose(code, reason?.toString() || "(empty)");
+			log("error", `${this.opts.appId}: WebSocket 关闭 | ${closeInfo}`);
+			if (this.closed) return;
+			this.close("closed");
+		});
+		ws.on("error", (err) => {
+			log("error", `${this.opts.appId}: WebSocket error:`, err);
+			if (this.closed) return;
+			this.close("error");
+		});
+		ws.on("unexpected-response", (_req, res) => {
+			log("error", `${this.opts.appId}: WebSocket unexpected-response status=${res.statusCode} ${res.statusMessage}`);
+		});
+		ws.on("message", (raw) => this.onMessage(raw));
+	}
+	/**
+	* 主动关闭
+	*/
+	stop() {
+		this.close("manual");
+	}
+	close(reason) {
+		if (this.closed) return;
+		this.closed = true;
+		this.closedReason = reason;
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = void 0;
+		}
+		try {
+			this.socket?.removeAllListeners();
+			this.socket?.close();
+		} catch {}
+		this.opts.onClose(reason);
+	}
+	send(payload) {
+		try {
+			this.socket?.send(JSON.stringify(payload));
+		} catch (err) {
+			log("error", `${this.opts.appId}: send failed`, err);
+		}
+	}
+	startHeartbeat() {
+		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		this.heartbeatTimer = setInterval(() => {
+			if (this.closed) return;
+			this.send({
+				op: 1,
+				d: this.seq || null
+			});
+		}, this.heartbeatInterval);
+	}
+	identify() {
+		this.send({
+			op: 2,
+			d: {
+				token: `QQBot ${this.opts.getAccessToken()}`,
+				intents: this.opts.intents,
+				shard: [0, 1],
+				properties: {
+					$os: os.type(),
+					$browser: "@karinjs/adapter-qqbot",
+					$device: "@karinjs/adapter-qqbot"
+				}
+			}
+		});
+		log("debug", `${this.opts.appId}: Identify sent, intents=${this.opts.intents}`);
+	}
+	resume() {
+		this.send({
+			op: 6,
+			d: {
+				token: `QQBot ${this.opts.getAccessToken()}`,
+				session_id: this.sessionId,
+				seq: this.seq
+			}
+		});
+		log("debug", `${this.opts.appId}: Resume sent, session=${this.sessionId}, seq=${this.seq}`);
+	}
+	onMessage(raw) {
+		const text = raw.toString();
+		let msg;
+		try {
+			msg = JSON.parse(text);
+		} catch {
+			log("error", `${this.opts.appId}: non-JSON message: ${text}`);
+			return;
+		}
+		log("debug", `${this.opts.appId}: << op=${msg.op} t=${msg.t ?? "-"} s=${msg.s ?? "-"} body=${text.length > 500 ? text.slice(0, 500) + "..." : text}`);
+		switch (msg.op) {
+			case 10:
+				this.heartbeatInterval = msg.d?.heartbeat_interval || 45e3;
+				log("debug", `${this.opts.appId}: Hello received, heartbeat_interval=${this.heartbeatInterval}ms, session=${this.sessionId || "(none)"} seq=${this.seq}`);
+				this.startHeartbeat();
+				if (this.sessionId && this.seq) this.resume();
+				else this.identify();
+				break;
+			case 11:
+				log("debug", `${this.opts.appId}: HeartbeatACK`);
+				break;
+			case 0:
+				if (typeof msg.s === "number") this.seq = msg.s;
+				if (msg.t === "READY") {
+					this.sessionId = msg.d?.session_id || "";
+					log("debug", `${this.opts.appId}: READY received, session_id=${this.sessionId}`);
+				}
+				try {
+					this.opts.onEvent(msg);
+				} catch (err) {
+					log("error", `${this.opts.appId}: onEvent handler threw:`, err);
+				}
+				break;
+			case 7:
+				log("debug", `${this.opts.appId}: server asked reconnect (op:7)`);
+				this.close("reconnect");
+				break;
+			case 9:
+				if (this.sessionId) {
+					log("debug", `${this.opts.appId}: invalid session, will retry with fresh identify`);
+					this.sessionId = "";
+					this.seq = 0;
+					this.close("session_lost");
+				} else {
+					log("error", `${this.opts.appId}: auth_fail (op:9 with no prior session)`);
+					this.close("auth_fail");
+				}
+				break;
+			default: log("debug", `${this.opts.appId}: unhandled opcode ${msg.op}`);
+		}
+	}
+};
+
+//#endregion
+//#region src/connection/ws/intents.ts
+/**
+* intent bit -> 名称（中英双语）
+*/
+const intentBitMap = {
+	[1]: "GUILDS               (频道生命周期)",
+	[2]: "GUILD_MEMBERS        (频道成员变更)",
+	[512]: "GUILD_MESSAGES       (频道消息-私域)",
+	[4096]: "DIRECT_MESSAGE       (频道私信)",
+	[1 << 25]: "GROUP_AND_C2C_EVENT (群聊/单聊消息)",
+	[1 << 30]: "PUBLIC_GUILD_MESSAGES (频道消息-公域)"
+};
+/** 优先级从高到低，回退时从最前面剥离 */
+const priorityIntents = [
+	2,
+	512,
+	1 << 30,
+	4096,
+	1 << 25,
+	1
+];
+/**
+* 计算最大 intents（全部启用）
+*/
+const computeMax = () => priorityIntents.reduce((acc, bit) => acc | bit, 0);
+/**
+* 在当前 intents 基础上去掉最高优先级的一位，得到回退值
+* 返回 0 表示已无可用 intent
+*/
+const computeFallback = (current) => {
+	for (const bit of priorityIntents) if (current & bit) return current & ~bit;
+	return 0;
+};
+/**
+* 将 intents 数值解析为可读名称列表
+*/
+const formatIntentNames = (intents, prefix = "") => {
+	const names = [];
+	for (const [bit, name] of Object.entries(intentBitMap)) if (intents & Number(bit)) names.push(prefix + name);
+	return names.join("\n");
+};
+
+//#endregion
+//#region src/connection/ws/manager.ts
+const conns = /* @__PURE__ */ new Map();
+/** /gateway 接口超时（毫秒） */
+const GATEWAY_FETCH_TIMEOUT_MS = 5e3;
+/**
+* 从 prodApi / sandboxApi 推导兜底的 WSS 地址
+* 官方实际长期返回的也是 wss://{host}/websocket/，不依赖 /gateway 也能直连
+*/
+const buildFallbackWssUrl = (cfg) => {
+	return `${(cfg.sandbox ? cfg.sandboxApi : cfg.prodApi).replace(/^https?:\/\//i, "wss://").replace(/\/+$/, "")}/websocket/`;
+};
+/**
+* 获取网关地址：优先调 /gateway；失败 / 超时 / 限频 → 直接 fallback 到硬编码
+*/
+const fetchGateway = async (cfg) => {
+	const apiUrl = cfg.sandbox ? cfg.sandboxApi : cfg.prodApi;
+	const fallback = buildFallbackWssUrl(cfg);
+	const accessToken = getBotAccessToken(cfg.appId);
+	if (!accessToken) {
+		log("warn", `${cfg.appId}: 无 access_token，使用硬编码 WSS ${fallback}`);
+		return fallback;
+	}
+	try {
+		const { data } = await axios.get(`${apiUrl}/gateway`, {
+			headers: { Authorization: `QQBot ${accessToken}` },
+			timeout: GATEWAY_FETCH_TIMEOUT_MS
+		});
+		if (data?.url) return data.url;
+		log("warn", `${cfg.appId}: /gateway 返回为空，使用硬编码 WSS ${fallback}`);
+		return fallback;
+	} catch (err) {
+		if (axios.isAxiosError(err)) {
+			const response = err.response;
+			const status = response?.status ?? 0;
+			const data = response?.data;
+			const detail = formatOpenAPIError(status, typeof data?.code === "number" ? data.code : void 0, typeof data?.message === "string" ? data.message : void 0);
+			log("warn", `${cfg.appId}: /gateway 调用失败 | ${detail}，使用硬编码 WSS ${fallback}`);
+		} else {
+			const reason = err?.message || "unknown";
+			log("warn", `${cfg.appId}: /gateway 调用失败 (${reason})，使用硬编码 WSS ${fallback}`);
+		}
+		return fallback;
+	}
+};
+/** 重连退避（毫秒） */
+const backoff = (attempt) => Math.min(3e4, 1500 * 2 ** Math.min(attempt, 5)) + random(0, 1500);
+/**
+* 打印 intents 探测汇总
+*/
+const summarize = (appId, finalIntents, success) => {
+	const conn = conns.get(appId);
+	if (!conn || conn.intentHistory.length <= 1) return;
+	const initial = conn.intentHistory[0];
+	const removed = [];
+	for (let i = 1; i < conn.intentHistory.length; i++) {
+		const diff = conn.intentHistory[i - 1] ^ conn.intentHistory[i];
+		for (const [bit, name] of Object.entries(intentBitMap)) if (diff & Number(bit)) removed.push(name.trim());
+	}
+	const removedBlock = removed.length ? "  └─ 被移除 / Removed:\n" + removed.map((n) => `      ${n.trim()}`).join("\n") : "  └─ 被移除 / Removed: 无";
+	log("debug", [
+		`${appId}: intents ${success ? "探测完成 | Probe Done" : "探测失败 | Probe Failed"}`,
+		`  ├─ 初始 / Initial: ${initial}`,
+		`  ├─ 最终 / Final  : ${finalIntents}`,
+		formatIntentNames(finalIntents, "  │   "),
+		removedBlock
+	].join("\n"));
+	conn.intentHistory = [];
+};
+/**
+* 启动连接
+*/
+const start = async (cfg) => {
+	if (cfg.event.type !== 2) return;
+	if (!cfg.appId) return;
+	if (conns.has(cfg.appId)) stop(cfg.appId);
+	const intents = computeMax();
+	conns.set(cfg.appId, {
+		client: null,
+		cfg,
+		intents,
+		intentHistory: [intents],
+		aborted: false
+	});
+	await connect(cfg, intents, 0);
+};
+/**
+* 调度一次重试（统一封装，便于 stop 取消）
+*/
+const schedule = (appId, delay, fn) => {
+	const conn = conns.get(appId);
+	if (!conn || conn.aborted) return;
+	if (conn.pendingTimer) clearTimeout(conn.pendingTimer);
+	conn.pendingTimer = setTimeout(() => {
+		if (conn.aborted) return;
+		conn.pendingTimer = void 0;
+		fn();
+	}, delay);
+};
+/**
+* 内部连接 + 重试
+*/
+const connect = async (cfg, intents, attempt, resume) => {
+	let conn = conns.get(cfg.appId);
+	if (!conn || conn.aborted) return;
+	const gatewayUrl = await fetchGateway(cfg);
+	conn = conns.get(cfg.appId);
+	if (!conn || conn.aborted) return;
+	const client = new WSClient({
+		appId: cfg.appId,
+		gatewayUrl,
+		getAccessToken: () => getBotAccessToken(cfg.appId) || "",
+		intents,
+		resume,
+		onEvent: (ev) => {
+			if (ev.t === "READY") summarize(cfg.appId, intents, true);
+			dispatch(cfg.appId, ev);
+		},
+		onClose: (reason) => onClose(cfg, intents, attempt, reason, client)
+	});
+	conn.client = client;
+	conn.cfg = cfg;
+	conn.intents = intents;
+	if (conn.intentHistory[conn.intentHistory.length - 1] !== intents) conn.intentHistory.push(intents);
+	client.start();
+};
+/**
+* 关闭回调处理
+*/
+const onClose = (cfg, intents, attempt, reason, client) => {
+	if (reason === "manual") {
+		log("debug", `${cfg.appId}: WebSocket 已主动关闭`);
+		return;
+	}
+	const conn = conns.get(cfg.appId);
+	if (!conn || conn.aborted) return;
+	if (reason === "auth_fail") {
+		const fallback = computeFallback(intents);
+		if (fallback && fallback !== intents) {
+			schedule(cfg.appId, 1e3, () => connect(cfg, fallback, 0));
+			return;
+		}
+		summarize(cfg.appId, 0, false);
+		log("error", `${cfg.appId}: 鉴权失败，所有 intents 均不可用，请检查机器人是否已上线`);
+		conn.aborted = true;
+		conns.delete(cfg.appId);
+		return;
+	}
+	const snap = client.snapshot();
+	const resume = reason === "session_lost" ? void 0 : snap.sessionId ? snap : void 0;
+	const delay = backoff(attempt);
+	log("error", `${cfg.appId}: WebSocket 断开 (${reason})，${delay}ms 后重连...`);
+	schedule(cfg.appId, delay, () => connect(cfg, intents, attempt + 1, resume));
+};
+/**
+* 停止连接（同步：标记 abort + 清 pendingTimer + 关 client）
+*/
+const stop = (appId) => {
+	const conn = conns.get(appId);
+	if (!conn) return false;
+	conn.aborted = true;
+	if (conn.pendingTimer) {
+		clearTimeout(conn.pendingTimer);
+		conn.pendingTimer = void 0;
+	}
+	try {
+		conn.client?.stop();
+	} catch {}
+	conns.delete(appId);
+	return true;
+};
+
+//#endregion
+//#region src/core/index.ts
+/**
+* 初始化所有 Bot
+*/
+const initQQBotAdapter = async () => {
+	const cfg = config();
+	logger.debug(`[QQ Official Bot] 开始初始化 ${cfg.length} 个 Bot...`);
+	for (const bot of cfg) try {
+		await createBot(bot);
+	} catch (err) {
+		logger.debug(`[QQ Official Bot] 初始化 Bot 失败 ${bot.appId || "(无 appId)"}:`, err);
+	}
+};
+/**
+* 初始化状态（防止并发触发重复连接）
+*/
+const initState = /* @__PURE__ */ new Map();
+const hashConfig = (bot) => JSON.stringify({
+	appId: bot.appId,
+	secret: bot.secret,
+	tokenApi: bot.tokenApi,
+	prodApi: bot.prodApi,
+	sandboxApi: bot.sandboxApi,
+	sandbox: bot.sandbox,
+	event: bot.event,
+	keyboard: bot.keyboard
+});
+/**
+* 创建单个 Bot 实例
+*/
+const createBot = async (bot) => {
+	const appId = String(bot.appId);
+	if (!appId) {
+		logger.warn("[QQ Official Bot] 配置缺少 appId，跳过");
+		return;
+	}
+	if (bot.event.type === 0) {
+		logger.info(`[QQ Official Bot][${appId}] 事件接收方式为"关闭"，跳过`);
+		return;
+	}
+	const hash = hashConfig(bot);
+	const existing = initState.get(appId);
+	if (existing) {
+		if (existing.hash === hash) return existing.promise;
+		await existing.promise.catch(() => {});
+	}
+	const promise = (async () => {
+		unregisterBot("selfId", appId);
+		stop(appId);
+		offAll(appId);
+		stopTokenRefresh(appId);
+		logger.info(`[QQ Official Bot][${appId}] 获取 access_token...`);
+		await getAccessToken(bot.tokenApi, appId, bot.secret);
+		const baseUrl = bot.sandbox ? bot.sandboxApi : bot.prodApi;
+		const api = new QQBotApi(createAxiosInstance(baseUrl, appId));
+		const me = await api.meta.getMe();
+		const client = new AdapterQQBot(bot, api);
+		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");
+		client.account.subId.id = me.id;
+		client.account.subId.qq = qq;
+		client.account.subId.appid = appId;
+		client.account.subId.union_openid = me.union_openid;
+		bus.on(appId, (ev) => dispatch$1(client, ev));
+		client.adapter.address = baseUrl;
+		client.adapter.secret = bot.secret;
+		client.adapter.version = pkg().version;
+		if (bot.event.type === 2) {
+			client.adapter.index = registerBot("webSocketClient", client);
+			logger.debug(`[QQ Official Bot][${appId}] 已注册为 webSocketClient`);
+			await start(bot);
+		} else if (bot.event.type === 1) {
+			client.adapter.index = registerBot("http", client);
+			logger.debug(`[QQ Official Bot][${appId}] 已注册为 http`);
+		}
+	})();
+	initState.set(appId, {
+		hash,
+		promise
+	});
+	promise.finally(() => {
+		if (initState.get(appId)?.hash === hash) initState.delete(appId);
+	});
+	return promise;
+};
+/**
+* 销毁 bot：注销 + 关 WS + 取消监听 + 停止 token 刷新
+*/
+const destroyBot = (appId) => {
+	unregisterBot("selfId", appId);
+	stop(appId);
+	offAll(appId);
+	stopTokenRefresh(appId);
+};
+bindHandlers(createBot, destroyBot);
+
+//#endregion
+//#region src/core/api/sign.ts
+/**
+* 从 secret 生成密钥对（不足 32 字节循环填充）
+*/
+const generateKeyPair = (seed) => {
+	let finalSeed = seed;
+	while (finalSeed.length < 32) finalSeed = finalSeed.repeat(2);
+	finalSeed = finalSeed.slice(0, 32);
+	const seedBuffer = Buffer.from(finalSeed, "utf-8");
+	return nacl.sign.keyPair.fromSeed(seedBuffer);
+};
+/**
+* 用 secret 对 eventTs + plainToken 签名（hex 编码）
+*/
+const sign = (secret, eventTs, plainToken) => {
+	const { secretKey } = generateKeyPair(secret);
+	const messageBytes = Buffer.from(eventTs + plainToken, "utf-8");
+	const signature = nacl.sign.detached(messageBytes, secretKey);
+	return Buffer.from(signature).toString("hex");
+};
+/**
+* 验证 webhook 推送签名（ed25519）
+* @param secret 机器人密钥
+* @param timestamp x-signature-timestamp 头
+* @param rawBody 原始 body 字符串
+* @param ed25519Hex x-signature-ed25519 头
+*/
+const verifySignature = (secret, timestamp, rawBody, ed25519Hex) => {
+	return sign(secret, timestamp, rawBody) === ed25519Hex;
+};
+
+//#endregion
+//#region src/connection/webhook.ts
+/**
+* 解析请求：读 rawBody + JSON + 字段校验
+* 失败返回 null，并已写入日志
+*/
+const parseRequest = async (req) => {
+	const ip = req.socket.remoteAddress;
+	const rawBody = await new Promise((resolve) => {
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(chunk));
+		req.on("end", () => resolve(chunks.join("")));
+	});
+	const appid = req.headers["x-bot-appid"];
+	if (!appid) {
+		fakeEvent(`未找到 x-bot-appid: ${ip} body: ${rawBody}`);
+		return null;
+	}
+	if (req.headers["user-agent"] !== "QQBot-Callback") {
+		fakeEvent(`User-Agent 非 QQBot-Callback: ${ip} body: ${rawBody}`);
+		return null;
+	}
+	let body;
+	try {
+		body = JSON.parse(rawBody) || {};
+	} catch {
+		fakeEvent(`非法 JSON: ${ip} body: ${rawBody}`);
+		return null;
+	}
+	if (typeof body.op !== "number") {
+		fakeEvent(`缺少 op 字段: ${ip} body: ${rawBody}`);
+		return null;
+	}
+	return {
+		appid,
+		rawBody,
+		body
+	};
+};
+/**
+* QQ 官方 webhook 路由
+* POST /qqbot/webhook
+*/
+const webhookRouting = async (req, res) => {
+	const parsed = await parseRequest(req);
+	if (!parsed) {
+		res.status(200).end();
+		return;
+	}
+	const cfg = getConfig(parsed.appid);
+	if (!cfg) {
+		log("error", `[webhook][${parsed.appid}] 配置文件中未找到对应 appId`);
+		res.status(200).end();
+		return;
+	}
+	if (cfg.event.type !== 1) {
+		log("error", `[webhook][${parsed.appid}] webhook 未启用`);
+		res.status(200).end();
+		return;
+	}
+	if (parsed.body.op === 13) {
+		const eventTs = parsed.body?.d?.event_ts;
+		const plainToken = parsed.body?.d?.plain_token;
+		if (!eventTs || !plainToken) {
+			log("error", `[webhook][${parsed.appid}] 缺少 event_ts/plain_token: ${parsed.rawBody}`);
+			res.status(200).end();
+			return;
+		}
+		const signature = sign(cfg.secret, eventTs, plainToken);
+		log("mark", `[webhook][${parsed.appid}] sign=${signature}`);
+		res.setHeader("Content-Type", "application/json");
+		res.status(200).end(JSON.stringify({
+			plain_token: plainToken,
+			signature
+		}));
+		return;
+	}
+	const ed25519 = req.headers["x-signature-ed25519"];
+	const timestamp = req.headers["x-signature-timestamp"];
+	if (!verifySignature(cfg.secret, timestamp, parsed.rawBody, ed25519)) {
+		fakeEvent(`签名验证失败 appid=${parsed.appid} headerSig=${ed25519} body=${parsed.rawBody}`);
+		res.status(200).end();
+		return;
+	}
+	res.status(200).end();
+	dispatch(parsed.appid, parsed.body);
+};
+
+//#endregion
+//#region src/connection/routing.ts
+/**
+* 初始化路由
+* 创建 /qqbot/webhook 路由用于接收QQ机器人事件
+*/
+const createRouting = () => {
+	const router = express.Router();
+	router.use("/webhook", webhookRouting);
+	app.use("/qqbot", router);
+};
+
+//#endregion
+//#region src/index.ts
+logger.info(`${logger.violet(`[插件:${pkg().version}]`)} ${logger.green(basename)} 初始化完成~`);
+createRouting();
+const printOnboardBanner = () => {
+	console.log();
+	console.log("  ==========================================");
+	console.log("  未检测到 QQBot 配置");
+	console.log("  请使用任意可用 bot（如 OneBot / Console 适配器）");
+	console.log("  对机器人发送指令： #QQ登录");
+	console.log("  扫码授权完成后会自动写入配置并完成初始化");
+	console.log();
+	console.log("  ⚠ 注意：扫码授权会刷新该机器人的 secret，旧 secret 立即失效");
+	console.log("  ==========================================");
+	console.log();
+};
+const bootstrap = async () => {
+	if (needQrOnboard()) {
+		printOnboardBanner();
+		return;
+	}
+	try {
+		await initQQBotAdapter();
+	} catch (err) {
+		log("error", "初始化适配器失败:", err);
+	}
+};
+bootstrap();
+
+//#endregion
+export {  };