@alemonjs/qq-bot 2.1.37 → 2.1.38

package/README.md

@@ -9,6 +9,10 @@ AlemonJS 的 QQ 开放平台适配器，用于连接官方机器人接口，将
 - 提供群管理、媒体上传和单聊流式消息能力；具体能力以平台权限为准。
 - 支持 WebSocket、Webhook 连接，以及 WebSocket 多机器人配置。
 
+官方 Node SDK 的对照结果、已落实修复和后续框架改进见 [SDK 对照与改进](./SDK_REVIEW.md)。
+
+三层限流、QQ 文本清洗、引用索引、群历史、LLM 上下文和 C2C 自动 typing 的配置与用法见 [消息处理与会话上下文](../alemonjs/docs/message-context.md)。
+
 ## 配置
 
 ### 基础配置

package/lib/config.d.ts

@@ -1,8 +1,11 @@
+import { QQTextSanitizerOptions } from "./text-sanitizer.js";
 import { Options as Options$1 } from "./sdk/typing.js";
 //#region src/config.d.ts
 declare const platform = "qq-bot";
 declare const platformFullName = "@alemonjs/qq-bot";
 type Options = {
+  /** Opt-in QQ markup normalization; raw content remains available. */
+  textSanitizer?: QQTextSanitizerOptions;
   /** 按钮/快捷菜单自动 ACK。设为 false 后由应用 useInteraction().ack() 回应。 */
   autoInteractionAck?: boolean;
   /**

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+import { QQTextSanitizerOptions, sanitizeQQText } from "./text-sanitizer.js";
 import { ApiRequestData, ButtonType, FileType, GlobalMuteRule, GroupAction, JoinApprovalStrategy, JoinRequest, KeyboardType, MarkdownType, MemberMuteState, MessageType, Options, SetMemberMuteState, StreamMessageData, StreamMessageResult, UploadConfig, UploadPart, UploadPartFinishData, UploadPrepareData, UploadPrepareResult, VerifyInfo } from "./sdk/typing.js";
 import { platform } from "./config.js";
 import { QQBotArkData, QQBotAttachment, QQBotBlacklistUser, QQBotGroupMember, QQBotInteractionResolved, QQBotMenu, QQBotMenuItem, QQBotMessageContent, QQBotMessageElement, QQBotMessageResult, QQBotMessageUser, QQBotPage, QQBotPanel, QQBotPanelCreate, QQBotPanelRecord, QQBotPanelScope } from "./sdk/non-channel-types.js";
@@ -8,4 +9,4 @@ import { QQBotPublicEventMap } from "./sdk/message.public.js";
 //#region src/index.d.ts
 declare const _default: () => any;
 //#endregion
-export { QQBotAPI as API, type ApiRequestData, type ButtonType, type FileType, type GlobalMuteRule, type GroupAction, type JoinApprovalStrategy, type JoinRequest, type KeyboardType, type MarkdownType, type MemberMuteState, type MessageType, type Options, type QQBotArkData, type QQBotAttachment, type QQBotBlacklistUser, type QQBotGroupEventMap, type QQBotGroupMember, type QQBotInteractionResolved, type QQBotMenu, type QQBotMenuItem, type QQBotMessageContent, type QQBotMessageElement, type QQBotMessageResult, type QQBotMessageUser, type QQBotPage, type QQBotPanel, type QQBotPanelCreate, type QQBotPanelRecord, type QQBotPanelScope, type QQBotPublicEventMap, type SetMemberMuteState, type StreamMessageData, type StreamMessageResult, type UploadConfig, type UploadPart, type UploadPartFinishData, type UploadPrepareData, type UploadPrepareResult, type VerifyInfo, _default as default, platform, useClient, useMode, useValue };
+export { QQBotAPI as API, type ApiRequestData, type ButtonType, type FileType, type GlobalMuteRule, type GroupAction, type JoinApprovalStrategy, type JoinRequest, type KeyboardType, type MarkdownType, type MemberMuteState, type MessageType, type Options, type QQBotArkData, type QQBotAttachment, type QQBotBlacklistUser, type QQBotGroupEventMap, type QQBotGroupMember, type QQBotInteractionResolved, type QQBotMenu, type QQBotMenuItem, type QQBotMessageContent, type QQBotMessageElement, type QQBotMessageResult, type QQBotMessageUser, type QQBotPage, type QQBotPanel, type QQBotPanelCreate, type QQBotPanelRecord, type QQBotPanelScope, type QQBotPublicEventMap, type QQTextSanitizerOptions, type SetMemberMuteState, type StreamMessageData, type StreamMessageResult, type UploadConfig, type UploadPart, type UploadPartFinishData, type UploadPrepareData, type UploadPrepareResult, type VerifyInfo, _default as default, platform, sanitizeQQText, useClient, useMode, useValue };

package/lib/index.js

@@ -1,4 +1,5 @@
 import { getQQBotConfig, platform } from "./config.js";
+import { sanitizeQQText } from "./text-sanitizer.js";
 import { QQBotAPI } from "./sdk/api.js";
 import { start } from "./index.websoket.js";
 import { useClient, useMode, useValue } from "./hook.js";
@@ -14,4 +15,4 @@ const main = () => {
 var src_default = definePlatform({ main });
 
 //#endregion
-export { QQBotAPI as API, src_default as default, platform, useClient, useMode, useValue };
+export { QQBotAPI as API, src_default as default, platform, sanitizeQQText, useClient, useMode, useValue };

package/lib/register.js

@@ -1,4 +1,5 @@
 import { getIdentity, getMaster, getQQBotConfig, platform } from "./config.js";
+import { sanitizeQQText } from "./text-sanitizer.js";
 import { AT_MESSAGE_CREATE, C2C_MESSAGE_CREATE, DIRECT_MESSAGE_CREATE, GROUP_AT_MESSAGE_CREATE, MESSAGE_CREATE } from "./sends.js";
 import { normalizeFrameworkEvent, normalizeMessageUser } from "./framework-events.js";
 import { handleFrameworkAction } from "./framework-actions.js";
@@ -47,7 +48,14 @@ const register = (client, options) => {
 	const botId = String(options?.botId ?? config?.app_id ?? "");
 	const url = `ws://127.0.0.1:${process.env?.port || config?.port || 17117}`;
 	const cbp = options?.cbp ?? cbpPlatform(url);
-	const emit = (event, acknowledged = false) => cbp.send(normalizeFrameworkEvent(event, acknowledged));
+	const emit = (event, acknowledged = false) => {
+		const normalized = normalizeFrameworkEvent(event, acknowledged);
+		if (config.textSanitizer && (normalized.name === "message.create" || normalized.name === "private.message.create") && typeof normalized.value?.content === "string") {
+			normalized.RawMessageText = normalized.value.content;
+			normalized.MessageText = sanitizeQQText(normalized.value.content, botId, config.textSanitizer);
+		}
+		cbp.send(normalized);
+	};
 	/**
 	* group
 	*

package/lib/sdk/client.webhook.js

@@ -68,7 +68,13 @@ var QQBotClient = class extends QQBotAPI {
 			if (!ws) {
 				this.#setTimeoutBotConfig();
 				this.#app = new Koa();
-				this.#app.use(bodyParser());
+				this.#app.use(bodyParser({
+					enableTypes: ["json"],
+					onerror: (_error, ctx) => {
+						ctx.status = 400;
+						ctx.body = { msg: "invalid json" };
+					}
+				}));
 				const router = new Router();
 				const port = this.config.get("port");
 				const secret = this.config.get("secret");
@@ -78,31 +84,39 @@ var QQBotClient = class extends QQBotAPI {
 					port: port ? Number(port) : 17157
 				};
 				const ntqqWebhook = new WebhookAPI({ secret: cfg.secret });
-				this.#app.use(async (ctx, next) => {
-					let rawData = "";
-					ctx.req.on("data", (chunk) => rawData += chunk);
-					ctx.req.on("end", () => ctx.request.rawBody = rawData);
-					await next();
-				});
 				router.post(route, (ctx) => {
-					const sign = ctx.req.headers["x-signature-ed25519"];
-					const timestamp = ctx.req.headers["x-signature-timestamp"];
-					const rawBody = ctx.request.rawBody;
-					if (!ntqqWebhook.validSign(timestamp, rawBody, String(sign))) {
+					const request = ctx.request;
+					const body = request.body;
+					if (!body || typeof body !== "object" || Array.isArray(body) || !Number.isInteger(body.op)) {
+						ctx.status = 400;
+						ctx.body = { msg: "invalid payload" };
+						return;
+					}
+					if (body.op !== 13 && !ntqqWebhook.validSign(ctx.get("x-signature-timestamp"), request.rawBody, ctx.get("x-signature-ed25519"))) {
 						ctx.status = 400;
 						ctx.body = { msg: "invalid signature" };
 						return;
 					}
-					const body = normalizeGatewayMessage(ctx.request.body);
-					if (+body.op === 13) {
+					if (body.op === 13) {
+						if (typeof body.d?.plain_token !== "string" || !body.d.plain_token || typeof body.d?.event_ts !== "string" || !body.d.event_ts) {
+							ctx.status = 400;
+							ctx.body = { msg: "invalid validation" };
+							return;
+						}
 						ctx.status = 200;
 						ctx.body = {
 							plain_token: body.d.plain_token,
 							signature: ntqqWebhook.getSign(body.d.event_ts, body.d.plain_token)
 						};
-					} else if (+body.op === 0) {
+					} else if (body.op === 0) {
+						if (typeof body.t !== "string" || !body.t || !body.d || typeof body.d !== "object" || Array.isArray(body.d)) {
+							ctx.status = 400;
+							ctx.body = { msg: "invalid dispatch" };
+							return;
+						}
+						normalizeGatewayMessage(body);
 						ctx.status = 204;
-						for (const event of this.#events[body.t] || []) event(body.d);
+						this.#dispatch(body);
 						const accessToken = this.config.get("access_token");
 						for (const client of this.#client) try {
 							if (accessToken) body["access_token"] = accessToken;
@@ -131,7 +145,7 @@ var QQBotClient = class extends QQBotAPI {
 					ws.on("message", (message) => {
 						try {
 							const body = normalizeGatewayMessage(JSON.parse(message.toString()));
-							for (const event of this.#events[body.t] || []) event(body.d);
+							this.#dispatch(body);
 						} catch (e) {
 							this.#error(e);
 						}
@@ -154,7 +168,7 @@ var QQBotClient = class extends QQBotAPI {
 							const body = normalizeGatewayMessage(JSON.parse(data.toString()));
 							const accessToken = body["access_token"];
 							if (accessToken) this.config.set("access_token", accessToken);
-							for (const event of this.#events[body.t] || []) event(body.d);
+							this.#dispatch(body);
 						} catch (e) {
 							this.#error(e);
 						}
@@ -177,12 +191,17 @@ var QQBotClient = class extends QQBotAPI {
 			this.#error(e);
 		}
 	}
+	/** Acknowledge receipt without waiting for application work. Each listener
+	* owns its failure path so a rejection cannot escape the transport. */
+	#dispatch(body) {
+		for (const event of this.#events[body.t] || []) Promise.resolve().then(() => event(body.d)).catch((error) => this.#error(error));
+	}
 	/**
 	*
 	* @param error
 	*/
 	#error(error) {
-		if (this.#events["ERROR"]) for (const event of this.#events["ERROR"] || []) event(error);
+		for (const event of this.#events["ERROR"] || []) Promise.resolve().then(() => event(error)).catch((failure) => console.error("[qq-bot] ERROR listener failed", failure instanceof Error ? failure.name : "UnknownError"));
 	}
 };
 

package/lib/sdk/instance.d.ts

@@ -1,11 +1,6 @@
 import { AxiosInstance, AxiosRequestConfig } from "axios";
 //#region src/sdk/instance.d.ts
-/**
- * 基础请求
- * @param service
- * @param options
- * @returns
- */
+/** Preserve native platform failure payloads for existing SDK and Action callers. */
 declare const createAxiosInstance: (service: AxiosInstance, options: AxiosRequestConfig) => Promise<any>;
 //#endregion
 export { createAxiosInstance };

package/lib/sdk/instance.js

@@ -1,75 +1,29 @@
 import { logger } from "alemonjs";
 
 //#region src/sdk/instance.ts
-const filterHeaders = (headers = {}) => {
-	if (!headers) return headers;
-	const filtered = {};
-	const sensitiveKeys = [
-		/^authorization$/i,
-		/^cookie$/i,
-		/^set-cookie$/i,
-		/token/i,
-		/key/i,
-		/jwt/i,
-		/^session[-_]id$/i,
-		/^uid$/i,
-		/^user[-_]id$/i
-	];
-	for (const key in headers) {
-		if (/^_/.test(key)) continue;
-		if (typeof key === "symbol") continue;
-		if (typeof headers[key] === "function") continue;
-		if (sensitiveKeys.some((re) => re.test(key))) filtered[key] = "******";
-		else filtered[key] = headers[key];
-	}
-	return filtered;
-};
-const filterConfig = (config = {}) => {
-	if (!config) return config;
-	const filtered = {};
-	for (const key in config) {
-		if (/^_/.test(key)) continue;
-		if (typeof key === "symbol") continue;
-		if (typeof config[key] === "function") continue;
-		filtered[key] = config[key];
-	}
-	return filtered;
-};
-const filterRequest = (request = {}) => {
-	if (!request) return request;
-	const filtered = {};
-	for (const key in request) {
-		if (/^_/.test(key)) continue;
-		if (typeof key === "symbol") continue;
-		if (typeof request[key] === "function") continue;
-		filtered[key] = request[key];
-	}
-	return filtered;
-};
+/** Log an allowlist of diagnostics. Axios config/request objects may contain
+* credentials, signed URLs, message bodies, buffers and circular references. */
 const loggerError = (err) => {
-	logger.error("[axios] error", {
-		config: {
-			headers: filterHeaders(err?.config?.headers),
-			params: err?.config?.params,
-			data: err?.config?.data
-		},
-		response: {
-			status: err?.response?.status,
-			statusText: err?.response?.statusText,
-			headers: filterHeaders(err?.response?.headers),
-			config: filterConfig(err?.response?.config),
-			request: filterRequest(err?.response?.request),
-			data: err?.response?.data
-		},
-		message: err?.message
+	const config = err?.config;
+	let path;
+	try {
+		path = new URL(config?.url ?? "", config?.baseURL || "http://localhost").pathname;
+	} catch {
+		path = void 0;
+	}
+	const headers = err?.response?.headers;
+	const data = err?.response?.data;
+	const scalarCode = (value) => typeof value === "number" || typeof value === "string" && /^[\w-]{1,64}$/.test(value) ? value : void 0;
+	logger.error("[qq-bot] HTTP request failed", {
+		method: typeof config?.method === "string" ? config.method.toUpperCase() : void 0,
+		path,
+		status: err?.response?.status,
+		code: scalarCode(data?.code ?? data?.err_code),
+		transportCode: scalarCode(err?.code),
+		traceId: headers?.["x-tps-trace-id"] ?? headers?.["x-trace-id"]
 	});
 };
-/**
-* 基础请求
-* @param service
-* @param options
-* @returns
-*/
+/** Preserve native platform failure payloads for existing SDK and Action callers. */
 const createAxiosInstance = async (service, options) => {
 	try {
 		return (await service(options))?.data ?? {};

package/lib/sdk/webhook.secret.d.ts

@@ -13,7 +13,7 @@ declare class WebhookAPI {
    * @param sign
    * @returns
    */
-  validSign(ts: any, body: any, sign: any): boolean;
+  validSign(ts: unknown, body: unknown, sign: unknown): boolean;
   /**
    *   生成签名
    * @param eventTs

package/lib/sdk/webhook.secret.js

@@ -14,11 +14,16 @@ var WebhookAPI = class {
 	* @returns
 	*/
 	validSign(ts, body, sign) {
-		const { publicKey } = this.getKey();
-		const sig = Buffer.isBuffer(sign) ? sign : Buffer.from(sign, "hex");
-		const httpBody = Buffer.from(body);
-		const msg = Buffer.from(ts + httpBody);
-		return ed25519.verify(sig, msg, publicKey);
+		if (typeof ts !== "string" || !ts || typeof body !== "string" && !Buffer.isBuffer(body)) return false;
+		if (!Buffer.isBuffer(sign) && (typeof sign !== "string" || !/^[a-f\d]{128}$/i.test(sign))) return false;
+		try {
+			const { publicKey } = this.getKey();
+			const sig = Buffer.isBuffer(sign) ? sign : Buffer.from(sign, "hex");
+			const msg = Buffer.concat([Buffer.from(ts), Buffer.isBuffer(body) ? body : Buffer.from(body)]);
+			return ed25519.verify(sig, msg, publicKey);
+		} catch {
+			return false;
+		}
 	}
 	/**
 	*   生成签名

package/lib/text-sanitizer.d.ts

@@ -0,0 +1,13 @@
+//#region src/text-sanitizer.d.ts
+type QQTextSanitizerOptions = {
+  /** Strip only this bot by default. Other users' mentions retain meaning. */
+  botMention?: 'remove' | 'preserve';
+  otherMentions?: 'remove' | 'preserve';
+  faces?: 'preserve' | 'remove' | 'label';
+  /** Disabled by default to preserve paragraphs and code indentation. */
+  collapseWhitespace?: boolean;
+};
+/** Converts QQ protocol markup, never HTML. Raw event content is preserved. */
+declare const sanitizeQQText: (text: string, botId: string, options?: QQTextSanitizerOptions) => string;
+//#endregion
+export { QQTextSanitizerOptions, sanitizeQQText };

package/lib/text-sanitizer.js

@@ -0,0 +1,26 @@
+//#region src/text-sanitizer.ts
+/** Converts QQ protocol markup, never HTML. Raw event content is preserved. */
+const sanitizeQQText = (text, botId, options = {}) => {
+	let result = text.replace(/<@!?([^>\s]+)>/g, (marker, id) => {
+		return (id === botId ? options.botMention !== "preserve" : options.otherMentions === "remove") ? "" : marker;
+	});
+	const faces = options.faces ?? "preserve";
+	if (faces !== "preserve") {
+		result = result.replace(/\[<face,id=(\d+)\/?>\]/g, (_marker, id) => faces === "label" ? `[表情:${id}]` : "");
+		result = result.replace(/<faceType=\d+,faceId="([^"]*)",ext="([^"]*)">/g, (_marker, id, ext) => {
+			if (faces === "remove") return "";
+			try {
+				if (ext.length <= 1e4) {
+					const data = JSON.parse(Buffer.from(ext, "base64").toString("utf8"));
+					if (typeof data?.text === "string" && data.text) return `[表情:${data.text.slice(0, 100)}]`;
+				}
+			} catch {}
+			return `[表情:${id}]`;
+		});
+	}
+	if (options.collapseWhitespace) result = result.replace(/\s+/g, " ");
+	return result.trim();
+};
+
+//#endregion
+export { sanitizeQQText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alemonjs/qq-bot",
-  "version": "2.1.37",
+  "version": "2.1.38",
   "description": "QQ官方平台",
   "author": "lemonade",
   "license": "MIT",
@@ -12,8 +12,10 @@
     "test:send": "yarn build && node tests/use-send.notice.mjs",
     "test:channel": "yarn --cwd ../alemonjs build && yarn build && node tests/channel.contract.mjs",
     "test:qr": "yarn build && node tests/qr-auth.mjs",
-    "test:non-channel": "yarn build && node tests/non-channel.contract.mjs && node tests/framework.contract.mjs && node tests/non-channel.transport.mjs && node tests/media-upload.contract.mjs && node tests/routing.contract.mjs && node tests/lifecycle.contract.mjs && tsc -p tests/tsconfig.non-channel.json",
-    "docs:snapshot": "python3 scripts/snapshot-official.py"
+    "test:non-channel": "yarn build && node tests/non-channel.contract.mjs && node tests/framework.contract.mjs && node tests/non-channel.transport.mjs && node tests/media-upload.contract.mjs && node tests/routing.contract.mjs && node tests/lifecycle.contract.mjs && node tests/http-diagnostics.contract.mjs && node tests/webhook-ingress.contract.mjs && node tests/text-sanitizer.contract.mjs && tsc -p tests/tsconfig.non-channel.json",
+    "docs:snapshot": "python3 scripts/snapshot-official.py",
+    "test:http": "yarn build && node tests/http-diagnostics.contract.mjs && node tests/webhook-ingress.contract.mjs",
+    "test:text": "yarn build && node tests/text-sanitizer.contract.mjs"
   },
   "dependencies": {
     "@noble/curves": "^1.7.0",
@@ -32,9 +34,6 @@
     "ws": "^8.13.0",
     "yaml": "^2.5.1"
   },
-  "peerDependencies": {
-    "alemonjs": "^2.1.0"
-  },
   "types": "lib",
   "exports": {
     ".": {
@@ -100,5 +99,5 @@
     "type": "git",
     "url": "https://github.com/lemonade-lab/alemonjs.git"
   },
-  "gitHead": "77aa1dad52568d709a460b1cdd32db6c36b6f0c2"
+  "gitHead": "e736f4e180a8694f8c9eb1796a23fdfadcc48f3e"
 }