@zhin.js/adapter-qq 1.1.17 → 1.1.19

package/commands/qq/endpoint/definition.js

@@ -3,16 +3,16 @@ import { resolveLocale } from 'zhin.js/i18n';
 import { messages as t } from "../../../lib/i18n.js";
 /**
  * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
- * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
- * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
- * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
+ * list / remove 与权限共用 @zhin.js/adapter 的账号管理入口；
+ * 本文件保留 QQ 扫码绑定 add 与 cancel，保存委派捕获的所属 Adapter CAS，并导出
  * qqEndpointCommands 供 commands/qq/endpoint/ 下的命令文件默认导出。
  */
-import { buildEndpointEnvKey, createEndpointCommands, endpointCommandForbidden, endpointConfigurationStoreToken, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointById, } from 'zhin.js/adapter';
+import { createEndpointCommands, endpointCommandForbidden, createDurableEndpointCommandReply, isEndpointOperator, extractEndpointCommandReply, adapterFeatureId, isAdapterIndex } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
 import { qqBotKindPrompt, qqCommandSessionKey } from "../../../lib/qq-bot-kind-prompt.js";
 import { startQqBindFlow } from "../../../lib/qq-bind-flow.js";
-import { defaultQqEndpointIntentFields } from "../../../lib/qq-intents.js";
+import { writeQqEndpointWithBotKind } from "../../../lib/qq-endpoint-write.js";
+import { cancelQqConsoleBind } from "../../../lib/qq-console.js";
 import { qqRuntimeStateToken, } from "../../../lib/qq-runtime-state.js";
 export { qqRuntimeStateToken };
 /**
@@ -21,7 +21,17 @@ export { qqRuntimeStateToken };
  * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
  */
 export function isQqEndpointOperator(config, input) {
-    return isEndpointOperator(config, input);
+    if (isEndpointOperator(config, input))
+        return true;
+    // The outage-notify target is the operator's conversation on another adapter.
+    const cfg = (config ?? {});
+    const notifyIds = [
+        cfg.notify?.id,
+        ...(Array.isArray(cfg.endpoints) ? cfg.endpoints.map((endpoint) => endpoint.notify?.id) : []),
+    ];
+    const senderRaw = input?.sender;
+    const senderId = (typeof senderRaw === 'object' && senderRaw?.id) ? String(senderRaw.id).trim() : '';
+    return senderId !== '' && notifyIds.some((id) => id != null && String(id) === senderId);
 }
 export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
 /**
@@ -36,59 +46,47 @@ function busyFooter(state, locale) {
     if (state.pendingBotKind) {
         return t(locale, 'kindBusy', { id: state.pendingBotKind.endpointId });
     }
+    if (state.consoleBind?.state === 'scanned') {
+        return t(locale, 'kindBusy', { id: state.consoleBind.pending?.endpointId ?? 'QQ' });
+    }
     return undefined;
 }
-/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
-export async function runQqEndpointList(state, store, locale) {
-    return formatEndpointList(qqEndpointListSpec, {
-        running: state.endpoints.values(),
-        configured: await store.list('qq'),
-        footer: busyFooter(state, locale), locale,
-    });
-}
 const qqEndpointListSpec = {
     adapterKey: 'qq',
     adapterDisplayName: 'QQ',
     describeEntry: (entry) => `appid: ${String(entry.appid)}`,
 };
-async function writeEndpointWithBotKind(pending, botKind, store) {
-    const locale = pending.locale;
-    const appidKey = buildEndpointEnvKey('qq', pending.endpointId, 'appid');
-    const secretKey = buildEndpointEnvKey('qq', pending.endpointId, 'secret');
-    const intentFields = defaultQqEndpointIntentFields(botKind);
-    const { filePath } = await store.add({
-        adapterKey: 'qq',
-        entry: {
-            id: pending.endpointId,
-            appid: `\${${appidKey}}`,
-            secret: `\${${secretKey}}`,
-            botKind: intentFields.botKind,
-            intents: [...intentFields.intents],
-        },
-        environment: {
-            [appidKey]: pending.appId,
-            [secretKey]: pending.appSecret,
-        },
+async function writeEndpointWithBotKind(pending, botKind, save) {
+    const result = await writeQqEndpointWithBotKind({
+        endpointId: pending.endpointId,
+        appId: pending.appId,
+        appSecret: pending.appSecret,
+        botKind,
+    }, save);
+    return t(pending.locale, 'endpointSaved', {
+        kind: result.botKind,
+        id: result.endpointId,
+        intents: result.intents.join(', '),
     });
-    return t(locale, 'endpointSaved', { kind: intentFields.botKind, id: pending.endpointId, file: filePath, intents: intentFields.intents.join(', ') });
 }
 /**
- * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
+ * 完成 pending 的公域/私域选择：通过已捕获的所属 Adapter 保存一次账号配置。
  * @returns 成功文案；调用方负责清 pending。
  */
