@zhin.js/adapter-qq 1.1.17 → 1.1.19

package/lib/qq-send.d.ts

@@ -1,16 +1,4 @@
-/**
- * One QQ outbound send: passive reply when a usable source exists, active message otherwise, with
- * the fallbacks the platform's error codes allow. Shared by the websocket and webhook Endpoints.
- *
- * 1. Each message claims a passive source (explicit reply segment first, else the conversation's
- *    newest usable msg_id / event_id) with its own msg_seq.
- * 2. Source unusable (expired, over the limit, invalid id): mark it and send that message once as
- *    an active message. Never after a timeout: the first request may have been delivered.
- * 3. Markdown not allowed: resend the same message as plain text.
- * 4. Active message refused (no permission, quota, user switched it off): remember the conversation
- *    for a while and fail fast instead of calling the platform again.
- */
-import type { ConversationRef } from '@zhin.js/im-contract';
+import { type ConversationRef } from '@zhin.js/im-contract';
 import type { QqOutboundMessage } from './outbound.js';
 import { type QqActiveMessageGate, type QqPassiveReplyLedger, type QqReplySource } from './passive-reply.js';
 import type { QqBotTransport } from './ws.js';
@@ -20,9 +8,14 @@ export interface QqSendContext {
     readonly activeGate: QqActiveMessageGate;
     readonly log: (fields: Record<string, string | number | undefined>) => void;
 }
+export interface QqMessagesRequest {
+    readonly conversation: ConversationRef;
+    readonly messages: readonly QqOutboundMessage[];
+    readonly signal?: AbortSignal;
+}
 /** The reply segment the payload already names, as a passive source. */
 export declare function explicitReplySource(message: QqOutboundMessage): QqReplySource | undefined;
 /** Plain-text version of a Markdown message (buttons dropped); undefined when it has no Markdown. */
 export declare function markdownAsText(message: QqOutboundMessage): QqOutboundMessage | undefined;
 /** Sends every message of one delivery in order; returns the last platform result. */
-export declare function sendQqMessages(context: QqSendContext, conversation: ConversationRef, messages: readonly QqOutboundMessage[]): Promise<unknown>;
+export declare function sendQqMessages(context: QqSendContext, { conversation, messages, signal }: QqMessagesRequest): Promise<unknown>;

package/lib/qq-send.js

@@ -1,3 +1,16 @@
+/**
+ * One QQ outbound send: passive reply when a usable source exists, active message otherwise, with
+ * the fallbacks the platform's error codes allow. Shared by the websocket and webhook Endpoints.
+ *
+ * 1. Each message claims a passive source (explicit reply segment first, else the conversation's
+ *    newest usable msg_id / event_id) with its own msg_seq.
+ * 2. Source unusable (expired, over the limit, invalid id): mark it and send that message once as
+ *    an active message. Never after a timeout: the first request may have been delivered.
+ * 3. Markdown not allowed: resend the same message as plain text.
+ * 4. Active message refused (no permission, quota, user switched it off): remember the conversation
+ *    for a while and fail fast instead of calling the platform again.
+ */
+import { createEndpointOperation } from 'zhin.js/adapter';
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { QQ_ACTIVE_UNAVAILABLE_CODES, QQ_MARKDOWN_DENIED_CODES, QQ_PASSIVE_SOURCE_CODES, } from './passive-reply.js';
 import { qqDeliveryFailure } from './delivery-error.js';
@@ -39,7 +52,7 @@ export function markdownAsText(message) {
     const kept = parts.filter((part) => typeof part !== 'string' && (part.type === 'reply' || part.type === 'at'));
     return text ? [...kept, text] : undefined;
 }
