@karinjs/adapter-qqbot 2.1.0 → 2.2.1

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-B_Gc9JKZ.js";
+import "./utils-DIq0lGMt.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,140 @@ 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)
+				...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",
-						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",
+						label: "机器人 Secret",
+						description: "QQ 开放平台机器人应用的 Secret，用于获取 access token。请不要泄露；扫码授权会刷新 Secret，旧 Secret 会立即失效。",
 						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",
-						radio: [
-							components.radio.create("0", {
-								label: "关闭",
-								value: "0",
-								description: "不接收任何事件"
-							}),
-							components.radio.create("1", {
-								label: "Webhook",
-								value: "1",
-								description: "QQ 官方主动推送事件到本机"
-							}),
-							components.radio.create("2", {
-								label: "WebSocket",
-								value: "2",
-								description: "主动连接 QQ 官方 WebSocket 网关接收事件（推荐）"
-							})
-						]
+					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 +251,65 @@ 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);
+				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
+					},
+					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": "2.2.1",
   "description": "karin adapter for QQ Official Bot (2.0)",
   "homepage": "https://github.com/KarinJS/karin-plugin-adapter-qqbot",
   "bugs": {
@@ -40,9 +40,9 @@
     "@types/qrcode": "^1.5.6",
     "eslint": "^9.39.4",
     "neostandard": "^0.13.0",
-    "node-karin": "^1.15.5",
+    "node-karin": "1.16.3",
     "tsdown": "^0.22.3",
-    "tsx": "^4.22.4",
+    "tsx": "^4.23.0",
     "typescript": "^6.0.3"
   },
   "publishConfig": {

package/dist/config-DKa7596f.js

@@ -1,170 +0,0 @@
-import { common, karinPathBase, logger, requireFileSync, watch } from "node-karin";
-import path from "path";
-import { fileURLToPath } from "url";
-import fs from "node:fs";
-
-//#region src/root.ts
-/** 当前文件的绝对路径 */
-const filePath = fileURLToPath(import.meta.url);
-/** 插件包绝对路径 */
-const dirPath = path.resolve(filePath, "../..");
-/** 插件包的名称 */
-const basename = path.basename(dirPath);
-
-//#endregion
-//#region src/utils/logger.ts
-const PREFIX = "[QQ Official Bot]";
-const m = {
-	trace: (...a) => logger.trace(PREFIX, ...a),
-	debug: (...a) => logger.debug(PREFIX, ...a),
-	info: (...a) => logger.info(PREFIX, ...a),
-	warn: (...a) => logger.warn(PREFIX, ...a),
-	error: (...a) => logger.error(PREFIX, ...a),
-	fatal: (...a) => logger.fatal(PREFIX, ...a),
-	mark: (...a) => logger.mark(PREFIX, ...a)
-};
-/**
-* QQBot 日志函数
-* - log('info', '消息')
-* - log.info('消息')
-*
-* 日志级别由 karin 框架的 log.level 控制
-*/
-function log(level, ...args) {
-	m[level](...args);
-}
-Object.assign(log, m);
-
-//#endregion
-//#region src/utils/plugin.ts
-/**
-* 读取当前插件的 package.json。
-*
-* @returns package.json 内容。
-*/
-const pkg = () => requireFileSync(`${dirPath}/package.json`);
-/** 当前插件 npm 包名，如 @karinjs/adapter-qqbot。 */
-const pluginName = pkg().name;
-/** 文件系统目录名：把 npm 包名里的 `/` 规范化为 `-`，与 Karin 框架对齐。 */
-const pluginDirName = pluginName.replace(/\//g, "-");
-
-//#endregion
-//#region src/utils/config.ts
-let cache;
-const cacheMap = {};
-/** 延迟注入，避免与 core/index.ts 循环依赖 */
-let _createBot;
-let _destroyBot;
-const bindHandlers = (createBot, destroyBot) => {
-	_createBot = createBot;
-	_destroyBot = destroyBot;
-};
-/** 配置目录：${karinPathBase}/@karinjs-adapter-qqbot/config */
-const dirConfig = `${karinPathBase}/${pluginDirName}/config`;
-/**
-* 读取配置
-*/
-const config = () => {
-	const cfgPath = `${dirConfig}/config.json`;
-	if (!fs.existsSync(cfgPath)) {
-		fs.mkdirSync(dirConfig, { recursive: true });
-		fs.writeFileSync(cfgPath, JSON.stringify([], null, 2));
-	}
-	if (cache) return cache;
-	const result = formatConfig(requireFileSync(cfgPath));
-	cache = result;
-	result.forEach((v) => {
-		cacheMap[v.appId] = v;
-	});
-	return result;
-};
-/**
-* 获取单 bot 配置
-*/
-const getConfig = (appid) => cacheMap[appid];
-/**
-* 写入配置
-*/
-const writeConfig = (data) => {
-	fs.mkdirSync(dirConfig, { recursive: true });
-	fs.writeFileSync(`${dirConfig}/config.json`, JSON.stringify(data, null, 2));
-};
-/**
-* 用默认值补齐用户配置
-*/
-const formatConfig = (user) => {
-	const def = getDefaultConfig()[0];
-	return user.map((item) => ({
-		...def,
-		...item,
-		keyboard: {
-			...def.keyboard,
-			...item.keyboard
-		},
-		messageCache: {
-			...def.messageCache,
-			...item.messageCache
-		},
-		event: {
-			...def.event,
-			...item.event
-		}
-	}));
-};
-/**
-* 默认配置
-*/
-const getDefaultConfig = () => [{
-	name: "",
-	appId: "",
-	secret: "",
-	prodApi: "https://api.sgroup.qq.com",
-	sandboxApi: "https://sandbox.api.sgroup.qq.com",
-	tokenApi: "https://bots.qq.com/app/getAppAccessToken",
-	sandbox: false,
-	qqEnable: true,
-	guildEnable: true,
-	guildMode: 0,
-	regex: [{
-		reg: "^/",
-		rep: "#"
-	}],
-	keyboard: { enable: true },
-	messageCache: {
-		enable: false,
-		self: false
-	},
-	event: { type: 2 }
-}];
-/**
-* 监听配置文件，比较前后差异决定重建 / 销毁 bot
-*/
-setTimeout(() => {
-	watch(`${dirConfig}/config.json`, (old, now) => {
-		cache = formatConfig(now);
-		cache.forEach((v) => {
-			cacheMap[v.appId] = v;
-		});
-		const diff = common.diffArray(old, now);
-		diff.removed.forEach((v) => _destroyBot?.(v.appId));
-		if (diff.added.length > 0) {
-			const ids = new Set(diff.added.map((v) => v.appId));
-			cache.forEach((v) => {
-				if (!ids.has(v.appId)) return;
-				if (v.event.type === 0) return;
-				_createBot?.(v);
-			});
-		}
-		diff.common.forEach((curr) => {
-			const prev = old.find((c) => c.appId === curr.appId);
-			if (!prev) return;
-			if (JSON.stringify(prev) === JSON.stringify(curr)) return;
-			logger.info(`[QQ Official Bot][配置监听] 配置已变更: ${curr.appId}，重新初始化`);
-			_destroyBot?.(prev.appId);
-			if (curr.event.type !== 0) _createBot?.(curr);
-		});
-	});
-}, 2e3);
-
-//#endregion
-export { writeConfig as a, log as c, getDefaultConfig as i, basename as l, config as n, pkg as o, getConfig as r, pluginDirName as s, bindHandlers as t };

package/dist/utils-BPbnNAix.js

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