@zhin.js/adapter-qq 5.0.2 → 5.0.3

package/agent/tools/member_detail.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string; user_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string }>({
   description: '获取 QQ 频道中指定成员的详细信息',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/remove_role.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string; channel_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string; channel_id: string; user_id: string; role_id: string }>({
   description: '移除成员的 QQ 频道角色',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/lib/endpoint.d.ts

@@ -0,0 +1,69 @@
+/**
+ * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
+ */
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type QqInboundMessage, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig } from './protocol.js';
+import { type CreateQqHttpBot } from './webhook.js';
+import { type CreateQqBot } from './ws.js';
+export type { CreateQqBot, QqBotTransport } from './ws.js';
+export type { CreateQqHttpBot, QqHttpBotTransport } from './webhook.js';
+export interface QqEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly config: ResolvedQqWebsocketConfig;
+    readonly createBot?: CreateQqBot;
+}
+export declare class QqWebsocketEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: QqEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a message when open. */
+    admit(msg: QqInboundMessage): void;
+    getGuilds(): Promise<unknown[]>;
+    getChannels(guildId: string): Promise<unknown[]>;
+    getChannelInfo(channelId: string): Promise<unknown>;
+    getGuildMember(guildId: string, userId: string): Promise<unknown>;
+    getGuildRoles(guildId: string): Promise<unknown[]>;
+    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
+    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+}
+export interface QqHttpEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: ResolvedQqHttpConfig;
+    readonly createBot?: CreateQqHttpBot;
+}
+/** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
+export declare class QqHttpEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: QqHttpEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    admit(msg: QqInboundMessage): void;
+    getGuilds(): Promise<unknown[]>;
+    getChannels(guildId: string): Promise<unknown[]>;
+    getChannelInfo(channelId: string): Promise<unknown>;
+    getGuildMember(guildId: string, userId: string): Promise<unknown>;
+    getGuildRoles(guildId: string): Promise<unknown[]>;
+    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
+    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+}

package/lib/endpoint.js

@@ -0,0 +1,315 @@
+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 {
+            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 (error) {
+            await this.stop();
+            logger.error('Failed to connect QQ websocket:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        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)}`);
+        }
+        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;
+        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),
+            }));
+        });
+    }
+    getGuilds() {
+        return this.#requireBot().getGuilds();
+    }
+    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);
+        });
+    }
+    #requireBot() {
+        if (!this.#bot)
+            throw new Error('QQ bot not connected');
+        return this.#bot;
+    }
+}
+/** 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;
+        this.#started = true;
+        try {
+            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) {
+            await this.stop();
+            logger.error('Failed to connect QQ HTTP receiver:', error);
+            throw error;
+        }
+    }
+    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;
+        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)}`;
+    }
+    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),
+            }));
+        });
+    }
+    getGuilds() {
+        return this.#requireBot().getGuilds();
+    }
+    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);
+    }
+    #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;
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export { formatInboundContent, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, type ParsedSendTarget, type QqAdapterConfig, type QqChannelKind, type QqInboundMessage, type QqWireSegment, type ResolvedQqConfig, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig, } from './protocol.js';
+export { QqHttpEndpoint, QqWebsocketEndpoint, type CreateQqBot, type CreateQqHttpBot, type QqBotTransport, type QqEndpointOptions, type QqHttpBotTransport, type QqHttpEndpointOptions, } from './endpoint.js';
+export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, type QqWebhookHandler, } from './webhook.js';
+export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
+export { getQqAgentDeps, registerQqAgentEndpoint, setQqAgentDeps, type QqAgentDeps, type QqAgentEndpoint, } from './qq-agent-deps.js';
+export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, registerQqPlatformPermitChecker, } from './platform-permit.js';

package/lib/index.js

@@ -0,0 +1,6 @@
+export { formatInboundContent, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, } from './protocol.js';
+export { QqHttpEndpoint, QqWebsocketEndpoint, } from './endpoint.js';
+export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, } from './webhook.js';
+export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
+export { getQqAgentDeps, registerQqAgentEndpoint, setQqAgentDeps, } from './qq-agent-deps.js';
+export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, registerQqPlatformPermitChecker, } from './platform-permit.js';

package/lib/platform-permit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
+ */
+import { type Message } from '@zhin.js/core';
+export declare function platformPermit(perm: string): string;
+export declare function qqGuildPermitResolver(logicalPerm: string): string;
+export declare function normalizeQqGuildSenderForPermit(input: {
+    roles?: string[];
+    isOwner?: boolean;
+    isAdmin?: boolean;
+}): {
+    role?: string;
+    permissions?: string[];
+};
+export declare function checkQqPlatformPermit(perm: string, message: Message<any>): boolean;
+export declare function registerQqPlatformPermitChecker(): () => void;

package/lib/{src/platform-permit.js → platform-permit.js}

@@ -1,7 +1,7 @@
 /**
  * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
  */
