@zhin.js/adapter-icqq 6.0.2 → 7.0.0

package/lib/endpoint.js

@@ -0,0 +1,715 @@
+import { formatCompact, getLogger } 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 { buildIcqqInboxNoticeRow, buildIcqqInboxRequestRow, buildIcqqSystemRequestRow, isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
+import { IcqqGuildCatalog, isIcqqGuildIpcEvent, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
+import { IpcClient } from './ipc-client.js';
+import { materializeOutboundBase64, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
+import { Actions, formatInboundContent, formatInboundTarget, formatOutboundBody, parseSendTarget, } from './protocol.js';
+const logger = getLogger('icqq');
+export class IcqqIpcEndpoint {
+    #options;
+    #createIpc;
+    name;
+    /** Populated after start(); agent tools read this. */
+    ipc;
+    friends = new Map();
+    groups = new Map();
+    #guildCatalog = new IcqqGuildCatalog();
+    management = Object.freeze({
+        listFriends: () => this.getFriendList(),
+        listGroups: () => this.getGroupList(),
+        listChannels: async () => {
+            await this.#guildCatalog.syncAll(this.ipc);
+            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),
+    });
+    #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) {
+        this.#options = options;
+        this.name = options.config.name;
+        this.#createIpc = options.createIpc ?? defaultCreateIpc;
+    }
+    async request(action, params) {
+        if (!this.ipc) {
+            throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发起请求: ${action}`);
+        }
+        return this.ipc.request(action, params);
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#intentionalDisconnect = false;
+        try {
+            await this.#bindIpcSession();
+            this.#unregisterAgent = registerIcqqAgentEndpoint(this.name, this);
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.name,
+                mode: this.#options.config.rpc ? 'rpc' : 'ipc',
+                friends: this.friends.size,
+                groups: this.groups.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.
+            logger.debug(`Failed to connect ICQQ IPC: ${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 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+                disconnectLog(formatCompact({
+                    op: 'disconnect',
+                    endpoint: this.name,
+                    ok: false,
+                    delay_ms: delayMs,
+                    attempt: attempt + 1,
+                }));
+                await new Promise((r) => setTimeout(r, delayMs));
+                if (this.#intentionalDisconnect)
+                    break;
+                try {
+                    await this.#bindIpcSession();
+                    logger.info(formatCompact({
+                        op: 'reconnect',
+                        endpoint: this.name,
+                        ok: true,
+                        attempts: attempt + 1,
+                        friends: this.friends.size,
+                        groups: this.groups.size,
+                    }));
+                    break;
+                }
+                catch (error) {
+                    const retryLog = attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(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;
+    }
+    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.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#inboundDeduper.clear();
+        this.#inboxDeduper.clear();
+        this.friends.clear();
+        this.groups.clear();
+        this.#guildCatalog.clear();
+        try {
+            this.ipc?.close();
+        }
+        catch {
+            /* ignore */
+        }
+        // 置空 ipc：start 前 / stop 后的 request() 走防御性报错而非 TypeError
+        this.ipc = undefined;
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
+    }
+    async send({ target, payload }) {
+        if (!this.ipc) {
+            throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发送消息`);
+        }
+        const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
+        const content = Array.isArray(payload)
+            ? materializeOutboundBase64(payload, mediaMode)
+            : payload;
+        const message = formatOutboundBody(content);
+        const parsed = parseSendTarget(target);
+        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) {
+            throw new Error(`发送消息失败: ${resp.error}`);
+        }
+        const messageId = String(resp.data?.message_id ?? `sent_${Date.now()}`);
+        logger.debug(formatCompact({
+            op: 'icqq_send',
+            endpoint: this.name,
+            target,
+            messageId,
+        }));
+        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) {
+        try {
+            const emojiId = this.getEmojiId(emoji);
+            const resp = await this.request(Actions.GROUP_SET_REACTION, {
+                message_id: messageId,
+                id: emojiId,
+            });
+            if (!resp.ok) {
+                logger.warn(formatCompact({
+                    op: 'add_reaction',
+                    endpoint: this.name,
+                    message_id: messageId,
+                    emoji,
+                    id: emojiId,
+                    ok: false,
+                    error: resp.error,
+                }));
+                return null;
+            }
+            logger.debug(formatCompact({
+                op: 'add_reaction',
+                endpoint: this.name,
+                message_id: messageId,
+                emoji,
+                id: emojiId,
+                ok: true,
+            }));
+            return emojiId;
+        }
+        catch (error) {
+            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) {
+                logger.warn(formatCompact({
+                    op: 'remove_reaction',
+                    endpoint: this.name,
+                    message_id: messageId,
+                    reaction_id: reactionId,
+                    id: emojiId,
+                    ok: false,
+                    error: resp.error,
+                }));
+                return;
+            }
+            logger.debug(formatCompact({
+                op: 'remove_reaction',
+                endpoint: this.name,
+                message_id: messageId,
+                reaction_id: reactionId,
+                id: emojiId,
+                ok: true,
+            }));
+        }
+        catch (error) {
+            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) {
+                logger.warn(formatCompact({
+                    op: 'recall_message',
+                    endpoint: this.name,
+                    message_id: messageId,
+                    ok: false,
+                    error: resp.error,
+                }));
+                return;
+            }
+            logger.debug(formatCompact({
+                op: 'recall_message',
+                endpoint: this.name,
+                message_id: messageId,
+                ok: true,
+            }));
+        }
+        catch (error) {
+            logger.warn(formatCompact({
+                op: 'recall_message',
+                endpoint: this.name,
+                message_id: messageId,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    // ── 社交/群管（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) {
+        if (!this.#open)
+            return;
+        // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）只能经 metadata 传递
+        const mentioned = isIcqqBotMentioned({ uin: this.name, rawMessage: msg.content });
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target: msg.target,
+            content: msg.content,
+            sender: msg.sender,
+            id: msg.id,
+            metadata: Object.freeze({
+                endpoint: this.name,
+                channelType: msg.channelType,
+                ...msg.metadata,
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'icqq_gateway_receive_failed',
+                target: msg.target,
+                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);
+            }
+        }
+        this.groups.clear();
+        if (glResp.ok && Array.isArray(glResp.data)) {
+            for (const g of glResp.data) {
+                this.groups.set(g.group_id, g);
+            }
+        }
+    }
+    #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);
+            return;
+        }
+        if (!isIcqqMessagePostType(payload))
+            return;
+        const data = payload;
+        if (shouldSkipSelfInboundMessage(data))
+            return;
+        const normalized = normalizeIcqqInboundMessage(data);
+        if (!normalized)
+            return;
+        if (!this.#inboundDeduper.shouldProcess(normalized.messageId))
+            return;
+        this.admit({
+            id: normalized.messageId,
+            target: formatInboundTarget({
+                channelType: normalized.channelType,
+                channelId: normalized.channelId,
+                channelParentGroupId: normalized.channelParentGroupId,
+            }),
+            content: formatInboundContent(normalized.rawMessage),
+            sender: normalized.userId,
+            channelType: normalized.channelType,
+            metadata: buildIcqqQuoteMetadata(data, {
+                nickname: normalized.nickname,
+                senderRole: normalized.senderRole,
+            }),
+        });
+    }
+    #handleGuildEvent(event) {
+        const payload = event.data;
+        if (!payload || typeof payload !== 'object')
+            return;
+        const normalized = normalizeIcqqGuildInboundMessage(payload);
+        if (!normalized)
+            return;
+        this.#guildCatalog.upsertFromInbound(normalized.raw);
+        if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`))
+            return;
+        this.admit({
+            id: normalized.messageId,
+            target: formatInboundTarget({
+                channelType: 'channel',
+                channelId: normalized.channelId,
+                guildId: normalized.guildId,
+            }),
+            content: formatInboundContent(normalized.rawMessage),
+            sender: normalized.userId,
+            channelType: 'channel',
+            metadata: {
+                guildId: normalized.guildId,
+                nickname: normalized.nickname,
+            },
+        });
+    }
+    /** 收件箱行公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
+    #inboxBase() {
+        const id = String(this.#options.id);
+        return { adapter: id.split('\0').pop() ?? id, endpointId: this.name };
+    }
+    #recordInboxRequest(payload) {
+        const hooks = this.#options.inbox;
+        if (!hooks)
+            return;
+        const row = buildIcqqInboxRequestRow(payload, this.#inboxBase());
+        if (!row)
+            return;
+        if (!this.#inboxDeduper.shouldProcess(`request:${String(row.platform_request_id)}`))
+            return;
+        void hooks.recordRequest(row);
+        hooks.publish?.('endpoint:request', row);
+    }
+    #recordInboxNotice(payload) {
+        const hooks = this.#options.inbox;
+        if (!hooks)
+            return;
+        const row = buildIcqqInboxNoticeRow(payload, this.#inboxBase());
+        if (!row)
+            return;
+        if (!this.#inboxDeduper.shouldProcess(`notice:${String(row.platform_notice_id)}`))
+            return;
+        void hooks.recordNotice(row);
+        hooks.publish?.('endpoint:notice', row);
+    }
+    /** 启动/重连后首拉 GET_SYSTEM_MSG：补录离线期间的好友/群待处理请求。 */
+    async #pullPendingSystemMessages() {
+        const hooks = this.#options.inbox;
+        if (!hooks || !this.ipc)
+            return;
+        try {
+            const resp = await this.ipc.request(Actions.GET_SYSTEM_MSG);
+            if (!resp.ok)
+                return;
+            const data = resp.data;
+            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))
+                    : []),
+            ];
+            for (const row of rows) {
+                if (!row)
+                    continue;
+                if (!this.#inboxDeduper.shouldProcess(`request:${String(row.platform_request_id)}`))
+                    continue;
+                void hooks.recordRequest(row);
+                hooks.publish?.('endpoint:request', row);
+            }
+        }
+        catch (error) {
+            logger.debug(formatCompact({
+                op: 'inbox_pull_system_msg',
+                endpoint: this.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+}
+/**
+ * 组装入站 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);
+    if (quoteId)
+        metadata.quote_id = quoteId;
+    const quoted = quotedPayloadFromIcqqSource(findIcqqNestedMessageSource(data));
+    if (quoted?.sender?.id)
+        metadata.quote_sender_id = quoted.sender.id;
+    if (quoted?.sender?.name)
+        metadata.quote_sender_name = quoted.sender.name;
+    const quoteText = quoted
+        ? (typeof quoted.content === 'string'
+            ? quoted.content
+            : quoted.content
+                .map((seg) => seg && typeof seg === 'object' && seg.type === 'text'
+                ? String(seg.data?.text ?? '')
+                : '')
+                .join('')).trim() || quoted.raw || ''
+        : '';
+    if (quoteText)
+        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)}`);
+    }
+    return n;
+}
+async function defaultCreateIpc(config) {
+    const uin = Number(config.name);
+    if (config.rpc) {
+        return IpcClient.connectRpc(config.rpc);
+    }
+    return IpcClient.connect(uin);
+}