@zhin.js/adapter-kook 5.0.1 → 5.0.3

package/lib/endpoint.js

@@ -1,775 +1,299 @@
-/**
- * KOOK Endpoint 实现
- */
-import { Client, } from "kook-client";
-import { EventEmitter } from "node:events";
-import path from "path";
-import { Message, segment, expandInteractiveSegmentsInContent, } from 'zhin.js';
-import { KookPermission } from "./types.js";
-import { InboundMessageDeduper } from "./kook-inbound.js";
-import { normalizeKookSenderForPermit } from "./platform-permit.js";
-import { enrichKookGatewayForPlugins, formatKookNotice, formatKookNoticeLog, formatKookButtonClickMessage, isKookButtonClickEvent, isKookNoticeGatewayEvent, resolveKookSideEventDedupeKey, } from "./kook-side-events.js";
-import { encodeKookMsgRef, encodeKookReactionId, isKookApiGoneResult, isKookApiSuccess, isKookMsgGoneError, shouldStopDeleteAfterResponse, kookDeleteApiPath, kookReactionApiPath, parseKookMsgRef, parseKookReactionId, plainKookMsgId, resolveKookRoutes, routeFromSceneType, routeFromSendType, } from "./kook-msg-route.js";
-import { materializeOutboundMedia } from "./outbound-media.js";
-import { uploadKookAsset } from "./kook-asset-upload.js";
-import { convertToKookSendable } from "./outbound-sendable.js";
-import { fromCanonicalSegments, toCanonicalSegments } from './segment-mapper.js';
-export class KookEndpoint extends Client {
-    $config;
-    $connected = false;
-    /** KOOK 平台 user_id，用于 @ 触发匹配（resolveEndpointAtIds） */
-    $platformUserId;
-    adapter;
-    inboundDeduper = new InboundMessageDeduper();
-    onGatewayEvent = (raw) => {
-        this.handleGatewayEvent(raw);
-    };
-    /** kook-client 构造函数注入的 process 监听器，disconnect 时需移除 */
-    _kookProcessListeners = [];
-    get $id() {
-        return this.$config.name;
-    }
-    get pluginLogger() {
-        return this.adapter.plugin.logger;
-    }
-    constructor(adapter, $config) {
-        // 记录构造前 process 上的 uncaughtException 监听器数量
-        const beforeCount = process.listenerCount('uncaughtException');
-        super({
-            token: $config.token,
-            mode: "websocket", // KOOK 默认使用 WebSocket 模式
-            data_dir: $config.data_dir || path.join(process.cwd(), "data", "kook"),
-            timeout: $config.timeout || 10000,
-            max_retry: $config.max_retry || 3,
-            ignore: $config.ignore || "bot",
-            logLevel: $config.logLevel || "info",
-        });
-        this.$config = $config;
-        // 捕获 kook-client 构造函数注入的 process 监听器
-        const afterListeners = process.listeners('uncaughtException');
-        for (let i = beforeCount; i < afterListeners.length; i++) {
-            this._kookProcessListeners.push({ event: 'uncaughtException', fn: afterListeners[i] });
-        }
-        this.adapter = adapter;
-        this.setupEventListeners();
-        this.hookGatewayReceiver();
-    }
-    /**
-     * 在 kook-client Receiver transform 之前拦截原始 gateway 事件（SDK 未实现 notice transform）
-     */
-    hookGatewayReceiver() {
-        const receiver = this.receiver;
-        receiver.prependListener("event", this.onGatewayEvent);
-    }
-    handleGatewayEvent(raw) {
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerKookAgentEndpoint } from './kook-agent-deps.js';
+import { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, isKookBotMentioned, parseSendTarget, senderDisplayName, } from './protocol.js';
+import { registerKookWebhookRoutes } from './webhook.js';
+import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
+const logger = getLogger('kook');
+export class KookWebsocketEndpoint {
+    #options;
+    #createClient;
+    #client = null;
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#createClient = options.createClient ?? defaultCreateClient;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
         try {
-            const enriched = enrichKookGatewayForPlugins(raw);
-            EventEmitter.prototype.emit.call(this.adapter, "kook.gateway", enriched);
-            if (isKookButtonClickEvent(raw)) {
-                const dedupeKey = resolveKookSideEventDedupeKey(raw, "gateway");
-                if (!this.inboundDeduper.shouldProcess(dedupeKey))
-                    return;
-                const message = formatKookButtonClickMessage(raw, this.$id);
-                this.adapter.emit("message.receive", message);
-                this.pluginLogger.debug(`KOOK 按钮点击 ${message.$channel.type}(${message.$channel.id}): ${message.$raw}`);
-                return;
-            }
-            if (!isKookNoticeGatewayEvent(raw))
-                return;
-            const dedupeKey = resolveKookSideEventDedupeKey(raw, "notice");
-            if (!this.inboundDeduper.shouldProcess(dedupeKey))
-                return;
-            const notice = formatKookNotice(raw, this.$config.name);
-            this.emitSideEvent("notice.receive", notice);
-            this.pluginLogger.info(formatKookNoticeLog(notice));
+            this.#unregisterAgent = registerKookAgentEndpoint(this.#options.config.name, this);
+            this.#client = this.#createClient(this.#options.config);
+            this.#bindClient(this.#client);
+            await this.#client.connect();
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.name,
+                mode: 'websocket',
+                self_id: this.#client.self_id != null ? String(this.#client.self_id) : undefined,
+            }));
         }
         catch (error) {
-            this.pluginLogger.error("处理 KOOK gateway 事件失败:", error);
+            await this.stop();
+            logger.error('Failed to connect KOOK websocket:', error);
+            throw error;
         }
     }
