@zhin.js/adapter-qq 5.0.1 → 5.0.3

package/lib/endpoint.js

@@ -1,600 +1,315 @@
-/**
- * QQ 官方 Endpoint 实现
- */
-import { Bot as QQOfficialClient, } from "qq-official-bot";
-import path from "path";
-import { formatCompact } from "@zhin.js/logger";
-import { Message, segment, } from 'zhin.js';
-import { ReceiverMode } from "./types.js";
-import { normalizeQqInboundWsPayload } from "./inbound-normalize.js";
-import { normalizeGroupAtPrefix } from "./group-at-normalize.js";
-import { SDK_VERSION, SDK_VERSION_HEADER } from "./sdk-version.js";
-import { applyCustomAuthEndpoints } from "./gateway-config.js";
-import { normalizeOutboundMarkdown, asOutboundSegments, splitReplyPrefix } from "./outbound-markdown.js";
-import { normalizeOutboundMedia } from "./outbound-media.js";
-import { fromCanonicalSegments, toCanonicalSegments } from "./segment-mapper.js";
-import { enrichCanonicalMentionNames } from "./mention-enrich.js";
-import { buildMixedMediaMessagePayload, buildQqImageUploadPayload, firstImageSegment, shouldSendTextImageMixedMedia, } from "./outbound-mixed-media.js";
-import { normalizeQqGuildSenderForPermit } from "./platform-permit.js";
-import { expandKeyboardSegmentsForQq } from "./outbound-keyboard.js";
-import { formatQqActionMessage } from "./inbound-action.js";
-/** 从 qq-official-bot SendResult / 审核回包中解析出站消息 ID */
-export function resolveOutboundMessageId(result) {
-    if (!result || typeof result !== "object") {
-        throw new Error("QQ 发送消息失败：响应为空");
-    }
-    const row = result;
-    const nested = row.data && typeof row.data === "object"
-        ? row.data
-        : undefined;
-    const audit = (row.message_audit ?? nested?.message_audit);
-    const id = row.id ?? row.message_id ?? audit?.audit_id;
-    if (id == null || id === "") {
-        const code = row.code;
-        const msg = row.message;
-        throw new Error(code != null
-            ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ""}`
-            : "QQ 发送消息失败：响应缺少消息 ID");
-    }
-    return String(id);
-}
-export class QQEndpoint extends QQOfficialClient {
-    adapter;
-    $connected = false;
-    /** 平台侧机器人 user_id，用于 @ 触发匹配 */
-    $platformUserId;
-    get pluginLogger() {
-        return this.adapter.plugin.logger;
-    }
-    get $id() {
-        return this.$config.name;
-    }
-    constructor(adapter, config) {
-        if (!config.data_dir)
-            config.data_dir = path.join(process.cwd(), "data");
-        if (config.mode === ReceiverMode.MIDDLEWARE) {
-            const mw = config;
-            if (!mw.platform) {
-                mw.platform = (mw.application ?? "koa");
-            }
-        }
-        super(config);
-        this.adapter = adapter;
-        this.$config = config;
-        this.attachSdkVersionHeader();
-        applyCustomAuthEndpoints(this, config, this.pluginLogger);
-    }
-    /** 出站 QQ API 请求附带 SDK 版本，便于平台侧日志排查 */
-    attachSdkVersionHeader() {
-        this.request.interceptors.request.use((reqConfig) => {
-            reqConfig.headers[SDK_VERSION_HEADER] = SDK_VERSION;
-            return reqConfig;
-        });
-    }
-    /** 归一化 QQ API v2 群聊字段后再交给 qq-official-bot 解析 */
-    dispatchEvent(event, wsRes) {
-        this.pluginLogger.debug({
-            op: 'inbound_ws',
-            event,
-            group: String(wsRes.d?.group_openid ?? wsRes.d?.group_id ?? '?'),
-        });
-        if (event === 'GROUP_AT_MESSAGE_CREATE' || event === 'GROUP_MESSAGE_CREATE') {
-            this.pluginLogger.info(`qq inbound ws: ${event} group=${String(wsRes.d?.group_openid ?? wsRes.d?.group_id ?? '?')}`);
-        }
-        normalizeQqInboundWsPayload(event, wsRes);
-        super.dispatchEvent(event, wsRes);
-    }
-    guildMemberCache = new Map();
-    guildOwnerCache = new Map();
-    async enrichGuildSender(message, guildId, userId) {
-        const key = `${guildId}:${userId}`;
-        const now = Date.now();
-        const cached = this.guildMemberCache.get(key);
-        if (cached && now - cached.at < 60_000) {
-            message.$sender.role = cached.role;
-            message.$sender.permissions = cached.permissions;
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerQqAgentEndpoint } from './qq-agent-deps.js';
+import { formatInboundContent, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
+import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
+import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
+const logger = getLogger('qq');
+export class QqWebsocketEndpoint {
+    #options;
+    #createBot;
+    #bot = null;
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#createBot = options.createBot ?? defaultCreateBot;
+    }
+    async start() {
+        if (this.#started)
             return;
-        }
+        this.#started = true;
         try {
-            let ownerId;
-            const ownerCached = this.guildOwnerCache.get(guildId);
-            if (ownerCached && now - ownerCached.at < 300_000) {
-                ownerId = ownerCached.ownerId;
-            }
-            else {
-                const guild = await this.getGuildInfo(guildId);
-                ownerId = guild?.owner_id?.toString?.() ?? guild?.owner?.id?.toString?.();
-                this.guildOwnerCache.set(guildId, { at: now, ownerId });
-            }
-            const member = await this.getGuildMember(guildId, userId);
-            const roleIds = Array.isArray(member?.roles)
-                ? member.roles.map((r) => typeof r === "string" ? r : r?.id ?? String(r))
-                : [];
-            const isOwner = ownerId === userId;
-            const isAdmin = !isOwner && roleIds.length > 0;
-            const normalized = normalizeQqGuildSenderForPermit({ roles: roleIds, isOwner, isAdmin });
-            const entry = {
-                at: now,
-                role: normalized.role,
-                permissions: normalized.permissions ?? [],
-            };
-            this.guildMemberCache.set(key, entry);
-            message.$sender.role = entry.role;
-            message.$sender.permissions = entry.permissions;
-        }
-        catch {
-            // 保守拒绝
-        }
-    }
-    async handleQQMessage(msg) {
-        try {
-            const message = this.$formatMessage(msg);
-            if (msg.message_type === "guild" && msg.guild_id && message.$sender.id) {
-                await this.enrichGuildSender(message, String(msg.guild_id), message.$sender.id);
-            }
-            this.adapter.emit("message.receive", message);
-            this.pluginLogger.debug(`${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`);
+            this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.name, this);
+            this.#bot = this.#createBot(this.#options.config);
+            this.#bindBot(this.#bot);
+            await this.#bot.start();
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.name,
+                mode: 'websocket',
+                appid: this.#options.config.appid,
+            }));
         }
-        catch (err) {
-            this.pluginLogger.warn(`qq format inbound failed (${msg.message_type}): ${err instanceof Error ? err.message : String(err)}`);
+        catch (error) {
+            await this.stop();
+            logger.error('Failed to connect QQ websocket:', error);
+            throw error;
         }
     }
-    async handleQQAction(event) {
-        try {
-            await event.reply(0);
-            const channel = event.notice_type === 'group'
-                ? { id: String(event.group_id), type: 'group' }
-                : event.notice_type === 'guild'
-                    ? { id: String(event.channel_id), type: 'channel' }
-                    : { id: String(event.operator_id), type: 'private' };
-            const message = formatQqActionMessage(event, {
-                endpointName: this.$config.name,
-                send: async (content) => this.adapter.sendMessage({
-                    ...channel,
-                    context: 'qq',
-                    endpoint: this.$config.name,
-                    content,
-                }),
-            });
-            await this.adapter.receiveMessageAwait(message);
-            this.pluginLogger.debug(`qq action ${message.$channel.type}(${message.$channel.id}): ${message.$raw}`);
-        }
-        catch (err) {
-            this.pluginLogger.warn(`qq format action failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
+    open() {
+        this.#open = true;
     }
-    handleGroupNotice(event, payload) {
-        this.pluginLogger.info(`qq notice ${event}: group=${payload.group_id ?? '?'} operator=${payload.operator_id ?? '?'}`);
-    }
-    async $connect() {
-        this.on("message.group", this.handleQQMessage.bind(this));
-        this.on("message.guild", this.handleQQMessage.bind(this));
-        this.on("message.private", this.handleQQMessage.bind(this));
-        this.on("notice.friend.action", this.handleQQAction.bind(this));
-        this.on("notice.group.action", this.handleQQAction.bind(this));
-        this.on("notice.guild.action", this.handleQQAction.bind(this));
-        this.on("notice.group.increase", (e) => this.handleGroupNotice('group.add_robot', e));
-        this.on("notice.group.decrease", (e) => this.handleGroupNotice('group.del_robot', e));
-        this.on("notice.group.receive_open", (e) => this.handleGroupNotice('group.msg_receive_open', e));
-        this.on("notice.group.receive_close", (e) => this.handleGroupNotice('group.msg_receive_close', e));
-        await this.start();
-        this.mountWebhookReceiver();
-        this.$connected = true;
-        try {
-            const self = await this.getSelfInfo();
-            const uid = self?.id
-                ?? self?.user_id;
-            if (uid)
-                this.$platformUserId = String(uid);
-        }
-        catch (err) {
-            this.pluginLogger.debug(`${this.$config.name} getSelfInfo failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
+    close() {
+        this.#open = false;
     }
-    async $disconnect() {
-        // Endpoint 继承自 EventEmitter，清除 $connect() 注册的所有监听器
-        this.removeAllListeners();
-        await this.stop();
-        this.$connected = false;
-    }
-    resolveWebhookPath() {
-        const raw = this.$config.webhookPath ?? "/qq/webhook";
-        return raw.startsWith("/") ? raw : `/${raw}`;
-    }
-    /**
-     * Webhook 入站：middleware（挂 host-router）或独立 HTTP 端口（qq-official-bot 内置服务）。
-     */
-    mountWebhookReceiver() {
-        const mode = this.$config.mode;
-        if (mode === ReceiverMode.MIDDLEWARE) {
-            const router = this.adapter.getRouter();
-            if (!router) {
-                throw new Error("QQ mode=middleware 需要启用 @zhin.js/host-router 插件");
+    async stop() {
+        this.#open = false;
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        if (this.#bot) {
+            try {
+                this.#bot.removeAllListeners();
+                await this.#bot.stop();
             }
-            const webhookPath = this.resolveWebhookPath();
-            const mw = this.middleware;
-            router.post(webhookPath, async (ctx) => {
-                this.pluginLogger.debug(ctx.body);
-                await mw(ctx, async () => { });
-            });
-            this.pluginLogger.info(formatCompact({
-                op: "webhook",
-                mode: "middleware",
-                path: webhookPath,
-                url: `POST ${webhookPath}`,
-                note: "无 /api 前缀；Host API 才走 /api/*",
-            }));
+            catch {
+                /* ignore */
+            }
+            this.#bot = null;
+        }
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const body = formatOutboundText(payload);
+        const parsed = parseSendTarget(target);
+        const bot = this.#requireBot();
+        let result;
+        switch (parsed.kind) {
+            case 'private':
+                result = await bot.sendPrivateMessage(parsed.id, body);
+                break;
+            case 'group':
+                result = await bot.sendGroupMessage(parsed.id, body);
+                break;
+            case 'channel':
+                result = await bot.sendGuildMessage(parsed.id, body);
+                break;
+            case 'direct':
+                if (!bot.sendDirectMessage)
+                    throw new Error('QQ direct message not supported by transport');
+                result = await bot.sendDirectMessage(parsed.id, body);
+                break;
+            default:
+                throw new Error(`unsupported QQ target kind: ${String(parsed.kind)}`);
+        }
+        const messageId = `${parsed.kind}-${parsed.id}:${resolveOutboundMessageId(result)}`;
+        logger.debug(formatCompact({
+            op: 'qq_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
             return;
-        }
-        if (mode === ReceiverMode.WEBHOOK) {
-            const cfg = this.$config;
-            this.pluginLogger.info(formatCompact({
-                op: "webhook",
-                mode: "standalone",
-                port: cfg.port,
-                path: cfg.path,
-                url: `http://127.0.0.1:${cfg.port}${cfg.path}`,
+        const target = formatInboundTarget(msg);
+        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,
+                // AT 事件本身即 @ 机器人；新 Runtime 纯文本 content 需经 metadata 传递
+                ...(msg.mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'qq_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
             }));
-        }
+        });
     }
