@alemonjs/qq-bot 2.1.37 → 2.1.39

package/README.md

@@ -9,6 +9,12 @@ AlemonJS 的 QQ 开放平台适配器，用于连接官方机器人接口，将
 - 提供群管理、媒体上传和单聊流式消息能力；具体能力以平台权限为准。
 - 支持 WebSocket、Webhook 连接，以及 WebSocket 多机器人配置。
 
+官方 Node SDK 的对照结果、已落实修复和后续框架改进见 [SDK 对照与改进](./SDK_REVIEW.md)。
+
+三层限流、QQ 文本清洗、引用索引、群历史、LLM 上下文和 C2C 自动 typing 的配置与用法见 [消息处理与会话上下文](../alemonjs/docs/message-context.md)。
+
+Markdown 图片支持使用 `Media.image(source)` 自动准备 QQ 素材，也可通过媒体 Hook 提前上传、查询与删除，见[图片来源与平台资源](../alemonjs/docs/media.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;
   /**
@@ -41,7 +44,7 @@ declare const getQQBotBots: () => {
   bots: Map<string, Options$1>;
   defaultBot?: string;
 };
-declare const getIdentity: (UserId: string) => readonly [boolean, string];
-declare const getMaster: (UserId: string) => readonly [boolean, string];
+declare const getIdentity: (UserId: string) => readonly [any, any];
+declare const getMaster: (UserId: string) => readonly [any, any];
 //#endregion
 export { Options, getIdentity, getMaster, getQQBotBots, getQQBotConfig, platform, platformFullName };

package/lib/framework-actions.d.ts

@@ -3,66 +3,25 @@ import { OutgoingMessage } from "alemonjs";
 //#region src/framework-actions.d.ts
 declare const toQQMessage: (content: OutgoingMessage) => {
   msg_type: 0 | 2 | 3 | 7;
-  content: string;
+  content: any;
   markdown: {
-    content: string;
-    custom_template_id: string;
-    template_id: number;
-    params: {
-      key: string;
-      values: string[];
-    }[];
-    force_verify_image_resource: boolean;
+    content: any;
+    custom_template_id: any;
+    template_id: any;
+    params: any;
+    force_verify_image_resource: any;
   };
   media: {
-    file_info: string;
+    file_info: any;
   };
   ark: {
-    template_id: number;
-    kv: {
-      key: string;
-      value: string;
-      obj: {
-        obj_kv: {
-          key: string;
-          value: string;
-        }[];
-      }[];
-    }[];
+    template_id: any;
+    kv: any;
   };
   keyboard: {
-    id: string;
+    id: any;
     content: {
-      rows: {
-        buttons: {
-          id: string;
-          group_id: string;
-          render_data: {
-            label: string;
-            visited_label: string;
-            style: number;
-          };
-          action: {
-            type: number;
-            data: string;
-            permission: {
-              type: number;
-              specify_user_ids: string[];
-              specify_role_ids: string[];
-            };
-            enter: boolean;
-            reply: boolean;
-            unsupport_tips: string;
-            anchor: number;
-            click_limit: number;
-            modal: {
-              content: string;
-              confirm_text: string;
-              cancel_text: string;
-            };
-          };
-        }[];
-      }[];
+      rows: any;
     };
   };
 };
@@ -70,6 +29,6 @@ declare const toQQMessage: (content: OutgoingMessage) => {
 declare const handleFrameworkAction: (client: QQBotAPI, data: {
   action: string;
   payload: any;
-}, botId: string) => Promise<import("alemonjs/common").Result<any>[]>;
+}, botId: string) => Promise<ClientAPIMessageResult[]>;
 //#endregion
 export { handleFrameworkAction, toQQMessage };

package/lib/hook.d.ts

@@ -1,4 +1,3 @@
-import { QQBotAPI } from "./sdk/api.js";
 import { SUBSCRIBE_MESSAGE_STATUS_TYPE } from "./message/group/SUBSCRIBE_MESSAGE_STATUS.js";
 import { GROUP_MEMBER_ADD } from "./message/group/GROUP_MEMBER_ADD.js";
 import { GROUP_MEMBER_REMOVE } from "./message/group/GROUP_MEMBER_REMOVE.js";
@@ -77,7 +76,7 @@ declare const useValue: <T extends EventKeys>(event: Events[T]) => readonly [Eve
  * @param event
  * @returns
  */
-declare const useClient: <T extends EventKeys>(event: Events[T]) => readonly [QQBotAPI, EventValues[T]];
+declare const useClient: <T extends EventKeys>(event: Events[T]) => readonly [any, EventValues[T]];
 /**
  * 判断当前模式
  * @param event

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";
@@ -6,6 +7,6 @@ import { useClient, useMode, useValue } from "./hook.js";
 import { QQBotGroupEventMap } from "./sdk/message.group.js";
 import { QQBotPublicEventMap } from "./sdk/message.public.js";
 //#region src/index.d.ts
-declare const _default: () => any;
+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/materials.d.ts

@@ -0,0 +1,15 @@
+import { QQBotAPI } from "./sdk/api.js";
+import { MediaResource, MediaResourcePage, MediaSourceInput } from "alemonjs";
+//#region src/materials.d.ts
+/** Bot-scoped Markdown image materials. No access token is forwarded to COS. */
+declare class QQImageMaterials {
+  #private;
+  private readonly client;
+  private readonly botId;
+  constructor(client: QQBotAPI, botId: string);
+  upload(source: MediaSourceInput): Promise<MediaResource>;
+  list(cursor?: string): Promise<MediaResourcePage>;
+  delete(resource: MediaResource): Promise<{}>;
+}
+//#endregion
+export { QQImageMaterials };

package/lib/materials.js

@@ -0,0 +1,170 @@
+import axios from "axios";
+import { createHash } from "node:crypto";
+import { basename, extname } from "node:path";
+import { readFile, stat } from "node:fs/promises";
+import { fileTypeFromBuffer } from "file-type";
+
+//#region src/materials.ts
+const LIMIT = 10485760;
+const supported = {
+	"image/png": [".png"],
+	"image/jpeg": [".jpg", ".jpeg"],
+	"image/gif": [".gif"],
+	"image/webp": [".webp"]
+};
+/** Bot-scoped Markdown image materials. No access token is forwarded to COS. */
+var QQImageMaterials = class {
+	client;
+	botId;
+	#cache = /* @__PURE__ */ new Map();
+	#pending = /* @__PURE__ */ new Map();
+	constructor(client, botId) {
+		this.client = client;
+		this.botId = botId;
+	}
+	#resource(raw) {
+		if (typeof raw?.image_id !== "string" || typeof raw.url !== "string" || !raw.url.startsWith("qqbot-media://image/v1/")) throw new Error("QQ returned an invalid Markdown image resource");
+		return {
+			kind: "media-resource",
+			type: "image",
+			id: raw.image_id,
+			owner: {
+				platform: "qq-bot",
+				botId: this.botId
+			},
+			usage: "markdown",
+			reference: raw.url,
+			name: raw.file_name,
+			expiration: {
+				mode: "sliding",
+				...Number.isSafeInteger(raw.ttl) && raw.ttl > 0 && { windowSeconds: raw.ttl },
+				...Number.isFinite(raw.expires_at) && { expiresAt: raw.expires_at * 1e3 }
+			}
+		};
+	}
+	async upload(source) {
+		const values = [
+			source?.url,
+			source?.data,
+			source?.filePath
+		].filter((value) => value !== void 0);
+		if (values.length !== 1 || values.some((value) => typeof value !== "string" || !value)) throw new Error("Provide exactly one image source");
+		let bytes;
+		let name = source.name;
+		if (source.filePath) {
+			const info = await stat(source.filePath);
+			if (!info.isFile() || info.size > LIMIT) throw new Error("Markdown image must be a regular file no larger than 10 MiB");
+			bytes = await readFile(source.filePath);
+			name ??= basename(source.filePath);
+		} else if (source.url) {
+			const url = new URL(source.url);
+			if (!["http:", "https:"].includes(url.protocol)) throw new Error("Image URL must use HTTP or HTTPS");
+			const response = await axios.get(source.url, {
+				responseType: "arraybuffer",
+				timeout: 2e4,
+				maxContentLength: LIMIT,
+				headers: {
+					Authorization: null,
+					Cookie: null
+				}
+			});
+			bytes = Buffer.from(response.data);
+			name ??= basename(url.pathname) || void 0;
+		} else {
+			const data = source.data.replace(/^base64:\/\//, "");
+			if (data.length > Math.ceil(LIMIT / 3) * 4 || !/^[a-z\d+/]*={0,2}$/i.test(data) || data.length % 4 !== 0) throw new Error("Invalid or oversized base64 image");
+			bytes = Buffer.from(data, "base64");
+		}
+		if (!bytes.length || bytes.length > LIMIT) throw new Error("Markdown image must contain at most 10 MiB of image data");
+		const detected = await fileTypeFromBuffer(bytes);
+		if (!detected || !supported[detected.mime]) throw new Error("QQ Markdown materials support PNG, JPEG, GIF and WebP images");
+		if (!name || !source.name && !extname(name)) name = `${name || "image"}.${detected.ext}`;
+		if (!supported[detected.mime].includes(extname(name).toLowerCase())) throw new Error("Image filename extension must match its actual MIME type");
+		const key = `${createHash("sha256").update(bytes).digest("hex")}:${name}:${detected.mime}`;
+		const cached = this.#cache.get(key);
+		if (cached && cached.until > Date.now()) return structuredClone(cached.resource);
+		const pending = this.#pending.get(key);
+		if (pending !== void 0) return structuredClone(await pending);
+		if (this.#pending.size >= 100) throw new Error("Too many concurrent material uploads");
+		const task = this.#upload(bytes, name, detected.mime).then((resource) => {
+			if (this.#cache.size >= 100) this.#cache.delete(this.#cache.keys().next().value);
+			const lifetime = resource.expiration?.windowSeconds ?? 0;
+			if (lifetime > 0) this.#cache.set(key, {
+				resource,
+				until: Date.now() + lifetime * 1e3
+			});
+			return resource;
+		});
+		this.#pending.set(key, task);
+		try {
+			return structuredClone(await task);
+		} finally {
+			this.#pending.delete(key);
+		}
+	}
+	async #upload(bytes, name, mime) {
+		const prepared = await this.client.groupService({
+			method: "POST",
+			url: "/v2/media-images/prepare",
+			data: {
+				file_name: name,
+				file_size: bytes.length,
+				content_type: mime,
+				md5: createHash("md5").update(bytes).digest("hex"),
+				sha1: createHash("sha1").update(bytes).digest("hex")
+			}
+		});
+		const uploadUrl = new URL(prepared.presigned_url);
+		if (!["http:", "https:"].includes(uploadUrl.protocol) || !prepared.upload_id) throw new Error("QQ returned an invalid material upload task");
+		const uploaded = await axios.put(prepared.presigned_url, bytes, {
+			timeout: 2e4,
+			maxBodyLength: LIMIT,
+			maxRedirects: 0,
+			headers: {
+				"Content-Type": mime,
+				Authorization: null,
+				Cookie: null
+			}
+		}).catch(() => {
+			throw new Error("Markdown image binary upload failed");
+		});
+		const md5 = String(uploaded.headers.etag ?? "").replace(/^"|"$/g, "").toLowerCase();
+		if (md5 !== createHash("md5").update(bytes).digest("hex")) throw new Error("Markdown image upload returned an invalid ETag");
+		const completed = await this.client.groupService({
+			method: "POST",
+			url: "/v2/media-images/complete",
+			data: {
+				upload_id: prepared.upload_id,
+				md5
+			}
+		});
+		return {
+			...this.#resource(completed),
+			name
+		};
+	}
+	async list(cursor) {
+		const raw = await this.client.groupService({
+			method: "GET",
+			url: "/v2/media-images",
+			params: { cursor }
+		});
+		return {
+			Items: raw.images.map((item) => this.#resource(item)),
+			NextCursor: raw.next_cursor || void 0,
+			Total: raw.total
+		};
+	}
+	async delete(resource) {
+		if (resource.owner?.platform !== "qq-bot" || resource.owner.botId !== this.botId || resource.usage !== "markdown" || !resource.id) throw new Error("Image resource does not belong to this bot and usage");
+		await this.client.groupService({
+			method: "DELETE",
+			url: `/v2/media-images/${encodeURIComponent(resource.id)}/delete`
+		});
+		for (const [key, entry] of this.#cache) if (entry.resource.id === resource.id) this.#cache.delete(key);
+		return {};
+	}
+};
+
+//#endregion
+export { QQImageMaterials };

package/lib/register.js

@@ -1,4 +1,6 @@
 import { getIdentity, getMaster, getQQBotConfig, platform } from "./config.js";
+import { QQImageMaterials } from "./materials.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 +49,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
 	*
@@ -965,6 +974,11 @@ const register = (client, options) => {
 			}
 		}
 	};
