@zhin.js/adapter-qq 1.1.18 → 1.1.19

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.18",
+  "version": "1.1.19",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,27 +34,27 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.3.3",
-    "@zhin.js/adapter": "1.1.25",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/client": "1.1.21",
+    "@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.53",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
+    "@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/page": "1.1.10",
-    "@zhin.js/permission": "1.1.9",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.12"
+    "@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.25",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.53",
-    "@zhin.js/middleware": "^1.1.10",
-    "zhin.js": "^1.1.18"
+    "@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": {
@@ -75,8 +75,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.11",
-    "zhin.js": "1.1.18"
+    "@zhin.js/host-http": "1.1.12",
+    "zhin.js": "1.1.19"
   },
   "files": [
     "adapters",
@@ -109,7 +109,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",

package/plugin.js

@@ -4,6 +4,7 @@ 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: {
@@ -12,10 +13,9 @@ export default definePlugin({
     setup(context) {
         const state = createQqRuntimeState();
         context.resources.provide(qqRuntimeStateToken, state);
-        context.resources.provide(pluginConsoleRpcToken, createQqConsoleRpc(state, context.resources, () => context.config.get()));
-        if (context.resources.has(permissionHostToken)) {
-            const host = context.resources.use(permissionHostToken);
-            return host.registerPlatform('qq', checkQqPlatformPermit);
-        }
+        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?.(); };
     },
 });

package/src/adapter.ts

@@ -0,0 +1,23 @@
+import { Adapter, createAdapterOutageNotifier, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { outboundHostToken } from 'zhin.js';
+import { httpHostToken } from '@zhin.js/host-http';
+import { QqHttpEndpoint, QqWebsocketEndpoint } from './endpoint.js';
+import { resolveQqConfig, type QqEndpointConfig } from './protocol.js';
+import type { QqClientEventMap } from './client.js';
+
+export class QqAdapter extends Adapter<QqHttpEndpoint | QqWebsocketEndpoint, QqEndpointConfig, QqClientEventMap> {
+  constructor(private readonly context: AdapterContext<QqEndpointConfig>) { super(); }
+  override get configurationIdentityFields(): readonly string[] { return ['id', 'appid']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['accessTokenUrl', 'gatewayUrl']; }
+  override get configurationUpdateFields(): readonly string[] { return ['secret', 'mode', 'sandbox', 'intents', 'botKind',
+    'accessTokenUrl', 'gatewayUrl', 'streamProxy', 'streamProxy.port', 'streamProxy.serverName', 'webhookPath']; }
+  protected override validateConfiguration(input: QqEndpointConfig): void { resolveQqConfig(input); }
+  protected createEndpoint(input: QqEndpointConfig, execution: EndpointCreationContext): QqHttpEndpoint | QqWebsocketEndpoint {
+    const config = resolveQqConfig(input);
+    const outbound = this.context.has?.(outboundHostToken) ? this.context.use(outboundHostToken) : undefined;
+    const notifier = createAdapterOutageNotifier(outbound, config.notify);
+    return config.mode === 'websocket'
+      ? new QqWebsocketEndpoint({ id: execution.canonicalId, config, notifier })
+      : new QqHttpEndpoint({ id: execution.canonicalId, config, notifier, http: this.context.use(httpHostToken) });
+  }
+}

package/src/client.ts

@@ -1,16 +1,8 @@
-import { defineEndpointClient } from 'zhin.js/adapter';
-import type { QqInboundMessage } from './protocol.js';
-import type { QqBotTransport } from './ws.js';
+import type { EventMap } from 'qq-official-bot';
+import type { QqAdapter } from './adapter.js';
 
-export type QqClientEventMap = Record<string, QqInboundMessage | unknown>;
+export type QqClientEventMap = { readonly [K in keyof EventMap]: EventMap[K] extends (event: infer E, ...args: never[]) => unknown ? E : never };
 
 declare module '@zhin.js/feature-kit' {
-  interface AdapterClientRegistry {
-    readonly qq: {
-      readonly client: QqBotTransport;
-      readonly events: QqClientEventMap;
-    };
-  }
+  interface AdapterRegistry { readonly qq: QqAdapter; }
 }
-
-export const qqClient = defineEndpointClient<QqBotTransport, QqClientEventMap>('qq');

package/src/console.ts

@@ -3,11 +3,10 @@
  * （以及公域 / 私域选择、取消）搬到 Console 页面。
  */
 import {
-  endpointConfigurationStoreToken,
+  prepareConsoleAdapterMutation,
+  ownedConsoleAdapter,
   createAdapterConsoleRpc,
-  type AdapterConsoleResources,
   type AdapterConsoleSpec,
-  type EndpointConfigurationStore,
 } from 'zhin.js/adapter';
 import { PluginConsoleRpcError, type PluginConsoleRpc } from 'zhin.js';
 import { qqConsoleSpec } from './qq-console-spec.js';
@@ -20,16 +19,10 @@ import type { QqRuntimeState } from './qq-runtime-state.js';
 
 export function createQqConsoleRpc(
   state: QqRuntimeState,
-  resources: AdapterConsoleResources,
   getConfig: () => unknown,
 ): PluginConsoleRpc {
-  const store: EndpointConfigurationStore | undefined = resources.has(endpointConfigurationStoreToken)
-    ? resources.use(endpointConfigurationStoreToken)
-    : undefined;
-
   const spec: AdapterConsoleSpec = {
     ...qqConsoleSpec,
-    running: () => state.endpoints.values(),
     getConfig,
     extraStatus: () => {
       const bind = state.consoleBind;
@@ -45,7 +38,6 @@ export function createQqConsoleRpc(
       };
     },
     availableActions: () => {
-      if (!store) return [];
       if (state.consoleBind?.pending) return ['qq-bind-kind', 'qq-bind-cancel'];
       if (state.bindFlow || state.consoleBind?.state === 'waiting') return ['qq-bind-cancel'];
       return ['qq-bind-start'];
@@ -54,15 +46,23 @@ export function createQqConsoleRpc(
       'qq-bind-start': {
         label: '扫码绑定新机器人',
         labelI18n: { en: 'Bind a bot with QR' },
-        description: '用手机 QQ 扫码，成功后选择公域 / 私域，再一次性写入 .env 与配置。',
-        descriptionI18n: { en: 'Scan with mobile QQ, choose public/private, then save credentials to .env and the config.' },
-        handler: async () => {
-          if (!store) throw new PluginConsoleRpcError('unsupported', '当前运行环境不支持写入 endpoint 配置');
-          const { url } = await startQqConsoleBind(state);
+        description: '用手机 QQ 扫码，选择公域 / 私域后保存到账号库；保存后需手动启动。',
+        descriptionI18n: { en: 'Scan with mobile QQ, choose public/private and save the account; start it explicitly afterwards.' },
+        handler: async (input, call) => {
+          if (!call.runtime) throw new PluginConsoleRpcError('unsupported', '账号运行目录不可用');
+          const adapter = ownedConsoleAdapter(spec, call);
+          if (!adapter.canManage) throw new PluginConsoleRpcError('unsupported', '此环境未提供持久化账号管理');
+          if (input.expectedGeneration !== call.runtime.generation || input.expectedRevision !== adapter.revision) {
+            throw new PluginConsoleRpcError('conflict', '账号清单已变化，请刷新核实');
+          }
+          const starting = startQqConsoleBind(state);
+          state.consoleAdmission = { adapterId: adapter.descriptor.id, generation: call.runtime.generation, revision: adapter.revision };
+          const { url } = await starting;
           return { message: '请用手机 QQ 扫码；扫码成功后选择公域或私域', url };
         },
       },
       'qq-bind-kind': {
+        accountMutation: true,
         label: '选择公域 / 私域',
         labelI18n: { en: 'Choose public/private' },
         description: '公域订阅 PUBLIC_GUILD_MESSAGES；私域订阅 GUILD_MESSAGES。',
@@ -71,11 +71,18 @@ export function createQqConsoleRpc(
           { value: 'public', label: '公域', labelI18n: { en: 'Public' } },
           { value: 'private', label: '私域', labelI18n: { en: 'Private' } },
         ],
-        handler: async (input) => {
-          if (!store) throw new PluginConsoleRpcError('unsupported', '当前运行环境不支持写入 endpoint 配置');
-          const result = await completeQqConsoleBind(state, store, input.value);
+        handler: async (input, call) => {
+          const captured = state.consoleAdmission;
+          if (!captured || captured.generation !== input.expectedGeneration || captured.revision !== input.expectedRevision) {
+            throw new PluginConsoleRpcError('conflict', '扫码期间账号清单已变化，请刷新核实');
+          }
+          const admission = prepareConsoleAdapterMutation(spec, call, input);
+          if (admission.adapter.descriptor.id !== captured.adapterId) throw new PluginConsoleRpcError('conflict', '扫码所属 Adapter 已变化');
+          const result = await completeQqConsoleBind(state, config => admission.adapter.add(admission.revision,
+            { endpointId: config.id, config: { ...config } }, admission.options), input.value);
           return {
-            message: `已写入 endpoint「${result.endpointId}」（${result.botKind}），重启或热重载后生效`,
+            message: `已保存账号「${result.endpointId}」（${result.botKind}），尚未启动`,
+            saved: true, restartRequired: false, execution: { ...result.mutation.execution },
             details: { endpoint: result.endpointId, botKind: result.botKind, intents: result.intents.join(', ') },
           };
         },
@@ -92,5 +99,5 @@ export function createQqConsoleRpc(
       },
     },
   };
-  return createAdapterConsoleRpc(spec, resources);
+  return createAdapterConsoleRpc(spec);
 }