-import { registerPlatformPermitChecker } from 'zhin.js';
+import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'qq';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -47,4 +47,3 @@ export function checkQqPlatformPermit(perm, message) {
 export function registerQqPlatformPermitChecker() {
     return registerPlatformPermitChecker(ADAPTER, checkQqPlatformPermit);
 }
-//# sourceMappingURL=platform-permit.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,96 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface QqAdapterConfig {
+    readonly name?: string;
+    readonly appid?: string;
+    readonly secret?: string;
+    /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
+    readonly mode?: 'websocket' | 'webhook' | 'middleware';
+    readonly sandbox?: boolean;
+    readonly intents?: readonly string[];
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+    readonly webhookPath?: string;
+    readonly port?: number;
+    readonly path?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: qq`. */
+    readonly endpoints?: ReadonlyArray<{
+        readonly context?: string;
+        readonly name?: string;
+        readonly appid?: string;
+        readonly secret?: string;
+        readonly mode?: 'websocket' | 'webhook' | 'middleware';
+        readonly sandbox?: boolean;
+        readonly intents?: readonly string[];
+        readonly accessTokenUrl?: string;
+        readonly gatewayUrl?: string;
+        readonly webhookPath?: string;
+        readonly port?: number;
+        readonly path?: string;
+    }>;
+}
+export interface ResolvedQqWebsocketConfig {
+    readonly context: 'qq';
+    readonly mode: 'websocket';
+    readonly name: string;
+    readonly appid: string;
+    readonly secret: string;
+    readonly sandbox: boolean;
+    readonly intents?: readonly string[];
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+}
+export interface ResolvedQqHttpConfig {
+    readonly context: 'qq';
+    readonly mode: 'webhook' | 'middleware';
+    readonly name: string;
+    readonly appid: string;
+    readonly secret: string;
+    readonly webhookPath: string;
+    readonly sandbox: boolean;
+}
+export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
+export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';
+export interface QqInboundMessage {
+    readonly id: string;
+    readonly content: string;
+    readonly channelKind: QqChannelKind;
+    readonly channelId: string;
+    readonly authorId: string;
+    readonly authorName: string;
+    readonly authorRoles?: string[];
+    readonly timestamp: number;
+    readonly guildId?: string;
+    readonly rawMessage?: string;
+    /**
+     * 入站即 @ 机器人（AT_MESSAGE_CREATE 的 mentions[].bot，或群 GROUP_AT_MESSAGE_CREATE
+     * 事件本身仅 @ 时下发）。新 Runtime 纯文本 content 需经 metadata 传递。
+     */
+    readonly mentioned?: boolean;
+}
+export interface QqWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface ParsedSendTarget {
+    readonly kind: QqChannelKind;
+    readonly id: string;
+}
+export declare function resolveQqConfig(config?: QqAdapterConfig): ResolvedQqConfig;
+/**
+ * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ */
+export declare function formatInboundTarget(msg: QqInboundMessage): string;
+export declare function parseSendTarget(target: string): ParsedSendTarget;
+export declare function senderDisplayName(msg: QqInboundMessage): string;
+export declare function formatInboundContent(msg: QqInboundMessage): string;
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundText(payload: unknown): string;
+/** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
+export declare function resolveOutboundMessageId(result: unknown): string;

package/lib/protocol.js

@@ -0,0 +1,129 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { pickCredential } from '@zhin.js/adapter';
+export function resolveQqConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
+    const appid = pickCredential(config.appid, entry?.appid, process.env.QQ_APPID, process.env.QQ_BOT_APPID);
+    const secret = pickCredential(config.secret, entry?.secret, process.env.QQ_SECRET, process.env.QQ_BOT_SECRET);
+    if (!appid || !secret) {
+        throw new TypeError('QQ adapter requires appid + secret (plugins.<key>.appid/secret or endpoints with context: qq)');
+    }
+    const name = (typeof config.name === 'string' && config.name)
+        || (typeof entry?.name === 'string' && entry.name)
+        || process.env.QQ_BOT_NAME
+        || 'qq-bot';
+    const mode = config.mode ?? entry?.mode ?? 'websocket';
+    if (mode === 'webhook' || mode === 'middleware') {
+        const webhookPathRaw = config.webhookPath ?? entry?.webhookPath ?? '/qq/webhook';
+        const webhookPath = webhookPathRaw.startsWith('/') ? webhookPathRaw : `/${webhookPathRaw}`;
+        return {
+            context: 'qq',
+            mode,
+            name,
+            appid,
+            secret,
+            webhookPath,
+            sandbox: config.sandbox === true || entry?.sandbox === true,
+        };
+    }
+    return {
+        context: 'qq',
+        mode: 'websocket',
+        name,
+        appid,
+        secret,
+        sandbox: config.sandbox === true || entry?.sandbox === true,
+        intents: config.intents ?? entry?.intents,
+        accessTokenUrl: config.accessTokenUrl ?? entry?.accessTokenUrl,
+        gatewayUrl: config.gatewayUrl ?? entry?.gatewayUrl,
+    };
+}
+/**
+ * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ */
+export function formatInboundTarget(msg) {
+    return `${msg.channelKind}:${msg.channelId}`;
+}
+export function parseSendTarget(target) {
+    const sep = target.indexOf(':');
+    if (sep <= 0) {
+        return { kind: 'private', id: target };
+    }
+    const head = target.slice(0, sep);
+    const rest = target.slice(sep + 1);
+    if (head === 'private' || head === 'group' || head === 'channel' || head === 'direct') {
+        return { kind: head, id: rest };
+    }
+    return { kind: 'private', id: target };
+}
+export function senderDisplayName(msg) {
+    return msg.authorName || msg.authorId;
+}
+export function formatInboundContent(msg) {
+    const text = (msg.content || msg.rawMessage || '').trim();
+    return text || '(Empty message)';
+}
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundText(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    const segments = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (segments.length === 0) {
+        return payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+    }
+    return segments
+        .map((item) => {
+        if (typeof item === 'string')
+            return item;
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                return String(data.text ?? data.content ?? '');
+            case 'at': {
+                const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+                return id ? `<@!${id}>` : '';
+            }
+            case 'image':
+                return String(data.url || data.file || '');
+            case 'reply':
+                return '';
+            default:
+                return data.text != null ? String(data.text) : '';
+        }
+    })
+        .filter(Boolean)
+        .join('');
+}
+/** 从 QQ API 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);
+}