-    emitSideEvent(event, payload) {
-        this.adapter.emit(event, payload);
+    open() {
+        this.#open = true;
     }
-    /**
-     * 设置事件监听器
-     */
-    setupEventListeners() {
-        // 监听消息事件
-        this.on("message", (msg) => {
-            try {
-                const message = this.$formatMessage(msg);
-                const atSegs = message.$content.filter((s) => s.type === 'at');
-                if (atSegs.length > 0) {
-                    this.pluginLogger.debug(`KOOK @解析: self_id=${this.$platformUserId ?? this.self_id ?? '?'}`
-                        + ` at=${JSON.stringify(atSegs.map((s) => s.data))}`
-                        + ` preview=${segment.raw(message.$content)}`);
-                }
-                this.pluginLogger.debug(`KOOK 格式化消息: $content=${JSON.stringify(message.$content)}, $raw=${message.$raw}`);
-                this.adapter.emit("message.receive", message);
-                // 根据消息类型触发特定事件
-                const eventMap = {
-                    private: "message.private.receive",
-                    group: "message.group.receive",
-                    channel: "message.channel.receive",
-                };
-                const specificEvent = eventMap[msg.message_type];
-                if (specificEvent) {
-                    this.adapter.emit(specificEvent, message);
-                }
-            }
-            catch (error) {
-                this.pluginLogger.error(`处理 KOOK 消息失败:`, error);
-            }
-        });
-        // 监听连接事件
-        this.on("connect", () => {
-            this.$connected = true;
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 已连接`);
-        });
-        // 监听断开事件
-        this.on("disconnect", () => {
-            this.$connected = false;
-            this.pluginLogger.warn(`KOOK Endpoint ${this.$id} 已断开`);
-        });
-        // 监听错误事件
-        this.on("error", (error) => {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 错误:`, error);
-        });
+    close() {
+        this.#open = false;
     }
-    /**
-     * 将 KOOK 消息转换为标准消息格式
-     */
-    $formatMessage(msg) {
-        const channelId = msg.message_type === "channel"
-            ? msg.channel_id
-            : msg.author_id;
-        // 获取发送者的权限信息
-        const senderInfo = this.getSenderInfo(msg);
-        // 频道消息需要获取 guild_id
-        let guildId;
-        if (msg.message_type === "channel") {
-            const channelMsg = msg;
-            // 尝试从 channel 获取 guild_id
+    async stop() {
+        this.#open = false;
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        if (this.#client) {
             try {
-                const channel = channelMsg.channel;
-                guildId = channel?.info?.guild_id;
+                this.#client.removeAllListeners();
+                await this.#client.disconnect();
             }
             catch {
-                // 如果获取失败，尝试从缓存中查找
+                /* ignore */
             }
-        }
-        const message = Message.from(msg, {
-            $id: msg.message_id.toString(),
-            $adapter: "kook",
-            $endpoint: this.$id,
-            $sender: senderInfo,
-            $channel: {
-                id: channelId.toString(),
-                type: msg.message_type === "channel" ? "channel" : "private",
-                // 频道消息包含服务器ID
-                ...(guildId ? { guild_id: guildId } : {}),
-            },
-            $content: toCanonicalSegments(this.parseMessageContent(msg.message)),
-            $raw: msg.raw_message,
-            $timestamp: msg.timestamp,
-            $recall: async () => {
-                await this.$recallMessage(message.$id, {
-                    route: msg.message_type === 'channel' ? 'channel' : 'direct',
-                });
-            },
-            $reply: async (content, quote) => {
-                const elements = Array.isArray(content) ? content : [content];
-                const finalContent = [];
-                if (quote) {
-                    finalContent.push({
-                        type: "reply",
-                        data: {
-                            id: typeof quote === "boolean" ? message.$id : quote,
-                        },
-                    });
-                }
-                finalContent.push(...elements.map(el => typeof el === 'string' ? { type: 'text', data: { text: el } } : el));
-                return await this.adapter.sendMessage({
-                    ...message.$channel,
-                    context: "kook",
-                    endpoint: this.$id,
-                    content: finalContent,
-                });
-            },
+            this.#client = null;
+        }
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const body = formatOutboundKmarkdown(payload);
+        const parsed = parseSendTarget(target);
+        const client = this.#requireClient();
+        const result = parsed.kind === 'private'
+            ? await client.sendPrivateMsg(parsed.id, body)
+            : await client.sendChannelMsg(parsed.id, body);
+        const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+        logger.debug(formatCompact({
+            op: 'kook_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        if (msg.authorBot)
+            return;
+        const target = formatInboundTarget(msg);
+        const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(msg),
+            sender: senderDisplayName(msg),
+            id: msg.id,
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                channelKind: msg.channelKind,
+                userId: msg.authorId,
+                guildId: msg.guildId,
+                roles: msg.authorRoles,
+                ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'kook_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
         });
-        return message;
-    }
-    /**
-     * 获取发送者的详细权限信息
-     */
-    getSenderInfo(msg) {
-        const authorInfo = msg.author?.info;
-        const senderInfo = {
-            id: msg.author_id.toString(),
-            name: authorInfo?.nickname || authorInfo?.username || "未知用户",
-        };
-        // 频道消息才有权限信息
-        if (msg.message_type === "channel") {
-            const channelMsg = msg;
-            // 从 author.info 中获取权限信息（如果 kook-client 提供）
-            if (authorInfo) {
-                // 尝试获取角色列表
-                senderInfo.roles = authorInfo.roles || [];
-                // 尝试获取 guild_id 并检查是否为服务器主人
-                try {
-                    const channel = channelMsg.channel;
-                    const guildId = channel?.info?.guild_id;
-                    if (guildId) {
-                        const guildInfo = this.guilds?.get(guildId);
-                        if (guildInfo) {
-                            senderInfo.isGuildOwner = guildInfo.user_id === msg.author_id;
-                        }
-                    }
-                }
-                catch {
-                    // 忽略获取失败
-                }
-                // 根据 permission 字段判断（如果有）
-                const permission = authorInfo.permission;
-                if (permission !== undefined) {
-                    senderInfo.permission = permission;
-                    senderInfo.isAdmin = permission === KookPermission.Admin ||
-                        permission === KookPermission.Owner ||
-                        permission === KookPermission.ChannelAdmin;
-                    senderInfo.isGuildOwner = senderInfo.isGuildOwner || permission === KookPermission.Owner;
-                }
-            }
-        }
-        const normalized = normalizeKookSenderForPermit(senderInfo, msg.message_type === "channel");
-        senderInfo.role = normalized.role;
-        senderInfo.permissions = normalized.permissions;
-        return senderInfo;
-    }
-    // ==================== 频道管理 API ====================
-    /**
-     * 踢出用户
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     */
-    async kickUser(guildId, userId) {
-        try {
-            const guild = this.pickGuild(guildId);
-            const result = await guild.kick(userId);
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 踢出用户 ${userId} 从服务器 ${guildId}`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 踢出用户失败:`, error);
-            throw error;
-        }
     }
-    /**
-     * 将用户加入黑名单
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     * @param remark 备注
-     * @param delMsgDays 删除消息天数（0-7）
-     */
-    async addToBlacklist(guildId, userId, remark, delMsgDays) {
-        try {
-            const member = this.pickGuildMember(guildId, userId);
-            const result = await member.addToBlackList(remark, delMsgDays);
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 将用户 ${userId} 加入黑名单（服务器 ${guildId}）`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 加入黑名单失败:`, error);
-            throw error;
-        }
+    // ── Agent tool surface ──────────────────────────────────────────────
+    async getRoleList(guildId) {
+        return this.#requireClient().pickGuild(guildId).getRoleList();
     }
-    /**
-     * 将用户从黑名单移除
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     */
-    async removeFromBlacklist(guildId, userId) {
-        try {
-            const member = this.pickGuildMember(guildId, userId);
-            const result = await member.removeFromBlackList();
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 将用户 ${userId} 从黑名单移除（服务器 ${guildId}）`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 移除黑名单失败:`, error);
-            throw error;
-        }
+    async createRole(guildId, name) {
+        return this.#requireClient().pickGuild(guildId).createRole(name);
+    }
+    async deleteRole(guildId, roleId) {
+        return this.#requireClient().pickGuild(guildId).deleteRole(roleId);
     }
-    /**
-     * 给用户授予角色
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     * @param roleId 角色ID
-     */
     async grantRole(guildId, userId, roleId) {
-        try {
-            const member = this.pickGuildMember(guildId, userId);
-            const result = await member.grant(roleId);
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 授予用户 ${userId} 角色 ${roleId}（服务器 ${guildId}）`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 授予角色失败:`, error);
-            throw error;
-        }
+        return this.#requireClient().pickGuildMember(guildId, userId).grant(roleId);
     }
-    /**
-     * 撤销用户角色
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     * @param roleId 角色ID
-     */
     async revokeRole(guildId, userId, roleId) {
-        try {
-            const member = this.pickGuildMember(guildId, userId);
-            const result = await member.revoke(roleId);
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 撤销用户 ${userId} 角色 ${roleId}（服务器 ${guildId}）`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 撤销角色失败:`, error);
-            throw error;
-        }
+        return this.#requireClient().pickGuildMember(guildId, userId).revoke(roleId);
     }
-    /**
-     * 设置用户昵称
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     * @param nickname 新昵称
-     */
-    async setNickname(guildId, userId, nickname) {
-        try {
-            const member = this.pickGuildMember(guildId, userId);
-            const result = await member.setNickname(nickname);
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 设置用户 ${userId} 昵称为 "${nickname}"（服务器 ${guildId}）`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 设置昵称失败:`, error);
-            throw error;
-        }
+    async addToBlacklist(guildId, userId, remark) {
+        return this.#requireClient().pickGuildMember(guildId, userId).addToBlackList(remark);
     }
-    /**
-     * 获取服务器角色列表
-     * @param guildId 服务器ID
-     */
-    async getRoleList(guildId) {
-        try {
-            const guild = this.pickGuild(guildId);
-            return await guild.getRoleList();
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 获取角色列表失败:`, error);
-            throw error;
-        }
+    async removeFromBlacklist(guildId, userId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).removeFromBlackList();
     }
-    /**
-     * 创建角色
-     * @param guildId 服务器ID
-     * @param name 角色名称
-     */
-    async createRole(guildId, name) {
-        try {
-            const guild = this.pickGuild(guildId);
-            const role = await guild.createRole(name);
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 创建角色 "${name}"（服务器 ${guildId}）`);
-            return role;
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 创建角色失败:`, error);
-            throw error;
-        }
+    #bindClient(client) {
+        client.on('message', (raw) => {
+            const msg = normalizeKookMessage(raw);
+            if (msg)
+                this.admit(msg);
+        });
     }
-    /**
-     * 删除角色
-     * @param guildId 服务器ID
-     * @param roleId 角色ID
-     */
-    async deleteRole(guildId, roleId) {
-        try {
-            const guild = this.pickGuild(guildId);
-            const result = await guild.deleteRole(roleId);
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 删除角色 ${roleId}（服务器 ${guildId}）`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 删除角色失败:`, error);
-            throw error;
-        }
+    #requireClient() {
+        if (!this.#client)
+            throw new Error('KOOK client not connected');
+        return this.#client;
     }
-    /**
-     * 获取服务器成员列表
-     * @param guildId 服务器ID
-     * @param channelId 可选的频道ID
-     */
-    async getGuildMembers(guildId, channelId) {
+}
+export class KookWebhookEndpoint {
+    #options;
+    #createClient;
+    #client = null;
+    #routeReleases = [];
+    #processedSn = new Set();
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#createClient = options.createClient ?? defaultCreateWebhookClient;
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    get selfId() {
+        return this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
         try {
-            return await this.getGuildUserList(guildId, channelId);
+            this.#unregisterAgent = registerKookAgentEndpoint(this.#options.config.name, this);
+            this.#client = this.#createClient(this.#options.config);
+            await this.#client.init();
+            this.#routeReleases.push(...registerKookWebhookRoutes(this.#options.http, this));
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.name,
+                mode: 'webhook',
+                path: this.#options.config.webhookPath,
+                self_id: this.#client.self_id != null ? String(this.#client.self_id) : undefined,
+            }));
         }
         catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 获取成员列表失败:`, error);
+            await this.stop();
+            logger.error('Failed to connect KOOK webhook:', error);
             throw error;
         }
     }
