@alemonjs/qq-bot 2.1.40 → 2.1.42

package/README.md

@@ -79,7 +79,7 @@ qq-bot:
 | `base_url_gateway`          | string           | —               | 网关域名代理                                                                              |
 | `base_url_app_access_token` | string           | —               | 获取 access_token 的域名代理                                                              |
 | `is_private`                | boolean          | `false`         | 私域机器人，影响默认事件订阅                                                              |
-| `sandbox`                   | boolean          | `false`         | 使用沙盒 API 环境                                                                         |
+| `sandbox`                   | boolean          | `false`         | 显式使用旧版沙盒域名；默认正式环境使用 api.bot.qq.com                                                                         |
 | `shard`                     | number[]         | `[0, 1]`        | WebSocket 分片                                                                            |
 | `intents`                   | string[]         | 自动组装        | 自定义事件订阅，覆盖默认值，见 [intents.ts](./src/sdk/intents.ts)；通常省略，不要填空数组 |
 | `autoInteractionAck`        | boolean          | `true`          | 自动确认按钮、快捷菜单事件；关闭后由应用调用 `useInteraction().ack()`                     |

package/lib/format.js

@@ -129,10 +129,10 @@ const mdFormatters = {
 		return `[🔗${value?.text}](${value?.url}) `;
 	},
 	"MD.image": (value, options) => `\n![text #${options?.width || 208}px #${options?.height || 320}px](${value})\n`,
