@zhin.js/adapter-icqq 6.0.1 → 6.0.3

package/lib/endpoint.js

@@ -1,668 +1,244 @@
-/**
- * ICQQ Bot：通过 @icqqjs/cli 守护进程 IPC 通信，实现 zhin Endpoint 接口
- *
- * 不再直接依赖 @icqqjs/icqq 协议库。
- * 登录由 `icqq login` 完成，本 Endpoint 只负责连接守护进程并收发消息。
- */
-import { formatCompact, Message, segment, expandInteractiveSegmentsInContent, } from 'zhin.js';
-import { IpcClient } from "./ipc-client.js";
-import { Actions } from "./protocol.js";
-import { findIcqqNestedMessageSource, InboundMessageDeduper, isIcqqMessagePostType, normalizeIcqqInboundMessage, quotedPayloadFromIcqqSource, resolveIcqqQuoteIdFromEvent, resolveQuoteIdFromIcqqSource, shouldSkipSelfInboundMessage, unwrapIcqqIpcEventPayload, } from "./icqq-inbound.js";
-import { buildIcqqIpcMessage as buildIcqqIpcMessageImpl, parseCqMessage as parseCqMessageImpl, toCqString as toCqStringImpl, } from "./cq-message.js";
-import { materializeOutboundBase64, resolveIcqqOutboundMediaMode, } from "./outbound-media.js";
-import { formatIcqqMetaLog, formatIcqqNotice, formatIcqqRequest, isIcqqMetaPayload, isIcqqNoticePayload, isIcqqRequestPayload, resolveIcqqEventPostType, resolveSideEventDedupeKey, shouldRefreshListsOnMeta, } from "./icqq-side-events.js";
-import { disposeIcqqLoginAssistBridge, handleIcqqLoginIpcEvent, } from "./icqq-login-assist-bridge.js";
-import { parseIcqqGetMsgResponse } from "./get-msg.js";
-import { enrichQuotedPayloadWithForward, isForwardPlaceholderPayload } from "./forward-msg.js";
-import { IcqqGuildCatalog, isIcqqGuildIpcEvent, normalizeIcqqGuildInboundMessage, } from "./icqq-guild.js";
-export class IcqqEndpoint {
-    adapter;
-    $connected = false;
-    $config;
+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 { 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();
-    /** QQ 频道（guild）子频道缓存 */
-    guildCatalog = new IcqqGuildCatalog();
-    subscriptions = [];
-    /** 事件去重：覆盖多端回流/服务端重复推送等场景 */
-    inboundDeduper = new InboundMessageDeduper();
-    /** MessageEvent.source 解析结果，供 $getMsg 优先命中 */
-    quotedSourceCache = new Map();
-    /** 用户主动断开时为 true，阻止自动重连 */
-    intentionalDisconnect = false;
+    #open = false;
+    #started = false;
+    #subscriptions = [];
+    #inboundDeduper = new InboundMessageDeduper();
+    #unregisterAgent;
+    /** 用户主动 stop 时为 true，阻止自动重连 */
+    #intentionalDisconnect = false;
     /** 是否已有重连循环在跑（避免多次 schedule 叠套） */
-    reconnectRunning = false;
-    get $id() {
-        return this.$config.name;
+    #reconnectRunning = false;
+    constructor(options) {
+        this.#options = options;
+        this.name = options.config.name;
+        this.#createIpc = options.createIpc ?? defaultCreateIpc;
     }
-    get logger() {
-        return this.adapter.plugin.logger;
-    }
-    constructor(adapter, config) {
-        this.adapter = adapter;
-        this.$config = config;
+    async request(action, params) {
+        if (!this.ipc) {
+            throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发起请求: ${action}`);
+        }
+        return this.ipc.request(action, params);
     }
-    // ── 连接 ───────────────────────────────────────────────────────────
-    async $connect() {
-        this.intentionalDisconnect = false;
-        const rpc = this.$config.rpc;
-        this.logger.debug(formatCompact({
-            connecting: this.$id,
-            mode: rpc ? "rpc" : "ipc",
-            host: rpc?.host,
-            port: rpc?.port,
-        }));
-        await this.rebindIpcSession();
-        this.logger.info(formatCompact({
-            机器人: this.$id,
-            好友数: this.friends.size,
-            群组数: this.groups.size,
-        }));
+    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 rebindIpcSession() {
-        const uin = Number(this.$config.name);
-        const rpc = this.$config.rpc;
+    async #bindIpcSession() {
         // 旧连接上的订阅句柄已失效，不再对死 socket 发 unsubscribe
-        this.subscriptions = [];
-        let client;
-        if (rpc) {
-            client = await IpcClient.connectRpc(rpc);
-        }
-        else {
-            client = await IpcClient.connect(uin);
-        }
-        if (this.intentionalDisconnect) {
-            client.close();
-            throw new Error("连接已取消");
-        }
-        this.ipc = client;
-        if (this.$config.autoReconnect !== false) {
-            this.ipc.setOnRemoteDisconnect(() => this.scheduleReconnect());
-        }
-        else {
-            this.ipc.setOnRemoteDisconnect(null);
-        }
-        await this.refreshLists();
-        // 新版 icqq cli 在认证后自动广播事件，订阅过滤改为客户端侧完成。
-        const sub = this.ipc.subscribe(Actions.SUBSCRIBE, {}, (event) => this.handleEvent(event));
-        this.subscriptions.push(sub);
-        this.$connected = true;
+        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);
     }
     /** IPC/RPC 意外断开时调度重连（指数退避） */
-    scheduleReconnect() {
-        if (this.$config.autoReconnect === false)
+    #scheduleReconnect() {
+        if (this.#options.config.autoReconnect === false)
             return;
-        if (this.intentionalDisconnect)
+        if (this.#intentionalDisconnect)
             return;
-        if (this.reconnectRunning)
+        if (this.#reconnectRunning)
             return;
-        this.reconnectRunning = true;
-        void this.runReconnectLoop();
+        this.#reconnectRunning = true;
+        void this.#runReconnectLoop();
     }
-    async runReconnectLoop() {
+    async #runReconnectLoop() {
         try {
-            for (let attempt = 0; !this.intentionalDisconnect; attempt++) {
+            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;
-                this.$connected = false;
-                this.logger.warn(formatCompact({
-                    op: "disconnect",
-                    endpoint: this.$id,
+                // 首次断开 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)
+                if (this.#intentionalDisconnect)
                     break;
                 try {
-                    await this.rebindIpcSession();
-                    this.logger.info(formatCompact({
-                        op: "reconnect",
-                        endpoint: this.$id,
+                    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 (e) {
-                    this.logger.warn(formatCompact({
-                        op: "reconnect",
-                        endpoint: this.$id,
+                catch (error) {
+                    const retryLog = attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+                    retryLog(formatCompact({
+                        op: 'reconnect',
+                        endpoint: this.name,
                         ok: false,
-                        error: e instanceof Error ? e.message : String(e),
+                        attempt: attempt + 1,
+                        error: error instanceof Error ? error.message : String(error),
                     }));
                 }
             }
         }
         finally {
-            this.reconnectRunning = false;
-        }
-    }
-    /** 刷新好友/群列表缓存 */
-    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);
-            }
+            this.#reconnectRunning = false;
         }
-        await this.guildCatalog.syncAll(this.ipc).catch((e) => {
-            this.logger.warn(formatCompact({
-                op: "sync_guilds",
-                endpoint: this.$id,
-                ok: false,
-                error: e instanceof Error ? e.message : String(e),
-            }));
-        });
     }
-    /** Console：列出 guild 子频道（含 parent.guild） */
-    getGuildChannelList() {
-        return this.guildCatalog.getGuildChannelList();
+    open() {
+        this.#open = true;
     }
-    resolveConsoleChannelNames(channelId, guildId) {
-        return this.guildCatalog.resolveConsoleChannelNames(channelId, guildId);
+    close() {
+        this.#open = false;
     }
-    // ── 断开 ───────────────────────────────────────────────────────────
-    async $disconnect() {
-        this.intentionalDisconnect = true;
+    async stop() {
+        this.#intentionalDisconnect = true;
+        this.#open = false;
         this.ipc?.setOnRemoteDisconnect(null);
-        for (const sub of this.subscriptions) {
+        for (const sub of this.#subscriptions.splice(0)) {
             await sub.unsubscribe().catch(() => { });
         }
-        this.subscriptions = [];
-        this.inboundDeduper.clear();
-        disposeIcqqLoginAssistBridge(this.$id);
-        this.ipc?.close();
-        this.$connected = false;
-        this.logger.info(formatCompact({ op: "disconnect", endpoint: this.$id }));
-    }
-    // ── 消息处理 ───────────────────────────────────────────────────────
-    handleEvent(event) {
-        if (event.event?.startsWith("system.login.")) {
-            handleIcqqLoginIpcEvent(this, event.event, event.data);
-            return;
-        }
-        if (event.event === Actions.RELOAD_GUILDS) {
-            void this.guildCatalog.syncAll(this.ipc).catch((e) => {
-                this.logger.warn(formatCompact({
-                    op: "reload_guilds",
-                    endpoint: this.$id,
-                    ok: false,
-                    error: e instanceof Error ? e.message : String(e),
-                }));
-            });
-            return;
-        }
-        if (isIcqqGuildIpcEvent(event.event)) {
-            this.handleGuildMessageEvent(event);
-            return;
-        }
-        const payload = unwrapIcqqIpcEventPayload(event);
-        if (!payload || typeof payload !== "object") {
-            if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-                this.logger.info(formatCompact({
-                    ipc_skip: "no_payload",
-                    ipc_event: event.event,
-                }));
-            }
-            return;
-        }
-        if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-            this.logger.info(formatCompact({
-                ipc_raw: JSON.stringify(payload).slice(0, 800),
-            }));
-        }
-        if (isIcqqNoticePayload(payload)) {
-            this.handleNoticeEvent(payload);
-            return;
-        }
-        if (isIcqqRequestPayload(payload)) {
-            this.handleRequestEvent(payload);
-            return;
-        }
-        if (isIcqqMetaPayload(payload)) {
-            this.handleMetaEvent(payload);
-            return;
-        }
-        if (!isIcqqMessagePostType(payload)) {
-            const postType = resolveIcqqEventPostType(payload);
-            if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-                this.logger.info(formatCompact({ ipc_skip: postType ?? "unknown_event" }));
-            }
-            return;
-        }
-        const data = payload;
-        if (shouldSkipSelfInboundMessage(data)) {
-            if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-                this.logger.info(formatCompact({ ipc_skip: "self_message" }));
-            }
-            return;
-        }
-        const normalized = normalizeIcqqInboundMessage(data);
-        if (!normalized) {
-            if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-                this.logger.info(formatCompact({ ipc_skip: "normalize_failed" }));
-            }
-            return;
-        }
-        if (!this.inboundDeduper.shouldProcess(normalized.messageId)) {
-            if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-                this.logger.info(formatCompact({ ipc_dedupe: normalized.messageId }));
-            }
-            return;
-        }
-        void this.dispatchInboundMessage(data, normalized);
-    }
-    async dispatchInboundMessage(data, normalized) {
-        this.logIpcInboundPayload(data, normalized);
-        await this.primeQuotedSourceCache(data.source ?? findIcqqNestedMessageSource(data));
-        const message = this.$formatMessage(normalized);
-        this.adapter.emit("message.receive", message);
-        this.logger.debug(`${this.$id} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}${message.$quote_id ? ` quote_id=${message.$quote_id}` : ""}`);
-    }
-    handleGuildMessageEvent(event) {
-        const payload = event.data;
-        if (!payload || typeof payload !== "object")
-            return;
-        const data = payload;
-        const normalized = normalizeIcqqGuildInboundMessage(data);
-        if (!normalized)
-            return;
-        this.guildCatalog.upsertFromInbound(data);
-        if (!this.inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
-            return;
-        }
-        void this.dispatchGuildInboundMessage(normalized);
-    }
-    async dispatchGuildInboundMessage(normalized) {
-        const message = this.$formatGuildMessage(normalized);
-        this.adapter.emit("message.receive", message);
-        this.logger.debug(`${this.$id} recv channel(${message.$channel.id}):${segment.raw(message.$content)}`);
-    }
-    $formatGuildMessage(normalized) {
-        const senderInfo = {
-            id: normalized.userId,
-            name: normalized.nickname,
-        };
-        const result = Message.from(normalized.raw, {
-            $id: normalized.messageId,
-            $adapter: "icqq",
-            $endpoint: this.$config.name,
-            $sender: senderInfo,
-            $channel: {
-                id: normalized.channelId,
-                type: "channel",
-                parent: { type: "guild", id: normalized.guildId },
-            },
-            $content: normalized.content,
-            $raw: normalized.rawMessage,
-            $timestamp: normalized.timestampMs,
-            $recall: async () => {
-                await this.$recallMessage(result.$id);
-            },
-            $reply: async (content, quote) => {
-                if (!Array.isArray(content))
-                    content = [content];
-                if (quote) {
-                    content.unshift({
-                        type: "reply",
-                        data: { id: typeof quote === "boolean" ? result.$id : quote },
-                    });
-                }
-                return await this.adapter.sendMessage({
-                    context: "icqq",
-                    endpoint: this.$config.name,
-                    id: normalized.channelId,
-                    type: "channel",
-                    parent: { type: "guild", id: normalized.guildId },
-                    content,
-                });
-            },
-        });
-        return result;
-    }
-    handleNoticeEvent(event) {
-        const dedupeKey = resolveSideEventDedupeKey(event, "notice");
-        if (!this.inboundDeduper.shouldProcess(dedupeKey)) {
-            if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-                this.logger.info(formatCompact({ ipc_dedupe: dedupeKey }));
-            }
-            return;
-        }
-        const notice = formatIcqqNotice(event, this.$config.name);
-        this.adapter.emit("notice.receive", notice);
-        this.logger.info(formatCompact({
-            notice: notice.$type,
-            channel: `${notice.$channel.type}(${notice.$channel.id})`,
-            endpoint: this.$id,
-            sub_type: notice.$subType,
-        }));
-    }
-    handleRequestEvent(event) {
-        const dedupeKey = resolveSideEventDedupeKey(event, "request");
-        if (!this.inboundDeduper.shouldProcess(dedupeKey)) {
-            if (process.env.ICQQ_IPC_LOG_RAW === "1") {
-                this.logger.info(formatCompact({ ipc_dedupe: dedupeKey }));
-            }
-            return;
-        }
-        const request = formatIcqqRequest(event, this.$config.name, this.ipc);
-        this.adapter.emit("request.receive", request);
-        this.logger.info(formatCompact({
-            request: request.$type,
-            channel: `${request.$channel.type}(${request.$channel.id})`,
-            endpoint: this.$id,
-            from: request.$sender.id,
-        }));
-    }
-    handleMetaEvent(event) {
-        const dedupeKey = resolveSideEventDedupeKey(event, "meta");
-        if (!this.inboundDeduper.shouldProcess(dedupeKey))
-            return;
-        this.logger.debug(formatIcqqMetaLog(event));
-        if (shouldRefreshListsOnMeta(event)) {
-            void this.refreshLists().catch((e) => {
-                this.logger.warn(formatCompact({
-                    op: "refresh_lists",
-                    ok: false,
-                    error: e instanceof Error ? e.message : String(e),
-                }));
-            });
-        }
-    }
-    /** 调试 IPC 入站字段：默认 debug；设 ICQQ_IPC_LOG_RAW=1 则 info 打完整 payload */
-    logIpcInboundPayload(data, normalized) {
-        const ext = data;
-        const keys = Object.keys(ext);
-        const idHints = {};
-        for (const key of keys) {
-            if (/message|msg|seq|id|source/i.test(key)) {
-                idHints[key] = ext[key];
-            }
-        }
-        const preview = JSON.stringify(data);
-        const compact = formatCompact({
-            post_type: data.post_type ?? "legacy",
-            message_type: data.message_type ?? data.type,
-            ipc_message_id: normalized.messageId,
-            id_source: normalized.idSource,
-            ipc_keys: keys.join(","),
-            ...(Object.keys(idHints).length ? { ipc_id_hints: JSON.stringify(idHints) } : {}),
-        });
-        this.logger.debug(compact);
-        this.logger.debug(formatCompact({ ipc_payload: preview.slice(0, 1200) }));
-    }
-    $formatMessage(input) {
-        const normalized = "messageId" in input
-            ? input
-            : normalizeIcqqInboundMessage(input);
-        if (!normalized) {
-            throw new Error("无法解析 icqq 入站消息");
-        }
-        const raw = normalized.raw;
-        const senderInfo = {
-            id: normalized.userId,
-            name: normalized.nickname,
-        };
-        if (normalized.senderRole && normalized.senderRole !== "member") {
-            senderInfo.role = normalized.senderRole;
-            if (normalized.senderRole === "owner") {
-                senderInfo.isOwner = true;
-                senderInfo.permissions = ["owner"];
-            }
-            else if (normalized.senderRole === "admin") {
-                senderInfo.isAdmin = true;
-                senderInfo.permissions = ["admin"];
-            }
-        }
-        const quoteId = Message.quoteIdFromContent(normalized.content) ??
-            resolveIcqqQuoteIdFromEvent(normalized.raw);
-        Message.alignReplySegments(normalized.content, quoteId);
-        const result = Message.from(raw, {
-            $id: normalized.messageId,
-            $adapter: "icqq",
-            $endpoint: this.$config.name,
-            $sender: senderInfo,
-            $channel: {
-                id: normalized.channelId,
-                type: normalized.channelType,
-                ...(normalized.channelParentGroupId
-                    ? { parent: { type: 'group', id: normalized.channelParentGroupId } }
-                    : {}),
-            },
-            $content: normalized.content,
-            $quote_id: quoteId,
-            $raw: normalized.rawMessage,
-            $timestamp: normalized.timestampMs,
-            $recall: async () => {
-                if (normalized.idSource === "synthetic") {
-                    this.logger.warn(formatCompact({
-                        op: "recall",
-                        endpoint: this.$id,
-                        ok: false,
-                        error: "no message_id in push",
-                    }));
-                    return;
-                }
-                await this.$recallMessage(result.$id);
-            },
-            $reply: async (content, quote) => {
-                if (!Array.isArray(content))
-                    content = [content];
-                if (quote) {
-                    content.unshift({
-                        type: "reply",
-                        data: { id: typeof quote === "boolean" ? result.$id : quote },
-                    });
-                }
-                return await this.adapter.sendMessage({
-                    ...result.$channel,
-                    context: "icqq",
-                    endpoint: this.$config.name,
-                    content,
-                });
-            },
-        });
-        return result;
-    }
-    /**
-     * 有 source.message_id 时用 get_msg 拉全量正文；否则仅用 source 内联摘要。
-     */
-    async primeQuotedSourceCache(source) {
-        if (!source)
-            return;
-        const quoteId = resolveQuoteIdFromIcqqSource(source);
-        const s = source;
-        const hasCanonicalId = quoteId &&
-            s.message_id != null &&
-            String(s.message_id).trim() === quoteId;
-        if (hasCanonicalId) {
-            try {
-                await this.fetchQuotedMessagePayload(quoteId);
-                return;
-            }
-            catch (e) {
-                this.logger.debug(formatCompact({
-                    op: "quote_get_msg",
-                    message_id: quoteId,
-                    ok: false,
-                    error: e instanceof Error ? e.message : String(e),
-                }));
-            }
-        }
-        const sourcePayload = quotedPayloadFromIcqqSource(source);
-        if (!sourcePayload)
-            return;
-        const enriched = await enrichQuotedPayloadWithForward(this.ipc, sourcePayload);
-        this.quotedSourceCache.set(enriched.messageId, enriched);
-    }
-    async fetchQuotedMessagePayload(messageId) {
-        const resp = await this.ipc.request(Actions.GET_MSG, {
-            message_id: messageId,
-        });
-        if (!resp.ok) {
-            throw new Error(resp.error ?? "get_msg failed");
-        }
-        const payload = parseIcqqGetMsgResponse(messageId, resp.data);
-        const enriched = await enrichQuotedPayloadWithForward(this.ipc, payload, resp.data);
-        if (isForwardPlaceholderPayload(enriched) &&
-            !String(Array.isArray(enriched.content)
-                ? segment.raw(enriched.content)
-                : enriched.content ?? "").includes("[Merged chat history")) {
-            this.logger.debug(formatCompact({
-                op: "forward_unresolved",
-                message_id: messageId,
-            }));
-        }
-        this.quotedSourceCache.set(messageId, enriched);
-        return enriched;
-    }
-    async $getMsg(messageId) {
-        const cached = this.quotedSourceCache.get(messageId);
-        if (cached) {
-            return enrichQuotedPayloadWithForward(this.ipc, cached);
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#inboundDeduper.clear();
+        this.friends.clear();
+        this.groups.clear();
+        try {
+            this.ipc?.close();
         }
-        return this.fetchQuotedMessagePayload(messageId);
-    }
-    // ── 撤回 ───────────────────────────────────────────────────────────
-    async $recallMessage(id) {
-        const resp = await this.ipc.request(Actions.RECALL_MSG, {
-            message_id: id,
-        });
-        if (!resp.ok) {
-            this.logger.warn(formatCompact({
-                op: "recall",
-                endpoint: this.$id,
-                ok: false,
-                error: resp.error,
-            }));
+        catch {
+            /* ignore */
         }
+        // 置空 ipc：start 前 / stop 后的 request() 走防御性报错而非 TypeError
+        this.ipc = undefined;
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
     }
-    // ── 发送消息 ───────────────────────────────────────────────────────
-    async $sendMessage(options) {
-        const outboundMedia = resolveIcqqOutboundMediaMode(this.$config);
-        const expanded = expandInteractiveSegmentsInContent(options.content);
-        const qrcodeContent = expanded;
-        const content = materializeOutboundBase64(qrcodeContent, outboundMedia);
-        const message = buildIcqqIpcMessageImpl(content);
+    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 (options.type) {
-            case "private": {
-                const groupParent = options.parent?.type === "group" ? options.parent.id : undefined;
-                if (groupParent) {
-                    action = Actions.SEND_TEMP_MSG;
-                    params = {
-                        group_id: Number(groupParent),
-                        user_id: Number(options.id),
-                        message,
-                    };
-                }
-                else {
-                    action = Actions.SEND_PRIVATE_MSG;
-                    params = { user_id: Number(options.id), message };
-                }
+        switch (parsed.kind) {
+            case 'private':
+                action = Actions.SEND_PRIVATE_MSG;
+                params = { user_id: parsed.userId, message };
                 break;
-            }
-            case "group":
+            case 'group':
                 action = Actions.SEND_GROUP_MSG;
-                params = { group_id: Number(options.id), message };
+                params = { group_id: parsed.groupId, message };
                 break;
-            case "channel": {
-                const guildId = options.parent?.type === "guild" ? options.parent.id : undefined;
-                if (!guildId) {
-                    throw new Error('channel 发送需要 parent: { type: "guild", id: guild_id }');
-                }
+            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: guildId,
-                    channel_id: options.id,
+                    guild_id: parsed.guildId,
+                    channel_id: parsed.channelId,
                     message,
                 };
                 break;
-            }
-            default:
-                throw new Error(`不支持的频道类型: ${options.type}`);
         }
         const resp = await this.ipc.request(action, params);
         if (!resp.ok) {
-            this.logger.debug(formatCompact({
-                op: action,
-                ...params,
-            }));
             throw new Error(`发送消息失败: ${resp.error}`);
         }
         const messageId = String(resp.data?.message_id ?? `sent_${Date.now()}`);
-        this.logger.debug(`${this.$id} send ${options.type}(${options.id}):${segment.raw(options.content)}`);
+        logger.debug(formatCompact({
+            op: 'icqq_send',
+            endpoint: this.name,
+            target,
+            messageId,
+        }));
         return messageId;
     }
-    // ── 消息回应 ───────────────────────────────────────────────────────
-    /**
-     * 表情符号到 reaction id 的映射
-     * QQ 使用数字 ID 来标识表情，而不是 Unicode 字符
-     */
+    // ── 消息回应（activity-feedback / typing reaction）────────────────────
     static EMOJI_MAP = {
-        '⏳': '1468368274', // 沙漏
-        '👍': '128077', // 竖起大拇指
-        '❤️': '10084', // 红心
-        '😊': '128522', // 微笑
-        '🎉': '127881', // 派对
-        '🔥': '128293', // 火
-        '✅': '9989', // 勾选
-        '❌': '10060', // 叉号
-        '⭐': '11088', // 星星
-        '💯': '128175', // 一百分
+        '⏳': '1468368274',
+        '👍': '128077',
+        '❤️': '10084',
+        '😊': '128522',
+        '🎉': '127881',
+        '🔥': '128293',
+        '✅': '9989',
+        '❌': '10060',
+        '⭐': '11088',
+        '💯': '128175',
     };
-    /**
-     * 将表情符号转换为 reaction id
-     */
     getEmojiId(emoji) {
-        // 如果已经是数字 ID，直接返回
-        if (/^\d+$/.test(emoji)) {
+        if (/^\d+$/u.test(emoji))
             return emoji;
-        }
-        // 从映射中查找
-        const id = IcqqEndpoint.EMOJI_MAP[emoji];
-        if (id) {
-            return id;
-        }
-        // 默认返回 Unicode 码点
-        return String(emoji.codePointAt(0) || 0);
+        return IcqqIpcEndpoint.EMOJI_MAP[emoji] ?? String(emoji.codePointAt(0) || 0);
     }
-    /**
-     * 添加消息回应（表情）
-     *
-     * @param messageId - 消息 ID
-    * @param emoji - 表情符号或 reaction id
-     * @returns 反应 ID，可用于后续移除
-     */
-    async $addReaction(messageId, emoji) {
+    /** Activity-feedback / OutboundHost reaction surface. */
+    async addReaction(messageId, emoji) {
         try {
             const emojiId = this.getEmojiId(emoji);
-            const resp = await this.ipc.request(Actions.GROUP_SET_REACTION, {
+            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.$id,
+                logger.warn(formatCompact({
+                    op: 'add_reaction',
+                    endpoint: this.name,
                     message_id: messageId,
                     emoji,
                     id: emojiId,
@@ -671,21 +247,20 @@ export class IcqqEndpoint {
                 }));
                 return null;
             }
-            this.logger.debug(formatCompact({
-                op: "add_reaction",
-                endpoint: this.$id,
+            logger.debug(formatCompact({
+                op: 'add_reaction',
+                endpoint: this.name,
                 message_id: messageId,
                 emoji,
                 id: emojiId,
                 ok: true,
             }));
-            // 返回 reaction id，供 $removeReaction 直接使用
             return emojiId;
         }
         catch (error) {
-            this.logger.warn(formatCompact({
-                op: "add_reaction",
-                endpoint: this.$id,
+            logger.warn(formatCompact({
+                op: 'add_reaction',
+                endpoint: this.name,
                 message_id: messageId,
                 emoji,
                 ok: false,
@@ -694,61 +269,215 @@ export class IcqqEndpoint {
             return null;
         }
     }
-    /**
-     * 移除消息回应
-     *
-     * @param messageId - 消息 ID
-     * @param reactionId - 反应 ID（由 $addReaction 返回）
-     */
-    async $removeReaction(messageId, reactionId) {
+    async removeReaction(messageId, reactionId) {
         try {
-            // 兼容两种格式：
-            // 1) 旧格式 reaction_{id}_{timestamp}
-            // 2) 新格式直接为 id
             const parts = reactionId.split('_');
             const emojiId = parts.length >= 2 ? parts[1] : reactionId;
-            const resp = await this.ipc.request(Actions.GROUP_DEL_REACTION, {
+            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.$id,
+                logger.warn(formatCompact({
+                    op: 'remove_reaction',
+                    endpoint: this.name,
                     message_id: messageId,
                     reaction_id: reactionId,
                     id: emojiId,
                     ok: false,
                     error: resp.error,
                 }));
+                return;
             }
-            else {
-                this.logger.debug(formatCompact({
-                    op: "remove_reaction",
-                    endpoint: this.$id,
+            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,
-                    reaction_id: reactionId,
-                    id: emojiId,
-                    ok: true,
+                    ok: false,
+                    error: resp.error,
                 }));
+                return;
             }
+            logger.debug(formatCompact({
+                op: 'recall_message',
+                endpoint: this.name,
+                message_id: messageId,
+                ok: true,
+            }));
         }
         catch (error) {
-            this.logger.warn(formatCompact({
-                op: "remove_reaction",
-                endpoint: this.$id,
+            logger.warn(formatCompact({
+                op: 'recall_message',
+                endpoint: this.name,
                 message_id: messageId,
-                reaction_id: reactionId,
                 ok: false,
                 error: error instanceof Error ? error.message : String(error),
             }));
         }
     }
+    /** 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 (!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;
+        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,
+            },
+        });
+    }
+}
+/**
+ * 组装入站 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;
+}
+async function defaultCreateIpc(config) {
+    const uin = Number(config.name);
+    if (config.rpc) {
+        return IpcClient.connectRpc(config.rpc);
+    }
+    return IpcClient.connect(uin);
 }
-/** @deprecated 使用 `./cq-message.js` 导出 */
-(function (IcqqEndpoint) {
-    IcqqEndpoint.parseCqMessage = parseCqMessageImpl;
-    IcqqEndpoint.buildIcqqIpcMessage = buildIcqqIpcMessageImpl;
-    IcqqEndpoint.toCqString = toCqStringImpl;
-})(IcqqEndpoint || (IcqqEndpoint = {}));
-//# sourceMappingURL=endpoint.js.map