@karinjs/adapter-qqbot 2.1.0 → 3.0.0

package/dist/{onboard-DPWgX39H.js → onboard-vIEoe9dB.js}

@@ -1,4 +1,4 @@
-import { a as writeConfig, c as log, i as getDefaultConfig, n as config } from "./config-DKa7596f.js";
+import { i as getDefaultConfig, m as log, n as config, o as writeConfig } from "./config-BUuU6FnQ.js";
 import { a as sleep } from "./common-by1GpV0b.js";
 import qrcode from "qrcode";
 import axios from "node-karin/axios";

package/dist/utils-N9PNiHjE.js

@@ -0,0 +1,4 @@
+import "./config-BUuU6FnQ.js";
+import "./common-by1GpV0b.js";
+
+export {  };

package/dist/web.config.d.ts

@@ -1,22 +1,27 @@
 //#region src/web.config.d.ts
-declare const _default: import("node-karin").DefineConfig<{
-  qqbot: Array<{
-    name: string;
-    appId: string;
-    secret: string;
-    prodApi: string;
-    sandboxApi: string;
-    tokenApi: string;
-    sandbox: boolean;
-    qqEnable: boolean;
-    guildEnable: boolean;
-    guildMode: boolean;
-    regex: string[];
-    "keyboard:enable": boolean;
-    "messageCache:enable": boolean;
-    "messageCache:self": boolean;
-    "event:type": string;
-  }>;
-}>;
+type WebQQBotInput = {
+  name: unknown;
+  appId: unknown;
+  secret: unknown;
+  'proxy:api': unknown;
+  'proxy:ws': unknown;
+  sandbox: unknown;
+  qqEnable: unknown;
+  guildEnable: unknown;
+  guildMode: unknown;
+  regex: unknown;
+  'keyboard:enable': unknown;
+  'markdown:enable': unknown;
+  'messageCache:enable': unknown;
+  'messageCache:self': unknown;
+  'messageCache:level': unknown;
+  'messageCache:ttlHours': unknown;
+  'messageCache:maxRows': unknown;
+  'event:type': unknown;
+};
+type WebConfigInput = {
+  qqbot: WebQQBotInput[];
+};
+declare const _default: import("node-karin").DefineComponentConfig<WebConfigInput>;
 //#endregion
 export { _default as default };

package/dist/web.config.js

@@ -1,8 +1,92 @@
-import { a as writeConfig, n as config, o as pkg } from "./config-DKa7596f.js";
-import "./utils-BPbnNAix.js";
+import { a as readConfigFile, f as pkg, i as getDefaultConfig, n as config, o as writeConfig, s as buildFallbackWsUrlFromApi, u as normalizeProxyConfig } from "./config-BUuU6FnQ.js";
+import "./utils-N9PNiHjE.js";
 import { components, defineConfig } from "node-karin";
 
 //#region src/web.config.ts