-    toWireSendContent(content) {
-        const items = (Array.isArray(content) ? content : [content]).map((item) => typeof item === "string" ? { type: "text", data: { text: item } } : item);
-        return fromCanonicalSegments(toCanonicalSegments(items));
+    getGuilds() {
+        return this.#requireBot().getGuilds();
     }
-    $formatMessage(msg) {
-        const raw = msg;
-        if (msg.message_type === "group") {
-            if (!raw.group_id && raw.group_openid) {
-                raw.group_id = raw.group_openid;
-            }
-            if (!msg.user_id && raw.author) {
-                const uid = raw.author.member_openid ?? raw.author.user_openid ?? raw.author.id;
-                if (uid)
-                    msg.user_id = String(uid);
-            }
-        }
-        let target_id = msg.user_id;
-        if (msg.message_type === "guild")
-            target_id = msg.channel_id;
-        if (msg.message_type === "group")
-            target_id = raw.group_id ?? msg.group_id ?? "";
-        if (msg.sub_type === "direct")
-            target_id = `direct:${msg.guild_id}`;
-        let content = msg.message;
-        if (msg.message_type === "group" && Array.isArray(content)) {
-            const endpointAtIds = [this.$platformUserId, this.$config.appid]
-                .filter((id) => Boolean(id))
-                .map(String);
-            content = normalizeGroupAtPrefix(content, endpointAtIds, raw.__zhin_group_at === true);
-        }
-        if (Array.isArray(content)) {
-            content = enrichCanonicalMentionNames(toCanonicalSegments(content), this.adapter, raw.mentions);
-        }
-        const result = Message.from(msg, {
-            $id: msg.message_id?.toString(),
-            $adapter: "qq",
-            $endpoint: this.$config.name,
-            $sender: {
-                id: msg.sender.user_id?.toString(),
-                name: msg.sender.user_name?.toString(),
-            },
-            $channel: {
-                id: target_id,
-                type: msg.message_type === "guild" ? "channel" : msg.message_type,
-            },
-            $content: content,
-            $raw: msg.raw_message,
-            $timestamp: Date.now(),
-            $recall: async () => {
-                await this.$recallMessage(result.$id);
-            },
-            $reply: async (content, quote = true) => {
-                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: "qq",
-                    endpoint: this.$config.name,
-                    content,
-                });
-            },
+    getChannels(guildId) {
+        return this.#requireBot().getChannels(guildId);
+    }
+    getChannelInfo(channelId) {
+        return this.#requireBot().getChannelInfo(channelId);
+    }
+    getGuildMember(guildId, userId) {
+        return this.#requireBot().getGuildMember(guildId, userId);
+    }
+    getGuildRoles(guildId) {
+        return this.#requireBot().getGuildRoles(guildId);
+    }
+    createGuildRole(guildId, name, color) {
+        return this.#requireBot().createGuildRole(guildId, name, color);
+    }
+    addMemberRole(guildId, channelId, userId, roleId) {
+        return this.#requireBot().addMemberRole(guildId, channelId, userId, roleId);
+    }
+    removeMemberRole(guildId, channelId, userId, roleId) {
+        return this.#requireBot().removeMemberRole(guildId, channelId, userId, roleId);
+    }
+    #bindBot(bot) {
+        bindQqBotInboundEvents(bot, (raw) => {
+            const msg = normalizeQqMessage(raw);
+            if (msg)
+                this.admit(msg);
         });
-        return result;
-    }
-    async $sendMessage(options) {
-        const expanded = expandKeyboardSegmentsForQq(options.content);
-        const canonicalized = this.toWireSendContent(expanded);
-        const mediaNorm = normalizeOutboundMedia(canonicalized);
-        const markdownMode = this.$config.outboundMarkdown;
-        if ((options.type === "group" || options.type === "private")
-            && !options.id.startsWith("direct:")
-            && shouldSendTextImageMixedMedia(mediaNorm, markdownMode)) {
-            return await this.$sendTextImageMixedMedia(options, mediaNorm);
-        }
-        const content = normalizeOutboundMarkdown(mediaNorm, markdownMode);
-        switch (options.type) {
-            case "private": {
-                if (options.id.startsWith("direct:")) {
-                    const id = options.id.replace("direct:", "");
-                    const result = await this.sendDirectMessage(id, content);
-                    this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
-                    return `direct-${options.id}:${resolveOutboundMessageId(result)}`;
-                }
-                else {
-                    const result = await this.sendPrivateMessage(options.id, content);
-                    this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
-                    return `private-${options.id}:${resolveOutboundMessageId(result)}`;
-                }
-            }
-            case "group": {
-                const result = await this.sendGroupMessage(options.id, content);
-                this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
-                return `group-${options.id}:${resolveOutboundMessageId(result)}`;
-            }
-            case "channel": {
-                const result = await this.sendGuildMessage(options.id, content);
-                this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
-                return `channel-${options.id}:${resolveOutboundMessageId(result)}`;
-            }
-            default:
-                throw new Error(`unsupported channel type ${options.type}`);
-        }
     }
-    /** 内联图 + 文本：上传 file_info 后以 msg_type=7 图文混排发送（二维码等场景） */
-    async $sendTextImageMixedMedia(options, content) {
-        const endpointPath = this.resolveV2EndpointPath(options);
-        const { body } = splitReplyPrefix(asOutboundSegments(content));
-        const image = firstImageSegment(body);
-        if (!image) {
-            throw new Error("QQ 图文混排：未找到图片段");
-        }
-        const uploadPayload = buildQqImageUploadPayload(image);
-        const { data: uploadResult } = await this.request.post(`${endpointPath}/files`, { ...uploadPayload, srv_send_msg: false });
-        if (!uploadResult?.file_info) {
-            throw new Error("QQ 图文混排：图片上传未返回 file_info");
-        }
-        const messagePayload = buildMixedMediaMessagePayload(content, uploadResult.file_info);
-        const { data: result } = await this.request.post(`${endpointPath}/messages`, messagePayload);
-        this.pluginLogger.debug(`${this.$config.name} send mixed-media ${options.type}(${options.id}):${segment.raw(content)}`);
-        const idPrefix = options.type === "group" ? "group" : "private";
-        return `${idPrefix}-${options.id}:${resolveOutboundMessageId(result)}`;
-    }
-    resolveV2EndpointPath(options) {
-        switch (options.type) {
-            case "group":
-                return `/v2/groups/${options.id}`;
-            case "private":
-                return `/v2/users/${options.id}`;
-            default:
-                throw new Error(`QQ 图文混排不支持 ${options.type}`);
-        }
+    #requireBot() {
+        if (!this.#bot)
+            throw new Error('QQ bot not connected');
+        return this.#bot;
     }
-    async $recallMessage(id) {
-        if (!/^(private|group|channel|direct)-([^\:]+):(.+)$/.test(id))
-            throw new Error(`invalid message id ${id}`);
-        const match = id.match(/^(private|group|channel|direct)-([^\:]+):(.+)$/);
-        if (!match)
+}
+/** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
+export class QqHttpEndpoint {
+    #options;
+    #createBot;
+    #bot = null;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#createBot = options.createBot ?? defaultCreateHttpBot;
+    }
+    async start() {
+        if (this.#started)
             return;
-        const [, target_type, target_id, message_id] = match;
-        if (target_type === "private")
-            await this.recallPrivateMessage(target_id, message_id);
-        if (target_type === "group")
-            await this.recallGroupMessage(target_id, message_id);
-        if (target_type === "channel")
-            await this.recallGuildMessage(target_id, message_id);
-        if (target_type === "direct")
-            await this.recallDirectMessage(target_id, message_id);
-    }
-    // ==================== 频道管理 API ====================
-    /**
-     * 获取频道列表
-     */
-    async getGuilds() {
+        this.#started = true;
         try {
-            return await this.guildService.getList();
+            this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.name, this);
+            this.#setupRoutes();
+            this.#bot = this.#createBot(this.#options.config);
+            this.#bindBot(this.#bot);
+            await this.#bot.start();
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.name,
+                mode: this.#options.config.mode,
+                path: this.#options.config.webhookPath,
+            }));
         }
         catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取频道列表失败:`, error);
+            await this.stop();
+            logger.error('Failed to connect QQ HTTP receiver:', error);
             throw error;
         }
     }
-    /**
-     * 获取频道详情
-     * @param guildId 频道 ID
-     */
-    async getGuildInfo(guildId) {
-        try {
-            return await this.guildService.getInfo(guildId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取频道详情失败:`, error);
-            throw error;
-        }
+    open() {
+        this.#open = true;
     }
