@zhin.js/adapter-qq 4.0.2 → 5.0.0

package/lib/qq-bind-flow.js

@@ -0,0 +1,77 @@
+/**
+ * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
+ */
+import { BindStatus, buildConnectUrl, createBindTask, decryptSecret, pollBindResult, } from './qq-bind-api.js';
+const POLL_INTERVAL_MS = 2000;
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new DOMException('Aborted', 'AbortError'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+    });
+}
+async function pollUntilResult(taskId, key, signal) {
+    while (!signal?.aborted) {
+        let result;
+        try {
+            result = await pollBindResult(taskId);
+        }
+        catch {
+            await sleep(POLL_INTERVAL_MS, signal);
+            continue;
+        }
+        if (result.status === BindStatus.COMPLETED) {
+            const appSecret = decryptSecret(result.botEncryptSecret, key);
+            return { outcome: 'scanned', appId: result.botAppId, appSecret };
+        }
+        if (result.status === BindStatus.EXPIRED) {
+            return { outcome: 'expired' };
+        }
+        await sleep(POLL_INTERVAL_MS, signal);
+    }
+    throw new DOMException('Aborted', 'AbortError');
+}
+/**
+ * 轮询等待扫码结果（回调风格）。返回 stop 函数可中止流程。
+ */
+export function startQqBindFlow(callbacks, options = {}) {
+    const controller = new AbortController();
+    const signal = options.signal
+        ? AbortSignal.any([controller.signal, options.signal])
+        : controller.signal;
+    void (async () => {
+        for (;;) {
+            if (signal.aborted) {
+                throw new DOMException('Aborted', 'AbortError');
+            }
+            let task;
+            try {
+                task = await createBindTask();
+            }
+            catch (err) {
+                throw new Error(`获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+            const connectUrl = buildConnectUrl(task.taskId, options.source ?? 'zhin');
+            await callbacks.onQrDisplayed?.(connectUrl);
+            const pollResult = await pollUntilResult(task.taskId, task.key, signal);
+            if (pollResult.outcome === 'scanned') {
+                callbacks.onSuccess([{ appId: pollResult.appId, appSecret: pollResult.appSecret }]);
+                return;
+            }
+            await callbacks.onQrExpired?.();
+        }
+    })().catch((err) => {
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return;
+        }
+        callbacks.onFailure(err instanceof Error ? err : new Error(String(err)));
+    });
+    return () => controller.abort();
+}
+//# sourceMappingURL=qq-bind-flow.js.map

package/lib/qq-bind-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qq-bind-flow.js","sourceRoot":"","sources":["../src/qq-bind-flow.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,16 @@
+import type { EndpointConfigRecord, EndpointManager, ProvisionContext } from 'zhin.js';
+import type { QQAdapter } from './adapter.js';
+export declare class QqEndpointManager implements EndpointManager {
+    private readonly adapter;
+    constructor(adapter: QQAdapter);
+    supportsProvision(): boolean;
+    listEndpoints(): EndpointConfigRecord[];
+    cancelProvision(): boolean;
+    addEndpoint(ctx: ProvisionContext): Promise<EndpointConfigRecord>;
+    editEndpoint(name: string, ctx: ProvisionContext): Promise<EndpointConfigRecord>;
+    removeEndpoint(name: string): Promise<boolean>;
+    startEndpoint(name: string, ctx: ProvisionContext): Promise<void>;
+    stopEndpoint(name: string): Promise<boolean>;
+}
+export declare function disposeQqEndpointProvision(): void;
+//# sourceMappingURL=qq-endpoint-manager.d.ts.map

package/lib/qq-endpoint-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qq-endpoint-manager.d.ts","sourceRoot":"","sources":["../src/qq-endpoint-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA4C9C,qBAAa,iBAAkB,YAAW,eAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,SAAS;IAE/C,iBAAiB,IAAI,OAAO;IAI5B,aAAa,IAAI,oBAAoB,EAAE;IAIvC,eAAe,IAAI,OAAO;IAOpB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA8CjE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAWhF,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGnD;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD"}

package/lib/qq-endpoint-manager.js

@@ -0,0 +1,124 @@
+import { ReceiverMode as QQReceiverMode } from './types.js';
+import { startQqBindFlow } from './qq-bind-flow.js';
+const DEFAULT_INTENTS = [
+    'GUILDS',
+    'GUILD_MEMBERS',
+    'GUILD_MESSAGE_REACTIONS',
+    'DIRECT_MESSAGE',
+    'GROUP_AND_C2C_EVENT',
+    'INTERACTION',
+    'MESSAGE_AUDIT',
+    'AUDIO_ACTION',
+    'PUBLIC_GUILD_MESSAGES',
+];
+function resolveQqEndpointTemplate(root) {
+    const configService = root.inject('config');
+    const doc = configService?.getPrimary?.();
+    const existing = doc?.endpoints?.find((e) => e.context === 'qq');
+    if (!existing) {
+        return {
+            mode: QQReceiverMode.WEBSOCKET,
+            sandbox: false,
+            timeout: 10_000,
+            data_dir: './data',
+            intents: [...DEFAULT_INTENTS],
+        };
+    }
+    const { name: _n, appid: _a, secret: _s, context: _c, ...rest } = existing;
+    return rest;
+}
+function readQqConfigs(root) {
+    const configService = root.inject('config');
+    if (!configService?.primaryFile || !configService.getRaw)
+        return [];
+    const raw = configService.getRaw(configService.primaryFile);
+    return (raw?.endpoints ?? []).filter((e) => e.context === 'qq');
+}
+/** 全局单例：同一时间只允许一个 QQ 扫码绑定 */
+let activeStopFlow = null;
+export class QqEndpointManager {
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    supportsProvision() {
+        return true;
+    }
+    listEndpoints() {
+        return readQqConfigs(this.adapter.plugin.root);
+    }
+    cancelProvision() {
+        if (!activeStopFlow)
+            return false;
+        activeStopFlow();
+        activeStopFlow = null;
+        return true;
+    }
+    async addEndpoint(ctx) {
+        if (activeStopFlow) {
+            throw new Error('已有进行中的 QQ 机器人绑定，请先 /endpoint cancel');
+        }
+        let endpointName;
+        const nameMatch = ctx.message.$raw?.match(/\/endpoint\s+add\s+qq\s+(\S+)/);
+        if (nameMatch?.[1]) {
+            endpointName = nameMatch[1];
+        }
+        return new Promise((resolve, reject) => {
+            const stopFlow = startQqBindFlow({
+                onQrDisplayed: async (url) => {
+                    await ctx.onStatusUpdate('请用手机 QQ 扫描下方二维码完成机器人绑定（source=zhin）。', {
+                        qrcode: url,
+                    });
+                },
+                onQrExpired: async () => {
+                    await ctx.onStatusUpdate('二维码已过期，正在刷新，请扫描新二维码…');
+                },
+                onSuccess: async (credentials) => {
+                    activeStopFlow = null;
+                    const [{ appId, appSecret }] = credentials;
+                    const name = endpointName?.trim() || appId;
+                    const template = resolveQqEndpointTemplate(ctx.root);
+                    resolve({
+                        context: 'qq',
+                        name,
+                        appid: appId,
+                        secret: appSecret,
+                        ...template,
+                    });
+                },
+                onFailure: async (error) => {
+                    activeStopFlow = null;
+                    reject(error);
+                },
+            }, { source: 'zhin' });
+            activeStopFlow = stopFlow;
+        });
+    }
+    async editEndpoint(name, ctx) {
+        const existing = this.listEndpoints().find((e) => e.name === name);
+        if (!existing) {
+            throw new Error(`配置中不存在 qq/${name}`);
+        }
+        await ctx.onStatusUpdate(`QQ 官方机器人暂不支持在线改凭据，请 /endpoint remove qq ${name} 后重新 /endpoint add qq。`);
+        return existing;
+    }
+    async removeEndpoint(name) {
+        return this.listEndpoints().some((e) => e.name === name);
+    }
+    async startEndpoint(name, ctx) {
+        if (!this.listEndpoints().some((e) => e.name === name)) {
+            throw new Error(`配置中不存在 qq/${name}`);
+        }
+        await ctx.onStatusUpdate(`正在连接 qq/${name}…`);
+    }
+    async stopEndpoint(name) {
+        return this.adapter.endpoints.has(name);
+    }
+}
+export function disposeQqEndpointProvision() {
+    if (activeStopFlow) {
+        activeStopFlow();
+        activeStopFlow = null;
+    }
+}
+//# sourceMappingURL=qq-endpoint-manager.js.map

package/lib/qq-endpoint-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qq-endpoint-manager.js","sourceRoot":"","sources":["../src/qq-endpoint-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "4.0.2",
+  "version": "5.0.0",
   "description": "Zhin.js adapter for QQ Official Bot",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,23 +39,23 @@
   "devDependencies": {
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "lucide-react": "^1.17.0",
+    "lucide-react": "^1.21.0",
     "typescript": "^6.0.3",
+    "@zhin.js/cli": "1.0.91",
     "@zhin.js/client": "2.0.3",
     "@zhin.js/contract": "1.0.1",
-    "@zhin.js/host-api": "2.0.2",
-    "@zhin.js/cli": "1.0.90",
-    "@zhin.js/host-router": "2.0.0",
-    "zhin.js": "4.0.1",
-    "@zhin.js/logger": "0.1.71"
+    "@zhin.js/host-api": "2.0.3",
+    "@zhin.js/host-router": "2.0.1",
+    "@zhin.js/logger": "1.0.72",
+    "zhin.js": "4.1.0"
   },
   "peerDependencies": {
     "@zhin.js/client": "2.0.3",
-    "@zhin.js/host-api": "2.0.2",
-    "@zhin.js/host-router": "2.0.0",
-    "@zhin.js/logger": "0.1.71",
+    "@zhin.js/host-api": "2.0.3",
     "@zhin.js/contract": "1.0.1",
-    "zhin.js": "4.0.1"
+    "@zhin.js/host-router": "2.0.1",
+    "@zhin.js/logger": "1.0.72",
+    "zhin.js": "4.1.0"
   },
   "peerDependenciesMeta": {
     "@zhin.js/client": {

package/src/adapter.ts

@@ -6,13 +6,22 @@ import {
   Plugin,
 } from "zhin.js";
 import type { Router } from "@zhin.js/host-router";
+import type { EndpointManager } from "zhin.js";
 import { QQEndpoint } from "./endpoint.js";
+import { QqEndpointManager } from "./qq-endpoint-manager.js";
 import type { QQEndpointConfig, ReceiverMode } from "./types.js";
+import type { OutboundRichSegmentPolicy } from "zhin.js";
 
 export class QQAdapter extends Adapter<QQEndpoint<ReceiverMode>> {
   static override readonly capabilities = ['inbound', 'outbound'] as const;
+  static override outboundRichSegmentPolicy: OutboundRichSegmentPolicy = {
+    qrcode: 'image',
+    html: 'image',
+    markdown: 'origin',
+  };
 
   #router?: Router;
+  #endpointManager?: QqEndpointManager;
 
   constructor(plugin: Plugin, router?: Router) {
     super(plugin, "qq", []);
@@ -27,6 +36,13 @@ export class QQAdapter extends Adapter<QQEndpoint<ReceiverMode>> {
     return new QQEndpoint(this, config);
   }
 
+  override getEndpointManager(): EndpointManager {
+    if (!this.#endpointManager) {
+      this.#endpointManager = new QqEndpointManager(this);
+    }
+    return this.#endpointManager;
+  }
+
   // ── IGroupManagement 标准群管方法 ──────────────────────────────────
 
   async kickMember(endpointId: string, sceneId: string, userId: string) {

package/src/endpoint.ts

@@ -14,8 +14,7 @@ import {
   Message,
   SendOptions,
   SendContent,
-  segment,
-} from "zhin.js";
+  segment,} from 'zhin.js';
 import type { MessageElement } from "zhin.js";
 import { ReceiverMode, type QQEndpointConfig, type ApplicationPlatform } from "./types.js";
 import type { QQAdapter } from "./adapter.js";

package/src/index.ts

@@ -11,6 +11,7 @@ import {
   qqGuildPermitResolver,
   registerQqPlatformPermitChecker,
 } from "./platform-permit.js";
+import { disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
 
 declare module "zhin.js" {
   namespace Plugin {
@@ -30,9 +31,12 @@ declare module "zhin.js" {
 export * from "./types.js";
 export { QQEndpoint } from "./endpoint.js";
 export { QQAdapter } from "./adapter.js";
+export { startQqBindFlow } from "./qq-bind-flow.js";
+export * from "./qq-bind-api.js";
+export { QqEndpointManager, disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
 
 const plugin = usePlugin();
-const { provide, useContext } = plugin;
+const { provide, useContext, onDispose } = plugin;
 
 useContext("router", (router: Router) => {
   provide({
@@ -361,3 +365,7 @@ useContext("router", "qq", (router: any, qq: QQAdapter) => {
     }
   });
 });
+
+onDispose(() => {
+  disposeQqEndpointProvision();
+});

package/src/qq-bind-api.ts

@@ -0,0 +1,126 @@
+/**
+ * QQ Bot 扫码绑定协议（内联）
+ * Protocol aligned with @tencent-connect/qqbot-connector@1.1.0 qqbot-session — inlined to avoid runtime dependency.
+ */
+import { createDecipheriv, randomBytes } from 'node:crypto';
+
+export type QQBotEnv = 'production' | 'test';
+
+const HOSTS: Record<QQBotEnv, string> = {
+  production: 'q.qq.com',
+  test: 'test.q.qq.com',
+};
+
+export enum BindStatus {
+  NONE = 0,
+  PENDING = 1,
+  COMPLETED = 2,
+  EXPIRED = 3,
+}
+
+export function getQQBotHost(env: QQBotEnv = 'production'): string {
+  return HOSTS[env];
+}
+
+export function generateBindKey(): string {
+  return randomBytes(32).toString('base64');
+}
+
+export function buildConnectUrl(taskId: string, source = 'zhin'): string {
+  return `https://${getQQBotHost('production')}/qqbot/openclaw/connect.html?task_id=${encodeURIComponent(taskId)}&source=${encodeURIComponent(source)}&_wv=2`;
+}
+
+/**
+ * AES-256-GCM 解密 base64 密文。
+ * 密文格式: IV(12 bytes) + ciphertext + AuthTag(16 bytes)
+ */
+export function decryptSecret(encryptedBase64: string, keyBase64: string): string {
+  const key = Buffer.from(keyBase64, 'base64');
+  const payload = Buffer.from(encryptedBase64, 'base64');
+  const iv = payload.subarray(0, 12);
+  const authTag = payload.subarray(payload.length - 16);
+  const ciphertext = payload.subarray(12, payload.length - 16);
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}
+
+interface LiteApiResponse<T> {
+  retcode: number;
+  msg?: string;
+  data?: T;
+}
+
+async function postJson<T>(
+  url: string,
+  body: Record<string, unknown>,
+  timeoutMs: number,
+): Promise<LiteApiResponse<T>> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status} from ${url}`);
+    }
+    return (await res.json()) as LiteApiResponse<T>;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface BindTaskResult {
+  taskId: string;
+  key: string;
+}
+
+export async function createBindTask(
+  env: QQBotEnv = 'production',
+  timeoutMs = 10_000,
+): Promise<BindTaskResult> {
+  const url = `https://${getQQBotHost(env)}/lite/create_bind_task`;
+  const key = generateBindKey();
+  const res = await postJson<{ task_id?: string }>(url, { key }, timeoutMs);
+  if (res.retcode !== 0) {
+    throw new Error(res.msg ?? 'create_bind_task failed');
+  }
+  if (!res.data?.task_id) {
+    throw new Error('create_bind_task: missing task_id');
+  }
+  return { taskId: res.data.task_id, key };
+}
+
+export interface PollBindResultOk {
+  status: BindStatus;
+  botAppId: string;
+  botEncryptSecret: string;
+}
+
+export async function pollBindResult(
+  taskId: string,
+  env: QQBotEnv = 'production',
+  timeoutMs = 10_000,
+): Promise<PollBindResultOk> {
+  const url = `https://${getQQBotHost(env)}/lite/poll_bind_result`;
+  const res = await postJson<{
+    status?: number;
+    bot_appid?: string | number;
+    bot_encrypt_secret?: string;
+  }>(url, { task_id: taskId }, timeoutMs);
+  if (res.retcode !== 0) {
+    throw new Error(res.msg ?? 'poll_bind_result failed');
+  }
+  return {
+    status: (res.data?.status ?? BindStatus.NONE) as BindStatus,
+    botAppId: String(res.data?.bot_appid ?? ''),
+    botEncryptSecret: res.data?.bot_encrypt_secret ?? '',
+  };
+}

package/src/qq-bind-flow.ts

@@ -0,0 +1,117 @@
+/**
+ * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
+ */
+import {
+  BindStatus,
+  buildConnectUrl,
+  createBindTask,
+  decryptSecret,
+  pollBindResult,
+} from './qq-bind-api.js';
+
+const POLL_INTERVAL_MS = 2000;
+
+export interface QqBindCredentials {
+  appId: string;
+  appSecret: string;
+}
+
+export interface QqBindCallbacks {
+  onSuccess: (credentials: QqBindCredentials[]) => void;
+  onFailure: (error: Error) => void;
+  onQrDisplayed?: (url: string) => void | Promise<void>;
+  onQrExpired?: () => void | Promise<void>;
+}
+
+export interface QqBindFlowOptions {
+  signal?: AbortSignal;
+  source?: string;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException('Aborted', 'AbortError'));
+      },
+      { once: true },
+    );
+  });
+}
+
+async function pollUntilResult(
+  taskId: string,
+  key: string,
+  signal?: AbortSignal,
+): Promise<{ outcome: 'scanned'; appId: string; appSecret: string } | { outcome: 'expired' }> {
+  while (!signal?.aborted) {
+    let result;
+    try {
+      result = await pollBindResult(taskId);
+    } catch {
+      await sleep(POLL_INTERVAL_MS, signal);
+      continue;
+    }
+    if (result.status === BindStatus.COMPLETED) {
+      const appSecret = decryptSecret(result.botEncryptSecret, key);
+      return { outcome: 'scanned', appId: result.botAppId, appSecret };
+    }
+    if (result.status === BindStatus.EXPIRED) {
+      return { outcome: 'expired' };
+    }
+    await sleep(POLL_INTERVAL_MS, signal);
+  }
+  throw new DOMException('Aborted', 'AbortError');
+}
+
+/**
+ * 轮询等待扫码结果（回调风格）。返回 stop 函数可中止流程。
+ */
+export function startQqBindFlow(
+  callbacks: QqBindCallbacks,
+  options: QqBindFlowOptions = {},
+): () => void {
+  const controller = new AbortController();
+  const signal = options.signal
+    ? AbortSignal.any([controller.signal, options.signal])
+    : controller.signal;
+
+  void (async () => {
+    for (;;) {
+      if (signal.aborted) {
+        throw new DOMException('Aborted', 'AbortError');
+      }
+      let task;
+      try {
+        task = await createBindTask();
+      } catch (err) {
+        throw new Error(
+          `获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`,
+          { cause: err },
+        );
+      }
+      const connectUrl = buildConnectUrl(task.taskId, options.source ?? 'zhin');
+      await callbacks.onQrDisplayed?.(connectUrl);
+      const pollResult = await pollUntilResult(task.taskId, task.key, signal);
+      if (pollResult.outcome === 'scanned') {
+        callbacks.onSuccess([{ appId: pollResult.appId, appSecret: pollResult.appSecret }]);
+        return;
+      }
+      await callbacks.onQrExpired?.();
+    }
+  })().catch((err) => {
+    if (err instanceof DOMException && err.name === 'AbortError') {
+      return;
+    }
+    callbacks.onFailure(err instanceof Error ? err : new Error(String(err)));
+  });
+
+  return () => controller.abort();
+}