@karinjs/adapter-qqbot 1.3.1 → 2.1.0

package/dist/index.js

@@ -1,100 +1,4745 @@
-import {
-  basename,
-  config_exports,
-  event,
-  fakeEvent,
-  getConfig,
-  initQQBotAdapter,
-  sign
-} from "./chunk-PYOUSZ6B.js";
-
-// src/index.ts
-import { logger as logger2 } from "node-karin";
-
-// src/connection/routing.ts
-import { app } from "node-karin";
+import { c as log, l as basename, n as config, o as pkg, r as getConfig, t as bindHandlers } from "./config-DKa7596f.js";
+import { i as random, n as getImageSize, r as handleUrl, t as fakeEvent } from "./common-by1GpV0b.js";
+import "./utils-BPbnNAix.js";
+import { t as getMessageStore } from "./message-O73AeL_P.js";
+import { t as needQrOnboard } from "./onboard-DPWgX39H.js";
+import { AdapterBase, app, buttonHandle, createDirectMessage, createFriendDecreaseNotice, createFriendIncreaseNotice, createFriendMessage, createGroupMemberAddNotice, createGroupMemberDelNotice, createGroupMessage, createGuildMessage, fileToUrl, fileToUrlHandlerKey, handler, karin as karin$1, karinToQQBot, logger, registerBot, segment, unregisterBot } from "node-karin";
+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 crypto from "node:crypto";
+import { open, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath as fileURLToPath$1 } from "node:url";
+import os from "node:os";
+import EventEmitter from "node:events";
+import { WebSocket } from "node-karin/ws";
 import express from "node-karin/express";
+import nacl from "tweetnacl";
 
