@zhin.js/adapter-qq 1.1.17 → 1.1.19

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/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

@@ -0,0 +1,103 @@
+/**
+ * QQ Console RPC：除通用 endpoint 管理外，把 `qq endpoint add` 的扫码绑定
+ * （以及公域 / 私域选择、取消）搬到 Console 页面。
+ */
+import {
+  prepareConsoleAdapterMutation,
+  ownedConsoleAdapter,
+  createAdapterConsoleRpc,
+  type AdapterConsoleSpec,
+} 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,
+  getConfig: () => unknown,
+): PluginConsoleRpc {
+  const spec: AdapterConsoleSpec = {
+    ...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);
+}