@zhin.js/adapter-icqq 8.0.9 → 8.0.11

package/lib/endpoint.js

@@ -1,502 +1,236 @@
+import { Client, parseGroupMessageId, } from '@icqqjs/icqq';
+import { inspect } from 'node:util';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { registerIcqqAgentEndpoint } from './icqq-agent-deps.js';
-import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, quotedPayloadFromIcqqSource, resolveIcqqQuoteIdFromEvent, shouldSkipSelfInboundMessage, unwrapIcqqIpcEventPayload, } from './icqq-inbound.js';
+import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, quotedPayloadFromIcqqSource, resolveIcqqQuoteIdFromEvent, shouldSkipSelfInboundMessage, } from './icqq-inbound.js';
 import { buildIcqqInboxNoticeRow, buildIcqqInboxRequestRow, buildIcqqSystemRequestRow, isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
-import { IcqqGuildCatalog, isIcqqGuildIpcEvent, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
-import { IpcClient } from './ipc-client.js';
+import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 import { materializeOutboundBase64, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
-import { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
-export class IcqqIpcEndpoint {
+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',
+];
+export class IcqqEndpoint extends Client {
     #logger;
     #options;
-    #createIpc;
-    name;
-    /** Populated after start(); agent tools read this. */
-    ipc;
-    friends = new Map();
-    groups = new Map();
+    endpointName;
     #guildCatalog = new IcqqGuildCatalog();
+    #inboundDeduper = new InboundMessageDeduper();
+    #inboxDeduper = new InboundMessageDeduper();
+    #open = false;
+    #started = false;
+    #heldInbound = [];
+    #unregisterAgent;
     management = Object.freeze({
-        listFriends: () => this.getFriendList(),
-        listGroups: () => this.getGroupList(),
+        listFriends: async () => Array.from(this.fl.values()).map((f) => ({
+            user_id: f.user_id,
+            nickname: f.nickname,
+            remark: f.remark ?? '',
+        })),
+        listGroups: async () => Array.from(this.gl.values()).map((g) => ({
+            group_id: g.group_id,
+            name: g.group_name,
+        })),
         listChannels: async () => {
-            await this.#guildCatalog.syncAll(this.ipc);
+            await this.#guildCatalog.syncAll(this);
             return this.#guildCatalog.getGuildChannelList();
         },
-        listGroupMembers: (groupId) => this.getGroupMemberList(groupId),
-        approveRequest: (requestId, remark) => this.approveRequest(requestId, remark),
-        rejectRequest: (requestId, reason) => this.rejectRequest(requestId, reason),
-        kickGroupMember: (groupId, userId) => this.removeMember(groupId, userId),
-        muteGroupMember: (groupId, userId, duration) => this.muteMember(groupId, userId, duration),
-        setGroupAdmin: (groupId, userId, enabled) => this.setModerator(groupId, userId, enabled),
-        deleteFriend: (userId) => this.deleteFriend(userId),
+        listGroupMembers: async (groupId) => Array.from((await this.getGroupMemberList(Number(groupId))).values()),
+        approveRequest: (requestId, remark) => this.#approveRequest(requestId, remark),
+        rejectRequest: (requestId, reason) => this.#rejectRequest(requestId, reason),
+        kickGroupMember: async (groupId, userId) => {
+            await this.setGroupKick(Number(groupId), Number(userId));
+        },
+        muteGroupMember: async (groupId, userId, duration) => {
+            await this.setGroupBan(Number(groupId), Number(userId), duration);
+        },
+        setGroupAdmin: async (groupId, userId, enabled) => {
+            await this.setGroupAdmin(Number(groupId), Number(userId), enabled);
+        },
+        deleteFriend: async (userId) => {
+            await this.deleteFriend(Number(userId));
+        },
     });
     control = Object.freeze({
-        recall: (message) => this.recallMessage(message.id),
-        addReaction: (message, emoji) => this.addReaction(message.id, emoji),
-        removeReaction: (message, reactionId) => this.removeReaction(message.id, reactionId),
+        recall: async (message) => {
+            if (!message.id || message.id.startsWith('outbound:'))
+                return;
+            await this.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.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.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),
+                }));
+            }
+        },
     });
