@zhin.js/adapter-qq 1.1.16 → 1.1.18

package/lib/qq-endpoint-write.d.ts

@@ -0,0 +1,22 @@
+/**
+ * QQ endpoint 配置写回：扫码成功后把 appId / appSecret 写进 `.env`，
+ * 配置里只保留 `${ENV}` 引用，并按公域 / 私域展开 intents。
+ *
+ * 命令（`qq endpoint add`）与 Console 扫码绑定共用这一处实现。
+ */
+import { type EndpointConfigurationStore } from 'zhin.js/adapter';
+import { type QqBotKind } from './qq-intents.js';
+export interface QqEndpointWriteInput {
+    readonly endpointId: string;
+    readonly appId: string;
+    readonly appSecret: string;
+    readonly botKind: QqBotKind;
+}
+export interface QqEndpointWriteResult {
+    readonly filePath: string;
+    readonly endpointId: string;
+    readonly botKind: QqBotKind;
+    readonly intents: readonly string[];
+}
+/** 写回 `.env` + `zhin.config.yml`；失败时抛原错误，由调用方决定文案。 */
+export declare function writeQqEndpointWithBotKind(input: QqEndpointWriteInput, store: EndpointConfigurationStore): Promise<QqEndpointWriteResult>;

package/lib/qq-endpoint-write.js

@@ -0,0 +1,34 @@
+/**
+ * QQ endpoint 配置写回：扫码成功后把 appId / appSecret 写进 `.env`，
+ * 配置里只保留 `${ENV}` 引用，并按公域 / 私域展开 intents。
+ *
+ * 命令（`qq endpoint add`）与 Console 扫码绑定共用这一处实现。
+ */
+import { buildEndpointEnvKey } from 'zhin.js/adapter';
+import { defaultQqEndpointIntentFields } from './qq-intents.js';
+/** 写回 `.env` + `zhin.config.yml`；失败时抛原错误，由调用方决定文案。 */
+export async function writeQqEndpointWithBotKind(input, store) {
+    const appidKey = buildEndpointEnvKey('qq', input.endpointId, 'appid');
+    const secretKey = buildEndpointEnvKey('qq', input.endpointId, 'secret');
+    const intentFields = defaultQqEndpointIntentFields(input.botKind);
+    const { filePath } = await store.add({
+        adapterKey: 'qq',
+        entry: {
+            id: input.endpointId,
+            appid: `\${${appidKey}}`,
+            secret: `\${${secretKey}}`,
+            botKind: intentFields.botKind,
+            intents: [...intentFields.intents],
+        },
+        environment: {
+            [appidKey]: input.appId,
+            [secretKey]: input.appSecret,
+        },
+    });
+    return {
+        filePath,
+        endpointId: input.endpointId,
+        botKind: intentFields.botKind,
+        intents: intentFields.intents,
+    };
+}

package/lib/qq-runtime-state.d.ts

@@ -24,6 +24,23 @@ export interface QqPendingBotKind {
     readonly cancelCommand?: string;
     readonly commandHeads?: readonly string[];
 }
+/**
+ * Console 发起的扫码绑定进度。凭据（appSecret）只留在内存，
+ * status 只暴露状态、扫码链接与目标 endpoint id。
+ */
+export interface QqConsoleBindState {
+    readonly state: 'waiting' | 'scanned' | 'failed';
+    readonly url?: string;
+    readonly message?: string;
+    readonly error?: string;
+    readonly startedAt: number;
+    /** 扫码成功后暂存，确认公域/私域后写配置。 */
+    readonly pending?: {
+        readonly endpointId: string;
+        readonly appId: string;
+        readonly appSecret: string;
+    };
+}
 export interface QqRuntimeState {
     /** 当前 generation 已成功创建的 endpoint（id → 描述） */
     readonly endpoints: Map<string, QqRunningEndpoint>;
@@ -31,6 +48,8 @@ export interface QqRuntimeState {
     bindFlow: QqBindFlowHandle | null;
     /** 扫码完成后等待 botKind 选择（凭据仅在内存） */
     pendingBotKind: QqPendingBotKind | null;
+    /** Console 页面的扫码绑定进度（与 bindFlow 共享单例）。 */
+    consoleBind: QqConsoleBindState | null;
 }
 export declare function createQqRuntimeState(): QqRuntimeState;
 export declare const qqRuntimeStateToken: import("zhin.js").Token<QqRuntimeState>;

package/lib/qq-runtime-state.js

@@ -9,6 +9,7 @@ export function createQqRuntimeState() {
         endpoints: new Map(),
         bindFlow: null,
         pendingBotKind: null,
+        consoleBind: null,
     };
 }
 export const qqRuntimeStateToken = createToken('zhin.qq.runtime-state', 'QQ adapter runtime state (running endpoints + bind flow singleton)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "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.23",
+    "@zhin.js/adapter": "1.1.25",
     "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.51",
+    "@zhin.js/client": "1.1.21",
+    "@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.10",
-    "@zhin.js/im-contract": "1.1.7",
+    "@zhin.js/host-http": "1.1.11",
+    "@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.10"
+    "@zhin.js/tool": "1.1.12"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.23",
+    "@zhin.js/adapter": "^1.1.25",
     "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.51",
+    "@zhin.js/core": "^1.1.53",
     "@zhin.js/middleware": "^1.1.10",
-    "zhin.js": "^1.1.16"
+    "zhin.js": "^1.1.18"
   },
   "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.10",