+const defaultProxy = () => getDefaultConfig()[0].proxy;
+const unwrapValue = (value) => {
+	if (value && typeof value === "object" && "value" in value) return value.value;
+	return value;
+};
+const toBool = (value, fallback) => {
+	const raw = unwrapValue(value);
+	if (typeof raw === "boolean") return raw;
+	if (typeof raw === "number") return raw !== 0;
+	if (typeof raw === "string") {
+		const normalized = raw.trim().toLowerCase();
+		if ([
+			"false",
+			"0",
+			"off",
+			"no",
+			""
+		].includes(normalized)) return false;
+		if ([
+			"true",
+			"1",
+			"on",
+			"yes"
+		].includes(normalized)) return true;
+	}
+	if (raw === null || raw === void 0) return fallback;
+	return fallback;
+};
+const toStringValue = (value, fallback = "") => {
+	const raw = unwrapValue(value);
+	if (typeof raw === "string") return raw;
+	if (raw === null || raw === void 0) return fallback;
+	return String(raw);
+};
+const toStringList = (value) => {
+	const raw = unwrapValue(value);
+	if (!Array.isArray(raw)) return [];
+	return raw.map((item) => toStringValue(item)).filter(Boolean);
+};
+const proxyKeys = (sandbox) => sandbox ? {
+	api: "sandboxApi",
+	ws: "sandboxWs"
+} : {
+	api: "prodApi",
+	ws: "prodWs"
+};
+const getBotProxyInput = (item) => {
+	const keys = proxyKeys(!!item.sandbox);
+	const proxy = item.proxy || defaultProxy();
+	return {
+		"proxy:api": proxy[keys.api] || defaultProxy()[keys.api],
+		"proxy:ws": proxy[keys.ws] || defaultProxy()[keys.ws]
+	};
+};
+const proxyFromInput = (item, previous) => {
+	const def = defaultProxy();
+	const sandbox = toBool(item.sandbox, previous?.sandbox ?? false);
+	const previousSandbox = previous?.sandbox ?? sandbox;
+	const keys = proxyKeys(sandbox);
+	const previousVisibleKeys = proxyKeys(previousSandbox);
+	const previousProxy = previous?.proxy;
+	const base = {
+		...def,
+		...previousProxy
+	};
+	const envChanged = !!previous && previousSandbox !== sandbox;
+	const rawApi = toStringValue(item["proxy:api"]).trim();
+	const rawWs = toStringValue(item["proxy:ws"]).trim();
+	const previousVisibleApi = previousProxy?.[previousVisibleKeys.api] || def[previousVisibleKeys.api];
+	const previousVisibleWs = previousProxy?.[previousVisibleKeys.ws] || def[previousVisibleKeys.ws];
+	const api = envChanged && rawApi === previousVisibleApi ? base[keys.api] || def[keys.api] : rawApi || base[keys.api] || def[keys.api];
+	const previousApi = previousProxy?.[keys.api] || def[keys.api];
+	const previousWs = previousProxy?.[keys.ws] || def[keys.ws];
+	const wsInput = envChanged && rawWs === previousVisibleWs ? base[keys.ws] || def[keys.ws] : rawWs;
+	let ws = wsInput || previousWs || def[keys.ws];
+	const previousAutoWs = buildFallbackWsUrlFromApi(previousApi);
+	if (!wsInput || wsInput === previousWs && previousWs === previousAutoWs && api !== previousApi) ws = buildFallbackWsUrlFromApi(api);
+	return normalizeProxyConfig({
+		...base,
+		[keys.api]: api,
+		tokenApi: base.tokenApi || def.tokenApi,
+		[keys.ws]: ws
+	});
+};
 var web_config_default = defineConfig({
 	info: {
 		id: pkg().name,
@@ -23,120 +107,173 @@ var web_config_default = defineConfig({
 				name: item.name,
 				appId: item.appId,
 				secret: item.secret,
-				prodApi: item.prodApi,
-				sandboxApi: item.sandboxApi,
-				tokenApi: item.tokenApi,
+				"event:type": String(item.event?.type ?? 2),
 				sandbox: item.sandbox,
 				qqEnable: item.qqEnable,
 				guildEnable: item.guildEnable,
 				guildMode: item.guildMode === 1,
 				regex: item.regex.map((r) => `${r.reg} ${r.rep}`),
 				"keyboard:enable": item.keyboard?.enable !== false,
+				"markdown:enable": item.markdown?.enable !== false,
 				"messageCache:enable": item.messageCache?.enable === true,
 				"messageCache:self": item.messageCache?.self === true,
-				"event:type": String(item.event?.type ?? 2)
+				"messageCache:level": item.messageCache?.level || "standard",
+				"messageCache:ttlHours": String(item.messageCache?.ttlHours ?? 24),
+				"messageCache:maxRows": String(item.messageCache?.maxRows ?? 2e5),
+				...getBotProxyInput(item)
 			});
 		});
-		return [components.accordionPro.create("qqbot", data, {
-			label: "QQBot",
-			description: "QQBot 配置",
+		return [components.divider.horizontal("bot-section", {
+			description: "机器人账号",
+			descPosition: 5
+		}), components.accordionPro.create("qqbot", data, {
+			label: "QQ 官方机器人列表",
+			description: "每一项对应一个 QQ 官方机器人账号。新增机器人时先填 AppID 和 Secret，再按需调整接收方式、场景能力和发送能力。",
 			children: {
 				key: "qqbotConfig",
 				children: [
+					components.radio.group("event:type", {
+						label: "事件接收方式",
+						description: "QQ 官方机器人只有 Webhook 推送和 WebSocket 主动连接两种接收方式。不确定时选择 WebSocket；如果 QQ 后台已启用 Webhook，可在下方高级设置填写第三方 Webhook 转 WebSocket 服务地址。",
+						defaultValue: "2",
+						radio: [
+							components.radio.create("0", {
+								label: "关闭接收",
+								value: "0",
+								description: "停用这个机器人，不连接 WebSocket，也不接收 Webhook 事件。"
+							}),
+							components.radio.create("1", {
+								label: "Webhook 推送",
+								value: "1",
+								description: "由 QQ 官方把事件推送到 Karin 的 /qqbot/webhook 路由。通常需要公网地址，并在 QQ 后台配置回调地址。"
+							}),
+							components.radio.create("2", {
+								label: "WebSocket 主动连接",
+								value: "2",
+								description: "适配器主动连接 WebSocket 地址接收事件。默认连接 QQ 官方网关；如果 QQ 后台已开 Webhook，可改为第三方 Webhook 转 WebSocket 服务地址。"
+							})
+						]
+					}),
+					components.divider.horizontal("bot-basic-section", {
+						description: "基础信息",
+						descPosition: 5
+					}),
 					components.input.create("name", {
-						label: "机器人名称",
-						description: "机器人名称，扫码登录会自动获取"
+						label: "机器人显示名称",
+						description: "只用于 Karin 配置页和日志里识别这个机器人，不影响 QQ 平台资料。扫码登录写入配置时通常会自动填充。"
 					}),
 					components.input.create("appId", {
-						label: "AppID",
-						description: "机器人 AppID",
+						label: "机器人 AppID",
+						description: "QQ 开放平台机器人应用的 AppID，是识别机器人账号的唯一编号。填错会导致鉴权和收发消息失败。",
 						isRequired: true
 					}),
 					components.input.create("secret", {
-						label: "Secret",
-						description: "机器人 Secret",
+						label: "机器人 Secret",
+						description: "QQ 开放平台机器人应用的 Secret，用于获取 access token。请不要泄露；扫码授权会刷新 Secret，旧 Secret 会立即失效。",
 						isRequired: true
 					}),
-					components.input.create("prodApi", {
-						label: "正式环境 API",
-						defaultValue: "https://api.sgroup.qq.com",
-						isRequired: true
-					}),
-					components.input.create("sandboxApi", {
-						label: "沙盒环境 API",
-						defaultValue: "https://sandbox.api.sgroup.qq.com",
-						isRequired: true
-					}),
-					components.input.create("tokenApi", {
-						label: "AccessToken 接口",
-						defaultValue: "https://bots.qq.com/app/getAppAccessToken",
-						isRequired: true
+					components.divider.horizontal("bot-scene-section", {
+						description: "场景能力",
+						descPosition: 5
 					}),
 					components.switch.create("sandbox", {
-						label: "沙盒环境",
-						description: "启用后调用沙盒 API",
+						label: "使用沙盒环境",
+						description: "开启后这个机器人会使用沙盒环境的 OpenAPI 和 WebSocket 地址；关闭时使用正式环境地址。正式上线机器人请关闭。",
 						defaultSelected: false
 					}),
 					components.switch.create("qqEnable", {
-						label: "QQ 场景",
-						description: "是否处理私聊和群聊消息",
+						label: "启用 QQ 私聊 / 群聊",
+						description: "开启后会处理 QQ 单聊和群聊里的消息事件；如果这个机器人只用于频道，可以关闭。",
 						defaultSelected: true
 					}),
 					components.switch.create("guildEnable", {
-						label: "频道场景",
-						description: "是否处理频道消息",
+						label: "启用频道消息",
+						description: "开启后会处理 QQ 频道消息事件；如果这个机器人只用于私聊或群聊，可以关闭。",
 						defaultSelected: true
 					}),
 					components.switch.create("guildMode", {
-						label: "频道私域模式",
-						description: "开启 = 私域机器人；关闭 = 公域机器人",
+						label: "频道私域机器人模式",
+						description: "关闭时按公域机器人处理，通常只接收 @ 机器人相关消息；开启时按私域机器人处理，可接收更多频道消息，需确认机器人权限匹配。",
 						defaultSelected: false
 					}),
+					components.divider.horizontal("bot-message-section", {
+						description: "消息发送",
+						descPosition: 5
+					}),
 					components.input.group("regex", {
 						data: [],
 						label: "消息正则替换",
-						description: "每行格式：正则表达式 替换内容。如：^/ #",
+						description: "收到文本消息后，先按这里的规则替换内容，再交给 Karin 插件处理。每行格式是“正则表达式 替换内容”，中间用空格分隔；例如“^/ #”会把“/菜单”改成“#菜单”。不懂正则可以保留默认或清空。",
 						template: components.input.create("regex", {
-							label: "正则规则",
+							label: "一条替换规则",
 							placeholder: "^/ #"
 						})
 					}),
 					components.switch.create("keyboard:enable", {
-						label: "URL 自动按钮",
-						description: "将文本中的链接自动转为 keyboard 按钮",
+						label: "把链接自动转成按钮",
+						description: "开启后，发送文本里出现的 http(s) 链接会尽量转成 QQ keyboard 按钮，用户可以直接点按钮打开链接。该能力依赖 Markdown 通道。",
 						defaultSelected: true
 					}),
+					components.switch.create("markdown:enable", {
+						label: "启用 Markdown 发送通道",
+						description: "开启后普通文本和图片优先合并为 QQ Markdown 消息，Markdown 里的图片会以内嵌图片形式发送；关闭后普通图片会按官方富媒体单独上传发送。插件显式传入的 segment.markdown 不受此开关影响。",
+						defaultSelected: true
+					}),
+					components.divider.horizontal("bot-cache-section", {
+						description: "消息缓存",
+						descPosition: 5
+					}),
 					components.switch.create("messageCache:enable", {
-						label: "启用数据库缓存消息",
-						description: "用于 bot.getMsg 查询最近一天消息。开启后会将收到的消息写入本地数据库，并把接收到的富媒体保存到本地；高并发或富媒体消息量较大时不建议开启，可能快速占用磁盘空间甚至导致磁盘溢出。",
+						label: "缓存收到的消息到数据库",
+						description: "开启后会把最近一天收到的消息写入本地数据库，供 bot.getMsg 等查询使用；收到的图片、语音、视频等富媒体也会保存到本地。消息量大时会明显占用磁盘空间。",
 						defaultSelected: false
 					}),
 					components.switch.create("messageCache:self", {
-						label: "缓存自己消息",
-						description: "仅在启用数据库缓存消息时生效，发送成功后缓存机器人自己的消息",
+						label: "同时缓存机器人自己发出的消息",
+						description: "只有开启“缓存收到的消息到数据库”后才生效。开启后，机器人发送成功的消息也会写入缓存，方便之后通过消息 ID 查询。",
 						defaultSelected: false
 					}),
-					components.radio.group("event:type", {
-						label: "事件接收方式",
-						description: "选择 QQ 官方推送事件的方式",
-						defaultValue: "2",
+					components.radio.group("messageCache:level", {
+						label: "缓存存储分级",
+						description: "控制每条消息落库的内容多少，直接影响数据库体积。撤回和引用解析在任何分级下都可用。",
+						defaultValue: "standard",
 						radio: [
-							components.radio.create("0", {
-								label: "关闭",
-								value: "0",
-								description: "不接收任何事件"
+							components.radio.create("minimal", {
+								label: "最小",
+								value: "minimal",
+								description: "只记录消息 ID 映射与引用关系，不保存正文和媒体，体积最小。"
 							}),
-							components.radio.create("1", {
-								label: "Webhook",
-								value: "1",
-								description: "QQ 官方主动推送事件到本机"
+							components.radio.create("standard", {
+								label: "标准（推荐）",
+								value: "standard",
+								description: "保存文本、表情和媒体本地文件，不保存 markdown 原文。"
 							}),
-							components.radio.create("2", {
-								label: "WebSocket",
-								value: "2",
-								description: "主动连接 QQ 官方 WebSocket 网关接收事件（推荐）"
+							components.radio.create("full", {
+								label: "完整",
+								value: "full",
+								description: "所有支持的消息段原样保存，包含 markdown 原文，体积最大。"
 							})
 						]
+					}),
+					components.input.create("messageCache:ttlHours", {
+						label: "缓存保留小时数",
+						description: "超过该时长的消息会被清理任务删除。范围 1~720 小时，默认 24。多个机器人同时开启缓存时按最大值生效。"
+					}),
+					components.input.create("messageCache:maxRows", {
+						label: "缓存最大消息条数",
+						description: "数据库消息行数硬上限，超出后从最旧的消息开始删除，保证磁盘占用可预期。范围 1000~5000000，默认 200000。"
+					}),
+					components.divider.horizontal("bot-proxy-section", {
+						description: "连接代理（高级设置：通常只在使用 Webhook 转 WebSocket 服务时填写，除非你知道你在做什么，否则不建议更改）",
+						descPosition: 5
+					}),
+					components.input.create("proxy:ws", {
+						label: "WebSocket 接入地址",
+						description: "事件接收方式为 WebSocket 时连接的地址。常见用途是填写第三方 Webhook 转 WebSocket 服务地址，因为 QQ 后台开启 Webhook 后通常无法再直连官方 WebSocket。不填会使用当前环境的官方默认网关。"
+					}),
+					components.input.create("proxy:api", {
+						label: "OpenAPI 反代地址",
+						description: "用于发送消息、上传媒体、查询网关和获取机器人资料的 QQ OpenAPI 根地址。多数 Webhook 转 WebSocket 场景不用改这里；只有 OpenAPI 请求也需要走反代时才填写。"
 					})
 				]
 			}
@@ -147,41 +284,75 @@ var web_config_default = defineConfig({
 			success: false,
 			message: "保存失败：配置格式错误"
 		};
-		const data = input.qqbot.map((item) => {
-			const guildMode = item.guildMode === true ? 1 : 0;
-			const eventType = Number(item["event:type"] ?? 0);
-			const regex = (item.regex || []).map((str) => {
-				const parts = str.split(" ");
+		const prevConfig = readConfigFile();
+		let data;
+		try {
+			data = input.qqbot.map((item) => {
+				const previous = prevConfig.find((cfg) => cfg.appId === toStringValue(item.appId));
+				const sandbox = toBool(item.sandbox, previous?.sandbox ?? false);
+				const qqEnable = toBool(item.qqEnable, previous?.qqEnable ?? true);
+				const guildEnable = toBool(item.guildEnable, previous?.guildEnable ?? true);
+				const guildMode = toBool(item.guildMode, previous?.guildMode === 1) ? 1 : 0;
+				const eventType = Number(toStringValue(item["event:type"], String(previous?.event?.type ?? 0)));
+				const keyboardEnable = toBool(item["keyboard:enable"], previous?.keyboard?.enable ?? true);
+				const markdownEnable = toBool(item["markdown:enable"], previous?.markdown?.enable ?? true);
+				const messageCacheEnable = toBool(item["messageCache:enable"], previous?.messageCache?.enable ?? false);
+				const messageCacheSelf = toBool(item["messageCache:self"], previous?.messageCache?.self ?? false);
+				/** 枚举与数值范围由 writeConfig 内的 formatConfig 统一校验回落。 */
+				const messageCacheLevel = toStringValue(item["messageCache:level"], previous?.messageCache?.level ?? "standard");
+				/** 输入被清空时回落上次值/默认值，避免 Number('') = 0 被夹到范围下限。 */
+				const ttlHoursRaw = toStringValue(item["messageCache:ttlHours"]).trim();
+				const messageCacheTtlHours = ttlHoursRaw ? Number(ttlHoursRaw) : previous?.messageCache?.ttlHours ?? 24;
+				const maxRowsRaw = toStringValue(item["messageCache:maxRows"]).trim();
+				const messageCacheMaxRows = maxRowsRaw ? Number(maxRowsRaw) : previous?.messageCache?.maxRows ?? 2e5;
+				const regex = toStringList(item.regex).map((str) => {
+					const parts = str.split(" ");
+					return {
+						reg: parts[0]?.replace(/^<|>$/g, "") || "",
+						rep: parts[1]?.replace(/^<|>$/g, "") || ""
+					};
+				});
+				const proxy = proxyFromInput(item, previous);
 				return {
-					reg: parts[0]?.replace(/^<|>$/g, "") || "",
-					rep: parts[1]?.replace(/^<|>$/g, "") || ""
+					name: toStringValue(item.name),
+					appId: toStringValue(item.appId),
+					secret: toStringValue(item.secret),
+					proxy,
+					sandbox,
+					qqEnable,
+					guildEnable,
+					guildMode,
+					regex,
+					keyboard: { enable: keyboardEnable },
+					markdown: { enable: markdownEnable },
+					messageCache: {
+						enable: messageCacheEnable,
+						self: messageCacheSelf,
+						level: messageCacheLevel,
+						ttlHours: messageCacheTtlHours,
+						maxRows: messageCacheMaxRows
+					},
+					event: { type: eventType }
 				};
 			});
+		} catch (err) {
 			return {
-				name: item.name || "",
-				appId: item.appId || "",
-				secret: item.secret || "",
-				prodApi: item.prodApi || "https://api.sgroup.qq.com",
-				sandboxApi: item.sandboxApi || "https://sandbox.api.sgroup.qq.com",
-				tokenApi: item.tokenApi || "https://bots.qq.com/app/getAppAccessToken",
-				sandbox: !!item.sandbox,
-				qqEnable: !!item.qqEnable,
-				guildEnable: !!item.guildEnable,
-				guildMode,
-				regex,
-				keyboard: { enable: item["keyboard:enable"] !== false },
-				messageCache: {
-					enable: !!item["messageCache:enable"],
-					self: !!item["messageCache:self"]
-				},
-				event: { type: eventType }
+				success: false,
+				message: `保存失败：代理地址格式错误：${err?.message || "unknown"}`
 			};
-		});
-		writeConfig(data);
-		return {
-			success: true,
-			message: "保存成功"
-		};
+		}
+		try {
+			writeConfig(data);
+			return {
+				success: true,
+				message: "保存成功"
+			};
+		} catch (err) {
+			return {
+				success: false,
+				message: `保存失败：${err?.message || "unknown"}`
+			};
+		}
 	}
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karinjs/adapter-qqbot",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "karin adapter for QQ Official Bot (2.0)",
   "homepage": "https://github.com/KarinJS/karin-plugin-adapter-qqbot",
   "bugs": {
@@ -24,7 +24,8 @@
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "pub": "npm publish --access public",
-    "sort": "npx sort-package-json"
+    "sort": "npx sort-package-json",
+    "test": "node tests/schema-sql.test.mjs && node tests/codec.test.mjs && node tests/store.test.mjs"
   },
   "dependencies": {
     "@karinjs/geturls": "^1.0.2",
@@ -35,14 +36,15 @@
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {
+    "@tencent-connect/qqbot-nodejs": "^1.0.4",
     "@types/express": "5.0.6",
-    "@types/node": "^24.13.2",
+    "@types/node": "^24.13.3",
     "@types/qrcode": "^1.5.6",
     "eslint": "^9.39.4",
     "neostandard": "^0.13.0",
-    "node-karin": "^1.15.5",
-    "tsdown": "^0.22.3",
-    "tsx": "^4.22.4",
+    "node-karin": "1.16.3",
+    "tsdown": "^0.22.13",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3"
   },
   "publishConfig": {