-    #open = false;
-    #started = false;
-    #subscriptions = [];
-    #inboundDeduper = new InboundMessageDeduper();
-    /** request/notice 去重（推送事件与 GET_SYSTEM_MSG 首拉可能重复同一 flag）。 */
-    #inboxDeduper = new InboundMessageDeduper();
-    #unregisterAgent;
-    /** 用户主动 stop 时为 true，阻止自动重连 */
-    #intentionalDisconnect = false;
-    /** 是否已有重连循环在跑（避免多次 schedule 叠套） */
-    #reconnectRunning = false;
     constructor(options) {
+        const nativeConfig = resolveNativeClientConfig(options.config);
+        super(Number(options.config.id), nativeConfig);
         this.#logger = getAdapterLogger('icqq', options.config.id);
         this.#options = options;
-        this.name = options.config.id;
-        this.#createIpc = options.createIpc ?? defaultCreateIpc;
+        this.endpointName = options.config.id;
     }
-    async request(action, params) {
-        if (!this.ipc) {
-            throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发起请求: ${action}`);
-        }
-        return this.ipc.request(action, params);
+    #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() {
         if (this.#started)
             return;
         this.#started = true;
-        this.#intentionalDisconnect = false;
         try {
-            await this.#bindIpcSession();
-            this.#unregisterAgent = registerIcqqAgentEndpoint(this.name, this);
-            this.#logger.info(`connected (${this.#options.config.rpc ? 'rpc' : 'ipc'}) | friends: ${this.friends.size} | groups: ${this.groups.size}`);
+            const onlineReady = new Promise((resolve) => {
+                this.on('system.online', () => resolve());
+            });
+            this.#bindClientEvents();
+            await this.login(this.#options.config.password);
+            await onlineReady;
+            await this.#pullPendingSystemMessages();
+            this.#unregisterAgent = registerIcqqAgentEndpoint(this.endpointName, this);
+            this.#logger.info(`connected (direct) | friends: ${this.fl.size} | groups: ${this.gl.size}`);
         }
         catch (error) {
             await this.stop();
-            // Startup connect failures are surfaced once (with stack) by AdapterIndex;
-            // keep this at debug to avoid a duplicate error-level log.
-            this.#logger.debug(`Failed to connect ICQQ IPC: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+            this.#logger.debug(`Failed to connect ICQQ client: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
             throw error;
         }
     }
-    /** 建立或恢复与守护进程的 IPC/RPC 会话（订阅、缓存列表） */
-    async #bindIpcSession() {
-        // 旧连接上的订阅句柄已失效，不再对死 socket 发 unsubscribe
-        this.#subscriptions = [];
-        this.ipc = await this.#createIpc(this.#options.config);
-        if (this.#options.config.autoReconnect !== false) {
-            this.ipc.setOnRemoteDisconnect(() => this.#scheduleReconnect());
-        }
-        await this.#refreshLists();
-        const sub = this.ipc.subscribe(Actions.SUBSCRIBE, {}, (event) => {
-            this.#handleEvent(event);
-        });
-        this.#subscriptions.push(sub);
-        // daemon 推送 client.em 全部事件，request/notice 实时到达；
-        // 启动时补一次 GET_SYSTEM_MSG，捞离线期间积存的待处理请求。
-        void this.#pullPendingSystemMessages();
-    }
-    /** IPC/RPC 意外断开时调度重连（指数退避） */
-    #scheduleReconnect() {
-        if (this.#options.config.autoReconnect === false)
-            return;
-        if (this.#intentionalDisconnect)
-            return;
-        if (this.#reconnectRunning)
-            return;
-        this.#reconnectRunning = true;
-        void this.#runReconnectLoop();
-    }
-    async #runReconnectLoop() {
-        try {
-            for (let attempt = 0; !this.#intentionalDisconnect; attempt++) {
-                const base = Math.min(30_000, 500 * 2 ** Math.min(attempt, 6));
-                const jitter = Math.floor(Math.random() * 400);
-                const delayMs = base + jitter;
-                // 首次断开 WARN，后续重试静默为 DEBUG，避免刷屏
-                const disconnectLog = attempt === 0 ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
-                disconnectLog(formatCompact({
-                    op: 'disconnect',
-                    ok: false,
-                    delay_ms: delayMs,
-                    attempt: attempt + 1,
-                }));
-                await new Promise((r) => setTimeout(r, delayMs));
-                if (this.#intentionalDisconnect)
-                    break;
-                try {
-                    await this.#bindIpcSession();
-                    this.#logger.info(`reconnected after ${attempt + 1} attempt(s)`
-                        + ` | friends: ${this.friends.size} | groups: ${this.groups.size}`);
-                    break;
-                }
-                catch (error) {
-                    const retryLog = attempt === 0 ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
-                    retryLog(formatCompact({
-                        op: 'reconnect',
-                        endpoint: this.name,
-                        ok: false,
-                        attempt: attempt + 1,
-                        error: error instanceof Error ? error.message : String(error),
-                    }));
-                }
-            }
-        }
-        finally {
-            this.#reconnectRunning = false;
-        }
-    }
     open() {
         this.#open = true;
+        const held = this.#heldInbound.splice(0);
+        for (const msg of held)
+            this.admit(msg);
     }
     close() {
         this.#open = false;
     }
     async stop() {
-        this.#intentionalDisconnect = true;
         this.#open = false;
-        this.ipc?.setOnRemoteDisconnect(null);
-        for (const sub of this.#subscriptions.splice(0)) {
-            await sub.unsubscribe().catch(() => { });
-        }
+        this.#heldInbound.length = 0;
         this.#unregisterAgent?.();
         this.#unregisterAgent = undefined;
-        this.#inboundDeduper.clear();
-        this.#inboxDeduper.clear();
-        this.friends.clear();
-        this.groups.clear();
-        this.#guildCatalog.clear();
+        for (const event of BOUND_EVENTS)
+            this.off(event);
         try {
-            this.ipc?.close();
+            await this.logout?.();
         }
-        catch {
-            /* ignore */
+        catch { /* ignore */ }
+        try {
+            this.terminate();
         }
-        // 置空 ipc：start 前 / stop 后的 request() 走防御性报错而非 TypeError
-        this.ipc = undefined;
+        catch { /* ignore */ }
+        this.#inboundDeduper.clear();
+        this.#inboxDeduper.clear();
+        this.#guildCatalog.clear();
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        if (!this.ipc) {
-            throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发送消息`);
-        }
+        if (!this.#started)
+            throw new Error('icqq endpoint 未连接');
         const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
         const content = Array.isArray(payload)
             ? materializeOutboundBase64(payload, mediaMode)
             : payload;
         const message = formatOutboundBody(content);
         const parsed = icqqOutboundTarget(conversation);
-        let action;
-        let params;
-        switch (parsed.kind) {
-            case 'private':
-                action = Actions.SEND_PRIVATE_MSG;
-                params = { user_id: parsed.userId, message };
-                break;
-            case 'group':
-                action = Actions.SEND_GROUP_MSG;
-                params = { group_id: parsed.groupId, message };
-                break;
-            case 'temp':
-                action = Actions.SEND_TEMP_MSG;
-                params = {
-                    group_id: parsed.groupId,
-                    user_id: parsed.userId,
-                    message,
-                };
-                break;
-            case 'channel':
-                action = Actions.GUILD_SEND_MSG;
-                params = {
-                    guild_id: parsed.guildId,
-                    channel_id: parsed.channelId,
-                    message,
-                };
-                break;
-        }
-        const resp = await this.ipc.request(action, params);
-        if (!resp.ok) {
-            this.#logger.warn(`send failed ${conversation.kind}:${conversation.id} | ${resp.error} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`);
-            throw new Error(`发送消息失败: ${resp.error}`);
-        }
-        const messageId = String(resp.data?.message_id ?? `sent_${Date.now()}`);
-        this.#logger.info(`send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`);
-        return messageId;
-    }
-    // ── 消息回应（activity-feedback / typing reaction）────────────────────
-    static EMOJI_MAP = {
-        '⏳': '1468368274',
-        '👍': '128077',
-        '❤️': '10084',
-        '😊': '128522',
-        '🎉': '127881',
-        '🔥': '128293',
-        '✅': '9989',
-        '❌': '10060',
-        '⭐': '11088',
-        '💯': '128175',
-    };
-    getEmojiId(emoji) {
-        if (/^\d+$/u.test(emoji))
-            return emoji;
-        return IcqqIpcEndpoint.EMOJI_MAP[emoji] ?? String(emoji.codePointAt(0) || 0);
-    }
-    /** Activity-feedback / OutboundHost reaction surface. */
-    async addReaction(messageId, emoji) {
+        let result;
         try {
-            const emojiId = this.getEmojiId(emoji);
-            const resp = await this.request(Actions.GROUP_SET_REACTION, {
-                message_id: messageId,
-                id: emojiId,
-            });
-            if (!resp.ok) {
-                this.#logger.warn(formatCompact({
-                    op: 'add_reaction',
-                    endpoint: this.name,
-                    message_id: messageId,
-                    emoji,
-                    id: emojiId,
-                    ok: false,
-                    error: resp.error,
-                }));
-                return null;
-            }
-            this.#logger.debug(formatCompact({
-                op: 'add_reaction',
-                endpoint: this.name,
-                message_id: messageId,
-                emoji,
-                id: emojiId,
-                ok: true,
-            }));
-            return emojiId;
-        }
-        catch (error) {
-            this.#logger.warn(formatCompact({
-                op: 'add_reaction',
-                endpoint: this.name,
-                message_id: messageId,
-                emoji,
-                ok: false,
-                error: error instanceof Error ? error.message : String(error),
-            }));
-            return null;
-        }
-    }
-    async removeReaction(messageId, reactionId) {
-        try {
-            const parts = reactionId.split('_');
-            const emojiId = parts.length >= 2 ? parts[1] : reactionId;
-            const resp = await this.request(Actions.GROUP_DEL_REACTION, {
-                message_id: messageId,
-                id: emojiId,
-            });
-            if (!resp.ok) {
-                this.#logger.warn(formatCompact({
-                    op: 'remove_reaction',
-                    endpoint: this.name,
-                    message_id: messageId,
-                    reaction_id: reactionId,
-                    id: emojiId,
-                    ok: false,
-                    error: resp.error,
-                }));
-                return;
-            }
-            this.#logger.debug(formatCompact({
-                op: 'remove_reaction',
-                endpoint: this.name,
-                message_id: messageId,
-                reaction_id: reactionId,
-                id: emojiId,
-                ok: true,
-            }));
-        }
-        catch (error) {
-            this.#logger.warn(formatCompact({
-                op: 'remove_reaction',
-                endpoint: this.name,
-                message_id: messageId,
-                reaction_id: reactionId,
-                ok: false,
-                error: error instanceof Error ? error.message : String(error),
-            }));
-        }
-    }
-    /** Activity-feedback autoRemove / Console recall. */
-    async recallMessage(messageId) {
-        if (!messageId || messageId.startsWith('outbound:'))
-            return;
-        try {
-            const resp = await this.request(Actions.RECALL_MSG, { message_id: messageId });
-            if (!resp.ok) {
-                this.#logger.warn(formatCompact({
-                    op: 'recall_message',
-                    endpoint: this.name,
-                    message_id: messageId,
-                    ok: false,
-                    error: resp.error,
-                }));
-                return;
+            switch (parsed.kind) {
+                case 'private':
+                    result = await this.sendPrivateMsg(parsed.userId, message);
+                    break;
+                case 'group':
+                    result = await this.sendGroupMsg(parsed.groupId, message);
+                    break;
+                case 'temp':
+                    result = await this.sendTempMsg(parsed.groupId, parsed.userId, message);
+                    break;
+                case 'channel':
+                    result = await this.sendGuildMsg(parsed.guildId, parsed.channelId, message);
+                    break;
             }
-            this.#logger.debug(formatCompact({
-                op: 'recall_message',
-                endpoint: this.name,
-                message_id: messageId,
-                ok: true,
-            }));
         }
         catch (error) {
             this.#logger.warn(formatCompact({
-                op: 'recall_message',
-                endpoint: this.name,
-                message_id: messageId,
-                ok: false,
-                error: error instanceof Error ? error.message : String(error),
+                op: 'icqq_send_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: describeUnknownError(error),
+                preview: truncatePreview(typeof message === 'string' ? message : String(message), 120),
             }));
+            throw error;
         }
+        const messageId = String(result?.message_id ?? `sent_${Date.now()}`);
+        this.#logger.info(`send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`);
+        return messageId;
     }
-    // ── 社交/群管（Console endpoint RPC 探测面）────────────────────────
-    // console-rpc-extended.ts 按方法名探测这些接口；全部薄封装走 IPC daemon。
-    /** EndpointManagement.listFriends —— 好友列表（LIST_FRIENDS，归一为 {user_id, nickname, remark}）。 */
-    async getFriendList() {
-        const resp = await this.#mustRequest(Actions.LIST_FRIENDS, undefined, '获取好友列表');
-        const list = Array.isArray(resp.data) ? resp.data : [];
-        return list.map((f) => ({
-            user_id: f.user_id,
-            nickname: f.nickname,
-            remark: f.remark ?? '',
-        }));
-    }
-    /** EndpointManagement.listGroups —— 群列表（LIST_GROUPS，归一为 {group_id, name}）。 */
-    async getGroupList() {
-        const resp = await this.#mustRequest(Actions.LIST_GROUPS, undefined, '获取群列表');
-        const list = Array.isArray(resp.data) ? resp.data : [];
-        return list.map((g) => ({
-            group_id: g.group_id,
-            name: g.group_name,
-        }));
-    }
-    /** EndpointManagement.listGroupMembers —— 群成员列表（字段对齐 daemon 返回）。 */
-    async getGroupMemberList(groupId) {
-        const resp = await this.#mustRequest(Actions.LIST_GROUP_MEMBERS, { group_id: toNumericId(groupId, 'group_id') }, '获取群成员列表');
-        return Array.isArray(resp.data) ? resp.data : [];
-    }
-    /** getGroupMemberList 别名（console 探测 listMembers / getMemberList）。 */
-    listMembers(groupId) {
-        return this.getGroupMemberList(groupId);
-    }
-    getMemberList(groupId) {
-        return this.getGroupMemberList(groupId);
-    }
-    /**
-     * EndpointManagement.resolveRequest —— id 为 inbox 行的 platform_request_id。
-     * 先 GET_SYSTEM_MSG 按 flag（回退 seq）定位请求，再按类型路由 handle_friend/group_request。
-     */
-    async approveRequest(id, remark) {
-        await this.#handleSystemRequest(id, true, { remark });
-    }
-    async rejectRequest(id, reason) {
-        await this.#handleSystemRequest(id, false, { reason });
-    }
-    /** EndpointManagement.deleteFriend —— FRIEND_DELETE。 */
-    async deleteFriend(userId) {
-        await this.#mustRequest(Actions.FRIEND_DELETE, { user_id: toNumericId(userId, 'user_id') }, '删除好友');
-    }
-    /** deleteFriend 别名（console 探测 delete_friend）。 */
-    delete_friend(userId) {
-        return this.deleteFriend(userId);
-    }
-    /** EndpointManagement.kickGroupMember —— GROUP_KICK。 */
-    async removeMember(groupId, userId) {
-        await this.#mustRequest(Actions.GROUP_KICK, { group_id: toNumericId(groupId, 'group_id'), user_id: toNumericId(userId, 'user_id') }, '踢出群成员');
-    }
-    kickMember(groupId, userId) {
-        return this.removeMember(groupId, userId);
-    }
-    setGroupKick(groupId, userId) {
-        return this.removeMember(groupId, userId);
-    }
-    /** EndpointManagement.muteGroupMember —— GROUP_MUTE（duration 秒，默认 600）。 */
-    async muteMember(groupId, userId, duration = 600) {
-        await this.#mustRequest(Actions.GROUP_MUTE, {
-            group_id: toNumericId(groupId, 'group_id'),
-            user_id: toNumericId(userId, 'user_id'),
-            duration,
-        }, '禁言群成员');
-    }
-    banMember(groupId, userId, duration = 600) {
-        return this.muteMember(groupId, userId, duration);
-    }
-    setGroupMute(groupId, userId, duration = 600) {
-        return this.muteMember(groupId, userId, duration);
-    }
-    /** EndpointManagement.setGroupAdmin —— SET_GROUP_ADMIN（enable 默认 true）。 */
-    async setModerator(groupId, userId, enable = true) {
-        await this.#mustRequest(Actions.SET_GROUP_ADMIN, {
-            group_id: toNumericId(groupId, 'group_id'),
-            user_id: toNumericId(userId, 'user_id'),
-            enable,
-        }, '设置群管理员');
-    }
-    setAdmin(groupId, userId, enable = true) {
-        return this.setModerator(groupId, userId, enable);
-    }
-    setGroupAdmin(groupId, userId, enable = true) {
-        return this.setModerator(groupId, userId, enable);
-    }
-    /** IPC 请求并统一错误上下文：daemon 返回 ok=false 时抛出带操作名的错误。 */
-    async #mustRequest(action, params, label) {
-        const resp = await this.request(action, params);
-        if (!resp.ok) {
-            throw new Error(`icqq ${label}失败: ${resp.error ?? 'daemon 未返回错误详情'}`);
-        }
-        return resp;
-    }
-    /** 按 flag/seq 在 GET_SYSTEM_MSG 中定位请求，路由到好友/群请求处理 action。 */
-    async #handleSystemRequest(id, approve, extra) {
-        const resp = await this.#mustRequest(Actions.GET_SYSTEM_MSG, undefined, '获取待处理请求');
-        const data = resp.data;
-        const friendRequests = Array.isArray(data?.friendRequests)
-            ? data.friendRequests
-            : [];
-        const groupRequests = Array.isArray(data?.groupRequests)
-            ? data.groupRequests
-            : [];
-        const matches = (m) => m.flag === id || (m.seq != null && String(m.seq) === id);
-        const friend = friendRequests.find(matches);
-        const group = friend ? undefined : groupRequests.find(matches);
-        const target = friend ?? group;
-        if (!target?.flag) {
-            throw new Error(`icqq 未找到待处理请求: ${id}（GET_SYSTEM_MSG 中无匹配 flag/seq）`);
-        }
-        const params = { flag: target.flag, approve };
-        if (friend) {
-            if (extra.remark)
-                params.remark = extra.remark;
-            await this.#mustRequest(Actions.HANDLE_FRIEND_REQUEST, params, '处理好友请求');
-        }
-        else {
-            if (extra.reason)
-                params.reason = extra.reason;
-            await this.#mustRequest(Actions.HANDLE_GROUP_REQUEST, params, '处理群请求');
-        }
-    }
-    /** Test / internal: admit when open. */
     admit(msg) {
         const conversation = msg.conversation;
         if (!this.#open) {
-            this.#logger.debug(formatCompact({
-                op: 'icqq_inbound_skip',
-                reason: 'endpoint_closed',
-                endpoint: this.name,
-                id: msg.id,
-                target: `${conversation.kind}:${conversation.id}`,
-            }));
+            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;
         }
-        // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）经结构化段 / metadata 传递
         const mentioned = isIcqqBotMentioned({
-            uin: this.name,
+            uin: this.endpointName,
             content: msg.segments,
             rawMessage: msg.content,
         });
@@ -512,7 +246,7 @@ export class IcqqIpcEndpoint {
             content: msg.content,
             ...(msg.segments ? { segments: msg.segments } : {}),
             sender: msg.sender,
-            endpointId: this.name,
+            endpointId: this.endpointName,
             ...(mentioned ? { mentioned: true } : {}),
             ...(quoteId ? { replyTo: { id: String(quoteId) } } : {}),
             metadata: Object.freeze({
@@ -522,55 +256,70 @@ export class IcqqIpcEndpoint {
         }).catch((err) => {
             this.#logger.warn(formatCompact({
                 op: 'recv',
-                endpoint: this.name,
+                endpoint: this.endpointName,
                 target: `${conversation.kind}:${conversation.id}`,
                 ok: false,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
     }
-    async #refreshLists() {
-        const [flResp, glResp] = await Promise.all([
-            this.ipc.request(Actions.LIST_FRIENDS),
-            this.ipc.request(Actions.LIST_GROUPS),
-        ]);
-        this.friends.clear();
-        if (flResp.ok && Array.isArray(flResp.data)) {
-            for (const f of flResp.data) {
-                this.friends.set(f.user_id, f);
+    #bindClientEvents() {
+        const safe = (label, fn) => {
+            try {
+                fn();
             }
-        }
-        this.groups.clear();
-        if (glResp.ok && Array.isArray(glResp.data)) {
-            for (const g of glResp.data) {
-                this.groups.set(g.group_id, g);
+            catch (error) {
+                this.#logger.warn(formatCompact({
+                    op: 'icqq_event_handler',
+                    endpoint: this.endpointName,
+                    event: label,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
             }
-        }
+        };
+        this.on('message.private', (event) => safe('message.private', () => this.#handleMessageEvent('message.private', event)));
+        this.on('message.group', (event) => safe('message.group', () => this.#handleMessageEvent('message.group', event)));
+        this.on('message.guild', (event) => safe('message.guild', () => this.#handleGuildEvent(event)));
+        this.on('request.friend', (event) => safe('request.friend', () => this.#recordInboxRequest(serializeIcqqEvent(event))));
+        this.on('request.group', (event) => safe('request.group', () => this.#recordInboxRequest(serializeIcqqEvent(event))));
+        this.on('notice.friend', (event) => safe('notice.friend', () => this.#recordInboxNotice(serializeIcqqEvent(event))));
+        this.on('notice.group', (event) => safe('notice.group', () => this.#recordInboxNotice(serializeIcqqEvent(event))));
+        this.on('system.offline', (event) => this.#logSystemEvent('offline', event));
+        this.on('system.offline.network', (event) => this.#logSystemEvent('offline.network', event));
+        this.on('system.offline.kickoff', (event) => this.#logSystemEvent('offline.kickoff', event));
+        this.on('system.login.qrcode', () => {
+            this.#logger.info('icqq 收到二维码登录事件，请按 icqq 默认流程扫码后继续登录');
+        });
+        this.on('system.login.device', (event) => this.#logSystemEvent('login.device', event));
+        this.on('system.login.slider', (event) => this.#logSystemEvent('login.slider', event));
+        this.on('system.login.error', (event) => this.#logSystemEvent('login.error', event));
+        this.on('system.login.auth', (event) => this.#logSystemEvent('login.auth', event));
+    }
+    #logSystemEvent(type, event) {
+        const payload = serializeIcqqEvent(event);
+        this.#logger.warn(formatCompact({
+            op: `system.${type}`,
+            endpoint: this.endpointName,
+            ...(payload ? { event: JSON.stringify(payload) } : {}),
+        }));
     }
-    #handleEvent(event) {
-        if (isIcqqGuildIpcEvent(event.event)) {
-            this.#handleGuildEvent(event);
-            return;
-        }
-        const payload = unwrapIcqqIpcEventPayload(event);
-        if (!payload || typeof payload !== 'object')
-            return;
-        if (isIcqqRequestPayload(payload)) {
-            this.#recordInboxRequest(payload);
-            return;
-        }
-        if (isIcqqNoticePayload(payload)) {
-            this.#recordInboxNotice(payload);
+    #handleMessageEvent(eventName, event) {
+        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;
         }
-        if (!isIcqqMessagePostType(payload))
-            return;
         const data = payload;
         if (shouldSkipSelfInboundMessage(data)) {
             this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'self',
-                endpoint: this.name,
+                endpoint: this.endpointName,
                 user_id: data.user_id,
                 self_id: data.self_id,
             }));
@@ -581,9 +330,9 @@ export class IcqqIpcEndpoint {
             this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'normalize_failed',
-                endpoint: this.name,
+                endpoint: this.endpointName,
+                event: eventName,
                 message_id: data.message_id,
-                message_type: data.message_type ?? data.type,
             }));
             return;
         }
@@ -591,7 +340,7 @@ export class IcqqIpcEndpoint {
             this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'dedupe',
-                endpoint: this.name,
+                endpoint: this.endpointName,
                 id: normalized.messageId,
             }));
             return;
@@ -618,7 +367,7 @@ export class IcqqIpcEndpoint {
         });
     }
     #handleGuildEvent(event) {
-        const payload = event.data;
+        const payload = serializeIcqqEvent(event);
         if (!payload || typeof payload !== 'object')
             return;
         const normalized = normalizeIcqqGuildInboundMessage(payload);
@@ -626,7 +375,7 @@ export class IcqqIpcEndpoint {
             this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'guild_normalize_failed',
-                endpoint: this.name,
+                endpoint: this.endpointName,
             }));
             return;
         }
@@ -635,7 +384,7 @@ export class IcqqIpcEndpoint {
             this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'dedupe',
-                endpoint: this.name,
+                endpoint: this.endpointName,
                 id: `guild:${normalized.messageId}`,
             }));
             return;
@@ -657,12 +406,9 @@ export class IcqqIpcEndpoint {
             },
         });
     }
-    /** 收件箱行公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
-    #inboxBase() {
-        const id = String(this.#options.id);
-        return { adapter: id.split('\0').pop() ?? id, endpointKey: this.name };
-    }
     #recordInboxRequest(payload) {
+        if (!payload || !isIcqqRequestPayload(payload))
+            return;
         const hooks = this.#options.inbox;
         if (!hooks)
             return;
@@ -675,6 +421,8 @@ export class IcqqIpcEndpoint {
         hooks.publish?.('endpoint:request', row);
     }
     #recordInboxNotice(payload) {
+        if (!payload || !isIcqqNoticePayload(payload))
+            return;
         const hooks = this.#options.inbox;
         if (!hooks)
             return;
@@ -686,24 +434,30 @@ export class IcqqIpcEndpoint {
         void hooks.recordNotice(row);
         hooks.publish?.('endpoint:notice', row);
     }
-    /** 启动/重连后首拉 GET_SYSTEM_MSG：补录离线期间的好友/群待处理请求。 */
+    #inboxBase() {
+        const id = String(this.#options.id);
+        return { adapter: id.split('\0').pop() ?? id, endpointKey: this.endpointName };
+    }
     async #pullPendingSystemMessages() {
         const hooks = this.#options.inbox;
-        if (!hooks || !this.ipc)
+        if (!hooks)
             return;
         try {
-            const resp = await this.ipc.request(Actions.GET_SYSTEM_MSG);
-            if (!resp.ok)
-                return;
-            const data = resp.data;
+            const messages = await this.getSystemMsg();
+            const friendRequests = [];
+            const groupRequests = [];
+            for (const msg of messages) {
+                if (msg.request_type === 'friend') {
+                    friendRequests.push(msg);
+                }
+                else {
+                    groupRequests.push(msg);
+                }
+            }
             const base = this.#inboxBase();
             const rows = [
-                ...(Array.isArray(data?.friendRequests)
-                    ? data.friendRequests.map((m) => buildIcqqSystemRequestRow(m, 'friend', base))
-                    : []),
-                ...(Array.isArray(data?.groupRequests)
-                    ? data.groupRequests.map((m) => buildIcqqSystemRequestRow(m, 'group', base))
-                    : []),
+                ...friendRequests.map((m) => buildIcqqSystemRequestRow(m, 'friend', base)),
+                ...groupRequests.map((m) => buildIcqqSystemRequestRow(m, 'group', base)),
             ];
             for (const row of rows) {
                 if (!row)
@@ -717,17 +471,94 @@ export class IcqqIpcEndpoint {
         catch (error) {
             this.#logger.debug(formatCompact({
                 op: 'inbox_pull_system_msg',
-                endpoint: this.name,
+                endpoint: this.endpointName,
                 error: error instanceof Error ? error.message : String(error),
             }));
         }
     }
+    async #approveRequest(id, remark) {
+        const messages = await this.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.setFriendAddRequest(target.flag, true, remark);
+        }
+        else {
+            await this.setGroupAddRequest(target.flag, true);
+        }
+    }
+    async #rejectRequest(id, reason) {
+        const messages = await this.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.setFriendAddRequest(target.flag, false);
+        }
+        else {
+            await this.setGroupAddRequest(target.flag, false, reason);
+        }
+    }
+}
+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,
+    };
 }
-/**
- * 组装入站 metadata：在基础字段上补充 quote 链路信息。
- * - quote_id：被引用消息 id（resolveIcqqQuoteIdFromEvent，无则不写）
- * - quote_sender_id / quote_sender_name / quote_content：source 可用时的平铺摘要
- */
 function buildIcqqQuoteMetadata(data, base) {
     const metadata = { ...base };
     const quoteId = resolveIcqqQuoteIdFromEvent(data);
@@ -751,18 +582,28 @@ function buildIcqqQuoteMetadata(data, base) {
         metadata.quote_content = quoteText;
     return metadata;
 }
-/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
-function toNumericId(value, label) {
-    const n = Number(value);
-    if (!Number.isFinite(n) || String(value).trim() === '') {
-        throw new TypeError(`icqq ${label} 必须是数字: ${String(value)}`);
+const INBOUND_HOLD_LIMIT = 32;
+const ICQQ_SERIALIZE_SKIP = ['group', 'member', 'friend', 'discuss', 'client'];
+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，不能当回退 */
+        }
     }
-    return n;
-}
-async function defaultCreateIpc(config) {
-    const uin = Number(config.id);
-    if (config.rpc) {
-        return IpcClient.connectRpc(config.rpc);
+    const out = {};
+    for (const [key, value] of Object.entries(event)) {
+        if (typeof value === 'function' || ICQQ_SERIALIZE_SKIP.includes(key))
+            continue;
+        out[key] = value;
     }
-    return IpcClient.connect(uin);
+    return Object.keys(out).length > 0 ? out : null;
 }