@alemonjs/qq-bot 2.1.38 → 2.1.39

package/README.md

@@ -13,6 +13,8 @@ AlemonJS 的 QQ 开放平台适配器，用于连接官方机器人接口，将
 
 三层限流、QQ 文本清洗、引用索引、群历史、LLM 上下文和 C2C 自动 typing 的配置与用法见 [消息处理与会话上下文](../alemonjs/docs/message-context.md)。
 
+Markdown 图片支持使用 `Media.image(source)` 自动准备 QQ 素材，也可通过媒体 Hook 提前上传、查询与删除，见[图片来源与平台资源](../alemonjs/docs/media.md)。
+
 ## 配置
 
 ### 基础配置

package/lib/config.d.ts

@@ -44,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

@@ -7,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 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/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,5 @@
 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";
@@ -973,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;
@@ -1003,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alemonjs/qq-bot",
-  "version": "2.1.38",
+  "version": "2.1.39",
   "description": "QQ官方平台",
   "author": "lemonade",
   "license": "MIT",
@@ -15,7 +15,9 @@
     "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: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",
@@ -99,5 +101,5 @@
     "type": "git",
     "url": "https://github.com/lemonade-lab/alemonjs.git"
   },
-  "gitHead": "e736f4e180a8694f8c9eb1796a23fdfadcc48f3e"
+  "gitHead": "114f342c08cb3ebbfee39b1c93fb30607d276083"
 }