+	const materials = new QQImageMaterials(client, botId);
+	const assertResource = (resource, usage, target) => {
+		if (resource.kind !== "media-resource" || resource.type !== "image" || resource.owner?.platform !== "qq-bot" || resource.owner.botId !== botId || resource.usage !== usage || !resource.id || !resource.reference) throw new Error("Image resource does not belong to this bot or usage");
+		if (resource.target && (!target || resource.target.scope !== target.scope || resource.target.targetId !== target.targetId)) throw new Error("Image resource belongs to another conversation");
+	};
 	const onactions = async (data, consume) => {
 		const event = data.payload.event ?? {};
 		const requestedBot = data.payload.params?.target?.BotId ?? data.payload.target?.BotId ?? data.payload.BotId ?? event.BotId;
@@ -995,6 +1009,88 @@ const register = (client, options) => {
 					return;
 				}
 			}
+			if (data.action.startsWith("media.resource.")) {
+				const params = data.payload.params ?? {};
+				const target = normalizeTarget(params.target ?? data.payload.target);
+				let result;
+				if (data.action === "media.resource.capabilities") result = { usages: {
+					message: {
+						upload: true,
+						list: false,
+						delete: false
+					},
+					markdown: {
+						upload: true,
+						list: true,
+						delete: true,
+						maxBytes: 10485760,
+						maxItems: 100
+					}
+				} };
+				else if (data.action === "media.resource.list") {
+					if (params.usage !== "markdown") throw new Error("QQ resource listing is only available for Markdown images");
+					result = await materials.list(params.cursor);
+				} else if (data.action === "media.resource.delete") {
+					assertResource(params.resource, "markdown");
+					result = await materials.delete(params.resource);
+				} else if (data.action === "media.resource.upload" || data.action === "media.resource.resolve") {
+					if (!["message", "markdown"].includes(params.usage)) throw new Error("Invalid image resource usage");
+					if (data.action === "media.resource.resolve" && params.usage === "markdown" && config.markdownToText) throw new Error("Markdown images cannot be embedded when markdownToText is enabled");
+					const image = params.image;
+					if (image?.kind === "media-resource") {
+						assertResource(image, params.usage, target);
+						result = image;
+					} else {
+						if (image && (image.kind !== "media-source" || image.type !== "image")) throw new Error("Expected an image source");
+						if (!image && params.type !== "image") throw new Error("Expected image upload type");
+						const source = image ? image.source : params.source;
+						if (params.usage === "markdown") result = await materials.upload(source);
+						else {
+							if (!target) throw new Error("A target is required for message image resources");
+							const uploaded = await uploadMedia(target, {
+								...source,
+								type: "image",
+								send: false
+							});
+							result = {
+								kind: "media-resource",
+								type: "image",
+								id: uploaded.fileId,
+								reference: uploaded.fileId,
+								owner: {
+									platform,
+									botId
+								},
+								usage: "message",
+								target: {
+									...target,
+									BotId: botId
+								},
+								name: source.name,
+								expiration: {
+									mode: "fixed",
+									expiresAt: "expiresAt" in uploaded ? uploaded.expiresAt : void 0
+								}
+							};
+						}
+					}
+				} else throw new Error("Unsupported media resource operation");
+				consume([createResult(ResultCode.Ok, data.action, result)]);
+				return;
+			}
+			if (data.action === "message.send" && data.payload.params?.format) {
+				const target = normalizeTarget(data.payload.target);
+				const validate = (items) => {
+					for (const item of items) {
+						if (item.media) {
+							if (item.type !== "Image") throw new Error("Structured media must be prepared through useMessage before sending");
+							assertResource(item.media, "message", target);
+						}
+						if ((item.type === "Markdown" || item.type === "MD.blockquote") && Array.isArray(item.value)) validate(item.value);
+					}
+				};
+				validate(data.payload.params.format);
+			}
 			const handled = await handleFrameworkAction(client, data, botId);
 			if (handled) {
 				consume(handled);

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/sends.js

@@ -177,13 +177,13 @@ const formatMention = (item, mode) => {
 	const value = item.value;
 	const isEmptyMention = value === "everyone" || value === "all" || value === "" || typeof value !== "string";
 	if (mode === "guild-public") {
-		if (isEmptyMention) return "@everyone";
-		if (item.options?.belong === "user") return `<@!${value}>`;
+		if (isEmptyMention) return "<qqbot-at-everyone />";
+		if (item.options?.belong === "user") return `<qqbot-at-user id="${value}" />`;
 		if (item.options?.belong === "channel") return `<#${value}>`;
 		return "";
 	}
 	if (isEmptyMention) return "";
-	if (item.options?.belong === "user") return `<@${value}>`;
+	if (item.options?.belong === "user") return `<qqbot-at-user id="${value}" />`;
 	return "";
 };
 /** 从消息数据中提取文本内容 */
@@ -321,6 +321,7 @@ const resolveFileData = async (item) => {
 */
 const resolveMediaUrl = async (media, uploadMedia) => {
 	for (const item of media) {
+		if (item.type === "Image" && item.media?.kind === "media-resource") return item.media.reference;
 		const fileData = await resolveFileData(item);
 		if (fileData) {
 			const fileInfo = await uploadMedia({

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.39",
   "description": "QQ官方平台",
   "author": "lemonade",
   "license": "MIT",
@@ -12,8 +12,12 @@
     "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",
+    "test:materials": "yarn build && node tests/materials.contract.mjs",
+    "test:mention": "yarn build && node tests/everyone.contract.mjs"
   },
   "dependencies": {
     "@noble/curves": "^1.7.0",
@@ -32,9 +36,6 @@
     "ws": "^8.13.0",
     "yaml": "^2.5.1"
   },
-  "peerDependencies": {
-    "alemonjs": "^2.1.0"
-  },
   "types": "lib",
   "exports": {
     ".": {
@@ -100,5 +101,5 @@
     "type": "git",
     "url": "https://github.com/lemonade-lab/alemonjs.git"
   },
-  "gitHead": "77aa1dad52568d709a460b1cdd32db6c36b6f0c2"
+  "gitHead": "114f342c08cb3ebbfee39b1c93fb30607d276083"
 }