-// src/connection/webhook.ts
-import { logger } from "node-karin";
-var webhookRouting = async (req, res) => {
-  var _a, _b, _c, _d;
-  const data = await checkAppid(req, res);
-  if (!data) return;
-  const cfg = getConfig(data.appid);
-  if (!cfg) {
-    logger.error(`[\u914D\u7F6E\u9519\u8BEF][${data.appid}] \u914D\u7F6E\u6587\u4EF6\u4E2D\u672A\u627E\u5230\u5BF9\u5E94\u7684appid\uFF0C\u8BF7\u68C0\u67E5\u914D\u7F6E\u6587\u4EF6`);
-    return;
-  }
-  if (cfg.event.type !== 1) {
-    logger.error(`[\u914D\u7F6E\u9519\u8BEF][${data.appid}] webhook\u672A\u542F\u7528\uFF0C\u8BF7\u68C0\u67E5\u914D\u7F6E\u6587\u4EF6`);
-    return;
-  }
-  if (data.body.op === 13) {
-    const eventTs = (_b = (_a = data.body) == null ? void 0 : _a.d) == null ? void 0 : _b.event_ts;
-    const plainToken = (_d = (_c = data.body) == null ? void 0 : _c.d) == null ? void 0 : _d.plain_token;
-    if (!eventTs || !plainToken) {
-      logger.error(`[\u8BF7\u6C42\u6570\u636E\u9519\u8BEF][${data.appid}] \u672A\u627E\u5230 event_ts \u6216 plain_token: ${data.rawBody}`);
-      return;
-    }
-    const signature2 = sign(cfg.secret, eventTs, plainToken);
-    logger.mark(`[signature][${data.appid}] ${signature2}`);
-    res.setHeader("Content-Type", "application/json");
-    res.status(200).end(JSON.stringify({ plain_token: plainToken, signature: signature2 }));
-    return;
-  }
-  const ed25519 = req.headers["x-signature-ed25519"];
-  const signature = sign(cfg.secret, req.headers["x-signature-timestamp"], data.rawBody);
-  if (ed25519 !== signature) {
-    fakeEvent(`\u7B7E\u540D\u9A8C\u8BC1\u5931\u8D25:
-appid: ${data.appid}
-ed25519: ${ed25519}
-\u5B9E\u9645\u7B7E\u540D: ${signature}
-body: ${data.rawBody}`);
-    return;
-  }
-  event.emit(data.appid, data.body);
-};
-var checkAppid = async (req, res) => {
-  let response = true;
-  try {
-    const ip = req.socket.remoteAddress;
-    const appid = req.headers["x-bot-appid"];
-    const rawBody = await new Promise((resolve) => {
-      const raw = [];
-      req.on("data", (chunk) => raw.push(chunk));
-      req.on("end", () => resolve(raw.join("")));
-    });
-    if (!appid) {
-      fakeEvent(`\u672A\u627E\u5230 x-bot-appid: ${ip} body: ${rawBody}`);
-      return;
-    }
-    const userAgent = req.headers["user-agent"];
-    if (userAgent !== "QQBot-Callback") {
-      fakeEvent(`\u672A\u627E\u5230 User-Agent: ${ip} body: ${rawBody}`);
-      return;
-    }
-    const body = JSON.parse(rawBody) || {};
-    if (typeof body.op !== "number") {
-      fakeEvent(`\u975E\u6CD5\u8BF7\u6C42\u4F53\uFF0C\u672A\u627E\u5230 op: ${ip} body: ${rawBody}`);
-      return;
-    } else if (body.op === 13) {
-      response = false;
-    }
-    return { appid, rawBody, body };
-  } finally {
-    response && res.status(200).end();
-  }
-};
-
-// src/connection/routing.ts
-var createRouting = () => {
-  const router = express.Router();
-  router.use("/webhook", webhookRouting);
-  app.use("/qqbot", router);
-};
-
-// src/index.ts
-logger2.info(`${logger2.violet(`[\u63D2\u4EF6:${config_exports.pkg().version}]`)} ${logger2.green(basename)} \u521D\u59CB\u5316\u5B8C\u6210~`);
+//#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(redactRequestData(options)), { length: 500 })}`);
+		if (!response) {
+			const reason = [err.code, err.message].filter(Boolean).join(" | ");
+			if (reason) lines.push(`请求错误: ${reason}`);
+		}
+		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));
+};
+/**
+* 请求失败日志脱敏，避免富媒体 file_data/base64 被完整 stringify。
+* @param value 请求数据。
+* @returns 脱敏后的请求数据。
+*/
+const redactRequestData = (value) => {
+	if (!value || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map((item) => redactRequestData(item));
+	const source = value;
+	const result = {};
+	for (const [key, item] of Object.entries(source)) if (key === "file_data" && typeof item === "string") result[key] = `<redacted ${item.length} chars>`;
+	else result[key] = redactRequestData(item);
+	return result;
+};
+/**
+* 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, timeout) {
+		try {
+			const { data } = await this.axios.post(path, body, {
+				headers,
+				timeout
+			});
+			return data;
+		} catch (err) {
+			throw formatError(path, body, err);
+		}
+	}
+	async put(path, body = {}, headers, timeout) {
+		try {
+			const { data } = await this.axios.put(path, body, {
+				headers,
+				timeout
+			});
+			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/upload-cache.ts
+/** 单进程内最多缓存的 file_info 数量，避免长期运行时内存无限增长。 */
+const MAX_CACHE_SIZE = 500;
+/** 比 QQ 返回的 ttl 提前失效，避免临界点使用到刚过期的 file_info。 */
+const TTL_SAFETY_MARGIN_SECONDS = 60;
+/** QQ 返回极短 ttl 时仍保留一个最小可用窗口。 */
+const MIN_EFFECTIVE_TTL_SECONDS = 10;
+const cache = /* @__PURE__ */ new Map();
+/**
+* 构建 file_info 缓存键。
+*
+* 虽然 QQ 文档说同一类会话内 file_info 可复用，但这里仍按 peer 隔离，
+* 以避开未文档化的服务端限制。
+*
+* @param scene 上传场景。
+* @param peer openid 或 group_openid。
+* @param type 富媒体类型。
+* @param contentHash 文件内容 hash。
+* @returns 缓存键。
+*/
+const cacheKey = (scene, peer, type, contentHash) => [
+	scene,
+	peer,
+	type,
+	contentHash
+].join("");
+/**
+* 惰性清理过期缓存。
+* @param now 当前时间戳。
+*/
+const cleanupExpired = (now = Date.now()) => {
+	for (const [key, entry] of cache) if (entry.expiresAt <= now) cache.delete(key);
+};
+/**
+* 缓存满时淘汰最旧的一批条目。
+*/
+const evictOldest = () => {
+	if (cache.size < MAX_CACHE_SIZE) return;
+	cleanupExpired();
+	if (cache.size < MAX_CACHE_SIZE) return;
+	const entries = [...cache.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+	const removeCount = Math.max(1, Math.ceil(MAX_CACHE_SIZE / 2));
+	for (const [key] of entries.slice(0, removeCount)) cache.delete(key);
+};
+/**
+* 读取可复用的上传结果。
+*
+* @param scene 上传场景。
+* @param peer openid 或 group_openid。
+* @param type 富媒体类型。
+* @param contentHash 文件内容 hash。
+* @returns 未命中或过期时返回 null。
+*/
+const getCachedUpload = (scene, peer, type, contentHash) => {
+	const key = cacheKey(scene, peer, type, contentHash);
+	const entry = cache.get(key);
+	if (!entry) return null;
+	if (entry.expiresAt <= Date.now()) {
+		cache.delete(key);
+		return null;
+	}
+	return { ...entry.response };
+};
+/**
+* 写入上传结果缓存。
+*
+* @param scene 上传场景。
+* @param peer openid 或 group_openid。
+* @param type 富媒体类型。
+* @param contentHash 文件内容 hash。
+* @param response 上传接口返回。
+*/
+const setCachedUpload = (scene, peer, type, contentHash, response) => {
+	if (!response.file_info) return;
+	evictOldest();
+	const now = Date.now();
+	const ttl = Number(response.ttl);
+	const effectiveTtl = ttl > 0 ? Math.max(ttl - TTL_SAFETY_MARGIN_SECONDS, MIN_EFFECTIVE_TTL_SECONDS) * 1e3 : Number.POSITIVE_INFINITY;
+	cache.set(cacheKey(scene, peer, type, contentHash), {
+		response: { ...response },
+		expiresAt: ttl > 0 ? now + effectiveTtl : Number.POSITIVE_INFINITY,
+		createdAt: now
+	});
+};
+
+//#endregion
+//#region src/core/api/media.ts
+const FILE_TYPE = {
+	image: 1,
+	video: 2,
+	record: 3,
+	file: 4
+};
+/** 各类资源的 QQ 上传上限。 */
+const MAX_UPLOAD_SIZE = {
+	image: 30 * 1024 * 1024,
+	video: 100 * 1024 * 1024,
+	record: 20 * 1024 * 1024,
+	file: 100 * 1024 * 1024
+};
+/** 上传错误中展示的资源类型名称。 */
+const MEDIA_TYPE_LABEL = {
+	image: "图片",
+	video: "视频",
+	record: "语音",
+	file: "文件"
+};
+/** fallback 上传超过该大小时走 QQ 分片上传。 */
+const LARGE_UPLOAD_THRESHOLD = 5 * 1024 * 1024;
+/** QQ upload_prepare 需要的前 10,002,432 字节 MD5。 */
+const MD5_10M_SIZE = 10002432;
+/** 分片上传时没有业务文件名的默认值。 */
+const DEFAULT_FILENAME$1 = {
+	image: "image.jpg",
+	video: "video.mp4",
+	record: "record.mp3",
+	file: "file.bin"
+};
+/** 富媒体上传比普通接口慢，尤其本地视频会走 file_data。 */
+const MEDIA_UPLOAD_TIMEOUT = 12e4;
+/** URL 回源下载兜底超时。 */
+const MEDIA_DOWNLOAD_TIMEOUT = 12e4;
+/** 每个分片 PUT 到 QQ 临时地址的超时时间。 */
+const PART_UPLOAD_TIMEOUT = 3e5;
+/** 每个分片 PUT 失败后的重试次数。 */
+const PART_UPLOAD_RETRIES = 2;
+/** upload_part_finish 普通失败重试次数。 */
+const PART_FINISH_RETRIES = 2;
+/** upload_part_finish 普通失败重试基础间隔。 */
+const PART_FINISH_BASE_DELAY = 1e3;
+/** upload_part_finish 命中这些业务码时，需要按服务端给出的窗口持续重试。 */
+const PART_FINISH_RETRYABLE_CODES = /* @__PURE__ */ new Set([40093001]);
+/** 服务端未返回 retry_timeout 时，持续重试的默认时间。 */
+const PART_FINISH_DEFAULT_RETRY_TIMEOUT = 120 * 1e3;
+/** 持续重试窗口上限，避免服务端返回异常值导致任务长时间占用。 */
+const PART_FINISH_MAX_RETRY_TIMEOUT = 600 * 1e3;
+/** 持续重试时的固定间隔。 */
+const PART_FINISH_RETRY_INTERVAL = 1e3;
+/** 分片完成接口失败重试次数。 */
+const COMPLETE_UPLOAD_RETRIES = 2;
+/** 分片完成接口失败重试基础间隔。 */
+const COMPLETE_UPLOAD_BASE_DELAY = 2e3;
+/** upload_prepare 返回该业务码时表示大文件上传额度受限。 */
+const UPLOAD_PREPARE_DAILY_LIMIT_CODE = 40093002;
+/** QQ 没返回建议并发数时的默认并发。 */
+const DEFAULT_PART_CONCURRENCY = 1;
+/** 本地限制的最大分片并发，避免服务端返回过大值。 */
+const MAX_PART_CONCURRENCY = 10;
+/** HTTP(S) URL 可直接交给 QQ 平台拉取。 */
+const HTTP_URL_RE$1 = /^https?:\/\//i;
+/** Karin 常见 base64 图片/媒体前缀。 */
+const BASE64_PREFIX_RE = /^base64:\/\//i;
+/** 标准 data URL 的 base64 前缀。 */
+const DATA_URL_BASE64_RE = /^data:[^;,]+;base64,/i;
+/**
+* 判断字符串是否明显是本地文件路径。
+* 不明显的字符串按裸 base64 兼容处理，避免破坏旧调用方式。
+*/
+const isLocalPathSource = (source) => {
+	return source.startsWith("file://") || /^[a-zA-Z]:[\\/]/.test(source) || source.startsWith("/") || source.startsWith("\\") || source.startsWith("./") || source.startsWith("../") || source.startsWith(".\\") || source.startsWith("..\\");
+};
+/**
+* 将 file:// 或普通路径统一为本地文件系统路径。
+* @param source 本地路径或 file:// URL。
+* @returns 可直接传给 fs 的本地路径。
+*/
+const normalizeLocalPath = (source) => {
+	return source.startsWith("file://") ? fileURLToPath$1(source) : source;
+};
+/**
+* 去掉 Karin/标准 data URL 的 base64 前缀。
+* @param source base64 字符串。
+* @returns QQ 上传接口需要的纯 base64 数据。
+*/
+const stripBase64Prefix = (source) => {
+	return source.replace(DATA_URL_BASE64_RE, "").replace(BASE64_PREFIX_RE, "");
+};
+/**
+* 将文件大小格式化为便于阅读的字符串。
+* @param bytes 文件字节数。
+* @returns 格式化后的文件大小。
+*/
+const formatBytes = (bytes) => {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+};
+/**
+* 规范化上传文件名，避免把路径当成文件名交给 QQ。
+* @param type 富媒体类型。
+* @param name 候选文件名。
+* @returns 安全的基础文件名。
+*/
+const normalizeUploadFileName = (type, name) => {
+	const value = name?.trim();
+	if (!value) return DEFAULT_FILENAME$1[type];
+	return path.basename(value) || DEFAULT_FILENAME$1[type];
+};
+/**
+* 检查 fallback 资源大小是否超过 QQ 对应类型上限。
+* @param type 富媒体类型。
+* @param size 文件大小。
+*/
+const assertUploadSize = (type, size) => {
+	const limit = MAX_UPLOAD_SIZE[type];
+	if (size <= limit) return;
+	throw new Error(`${MEDIA_TYPE_LABEL[type]}过大：${formatBytes(size)}，QQ 上传上限为 ${formatBytes(limit)}`);
+};
+/**
+* 读取本地媒体文件并转为 QQ 上传接口需要的 base64。
+* @param source 本地路径或 file:// URL。
+* @returns 文件内容的 base64 字符串。
+*/
+const readLocalFileAsBase64 = async (source) => {
+	return readFile(normalizeLocalPath(source), "base64");
+};
+/**
+* 下载远程媒体并返回 Buffer。
+* @param url 远程媒体 URL。
+* @returns 文件内容。
+*/
+const downloadRemoteAsBuffer = async (url) => {
+	const { data } = await axios.get(url, {
+		responseType: "arraybuffer",
+		timeout: MEDIA_DOWNLOAD_TIMEOUT,
+		maxBodyLength: Infinity,
+		maxContentLength: Infinity
+	});
+	return Buffer.from(data);
+};
+/**
+* 下载远程媒体并转为 QQ 上传接口需要的 base64。
+* @param url 远程媒体 URL。
+* @returns 文件内容的 base64 字符串。
+*/
+const downloadRemoteAsBase64 = async (url) => {
+	return (await downloadRemoteAsBuffer(url)).toString("base64");
+};
+/**
+* 将 Karin 的 file 字段归一为 QQ 上传接口支持的 url / file_data。
+* @param source HTTP URL、本地路径、data URL、base64:// 或裸 base64。
+* @returns 可合并进上传请求体的来源字段。
+*/
+const buildUploadSource = async (source) => {
+	const value = source.trim();
+	if (HTTP_URL_RE$1.test(value)) return { url: value };
+	if (DATA_URL_BASE64_RE.test(value) || BASE64_PREFIX_RE.test(value)) return { file_data: stripBase64Prefix(value) };
+	if (isLocalPathSource(value)) return { file_data: await readLocalFileAsBase64(value) };
+	return { file_data: value };
+};
+/**
+* 将 fallback 来源归一为可判断大小、可分片读取的形式。
+*
+* @param type 富媒体类型。
+* @param source Karin 消息段里的 file 字段。
+* @param fileName 可选文件名。
+* @returns 可用于普通上传或分片上传的来源。
+*/
+const buildFallbackSource = async (type, source, fileName) => {
+	const value = source.trim();
+	const normalizedName = normalizeUploadFileName(type, fileName);
+	if (HTTP_URL_RE$1.test(value)) {
+		const buffer = await downloadRemoteAsBuffer(value);
+		return {
+			kind: "buffer",
+			buffer,
+			size: buffer.length,
+			fileName: normalizedName
+		};
+	}
+	if (DATA_URL_BASE64_RE.test(value) || BASE64_PREFIX_RE.test(value)) {
+		const buffer = Buffer.from(stripBase64Prefix(value), "base64");
+		return {
+			kind: "buffer",
+			buffer,
+			size: buffer.length,
+			fileName: normalizedName
+		};
+	}
+	if (isLocalPathSource(value)) {
+		const file = normalizeLocalPath(value);
+		const info = await stat(file);
+		const name = normalizeUploadFileName(type, fileName || path.basename(file));
+		return {
+			kind: "local",
+			file,
+			size: info.size,
+			fileName: name
+		};
+	}
+	const buffer = Buffer.from(value, "base64");
+	return {
+		kind: "buffer",
+		buffer,
+		size: buffer.length,
+		fileName: normalizedName
+	};
+};
+/**
+* 读取 fallback 来源的小文件内容并转成 base64。
+* @param source fallback 来源。
+* @returns base64 字符串。
+*/
+const readFallbackSourceAsBase64 = async (source) => {
+	if (source.kind === "buffer") return source.buffer.toString("base64");
+	return readFile(source.file, "base64");
+};
+/**
+* 计算 QQ upload_prepare 所需的 hash。
+*
+* @param source fallback 来源。
+* @returns 完整 MD5、完整 SHA1 与前 10MB MD5。
+*/
+const computeUploadHashes = async (source) => {
+	if (source.kind === "buffer") {
+		const md5 = crypto.createHash("md5").update(source.buffer).digest("hex");
+		return {
+			md5,
+			sha1: crypto.createHash("sha1").update(source.buffer).digest("hex"),
+			md510m: source.size > MD5_10M_SIZE ? crypto.createHash("md5").update(source.buffer.subarray(0, MD5_10M_SIZE)).digest("hex") : md5
+		};
+	}
+	return new Promise((resolve, reject) => {
+		const md5 = crypto.createHash("md5");
+		const sha1 = crypto.createHash("sha1");
+		const md510m = crypto.createHash("md5");
+		const needsMd510m = source.size > MD5_10M_SIZE;
+		let consumed = 0;
+		const stream = createReadStream(source.file);
+		stream.on("data", (chunk) => {
+			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			md5.update(buffer);
+			sha1.update(buffer);
+			if (needsMd510m) {
+				const remaining = MD5_10M_SIZE - consumed;
+				if (remaining > 0) md510m.update(remaining >= buffer.length ? buffer : buffer.subarray(0, remaining));
+			}
+			consumed += buffer.length;
+		});
+		stream.on("end", () => {
+			const md5Hex = md5.digest("hex");
+			resolve({
+				md5: md5Hex,
+				sha1: sha1.digest("hex"),
+				md510m: needsMd510m ? md510m.digest("hex") : md5Hex
+			});
+		});
+		stream.on("error", reject);
+	});
+};
+/**
+* 从 fallback 来源读取指定分片。
+* @param source fallback 来源。
+* @param handle 本地文件句柄，buffer 来源不需要。
+* @param offset 分片起始位置。
+* @param length 分片长度。
+* @returns 分片内容。
+*/
+const readPart = async (source, handle, offset, length) => {
+	if (source.kind === "buffer") return source.buffer.subarray(offset, offset + length);
+	if (!handle) throw new Error("读取分片失败：文件句柄不存在");
+	const buffer = Buffer.alloc(length);
+	const { bytesRead } = await handle.read(buffer, 0, length, offset);
+	return bytesRead === length ? buffer : buffer.subarray(0, bytesRead);
+};
+/**
+* 带有限重试地把单个分片 PUT 到 QQ 返回的临时地址。
+*
+* @param url QQ 返回的分片上传地址。
+* @param data 分片内容。
+* @param partIndex 分片序号。
+* @param totalParts 总分片数。
+*/
+const putPart = async (url, data, partIndex, totalParts) => {
+	let lastError;
+	for (let attempt = 0; attempt <= PART_UPLOAD_RETRIES; attempt++) try {
+		await axios.put(url, data, {
+			headers: {
+				"Content-Type": "application/octet-stream",
+				"Content-Length": String(data.length)
+			},
+			timeout: PART_UPLOAD_TIMEOUT,
+			maxBodyLength: Infinity,
+			maxContentLength: Infinity
+		});
+		return;
+	} catch (err) {
+		lastError = err;
+		if (attempt < PART_UPLOAD_RETRIES) await new Promise((resolve) => setTimeout(resolve, 500 * (attempt + 1)));
+	}
+	throw new Error(`上传分片失败：${partIndex}/${totalParts}，${lastError instanceof Error ? lastError.message : String(lastError)}`);
+};
+/**
+* 使用固定并发执行异步任务。
+* @param tasks 待执行任务。
+* @param concurrency 最大并发。
+*/
+const runWithConcurrency = async (tasks, concurrency) => {
+	let index = 0;
+	const workerCount = Math.max(1, Math.min(concurrency, tasks.length));
+	const workers = Array.from({ length: workerCount }, async () => {
+		while (index < tasks.length) {
+			const current = index;
+			index += 1;
+			await tasks[current]();
+		}
+	});
+	await Promise.all(workers);
+};
+/**
+* 等待指定时间。
+* @param ms 毫秒数。
+*/
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* 从 axios 原始错误或已格式化错误文本里提取 QQ 业务错误码。
+* @param err 待检查的错误。
+* @returns 业务错误码。
+*/
+const openApiCode = (err) => {
+	if (axios.isAxiosError(err)) {
+		const data = err.response?.data;
+		const code = typeof data?.code === "number" ? data.code : typeof data?.err_code === "number" ? data.err_code : void 0;
+		if (code !== void 0) return code;
+	}
+	if (err instanceof Error) {
+		const match = err.message.match(/\[Code\s+(\d+)\]/);
+		if (match) return Number(match[1]);
+	}
+};
+/**
+* 判断 upload_part_finish 是否命中需要持续重试的服务端状态。
+* @param err 请求错误。
+* @returns 是否需要持续重试。
+*/
+const shouldRetryPartFinishPersistently = (err) => {
+	const code = openApiCode(err);
+	return code !== void 0 && PART_FINISH_RETRYABLE_CODES.has(code);
+};
+/**
+* 将未知错误重新抛出为 Error。
+* @param err 原始错误。
+*/
+const throwError = (err) => {
+	if (err instanceof Error) throw err;
+	throw new Error(typeof err === "string" ? err : JSON.stringify(err));
+};
+/**
+* 富媒体上传
+*/
+var MediaApi = class extends Http {
+	/**
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param type 文件类型
+	* @param source http url、本地路径或 base64 字符串
+	* @param srvSendMsg 上传后是否由服务端直接发送
+	* @param fileName 文件消息的展示文件名
+	*/
+	async upload(scene, peer, type, source, srvSendMsg = false, fileName) {
+		const sourceBody = await buildUploadSource(source);
+		const body = {
+			file_type: FILE_TYPE[type],
+			srv_send_msg: srvSendMsg
+		};
+		Object.assign(body, sourceBody);
+		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);
+		} catch (err) {
+			if (!sourceBody.url) throw err;
+			const fallbackBody = {
+				...body,
+				file_data: await downloadRemoteAsBase64(sourceBody.url)
+			};
+			delete fallbackBody.url;
+			return this.post(path, fallbackBody, void 0, MEDIA_UPLOAD_TIMEOUT);
+		}
+	}
+	/**
+	* 上传没有公网 URL 处理器可用时的 fallback 富媒体资源。
+	*
+	* 较大的 fallback 资源会优先使用 QQ 分片上传，提高直接发送成功率。
+	* `srvSendMsg` 为 true 时保留普通上传路径，避免分片完成接口与服务端直接发送语义冲突。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param type 文件类型
+	* @param source 本地路径、http url、data URL、base64:// 或裸 base64
+	* @param srvSendMsg 上传后是否由服务端直接发送
+	* @param fileName 文件消息的展示文件名
+	* @returns 上传结果，包含后续发送消息所需的 file_info
+	*/
+	async uploadFallback(scene, peer, type, source, srvSendMsg = false, fileName) {
+		const fallbackSource = await buildFallbackSource(type, source, fileName);
+		assertUploadSize(type, fallbackSource.size);
+		const hashes = !srvSendMsg ? await computeUploadHashes(fallbackSource) : void 0;
+		if (hashes) {
+			const cached = getCachedUpload(scene, peer, type, hashes.md5);
+			if (cached) return cached;
+		}
+		if (!srvSendMsg && fallbackSource.size >= LARGE_UPLOAD_THRESHOLD) {
+			const response = await this.uploadChunked(scene, peer, type, fallbackSource, hashes);
+			if (hashes) setCachedUpload(scene, peer, type, hashes.md5, response);
+			return response;
+		}
+		const body = {
+			file_type: FILE_TYPE[type],
+			srv_send_msg: srvSendMsg,
+			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);
+		if (hashes) setCachedUpload(scene, peer, type, hashes.md5, response);
+		return response;
+	}
+	/**
+	* 确认单个分片已完成上传。
+	*
+	* QQ 有时会在分片刚 PUT 完时短暂返回 40093001，此时需要在服务端给出的
+	* retry_timeout 窗口内持续重试，而不是直接判定整个大文件上传失败。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param body upload_part_finish 请求体
+	* @param retryTimeout 服务端返回的持续重试秒数
+	*/
+	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);
+			return;
+		} catch (err) {
+			if (shouldRetryPartFinishPersistently(err)) {
+				await this.retryUploadPartFinish(scene, peer, body, retryTimeout);
+				return;
+			}
+			lastError = err;
+			if (attempt < PART_FINISH_RETRIES) await sleep(PART_FINISH_BASE_DELAY * 2 ** attempt);
+		}
+		throwError(lastError);
+	}
+	/**
+	* 持续重试 upload_part_finish 的短暂服务端状态。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param body upload_part_finish 请求体
+	* @param retryTimeout 服务端返回的持续重试秒数
+	*/
+	async retryUploadPartFinish(scene, peer, body, retryTimeout) {
+		const retryTimeoutMs = retryTimeout ? Math.min(Number(retryTimeout) * 1e3, PART_FINISH_MAX_RETRY_TIMEOUT) : PART_FINISH_DEFAULT_RETRY_TIMEOUT;
+		const deadline = Date.now() + retryTimeoutMs;
+		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);
+			return;
+		} catch (err) {
+			lastError = err;
+			if (!shouldRetryPartFinishPersistently(err)) throwError(err);
+			attempts += 1;
+			await sleep(Math.min(PART_FINISH_RETRY_INTERVAL, Math.max(0, deadline - Date.now())));
+		}
+		throw new Error(`upload_part_finish 持续重试超时：${Math.round(retryTimeoutMs / 1e3)}s，已重试 ${attempts} 次，最后错误：${lastError instanceof Error ? lastError.message : String(lastError)}`);
+	}
+	/**
+	* 完成 QQ 分片上传，并对短暂失败做有限重试。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param uploadId upload_prepare 返回的上传任务 ID
+	* @returns 上传结果
+	*/
+	async completeChunkedUpload(scene, peer, uploadId) {
+		let lastError;
+		const body = { upload_id: uploadId };
+		for (let attempt = 0; attempt <= COMPLETE_UPLOAD_RETRIES; attempt++) try {
+			return await this.post(`/v2/${scene}s/${peer}/files`, body, void 0, MEDIA_UPLOAD_TIMEOUT);
+		} catch (err) {
+			lastError = err;
+			if (attempt < COMPLETE_UPLOAD_RETRIES) await sleep(COMPLETE_UPLOAD_BASE_DELAY * 2 ** attempt);
+		}
+		return throwError(lastError);
+	}
+	/**
+	* 使用 QQ 官方分片协议上传 fallback 大资源。
+	*
+	* 流程为：准备上传 -> PUT 每个分片 -> 确认每个分片 -> 完成上传。
+	*
+	* @param scene user(单聊) / group(群聊)
+	* @param peer openid 或 group_openid
+	* @param type 文件类型
+	* @param source 已归一化的 fallback 来源
+	* @param preparedHashes 预计算的文件 hash
+	* @returns 上传结果，包含后续发送消息所需的 file_info
+	*/
+	async uploadChunked(scene, peer, type, source, preparedHashes) {
+		const hashes = preparedHashes || await computeUploadHashes(source);
+		const prepareBody = {
+			file_type: FILE_TYPE[type],
+			file_name: source.fileName,
+			file_size: source.size,
+			md5: hashes.md5,
+			sha1: hashes.sha1
+		};
+		prepareBody["md5_10m"] = hashes.md510m;
+		const prepare = await this.post(`/v2/${scene}s/${peer}/upload_prepare`, prepareBody, void 0, MEDIA_UPLOAD_TIMEOUT).catch((err) => {
+			if (openApiCode(err) === UPLOAD_PREPARE_DAILY_LIMIT_CODE) throw new Error(`QQ 大文件上传额度已达上限，${MEDIA_TYPE_LABEL[type]}暂时无法通过 fallback 直传：${source.fileName} (${formatBytes(source.size)})`);
+			return throwError(err);
+		});
+		if (!prepare.parts.length) throw new Error("分片上传准备失败：QQ 未返回分片信息");
+		const concurrency = Math.min(prepare.concurrency || DEFAULT_PART_CONCURRENCY, MAX_PART_CONCURRENCY, prepare.parts.length);
+		const handle = source.kind === "local" ? await open(source.file, "r") : void 0;
+		try {
+			await runWithConcurrency(prepare.parts.map((part) => async () => {
+				const offset = (part.index - 1) * prepare.block_size;
+				const data = await readPart(source, handle, offset, Math.min(prepare.block_size, source.size - offset));
+				const md5 = crypto.createHash("md5").update(data).digest("hex");
+				await putPart(part.presigned_url, data, part.index, prepare.parts.length);
+				await this.finishUploadPart(scene, peer, {
+					upload_id: prepare.upload_id,
+					part_index: part.index,
+					block_size: data.length,
+					md5
+				}, prepare.retry_timeout);
+			}), concurrency);
+		} finally {
+			await handle?.close().catch(() => void 0);
+		}
+		return this.completeChunkedUpload(scene, peer, prepare.upload_id);
+	}
+};
+
+//#endregion
+//#region src/core/api/interaction.ts
+/** QQ 客户端回调按钮需要快速 ACK，超时必须小于平台等待窗口。 */
+const INTERACTION_ACK_TIMEOUT = 2800;
+/**
+* INTERACTION_CREATE 回应
+*/
+var InteractionApi = class extends Http {
+	/**
+	* @param interactionId INTERACTION_CREATE 事件中的 id
+	* @param code 0 成功 / 1 操作失败 / 2 操作频繁 / 3 重复操作 / 4 无权限 / 5 仅管理员
+	*/
+	async ack(interactionId, code = 0) {
+		await this.put(`/interactions/${interactionId}`, { code }, void 0, INTERACTION_ACK_TIMEOUT);
+	}
+};
+
+//#endregion
+//#region src/core/api/meta.ts
+/**
+* 元信息接口：@me / dms / gateway
+*/
+var MetaApi = class extends Http {
+	/** 当前机器人详情 */
+	getMe() {
+		return this.get("/users/@me");
+	}
+	/** 创建频道私信会话 */
+	createDms(recipientId, srcGuildId) {
+		return this.post("/users/@me/dms", {
+			recipient_id: recipientId,
+			source_guild_id: srcGuildId
+		});
+	}
+	/** 获取通用 WSS 地址 */
+	getGateway() {
+		return this.get("/gateway");
+	}
+};
+
+//#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 富媒体消息体 */
+	media(fileInfo) {
+		return {
+			msg_type: 7,
+			media: { file_info: fileInfo }
+		};
+	}
+};
+/**
+* 构造频道请求体
+*/
+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/utils/user-agent.ts
+const USER_AGENT_SUFFIX = "Karin";
+/**
+* 构建 QQBot HTTP / WebSocket 使用的 User-Agent。
+*/
+const getUserAgent = () => {
+	return `QQBotAdapter/${String(pkg().version || "unknown")} (Node/${process.versions.node}; ${os.platform()}; ${USER_AGENT_SUFFIX}/${process.env.KARIN_VERSION || "unknown"})`;
+};
+
+//#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
+		}, { headers: { "User-Agent": getUserAgent() } });
+	} 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",
+			"User-Agent": getUserAgent()
+		},
+		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/button-enter.ts
+/** QQ 私聊直发文本链标签。 */
+const COMMAND_ENTER_TEXT_CHAIN_REGEXP = /<\s*qqbot-cmd-enter\b/i;
+/**
+* 判断按钮是否是 `enter: true` 指令按钮。
+*
+* 链接按钮和回调按钮有自己的平台行为，只有普通指令按钮才需要提示
+* `enter: true` 在非私聊场景不生效。
+*
+* @param button Karin 按钮配置。
+* @returns 是否为直发指令按钮。
+*/
+const isCommandEnterButton = (button) => {
+	if (button.link || button.callback) return false;
+	return (button.type ?? 2) === 2 && button.enter === true;
+};
+/**
+* 判断 markdown 内容是否手写了 QQ 私聊直发文本链。
+*
+* @param markdown markdown 内容。
+* @returns 是否包含 `<qqbot-cmd-enter ...>`。
+*/
+const hasCommandEnterTextChain = (markdown) => {
+	return COMMAND_ENTER_TEXT_CHAIN_REGEXP.test(markdown);
+};
+/**
+* 收集 button/keyboard 中所有 `enter: true` 指令按钮。
+*
+* @param buttons 单行按钮元素列表。
+* @param keyboards 多行 keyboard 元素列表。
+* @returns 需要特殊处理的直发指令按钮。
+*/
+const collectCommandEnterButtons = (buttons, keyboards) => {
+	const result = [];
+	buttons.forEach((element) => {
+		element.data.forEach((button) => {
+			if (isCommandEnterButton(button)) result.push(button);
+		});
+	});
+	keyboards.forEach((element) => {
+		element.rows.forEach((row) => {
+			row.forEach((button) => {
+				if (isCommandEnterButton(button)) result.push(button);
+			});
+		});
+	});
+	return result;
+};
+/**
+* 归一 QQ keyboard 按钮字段。
+*
+* @param button node-karin 转换后的 QQBot 按钮。
+* @param id 当前 keyboard 内唯一按钮序号。
+* @returns 可直接放入 QQ 官方 keyboard 的按钮对象。
+*/
+const normalizeQQBotButton = (button, id) => {
+	return {
+		...button,
+		id: String(id)
+	};
+};
+/**
+* 生成直发按钮不支持提示中的按钮名称列表。
+*
+* @param buttons 直发指令按钮列表。
+* @returns 便于写入日志的按钮名称。
+*/
+const formatCommandEnterButtonNames = (buttons) => {
+	return buttons.map((button) => button.text || button.data || "未命名按钮").join("、");
+};
+
+//#endregion
+//#region src/core/adapter/grouping.ts
+/**
+* 生成 QQ 被动回复使用的 msg_seq 种子。
+*
+* QQ 官方使用 `msg_id + msg_seq` 判重。这里和 openclaw qqbot 适配器一样限制在
+* 16-bit 范围内，后续每发一条再递增取模。
+*
+* @returns 0..65535 范围内的初始 msg_seq。
+*/
+const createMsgSeqSeed = () => {
+	return (Date.now() % 1e8 ^ Math.floor(Math.random() * 65536)) % 65536;
+};
+/**
+* 创建空容器
+*/
+const createGrouping = () => ({
+	text: [],
+	qqImages: [],
+	guildImageUrls: [],
+	guildImageFiles: [],
+	buttons: [],
+	keyboards: [],
+	markdowns: [],
+	media: [],
+	reply: { messageId: "" },
+	pasmsg: {
+		type: "msg",
+		id: "",
+		seq: createMsgSeqSeed()
+	},
+	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,
+				name: v.name
+			});
+			break;
+		case "record":
+			g.media.push({
+				kind: "record",
+				source: v.file,
+				name: v.name
+			});
+			break;
+		case "file":
+			g.media.push({
+				kind: "file",
+				source: v.file,
+				name: v.name
+			});
+			break;
+		default: break;
+	}
+	return g;
+};
+
+//#endregion
+//#region src/core/adapter/media-source.ts
+/** HTTP(S) 资源已经是可直接传给 QQ 平台的公网地址。 */
+const HTTP_URL_RE = /^https?:\/\//i;
+/** fileToUrl 需要文件名来推断上传类型；没有业务文件名时使用这些默认值。 */
+const DEFAULT_FILENAME = {
+	image: "image.jpg",
+	video: "video.mp4",
+	record: "record.mp3",
+	file: "file.bin"
+};
+/**
+* 当前 Karin 运行时是否注册了 fileToUrl 处理器。
+* @returns true 表示可以优先通过 fileToUrl 产出公网 URL。
+*/
+const hasFileToUrlHandler = () => handler.has(fileToUrlHandlerKey);
+/**
+* 判断一个来源是否已经是公网 HTTP(S) 地址。
+* @param source Karin 消息段里的 file 字段。
+* @returns 是否为 HTTP(S) URL。
+*/
+const isHttpMediaSource = (source) => HTTP_URL_RE.test(source);
+/**
+* 优先把本地/base64 富媒体转换为公网 URL；没有处理器或转换失败时返回原始来源。
+*
+* QQ 官方的普通 file_data 上传对视频等资源更容易失败，因此 adapter 层始终把
+* fileToUrl 作为主路径，QQ 上传只做兜底。
+*
+* @param ctx 适配器实例，用于记录降级日志。
+* @param type 富媒体类型。
+* @param source Karin 消息段里的 file 字段。
+* @param filename 可选文件名，主要用于 file 消息。
+* @returns 解析后的首选来源和来源类型。
+*/
+const resolvePreferredMediaSource = async (ctx, type, source, filename) => {
+	if (isHttpMediaSource(source)) return {
+		source,
+		via: "public-url"
+	};
+	if (!hasFileToUrlHandler()) return {
+		source,
+		via: "fallback"
+	};
+	try {
+		return {
+			source: (await fileToUrl(type, source, filename || DEFAULT_FILENAME[type])).url,
+			via: "file-to-url"
+		};
+	} catch (err) {
+		ctx.logger("warn", `[sendQQ] ${type} 转 URL 失败，改用 QQ 上传兜底:`, err);
+		return {
+			source,
+			via: "fallback"
+		};
+	}
+};
+
+//#endregion
+//#region src/core/adapter/message-id-map.ts
+/** QQ 消息 ID 与 REFIDX 映射的短期缓存时长，和本地消息缓存窗口保持一致。 */
+const MESSAGE_ID_LINK_CACHE_TTL = 1440 * 60 * 1e3;
+/** QQ 消息 ID 映射表清理间隔。 */
+const MESSAGE_ID_LINK_CLEANUP_INTERVAL = 60 * 1e3;
+/** 按适配器实例隔离的消息 ID 映射状态。 */
+const states = /* @__PURE__ */ new WeakMap();
+/**
+* 获取适配器实例对应的消息 ID 映射状态。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @returns 该实例的映射状态。
+*/
+const getState = (ctx) => {
+	const existing = states.get(ctx);
+	if (existing) return existing;
+	const created = {
+		apiMessageIdCache: /* @__PURE__ */ new Map(),
+		referenceMessageIdCache: /* @__PURE__ */ new Map(),
+		ownMessageIdCache: /* @__PURE__ */ new Map(),
+		lastCleanup: 0
+	};
+	states.set(ctx, created);
+	return created;
+};
+/**
+* 构造 REFIDX/API ID 映射的会话级 key。
+*
+* @param contact 消息所在会话。
+* @param messageId 消息 ID。
+* @returns 可用于 Map 的稳定 key。
+*/
+const messageIdKey = (contact, messageId) => {
+	return [
+		contact.scene,
+		contact.peer,
+		contact.subPeer || "",
+		messageId
+	].join("");
+};
+/**
+* 清理过期的消息 ID 映射。
+*
+* @param ctx 当前 QQBot 适配器实例。
+*/
+const cleanup = (ctx) => {
+	const state = getState(ctx);
+	const now = Date.now();
+	if (now - state.lastCleanup < MESSAGE_ID_LINK_CLEANUP_INTERVAL) return;
+	state.lastCleanup = now;
+	for (const [key, entry] of state.apiMessageIdCache) if (entry.expiresAt <= now) state.apiMessageIdCache.delete(key);
+	for (const [key, entry] of state.referenceMessageIdCache) if (entry.expiresAt <= now) state.referenceMessageIdCache.delete(key);
+	for (const [key, entry] of state.ownMessageIdCache) if (entry.expiresAt <= now) state.ownMessageIdCache.delete(key);
+};
+/**
+* 记住机器人自己发送的 QQ API 消息 ID。
+*
+* 单聊场景只允许撤回机器人自己发送的消息。收到用户消息时的 `e.messageId`
+* 也是 API 消息 ID，但不能用于单聊撤回，因此需要独立标记来源。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param apiMessageId QQ API 消息 ID，通常为 ROBOT1.0_...。
+*/
+const rememberOwnMessageId = (ctx, contact, apiMessageId) => {
+	if (!apiMessageId) return;
+	cleanup(ctx);
+	getState(ctx).ownMessageIdCache.set(messageIdKey(contact, apiMessageId), { expiresAt: Date.now() + MESSAGE_ID_LINK_CACHE_TTL });
+};
+/**
+* 判断给定 QQ API 消息 ID 是否由机器人自己发送。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param apiMessageId QQ API 消息 ID。
+* @returns true 表示这条消息是当前适配器实例发送的。
+*/
+const isOwnMessageId = (ctx, contact, apiMessageId) => {
+	cleanup(ctx);
+	const state = getState(ctx);
+	const key = messageIdKey(contact, apiMessageId);
+	const cached = state.ownMessageIdCache.get(key);
+	if (!cached) return false;
+	if (cached.expiresAt > Date.now()) return true;
+	state.ownMessageIdCache.delete(key);
+	return false;
+};
+/**
+* 记住 QQ 引用索引对应的 API 消息 ID。
+*
+* QQ 群聊/单聊的 `message_reference.message_id` 使用 REFIDX，但撤回等 API 路径使用
+* ROBOT1.0 开头的消息 ID。映射按适配器实例和会话隔离，避免不同群里的 REFIDX 冲突。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param referenceMessageId QQ 引用索引，通常为 REFIDX_...。
+* @param apiMessageId QQ API 消息 ID，通常为 ROBOT1.0_...。
+*/
+const rememberApiMessageId = (ctx, contact, referenceMessageId, apiMessageId) => {
+	if (!referenceMessageId || !apiMessageId) return;
+	if (referenceMessageId === apiMessageId) return;
+	cleanup(ctx);
+	const state = getState(ctx);
+	const expiresAt = Date.now() + MESSAGE_ID_LINK_CACHE_TTL;
+	state.apiMessageIdCache.set(messageIdKey(contact, referenceMessageId), {
+		apiMessageId,
+		expiresAt
+	});
+	state.referenceMessageIdCache.set(messageIdKey(contact, apiMessageId), {
+		referenceMessageId,
+		expiresAt
+	});
+};
+/**
+* 将 QQ API 消息 ID 解析为客户端可见引用使用的 REFIDX。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param messageId Karin 侧传入的消息 ID，可能是 ROBOT1.0 或 REFIDX。
+* @returns 可用于 `message_reference.message_id` 的 ID；没有映射时返回原值。
+*/
+const resolveReferenceMessageId = (ctx, contact, messageId) => {
+	cleanup(ctx);
+	const state = getState(ctx);
+	const key = messageIdKey(contact, messageId);
+	const cached = state.referenceMessageIdCache.get(key);
+	if (!cached) return messageId;
+	if (cached.expiresAt > Date.now()) return cached.referenceMessageId;
+	state.referenceMessageIdCache.delete(key);
+	return messageId;
+};
+/**
+* 将 Karin 侧传入的消息 ID 解析为 QQ API 可用的消息 ID。
+*
+* @param ctx 当前 QQBot 适配器实例。
+* @param contact 消息所在会话。
+* @param messageId Karin 侧传入的消息 ID，可能是 REFIDX。
+* @returns QQ API 路径可用的消息 ID；没有映射时返回原值。
+*/
+const resolveApiMessageId = (ctx, contact, messageId) => {
+	cleanup(ctx);
+	const state = getState(ctx);
+	const key = messageIdKey(contact, messageId);
+	const cached = state.apiMessageIdCache.get(key);
+	if (!cached) return messageId;
+	if (cached.expiresAt > Date.now()) return cached.apiMessageId;
+	state.apiMessageIdCache.delete(key);
+	return messageId;
+};
+
+//#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
+/** QQ 官方限制：单聊中同一 `msg_id` 最多发送四次被动回复。 */
+const C2C_PASSIVE_REPLY_LIMIT = 4;
+/** QQ keyboard 限制：最多 5 行，每行最多 5 个按钮。 */
+const KEYBOARD_MAX_ROWS$1 = 5;
+const KEYBOARD_MAX_BUTTONS_PER_ROW$1 = 5;
+/** 只有按钮没有文本时仍需提供非空 markdown 内容。 */
+const BUTTON_ONLY_MARKDOWN$1 = "​";
+/** 群聊 event_id 白名单 */
+const GROUP_EVENT_WHITELIST = /* @__PURE__ */ new Set([
+	"INTERACTION_CREATE",
+	"GROUP_ADD_ROBOT",
+	"GROUP_MSG_RECEIVE"
+]);
+/** 单聊 event_id 白名单 */
+const FRIEND_EVENT_WHITELIST = /* @__PURE__ */ new Set([
+	"INTERACTION_CREATE",
+	"C2C_MSG_RECEIVE",
+	"FRIEND_ADD"
+]);
+/**
+* 处理 QQ 场景（单聊 + 群聊）的发送
+*/
+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 / 可转换为公网 URL 的图片通过 markdown content 渲染；无法转换的图片
+	* 与视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 单独补发。所有富媒体
+	* 都会优先通过 fileToUrl 取得公网地址，QQ 上传只做兜底。只有显式引用的
+	* 纯文本消息会降级为 msg_type=0，以保证 QQ 客户端能稳定显示引用气泡。
+	*/
+	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(""));
+	const fallbackImages = await appendMarkdownImages(ctx, lines, grouping.qqImages);
+	if (grouping.markdowns.length) grouping.markdowns.forEach((m) => lines.push(m.markdown));
+	if (contact.scene === "group") {
+		warnUnsupportedCommandEnterButtons$1(ctx, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
+		warnUnsupportedCommandEnterMarkdowns$1(ctx, grouping.markdowns.map((m) => m.markdown));
+	}
+	if (lines.length || grouping.buttons.length || grouping.keyboards.length) if (shouldUseTextForReference(ctx, contact, grouping)) items.push(ctx.super.qq.text(lines.join("\n")));
+	else {
+		const keyboard = buildKeyboard$1(grouping);
+		const content = lines.length ? lines.join("\n") : BUTTON_ONLY_MARKDOWN$1;
+		items.push(ctx.super.qq.markdown({ content }, keyboard));
+	}
+	for (const file of fallbackImages) {
+		const res = await ctx.super.media.uploadFallback(target, contact.peer, "image", file, false);
+		items.push(ctx.super.qq.media(res.file_info));
+	}
+	for (const m of grouping.media) {
+		const source = await resolvePreferredMediaSource(ctx, m.kind, m.source, m.name);
+		const res = source.via === "fallback" ? await ctx.super.media.uploadFallback(target, contact.peer, m.kind, source.source, false, m.name) : await ctx.super.media.upload(target, contact.peer, m.kind, source.source, false, m.name);
+		items.push(ctx.super.qq.media(res.file_info));
+	}
+	if (!items.length) items.push(ctx.super.qq.text("不支持发送的消息类型"));
+	return flushQQ(ctx, contact, grouping, items);
+};
+/**
+* 将能转成公网 URL 的图片追加到 markdown 行，无法转换的图片返回给富媒体 fallback。
+*
+* @param ctx 适配器实例，用于输出降级日志。
+* @param lines markdown 行数组。
+* @param files QQ 图片消息段的 file 字段。
+* @returns 需要改走 msg_type=7 富媒体发送的图片列表。
+*/
+const appendMarkdownImages = async (ctx, lines, files) => {
+	const fallback = [];
+	for (const file of files) {
+		const resolved = await resolvePreferredMediaSource(ctx, "image", file);
+		if (resolved.via === "fallback") {
+			fallback.push(file);
+			continue;
+		}
+		await appendImageUrlLine(lines, resolved.source);
+	}
+	return fallback;
+};
+/**
+* 生成单张 markdown 图片行。
+* 尺寸获取失败时使用保守默认尺寸，保证 fileToUrl 成功的图片仍走 markdown。
+*
+* @param lines markdown 行数组。
+* @param url 图片 URL。
+*/
+const appendImageUrlLine = async (lines, url) => {
+	try {
+		const [line] = await imagesToMarkdown([url]);
+		lines.push(line);
+	} catch {
+		lines.push(`![karin #300px #300px](${url})`);
+	}
+};
+/**
+* 判断显式引用回复是否应降级为普通文本消息。
+*
+* QQ 的 `message_reference` 对普通文本最稳定；markdown 带引用在客户端渲染上存在兼容问题。
+* 因此只有纯文本显式引用回复会走 msg_type=0，图片、按钮、keyboard、markdown 段仍走原通道。
+*
+* @param grouping 已归类的消息段。
+* @returns 是否使用普通文本发送主消息。
+*/
+const shouldUseTextForReference = (ctx, contact, grouping) => {
+	return isQQReferenceMessageId(resolveReferenceMessageId(ctx, contact, grouping.reply.messageId)) && !grouping.qqImages.length && !grouping.buttons.length && !grouping.keyboards.length && !grouping.markdowns.length;
+};
+/**
+* 判断给定 ID 是否是 QQ 客户端引用使用的 REFIDX。
+*
+* `ROBOT1.0_...` 这类官方消息 ID 只能作为被动发送的 `msg_id`，不能放进
+* `message_reference.message_id`。
+*
+* @param messageId 待判断的消息 ID。
+* @returns 是否为 QQ 引用索引。
+*/
+const isQQReferenceMessageId = (messageId) => messageId.startsWith("REFIDX_");
+/**
+* 构造 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)));
+	const normalizedRows = [];
+	let id = 0;
+	for (const row of rows.slice(0, KEYBOARD_MAX_ROWS$1)) {
+		const buttons = row.buttons.slice(0, KEYBOARD_MAX_BUTTONS_PER_ROW$1).map((button) => normalizeQQBotButton(button, id++));
+		if (buttons.length) normalizedRows.push({ buttons });
+	}
+	if (!normalizedRows.length) return void 0;
+	return { content: { rows: normalizedRows } };
+};
+/**
+* 群聊不支持 `enter: true` 直发按钮，只输出提示，不拦截 keyboard 发送。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param buttons 本次消息中的直发指令按钮。
+*/
+const warnUnsupportedCommandEnterButtons$1 = (ctx, buttons) => {
+	if (!buttons.length) return;
+	const names = formatCommandEnterButtonNames(buttons);
+	ctx.logger("debug", `群聊不支持 enter: true 直接发送，按钮仍会按原样发送: ${names}`);
+};
+/**
+* 群聊不支持 `<qqbot-cmd-enter>` 文本链，只输出提示，不拦截 markdown 发送。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param markdowns 本次消息中的 markdown 内容。
+*/
+const warnUnsupportedCommandEnterMarkdowns$1 = (ctx, markdowns) => {
+	if (!markdowns.some(hasCommandEnterTextChain)) return;
+	ctx.logger("debug", "群聊不支持 <qqbot-cmd-enter> 直接发送，markdown 仍会按原样发送");
+};
+/**
+* 逐条发送 + 被动消息附加 + 引用回复
+*/
+const flushQQ = async (ctx, contact, grouping, items) => {
+	const result = ctx.initSendMsgResults();
+	const passiveSource = resolvePassiveQQ(grouping);
+	const passive = buildPassiveQQ(ctx, contact.scene, grouping);
+	const send = contact.scene === "friend" ? (peer, item) => ctx.super.messages.sendFriendMsg(peer, item) : (peer, item) => ctx.super.messages.sendGroupMsg(peer, item);
+	/**
+	* 仅单聊 `msg_id` 回复受四次上限约束。`event_id` 事件回复和群聊不适用该限制。
+	* 这是 QQ 官方 2026-01-10 更新后的限制，超出部分不请求平台接口。
+	*/
+	const maxItems = contact.scene === "friend" && passiveSource?.type === "msg" && passiveSource.id ? C2C_PASSIVE_REPLY_LIMIT : Infinity;
+	if (items.length > maxItems) ctx.logger("warn", `单聊被动回复最多 ${C2C_PASSIVE_REPLY_LIMIT} 条，已跳过 ${items.length - maxItems} 条`);
+	let referenceHandled = false;
+	for (const item of items.slice(0, maxItems)) {
+		passive(item);
+		if (!referenceHandled) referenceHandled = attachVisibleReferenceQQ(ctx, contact, item, grouping);
+		const res = await sendQQWithEventFallback(ctx, contact, send, item);
+		rememberOwnMessageId(ctx, contact, res.id);
+		if (res.ext_info?.ref_idx) rememberApiMessageId(ctx, contact, res.ext_info.ref_idx, res.id);
+		result.rawData.push(res);
+	}
+	return ctx.handleResponse(result);
+};
+/**
+* 发送 QQ 消息，并在平台拒绝 `event_id` 时降级为普通消息重试。
+*
+* QQ 文档说明 `INTERACTION_CREATE.d.id` 可用于被动消息发送，但实测群聊接口会出现
+* 40034025。为了避免按钮回调业务回复把 Karin 命令链路打断，这里只对
+* `event_id` 参数无效做一次无 `event_id` 重试。
+*
+* @param ctx 适配器实例，用于输出降级日志。
+* @param contact 消息目标。
+* @param send 当前场景的发送函数。
+* @param item 即将发送的 QQ 消息体。
+* @returns QQ 消息发送响应。
+*/
+const sendQQWithEventFallback = async (ctx, contact, send, item) => {
+	try {
+		return await send(contact.peer, item);
+	} catch (err) {
+		if (!item.event_id || !isInvalidEventIdError(err)) throw err;
+		ctx.logger("warn", `event_id 被 QQ 拒绝，已改用普通消息重试: ${item.event_id}`);
+		const retryItem = { ...item };
+		delete retryItem.event_id;
+		delete retryItem.msg_seq;
+		return send(contact.peer, retryItem);
+	}
+};
+/**
+* 判断发送失败是否来自 QQ 对 `event_id` 的参数校验。
+*
+* 当前错误由 Http 层格式化为普通 Error，因此这里基于官方错误码和中文错误信息兜底识别。
+*
+* @param err 捕获到的发送异常。
+* @returns 是否可以通过移除 `event_id` 重试。
+*/
+const isInvalidEventIdError = (err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	return message.includes("40034025") || message.includes("请求参数event_id无效");
+};
+/**
+* 解析 QQ 场景应使用的被动回复来源。
+*
+* `msg_id/event_id` 是 QQBot 被动发送凭证，不等于客户端展示引用使用的
+* `message_reference.message_id`。因此这里只读取事件入口追加的 pasmsg，显式
+* `segment.reply` 交给 `attachVisibleReferenceQQ` 处理。
+*
+* @param grouping 已归类的消息段。
+* @returns 可附加到发送体的被动回复来源；没有可用来源时返回 undefined。
+*/
+const resolvePassiveQQ = (grouping) => {
+	if (grouping.pasmsg.id) return grouping.pasmsg;
+};
+/**
+* 附加 QQ 客户端可见的引用对象。
+*
+* 群聊/单聊里真正发给 QQ 的值必须是 `message_scene.ext` 的 `msg_idx=REFIDX_xxx`。
+* 如果插件传入的是 Karin 暴露的官方 API 消息 ID，这里会先按同会话映射转换。
+*
+* @param item 即将发送的 QQ 消息体。
+* @param grouping 已归类的消息段。
+* @returns 是否已经消费一次显式引用。
+*/
+const attachVisibleReferenceQQ = (ctx, contact, item, grouping) => {
+	const messageId = resolveReferenceMessageId(ctx, contact, grouping.reply.messageId);
+	if (!isQQReferenceMessageId(messageId)) return false;
+	item.message_reference = { message_id: messageId };
+	return true;
+};
+/**
+* 递增并返回下一条 QQ 被动回复序号。
+*
+* @param grouping 已归类的消息段。
+* @returns 0..65535 范围内的 msg_seq。
+*/
+const nextPassiveMsgSeq = (grouping) => {
+	grouping.pasmsg.seq = (grouping.pasmsg.seq + 1) % 65536;
+	return grouping.pasmsg.seq;
+};
+/**
+* 构造被动消息附加器（含白名单校验）
+*/
+const buildPassiveQQ = (ctx, scene, grouping) => {
+	const source = resolvePassiveQQ(grouping);
+	if (!source?.id) return (_item) => void 0;
+	const whitelist = scene === "friend" ? FRIEND_EVENT_WHITELIST : GROUP_EVENT_WHITELIST;
+	if (source.type === "event") {
+		const eventName = source.id.split(":")[0];
+		if (eventName && !whitelist.has(eventName)) {
+			ctx.logger("warn", `跳过无效 event_id: ${source.id}`);
+			return (_item) => void 0;
+		}
+		return (item) => {
+			item.msg_seq = nextPassiveMsgSeq(grouping);
+			item.event_id = source.id;
+		};
+	}
+	return (item) => {
+		item.msg_seq = nextPassiveMsgSeq(grouping);
+		item.msg_id = source.id;
+	};
+};
+
+//#endregion
+//#region src/core/adapter/pipeline-guild.ts
+/** QQ keyboard 限制：最多 5 行，每行最多 5 个按钮。 */
+const KEYBOARD_MAX_ROWS = 5;
+const KEYBOARD_MAX_BUTTONS_PER_ROW = 5;
+/** 只有按钮没有文本时仍需提供非空 markdown 内容。 */
+const BUTTON_ONLY_MARKDOWN = "​";
+/**
+* 处理频道场景（子频道 + 私信）的发送
+*
+* 永远走 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));
+	warnUnsupportedCommandEnterButtons(ctx, contact.scene, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
+	warnUnsupportedCommandEnterMarkdowns(ctx, contact.scene, grouping.markdowns.map((m) => m.markdown));
+	if (lines.length || grouping.buttons.length || grouping.keyboards.length) {
+		const keyboard = buildKeyboard(grouping);
+		const content = lines.length ? lines.join("\n") : BUTTON_ONLY_MARKDOWN;
+		items.push(ctx.super.guild.markdown({ content }, 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)));
+	const normalizedRows = [];
+	let id = 0;
+	for (const row of rows.slice(0, KEYBOARD_MAX_ROWS)) {
+		const buttons = row.buttons.slice(0, KEYBOARD_MAX_BUTTONS_PER_ROW).map((button) => normalizeQQBotButton(button, id++));
+		if (buttons.length) normalizedRows.push({ buttons });
+	}
+	if (!normalizedRows.length) return void 0;
+	return { content: { rows: normalizedRows } };
+};
+/**
+* 频道消息不支持 `enter: true` 直发按钮，只输出提示，不拦截 keyboard 发送。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param scene 频道消息场景。
+* @param buttons 本次消息中的直发指令按钮。
+*/
+const warnUnsupportedCommandEnterButtons = (ctx, scene, buttons) => {
+	if (!buttons.length) return;
+	const names = formatCommandEnterButtonNames(buttons);
+	const name = scene === "guild" ? "频道" : "频道私信";
+	ctx.logger("debug", `${name}不支持 enter: true 直接发送，按钮仍会按原样发送: ${names}`);
+};
+/**
+* 频道消息不支持 `<qqbot-cmd-enter>` 文本链，只输出提示，不拦截 markdown 发送。
+*
+* @param ctx 适配器实例，用于输出日志。
+* @param scene 频道消息场景。
+* @param markdowns 本次消息中的 markdown 内容。
+*/
+const warnUnsupportedCommandEnterMarkdowns = (ctx, scene, markdowns) => {
+	if (!markdowns.some(hasCommandEnterTextChain)) return;
+	const name = scene === "guild" ? "频道" : "频道私信";
+	ctx.logger("debug", `${name}不支持 <qqbot-cmd-enter> 直接发送，markdown 仍会按原样发送`);
+};
+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);
+	for (const item of items) {
+		passive(item);
+		const res = await send(contact.peer, contact.subPeer, item);
+		result.rawData.push(res);
+	}
+	return ctx.handleResponse(result);
+};
+/**
+* 解析频道/私信场景的被动回复来源。
+*
+* openclaw 的 qqbot 适配器对 channel/dm 也只传 `msg_id`。这里让显式
+* `segment.reply` 优先，其次使用事件入口追加的 pasmsg。
+*
+* @param grouping 已归类的消息段。
+* @returns 被动回复来源；没有可用来源时返回 undefined。
+*/
+const resolvePassiveGuild = (grouping) => {
+	if (grouping.reply.messageId) return {
+		type: "msg",
+		id: grouping.reply.messageId
+	};
+	if (grouping.pasmsg.id) return grouping.pasmsg;
+};
+/**
+* 构造频道/私信被动消息附加器。
+*
+* @param grouping 已归类的消息段。
+* @returns 可直接修改发送体或 FormData 的附加函数。
+*/
+const buildPassiveGuild = (grouping) => {
+	const source = resolvePassiveGuild(grouping);
+	if (!source?.id) return (_item) => void 0;
+	if (source.type === "event") return (item) => {
+		if (item instanceof FormData) item.append("event_id", source.id);
+		else item.event_id = source.id;
+	};
+	return (item) => {
+		if (item instanceof FormData) item.append("msg_id", source.id);
+		else item.msg_id = source.id;
+	};
+};
+
+//#endregion
+//#region src/core/adapter/self-message-cache.ts
+/**
+* 只有两个缓存开关同时开启时才需要等待发送结果并缓存自己消息。
+*/
+const shouldCacheSelfMessage = (ctx) => {
+	return ctx.cfg.messageCache.enable && ctx.cfg.messageCache.self;
+};
+/**
+* 预处理自己消息元素。
+*
+* 静态资源只在这里转一次 HTTP URL，之后发送 pipeline 和缓存都复用该 URL。
+*/
+const prepareSelfMessageCache = async (ctx, elements) => {
+	const sendElements = [];
+	const cacheElements = [];
+	for (const element of elements) {
+		const prepared = await prepareSelfCacheElement(ctx, element);
+		sendElements.push(prepared.send);
+		if (prepared.cache) cacheElements.push(prepared.cache);
+	}
+	return {
+		sendElements,
+		cacheElements
+	};
+};
+/**
+* 发送成功后缓存机器人自己的消息，供 bot.getMsg(messageId) 查询。
+*/
+const cacheSelfMessage = (ctx, contact, cacheElements, result) => {
+	if (!shouldCacheSelfMessage(ctx)) return;
+	if (!cacheElements.length) return;
+	const responses = (Array.isArray(result.rawData) ? result.rawData : [result.rawData]).filter((item) => item?.id);
+	if (!responses.length) return;
+	const sender = selfSender(ctx, contact);
+	const seen = /* @__PURE__ */ new Set();
+	for (const response of responses) {
+		const apiMessageId = String(response.id);
+		const referenceMessageId = typeof response.ext_info?.ref_idx === "string" ? response.ext_info.ref_idx : "";
+		const messageId = apiMessageId;
+		const aliases = [referenceMessageId].filter((id) => id && id !== messageId);
+		if (!messageId || seen.has(messageId)) continue;
+		seen.add(messageId);
+		if (referenceMessageId) rememberApiMessageId(ctx, contact, referenceMessageId, apiMessageId);
+		ctx.messageStore.save(String(ctx.cfg.appId), {
+			messageId,
+			messageSeq: 0,
+			time: responseTime(response.timestamp),
+			contact,
+			sender,
+			elements: cacheElements
+		}, aliases).catch((err) => ctx.logger("warn", `[getMsg] 写入自己消息缓存失败: ${messageId}`, err));
+	}
+};
+/**
+* 转换单个自己消息元素为缓存安全形态。
+*/
+const prepareSelfCacheElement = async (ctx, element) => {
+	switch (element.type) {
+		case "text":
+		case "at":
+		case "reply":
+		case "face":
+		case "markdown": {
+			const cached = { ...element };
+			return {
+				send: cached,
+				cache: cached
+			};
+		}
+		case "image":
+		case "video":
+		case "record":
+		case "file": return prepareStaticElement(ctx, element);
+		default: return {
+			send: element,
+			cache: null
+		};
+	}
+};
+/**
+* 静态资源统一转 HTTP URL 后再缓存；转换失败时跳过该元素。
+*/
+const prepareStaticElement = async (ctx, element) => {
+	if (element.file.startsWith("http")) {
+		const cached = { ...element };
+		return {
+			send: cached,
+			cache: cached
+		};
+	}
+	try {
+		switch (element.type) {
+			case "image": {
+				const res = await fileToUrl("image", element.file, element.name || "image.jpg");
+				const cached = {
+					...element,
+					file: res.url,
+					width: res.width,
+					height: res.height
+				};
+				return {
+					send: cached,
+					cache: cached
+				};
+			}
+			case "video": {
+				const res = await fileToUrl("video", element.file, element.name || "video.mp4");
+				const cached = {
+					...element,
+					file: res.url
+				};
+				return {
+					send: cached,
+					cache: cached
+				};
+			}
+			case "record": {
+				const res = await fileToUrl("record", element.file, element.name || "record.mp3");
+				const cached = {
+					...element,
+					file: res.url
+				};
+				return {
+					send: cached,
+					cache: cached
+				};
+			}
+			case "file": {
+				const res = await fileToUrl("file", element.file, element.name || "file.bin");
+				const cached = {
+					...element,
+					file: res.url
+				};
+				return {
+					send: cached,
+					cache: cached
+				};
+			}
+		}
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		ctx.logger("debug", `[getMsg] 跳过自己消息资源缓存: ${element.type} ${message}`);
+		return {
+			send: element,
+			cache: null
+		};
+	}
+};
+/**
+* 构造机器人自己的 sender。
+*/
+const selfSender = (ctx, contact) => {
+	const userId = ctx.selfSubId("id") || ctx.selfId;
+	const name = ctx.selfName || ctx.cfg.name || "";
+	if (contact.scene === "friend" || contact.scene === "direct") return karin$1.friendSender(userId, name);
+	return karin$1.groupSender(userId, "member", name);
+};
+/**
+* QQ / 频道发送接口 timestamp 格式不同，统一转成毫秒时间戳。
+*/
+const responseTime = (timestamp) => {
+	if (typeof timestamp === "string") {
+		const time = new Date(timestamp).getTime();
+		return Number.isFinite(time) ? time : Date.now();
+	}
+	if (typeof timestamp === "number") return timestamp < 0xe8d4a51000 ? timestamp * 1e3 : timestamp;
+	return Date.now();
+};
+
+//#endregion
+//#region src/core/adapter/base.ts
+const adapterConfigStore = /* @__PURE__ */ new WeakMap();
+/**
+* QQ Official Bot 适配器
+*
+* 全场景统一走 msg_type=2 Markdown 通道（详见 pipeline-qq / pipeline-guild）。
+* 视频 / 语音 / 文件由 pipeline 内部以 msg_type=7 紧随主消息补发。
+*/
+var AdapterQQBot = class extends AdapterBase {
+	/** 与官方 API 交互 */
+	super;
+	/** openId / member_openid -> 昵称 缓存 */
+	nicknameCache = /* @__PURE__ */ new Map();
+	constructor(cfg, api) {
+		super();
+		adapterConfigStore.set(this, cfg);
+		this.super = api;
+		this.adapter.name = "QQ Official Bot";
+		this.adapter.protocol = "qqbot";
+		this.adapter.platform = "qq";
+		this.adapter.standard = "other";
+	}
+	/** 当前 bot 配置。真实配置存放在 WeakMap，避免被系统接口序列化整个适配器时带出。 */
+	get cfg() {
+		const cfg = adapterConfigStore.get(this);
+		if (!cfg) throw new Error("QQBot adapter config missing");
+		return cfg;
+	}
+	/** 接收消息的一天热缓存 + SQLite 缓存，用于实现 Karin 标准 `getMsg`。 */
+	get messageStore() {
+		return getMessageStore();
+	}
+	logger(level, ...args) {
+		logger.bot(level, this.selfId, ...args);
+	}
+	/**
+	* 主消息回复入口（karin 调用）
+	*/
+	async srcReply(e, elements) {
+		const extra = await buttonHandle(e.msg, { e });
+		return this.sendMsg(e.contact, [...elements, ...extra]);
+	}
+	/**
+	* 发送消息
+	*/
+	async sendMsg(contact, elements, _retryCount) {
+		if (contact.scene === "direct" || contact.scene === "guild") {
+			if (!shouldCacheSelfMessage(this)) return sendGuild(this, contact, elements);
+			const prepared = await prepareSelfMessageCache(this, elements);
+			const result = await sendGuild(this, contact, prepared.sendElements);
+			cacheSelfMessage(this, contact, prepared.cacheElements, result);
+			return result;
+		}
+		if (contact.scene === "group" || contact.scene === "friend") {
+			if (!shouldCacheSelfMessage(this)) return sendQQ(this, contact, elements);
+			const prepared = await prepareSelfMessageCache(this, elements);
+			const result = await sendQQ(this, contact, prepared.sendElements);
+			cacheSelfMessage(this, contact, prepared.cacheElements, result);
+			return result;
+		}
+		throw new Error(`不支持的消息场景: ${contact.scene}`);
+	}
+	/**
+	* 撤回消息
+	*
+	* 群聊中机器人被群主设为管理员后，也可撤回成员消息；平台仍限制消息发送后两分钟内。
+	*/
+	async recallMsg(contact, messageId) {
+		const apiMessageId = resolveApiMessageId(this, contact, messageId);
+		try {
+			if (contact.scene === "friend") {
+				if (!isOwnMessageId(this, contact, apiMessageId)) {
+					this.logger("warn", `[recallMsg] QQ 单聊只能撤回机器人自己发送的消息，已跳过撤回: ${messageId}`);
+					return;
+				}
+				await this.super.messages.recall("user", contact.peer, apiMessageId);
+			} else if (contact.scene === "group") await this.super.messages.recall("group", contact.peer, apiMessageId);
+			else if (contact.scene === "direct") await this.super.messages.recall("dms", contact.peer, apiMessageId);
+			else if (contact.scene === "guild") await this.super.messages.recall("channels", contact.peer, apiMessageId);
+		} 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}`;
+	}
+	/**
+	* 按消息 ID 获取已接收的消息。
+	*
+	* QQ 官方 Bot API 没有历史消息查询接口，因此仅从本地缓存读取。
+	* 消息在接收时已转换为 Karin elements，最长保留一天；引用消息的 `REFIDX`
+	* 索引同样可作为 `messageId` 查询。
+	*
+	* @param input OneBot v11 标准单参 messageId，或用于限定查询范围的 Contact。
+	* @param messageId 当 input 是 Contact 时传入的目标消息 ID。
+	* @returns 命中的消息；未命中时返回空消息结构。
+	*/
+	async getMsg(input, messageId) {
+		/** OneBot v11 标准单参形式：bot.getMsg(messageId)。 */
+		const targetId = typeof input === "string" ? input : messageId || "";
+		const contact = typeof input === "string" ? void 0 : input;
+		if (!this.cfg.messageCache.enable) {
+			this.logger("debug", `[getMsg] 消息缓存已关闭: ${targetId || "(empty)"}`);
+			return {
+				time: 0,
+				messageId: targetId,
+				messageSeq: 0,
+				contact: contact || {
+					scene: "group",
+					peer: "",
+					subPeer: "",
+					name: ""
+				},
+				sender: {
+					userId: "",
+					nick: "",
+					name: "",
+					role: "member"
+				},
+				elements: []
+			};
+		}
+		const cached = await this.messageStore.get(String(this.cfg.appId), targetId, contact);
+		if (cached) return cached;
+		this.logger("debug", `[getMsg] 本地一天消息缓存未命中: ${targetId || "(empty)"}`);
+		return {
+			time: 0,
+			messageId: targetId,
+			messageSeq: 0,
+			contact: contact || {
+				scene: "group",
+				peer: "",
+				subPeer: "",
+				name: ""
+			},
+			sender: {
+				userId: "",
+				nick: "",
+				name: "",
+				role: "member"
+			},
+			elements: []
+		};
+	}
+	/** @internal */
+	async getHistoryMsg(contact, start, count = 1) {
+		if (typeof start === "number") {
+			this.logger("warn", "[getHistoryMsg] QQ Official Bot 仅支持通过 message_id 获取历史消息，不支持 message_seq");
+			return [];
+		}
+		if (!this.cfg.messageCache.enable) {
+			this.logger("warn", "[getHistoryMsg] 历史消息缓存为空，请打开“启用数据库缓存消息”开关后再记录历史消息");
+			return [];
+		}
+		const history = await this.messageStore.getHistory(String(this.cfg.appId), contact, start, count);
+		if (!history.length) this.logger("debug", `[getHistoryMsg] 本地一天历史消息缓存未命中: ${start || "(empty)"}`);
+		return history;
+	}
+	/**
+	* 获取合并转发消息
+	*/
+	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 `message_scene.ext` 中提取消息索引。 */
+const getMessageSceneIndex = (scene, key) => {
+	const prefix = `${key}=`;
+	return scene?.ext?.find((item) => item.startsWith(prefix))?.slice(prefix.length) || "";
+};
+/** 原生 Markdown 不能从 QQ 回显中完全区分，只识别适配器发送后可稳定还原的常用语法。 */
+const isNativeMarkdown = (text) => {
+	return /(^|\n)\s{0,3}(?:#{1,6}\s|[-*+]\s|\d+\.\s|>\s)|\*\*|__|~~|`{1,3}|\[[^\]]+\]\([^\s)]+\)|(^|\n)\s*\|.+\|\s*\n\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?/m.test(text);
+};
+/** 将非图片 Markdown 片段恢复为 text 或 markdown 元素。 */
+const pushMarkdownText = (text, elements) => {
+	if (!text) return;
+	elements.push(isNativeMarkdown(text) ? segment.markdown(text) : segment.text(text));
+};
+/**
+* 反向解析适配器发送的 QQ Markdown。
+*
+* 发送侧会将 Karin 图片编码为 `![名称 #宽px #高px](URL)`，并以换行拼接文本、
+* 图片和原生 Markdown；这里按原顺序恢复为 Karin `text`、`image`、`markdown`。
+*/
+const pushQQMarkdown = (text, elements) => {
+	const imageReg = /!\[([^\]]*)\]\((https?:\/\/[^\s)]+)\)/g;
+	let lastIndex = 0;
+	let matched = false;
+	let match;
+	while (match = imageReg.exec(text)) {
+		matched = true;
+		if (match.index > lastIndex) pushMarkdownText(text.slice(lastIndex, match.index), elements);
+		const alt = match[1];
+		const dimension = alt.match(/\s+#(\d+)px\s+#(\d+)px\s*$/);
+		const name = alt.replace(/\s+#\d+px\s+#\d+px\s*$/, "") || "图片";
+		elements.push(segment.image(match[2], {
+			name,
+			width: dimension ? Number(dimension[1]) : void 0,
+			height: dimension ? Number(dimension[2]) : void 0
+		}));
+		lastIndex = imageReg.lastIndex;
+	}
+	if (matched && lastIndex < text.length) pushMarkdownText(text.slice(lastIndex), elements);
+	return matched;
+};
+/**
+* 只拆 QQ 协议标签，保留普通文本中的 HTML/Markdown 片段。
+*
+* 普通文本或 Markdown 里可能包含 `<br>`、`<table>` 等内容；如果用 `[^<]+`
+* 直接切分，会把这些内容误当成协议标签边界，导致一条文本被拆成多段甚至丢失 `<`。
+*/
+const tokenizeContent = (content = "") => {
+	const tokens = [];
+	const knownTag = /<faceType=\d+,faceId="[^"]*",ext="[^"]*">|<qqbot-at-user id="[^"]+"\s*\/?>|<qqbot-at-everyone\s*\/?>|<@!?[A-Za-z0-9]+>/g;
+	let lastIndex = 0;
+	let match;
+	while (match = knownTag.exec(content)) {
+		if (match.index > lastIndex) tokens.push(content.slice(lastIndex, match.index));
+		tokens.push(match[0]);
+		lastIndex = knownTag.lastIndex;
+	}
+	if (lastIndex < content.length) tokens.push(content.slice(lastIndex));
+	return tokens;
+};
+/**
+* 判断 QQ 回显内容是否应恢复成 Karin markdown 段。
+*
+* QQBot 自己收到自己发出的 markdown 时可能是 `message_type=103`；收到其他
+* QQBot 发出的 markdown 时，官方报文仍可能给 `message_type=0`，只能结合
+* `author.bot` 与内容语法做保守识别。
+*/
+const shouldUseMarkdown = (messageType, fromBot, text) => {
+	return (messageType === 103 || fromBot) && isNativeMarkdown(text);
+};
+/**
+* 从 QQ 表情标签的 base64 ext 中提取可读文本。
+*
+* faceType=4 的表情包套图没有图片附件，只能通过 ext 中的 JSON 文本展示。
+*
+* @param ext QQ 表情标签里的 base64 字段。
+* @returns ext JSON 中的 text；解析失败时返回空字符串。
+*/
+const getFaceExtText = (ext) => {
+	if (!ext) return "";
+	try {
+		const decoded = Buffer.from(ext, "base64").toString("utf-8");
+		const payload = JSON.parse(decoded);
+		return typeof payload.text === "string" ? payload.text : "";
+	} catch {
+		return "";
+	}
+};
+/**
+* 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;
+	const messageType = "message_type" in data ? data.message_type : void 0;
+	const fromBot = !!data.author?.bot;
+	/** mentions 索引 id -> displayName */
+	const mentionMap = /* @__PURE__ */ new Map();
+	const selfMentionIds = new Set([appid, selfSubId].filter(Boolean));
+	if (ev.t === "MESSAGE_CREATE" || ev.t === "AT_MESSAGE_CREATE") ev.d.mentions?.forEach((v) => {
+		mentionMap.set(v.id, v.username);
+		if (v.id === selfSubId) selfMentionIds.add(v.id);
+	});
+	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);
+		if (v.is_you) {
+			selfMentionIds.add(v.id);
+			selfMentionIds.add(v.member_openid);
+		}
+	});
+	const isSelfAt = (element) => element.type === "at" && selfMentionIds.has(element.targetId);
+	const hasSelfAt = () => elements.some(isSelfAt);
+	const pushAt = (id, name = "") => {
+		const targetId = selfMentionIds.has(id) ? appid : id;
+		if (targetId === appid && hasSelfAt()) {
+			const prev = elements.at(-1);
+			const beforePrev = elements.at(-2);
+			if (prev?.type === "text" && !prev.text.trim() && beforePrev && isSelfAt(beforePrev)) elements.pop();
+			return;
+		}
+		elements.push(segment.at(targetId, name));
+	};
+	/** 将 QQ 附件转换为 Karin 元素。 */
+	const attachments = data.attachments || [];
+	let attachmentIndex = 0;
+	const pushAttachment = (v) => {
+		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.file(url, {
+			name: v.filename,
+			size: v.size
+		}));
+	};
+	/** content 解析 */
+	const tokens = tokenizeContent(data?.content);
+	const cfg = getConfig(appid);
+	for (const tok of tokens) {
+		if (tok.startsWith("<faceType=")) {
+			const m = tok.match(/faceType=(\d+),faceId="([^"]*)",ext="([^"]*)"/);
+			const faceType = Number(m?.[1]);
+			const faceIdText = m?.[2] || "";
+			const faceId = Number(faceIdText);
+			const attachment = attachments[attachmentIndex];
+			if (!faceIdText) {
+				if (attachment?.content_type.startsWith("image/")) {
+					pushAttachment(attachment);
+					attachmentIndex++;
+				} else {
+					const text = getFaceExtText(m?.[3] || "");
+					if (text) elements.push(segment.text(text));
+				}
+				continue;
+			}
+			/**
+			* QQ 将用户收藏表情图片编码为 `faceId=0` + 图片附件。附件在 content 中
+			* 没有独立标签，必须在这个占位符位置消费，才能保留原始元素顺序。
+			*/
+			if (faceId === 0 && (messageType === 103 || faceType === 6) && attachment?.content_type.startsWith("image/")) {
+				pushAttachment(attachment);
+				attachmentIndex++;
+			} else if (faceType === 6 && faceId === 0) {} else if (m) elements.push(segment.face(faceId, faceType === 3));
+			continue;
+		}
+		if (tok.startsWith("<@")) {
+			const id = tok.replace(/^<@!?|>$/g, "");
+			pushAt(id, mentionMap.get(id) || "");
+			continue;
+		}
+		if (tok.startsWith("<qqbot-at-user")) {
+			const id = tok.match(/id="([^"]+)"/)?.[1] || "";
+			pushAt(id, mentionMap.get(id) || "");
+			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.replace(reg, r.rep);
+		}
+		if (!text) continue;
+		if (messageType === 103 && pushQQMarkdown(text, elements)) continue;
+		if (shouldUseMarkdown(messageType, fromBot, text)) {
+			elements.push(segment.markdown(text));
+			continue;
+		}
+		elements.push(segment.text(text));
+	}
+	/** content 中未出现占位符的普通附件，按 QQ 报文顺序追加。 */
+	for (; attachmentIndex < attachments.length; attachmentIndex++) pushAttachment(attachments[attachmentIndex]);
+	/** 群消息是否需要在头部补 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;
+};
+/**
+* 将 QQ 引用上下文转换为 Karin 元素。
+*
+* QQ 不会提供引用消息的正式消息 ID；调用方应以 `msg_idx` 作为缓存键。
+*/
+const convertReferenceToKarin = (appid, ev, selfSubId, reference) => {
+	return convertToKarin(appid, {
+		...ev,
+		d: {
+			...ev.d,
+			content: reference.content,
+			attachments: reference.attachments,
+			mentions: void 0,
+			message_scene: void 0,
+			msg_elements: void 0,
+			message_type: reference.message_type
+		}
+	}, selfSubId);
+};
+
+//#endregion
+//#region src/core/event/message.ts
+/**
+* 写入 getMsg 热缓存并投递 SQLite 后台队列。
+*
+* 不等待数据库落库，避免缓存特性拖慢 Karin 消息事件下发。
+*
+* @param client 当前 QQBot 适配器实例。
+* @param message 需要缓存的消息快照。
+* @param aliases 可用于查询同一消息的 QQ 侧索引，例如 msg_idx。
+*/
+const cacheMessage = (client, message, aliases = []) => {
+	if (!client.cfg.messageCache.enable) return;
+	client.messageStore.save(String(client.cfg.appId), {
+		...message,
+		messageSeq: 0
+	}, aliases).catch((err) => log("warn", `[getMsg] 写入消息缓存失败: ${message.messageId}`, err));
+};
+/**
+* 写入引用消息上下文缓存。
+*
+* 引用上下文没有正式消息 ID 时，以 QQ 的 `ref_msg_idx` 建立只写入一次的缓存。
+*
+* @param client 当前 QQBot 适配器实例。
+* @param message 以 ref_msg_idx 作为 messageId 的引用消息快照。
+*/
+const cacheReference = (client, message) => {
+	if (!client.cfg.messageCache.enable) return;
+	client.messageStore.saveReferenceIfAbsent(String(client.cfg.appId), {
+		...message,
+		messageSeq: 0
+	}).catch((err) => log("warn", `[getMsg] 写入引用上下文失败: ${message.messageId}`, err));
+};
+/**
+* 群消息（@机器人 / 普通消息合并入口）
+*/
+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$1.contactGroup(ev.d.group_openid || ev.d.group_id);
+	const sender = karin$1.groupSender(userId, ev.d.author.member_role || "unknown", username);
+	const elements = convertToKarin(selfId, ev, client.selfSubId("id"), { forceAtSelf: opts.forceAtSelf });
+	const messageIndex = getMessageSceneIndex(ev.d.message_scene, "msg_idx");
+	const referenceIndex = getMessageSceneIndex(ev.d.message_scene, "ref_msg_idx");
+	const karinMessageId = ev.d.id;
+	if (messageIndex) rememberApiMessageId(client, contact, messageIndex, ev.d.id);
+	if (referenceIndex) elements.unshift(segment.reply(referenceIndex));
+	const time = Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp);
+	cacheMessage(client, {
+		messageId: karinMessageId,
+		time,
+		contact,
+		sender,
+		elements
+	}, [ev.d.id, messageIndex].filter((id) => !!id && id !== karinMessageId && id !== referenceIndex));
+	const reference = ev.d.msg_elements?.find((item) => item.msg_idx === referenceIndex);
+	if (reference && referenceIndex) cacheReference(client, {
+		messageId: referenceIndex,
+		time,
+		contact,
+		sender: karin$1.groupSender("", "member", reference.author?.username || ""),
+		elements: convertReferenceToKarin(selfId, ev, client.selfSubId("id"), reference)
+	});
+	const e = createGroupMessage({
+		bot: client,
+		elements,
+		eventId: ev.id,
+		messageId: karinMessageId,
+		messageSeq: 0,
+		rawEvent: ev,
+		time,
+		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$1.contactFriend(userId);
+	const sender = karin$1.friendSender(userId, username);
+	const elements = convertToKarin(selfId, ev, client.selfSubId("id"));
+	const messageIndex = getMessageSceneIndex(ev.d.message_scene, "msg_idx");
+	const referenceIndex = getMessageSceneIndex(ev.d.message_scene, "ref_msg_idx");
+	const karinMessageId = ev.d.id;
+	if (messageIndex) rememberApiMessageId(client, contact, messageIndex, ev.d.id);
+	if (referenceIndex) elements.unshift(segment.reply(referenceIndex));
+	const time = Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp);
+	cacheMessage(client, {
+		messageId: karinMessageId,
+		time,
+		contact,
+		sender,
+		elements
+	}, [ev.d.id, messageIndex].filter((id) => !!id && id !== karinMessageId && id !== referenceIndex));
+	const reference = ev.d.msg_elements?.find((item) => item.msg_idx === referenceIndex);
+	if (reference && referenceIndex) cacheReference(client, {
+		messageId: referenceIndex,
+		time,
+		contact,
+		sender: karin$1.friendSender("", reference.author?.username || ""),
+		elements: convertReferenceToKarin(selfId, ev, client.selfSubId("id"), reference)
+	});
+	const e = createFriendMessage({
+		bot: client,
+		elements,
+		eventId: ev.id,
+		messageId: karinMessageId,
+		messageSeq: 0,
+		rawEvent: ev,
+		time,
+		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$1.contact("guild", ev.d.guild_id, ev.d.channel_id);
+	const sender = karin$1.groupSender(userId, "unknown", ev.d.author.username || "");
+	const elements = convertToKarin(selfId, ev, client.selfSubId("id"));
+	const time = Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp);
+	cacheMessage(client, {
+		messageId: ev.d.id,
+		time,
+		contact,
+		sender,
+		elements
+	});
+	const e = createGuildMessage({
+		bot: client,
+		elements,
+		eventId: ev.id,
+		messageId: ev.d.id,
+		messageSeq: 0,
+		rawEvent: ev,
+		time,
+		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$1.contact("direct", ev.d.guild_id, ev.d.channel_id);
+	const sender = karin$1.friendSender(userId, ev.d.author.username || "");
+	const elements = convertToKarin(selfId, ev, client.selfSubId("id"));
+	const time = Number(new Date(ev.d.timestamp).getTime() || ev.d.timestamp);
+	cacheMessage(client, {
+		messageId: ev.d.id,
+		time,
+		contact,
+		sender,
+		elements
+	});
+	const e = createDirectMessage({
+		bot: client,
+		elements,
+		eventId: ev.id,
+		messageId: ev.d.id,
+		messageSeq: 0,
+		rawEvent: ev,
+		time,
+		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$1.contactGroup(groupId);
+	const sender = karin$1.groupSender(selfId, "member");
+	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$1.contactGroup(groupId);
+	const sender = karin$1.groupSender(selfId, "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"
+		}
+	});
+};
+/**
+* 群成员加入事件。
+*
+* QQ 官方仅下发加入成员，未提供操作人和加入方式；Karin 的通知模型要求
+* `type`，因此以 `approve` 表示已加入，并将 `operatorId` 留空。
+* 该事件不能作为 QQ 被动消息的 `event_id`，回复会按普通消息发送。
+*
+* @param client 机器人实例
+* @param event 官方群成员加入事件
+*/
+const onGroupMemberAdd = (client, event) => {
+	const memberId = event.d.member_openid;
+	const contact = karin$1.contactGroup(event.d.group_openid);
+	const sender = karin$1.groupSender(memberId, "member");
+	createGroupMemberAddNotice({
+		contact,
+		eventId: event.id,
+		sender,
+		srcReply: (elements) => client.sendMsg(contact, elements),
+		bot: client,
+		rawEvent: event,
+		time: event.d.timestamp,
+		content: {
+			operatorId: "",
+			targetId: memberId,
+			type: "approve"
+		}
+	});
+};
+/**
+* 群成员退出事件。
+*
+* QQ 官方仅下发退出成员，未提供操作人和退出原因；Karin 的通知模型要求
+* `type`，因此以 `leave` 表示成员已离开，并将 `operatorId` 留空。
+* 该事件不能作为 QQ 被动消息的 `event_id`，回复会按普通消息发送。
+*
+* @param client 机器人实例
+* @param event 官方群成员退出事件
+*/
+const onGroupMemberRemove = (client, event) => {
+	const memberId = event.d.member_openid;
+	const contact = karin$1.contactGroup(event.d.group_openid);
+	const sender = karin$1.groupSender(memberId, "unknown");
+	createGroupMemberDelNotice({
+		contact,
+		eventId: event.id,
+		sender,
+		srcReply: (elements) => client.sendMsg(contact, elements),
+		bot: client,
+		rawEvent: event,
+		time: event.d.timestamp,
+		content: {
+			operatorId: "",
+			targetId: memberId,
+			type: "leave"
+		}
+	});
+};
+/**
+* 群聊接受机器人主动消息
+* @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$1.contactFriend(userId);
+	const sender = karin$1.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$1.contactFriend(userId);
+	const sender = karin$1.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
+/**
+* 取得互动事件真正用于 ACK 的平台 ID。
+*
+* WebSocket Dispatch 外层也有一个 `id`，形如 `INTERACTION_CREATE:uuid`；按钮 ACK
+* 接口需要的是事件体内的 `d.id`，也就是不带事件名前缀的 uuid。
+*
+* @param ev QQBot 原始互动事件。
+* @returns 可传给 `/interactions/{interaction_id}` 的 ID。
+*/
+const getInteractionId = (ev) => ev.d.id || ev.id;
+/**
+* 构造按钮回调附加给 Karin 消息的元信息。
+*
+* QQBot 不同场景下下发字段差异很大：群聊通常只有 button_data/button_id，
+* 频道才可能带 user_id/message_id/feature_id。这里只写入实际存在的字段，
+* 避免插件侧看到一堆语义不明的空值。
+*
+* @param ev QQBot 原始互动事件。
+* @param interactionId 已确认可用于 ACK 的平台互动 ID。
+* @returns 可放入 segment.json 的精简元信息。
+*/
+const createInteractionMeta = (ev, interactionId) => {
+	const resolved = ev.d.data?.resolved;
+	const meta = {
+		tag: "qqbot-button-click",
+		interaction_id: interactionId,
+		dispatch_id: ev.id,
+		interaction_type: ev.d.type
+	};
+	const optional = {
+		data_type: ev.d.data?.type,
+		chat_type: ev.d.chat_type,
+		scene: ev.d.scene,
+		button_id: resolved?.button_id,
+		button_data: resolved?.button_data,
+		application_id: ev.d.application_id,
+		group_openid: ev.d.group_openid,
+		group_member_openid: ev.d.group_member_openid,
+		user_openid: ev.d.user_openid,
+		guild_id: ev.d.guild_id,
+		channel_id: ev.d.channel_id,
+		guild_user_id: resolved?.user_id,
+		feature_id: resolved?.feature_id,
+		message_id: resolved?.message_id,
+		require_mention: resolved?.require_mention,
+		group_policy: resolved?.group_policy,
+		mention_patterns: resolved?.mention_patterns,
+		version: ev.d.version
+	};
+	for (const [key, value] of Object.entries(optional)) if (value !== void 0 && value !== "") meta[key] = value;
+	return meta;
+};
+/**
+* INTERACTION_CREATE 处理
+*
+* - 先 ack 客户端（必须在 3s 内），失败仅 warn
+* - 借用普通消息事件投递给业务层，业务层通过 e.rawEvent.t === 'INTERACTION_CREATE' 区分
+* - elements 只放 button_data 文本，避免 at/json 段污染 e.msg 导致 command 无法精确匹配
+*/
+const onInteraction = (client, ev) => {
+	const interactionId = getInteractionId(ev);
+	const ackStart = Date.now();
+	client.logger("debug", `[INTERACTION] ack 准备: ${interactionId} dispatch=${ev.id}`);
+	client.super.interaction.ack(interactionId, 0).then(() => {
+		client.logger("debug", `[INTERACTION] ack 成功: ${interactionId} (${Date.now() - ackStart}ms)`);
+	}).catch((err) => {
+		client.logger("warn", "[INTERACTION] ack 失败:", err);
+	}).finally(() => {
+		emitInteractionMessage(client, ev, interactionId);
+	});
+};
+/**
+* 将按钮互动事件转换为 Karin 消息事件。
+*
+* ACK 请求先发出并结束后再投递业务层，避免业务回复请求抢在 ACK 前占用回调窗口。
+*
+* @param client 当前 QQBot 适配器实例。
+* @param ev QQBot 原始互动事件。
+* @param interactionId 已确认可用于 ACK 的平台互动 ID。
+*/
+const emitInteractionMessage = (client, ev, interactionId) => {
+	const buttonData = ev.d.data?.resolved?.button_data || "";
+	const rawEvent = {
+		...ev,
+		buttonMeta: createInteractionMeta(ev, interactionId)
+	};
+	const time = Number(ev.d.timestamp ? new Date(ev.d.timestamp).getTime() : Date.now()) || Date.now();
+	if (ev.d.chat_type === 1 && ev.d.group_openid) {
+		const userId = ev.d.group_member_openid || "";
+		const contact = karin$1.contactGroup(ev.d.group_openid);
+		const sender = karin$1.groupSender(userId, "unknown");
+		const e = createGroupMessage({
+			bot: client,
+			elements: [segment.text(buttonData)],
+			eventId: ev.id,
+			messageId: interactionId,
+			messageSeq: 0,
+			rawEvent,
+			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$1.contactFriend(userId);
+		const sender = karin$1.friendSender(userId, "");
+		const e = createFriendMessage({
+			bot: client,
+			elements: [segment.text(buttonData)],
+			eventId: ev.id,
+			messageId: interactionId,
+			messageSeq: 0,
+			rawEvent,
+			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$1.contact("guild", ev.d.guild_id, ev.d.channel_id);
+		const sender = karin$1.groupSender(userId, "unknown");
+		const e = createGuildMessage({
+			bot: client,
+			elements: [segment.text(buttonData)],
+			eventId: ev.id,
+			messageId: interactionId,
+			messageSeq: 0,
+			rawEvent,
+			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_MEMBER_ADD"]: "群成员加入",
+	["GROUP_MEMBER_REMOVE"]: "群成员退出",
+	["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_MEMBER_ADD":
+			onGroupMemberAdd(client, ev);
+			return;
+		case "GROUP_MEMBER_REMOVE":
+			onGroupMemberRemove(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: client.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
+	},
+	4004: {
+		message: "鉴权失败或 access_token 无效",
+		canResume: false,
+		canIdentify: true
+	},
+	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";
+	openedAt = 0;
+	lastAuthAction;
+	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, { headers: { "User-Agent": this.opts.userAgent } });
+		this.socket = ws;
+		ws.on("open", () => {
+			this.openedAt = Date.now();
+			log("debug", `${this.opts.appId}: WebSocket opened (${this.opts.gatewayUrl})`);
+		});
+		ws.on("close", (code, reason) => {
+			const remoteReason = reason?.toString() || "";
+			const closeInfo = formatWSClose(code, remoteReason);
+			const info = getWSErrorInfo(code);
+			log("error", `${this.opts.appId}: WebSocket 关闭 | ${closeInfo}`);
+			if (this.closed) return;
+			this.close("closed", {
+				code,
+				remoteReason: remoteReason || void 0,
+				durationMs: this.durationMs(),
+				canResume: info?.canResume,
+				canIdentify: info?.canIdentify
+			});
+		});
+		ws.on("error", (err) => {
+			log("error", `${this.opts.appId}: WebSocket error:`, err);
+			if (this.closed) return;
+			this.close("error", { durationMs: this.durationMs() });
+		});
+		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, event = {}) {
+		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,
+			...event
+		});
+	}
+	durationMs() {
+		return this.openedAt ? Date.now() - this.openedAt : void 0;
+	}
+	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.lastAuthAction = "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.lastAuthAction = "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.lastAuthAction = void 0;
+					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: {
+				const canResume = msg.d === true;
+				if (this.lastAuthAction === "identify") {
+					log("error", `${this.opts.appId}: identify rejected (op:9), will try fallback intents, canResume=${canResume}`);
+					this.close("auth_fail", {
+						durationMs: this.durationMs(),
+						invalidSessionCanResume: canResume
+					});
+				} else if (canResume && this.sessionId) {
+					log("debug", `${this.opts.appId}: invalid session, server allows resume`);
+					this.close("reconnect", {
+						durationMs: this.durationMs(),
+						invalidSessionCanResume: true
+					});
+				} else {
+					log("debug", `${this.opts.appId}: invalid session, will retry with fresh identify, canResume=${canResume}`);
+					this.sessionId = "";
+					this.seq = 0;
+					this.close("session_lost", {
+						durationMs: this.durationMs(),
+						invalidSessionCanResume: canResume
+					});
+				}
+				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 << 24]: "群成员进退群事件",
+	[1 << 25]: "GROUP_AND_C2C_EVENT (群聊/单聊消息)",
+	[1 << 26]: "INTERACTION          (按钮交互回调)",
+	[1 << 30]: "PUBLIC_GUILD_MESSAGES (频道消息-公域)"
+};
+/** 优先级从高到低，回退时从最前面剥离 */
+const priorityIntents = [
+	2,
+	512,
+	1 << 30,
+	4096,
+	1 << 24,
+	1 << 26,
+	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;
+const RATE_LIMIT_DELAY_MS = 6e4;
+const QUICK_DISCONNECT_THRESHOLD_MS = 5e3;
+const QUICK_DISCONNECT_LIMIT = 3;
+const QUICK_DISCONNECT_DELAY_MS = 6e4;
+/**
+* 从 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}`,
+				"User-Agent": getUserAgent()
+			},
+			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],
+		quickDisconnects: 0,
+		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;
+	let gatewayUrl = conn.gatewayUrl;
+	if (!gatewayUrl) gatewayUrl = await fetchGateway(cfg);
+	conn = conns.get(cfg.appId);
+	if (!conn || conn.aborted) return;
+	conn.gatewayUrl = gatewayUrl;
+	const client = new WSClient({
+		appId: cfg.appId,
+		gatewayUrl,
+		userAgent: getUserAgent(),
+		getAccessToken: () => getBotAccessToken(cfg.appId) || "",
+		intents,
+		resume,
+		onEvent: (ev) => {
+			if (ev.t === "READY") summarize(cfg.appId, intents, true);
+			dispatch(cfg.appId, ev);
+		},
+		onClose: (event) => onClose(cfg, intents, attempt, event, 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, event, client) => {
+	if (event.reason === "manual") {
+		log("debug", `${cfg.appId}: WebSocket 已主动关闭`);
+		return;
+	}
+	const conn = conns.get(cfg.appId);
+	if (!conn || conn.aborted) return;
+	const code = event.code;
+	const closeLabel = formatCloseLabel(event);
+	if (event.reason === "auth_fail" || code === 4013 || code === 4014) {
+		const fallback = computeFallback(intents);
+		if (fallback && fallback !== intents) {
+			log("warn", `${cfg.appId}: Identify 被拒，尝试降级 intents ${intents} -> ${fallback}`);
+			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;
+	}
+	if (code === 4914 || code === 4915) {
+		summarize(cfg.appId, intents, false);
+		log("error", `${cfg.appId}: WebSocket 断开 (${closeLabel})，机器人状态不允许连接，已停止自动重连`);
+		conn.aborted = true;
+		conns.delete(cfg.appId);
+		return;
+	}
+	if (event.canResume === false && event.canIdentify === false) {
+		summarize(cfg.appId, intents, false);
+		log("error", `${cfg.appId}: WebSocket 断开 (${closeLabel})，该错误不建议重试，已停止自动重连`);
+		conn.aborted = true;
+		conns.delete(cfg.appId);
+		return;
+	}
+	if (code === 4004) {
+		log("warn", `${cfg.appId}: access_token 已失效，刷新 token 后重连...`);
+		schedule(cfg.appId, 1e3, () => {
+			getAccessToken(cfg.tokenApi, cfg.appId, cfg.secret).then(() => connect(cfg, intents, 0)).catch(() => {
+				log("error", `${cfg.appId}: access_token 刷新失败，${RATE_LIMIT_DELAY_MS}ms 后重试连接...`);
+				schedule(cfg.appId, RATE_LIMIT_DELAY_MS, () => connect(cfg, intents, attempt + 1));
+			});
+		});
+		return;
+	}
+	const snap = client.snapshot();
+	const resume = event.reason === "session_lost" || shouldFreshIdentify(code) ? void 0 : snap.sessionId ? snap : void 0;
+	const delay = reconnectDelay(conn, attempt, event, code === 4008 ? RATE_LIMIT_DELAY_MS : void 0);
+	const nextAttempt = shouldResetAttempt(event) ? 0 : attempt + 1;
+	log("error", `${cfg.appId}: WebSocket 断开 (${closeLabel})，${delay}ms 后${resume ? "Resume" : "Identify"}重连...`);
+	schedule(cfg.appId, delay, () => connect(cfg, intents, nextAttempt, resume));
+};
+const shouldFreshIdentify = (code) => {
+	if (code === 4006 || code === 4007 || code === 4009) return true;
+	return typeof code === "number" && code >= 4900 && code <= 4913;
+};
+const shouldResetAttempt = (event) => {
+	return typeof event.durationMs === "number" && event.durationMs >= QUICK_DISCONNECT_THRESHOLD_MS;
+};
+const reconnectDelay = (conn, attempt, event, forcedDelay) => {
+	const stable = shouldResetAttempt(event);
+	let delay = forcedDelay ?? backoff(stable ? 0 : attempt);
+	if (typeof event.durationMs !== "number") return delay;
+	if (event.durationMs >= QUICK_DISCONNECT_THRESHOLD_MS) {
+		conn.quickDisconnects = 0;
+		return delay;
+	}
+	conn.quickDisconnects += 1;
+	if (conn.quickDisconnects >= QUICK_DISCONNECT_LIMIT) {
+		delay = Math.max(delay, QUICK_DISCONNECT_DELAY_MS);
+		log("warn", `${conn.cfg.appId}: WebSocket 连续快速断开 ${conn.quickDisconnects} 次，延长重连间隔到 ${delay}ms`);
+	}
+	return delay;
+};
+const formatCloseLabel = (event) => {
+	const parts = [event.reason];
+	if (typeof event.code === "number") parts.push(String(event.code));
+	if (event.remoteReason) parts.push(event.remoteReason);
+	return parts.join(" / ");
+};
+/**
+* 停止连接（同步：标记 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,
+	messageCache: bot.messageCache
+});
+/**
+* 创建单个 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 = "*********";
+		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();
-initQQBotAdapter();
+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 {  };