@zhin.js/adapter-icqq 1.0.71 → 1.1.2

package/lib/endpoint.js

@@ -0,0 +1,1003 @@
+import { Client, parseGroupMessageId, } from '@icqqjs/icqq';
+import { inspect } from 'node:util';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Endpoint, } from 'zhin.js/adapter';
+import { receiveOneBotLikeSideEvent, SystemEvent, toCanonicalSegments } from '@zhin.js/core';
+import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
+import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
+import { IcqqContentResolver } from './content-resolver.js';
+import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, messageLookupFromIcqqSource, resolveIcqqQuoteIdFromEvent, resolveIcqqInboundMedia, shouldSkipSelfInboundMessage, } from './icqq-inbound.js';
+import { isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
+import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
+import { prepareIcqqOutboundMedia, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
+import { formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
+const BOUND_EVENTS = [
+    'message.private',
+    'message.group',
+    'message.guild',
+    'request.friend',
+    'request.group',
+    'notice.friend',
+    'notice.group',
+    'system.online',
+    'system.offline',
+    'system.offline.network',
+    'system.offline.kickoff',
+    'system.login.qrcode',
+    'system.login.device',
+    'system.login.slider',
+    'system.login.error',
+    'system.login.auth',
+];
+class ManagedIcqqClient extends Client {
+    cancelReconnect() {
+        if (!this.login_timer)
+            return;
+        clearTimeout(this.login_timer);
+        this.login_timer = null;
+    }
+}
+export class IcqqEndpoint extends Endpoint {
+    client;
+    #logger;
+    #options;
+    endpointName;
+    #guildCatalog = new IcqqGuildCatalog();
+    #inboundDeduper = new InboundMessageDeduper();
+    #sideEventDeduper = new InboundMessageDeduper();
+    #loginAssistOwner = Object.freeze({});
+    #open = false;
+    #retiring = false;
+    #started = false;
+    #retirementEpoch = 0;
+    #retirementArmed = false;
+    #disposeNativeEvents;
+    #resolveStartOnline;
+    #heldInbound = [];
+    #inflightInbound = new Set();
+    #inboundOwner = new AsyncLocalStorage();
+    #contentResolver;
+    content;
+    management = Object.freeze({
+        listFriends: async () => Array.from(this.client.fl.values()).map((f) => ({
+            user_id: f.user_id,
+            nickname: f.nickname,
+            remark: f.remark ?? '',
+        })),
+        listGroups: async () => Array.from(this.client.gl.values()).map((g) => ({
+            group_id: g.group_id,
+            name: g.group_name,
+        })),
+        listChannels: async () => {
+            await this.#guildCatalog.syncAll(this.client);
+            return this.#guildCatalog.getGuildChannelList();
+        },
+        listGroupMembers: async (groupId) => Array.from((await this.client.getGroupMemberList(Number(groupId))).values()),
+        listRequests: () => this.#listPendingRequests(),
+        approveRequest: (requestId, remark) => this.#approveRequest(requestId, remark),
+        rejectRequest: (requestId, reason) => this.#rejectRequest(requestId, reason),
+        kickGroupMember: async (groupId, userId) => {
+            await this.client.setGroupKick(Number(groupId), Number(userId));
+        },
+        muteGroupMember: async (groupId, userId, duration) => {
+            await this.client.setGroupBan(Number(groupId), Number(userId), duration);
+        },
+        setGroupAdmin: async (groupId, userId, enabled) => {
+            await this.client.setGroupAdmin(Number(groupId), Number(userId), enabled);
+        },
+        deleteFriend: async (userId) => {
+            await this.client.deleteFriend(Number(userId));
+        },
+    });
+    control = Object.freeze({
+        recall: async (message) => {
+            if (!message.id || message.id.startsWith('outbound:'))
+                return;
+            await this.client.deleteMsg(message.id);
+        },
+        addReaction: async (message, emoji) => {
+            const target = resolveIcqqGroupReactionTarget(message);
+            if (!target)
+                return null;
+            try {
+                // Do not await protocol ACK — packet timeout must not stall the AI reply.
+                this.#ignoreReactionAck('add', this.client.pickGroup(target.groupId).setReaction(target.seq, emoji));
+            }
+            catch (error) {
+                this.#logger.debug(formatCompact({
+                    op: 'reaction_add_failed',
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+            return emoji;
+        },
+        removeReaction: async (message, reactionId) => {
+            const target = resolveIcqqGroupReactionTarget(message);
+            if (!target)
+                return;
+            try {
+                this.#ignoreReactionAck('remove', this.client.pickGroup(target.groupId).delReaction(target.seq, reactionId));
+            }
+            catch (error) {
+                this.#logger.debug(formatCompact({
+                    op: 'reaction_remove_failed',
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+        },
+    });
+    constructor(options) {
+        super();
+        const nativeConfig = resolveNativeClientConfig(options.config);
+        this.client = new ManagedIcqqClient(Number(options.config.id), nativeConfig);
+        this.#contentResolver = new IcqqContentResolver(this.client);
+        this.content = this.#contentResolver.port;
+        this.#logger = getAdapterLogger('icqq', options.config.id);
+        this.#options = options;
+        this.endpointName = options.config.id;
+    }
+    #ignoreReactionAck(action, task) {
+        void Promise.resolve(task).catch((error) => {
+            this.#logger.debug(formatCompact({
+                op: `reaction_${action}_failed`,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
+    async start(signal) {
+        if (this.#started)
+            return;
+        signal.throwIfAborted();
+        // Invalidate a guard left by a prior lifecycle epoch before admitting a
+        // new login attempt on this endpoint instance.
+        this.#retirementEpoch += 1;
+        this.#retirementArmed = false;
+        this.#retiring = false;
+        this.client.off('system.online');
+        this.#started = true;
+        let resolveOnline;
+        const onlineReady = new Promise((resolve) => {
+            resolveOnline = resolve;
+        });
+        const onAbort = () => resolveOnline();
+        this.#resolveStartOnline = resolveOnline;
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            this.#bindClientEvents();
+            await raceAbort(Promise.resolve(this.client.login(this.#options.config.password)), signal);
+            await onlineReady;
+            signal.throwIfAborted();
+            await this.#pullPendingSystemMessages(signal);
+            signal.throwIfAborted();
+            this.#logger.info(`connected (direct) | friends: ${this.client.fl.size} | groups: ${this.client.gl.size}`);
+        }
+        catch (error) {
+            await this.stop();
+            this.#logger.debug(`Failed to connect ICQQ client: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+            throw error;
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+            if (this.#resolveStartOnline === resolveOnline)
+                this.#resolveStartOnline = undefined;
+        }
+    }
+    open() {
+        if (this.#retirementArmed) {
+            this.#retirementEpoch += 1;
+            this.#retirementArmed = false;
+            this.client.off('system.online');
+            this.#bindSystemOnlineEvent();
+        }
+        this.#retiring = false;
+        this.#open = true;
+        const held = this.#heldInbound.splice(0);
+        for (const msg of held) {
+            void this.admit(msg).catch((error) => {
+                this.#logInboundHandlerFailure('held', error);
+            });
+        }
+    }
+    async close() {
+        this.#assertExternalLifecycle('close');
+        this.#armRetirementFence();
+        await Promise.allSettled([...this.#inflightInbound]);
+    }
+    async stop() {
+        this.#assertExternalLifecycle('stop');
+        this.#armRetirementFence();
+        await Promise.allSettled([...this.#inflightInbound]);
+        this.#resolveStartOnline?.();
+        this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'endpoint_stopped');
+        this.#heldInbound.length = 0;
+        this.#disposeNativeEvents?.();
+        this.#disposeNativeEvents = undefined;
+        for (const event of BOUND_EVENTS) {
+            // The retirement guard owns this matcher until a late login handshake
+            // has finished. start()/open() replace it with the normal listener.
+            if (event !== 'system.online')
+                this.client.off(event);
+        }
+        // `Client.logout()` sends an account-level unregister packet before it
+        // closes this transport. During config HMR the replacement endpoint for
+        // the same UIN is already online, so unregistering the retiring generation
+        // also closes the replacement session. Endpoint ownership is transport
+        // scoped: retire only this Client's TCP connection.
+        try {
+            this.client.terminate();
+        }
+        catch { /* ignore */ }
+        this.#inboundDeduper.clear();
+        this.#sideEventDeduper.clear();
+        this.#guildCatalog.clear();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    #armRetirementFence() {
+        this.#retiring = true;
+        this.#open = false;
+        if (this.#retirementArmed)
+            return;
+        this.#retirementArmed = true;
+        const retirementEpoch = ++this.#retirementEpoch;
+        // ICQQ owns reconnect through this per-Client timer. Clear it before any
+        // asynchronous drain so a queued callback cannot enter while close waits.
+        this.client.cancelReconnect();
+        // A login callback may already be inside the SDK handshake, which has no
+        // abort API. Replace the normal online listener with an epoch-owned guard
+        // before draining inbound work. Transport termination is account-local;
+        // logout would also unregister an HMR replacement using the same UIN.
+        this.client.off('system.online');
+        this.client.on('system.online', () => {
+            if (this.#retirementEpoch !== retirementEpoch || !this.#retiring)
+                return;
+            try {
+                this.client.terminate();
+            }
+            catch { /* already closed */ }
+        });
+    }
+    async send({ conversation, payload }) {
+        if (!this.#started)
+            throw new Error('icqq endpoint 未连接');
+        const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
+        const prepared = isIcqqSegmentPayload(payload)
+            ? prepareIcqqOutboundMedia(payload, mediaMode)
+            : { content: payload, dispose() { } };
+        try {
+            const message = formatOutboundBody(prepared.content);
+            const preview = formatIcqqSendablePreview(message);
+            const parsed = icqqOutboundTarget(conversation);
+            let result;
+            try {
+                result = await this.#sendNative(parsed, message);
+            }
+            catch (error) {
+                this.#logger.warn(formatCompact({
+                    op: 'icqq_send_failed',
+                    target: `${conversation.kind}:${conversation.id}`,
+                    error: describeUnknownError(error),
+                    preview: truncatePreview(preview, 120),
+                }));
+                throw error;
+            }
+            const messageId = String(result?.message_id ?? `sent_${Date.now()}`);
+            this.#logger.info(`send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(preview, 80)}`);
+            return messageId;
+        }
+        finally {
+            prepared.dispose();
+        }
+    }
+    async #sendNative(target, message) {
+        if (isIcqqShareElement(message)) {
+            switch (target.kind) {
+                case 'private':
+                    await this.client.pickFriend(target.userId).share(message);
+                    return {};
+                case 'group':
+                    await this.client.pickGroup(target.groupId).share(message);
+                    return {};
+                case 'temp':
+                    await this.client.pickMember(target.groupId, target.userId).share(message);
+                    return {};
+                case 'channel': {
+                    const channel = this.client.pickGuild(target.guildId).channels.get(target.channelId);
+                    if (!channel) {
+                        throw new TypeError(`ICQQ guild channel is unavailable: ${target.guildId}/${target.channelId}`);
+                    }
+                    await channel.share(message);
+                    return {};
+                }
+            }
+        }
+        if (isIcqqFileElement(message)) {
+            switch (target.kind) {
+                case 'private': {
+                    const id = await this.client.pickFriend(target.userId).sendFile(message.file, message.name);
+                    return { message_id: id };
+                }
+                case 'group': {
+                    const stat = await this.client.pickGroup(target.groupId).sendFile(message.file, '/', message.name);
+                    return { message_id: stat.fid };
+                }
+                case 'temp':
+                case 'channel':
+                    throw new TypeError(`ICQQ ${target.kind} conversation does not support file delivery`);
+            }
+        }
+        switch (target.kind) {
+            case 'private':
+                return this.client.sendPrivateMsg(target.userId, message);
+            case 'group':
+                return this.client.sendGroupMsg(target.groupId, message);
+            case 'temp':
+                return this.client.sendTempMsg(target.groupId, target.userId, message);
+            case 'channel':
+                return this.client.sendGuildMsg(target.guildId, target.channelId, message);
+        }
+    }
+    admit(msg) {
+        return this.#trackInbound(() => this.#deliverInbound(msg));
+    }
+    #trackInbound(run) {
+        const owner = Symbol('icqq-inbound');
+        let settle;
+        const settlement = new Promise((resolve) => { settle = resolve; });
+        this.#inflightInbound.add(settlement);
+        let operation;
+        try {
+            operation = this.#inboundOwner.run(owner, run);
+        }
+        catch (error) {
+            this.#inflightInbound.delete(settlement);
+            settle();
+            return Promise.reject(error);
+        }
+        return operation.finally(() => {
+            this.#inflightInbound.delete(settlement);
+            settle();
+        });
+    }
+    #assertExternalLifecycle(operation) {
+        if (!this.#inboundOwner.getStore())
+            return;
+        throw new Error(`ICQQ endpoint ${operation} cannot run inside its own inbound receive; invoke it from the owning lifecycle`);
+    }
+    async #deliverInbound(msg, admittedBeforeRetire = false) {
+        const conversation = msg.conversation;
+        if (!this.#open && !admittedBeforeRetire) {
+            if (this.#retiring)
+                return;
+            if (this.#heldInbound.length >= INBOUND_HOLD_LIMIT) {
+                const dropped = this.#heldInbound.shift();
+                this.#logger.warn(formatCompact({
+                    op: 'icqq_inbound_hold_drop',
+                    endpoint: this.endpointName,
+                    id: dropped?.id,
+                    target: dropped
+                        ? `${dropped.conversation.kind}:${dropped.conversation.id}`
+                        : undefined,
+                    limit: INBOUND_HOLD_LIMIT,
+                }));
+            }
+            this.#heldInbound.push(msg);
+            this.#logger.info(`hold ${conversation.kind}:${conversation.id}`
+                + (msg.sender ? ` from ${msg.sender.name ?? msg.sender.id}` : '')
+                + ` until open | ${truncatePreview(msg.content, 80)}`);
+            return;
+        }
+        const mentioned = isIcqqBotMentioned({
+            uin: this.endpointName,
+            content: msg.segments,
+            rawMessage: msg.content,
+        });
+        this.#logger.info(`recv ${conversation.kind}:${conversation.id}`
+            + (msg.sender ? ` from ${msg.sender.name ?? msg.sender.id}` : '')
+            + (mentioned ? ' (mentioned)' : '')
+            + ` | ${truncatePreview(msg.content, 80)}`);
+        await this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: msg.id },
+            content: msg.content,
+            ...(msg.segments ? { segments: msg.segments } : {}),
+            sender: msg.sender,
+            endpointId: this.endpointName,
+            ...(mentioned ? { mentioned: true } : {}),
+            ...(msg.replyTo ? { replyTo: msg.replyTo } : {}),
+            metadata: Object.freeze({
+                channelType: msg.channelType,
+                ...(msg.metadata ?? {}),
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'recv',
+                endpoint: this.endpointName,
+                target: `${conversation.kind}:${conversation.id}`,
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #bindClientEvents() {
+        this.#bindNativeEvents();
+        const safe = (label, fn) => {
+            try {
+                fn();
+            }
+            catch (error) {
+                this.#logger.warn(formatCompact({
+                    op: 'icqq_event_handler',
+                    endpoint: this.endpointName,
+                    event: label,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+        };
+        this.client.on('message.private', (event) => {
+            this.#startMessageEvent('message.private', event);
+        });
+        this.client.on('message.group', (event) => {
+            this.#startMessageEvent('message.group', event);
+        });
+        this.client.on('message.guild', (event) => {
+            void this.#handleGuildEvent(event).catch((error) => {
+                this.#logInboundHandlerFailure('message.guild', error);
+            });
+        });
+        this.client.on('request.friend', (event) => safe('request.friend', () => {
+            this.#onRequestEvent(serializeIcqqEvent(event));
+        }));
+        this.client.on('request.group', (event) => safe('request.group', () => {
+            this.#onRequestEvent(serializeIcqqEvent(event));
+        }));
+        this.client.on('notice.friend', (event) => safe('notice.friend', () => {
+            this.#onNoticeEvent(serializeIcqqEvent(event));
+        }));
+        this.client.on('notice.group', (event) => safe('notice.group', () => {
+            this.#onNoticeEvent(serializeIcqqEvent(event));
+        }));
+        this.#bindSystemOnlineEvent();
+        this.client.on('system.offline', (event) => {
+            this.#logSystemEvent('offline', event);
+        });
+        this.client.on('system.offline.network', (event) => {
+            this.#logSystemEvent('offline.network', event);
+        });
+        this.client.on('system.offline.kickoff', (event) => {
+            this.#logSystemEvent('offline.kickoff', event);
+        });
+        this.client.on('system.login.qrcode', (event) => {
+            this.#logger.info('icqq 收到二维码登录事件，等待 LoginAssist / 终端确认后继续');
+            this.#handleLoginChallenge('qrcode', event);
+        });
+        this.client.on('system.login.device', (event) => {
+            this.#handleLoginChallenge('device', event);
+        });
+        this.client.on('system.login.slider', (event) => {
+            this.#handleLoginChallenge('slider', event);
+        });
+        this.client.on('system.login.error', (event) => {
+            this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'login_error');
+            this.#logSystemEvent('login.error', event);
+        });
+        this.client.on('system.login.auth', (event) => {
+            this.#handleLoginChallenge('auth', event);
+        });
+    }
+    #bindSystemOnlineEvent() {
+        this.client.on('system.online', (event) => {
+            if (this.#retiring)
+                return;
+            try {
+                this.#resolveStartOnline?.();
+                this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
+                this.#logSystemEvent('online', event);
+            }
+            catch (error) {
+                this.#logger.warn(formatCompact({
+                    op: 'icqq_event_handler',
+                    endpoint: this.endpointName,
+                    event: 'system.online',
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+        });
+    }
+    /** Forward every public SDK event, including protocol extensions unknown to Zhin. */
+    #bindNativeEvents() {
+        this.#disposeNativeEvents?.();
+        let matchedName;
+        const registration = this.client.on((eventName) => {
+            matchedName = typeof eventName === 'string' && !eventName.startsWith('internal.')
+                ? eventName
+                : undefined;
+            return matchedName !== undefined;
+        }, (event) => {
+            const name = matchedName;
+            if (name)
+                this.#emitNativeEvent(name, event);
+        });
+        this.#disposeNativeEvents = () => registration();
+    }
+    #emitNativeEvent(name, event) {
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'icqq_platform_event_failed',
+                endpoint: this.endpointName,
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
+    #handleLoginChallenge(step, event) {
+        const payload = serializeIcqqEvent(event) ?? (event && typeof event === 'object'
+            ? event
+            : null);
+        this.#logSystemEvent(`login.${step}`, event);
+        void runIcqqLoginAssistStep({
+            assist: this.#options.loginAssist,
+            client: this.client,
+            adapter: 'icqq',
+            endpointKey: this.endpointName,
+            owner: this.#loginAssistOwner,
+            logger: this.#logger,
+            step,
+            event: payload ?? event,
+        });
+    }
+    #logSystemEvent(type, event) {
+        const payload = serializeIcqqEvent(event);
+        this.#logger.warn(formatCompact({
+            op: `system.${type}`,
+            endpoint: this.endpointName,
+            ...(payload ? { event: JSON.stringify(payload) } : {}),
+        }));
+        this.#dispatchIcqqSystemSideEvent(type, payload);
+    }
+    #dispatchIcqqSideEvent(payload) {
+        const postType = String(payload.post_type ?? '');
+        const isRequest = postType === 'request' || postType.startsWith('request.');
+        const flag = payload.flag != null ? String(payload.flag) : '';
+        void receiveOneBotLikeSideEvent((name, payload) => this.emit(name, payload), {
+            adapter: 'icqq',
+            endpointKey: this.endpointName,
+            platform: 'icqq',
+            raw: payload,
+            ...(isRequest ? {
+                approve: (id, remark) => this.#approveRequest(flag || id, remark),
+                reject: (id, reason) => this.#rejectRequest(flag || id, reason),
+            } : {}),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'icqq_side_event_failed',
+                endpoint: this.endpointName,
+                post_type: postType || undefined,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #dispatchIcqqSystemSideEvent(type, payload) {
+        const { scene_type, sub_type } = parseIcqqSystemScene(type);
+        void this.emit('system.receive', SystemEvent.from(payload ?? {}, {
+            $id: `system:${this.endpointName}:${type}:${Date.now()}`,
+            $adapter: 'icqq',
+            $endpoint: this.endpointName,
+            $type: 'system',
+            $scene_id: this.endpointName,
+            $scene_type: scene_type,
+            $sub_type: sub_type,
+            $timestamp: Date.now(),
+        })).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'icqq_system_side_event_failed',
+                endpoint: this.endpointName,
+                type,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async #handleMessageEvent(eventName, event) {
+        if (this.#retiring)
+            return;
+        const admittedBeforeRetire = this.#open;
+        const payload = serializeIcqqEvent(event);
+        if (!payload || !isIcqqMessagePostType(payload)) {
+            this.#logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: payload ? 'not_message_post' : 'serialize_failed',
+                endpoint: this.endpointName,
+                event: eventName,
+            }));
+            return;
+        }
+        const data = payload;
+        if (shouldSkipSelfInboundMessage(data)) {
+            this.#logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'self',
+                endpoint: this.endpointName,
+                user_id: data.user_id,
+                self_id: data.self_id,
+            }));
+            return;
+        }
+        const contact = this.#resolveInboundContact(data);
+        if (contact) {
+            await resolveIcqqInboundMedia(data.message, {
+                getPttUrl: (element) => contact.getPttUrl(element),
+                getVideoUrl: (element) => contact.getVideoUrl(element),
+            });
+            if (!this.#started)
+                return;
+        }
+        const normalized = normalizeIcqqInboundMessage(data);
+        if (!normalized) {
+            this.#logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'normalize_failed',
+                endpoint: this.endpointName,
+                event: eventName,
+                message_id: data.message_id,
+            }));
+            return;
+        }
+        if (!this.#inboundDeduper.shouldProcess(normalized.messageId)) {
+            this.#logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'dedupe',
+                endpoint: this.endpointName,
+                id: normalized.messageId,
+            }));
+            return;
+        }
+        const conversation = icqqInboundConversation(String(this.#options.id), {
+            channelType: normalized.channelType,
+            channelId: normalized.channelId,
+            channelParentGroupId: normalized.channelParentGroupId,
+        });
+        const quoteId = resolveIcqqQuoteIdFromEvent(data);
+        const quoted = messageLookupFromIcqqSource(findIcqqNestedMessageSource(data));
+        if (quoteId && quoted) {
+            this.#contentResolver.remember(quoteId, Object.freeze({
+                ref: Object.freeze({ conversation, id: quoteId }),
+                ...(quoted.sender?.id ? { actor: Object.freeze({
+                        id: quoted.sender.id,
+                        ...(quoted.sender.name ? { displayName: quoted.sender.name } : {}),
+                    }) } : {}),
+                segments: Object.freeze(toCanonicalSegments(Array.isArray(quoted.content)
+                    ? quoted.content
+                    : [{ type: 'text', data: { text: quoted.content } }])),
+                timestamp: quoted.time ? quoted.time * (quoted.time < 1e12 ? 1000 : 1) : Date.now(),
+            }));
+        }
+        await this.#deliverInbound({
+            id: normalized.messageId,
+            conversation,
+            content: formatInboundContent(normalized.rawMessage),
+            segments: normalized.content,
+            sender: {
+                id: normalized.userId,
+                name: normalized.nickname || undefined,
+                ...(normalized.senderRole ? { roles: [normalized.senderRole] } : {}),
+            },
+            channelType: normalized.channelType,
+            ...(quoteId ? { replyTo: { id: quoteId } } : {}),
+            metadata: {
+                nickname: normalized.nickname,
+                senderRole: normalized.senderRole,
+            },
+        }, admittedBeforeRetire);
+    }
+    #startMessageEvent(eventName, event) {
+        const operation = this.#trackInbound(() => this.#handleMessageEvent(eventName, event));
+        void operation.catch((error) => {
+            this.#logInboundHandlerFailure(eventName, error);
+        });
+    }
+    #resolveInboundContact(data) {
+        const userId = Number(data.user_id ?? data.from_id);
+        if (!Number.isFinite(userId) || userId <= 0)
+            return null;
+        if (data.message_type === 'group' || data.group_id != null) {
+            const groupId = Number(data.group_id);
+            return Number.isFinite(groupId) && groupId > 0 ? this.client.pickGroup(groupId) : null;
+        }
+        const sourceGroupId = Number(data.sender?.group_id);
+        if (Number.isFinite(sourceGroupId) && sourceGroupId > 0) {
+            return this.client.pickMember(sourceGroupId, userId);
+        }
+        return this.client.pickFriend(userId);
+    }
+    #logInboundHandlerFailure(event, error) {
+        this.#logger.warn(formatCompact({
+            op: 'icqq_inbound_handler_failed',
+            endpoint: this.endpointName,
+            event,
+            error: describeUnknownError(error),
+        }));
+    }
+    async #handleGuildEvent(event) {
+        const payload = serializeIcqqEvent(event);
+        if (!payload || typeof payload !== 'object')
+            return;
+        const normalized = normalizeIcqqGuildInboundMessage(payload);
+        if (!normalized) {
+            this.#logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'guild_normalize_failed',
+                endpoint: this.endpointName,
+            }));
+            return;
+        }
+        this.#guildCatalog.upsertFromInbound(normalized.raw);
+        if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
+            this.#logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'dedupe',
+                endpoint: this.endpointName,
+                id: `guild:${normalized.messageId}`,
+            }));
+            return;
+        }
+        await this.admit({
+            id: normalized.messageId,
+            conversation: icqqInboundConversation(String(this.#options.id), {
+                channelType: 'channel',
+                channelId: normalized.channelId,
+                guildId: normalized.guildId,
+            }),
+            content: formatInboundContent(normalized.rawMessage),
+            segments: normalized.content,
+            sender: { id: normalized.userId, name: normalized.nickname || undefined },
+            channelType: 'channel',
+            metadata: {
+                guildId: normalized.guildId,
+                nickname: normalized.nickname,
+            },
+        });
+    }
+    #onRequestEvent(payload) {
+        if (!payload || !isIcqqRequestPayload(payload))
+            return;
+        const flag = payload.flag != null ? String(payload.flag) : (payload.seq != null ? String(payload.seq) : '');
+        if (flag && !this.#sideEventDeduper.shouldProcess(`request:${flag}`))
+            return;
+        this.#dispatchIcqqSideEvent(payload);
+    }
+    #onNoticeEvent(payload) {
+        if (!payload || !isIcqqNoticePayload(payload))
+            return;
+        const key = [
+            payload.time,
+            payload.operator_id ?? payload.user_id,
+            payload.notice_type ?? payload.type,
+            payload.sub_type,
+        ].join('_');
+        if (!this.#sideEventDeduper.shouldProcess(`notice:${key}`))
+            return;
+        this.#dispatchIcqqSideEvent(payload);
+    }
+    async #listPendingRequests() {
+        const messages = await this.client.getSystemMsg();
+        const rows = [];
+        for (const raw of messages) {
+            const msg = raw;
+            const kind = msg.request_type === 'friend' ? 'friend' : 'group';
+            const platformRequestId = (msg.flag && String(msg.flag).trim())
+                || (msg.seq != null ? String(msg.seq) : '');
+            if (!platformRequestId || msg.user_id == null)
+                continue;
+            const createdAt = Number(msg.time);
+            rows.push(Object.freeze({
+                platform_request_id: platformRequestId,
+                type: kind,
+                scene_type: kind === 'group' ? 'group' : null,
+                scene_id: String(kind === 'group' ? (msg.group_id ?? msg.user_id) : msg.user_id),
+                sub_type: kind === 'group' ? (msg.type != null ? String(msg.type) : null) : null,
+                actor_id: String(msg.user_id),
+                actor_name: msg.nickname != null ? String(msg.nickname) : null,
+                comment: msg.comment != null ? String(msg.comment) : null,
+                created_at: Number.isFinite(createdAt) && createdAt > 0
+                    ? (createdAt < 1e12 ? createdAt * 1000 : createdAt)
+                    : Date.now(),
+            }));
+        }
+        return Object.freeze(rows);
+    }
+    async #pullPendingSystemMessages(signal) {
+        try {
+            const messages = await raceAbort(Promise.resolve(this.client.getSystemMsg()), signal);
+            for (const raw of messages) {
+                signal.throwIfAborted();
+                const msg = raw;
+                const kind = msg.request_type === 'friend' ? 'friend' : 'group';
+                const flag = msg.flag != null ? String(msg.flag) : (msg.seq != null ? String(msg.seq) : '');
+                if (!flag || !this.#sideEventDeduper.shouldProcess(`request:${flag}`))
+                    continue;
+                this.#dispatchIcqqSideEvent({
+                    post_type: 'request',
+                    request_type: kind,
+                    flag: msg.flag,
+                    user_id: msg.user_id,
+                    group_id: msg.group_id,
+                    comment: msg.comment,
+                    time: msg.time,
+                    sub_type: msg.type,
+                });
+            }
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw signal.reason ?? error;
+            this.#logger.debug(formatCompact({
+                op: 'side_event_pull_system_msg',
+                endpoint: this.endpointName,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    async #approveRequest(id, remark) {
+        const messages = await this.client.getSystemMsg();
+        const target = messages.find((m) => {
+            const msg = m;
+            return msg.flag === id || (msg.seq != null && String(msg.seq) === id);
+        });
+        if (!target?.flag) {
+            throw new Error(`icqq 未找到待处理请求: ${id}`);
+        }
+        if (target.request_type === 'friend') {
+            await this.client.setFriendAddRequest(target.flag, true, remark);
+        }
+        else {
+            await this.client.setGroupAddRequest(target.flag, true);
+        }
+    }
+    async #rejectRequest(id, reason) {
+        const messages = await this.client.getSystemMsg();
+        const target = messages.find((m) => {
+            const msg = m;
+            return msg.flag === id || (msg.seq != null && String(msg.seq) === id);
+        });
+        if (!target?.flag) {
+            throw new Error(`icqq 未找到待处理请求: ${id}`);
+        }
+        if (target.request_type === 'friend') {
+            await this.client.setFriendAddRequest(target.flag, false);
+        }
+        else {
+            await this.client.setGroupAddRequest(target.flag, false, reason);
+        }
+    }
+}
+function isIcqqShareElement(message) {
+    return !Array.isArray(message)
+        && typeof message === 'object'
+        && message !== null
+        && message.type === 'share';
+}
+function formatIcqqSendablePreview(message) {
+    if (typeof message === 'string')
+        return message;
+    try {
+        return JSON.stringify(message, (_key, value) => Buffer.isBuffer(value) ? '<buffer>' : value);
+    }
+    catch {
+        return '[ICQQ Sendable]';
+    }
+}
+function isIcqqSegmentPayload(payload) {
+    if (Array.isArray(payload))
+        return true;
+    return typeof payload === 'object'
+        && payload !== null
+        && typeof payload.type === 'string';
+}
+function isIcqqFileElement(message) {
+    return !Array.isArray(message)
+        && typeof message !== 'string'
+        && message.type === 'file';
+}
+async function raceAbort(operation, signal) {
+    signal.throwIfAborted();
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => { rejectAbort = reject; });
+    const onAbort = () => rejectAbort(signal.reason ?? new Error('ICQQ operation aborted'));
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        return await Promise.race([operation, aborted]);
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
+function describeUnknownError(error) {
+    if (error instanceof Error)
+        return error.stack ?? error.message;
+    if (error && typeof error === 'object') {
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return inspect(error, { depth: 4, breakLength: 120 });
+        }
+    }
+    return String(error);
+}
+function resolveIcqqGroupReactionTarget(message) {
+    if (message.conversation.kind !== 'group')
+        return null;
+    const groupId = Number(message.conversation.id);
+    if (!Number.isFinite(groupId) || groupId <= 0)
+        return null;
+    const raw = message.id?.trim();
+    if (!raw || raw.startsWith('outbound:'))
+        return null;
+    if (/^[1-9]\d*$/.test(raw))
+        return { groupId, seq: Number(raw) };
+    try {
+        const parsed = parseGroupMessageId(raw);
+        if (parsed.seq > 0)
+            return { groupId: parsed.group_id || groupId, seq: parsed.seq };
+    }
+    catch {
+        // not a cqhttp group message id
+    }
+    return null;
+}
+function resolveNativeClientConfig(config) {
+    return {
+        log_level: 'info',
+        platform: config.platform,
+        ...(config.ver ? { ver: config.ver } : {}),
+        ...(config.dataDir ? { data_dir: config.dataDir } : {}),
+        ...(config.signApiAddr ? { sign_api_addr: config.signApiAddr } : {}),
+        ...(config.ignoreSelf != null ? { ignore_self: config.ignoreSelf } : {}),
+        ...(config.resend != null ? { resend: config.resend } : {}),
+        ...(config.cacheGroupMember != null ? { cache_group_member: config.cacheGroupMember } : {}),
+        ...(config.autoServer != null ? { auto_server: config.autoServer } : {}),
+        ...(config.qqnt != null ? { QQNT: config.qqnt } : {}),
+        ...(config.ntLogin != null ? { NTLogin: config.ntLogin } : {}),
+        reconn_interval: config.autoReconnect ? 5 : 0,
+    };
+}
+function serializeIcqqEvent(event) {
+    if (!event || typeof event !== 'object')
+        return null;
+    const nativeToJSON = event.toJSON;
+    if (typeof nativeToJSON === 'function') {
+        try {
+            const json = nativeToJSON.call(event, [...ICQQ_SERIALIZE_SKIP]);
+            if (json && typeof json === 'object' && !Array.isArray(json)) {
+                return json;
+            }
+        }
+        catch {
+            /* JSON.stringify 也会无参调 toJSON，不能当回退 */
+        }
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(event)) {
+        if (typeof value === 'function' || ICQQ_SERIALIZE_SKIP.includes(key))
+            continue;
+        out[key] = value;
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
+function parseIcqqSystemScene(type) {
+    if (type.startsWith('login.')) {
+        return { scene_type: 'login', sub_type: type.slice('login.'.length) || 'unknown' };
+    }
+    if (type.startsWith('offline.')) {
+        return { scene_type: 'offline', sub_type: type.slice('offline.'.length) || 'unknown' };
+    }
+    if (type === 'online') {
+        return { scene_type: 'online', sub_type: 'online' };
+    }
+    if (type === 'offline') {
+        return { scene_type: 'offline', sub_type: 'offline' };
+    }
+    return { scene_type: 'system', sub_type: type };
+}
+const INBOUND_HOLD_LIMIT = 32;
+const ICQQ_SERIALIZE_SKIP = ['group', 'member', 'friend', 'discuss', 'client'];