-export async function completeQqPendingBotKind(pending, botKind, store) {
-    return await writeEndpointWithBotKind(pending, botKind, store);
+export async function completeQqPendingBotKind(pending, botKind) {
+    return await writeEndpointWithBotKind(pending, botKind, pending.save);
 }
 /**
  * `qq endpoint add [id]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
- * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
+ * 扫码成功后凭据暂存内存并询问公域/私域；确认后保存到账号库，等待显式启动。
  */
-export function runQqEndpointAdd(state, id, reply, store, input, locale = 'zh-CN', cancelCommand, commandHeads) {
-    if (state.bindFlow || state.pendingBotKind) {
+export function runQqEndpointAdd(state, id, reply, save, input, locale = 'zh-CN', cancelCommand, commandHeads) {
+    if (state.bindFlow || state.pendingBotKind || state.consoleBind?.pending || state.consoleBind?.state === 'waiting') {
         return Promise.resolve(t(locale, 'existingFlow'));
     }
+    state.consoleBind = null;
     const endpointId = id?.trim() || undefined;
     const sessionKey = qqCommandSessionKey(input);
     return new Promise((resolve) => {
@@ -128,8 +126,8 @@ export function runQqEndpointAdd(state, id, reply, store, input, locale = 'zh-CN
                             endpointId: finalName,
                             appId,
                             appSecret,
-                            sessionKey: '', locale, cancelCommand,
-                        }, 'public', store) +
+                            sessionKey: '', locale, cancelCommand, save,
+                        }, 'public', save) +
                             t(locale, 'noInteractiveKind'));
                         return;
                     }
@@ -137,7 +135,7 @@ export function runQqEndpointAdd(state, id, reply, store, input, locale = 'zh-CN
                         endpointId: finalName,
                         appId,
                         appSecret,
-                        sessionKey, locale, cancelCommand, commandHeads,
+                        sessionKey, locale, cancelCommand, commandHeads, save,
                     };
                     settle(t(locale, 'scanned', { id: finalName, prompt: qqBotKindPrompt(locale, cancelCommand) }));
                 }