-    /**
-     * 获取子频道列表
-     * @param guildId 频道 ID
-     */
-    async getChannels(guildId) {
-        try {
-            return await this.channelService.getList(guildId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取子频道列表失败:`, error);
-            throw error;
-        }
+    close() {
+        this.#open = false;
     }
-    /**
-     * 获取子频道详情
-     * @param channelId 子频道 ID
-     */
-    async getChannelInfo(channelId) {
-        try {
-            return await this.channelService.getInfo(channelId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取子频道详情失败:`, error);
-            throw error;
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        if (this.#bot) {
+            try {
+                this.#bot.removeAllListeners();
+                await this.#bot.stop();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#bot = null;
+        }
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const body = formatOutboundText(payload);
+        const parsed = parseSendTarget(target);
+        const bot = this.#requireBot();
+        let result;
+        switch (parsed.kind) {
+            case 'private':
+                result = await bot.sendPrivateMessage(parsed.id, body);
+                break;
+            case 'group':
+                result = await bot.sendGroupMessage(parsed.id, body);
+                break;
+            case 'channel':
+                result = await bot.sendGuildMessage(parsed.id, body);
+                break;
+            case 'direct':
+                if (!bot.sendDirectMessage)
+                    throw new Error('QQ direct message not supported by transport');
+                result = await bot.sendDirectMessage(parsed.id, body);
+                break;
+            default:
+                throw new Error(`unsupported QQ target kind: ${String(parsed.kind)}`);
         }
+        return `${parsed.kind}-${parsed.id}:${resolveOutboundMessageId(result)}`;
     }
-    /**
-     * 获取频道成员列表
-     * @param guildId 频道 ID
-     */
-    async getGuildMembers(guildId) {
-        try {
-            return await this.memberService.getGuildMemberList(guildId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取频道成员列表失败:`, error);
-            throw error;
-        }
+    admit(msg) {
+        if (!this.#open)
+            return;
+        const target = formatInboundTarget(msg);
+        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,
+                // AT 事件本身即 @ 机器人；新 Runtime 纯文本 content 需经 metadata 传递
+                ...(msg.mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'qq_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
     }
-    /**
-     * 获取频道成员详情
-     * @param guildId 频道 ID
-     * @param userId 用户 ID
-     */
-    async getGuildMember(guildId, userId) {
-        try {
-            return await this.memberService.getGuildMemberInfo(guildId, userId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取成员详情失败:`, error);
-            throw error;
-        }
+    getGuilds() {
+        return this.#requireBot().getGuilds();
     }
-    /**
-     * 删除频道成员（踢出）
-     * @param guildId 频道 ID
-     * @param userId 用户 ID
-     * @param addBlacklist 是否加入黑名单
-     * @param deleteHistoryMsg 删除历史消息天数 (-1不删除，0全部删除，3/7/15/30)
-     */
-    async removeGuildMember(guildId, userId, addBlacklist, deleteHistoryMsg) {
-        try {
-            await this.memberService.kickMember(guildId, userId, deleteHistoryMsg, addBlacklist);
-            this.pluginLogger.info(`QQ Endpoint ${this.$id} 踢出成员 ${userId}（频道 ${guildId}）`);
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 踢出成员失败:`, error);
-            throw error;
-        }
+    getChannels(guildId) {
+        return this.#requireBot().getChannels(guildId);
     }
-    /**
-     * 获取频道角色列表
-     * @param guildId 频道 ID
-     */
-    async getGuildRoles(guildId) {
-        try {
-            return await this.guildService.getRoles(guildId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取角色列表失败:`, error);
-            throw error;
-        }
+    getChannelInfo(channelId) {
+        return this.#requireBot().getChannelInfo(channelId);
     }
-    /**
-     * 创建频道角色
-     * @param guildId 频道 ID
-     * @param name 角色名
-     * @param color 颜色
-     * @param hoist 是否在成员列表中单独展示 (0 或 1)
-     */
-    async createGuildRole(guildId, name, color, hoist) {
-        try {
-            const result = await this.guildService.createRole(guildId, { name, color: color || 0, hoist: hoist ?? 0 });
-            this.pluginLogger.info(`QQ Endpoint ${this.$id} 创建角色 "${name}"（频道 ${guildId}）`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 创建角色失败:`, error);
-            throw error;
-        }
+    getGuildMember(guildId, userId) {
+        return this.#requireBot().getGuildMember(guildId, userId);
     }
-    /**
-     * 给成员添加角色
-     * @param guildId 频道 ID
-     * @param channelId 子频道 ID
-     * @param userId 用户 ID
-     * @param roleId 角色 ID
-     */
-    async addMemberRole(guildId, channelId, userId, roleId) {
-        try {
-            await this.memberService.addMemberRole(guildId, channelId, userId, roleId);
-            this.pluginLogger.info(`QQ Endpoint ${this.$id} 给成员 ${userId} 添加角色 ${roleId}（频道 ${guildId}）`);
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 添加角色失败:`, error);
-            throw error;
-        }
+    getGuildRoles(guildId) {
+        return this.#requireBot().getGuildRoles(guildId);
     }
-    /**
-     * 移除成员角色
-     * @param guildId 频道 ID
-     * @param channelId 子频道 ID
-     * @param userId 用户 ID
-     * @param roleId 角色 ID
-     */
-    async removeMemberRole(guildId, channelId, userId, roleId) {
-        try {
-            await this.memberService.removeMemberRole(guildId, channelId, userId, roleId);
-            this.pluginLogger.info(`QQ Endpoint ${this.$id} 移除成员 ${userId} 的角色 ${roleId}（频道 ${guildId}）`);
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 移除角色失败:`, error);
-            throw error;
-        }
+    createGuildRole(guildId, name, color) {
+        return this.#requireBot().createGuildRole(guildId, name, color);
     }
-    /**
-     * 禁言成员（批量）
-     * @param guildId 频道 ID
-     * @param userIds 用户 ID 列表
-     * @param muteSeconds 禁言时长（秒），0 表示解除禁言
-     */
-    async muteMembers(guildId, userIds, muteSeconds) {
-        try {
-            if (muteSeconds > 0) {
-                await this.memberService.muteMembers(guildId, userIds, muteSeconds);
-                this.pluginLogger.info(`QQ Endpoint ${this.$id} 禁言成员 ${userIds.join(',')} ${muteSeconds}秒（频道 ${guildId}）`);
-            }
-            else {
-                await this.memberService.unmuteMembers(guildId, userIds);
-                this.pluginLogger.info(`QQ Endpoint ${this.$id} 解除成员 ${userIds.join(',')} 禁言（频道 ${guildId}）`);
-            }
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 禁言操作失败:`, error);
-            throw error;
-        }
+    addMemberRole(guildId, channelId, userId, roleId) {
+        return this.#requireBot().addMemberRole(guildId, channelId, userId, roleId);
     }
-    /**
-     * 全员禁言
-     * @param guildId 频道 ID
-     * @param muteSeconds 禁言时长（秒），0 表示解除禁言
-     */
-    async muteAll(guildId, muteSeconds) {
-        try {
-            if (muteSeconds > 0) {
-                await this.guildService.mute(guildId, muteSeconds);
-                this.pluginLogger.info(`QQ Endpoint ${this.$id} 开启全员禁言（频道 ${guildId}）`);
-            }
-            else {
-                await this.guildService.unmute(guildId);
-                this.pluginLogger.info(`QQ Endpoint ${this.$id} 关闭全员禁言（频道 ${guildId}）`);
-            }
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`QQ Endpoint ${this.$id} 全员禁言操作失败:`, error);
-            throw error;
-        }
+    removeMemberRole(guildId, channelId, userId, roleId) {
+        return this.#requireBot().removeMemberRole(guildId, channelId, userId, roleId);
+    }
+    #setupRoutes() {
+        this.#routeReleases.push(...registerQqWebhookRoutes(this.#options.http, {
+            config: this.#options.config,
+            getBot: () => this.#bot,
+        }));
+    }
+    #bindBot(bot) {
+        bindQqBotInboundEvents(bot, (raw) => {
+            const msg = normalizeQqMessage(raw);
+            if (msg)
+                this.admit(msg);
+        });
+    }
+    #requireBot() {
+        if (!this.#bot)
+            throw new Error('QQ bot not connected');
+        return this.#bot;
     }
 }
-//# sourceMappingURL=endpoint.js.map