-	"MD.mention": (value, options) => {
+	"MD.mention": (value, options, context) => {
 		const { belong } = options || {};
 		if (belong === "channel") return "";
-		if (value === "everyone") return "<qqbot-at-everyone />";
+		if (value === "everyone") return context === "c2c" ? "" : "<qqbot-at-everyone />";
 		if (belong === "user") return `<qqbot-at-user id="${value}" />`;
 		return `<qqbot-at-user id="${value}" />`;
 	},

package/lib/framework-actions.js

@@ -21,10 +21,15 @@ const nonEmptyIds = (ids, maximum, name) => {
 	if (!Array.isArray(ids) || ids.length < 1 || ids.length > maximum || ids.some((id) => typeof id !== "string" || !id)) throw new Error(`Expected 1 to ${maximum} non-empty ${name}`);
 	return ids;
 };
-const textLength = (value) => Buffer.byteLength(value, "utf8");
+const textLength = (value) => Array.from(value).reduce((length, character) => length + (character.codePointAt(0) <= 127 ? 1 : 2), 0);
+const panelScope = (scope) => {
+	if (scope === "direct") return "dm";
+	if (scope === "group" || scope === "c2c" || scope === "channel") return scope;
+	throw new Error("QQ panel scope must be group, c2c, channel or direct");
+};
 const menuItem = (item, child = false) => {
 	const maximum = child ? 14 : 10;
-	if (!item.name || textLength(item.name) > maximum) throw new Error(`Menu item name must be at most ${maximum} bytes`);
+	if (!item.name || textLength(item.name) > maximum) throw new Error(`Menu item name must be at most ${maximum} weighted characters`);
 	if (child && item.type === "menu") throw new Error("Menu sub-items cannot contain another menu");
 	if (item.type === "link" && !item.url.startsWith("https://")) throw new Error("Menu links must use https");
 	if (item.type === "menu" && (item.items.length < 1 || item.items.length > 5)) throw new Error("A menu must contain 1 to 5 sub-items");
@@ -41,14 +46,18 @@ const menuItem = (item, child = false) => {
 	};
 };
 const validatePanel = (panel) => {
-	if (panel.items.length > 20 || panel.remark && textLength(panel.remark) > 255) throw new Error("Panel supports at most 20 items and a 255-byte remark");
+	if (panel.items.length > 20 || panel.remark && Array.from(panel.remark).length > 255) throw new Error("Panel supports at most 20 items and a 255-character remark");
 	for (const item of panel.items) {
 		if (!item.name || textLength(item.name) > 14 || item.description && textLength(item.description) > 30) throw new Error("Panel item name/description exceeds its limit");
 		if (item.type === "link" && (!item.url || !item.url.startsWith("https://"))) throw new Error("Panel link items require an https URL");
 	}
 };
 const validatePanelAudience = (scope, audience, userIds, guildIds) => {
-	if (!["group", "c2c"].includes(scope)) throw new Error("QQ panel scope must be group or c2c");
+	if (audience !== void 0 && audience !== "all" && audience !== "specific") throw new Error("QQ panel audience must be all or specific");
+	if (scope === "channel" || scope === "dm") {
+		if (audience !== void 0 && audience !== "all" || userIds?.length || guildIds?.length) throw new Error("QQ channel/direct panels only support audience: all without audience IDs");
+		return;
+	}
 	if (Boolean(userIds?.length) && Boolean(guildIds?.length)) throw new Error("A panel audience cannot mix users and groups");
 	if (audience === "specific") nonEmptyIds(scope === "group" ? guildIds : userIds, 20, scope === "group" ? "group IDs" : "user IDs");
 	else if (userIds?.length || guildIds?.length) throw new Error("Panel audience IDs require audience: specific");
@@ -125,10 +134,15 @@ const panelBody = (panel) => ({
 	version: panel.version
 });
 const fromPanel = (r) => {
-	if (!["group", "c2c"].includes(r.scope)) throw new Error(`QQ panel scope ${r.scope || "unknown"} is outside the non-channel framework surface`);
+	if (![
+		"group",
+		"c2c",
+		"channel",
+		"dm"
+	].includes(r.scope)) throw new Error(`QQ panel scope ${r.scope || "unknown"} is not supported`);
 	return {
 		id: r.panel_id,
-		scope: r.scope,
+		scope: r.scope === "dm" ? "direct" : r.scope,
 		audience: r.target_type,
 		userIds: r.user_openids,
 		guildIds: r.group_openids,
@@ -293,19 +307,19 @@ const handleFrameworkAction = async (client, data, botId) => {
 			return client.menuPut({ menu: { items: p.menu.items.map(menuItem) } });
 		},
 		"panel.list": async () => {
-			if (!["group", "c2c"].includes(p.scope)) throw new Error("QQ panel scope must be group or c2c");
 			const r = await client.panelsList({
-				scope: p.scope,
+				scope: panelScope(p.scope),
 				...pagination(p.pagination)
 			});
 			return page(r.records.map(fromPanel), r);
 		},
 		"panel.create": async () => {
 			validatePanel(p.panel);
-			validatePanelAudience(p.scope, p.audience, p.userIds, p.guildIds);
+			const scope = panelScope(p.scope);
+			validatePanelAudience(scope, p.audience, p.userIds, p.guildIds);
 			return { id: (await client.panelsCreate({
-				scope: p.scope,
-				target_type: p.audience,
+				scope,
+				target_type: p.audience ?? "all",
 				user_openids: p.userIds,
 				group_openids: p.guildIds,
 				panel: panelBody(p.panel)

package/lib/index.d.ts

@@ -6,7 +6,8 @@ import { QQBotAPI } from "./sdk/api.js";
 import { useClient, useMode, useValue } from "./hook.js";
 import { QQBotGroupEventMap } from "./sdk/message.group.js";
 import { QQBotPublicEventMap } from "./sdk/message.public.js";
+import { QQMarkdown, QQMarkdownMathOptions, QQMarkdownTask } from "./markdown.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 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 };
+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, QQMarkdown, type QQMarkdownMathOptions, type QQMarkdownTask, 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

@@ -4,6 +4,7 @@ import { QQBotAPI } from "./sdk/api.js";
 import { start } from "./index.websoket.js";
 import { useClient, useMode, useValue } from "./hook.js";
 import { start as start$1 } from "./index.webhook.js";
+import { QQMarkdown } from "./markdown.js";
 import { definePlatform } from "alemonjs";
 
 //#region src/index.ts
@@ -15,4 +16,4 @@ const main = () => {
 var src_default = definePlatform({ main });
 
 //#endregion
-export { QQBotAPI as API, src_default as default, platform, sanitizeQQText, useClient, useMode, useValue };
+export { QQBotAPI as API, QQMarkdown, src_default as default, platform, sanitizeQQText, useClient, useMode, useValue };

package/lib/markdown.d.ts

@@ -0,0 +1,25 @@
+//#region src/markdown.d.ts
+/** QQ Markdown 专用扩展。仅生成字符串，不扩展 alemonjs 的通用节点或渲染协议。 */
+type QQMarkdownMathOptions = {
+  block?: boolean;
+};
+type QQMarkdownTask = {
+  text: string;
+  checked?: boolean;
+};
+declare const math: (latex: string, options?: QQMarkdownMathOptions) => string;
+/**
+ * 仅用于支持这些扩展的 QQ Markdown 消息；通过 addContent() 或原始 Markdown 发送。
+ * 不提供跨平台渲染或自动降级，调用方应根据发送平台选择内容。
+ */
+declare const QQMarkdown: {
+  math: typeof math;
+  taskList(...items: QQMarkdownTask[]): string;
+  underline(text: string): string;
+  color(text: string, color: string): string;
+  ruby(text: string, annotation: string): string;
+  boxed(text: string): string;
+  cancel(text: string): string;
+};
+//#endregion
+export { QQMarkdown, QQMarkdownMathOptions, QQMarkdownTask };

package/lib/markdown.js

@@ -0,0 +1,47 @@
+//#region src/markdown.ts
+const latexText = (text) => {
+	const escapes = {
+		"\\": "\\textbackslash{}",
+		"{": "\\{",
+		"}": "\\}",
+		$: "\\$",
+		"&": "\\&",
+		"#": "\\#",
+		"%": "\\%",
+		_: "\\_",
+		"^": "\\textasciicircum{}",
+		"~": "\\textasciitilde{}"
+	};
+	return `\\text{${text.replace(/[\\{}$&#%_^~]/g, (character) => escapes[character]).replace(/\r\n?|\n/g, " ")}}`;
+};
+const math = (latex, options) => options?.block ? `\n\n$$\n${latex}\n$$\n\n` : `$${latex}$`;
+/**
+* 仅用于支持这些扩展的 QQ Markdown 消息；通过 addContent() 或原始 Markdown 发送。
+* 不提供跨平台渲染或自动降级，调用方应根据发送平台选择内容。
+*/
+const QQMarkdown = {
+	math,
+	taskList(...items) {
+		if (items.length === 0) return "";
+		return "\n\n" + items.map((item) => `- [${item.checked ? "x" : " "}] ${item.text.replace(/\r\n?|\n/g, " ")}`).join("\n") + "\n\n";
+	},
+	underline(text) {
+		return math(`\\underline{${latexText(text)}}`);
+	},
+	color(text, color) {
+		if (!/^(?:[a-zA-Z]+|#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3})?)$/.test(color)) throw new TypeError("QQ Markdown color must be a color name or #RGB / #RRGGBB");
+		return math(`\\color{${color}}{${latexText(text)}}`);
+	},
+	ruby(text, annotation) {
+		return math(`\\overset{${latexText(annotation)}}{${latexText(text)}}`);
+	},
+	boxed(text) {
+		return math(`\\boxed{${latexText(text)}}`);
+	},
+	cancel(text) {
+		return math(`\\cancel{${latexText(text)}}`);
+	}
+};
+
+//#endregion
+export { QQMarkdown };

package/lib/sdk/non-channel-types.d.ts

@@ -34,8 +34,8 @@ type QQBotPanel = {
   remark?: string;
   version?: number;
 };
-/** 本次仅开放非频道场景。 */
-type QQBotPanelScope = 'c2c' | 'group';
+/** QQ 原生面板场景；框架 direct 对应 dm。 */
+type QQBotPanelScope = 'c2c' | 'group' | 'channel' | 'dm';
 type QQBotPanelCreate = {
   scope: QQBotPanelScope;
   target_type?: 'all' | 'specific';

package/lib/sends.js

@@ -182,7 +182,7 @@ const formatMention = (item, mode) => {
 		if (item.options?.belong === "channel") return `<#${value}>`;
 		return "";
 	}
-	if (isEmptyMention) return "";
+	if (isEmptyMention) return mode === "group" ? "<qqbot-at-everyone />" : "";
 	if (item.options?.belong === "user") return `<qqbot-at-user id="${value}" />`;
 	return "";
 };
@@ -352,7 +352,7 @@ const sendOpenApiMessage = async (content, val, baseParams, uploadMedia, sendMes
 		const fileInfo = await resolveMediaUrl(media, uploadMedia);
 		if (!fileInfo) return [createResult(ResultCode.Fail, "媒体上传失败", null)];
 		const res = await sendMessage({
-			content: stripMediaPlaceholders(formatQQContent(val, (item) => extractContent([item], "group"), true, config.hideUnsupported)),
+			content: stripMediaPlaceholders(formatQQContent(val, (item) => extractContent([item], context === "group" ? "group-media" : context), true, config.hideUnsupported)),
 			media: { file_info: fileInfo },
 			msg_type: 7,
 			...baseParams
@@ -368,7 +368,7 @@ const sendOpenApiMessage = async (content, val, baseParams, uploadMedia, sendMes
 		return [];
 	}
 	if (mdToText) {
-		const textContent = formatQQContent(val, (item) => extractContent([item], "group"), true, config.hideUnsupported);
+		const textContent = formatQQContent(val, (item) => extractContent([item], context), true, config.hideUnsupported);
 		if (textContent) {
 			const res = await sendMessage({
 				content: textContent,
@@ -385,7 +385,7 @@ const sendOpenApiMessage = async (content, val, baseParams, uploadMedia, sendMes
 	}
 	const mdParams = buildMdAndButtonsParams(val, context);
 	if (mdParams) {
-		if (mdParams.markdown?.content) mdParams.markdown.content = formatQQContent(val, (item) => extractContent([item], "group"), false, void 0, context);
+		if (mdParams.markdown?.content) mdParams.markdown.content = formatQQContent(val, (item) => extractContent([item], context), false, void 0, context);
 		if (mdParams.markdown && options?.forceVerifyImageResource !== void 0) mdParams.markdown.force_verify_image_resource = options.forceVerifyImageResource;
 		const res = await sendMessage({
 			msg_type: 2,
@@ -522,7 +522,7 @@ const GROUP_AT_MESSAGE_CREATE = async (client, event, val, options) => {
 */
 const C2C_MESSAGE_CREATE = async (client, event, val, options) => {
 	const baseParams = buildBaseParams(event._tag, event.MessageId, "INTERACTION_CREATE_C2C");
-	const content = extractContent(val, "group");
+	const content = extractContent(val, "c2c");
 	try {
 		return await sendOpenApiMessage(content, val, baseParams, (data) => client.postRichMediaByUser(event.UserId, data), (data) => client.usersOpenMessages(event.UserId, data), "client.usersOpenMessages", "c2c", options);
 	} catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alemonjs/qq-bot",
-  "version": "2.1.40",
+  "version": "2.1.42",
   "description": "QQ官方平台",
   "author": "lemonade",
   "license": "MIT",
@@ -12,13 +12,15 @@
     "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/markdown-buttons.contract.mjs && 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",
+    "test:non-channel": "yarn build && node tests/markdown-buttons.contract.mjs && node tests/markdown-extension.contract.mjs && node tests/non-channel.contract.mjs && node tests/framework.contract.mjs && node tests/changelog.contract.mjs && node tests/everyone.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",
-    "test:buttons": "yarn build && node tests/markdown-buttons.contract.mjs"
+    "test:buttons": "yarn build && node tests/markdown-buttons.contract.mjs",
+    "test:markdown-extension": "yarn build && node tests/markdown-extension.contract.mjs && node ../../node_modules/typescript/bin/tsc --noEmit --strict --skipLibCheck --module ESNext --moduleResolution Bundler --target ES2022 tests/markdown-extension.types.ts",
+    "test:changelog": "yarn --cwd ../alemonjs build && yarn build && node tests/changelog.contract.mjs && node tests/everyone.contract.mjs"
   },
   "dependencies": {
     "@noble/curves": "^1.7.0",
@@ -45,7 +47,12 @@
       "require": "./lib/index.js"
     },
     "./package": "./package.json",
-    "./desktop": "./lib/desktop.js"
+    "./desktop": "./lib/desktop.js",
+    "./markdown": {
+      "types": "./lib/markdown.d.ts",
+      "import": "./lib/markdown.js",
+      "require": "./lib/markdown.js"
+    }
   },
   "alemonjs": {
     "config": [