@@ -159,6 +157,7 @@ export function runQqEndpointCancel(state, preference) {
     if (state.bindFlow) {
         state.bindFlow.stop();
         state.bindFlow = null;
+        cancelQqConsoleBind(state);
         return t(locale, 'cancelled');
     }
     if (state.pendingBotKind) {
@@ -166,25 +165,44 @@ export function runQqEndpointCancel(state, preference) {
         state.pendingBotKind = null;
         return t(locale, 'pendingCancelled', { name });
     }
+    if (state.consoleBind) {
+        cancelQqConsoleBind(state);
+        return t(locale, 'cancelled');
+    }
     return t(locale, 'noFlow');
 }
-/** `qq endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
-export async function runQqEndpointRemove(_state, id, store) {
-    return await removeEndpointById(qqEndpointListSpec, id, store);
-}
 /**
  * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
  * commands/qq/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
  */
-export const qqEndpointCommands = createEndpointCommands({
+const standard = createEndpointCommands({
     ...qqEndpointListSpec,
-    fields: [
-        { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid', descriptionI18n: { en: "QQ bot app ID" } },
-        { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret', descriptionI18n: { en: "QQ bot secret" } },
-    ],
-    running: (use) => use(qqRuntimeStateToken).endpoints.values(),
+    fields: [{ key: 'appid', required: true }, { key: 'secret', required: true, secret: true }],
     listFooter: (use, locale) => busyFooter(use(qqRuntimeStateToken), locale),
-    addDescriptionI18n: { en: 'Bind a bot through mobile QQ, choose public/private, then save configuration; restart to apply' },
-    addDescription: '手机 QQ 扫码绑定机器人：确认公域/私域后一次性写入 .env 与 zhin.config.yml（重启生效）',
-    bindFlow: ({ id, reply, input, use, locale, formatCommand }) => runQqEndpointAdd(use(qqRuntimeStateToken), id, reply, use(endpointConfigurationStoreToken), input, locale, formatCommand?.('qq endpoint cancel'), ['qq endpoint list', 'qq endpoint add', 'qq endpoint remove', 'qq endpoint cancel'].flatMap(path => { const head = formatCommand?.(path); return head ? [head] : []; })),
 }, defineCommand);
+export const qqEndpointCommands = {
+    ...standard,
+    add: defineCommand({
+        description: '手机 QQ 扫码绑定；确认公域/私域后保存账号，手动启动',
+        descriptionI18n: { en: 'Scan with mobile QQ, choose public/private, save the account and start explicitly' },
+        params: { id: { type: 'string', description: 'endpoint ID' } },
+        async execute(context) {
+            if (!isEndpointOperator(context.config, context.input))
+                return endpointCommandForbidden('QQ', context.locale);
+            const index = context.project(adapterFeatureId);
+            if (!isAdapterIndex(index))
+                throw new Error('QQ Adapter projection is unavailable');
+            const own = index.forOwner(context.owner.id).adapters().filter(adapter => adapter.descriptor.name === 'qq');
+            if (own.length !== 1)
+                throw new Error('QQ Adapter ownership is ambiguous');
+            const adapter = own[0];
+            if (adapter.needsMigration)
+                return '首次修改账号前，请由管理员在 Console 确认迁移账号清单';
+            if (!adapter.canManage)
+                return '此环境未提供持久化账号管理';
+            const revision = adapter.revision;
+            const save = config => adapter.add(revision, { endpointId: config.id, config: { ...config } }, { waitForExecution: false });
+            return runQqEndpointAdd(context.use(qqRuntimeStateToken), context.params.id, createDurableEndpointCommandReply(context.input, context.use), save, context.input, context.locale, context.formatCommand?.('qq endpoint cancel'), ['qq endpoint list', 'qq endpoint add', 'qq endpoint remove', 'qq endpoint cancel'].flatMap(path => { const head = context.formatCommand?.(path); return head ? [head] : []; }));
+        },
+    }),
+};

package/commands/qq/endpoint/definition.ts

@@ -2,28 +2,18 @@ import { resolveLocale, type Locale } from 'zhin.js/i18n';
 import { messages as t } from '../../../src/i18n.js';
 /**
  * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
- * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
- * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
- * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
+ * list / remove 与权限共用 @zhin.js/adapter 的账号管理入口；
+ * 本文件保留 QQ 扫码绑定 add 与 cancel，保存委派捕获的所属 Adapter CAS，并导出
  * qqEndpointCommands 供 commands/qq/endpoint/ 下的命令文件默认导出。
  */
-import {
-  buildEndpointEnvKey,
-  createEndpointCommands,
-  endpointCommandForbidden,
-  endpointConfigurationStoreToken,
-  extractEndpointCommandReply,
-  formatEndpointList,
-  isEndpointOperator,
-  removeEndpointById,
-  type ConfiguredEndpointEntry,
-  type EndpointCommandReply,
-  type EndpointConfigurationStore,
-} from 'zhin.js/adapter';
+import { createEndpointCommands, endpointCommandForbidden, createDurableEndpointCommandReply, isEndpointOperator, extractEndpointCommandReply,
+  adapterFeatureId, isAdapterIndex, type ConfiguredEndpointEntry, type EndpointCommandReply } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
 import { qqBotKindPrompt, qqCommandSessionKey } from '../../../src/qq-bot-kind-prompt.js';
 import { startQqBindFlow } from '../../../src/qq-bind-flow.js';
-import { defaultQqEndpointIntentFields, type QqBotKind } from '../../../src/qq-intents.js';
+import { writeQqEndpointWithBotKind, type QqEndpointSavePort } from '../../../src/qq-endpoint-write.js';
+import type { QqBotKind } from '../../../src/qq-intents.js';
+import { cancelQqConsoleBind } from '../../../src/qq-console.js';
 import {
   qqRuntimeStateToken,
   type QqPendingBotKind,
@@ -40,7 +30,19 @@ export type QqCommandReply = EndpointCommandReply;
  * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
  */
 export function isQqEndpointOperator(config: unknown, input: unknown): boolean {
-  return isEndpointOperator(config, input);
+  if (isEndpointOperator(config, input)) return true;
+  // The outage-notify target is the operator's conversation on another adapter.
+  const cfg = (config ?? {}) as {
+    notify?: { id?: unknown };
+    endpoints?: readonly { notify?: { id?: unknown } }[];
+  };
+  const notifyIds = [
+    cfg.notify?.id,
+    ...(Array.isArray(cfg.endpoints) ? cfg.endpoints.map((endpoint) => endpoint.notify?.id) : []),
+  ];
+  const senderRaw = (input as { sender?: { id?: unknown } } | null | undefined)?.sender;
+  const senderId = (typeof senderRaw === 'object' && senderRaw?.id) ? String(senderRaw.id).trim() : '';
+  return senderId !== '' && notifyIds.some((id) => id != null && String(id) === senderId);
 }
 
 export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
@@ -57,22 +59,12 @@ function busyFooter(state: QqRuntimeState, locale?: Locale): string | undefined
   if (state.pendingBotKind) {
     return t(locale, 'kindBusy', { id: state.pendingBotKind.endpointId });
   }
+  if (state.consoleBind?.state === 'scanned') {
+    return t(locale, 'kindBusy', { id: state.consoleBind.pending?.endpointId ?? 'QQ' });
+  }
   return undefined;
 }
 
-/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
-export async function runQqEndpointList(
-  state: QqRuntimeState,
-  store: EndpointConfigurationStore,
-  locale?: Locale,
-): Promise<string> {
-  return formatEndpointList(qqEndpointListSpec, {
-    running: state.endpoints.values(),
-    configured: await store.list('qq'),
-    footer: busyFooter(state, locale), locale,
-  });
-}
-
 const qqEndpointListSpec = {
   adapterKey: 'qq',
   adapterDisplayName: 'QQ',
@@ -82,62 +74,54 @@ const qqEndpointListSpec = {
 async function writeEndpointWithBotKind(
   pending: QqPendingBotKind,
   botKind: QqBotKind,
-  store: EndpointConfigurationStore,
+  save: QqEndpointSavePort,
 ): Promise<string> {
-  const locale = pending.locale;
-  const appidKey = buildEndpointEnvKey('qq', pending.endpointId, 'appid');
-  const secretKey = buildEndpointEnvKey('qq', pending.endpointId, 'secret');
-  const intentFields = defaultQqEndpointIntentFields(botKind);
-  const { filePath } = await store.add({
-    adapterKey: 'qq',
-    entry: {
-      id: pending.endpointId,
-      appid: `\${${appidKey}}`,
-      secret: `\${${secretKey}}`,
-      botKind: intentFields.botKind,
-      intents: [...intentFields.intents],
-    },
-    environment: {
-      [appidKey]: pending.appId,
-      [secretKey]: pending.appSecret,
-    },
+  const result = await writeQqEndpointWithBotKind({
+    endpointId: pending.endpointId,
+    appId: pending.appId,
+    appSecret: pending.appSecret,
+    botKind,
+  }, save);
+  return t(pending.locale, 'endpointSaved', {
+    kind: result.botKind,
+    id: result.endpointId,
+    intents: result.intents.join(', '),
   });
-  return t(locale, 'endpointSaved', { kind: intentFields.botKind, id: pending.endpointId, file: filePath, intents: intentFields.intents.join(', ') });
 }
 
 /**
- * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
+ * 完成 pending 的公域/私域选择：通过已捕获的所属 Adapter 保存一次账号配置。
  * @returns 成功文案；调用方负责清 pending。
  */
 export async function completeQqPendingBotKind(
   pending: QqPendingBotKind,
   botKind: QqBotKind,
-  store: EndpointConfigurationStore,
 ): Promise<string> {
-  return await writeEndpointWithBotKind(pending, botKind, store);
+  return await writeEndpointWithBotKind(pending, botKind, pending.save);
 }
 
 /**
  * `qq endpoint add [id]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
- * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
+ * 扫码成功后凭据暂存内存并询问公域/私域；确认后保存到账号库，等待显式启动。
  */
 export function runQqEndpointAdd(
   state: QqRuntimeState,
   id: string | undefined,
   reply: QqCommandReply,
-  store: EndpointConfigurationStore,
+  save: QqEndpointSavePort,
   input?: unknown,
   locale: Locale = 'zh-CN',
   cancelCommand?: string,
   commandHeads?: readonly string[],
 ): Promise<string> {
-  if (state.bindFlow || state.pendingBotKind) {
+  if (state.bindFlow || state.pendingBotKind || state.consoleBind?.pending || state.consoleBind?.state === 'waiting') {
     return Promise.resolve(
       t(locale, 'existingFlow'),
     );
   }
+  state.consoleBind = null;
   const endpointId = id?.trim() || undefined;
   const sessionKey = qqCommandSessionKey(input);
   return new Promise<string>((resolve) => {
@@ -182,10 +166,10 @@ export function runQqEndpointAdd(
                     endpointId: finalName,
                     appId,
                     appSecret,
-                    sessionKey: '', locale, cancelCommand,
+                    sessionKey: '', locale, cancelCommand, save,
                   },
                   'public',
-                  store,
+                  save,
                 ) +
                 t(locale, 'noInteractiveKind'),
               );
@@ -196,7 +180,7 @@ export function runQqEndpointAdd(
               endpointId: finalName,
               appId,
               appSecret,
-              sessionKey, locale, cancelCommand, commandHeads,
+              sessionKey, locale, cancelCommand, commandHeads, save,
             };
             settle(
               t(locale, 'scanned', { id: finalName, prompt: qqBotKindPrompt(locale, cancelCommand) }),
@@ -222,6 +206,7 @@ export function runQqEndpointCancel(state: QqRuntimeState, preference?: Locale):
   if (state.bindFlow) {
     state.bindFlow.stop();
     state.bindFlow = null;
+    cancelQqConsoleBind(state);
     return t(locale, 'cancelled');
   }
   if (state.pendingBotKind) {
@@ -229,40 +214,44 @@ export function runQqEndpointCancel(state: QqRuntimeState, preference?: Locale):
     state.pendingBotKind = null;
     return t(locale, 'pendingCancelled', { name });
   }
+  if (state.consoleBind) {
+    cancelQqConsoleBind(state);
+    return t(locale, 'cancelled');
+  }
   return t(locale, 'noFlow');
 }
 
-/** `qq endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
-export async function runQqEndpointRemove(
-  _state: QqRuntimeState,
-  id: string,
-  store: EndpointConfigurationStore,
-): Promise<string> {
-  return await removeEndpointById(qqEndpointListSpec, id, store);
-}
-
 /**
  * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
  * commands/qq/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
  */
-export const qqEndpointCommands = createEndpointCommands({
+const standard = createEndpointCommands({
   ...qqEndpointListSpec,
-  fields: [
-    { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid', descriptionI18n: { en: "QQ bot app ID" } },
-    { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret', descriptionI18n: { en: "QQ bot secret" } },
-  ],
-  running: (use) => use(qqRuntimeStateToken).endpoints.values(),
+  fields: [{ key: 'appid', required: true }, { key: 'secret', required: true, secret: true }],
   listFooter: (use, locale) => busyFooter(use(qqRuntimeStateToken), locale),
-  addDescriptionI18n: { en: 'Bind a bot through mobile QQ, choose public/private, then save configuration; restart to apply' },
-  addDescription:
-    '手机 QQ 扫码绑定机器人：确认公域/私域后一次性写入 .env 与 zhin.config.yml（重启生效）',
-  bindFlow: ({ id, reply, input, use, locale, formatCommand }) =>
-    runQqEndpointAdd(
-      use(qqRuntimeStateToken),
-      id,
-      reply,
-      use(endpointConfigurationStoreToken),
-      input, locale, formatCommand?.('qq endpoint cancel'),
-      ['qq endpoint list', 'qq endpoint add', 'qq endpoint remove', 'qq endpoint cancel'].flatMap(path => { const head = formatCommand?.(path); return head ? [head] : []; }),
-    ),
 }, defineCommand);
+
+export const qqEndpointCommands = {
+  ...standard,
+  add: defineCommand({
+    description: '手机 QQ 扫码绑定；确认公域/私域后保存账号，手动启动',
+    descriptionI18n: { en: 'Scan with mobile QQ, choose public/private, save the account and start explicitly' },
+    params: { id: { type: 'string', description: 'endpoint ID' } },
+    async execute(context) {
+      if (!isEndpointOperator(context.config, context.input)) return endpointCommandForbidden('QQ', context.locale);
+      const index = context.project<unknown>(adapterFeatureId);
+      if (!isAdapterIndex(index)) throw new Error('QQ Adapter projection is unavailable');
+      const own = index.forOwner(context.owner.id).adapters().filter(adapter => adapter.descriptor.name === 'qq');
+      if (own.length !== 1) throw new Error('QQ Adapter ownership is ambiguous');
+      const adapter = own[0];
+      if (adapter.needsMigration) return '首次修改账号前，请由管理员在 Console 确认迁移账号清单';
+      if (!adapter.canManage) return '此环境未提供持久化账号管理';
+      const revision = adapter.revision;
+      const save: QqEndpointSavePort = config => adapter.add(revision, { endpointId: config.id, config: { ...config } }, { waitForExecution: false });
+      return runQqEndpointAdd(context.use(qqRuntimeStateToken), context.params.id,
+        createDurableEndpointCommandReply(context.input, context.use), save, context.input, context.locale,
+        context.formatCommand?.('qq endpoint cancel'),
+        ['qq endpoint list', 'qq endpoint add', 'qq endpoint remove', 'qq endpoint cancel'].flatMap(path => { const head = context.formatCommand?.(path); return head ? [head] : []; }));
+    },
+  }),
+};

package/lib/adapter.d.ts

@@ -0,0 +1,13 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { QqHttpEndpoint, QqWebsocketEndpoint } from './endpoint.js';
+import { type QqEndpointConfig } from './protocol.js';
+import type { QqClientEventMap } from './client.js';
+export declare class QqAdapter extends Adapter<QqHttpEndpoint | QqWebsocketEndpoint, QqEndpointConfig, QqClientEventMap> {
+    private readonly context;
+    constructor(context: AdapterContext<QqEndpointConfig>);
+    get configurationIdentityFields(): readonly string[];
+    get configurationIdentityProbeFields(): readonly string[];
+    get configurationUpdateFields(): readonly string[];
+    protected validateConfiguration(input: QqEndpointConfig): void;
+    protected createEndpoint(input: QqEndpointConfig, execution: EndpointCreationContext): QqHttpEndpoint | QqWebsocketEndpoint;
+}

package/lib/adapter.js

@@ -0,0 +1,27 @@
+import { Adapter, createAdapterOutageNotifier } from 'zhin.js/adapter';
+import { outboundHostToken } from 'zhin.js';
+import { httpHostToken } from '@zhin.js/host-http';
+import { QqHttpEndpoint, QqWebsocketEndpoint } from './endpoint.js';
+import { resolveQqConfig } from './protocol.js';
+export class QqAdapter extends Adapter {
+    context;
+    constructor(context) {
+        super();
+        this.context = context;
+    }
+    get configurationIdentityFields() { return ['id', 'appid']; }
+    get configurationIdentityProbeFields() { return ['accessTokenUrl', 'gatewayUrl']; }
+    get configurationUpdateFields() {
+        return ['secret', 'mode', 'sandbox', 'intents', 'botKind',
+            'accessTokenUrl', 'gatewayUrl', 'streamProxy', 'streamProxy.port', 'streamProxy.serverName', 'webhookPath'];
+    }
+    validateConfiguration(input) { resolveQqConfig(input); }
+    createEndpoint(input, execution) {
+        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/lib/client.d.ts

@@ -1,12 +1,10 @@
-import type { QqInboundMessage } from './protocol.js';
-import type { QqBotTransport } from './ws.js';
-export type QqClientEventMap = Record<string, QqInboundMessage | unknown>;
+import type { EventMap } from 'qq-official-bot';
+import type { QqAdapter } from './adapter.js';
+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 declare const qqClient: import("@zhin.js/adapter").EndpointClientToken<QqBotTransport, QqClientEventMap>;

package/lib/client.js

@@ -1,2 +1 @@
-import { defineEndpointClient } from 'zhin.js/adapter';
-export const qqClient = defineEndpointClient('qq');
+export {};

package/lib/console.d.ts

@@ -0,0 +1,3 @@
+import { type PluginConsoleRpc } from 'zhin.js';
+import type { QqRuntimeState } from './qq-runtime-state.js';
+export declare function createQqConsoleRpc(state: QqRuntimeState, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -0,0 +1,93 @@
+/**
+ * QQ Console RPC：除通用 endpoint 管理外，把 `qq endpoint add` 的扫码绑定
+ * （以及公域 / 私域选择、取消）搬到 Console 页面。
+ */
+import { prepareConsoleAdapterMutation, ownedConsoleAdapter, createAdapterConsoleRpc, } from 'zhin.js/adapter';
+import { PluginConsoleRpcError } from 'zhin.js';
+import { qqConsoleSpec } from './qq-console-spec.js';
+import { cancelQqConsoleBind, completeQqConsoleBind, startQqConsoleBind, } from './qq-console.js';
+export function createQqConsoleRpc(state, getConfig) {
+    const spec = {
+        ...qqConsoleSpec,
+        getConfig,
+        extraStatus: () => {
+            const bind = state.consoleBind;
+            if (!bind) {
+                return { bindState: state.bindFlow ? 'binding' : 'idle' };
+            }
+            return {
+                bindState: bind.state,
+                ...(bind.url ? { scanUrl: bind.url } : {}),
+                ...(bind.message ? { bindMessage: bind.message } : {}),
+                ...(bind.pending ? { bindEndpoint: bind.pending.endpointId } : {}),
+                ...(bind.error ? { bindError: bind.error } : {}),
+            };
+        },
+        availableActions: () => {
+            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'];
+        },
+        actions: {
+            'qq-bind-start': {
+                label: '扫码绑定新机器人',
+                labelI18n: { en: 'Bind a bot with QR' },
+                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。',
+                descriptionI18n: { en: 'Public subscribes PUBLIC_GUILD_MESSAGES; private subscribes GUILD_MESSAGES.' },
+                options: [
+                    { value: 'public', label: '公域', labelI18n: { en: 'Public' } },
+                    { value: 'private', label: '私域', labelI18n: { en: 'Private' } },
+                ],
+                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: `已保存账号「${result.endpointId}」（${result.botKind}），尚未启动`,
+                        saved: true, restartRequired: false, execution: { ...result.mutation.execution },
+                        details: { endpoint: result.endpointId, botKind: result.botKind, intents: result.intents.join(', ') },
+                    };
+                },
+            },
+            'qq-bind-cancel': {
+                label: '取消扫码绑定',
+                labelI18n: { en: 'Cancel QR binding' },
+                description: '中止正在进行的扫码绑定；已写入的配置不会删除。',
+                descriptionI18n: { en: 'Stop the current QR binding flow; already-saved configuration is untouched.' },
+                handler: async () => {
+                    const cancelled = cancelQqConsoleBind(state);
+                    return { message: cancelled ? '已取消绑定' : '当前没有进行中的绑定流程' };
+                },
+            },
+        },
+    };
+    return createAdapterConsoleRpc(spec);
+}