@zhin.js/adapter-qq 5.0.1 → 5.0.3

package/lib/index.d.ts

@@ -1,23 +1,6 @@
-import type { Router } from "@zhin.js/host-router";
-import { QQAdapter } from "./adapter.js";
-import { PageManager } from "@zhin.js/host-api";
-declare module "zhin.js" {
-    namespace Plugin {
-        interface Contexts {
-            web: PageManager;
-            router: Router;
-        }
-    }
-}
-declare module "zhin.js" {
-    interface Adapters {
-        qq: QQAdapter;
-    }
-}
-export * from "./types.js";
-export { QQEndpoint } from "./endpoint.js";
-export { QQAdapter } from "./adapter.js";
-export { startQqBindFlow } from "./qq-bind-flow.js";
-export * from "./qq-bind-api.js";
-export { QqEndpointManager, disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
-//# sourceMappingURL=index.d.ts.map
+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

@@ -1,375 +1,6 @@
-/**
- * QQ 官方适配器入口：类型扩展、导出、注册
- */
-import path from "node:path";
-import { usePlugin, createSceneManagementTools } from "zhin.js";
-import { QQAdapter } from "./adapter.js";
-import { platformPermit, qqGuildPermitResolver, registerQqPlatformPermitChecker, } from "./platform-permit.js";
-import { disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
-export * from "./types.js";
-export { QQEndpoint } from "./endpoint.js";
-export { QQAdapter } from "./adapter.js";
-export { startQqBindFlow } from "./qq-bind-flow.js";
-export * from "./qq-bind-api.js";
-export { QqEndpointManager, disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
-const plugin = usePlugin();
-const { provide, useContext, onDispose } = plugin;
-useContext("router", (router) => {
-    provide({
-        name: "qq",
-        description: "QQ Official Endpoint Adapter",
-        mounted: async (p) => {
-            const adapter = new QQAdapter(p, router);
-            await adapter.start();
-            return adapter;
-        },
-        dispose: async (adapter) => {
-            await adapter.stop();
-        },
-    });
-});
-useContext('tool', 'qq', (toolService, qq) => {
-    const disposers = [];
-    disposers.push(registerQqPlatformPermitChecker());
-    const sceneTools = createSceneManagementTools(qq, 'qq', { permitResolver: qqGuildPermitResolver, registerChecker: false });
-    disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
-    // 获取频道列表
-    disposers.push(toolService.addTool({
-        name: 'qq_list_guilds',
-        description: '获取 QQ 频道列表',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-            },
-            required: ['endpoint_id'],
-        },
-        platforms: ['qq'],
-        tags: ['qq'],
-        execute: async (args) => {
-            const endpoint = qq.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const guilds = await endpoint.getGuilds();
-            return { guilds, count: guilds.length };
-        },
-    }, plugin.name));
-    // 获取子频道列表
-    disposers.push(toolService.addTool({
-        name: 'qq_list_channels',
-        description: '获取 QQ 频道下的子频道列表',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '频道 ID' },
-            },
-            required: ['endpoint_id', 'guild_id'],
-        },
-        platforms: ['qq'],
-        tags: ['qq'],
-        permissions: [platformPermit('manage_channels')],
-        execute: async (args) => {
-            const endpoint = qq.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const channels = await endpoint.getChannels(args.guild_id);
-            return { channels, count: channels.length };
-        },
-    }, plugin.name));
-    // 获取角色列表
-    disposers.push(toolService.addTool({
-        name: 'qq_list_roles',
-        description: '获取 QQ 频道角色列表',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '频道 ID' },
-            },
-            required: ['endpoint_id', 'guild_id'],
-        },
-        platforms: ['qq'],
-        tags: ['qq'],
-        permissions: [platformPermit('manage_roles')],
-        execute: async (args) => {
-            const endpoint = qq.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const roles = await endpoint.getGuildRoles(args.guild_id);
-            return { roles, count: roles.length };
-        },
-    }, plugin.name));
-    // 创建角色
-    disposers.push(toolService.addTool({
-        name: 'qq_create_role',
-        description: '创建 QQ 频道角色',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '频道 ID' },
-                name: { type: 'string', description: '角色名称' },
-                color: { type: 'number', description: '颜色（RGB 十进制数值）' },
-            },
-            required: ['endpoint_id', 'guild_id', 'name'],
-        },
-        platforms: ['qq'],
-        tags: ['qq'],
-        permissions: [platformPermit('guild_owner')],
-        execute: async (args) => {
-            const endpoint = qq.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const role = await endpoint.createGuildRole(args.guild_id, args.name, args.color);
-            return { success: !!role, role, message: role ? `角色 "${args.name}" 创建成功` : '创建失败' };
-        },
-    }, plugin.name));
-    // 添加角色
-    disposers.push(toolService.addTool({
-        name: 'qq_add_role',
-        description: '给成员添加 QQ 频道角色',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '频道 ID' },
-                channel_id: { type: 'string', description: '子频道 ID' },
-                user_id: { type: 'string', description: '用户 ID' },
-                role_id: { type: 'string', description: '角色 ID' },
-            },
-            required: ['endpoint_id', 'guild_id', 'channel_id', 'user_id', 'role_id'],
-        },
-        platforms: ['qq'],
-        tags: ['qq'],
-        permissions: [platformPermit('manage_roles')],
-        execute: async (args) => {
-            const endpoint = qq.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.addMemberRole(args.guild_id, args.channel_id, args.user_id, args.role_id);
-            return { success, message: success ? '已给成员添加角色' : '操作失败' };
-        },
-    }, plugin.name));
-    // 移除角色
-    disposers.push(toolService.addTool({
-        name: 'qq_remove_role',
-        description: '移除成员的 QQ 频道角色',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '频道 ID' },
-                channel_id: { type: 'string', description: '子频道 ID' },
-                user_id: { type: 'string', description: '用户 ID' },
-                role_id: { type: 'string', description: '角色 ID' },
-            },
-            required: ['endpoint_id', 'guild_id', 'channel_id', 'user_id', 'role_id'],
-        },
-        platforms: ['qq'],
-        tags: ['qq'],
-        permissions: [platformPermit('manage_roles')],
-        execute: async (args) => {
-            const endpoint = qq.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.removeMemberRole(args.guild_id, args.channel_id, args.user_id, args.role_id);
-            return { success, message: success ? '已移除成员的角色' : '操作失败' };
-        },
-    }, plugin.name));
-    // 子频道详情
-    disposers.push(toolService.addTool({
-        name: 'qq_channel_info',
-        description: '获取 QQ 频道中指定子频道的详细信息',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                channel_id: { type: 'string', description: '子频道 ID' },
-            },
-            required: ['endpoint_id', 'channel_id'],
-        },
-        platforms: ['qq'],
-        tags: ['qq'],
-        permissions: [platformPermit('guild_admin')],
-        execute: async (args) => {
-            const endpoint = qq.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const info = await endpoint.getChannelInfo(args.channel_id);
-            return info;
-        },
-    }, plugin.name));
-    // 单成员详情
-    disposers.push(toolService.addTool({
-        name: 'qq_member_detail',
-        description: '获取 QQ 频道中指定成员的详细信息',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '频道 ID' },
-                user_id: { type: 'string', description: '用户 ID' },
-            },
-            required: ['endpoint_id', 'guild_id', 'user_id'],
-        },
-        platforms: ['qq'],
-        tags: ['qq'],
-        permissions: [platformPermit('guild_admin')],
-        execute: async (args) => {
-            const endpoint = qq.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const member = await endpoint.getGuildMember(args.guild_id, args.user_id);
-            return member;
-        },
-    }, plugin.name));
-    return () => disposers.forEach(d => d());
-});
-// ── Web 控制台 ─────────────────────────────────────────────────────────
-useContext("web", (pageManager) => {
-    pageManager.addEntry({
-        id: "qq",
-        development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-        production: path.resolve(import.meta.dirname, "../dist/index.js"),
-        meta: { name: "QQ" },
-    });
-});
-useContext("router", "qq", (router, qq) => {
-    router.get("/api/qq/endpoints", async (ctx) => {
-        try {
-            const endpoints = Array.from(qq.endpoints.values());
-            const result = await Promise.all(endpoints.map(async (endpoint) => {
-                try {
-                    let guildCount = 0;
-                    try {
-                        const guilds = await endpoint.getGuilds();
-                        guildCount = guilds?.length || 0;
-                    }
-                    catch { }
-                    return {
-                        name: endpoint.$config.name,
-                        connected: endpoint.$connected || false,
-                        guildCount,
-                        status: endpoint.$connected ? "online" : "offline",
-                    };
-                }
-                catch {
-                    return { name: endpoint.$config.name, connected: false, guildCount: 0, status: "error" };
-                }
-            }));
-            ctx.body = { success: true, data: result };
-        }
-        catch {
-            ctx.status = 500;
-            ctx.body = { success: false, error: "获取 Endpoint 数据失败" };
-        }
-    });
-    // Endpoint 连接/断开
-    router.post("/api/qq/endpoints/:name/connect", async (ctx) => {
-        try {
-            const endpoint = qq.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (endpoint.$connected) {
-                ctx.body = { success: true, message: "已经在线" };
-                return;
-            }
-            await endpoint.$connect();
-            ctx.body = { success: true, message: "连接成功" };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "连接失败" };
-        }
-    });
-    router.post("/api/qq/endpoints/:name/disconnect", async (ctx) => {
-        try {
-            const endpoint = qq.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (!endpoint.$connected) {
-                ctx.body = { success: true, message: "已经离线" };
-                return;
-            }
-            await endpoint.$disconnect();
-            ctx.body = { success: true, message: "已断开" };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "断开失败" };
-        }
-    });
-    // 频道列表（QQ 官方 API 返回 guild_id/guild_name，归一化为控制台用的 id/name）
-    router.get("/api/qq/endpoints/:name/guilds", async (ctx) => {
-        try {
-            const endpoint = qq.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (!endpoint.$connected) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "Endpoint 未连接" };
-                return;
-            }
-            const raw = await endpoint.getGuilds();
-            const guilds = (raw || []).map((g) => ({
-                id: g.guild_id ?? g.id,
-                name: g.guild_name ?? g.name,
-                icon: g.icon,
-                description: g.description,
-                memberCount: g.member_count,
-                ownerId: g.owner_id,
-                owner: g.owner,
-                joinTime: g.join_time,
-            }));
-            ctx.body = { success: true, data: guilds };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "获取频道失败" };
-        }
-    });
-    // 子频道列表（QQ 官方 API 返回 channel_id/channel_name，归一化为 id/name）
-    router.get("/api/qq/endpoints/:name/guilds/:guildId/channels", async (ctx) => {
-        try {
-            const endpoint = qq.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (!endpoint.$connected) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "Endpoint 未连接" };
-                return;
-            }
-            const raw = await endpoint.getChannels(ctx.params.guildId);
-            const channels = (raw || []).map((ch) => ({
-                id: ch.channel_id ?? ch.id,
-                name: ch.channel_name ?? ch.name,
-                type: ch.type,
-                subType: ch.sub_type,
-                position: ch.position,
-                parentId: ch.parent_id,
-            }));
-            ctx.body = { success: true, data: channels };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "获取子频道失败" };
-        }
-    });
-});
-onDispose(() => {
-    disposeQqEndpointProvision();
-});
-//# sourceMappingURL=index.js.map
+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

@@ -1,7 +1,7 @@
 /**
  * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
  */
-import type { Message } from 'zhin.js';
+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: {
@@ -14,4 +14,3 @@ export declare function normalizeQqGuildSenderForPermit(input: {
 };
 export declare function checkQqPlatformPermit(perm: string, message: Message<any>): boolean;
 export declare function registerQqPlatformPermitChecker(): () => void;
-//# sourceMappingURL=platform-permit.d.ts.map

package/lib/platform-permit.js

@@ -1,4 +1,7 @@
-import { registerPlatformPermitChecker } from 'zhin.js';
+/**
+ * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
+ */
+import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'qq';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -44,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);
+}