-function dispatch(bot, kind, id, message, source, options) {
+function dispatch(bot, { kind, id, message, source, options }) {
     switch (kind) {
         case 'private': return bot.sendPrivateMessage(id, message, source, options);
         case 'group': return bot.sendGroupMessage(id, message, source, options);
@@ -54,14 +67,14 @@ function platformCode(error) {
     return qqDeliveryFailure(error).diagnostic.platformCode;
 }
 /** Sends one message, passive if possible; returns the platform result. */
-async function sendOne(context, kind, id, message) {
-    const passive = (body, grant) => dispatch(context.bot, kind, id, body, grant.source, { msgSeq: grant.msgSeq });
+async function sendOne(context, { kind, id, message }) {
+    const passive = (body, grant) => context.operation.run(() => dispatch(context.bot, { kind, id, message: body, source: grant.source, options: { msgSeq: grant.msgSeq } }));
     const active = async (body) => {
         if (context.activeGate.blocked(kind, id)) {
             throw new EndpointDeliveryError('platform_rejected', 'QQ active messages are unavailable for this conversation', 'not_sent');
         }
         try {
-            return await dispatch(context.bot, kind, id, body);
+            return await context.operation.run(() => dispatch(context.bot, { kind, id, message: body }));
         }
         catch (error) {
             const code = platformCode(error);
@@ -100,10 +113,11 @@ async function sendOne(context, kind, id, message) {
     }
 }
 /** Sends every message of one delivery in order; returns the last platform result. */
-export async function sendQqMessages(context, conversation, messages) {
+export async function sendQqMessages(context, { conversation, messages, signal }) {
     const kind = qqOutboundKind(conversation);
+    const execution = { ...context, operation: createEndpointOperation({ signal }) };
     let result;
     for (const message of messages)
-        result = await sendOne(context, kind, conversation.id, message);
+        result = await sendOne(execution, { kind, id: conversation.id, message });
     return result;
 }

package/lib/webhook.d.ts

@@ -1,11 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { Bot, ReceiverMode } from 'qq-official-bot';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import type { ResolvedQqHttpConfig } from './protocol.js';
-import type { QqBotTransport } from './ws.js';
-export type QqHttpBotTransport = QqBotTransport & {
-    middleware: (ctx: unknown, next: () => Promise<void>) => Promise<unknown>;
-};
-export type CreateQqHttpBot = (config: ResolvedQqHttpConfig) => QqHttpBotTransport;
+export type QqHttpBotTransport = Bot<ReceiverMode.MIDDLEWARE, 'koa'>;
 export interface QqWebhookHandler {
     readonly config: ResolvedQqHttpConfig;
     getBot(): (QqHttpBotTransport & {
@@ -15,4 +12,4 @@ export interface QqWebhookHandler {
 export declare function registerQqWebhookRoutes(http: HttpHost, handler: QqWebhookHandler): HttpRouteRegistration[];
 export declare function handleQqWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: QqWebhookHandler): Promise<void>;
 export declare function readRequestBodyText(request: IncomingMessage): Promise<string>;
-export declare function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTransport;
+export declare function qqHttpBotOptions(config: ResolvedQqHttpConfig): ConstructorParameters<typeof Bot<ReceiverMode.MIDDLEWARE, 'koa'>>[0];

package/lib/webhook.js

@@ -2,7 +2,7 @@
  * QQ HTTP webhook / middleware inbound via httpHostToken POST.
  */
 import path from 'node:path';
-import { Bot, ReceiverMode } from 'qq-official-bot';
+import { ReceiverMode } from 'qq-official-bot';
 import { getLogger } from '@zhin.js/logger';
 const logger = getLogger('qq');
 export function registerQqWebhookRoutes(http, handler) {
@@ -28,6 +28,7 @@ export async function handleQqWebhookRequest(request, response, handler) {
             req: request,
             res: response,
             request: { body: undefined },
+            response: {},
         }, async () => undefined);
     }
     catch (error) {
@@ -52,52 +53,8 @@ export async function readRequestBodyText(request) {
     }
     return Buffer.concat(chunks).toString('utf8');
 }
-export function defaultCreateHttpBot(config) {
-    const bot = new Bot({
-        appid: config.appid,
-        secret: config.secret,
-        mode: ReceiverMode.MIDDLEWARE,
-        platform: 'koa',
-        sandbox: config.sandbox,
-        dataDir: path.join(process.cwd(), 'data', 'qq'),
-        // 关闭内置 log4js，与 WebSocket 模式一致走 zhin adapter logger
-        logLevel: 'off',
-    });
-    return {
-        api: bot,
-        start: () => bot.start().then(() => undefined),
-        stop: () => bot.stop().then(() => undefined),
-        on: (event, listener) => {
-            bot.on(event, listener);
-        },
-        removeAllListeners: () => {
-            bot.removeAllListeners(undefined);
-        },
-        sendPrivateMessage: (userId, message, source, options) => bot.sendPrivateMessage(userId, message, source, options),
-        sendGroupMessage: (groupId, message, source, options) => bot.sendGroupMessage(groupId, message, source, options),
-        sendGuildMessage: (channelId, message, source, options) => bot.sendGuildMessage(channelId, message, source, options),
-        sendDirectMessage: (guildId, message, source, options) => bot.sendDirectMessage(guildId, message, source, options),
-        recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
-        recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
-        recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),
-        recallDirectMessage: (guildId, messageId) => bot.recallDirectMessage(guildId, messageId),
-        getGuilds: () => bot.guildService.getList(),
-        getChannels: (guildId) => bot.channelService.getList(guildId),
-        getChannelInfo: (channelId) => bot.channelService.getInfo(channelId),
-        getGuildMember: (guildId, userId) => bot.memberService.getGuildMemberInfo(guildId, userId),
-        getGuildRoles: (guildId) => bot.guildService.getRoles(guildId),
-        createGuildRole: (guildId, name, color) => bot.guildService.createRole(guildId, { name, color: color || 0, hoist: 0 }),
-        addMemberRole: async (guildId, channelId, userId, roleId) => {
-            await bot.memberService.addMemberRole(guildId, channelId, userId, roleId);
-            return true;
-        },
-        removeMemberRole: async (guildId, channelId, userId, roleId) => {
-            await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
-            return true;
-        },
-        approveGroupJoinRequest: (groupId, userId, options) => bot
-            .approveGroupJoinRequest?.(groupId, userId, options)
-            ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
-        middleware: (ctx, next) => bot.middleware(ctx, next),
-    };
+export function qqHttpBotOptions(config) {
+    return { handleProcessErrors: false, appid: config.appid, secret: config.secret,
+        mode: ReceiverMode.MIDDLEWARE, platform: 'koa', sandbox: config.sandbox,
+        dataDir: path.join(process.cwd(), 'data', 'qq'), logLevel: 'off' };
 }

package/lib/ws.d.ts

@@ -1,7 +1,5 @@
-import { Bot, type ApproveJoinRequestOptions } from 'qq-official-bot';
+import { Bot, ReceiverMode } from 'qq-official-bot';
 import type { EndpointTransportState } from 'zhin.js/adapter';
-import type { QqOutboundMessage } from './outbound.js';
-import type { QqReplySource } from './passive-reply.js';
 /** Per-send options. `msgSeq` numbers replies to one passive source (qq-official-bot ≥ 1.3.3). */
 export interface QqSendOptions {
     readonly msgSeq?: number;
@@ -9,35 +7,7 @@ export interface QqSendOptions {
 import type { QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
 /** SDK business surface exposed to plugins without bypassing Endpoint lifecycle ownership. */
 export type QqOfficialApi = Pick<Bot, 'messageService' | 'fileProcessor' | 'guildService' | 'channelService' | 'memberService' | 'permissionService' | 'reactionService' | 'scheduleService' | 'threadService' | 'audioService' | 'botService' | 'groupService' | 'menuPanelService' | 'group' | 'user' | 'channel' | 'direct' | 'guild'>;
-/** Minimal bot surface used by the endpoint (real qq-official-bot or test mock). */
-export interface QqBotTransport {
-    readonly transportState?: EndpointTransportState;
-    /** Full qq-official-bot business API; lifecycle remains owned by the Endpoint. */
-    readonly api: QqOfficialApi;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    on(event: string, listener: (...args: unknown[]) => void): void;
-    removeAllListeners(): void;
-    /** `source` makes it a passive reply; without it the platform treats the message as active. */
-    sendPrivateMessage(userId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
-    sendGroupMessage(groupId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
-    sendGuildMessage(channelId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
-    sendDirectMessage?(guildId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
-    recallPrivateMessage?(userId: string, messageId: string): Promise<unknown>;
-    recallGroupMessage?(groupId: string, messageId: string): Promise<unknown>;
-    recallGuildMessage?(channelId: string, messageId: string): Promise<unknown>;
-    recallDirectMessage?(guildId: string, messageId: string): Promise<unknown>;
-    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>;
-    approveGroupJoinRequest?(groupId: string, userId: string, options: ApproveJoinRequestOptions): Promise<unknown>;
-}
-export type CreateQqBot = (config: ResolvedQqWebsocketConfig) => QqBotTransport;
+export type QqBotTransport = Bot;
 interface QqOfficialBotLifecycle {
     stop(): Promise<unknown>;
     readonly sessionManager: {
@@ -59,5 +29,12 @@ interface QqOfficialBotLifecycle {
 export declare function stopQqOfficialBot(bot: QqOfficialBotLifecycle): Promise<void>;
 export declare function bindQqBotInboundEvents(bot: QqBotTransport, admitRaw: (raw: unknown) => void): void;
 export declare function normalizeQqMessage(raw: unknown): QqInboundMessage | null;
-export declare function defaultCreateBot(config: ResolvedQqWebsocketConfig): QqBotTransport;
+export declare function qqWebsocketBotOptions(config: ResolvedQqWebsocketConfig): ConstructorParameters<typeof Bot<ReceiverMode.WEBSOCKET>>[0];
+/** SDK 1.3.3 has no public receiver configuration/state accessor. This seam only reads its verified native fields. */
+export declare function configureQqWebsocketReceiver(bot: Bot<ReceiverMode.WEBSOCKET>, config: ResolvedQqWebsocketConfig): {
+    state(): EndpointTransportState;
+    dispose(): void;
+};
+/** Session.stop leaves Auth refresh alive for reconnect; actual instance retirement destroys it. */
+export declare function disposeQqAuthorization(bot: Bot): void;
 export {};

package/lib/ws.js

@@ -3,7 +3,7 @@
  */
 import path from 'node:path';
 import { createQqStreamAgent } from './stream-proxy.js';
-import { Bot, ReceiverMode, } from 'qq-official-bot';
+import { ReceiverMode, } from 'qq-official-bot';
 /**
  * qq-official-bot 1.2 used a separate connection manager; 1.3 moved WebSocket
  * ownership into the receiver, but Session.stop() still leaves the auth refresh
@@ -72,6 +72,8 @@ export function normalizeQqMessage(raw) {
         && msg.mentions.some((m) => m?.is_you === true || (m?.bot === true && channelKind !== 'group'));
     return {
         id: String(msg.message_id),
+        event: raw,
+        ...(typeof msg.timestamp === 'number' && Number.isFinite(msg.timestamp) ? { platformSentAt: msg.timestamp * 1_000 } : {}),
         content,
         channelKind,
         channelId,
@@ -183,87 +185,36 @@ function extractTextContent(message) {
     })
         .join('');
 }
-export function defaultCreateBot(config) {
-    const bot = new Bot({
-        ...{ handleProcessErrors: false },
-        appid: config.appid,
-        secret: config.secret,
-        mode: ReceiverMode.WEBSOCKET,
-        sandbox: config.sandbox,
-        dataDir: path.join(process.cwd(), 'data', 'qq'),
-        // 关闭 qq-official-bot 内置 log4js，入/出站由 getAdapterLogger('qq', …) 统一格式
-        logLevel: 'off',
+export function qqWebsocketBotOptions(config) {
+    return { handleProcessErrors: false, appid: config.appid, secret: config.secret,
+        mode: ReceiverMode.WEBSOCKET, sandbox: config.sandbox,
+        dataDir: path.join(process.cwd(), 'data', 'qq'), logLevel: 'off',
         ...(config.intents ? { intents: config.intents } : {}),
         ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
-        ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),
-    });
+        ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}), };
+}
+/** SDK 1.3.3 has no public receiver configuration/state accessor. This seam only reads its verified native fields. */
+export function configureQqWebsocketReceiver(bot, config) {
     const receiver = bot.receiver;
     receiver.config.autoReconnect = false;
     const agent = config.streamProxy ? createQqStreamAgent(config.streamProxy) : undefined;
     receiver.config.agent = agent;
-    const receiverListeners = [];
-    // Keep receiver error ownership after Session.start removes its temporary listener.
-    const receiverError = () => { };
-    receiver.on('error', receiverError);
+    const observeError = () => undefined;
+    bot.receiver.on('error', observeError);
     return {
-        get transportState() {
-            const receiver = bot.receiver;
+        state() {
             const state = receiver.handler?.ws?.readyState;
             if (state === 1 && receiver.isReady && receiver.isClosed === false)
                 return 'open';
             if (state === 0)
                 return 'connecting';
-            if (receiver.isStarted)
-                return 'reconnecting';
-            return 'closed';
-        },
-        api: bot,
-        start: () => bot.start().then(() => undefined),
-        stop: async () => {
-            try {
-                await stopQqOfficialBot(bot);
-            }
-            finally {
-                agent?.destroy();
-            }
-        },
-        on: (event, listener) => {
-            if (event === 'transport.close') {
-                receiver.on('close', listener);
-                receiverListeners.push({ event: 'close', listener });
-            }
-            else
-                bot.on(event, listener);
+            return receiver.isStarted ? 'reconnecting' : 'closed';
         },
-        removeAllListeners: () => {
-            for (const entry of receiverListeners.splice(0))
-                receiver.removeListener(entry.event, entry.listener);
-            bot.removeAllListeners(undefined);
-        },
-        sendPrivateMessage: (userId, message, source, options) => bot.sendPrivateMessage(userId, message, source, options),
-        sendGroupMessage: (groupId, message, source, options) => bot.sendGroupMessage(groupId, message, source, options),
-        sendGuildMessage: (channelId, message, source, options) => bot.sendGuildMessage(channelId, message, source, options),
-        sendDirectMessage: (guildId, message, source, options) => bot.sendDirectMessage(guildId, message, source, options),
-        recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
-        recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
-        recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),
-        recallDirectMessage: (guildId, messageId) => bot.recallDirectMessage(guildId, messageId),
-        getGuilds: () => bot.guildService.getList(),
-        getChannels: (guildId) => bot.channelService.getList(guildId),
-        getChannelInfo: (channelId) => bot.channelService.getInfo(channelId),
-        getGuildMember: (guildId, userId) => bot.memberService.getGuildMemberInfo(guildId, userId),
-        getGuildRoles: (guildId) => bot.guildService.getRoles(guildId),
-        createGuildRole: (guildId, name, color) => bot.guildService.createRole(guildId, { name, color: color || 0, hoist: 0 }),
-        addMemberRole: async (guildId, channelId, userId, roleId) => {
-            await bot.memberService.addMemberRole(guildId, channelId, userId, roleId);
-            return true;
-        },
-        removeMemberRole: async (guildId, channelId, userId, roleId) => {
-            await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
-            return true;
-        },
-        approveGroupJoinRequest: (groupId, userId, options) => bot
-            .approveGroupJoinRequest?.(groupId, userId, options)
-            ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
+        dispose() { bot.receiver.off('error', observeError); agent?.destroy(); },
     };
 }
+/** Session.stop leaves Auth refresh alive for reconnect; actual instance retirement destroys it. */
+export function disposeQqAuthorization(bot) {
+    const session = bot.sessionManager;
+    session.authManager.destroy();
+}

package/middlewares/bot-kind-reply/index.js

@@ -1,7 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../lib/i18n.js";
 import { defineMiddleware } from 'zhin.js/middleware';
-import { endpointConfigurationStoreToken } from 'zhin.js/adapter';
 import { completeQqPendingBotKind, } from '../../commands/qq/endpoint/definition.js';
 import { parseQqBotKindAnswer, qqCommandSessionKey, qqBotKindPrompt, } from "../../lib/qq-bot-kind-prompt.js";
 import { qqRuntimeStateToken } from "../../lib/qq-runtime-state.js";
@@ -37,7 +36,7 @@ export default defineMiddleware({
             return;
         }
         try {
-            const text = await completeQqPendingBotKind(pending, botKind, context.use(endpointConfigurationStoreToken));
+            const text = await completeQqPendingBotKind(pending, botKind);
             state.pendingBotKind = null;
             await context.input.$reply?.(text);
         }

package/middlewares/bot-kind-reply/index.ts

@@ -1,7 +1,6 @@
 import { messages as t } from '../../src/i18n.js';
 import { defineMiddleware } from 'zhin.js/middleware';
 import type { CommandMessage } from 'zhin.js/command';
-import { endpointConfigurationStoreToken } from 'zhin.js/adapter';
 import {
   completeQqPendingBotKind,
 } from '../../commands/qq/endpoint/definition.js';
@@ -53,7 +52,6 @@ export default defineMiddleware<CommandMessage>({
       const text = await completeQqPendingBotKind(
         pending,
         botKind,
-        context.use(endpointConfigurationStoreToken),
       );
       state.pendingBotKind = null;
       await context.input.$reply?.(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,24 +34,27 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.3.3",
-    "@zhin.js/adapter": "1.1.24",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.52",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
-    "@zhin.js/im-contract": "1.1.8",
+    "@zhin.js/adapter": "1.1.26",
+    "@zhin.js/agent-feature": "1.1.11",
+    "@zhin.js/client": "1.1.22",
+    "@zhin.js/console-contract": "1.1.3",
+    "@zhin.js/core": "1.1.54",
+    "@zhin.js/feature-kit": "1.1.10",
+    "@zhin.js/host-http": "1.1.12",
+    "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.9",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/permission": "1.1.10",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
-    "@zhin.js/middleware": "^1.1.10",
-    "zhin.js": "^1.1.17"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "@zhin.js/middleware": "^1.1.11",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -72,13 +75,14 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.11",
-    "zhin.js": "1.1.17"
+    "@zhin.js/host-http": "1.1.12",
+    "zhin.js": "1.1.19"
   },
   "files": [
     "adapters",
     "commands",
     "middlewares",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -105,7 +109,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",
@@ -126,6 +130,10 @@
       {
         "package": "@zhin.js/agent-feature",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/pages/index/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+export const meta = definePage({
+    title: 'QQ',
+    titleI18n: { en: 'QQ' },
+    icon: 'MessageCircle',
+    order: 60,
+    requiredPermissions: ['qq:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/qq`（插件路径）。
+ * 连接状态、测试、endpoint 增删、扫码绑定（原本 `qq endpoint add` 的聊天流程）。
+ */
+export default createAdapterConsolePage('qq');

package/pages/index/index.ts

@@ -0,0 +1,16 @@
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+
+export const meta = definePage({
+  title: 'QQ',
+  titleI18n: { en: 'QQ' },
+  icon: 'MessageCircle',
+  order: 60,
+  requiredPermissions: ['qq:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/qq`（插件路径）。
+ * 连接状态、测试、endpoint 增删、扫码绑定（原本 `qq endpoint add` 的聊天流程）。
+ */
+export default createAdapterConsolePage('qq');

package/plugin.js

@@ -1,18 +1,21 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { definePlugin } from 'zhin.js';
+import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
 import { permissionHostToken } from '@zhin.js/permission';
 import { checkQqPlatformPermit } from "./lib/platform-permit.js";
 import { createQqRuntimeState, qqRuntimeStateToken } from "./lib/qq-runtime-state.js";
+import { createQqConsoleRpc } from "./lib/console.js";
+import { cancelQqConsoleBind } from "./lib/qq-console.js";
 export default definePlugin({
     name: 'qq',
     metadata: {
         displayName: 'QQ Official WebSocket Adapter',
     },
     setup(context) {
-        context.resources.provide(qqRuntimeStateToken, createQqRuntimeState());
-        if (context.resources.has(permissionHostToken)) {
-            const host = context.resources.use(permissionHostToken);
-            return host.registerPlatform('qq', checkQqPlatformPermit);
-        }
+        const state = createQqRuntimeState();
+        context.resources.provide(qqRuntimeStateToken, state);
+        context.resources.provide(pluginConsoleRpcToken, createQqConsoleRpc(state, () => context.config.get()));
+        const releasePermission = context.resources.has(permissionHostToken)
+            ? context.resources.use(permissionHostToken).registerPlatform('qq', checkQqPlatformPermit) : undefined;
+        return () => { cancelQqConsoleBind(state); releasePermission?.(); };
     },
 });