@nextclaw/channel-extension-qq 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/main.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/main.js

@@ -0,0 +1,10 @@
+import { QQChannel } from "./services/qq-channel.service.js";
+import { startBusChannelExtension, warnNcpEventError } from "@nextclaw/extension-sdk";
+//#region src/main.ts
+await startBusChannelExtension({
+	channelId: "qq",
+	createChannel: ({ config, bus }) => new QQChannel(config, bus),
+	onChannelStartError: warnNcpEventError("qq")
+});
+//#endregion
+export {};

package/dist/services/qq-channel.service.js

@@ -0,0 +1,352 @@
+import { Bot, ReceiverMode, SessionEvents } from "qq-official-bot";
+//#region src/services/qq-channel.service.ts
+var QQChannel = class {
+	name = "qq";
+	running = false;
+	bot = null;
+	processedIds = [];
+	processedSet = /* @__PURE__ */ new Set();
+	senderNameCache = /* @__PURE__ */ new Map();
+	reconnectTimer = null;
+	connectTask = null;
+	reconnectAttempt = 0;
+	reconnectBaseMs = 1e3;
+	reconnectMaxMs = 6e4;
+	connectTimeoutMs = 9e4;
+	constructor(config, bus) {
+		this.config = config;
+		this.bus = bus;
+	}
+	start = async () => {
+		if (!this.config.appId || !this.config.secret) {
+			this.running = false;
+			throw new Error("QQ appId/appSecret not configured");
+		}
+		this.running = true;
+		this.reconnectAttempt = 0;
+		this.clearReconnectTimer();
+		this.tryConnect("startup");
+		await this.connectTask;
+	};
+	stop = async () => {
+		this.running = false;
+		this.clearReconnectTimer();
+		this.reconnectAttempt = 0;
+		await this.teardownBot();
+		if (this.connectTask) await this.connectTask;
+	};
+	send = async (msg) => {
+		if (!this.bot) return;
+		const qqMeta = msg.metadata?.qq ?? {};
+		const messageType = qqMeta.messageType ?? "private";
+		const metadataMessageId = msg.metadata?.message_id ?? null;
+		const sourceId = msg.replyTo ?? metadataMessageId ?? void 0;
+		const source = sourceId ? { id: sourceId } : void 0;
+		const rawContent = msg.content ?? "";
+		const payload = rawContent;
+		try {
+			await this.sendByMessageType({
+				messageType,
+				qqMeta,
+				msg,
+				payload,
+				source
+			});
+		} catch (error) {
+			if (!this.isDisallowedUrlParamError(error)) throw error;
+			const safeText = this.toQqSafeText(rawContent, error);
+			await this.sendByMessageType({
+				messageType,
+				qqMeta,
+				msg,
+				payload: safeText,
+				source
+			});
+		}
+	};
+	sendByMessageType = async (params) => {
+		const { messageType, qqMeta, msg, payload, source } = params;
+		if (messageType === "group") {
+			const groupId = qqMeta.groupId ?? msg.chatId;
+			await this.sendWithTokenRetry(() => this.bot?.sendGroupMessage(groupId, payload, source));
+			return;
+		}
+		const userId = qqMeta.userId ?? msg.chatId;
+		await this.sendWithTokenRetry(() => this.bot?.sendPrivateMessage(userId, payload, source));
+	};
+	handleIncoming = async (event) => {
+		const identity = this.resolveIncomingIdentity(event);
+		if (!identity) return;
+		const content = event.raw_message?.trim() || "[empty message]";
+		const senderName = this.resolveIncomingSenderName(identity.senderId, identity.rawEvent, content);
+		const route = this.resolveIncomingRoute(event, identity.rawEvent, identity.senderId, senderName);
+		if (!route.chatId || !this.isAllowed(identity.senderId)) return;
+		await this.bus.publishInbound({
+			channel: this.name,
+			senderId: identity.senderId,
+			chatId: route.chatId,
+			content: this.decorateSpeakerPrefix({
+				content,
+				messageType: route.messageType,
+				senderId: identity.senderId,
+				senderName
+			}),
+			metadata: {
+				message_id: identity.messageId,
+				qq: route.metadata
+			}
+		});
+	};
+	resolveIncomingIdentity = (event) => {
+		const messageId = event.message_id || event.id || "";
+		if (messageId && this.isDuplicate(messageId)) return null;
+		const rawEvent = event;
+		if (this.isSelfEvent(event)) return null;
+		const senderId = this.resolveSenderId(event, rawEvent);
+		return senderId ? {
+			messageId,
+			rawEvent,
+			senderId
+		} : null;
+	};
+	resolveIncomingSenderName = (senderId, rawEvent, content) => {
+		const eventSenderName = this.resolveSenderName(rawEvent);
+		if (eventSenderName) this.senderNameCache.set(senderId, eventSenderName);
+		const declaredName = this.extractDeclaredName(content);
+		if (declaredName) this.senderNameCache.set(senderId, declaredName);
+		return declaredName ?? eventSenderName ?? this.senderNameCache.get(senderId) ?? null;
+	};
+	resolveIncomingRoute = (event, rawEvent, senderId, senderName) => {
+		let chatId = senderId;
+		let messageType = "private";
+		const qqMeta = {};
+		if (event.message_type === "group") {
+			messageType = "group";
+			const groupId = event.group_id || rawEvent.group_openid || "";
+			chatId = groupId;
+			qqMeta.groupId = groupId;
+			qqMeta.userId = senderId;
+			if (senderName) qqMeta.userName = senderName;
+		} else {
+			qqMeta.userId = senderId;
+			if (senderName) qqMeta.userName = senderName;
+		}
+		qqMeta.messageType = messageType;
+		return {
+			chatId,
+			messageType,
+			metadata: qqMeta
+		};
+	};
+	isAllowed = (senderId) => {
+		const allowList = this.config.allowFrom ?? [];
+		if (!allowList.length || allowList.includes(senderId)) return true;
+		return senderId.includes("|") && senderId.split("|").some((part) => allowList.includes(part));
+	};
+	isSelfEvent = (event) => {
+		const userId = typeof event.user_id === "string" ? event.user_id : "";
+		const selfId = typeof event.self_id === "string" ? event.self_id : "";
+		return Boolean(userId && selfId && userId === selfId);
+	};
+	resolveSenderId = (event, rawEvent) => {
+		return this.readFirstString([
+			event.user_id,
+			rawEvent.sender?.member_openid,
+			rawEvent.sender?.user_openid,
+			rawEvent.sender?.user_id,
+			rawEvent.author?.member_openid,
+			rawEvent.author?.user_openid,
+			rawEvent.author?.id
+		]) ?? "";
+	};
+	resolveSenderName = (rawEvent) => {
+		return this.readFirstString([
+			rawEvent.sender?.card,
+			rawEvent.sender?.nickname,
+			rawEvent.sender?.nick,
+			rawEvent.sender?.username,
+			rawEvent.sender?.user_name,
+			rawEvent.author?.username
+		]);
+	};
+	readFirstString = (values) => {
+		for (const value of values) {
+			if (typeof value !== "string") continue;
+			const normalized = value.trim();
+			if (normalized) return normalized;
+		}
+		return null;
+	};
+	decorateSpeakerPrefix = (params) => {
+		const { content, senderId, senderName } = params;
+		const userId = this.sanitizeSpeakerToken(senderId);
+		if (!userId) return content;
+		const name = this.sanitizeSpeakerToken(senderName ?? "");
+		const speakerFields = [`user_id=${userId}`];
+		if (name) speakerFields.push(`name=${name}`);
+		return `[speaker:${speakerFields.join(";")}] ${content}`;
+	};
+	sanitizeSpeakerToken = (value) => {
+		return value.replace(/[\r\n;\]]/g, " ").trim();
+	};
+	extractDeclaredName = (content) => {
+		const trimmed = content.trim();
+		for (const pattern of [
+			/^我的昵称是\s*([^\s，。！？!?,]{1,24})$/u,
+			/^我叫\s*([^\s，。！？!?,]{1,24})$/u,
+			/^叫我\s*([^\s，。！？!?,]{1,24})$/u
+		]) {
+			const match = trimmed.match(pattern);
+			if (!match) continue;
+			const candidate = this.sanitizeSpeakerToken(match[1] ?? "");
+			if (candidate) return candidate;
+		}
+		return null;
+	};
+	isDuplicate = (messageId) => {
+		if (this.processedSet.has(messageId)) return true;
+		this.processedSet.add(messageId);
+		this.processedIds.push(messageId);
+		if (this.processedIds.length > 1e3) {
+			const removed = this.processedIds.splice(0, 500);
+			for (const id of removed) this.processedSet.delete(id);
+		}
+		return false;
+	};
+	sendWithTokenRetry = async (send) => {
+		try {
+			await send();
+		} catch (error) {
+			if (!this.isTokenExpiredError(error) || !this.bot) throw error;
+			await this.bot.sessionManager.getAccessToken();
+			await send();
+		}
+	};
+	isTokenExpiredError = (error) => {
+		const message = error instanceof Error ? error.message : String(error);
+		return message.includes("code(11244)") || message.toLowerCase().includes("token not exist or expire");
+	};
+	isDisallowedUrlParamError = (error) => {
+		const message = error instanceof Error ? error.message : String(error);
+		return message.includes("code(40034028)") || message.includes("请求参数不允许包含url");
+	};
+	toQqSafeText = (content, error) => {
+		let safe = content.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1").replace(/https?:\/\/\S+/gi, "[link]").replace(/www\.\S+/gi, "[link]").replace(/\b[a-z0-9._/-]+\.md\b/gi, "[file]");
+		const blocked = this.extractBlockedUrlToken(error);
+		if (blocked) safe = safe.replaceAll(blocked, "[link]");
+		return safe;
+	};
+	extractBlockedUrlToken = (error) => {
+		const match = (error instanceof Error ? error.message : String(error)).match(/包含url\s+([^\s]+)/);
+		if (!match) return null;
+		const token = match[1].trim();
+		return token.length > 0 ? token : null;
+	};
+	tryConnect = (trigger) => {
+		if (!this.running || this.bot || this.connectTask) return;
+		this.connectTask = this.connect(trigger).finally(() => {
+			this.connectTask = null;
+		});
+	};
+	connect = async (trigger) => {
+		let candidate = null;
+		try {
+			candidate = this.createBot();
+			await this.startBotWithTimeout(candidate);
+			if (!this.running) {
+				await this.safeStopBot(candidate);
+				return;
+			}
+			this.bot = candidate;
+			this.reconnectAttempt = 0;
+			console.log("QQ bot connected");
+		} catch (error) {
+			if (candidate) await this.safeStopBot(candidate);
+			if (!this.running) return;
+			this.reconnectAttempt += 1;
+			const delayMs = this.getBackoffDelayMs(this.reconnectAttempt);
+			console.error(`[qq] start failed (${trigger}, attempt ${this.reconnectAttempt}), retry in ${delayMs}ms: ${this.formatError(error)}`);
+			this.scheduleReconnect(delayMs, `${trigger}-retry`);
+		}
+	};
+	createBot = () => {
+		const bot = new Bot({
+			appid: this.config.appId,
+			secret: this.config.secret,
+			mode: ReceiverMode.WEBSOCKET,
+			intents: ["C2C_MESSAGE_CREATE", "GROUP_AT_MESSAGE_CREATE"],
+			removeAt: true,
+			logLevel: "info"
+		});
+		bot.on("message.private", async (event) => {
+			await this.handleIncoming(event);
+		});
+		bot.on("message.group", async (event) => {
+			await this.handleIncoming(event);
+		});
+		bot.sessionManager.on(SessionEvents.DEAD, () => {
+			this.handleSessionDead(bot);
+		});
+		return bot;
+	};
+	handleSessionDead = async (bot) => {
+		if (!this.running || this.bot !== bot) return;
+		this.bot = null;
+		await this.safeStopBot(bot);
+		this.reconnectAttempt += 1;
+		const delayMs = this.getBackoffDelayMs(this.reconnectAttempt);
+		console.error(`[qq] session dead, reconnect in ${delayMs}ms`);
+		this.scheduleReconnect(delayMs, "session-dead");
+	};
+	scheduleReconnect = (delayMs, trigger) => {
+		if (!this.running) return;
+		this.clearReconnectTimer();
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = null;
+			this.tryConnect(trigger);
+		}, delayMs);
+	};
+	clearReconnectTimer = () => {
+		if (!this.reconnectTimer) return;
+		clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = null;
+	};
+	teardownBot = async () => {
+		if (!this.bot) return;
+		const bot = this.bot;
+		this.bot = null;
+		await this.safeStopBot(bot);
+	};
+	safeStopBot = async (bot) => {
+		bot.removeAllListeners("message.private");
+		bot.removeAllListeners("message.group");
+		bot.sessionManager.removeAllListeners(SessionEvents.DEAD);
+		try {
+			await bot.stop();
+		} catch {}
+	};
+	startBotWithTimeout = async (bot) => {
+		let timer = null;
+		try {
+			await Promise.race([bot.start(), new Promise((_, reject) => {
+				timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`QQ bot start timed out after ${this.connectTimeoutMs}ms`)), this.connectTimeoutMs);
+			})]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	};
+	get isRunning() {
+		return this.bot !== null;
+	}
+	getBackoffDelayMs = (attempt) => {
+		const jitter = Math.floor(Math.random() * 500);
+		const exp = Math.min(this.reconnectMaxMs, this.reconnectBaseMs * 2 ** Math.max(0, attempt - 1));
+		return Math.min(this.reconnectMaxMs, exp + jitter);
+	};
+	formatError = (error) => {
+		if (error instanceof Error) return error.stack ?? error.message;
+		return String(error);
+	};
+};
+//#endregion
+export { QQChannel };

package/nextclaw.extension.json

@@ -0,0 +1,32 @@
+{
+  "id": "nextclaw-channel-extension-qq",
+  "name": "NextClaw QQ Channel Extension",
+  "version": "0.1.0",
+  "server": {
+    "type": "stdio",
+    "command": "node",
+    "args": ["dist/main.js"]
+  },
+  "contributes": {
+    "channels": [
+      {
+        "id": "qq",
+        "name": "QQ",
+        "description": "QQ official bot channel",
+        "configSchema": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "appId": { "type": "string" },
+            "secret": { "type": "string" },
+            "allowFrom": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nextclaw/channel-extension-qq",
+  "version": "0.1.1",
+  "private": false,
+  "description": "NextClaw QQ channel extension process.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "nextclaw.extension.json"
+  ],
+  "dependencies": {
+    "qq-official-bot": "1.0.12",
+    "@nextclaw/extension-sdk": "0.1.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/main.ts --dts --clean --target es2022 --no-fixedExtension --unbundle",
+    "lint": "eslint src --max-warnings=0",
+    "test": "node --import tsx --test src/tests/*.test.ts",
+    "tsc": "tsc -p tsconfig.json"
+  }
+}