-    "zhin.js": "1.1.16"
+    "@zhin.js/host-http": "1.1.11",
+    "zhin.js": "1.1.18"
   },
   "files": [
     "adapters",
     "commands",
     "middlewares",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -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,15 +1,18 @@
 // 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";
 export default definePlugin({
     name: 'qq',
     metadata: {
         displayName: 'QQ Official WebSocket Adapter',
     },
     setup(context) {
-        context.resources.provide(qqRuntimeStateToken, createQqRuntimeState());
+        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);

package/schema.json

@@ -197,6 +197,93 @@
               }
             },
             "description": "Optional fixed loopback TCP fault proxy for WSS only; original gateway TLS identity must match serverName."
+          },
+          "notify": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "掉线/登录失败时通过另一个适配器实例给 master 发通知（adapter/endpoint/kind/id 指向实际会话）",
+            "x-i18n": {
+              "en": {
+                "description": "Send outage/login notices to the master through another adapter instance (adapter/endpoint/kind/id identify the actual conversation)."
+              }
+            },
+            "properties": {
+              "adapter": {
+                "type": "string",
+                "description": "通知使用的适配器类型，如 qq / icqq",
+                "x-i18n": {
+                  "en": {
+                    "description": "Adapter type used for the notice, such as qq or icqq."
+                  }
+                }
+              },
+              "endpoint": {
+                "type": "string",
+                "description": "该适配器的 endpoint id",
+                "x-i18n": {
+                  "en": {
+                    "description": "Endpoint id of that adapter."
+                  }
+                }
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "private",
+                  "group",
+                  "channel"
+                ],
+                "default": "private",
+                "description": "会话类型，默认 private",
+                "x-i18n": {
+                  "en": {
+                    "description": "Conversation kind; defaults to private."
+                  }
+                }
+              },
+              "id": {
+                "type": [
+                  "string",
+                  "number"
+                ],
+                "description": "master 在该平台上的会话 id（QQ 官方为 openid，ICQQ 为 QQ 号）",
+                "x-i18n": {
+                  "en": {
+                    "description": "Master conversation id on that platform (openid for QQ official, QQ number for ICQQ)."
+                  }
+                }
+              },
+              "parent": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "private",
+                      "group",
+                      "channel"
+                    ]
+                  },
+                  "id": {
+                    "type": [
+                      "string",
+                      "number"
+                    ]
+                  }
+                },
+                "required": [
+                  "kind",
+                  "id"
+                ],
+                "description": "可选的父频道/群容器"
+              }
+            },
+            "required": [
+              "adapter",
+              "endpoint",
+              "id"
+            ]
           }
         },
         "required": [
@@ -240,6 +327,93 @@
         }
       },
       "description": "Optional fixed loopback TCP fault proxy for WSS only; original gateway TLS identity must match serverName."
+    },
+    "notify": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "掉线/登录失败时通过另一个适配器实例给 master 发通知（adapter/endpoint/kind/id 指向实际会话）",
+      "x-i18n": {
+        "en": {
+          "description": "Send outage/login notices to the master through another adapter instance (adapter/endpoint/kind/id identify the actual conversation)."
+        }
+      },
+      "properties": {
+        "adapter": {
+          "type": "string",
+          "description": "通知使用的适配器类型，如 qq / icqq",
+          "x-i18n": {
+            "en": {
+              "description": "Adapter type used for the notice, such as qq or icqq."
+            }
+          }
+        },
+        "endpoint": {
+          "type": "string",
+          "description": "该适配器的 endpoint id",
+          "x-i18n": {
+            "en": {
+              "description": "Endpoint id of that adapter."
+            }
+          }
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "private",
+            "group",
+            "channel"
+          ],
+          "default": "private",
+          "description": "会话类型，默认 private",
+          "x-i18n": {
+            "en": {
+              "description": "Conversation kind; defaults to private."
+            }
+          }
+        },
+        "id": {
+          "type": [
+            "string",
+            "number"
+          ],
+          "description": "master 在该平台上的会话 id（QQ 官方为 openid，ICQQ 为 QQ 号）",
+          "x-i18n": {
+            "en": {
+              "description": "Master conversation id on that platform (openid for QQ official, QQ number for ICQQ)."
+            }
+          }
+        },
+        "parent": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "private",
+                "group",
+                "channel"
+              ]
+            },
+            "id": {
+              "type": [
+                "string",
+                "number"
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "id"
+          ],
+          "description": "可选的父频道/群容器"
+        }
+      },
+      "required": [
+        "adapter",
+        "endpoint",
+        "id"
+      ]
     }
   },
   "required": [

package/src/console.ts

@@ -0,0 +1,96 @@
+/**
+ * QQ Console RPC：除通用 endpoint 管理外，把 `qq endpoint add` 的扫码绑定
+ * （以及公域 / 私域选择、取消）搬到 Console 页面。
+ */
+import {
+  endpointConfigurationStoreToken,
+  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';
+import {
+  cancelQqConsoleBind,
+  completeQqConsoleBind,
+  startQqConsoleBind,
+} from './qq-console.js';
+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;
+      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 (!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'];
+    },
+    actions: {
+      '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);
+          return { message: '请用手机 QQ 扫码；扫码成功后选择公域或私域', url };
+        },
+      },
+      'qq-bind-kind': {
+        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) => {
+          if (!store) throw new PluginConsoleRpcError('unsupported', '当前运行环境不支持写入 endpoint 配置');
+          const result = await completeQqConsoleBind(state, store, input.value);
+          return {
+            message: `已写入 endpoint「${result.endpointId}」（${result.botKind}），重启或热重载后生效`,
+            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, resources);
+}