-    buildAtElement(userId) {
-        const id = String(userId);
-        return { type: 'at', data: { id, user_id: id, qq: id } };
-    }
-    resolveAtUserId(data) {
-        const raw = data.user_id ?? data.qq ?? data.id;
-        return raw == null ? '' : String(raw);
-    }
-    parseMarkdown(content) {
-        const elements = [];
-        // KMarkdown 图片格式: ![alt](url)
-        const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
-        // KMarkdown @提及格式: (met)userId(met) 或 @用户名
-        const mentionRegex = /\(met\)(\d+)\(met\)|@([^\s]+)/g;
-        // KMarkdown 表情格式: (emj)表情名(emj)[表情ID]
-        const emojiRegex = /\(emj\)([^(]+)\(emj\)\[([^\]]+)\]/g;
-        // KMarkdown 频道格式: (chn)channelId(chn)
-        const channelRegex = /\(chn\)(\d+)\(chn\)/g;
-        let lastIndex = 0;
-        const matches = [];
-        // 解析图片
-        let match;
-        while ((match = imageRegex.exec(content)) !== null) {
-            matches.push({
-                index: match.index,
-                length: match[0].length,
-                element: { type: "image", data: { url: match[2], alt: match[1] } }
-            });
-        }
-        // 解析 @提及
-        while ((match = mentionRegex.exec(content)) !== null) {
-            const userId = match[1] || match[2];
-            matches.push({
-                index: match.index,
-                length: match[0].length,
-                element: this.buildAtElement(userId),
-            });
-        }
-        // 解析表情
-        while ((match = emojiRegex.exec(content)) !== null) {
-            matches.push({
-                index: match.index,
-                length: match[0].length,
-                element: { type: "face", data: { id: match[2], name: match[1] } }
-            });
-        }
-        // 解析频道引用
-        while ((match = channelRegex.exec(content)) !== null) {
-            matches.push({
-                index: match.index,
-                length: match[0].length,
-                element: { type: "text", data: { text: `#频道:${match[1]}` } }
-            });
-        }
-        // 按位置排序
-        matches.sort((a, b) => a.index - b.index);
-        // 组装消息段
-        for (const match of matches) {
-            // 添加之前的文本
-            if (match.index > lastIndex) {
-                const text = content.slice(lastIndex, match.index);
-                if (text) {
-                    elements.push({ type: "text", data: { text } });
-                }
-            }
-            // 添加特殊元素
-            elements.push(match.element);
-            lastIndex = match.index + match.length;
-        }
-        // 添加剩余文本
-        if (lastIndex < content.length) {
-            const text = content.slice(lastIndex);
-            if (text) {
-                elements.push({ type: "text", data: { text } });
-            }
-        }
-        // 如果没有解析到任何特殊元素，返回纯文本
-        if (elements.length === 0) {
-            elements.push({ type: "text", data: { text: content } });
-        }
-        return elements;
-    }
-    /**
-     * 将 kook-client 的 MessageSegment[] 转换为 Zhin 的 MessageElement[]
-     */
-    parseMessageContent(segments) {
-        const elements = [];
-        for (const segment of segments) {
-            switch (segment.type) {
-                case "markdown":
-                    // 检查是否包含特殊语法，如果是纯文本则直接转换
-                    if (this.hasKMarkdownSyntax(segment.text)) {
-                        elements.push(...this.parseMarkdown(segment.text));
-                    }
-                    else {
-                        elements.push({ type: "text", data: { text: segment.text } });
-                    }
-                    break;
-                case "text":
-                    elements.push({ type: "text", data: { text: segment.text } });
-                    break;
-                case "at":
-                    elements.push(this.buildAtElement(segment.user_id));
-                    break;
-                case "image":
-                    elements.push({
-                        type: "image",
-                        data: { url: segment.url, alt: segment.title || "图片" }
-                    });
-                    break;
-                case "video":
-                    elements.push({ type: "video", data: { url: segment.url } });
-                    break;
-                case "audio":
-                    elements.push({ type: "audio", data: { url: segment.url } });
-                    break;
-                case "file":
-                    elements.push({
-                        type: "file",
-                        data: { url: segment.url, name: segment.name }
-                    });
-                    break;
-                case "reply":
-                    elements.push({ type: "reply", data: { id: segment.id } });
-                    break;
-                case "card":
-                    // Card 消息暂不支持，转为提示文本
-                    elements.push({ type: "text", data: { text: "[卡片消息]" } });
-                    break;
-                default:
-                    this.pluginLogger.warn(`未知的 KOOK 消息段类型: ${segment.type}`);
-                    break;
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#processedSn.clear();
+        if (this.#client) {
+            try {
+                this.#client.removeAllListeners();
+                await this.#client.disconnect();
             }
-        }
-        return elements.length > 0 ? elements : [{ type: "text", data: { text: "" } }];
-    }
-    /**
-     * 检查文本是否包含 KMarkdown 特殊语法
-     */
-    hasKMarkdownSyntax(text) {
-        return /!\[.*?\]\(.*?\)|\(met\)|\(emj\)|\(chn\)|@\S+/.test(text);
-    }
-    /**
-     * 连接到 KOOK
-     */
-    async $connect() {
-        try {
-            await this.connect();
-            this.$connected = true;
-            const selfId = this.self_id;
-            if (selfId != null) {
-                this.$platformUserId = String(selfId);
+            catch {
+                /* ignore */
             }
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 连接成功`
-                + (this.$platformUserId ? ` (platform_user_id=${this.$platformUserId})` : ''));
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 连接失败:`, error);
-            throw error;
-        }
+            this.#client = null;
+        }
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const body = formatOutboundKmarkdown(payload);
+        const parsed = parseSendTarget(target);
+        const client = this.#requireClient();
+        const result = parsed.kind === 'private'
+            ? await client.sendPrivateMsg(parsed.id, body)
+            : await client.sendChannelMsg(parsed.id, body);
+        const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+        logger.debug(formatCompact({
+            op: 'kook_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        if (msg.authorBot)
+            return;
+        const target = formatInboundTarget(msg);
+        const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(msg),
+            sender: senderDisplayName(msg),
+            id: msg.id,
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                channelKind: msg.channelKind,
+                userId: msg.authorId,
+                guildId: msg.guildId,
+                roles: msg.authorRoles,
+                ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'kook_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
     }
-    /**
-   * 断开连接
-   */
-    async $disconnect() {
-        try {
-            const receiver = this.receiver;
-            receiver.off("event", this.onGatewayEvent);
-            this.inboundDeduper.clear();
-            this.removeAllListeners();
-            // 移除 kook-client 构造函数注入的 process 监听器
-            for (const { event, fn } of this._kookProcessListeners) {
-                process.removeListener(event, fn);
-            }
-            this._kookProcessListeners.length = 0;
-            await this.disconnect();
-            this.$connected = false;
-            this.pluginLogger.info(`KOOK Endpoint ${this.$id} 已断开连接`);
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 断开连接失败:`, error);
-            throw error;
+    checkAndRememberSn(sn) {
+        if (this.#processedSn.has(sn))
+            return false;
+        this.#processedSn.add(sn);
+        if (this.#processedSn.size > 1024) {
+            const first = this.#processedSn.values().next().value;
+            if (first != null)
+                this.#processedSn.delete(first);
         }
+        return true;
     }
-    /**
-     * 上传媒体（覆盖 kook-client：其 FormData.append 不接受 Node Buffer）
-     */
-    async uploadMedia(data) {
-        return uploadKookAsset(this.request, data);
+    async getRoleList(guildId) {
+        return this.#requireClient().pickGuild(guildId).getRoleList();
     }
-    /**
-   * 发送消息
-   */
-    async $sendMessage(options) {
-        try {
-            const { id, type, content } = options;
-            const expanded = expandInteractiveSegmentsInContent(content);
-            const canonical = toCanonicalSegments(Array.isArray(expanded) ? expanded : [expanded]);
-            const wire = fromCanonicalSegments(canonical);
-            const elements = await materializeOutboundMedia(this, wire);
-            const kookContent = convertToKookSendable(elements, (els) => this.convertToKookFormat(els));
-            // 根据消息类型发送
-            let result;
-            if (type === "private") {
-                result = await this.sendPrivateMsg(id, kookContent);
-            }
-            else {
-                result = await this.sendChannelMsg(id, kookContent);
-            }
-            const route = routeFromSendType(type);
-            return encodeKookMsgRef(route, String(result?.msg_id ?? ''));
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 发送消息失败:`, error);
-            throw error;
-        }
+    async createRole(guildId, name) {
+        return this.#requireClient().pickGuild(guildId).createRole(name);
     }
-    /**
-     * 撤回消息。支持 `kook:channel:msgId` 出站 ref，或入站 plain msgId + route/sceneType 提示。
-     */
-    async $recallMessage(messageIdOrRef, hint) {
-        const { route: encodedRoute, msgId } = parseKookMsgRef(messageIdOrRef);
-        const routeHint = encodedRoute ?? hint?.route ?? routeFromSceneType(hint?.sceneType);
-        try {
-            await this.deleteKookMsg(msgId, routeHint);
-            this.pluginLogger.debug(`KOOK Endpoint ${this.$id} 撤回消息 (${routeHint ?? 'auto'}): ${msgId}`);
-        }
-        catch (error) {
-            this.pluginLogger.error(`KOOK Endpoint ${this.$id} 撤回消息失败:`, error);
-            throw error;
-        }
+    async deleteRole(guildId, roleId) {
+        return this.#requireClient().pickGuild(guildId).deleteRole(roleId);
     }
-    async deleteKookMsg(msgId, routeHint) {
-        const routes = resolveKookRoutes('delete', routeHint);
-        let lastError;
-        for (const route of routes) {
-            try {
-                const result = await this.request.post(kookDeleteApiPath(route), { msg_id: msgId });
-                if (shouldStopDeleteAfterResponse(result, routes.length))
-                    return;
-            }
-            catch (err) {
-                if (isKookMsgGoneError(err))
-                    return;
-                lastError = err;
-            }
-        }
-        return;
-    }
-    /**
-     * 为消息添加表情回应（TypingIndicator reaction 模式）
-     * @returns reactionId（含 channel/direct 路由），供 $removeReaction 使用
-     */
-    async $addReaction(messageId, emoji, hint) {
-        const msgId = plainKookMsgId(messageId);
-        const route = await this.mutateMsgReaction(msgId, emoji, 'add', routeFromSceneType(hint?.sceneType));
-        return encodeKookReactionId(route, msgId, emoji);
-    }
-    /** 移除本 Endpoint 在消息上的表情回应 */
-    async $removeReaction(messageId, reactionId) {
-        const { route, emoji } = parseKookReactionId(reactionId);
-        await this.mutateMsgReaction(plainKookMsgId(messageId), emoji, 'delete', route);
-    }
-    async mutateMsgReaction(msgId, emoji, action, routeHint) {
-        const routes = resolveKookRoutes(action, routeHint);
-        const body = { msg_id: msgId, emoji };
-        let lastError;
-        for (const route of routes) {
-            try {
-                const result = await this.request.post(kookReactionApiPath(route, action), body);
-                if (isKookApiSuccess(result)) {
-                    this.pluginLogger.debug(`KOOK Endpoint ${this.$id} ${action} reaction (${route}) on ${msgId}`);
-                    return route;
-                }
-                if (action === 'delete' && shouldStopDeleteAfterResponse(result, routes.length)) {
-                    const label = isKookApiGoneResult(result) ? 'already gone' : 'done';
-                    this.pluginLogger.debug(`KOOK Endpoint ${this.$id} delete reaction ${label} (${route}) on ${msgId}`);
-                    return route;
-                }
-            }
-            catch (err) {
-                if (action === 'delete' && isKookMsgGoneError(err)) {
-                    this.pluginLogger.debug(`KOOK Endpoint ${this.$id} delete reaction already gone (${route}) on ${msgId}`);
-                    return route;
-                }
-                lastError = err;
-            }
-        }
-        if (action === 'delete') {
-            this.pluginLogger.debug(`KOOK Endpoint ${this.$id} delete reaction noop on ${msgId}`);
-            return routeHint ?? 'channel';
-        }
-        throw lastError instanceof Error
-            ? lastError
-            : new Error(`KOOK ${action} reaction failed (msg_id=${msgId})`);
-    }
-    /**
-   * 将消息段转换为 KOOK KMarkdown 格式
-   * 支持：文本、图片、@提及、表情、引用等
-   */
-    convertToKookFormat(content) {
-        return content
-            .map((el) => {
-            switch (el.type) {
-                case "text":
-                    // 纯文本，转义特殊字符
-                    return el.data.text.replace(/[\\`*_{}[\]()#+\-.!]/g, '\\$&');
-                case "image":
-                    // 图片：![alt](url)
-                    return `![${el.data.alt || '图片'}](${el.data.url || el.data.file})`;
-                case "at": {
-                    const atId = this.resolveAtUserId(el.data);
-                    if (atId === 'all') {
-                        return '(met)all(met)';
-                    }
-                    return `(met)${atId}(met)`;
-                }
-                case "face":
-                    // 表情：(emj)表情名(emj)[表情ID]
-                    return `(emj)${el.data.name || 'emoji'}(emj)[${el.data.id}]`;
-                case "reply":
-                    // 引用消息（KOOK 使用 quote 参数，不在消息内容中）
-                    return "";
-                case "video":
-                    // 视频：使用链接形式
-                    return `[视频](${el.data.url || el.data.file})`;
-                case "audio":
-                    // 音频：使用链接形式
-                    return `[音频](${el.data.url || el.data.file})`;
-                case "file":
-                    // 文件：使用链接形式
-                    return `[文件: ${el.data.name || '未命名'}](${el.data.url || el.data.file})`;
-                case "link":
-                    // 链接：[文本](url)
-                    return `[${el.data.text || el.data.url}](${el.data.url})`;
-                case "bold":
-                    // 粗体：**文本**
-                    return `**${el.data.text}**`;
-                case "italic":
-                    // 斜体：*文本*
-                    return `*${el.data.text}*`;
-                case "code":
-                    // 行内代码：`代码`
-                    return `\`${el.data.text}\``;
-                case "code_block":
-                    // 代码块：```语言\n代码\n```
-                    return `\`\`\`${el.data.language || ''}\n${el.data.text}\n\`\`\``;
-                default:
-                    // 未知类型，尝试转换为文本
-                    this.pluginLogger.warn(`未知的消息段类型: ${el.type}`);
-                    return el.data.text || JSON.stringify(el.data);
-            }
-        })
-            .filter(Boolean)
-            .join("");
+    async grantRole(guildId, userId, roleId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).grant(roleId);
+    }
+    async revokeRole(guildId, userId, roleId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).revoke(roleId);
+    }
+    async addToBlacklist(guildId, userId, remark) {
+        return this.#requireClient().pickGuildMember(guildId, userId).addToBlackList(remark);
+    }
+    async removeFromBlacklist(guildId, userId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).removeFromBlackList();
+    }
+    #requireClient() {
+        if (!this.#client)
+            throw new Error('KOOK client not initialized');
+        return this.#client;
     }
 }
-//# sourceMappingURL=endpoint.js.map