@zhin.js/adapter-qq 4.0.2 → 5.0.1

package/src/qq-bind-api.ts

@@ -0,0 +1,145 @@
+/**
+ * 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;
+  /** 扫码绑定开发者 QQ 的 OpenID（poll_bind_result 返回） */
+  userOpenId: string;
+}
+
+export function parsePollBindResultData(data: {
+  status?: number;
+  bot_appid?: string | number;
+  bot_encrypt_secret?: string;
+  user_openid?: string;
+  userOpenid?: string;
+  openid?: string;
+} | undefined): PollBindResultOk {
+  return {
+    status: (data?.status ?? BindStatus.NONE) as BindStatus,
+    botAppId: String(data?.bot_appid ?? ''),
+    botEncryptSecret: data?.bot_encrypt_secret ?? '',
+    userOpenId: String(
+      data?.user_openid ?? data?.userOpenid ?? data?.openid ?? '',
+    ),
+  };
+}
+
+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;
+    user_openid?: string;
+    userOpenid?: string;
+    openid?: string;
+  }>(url, { task_id: taskId }, timeoutMs);
+  if (res.retcode !== 0) {
+    throw new Error(res.msg ?? 'poll_bind_result failed');
+  }
+  return parsePollBindResultData(res.data);
+}

package/src/qq-bind-flow.ts

@@ -0,0 +1,127 @@
+/**
+ * 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;
+  userOpenId?: 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; userOpenId: 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,
+        userOpenId: result.userOpenId,
+      };
+    }
+    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,
+          userOpenId: pollResult.userOpenId || undefined,
+        }]);
+        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();
+}

package/src/qq-bind-persist.ts

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runtimeCwd } from 'zhin.js';
+
+export interface QqCredentialEnvKeys {
+  appidKey: string;
+  secretKey: string;
+  appidRef: string;
+  secretRef: string;
+}
+
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MOCK_QQ_BOT_APPID`） */
+export function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvKeys {
+  const slug = endpointName.replace(/[^a-zA-Z0-9_]/g, '_').toUpperCase();
+  const appidKey = `QQ_${slug}_APPID`;
+  const secretKey = `QQ_${slug}_SECRET`;
+  return {
+    appidKey,
+    secretKey,
+    appidRef: `\${${appidKey}}`,
+    secretRef: `\${${secretKey}}`,
+  };
+}
+
+function resolveProjectRoot(): string {
+  const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
+  return path.resolve(envRoot || runtimeCwd());
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function upsertEnvLine(content: string, key: string, value: string): string {
+  const lineRe = new RegExp(`^${escapeRegExp(key)}\\s*=.*$`, 'm');
+  const newLine = `${key}=${value}`;
+  if (lineRe.test(content)) {
+    return content.replace(lineRe, newLine);
+  }
+  const trimmed = content.replace(/\s*$/, '');
+  if (trimmed.length === 0) {
+    return `${newLine}\n`;
+  }
+  return `${trimmed}\n${newLine}\n`;
+}
+
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export function persistQqCredentialsToEnv(
+  endpointName: string,
+  appId: string,
+  appSecret: string,
+  projectRoot?: string,
+): QqCredentialEnvKeys {
+  const keys = buildQqCredentialEnvKeys(endpointName);
+  const root = projectRoot ?? resolveProjectRoot();
+  const envPath = path.join(root, '.env');
+  let content = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : '';
+
+  const entries: Record<string, string> = {
+    [keys.appidKey]: appId,
+    [keys.secretKey]: appSecret,
+  };
+
+  for (const [key, value] of Object.entries(entries)) {
+    content = upsertEnvLine(content, key, value);
+    process.env[key] = value;
+  }
+
+  fs.writeFileSync(envPath, content);
+  return keys;
+}

package/src/qq-endpoint-manager.ts

@@ -0,0 +1,199 @@
+import type {
+  EndpointConfigRecord,
+  EndpointManager,
+  ProvisionContext,
+} from 'zhin.js';
+import type { QQAdapter } from './adapter.js';
+import type { QQEndpointConfig, ReceiverMode } from './types.js';
+import { ReceiverMode as QQReceiverMode } from './types.js';
+import { startQqBindFlow } from './qq-bind-flow.js';
+import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
+
+const DEFAULT_INTENTS = [
+  'GUILDS',
+  'GUILD_MEMBERS',
+  'GUILD_MESSAGE_REACTIONS',
+  'DIRECT_MESSAGE',
+  'GROUP_AND_C2C_EVENT',
+  'INTERACTION',
+  'MESSAGE_AUDIT',
+  'AUDIO_ACTION',
+  'PUBLIC_GUILD_MESSAGES',
+] as const;
+
+function clonePlainConfig<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function resolveQqEndpointTemplate(root: ProvisionContext['root']): Partial<QQEndpointConfig<ReceiverMode>> {
+  const configService = root.inject('config') as {
+    getRaw?: (f: string) => { endpoints?: Array<Record<string, unknown>> };
+    primaryFile?: string;
+  } | undefined;
+  const raw = configService?.primaryFile && configService.getRaw
+    ? configService.getRaw(configService.primaryFile)
+    : undefined;
+  const existing = raw?.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 clonePlainConfig(rest) as Partial<QQEndpointConfig<ReceiverMode>>;
+}
+
+function resolveBindOperatorId(
+  userOpenId: string | undefined,
+  ctx: ProvisionContext,
+): string {
+  const fromApi = userOpenId?.trim();
+  if (fromApi) return fromApi;
+  return ctx.message.$sender?.id?.trim() ?? '';
+}
+
+function applyBindOwnership(
+  template: Partial<QQEndpointConfig<ReceiverMode>>,
+  operatorId: string,
+): Partial<QQEndpointConfig<ReceiverMode>> {
+  const { master: _m, aiAccess, ...rest } = template as Record<string, unknown>;
+  if (!operatorId) {
+    return rest as Partial<QQEndpointConfig<ReceiverMode>>;
+  }
+  const prior = aiAccess as {
+    mode?: string;
+    groups?: string[];
+    denyMessage?: string;
+  } | undefined;
+  return {
+    ...rest,
+    master: operatorId,
+    aiAccess: {
+      mode: prior?.mode ?? 'whitelist',
+      users: [operatorId],
+      groups: Array.isArray(prior?.groups) ? [...prior.groups] : [],
+      denyMessage:
+        typeof prior?.denyMessage === 'string'
+          ? prior.denyMessage
+          : '当前用户尚未开放 AI 功能，请联系开启。',
+    },
+  } as Partial<QQEndpointConfig<ReceiverMode>>;
+}
+
+function readQqConfigs(root: ProvisionContext['root']): EndpointConfigRecord[] {
+  const configService = root.inject('config') as { getRaw?: (f: string) => { endpoints?: EndpointConfigRecord[] } ; primaryFile?: string } | undefined;
+  if (!configService?.primaryFile || !configService.getRaw) return [];
+  const raw = configService.getRaw(configService.primaryFile);
+  return (raw?.endpoints ?? []).filter((e) => e.context === 'qq');
+}
+
+/** 全局单例：同一时间只允许一个 QQ 扫码绑定 */
+let activeStopFlow: (() => void) | null = null;
+
+export class QqEndpointManager implements EndpointManager {
+  constructor(private readonly adapter: QQAdapter) {}
+
+  supportsProvision(): boolean {
+    return true;
+  }
+
+  listEndpoints(): EndpointConfigRecord[] {
+    return readQqConfigs(this.adapter.plugin.root);
+  }
+
+  cancelProvision(): boolean {
+    if (!activeStopFlow) return false;
+    activeStopFlow();
+    activeStopFlow = null;
+    return true;
+  }
+
+  async addEndpoint(ctx: ProvisionContext): Promise<EndpointConfigRecord> {
+    if (activeStopFlow) {
+      throw new Error('已有进行中的 QQ 机器人绑定，请先 /endpoint cancel');
+    }
+
+    let endpointName: string | undefined;
+    const nameMatch = ctx.message.$raw?.match(/\/endpoint\s+add\s+qq\s+(\S+)/);
+    if (nameMatch?.[1]) {
+      endpointName = nameMatch[1];
+    }
+
+    return new Promise<EndpointConfigRecord>((resolve, reject) => {
+      const stopFlow = startQqBindFlow(
+        {
+          onQrDisplayed: async (url) => {
+            await ctx.onStatusUpdate('请用手机 QQ 扫描二维码完成机器人绑定。', {
+              qrcode: url,
+            });
+          },
+          onQrExpired: async () => {
+            await ctx.onStatusUpdate('二维码已过期，正在刷新，请扫描新二维码…');
+          },
+          onSuccess: async (credentials) => {
+            activeStopFlow = null;
+            const [{ appId, appSecret, userOpenId }] = credentials;
+            const name = endpointName?.trim() || appId;
+            await ctx.onStatusUpdate(
+              '凭据绑定成功，正在写入配置…',
+            );
+            const envKeys = persistQqCredentialsToEnv(name, appId, appSecret);
+            const template = resolveQqEndpointTemplate(ctx.root);
+            const operatorId = resolveBindOperatorId(userOpenId, ctx);
+            const owned = applyBindOwnership(template, operatorId);
+            resolve({
+              context: 'qq',
+              name,
+              appid: envKeys.appidRef,
+              secret: envKeys.secretRef,
+              ...owned,
+            } as EndpointConfigRecord);
+          },
+          onFailure: async (error) => {
+            activeStopFlow = null;
+            reject(error);
+          },
+        },
+        { source: 'zhin' },
+      );
+      activeStopFlow = stopFlow;
+    });
+  }
+
+  async editEndpoint(name: string, ctx: ProvisionContext): Promise<EndpointConfigRecord> {
+    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: string): Promise<boolean> {
+    return this.listEndpoints().some((e) => e.name === name);
+  }
+
+  async startEndpoint(name: string, ctx: ProvisionContext): Promise<void> {
+    if (!this.listEndpoints().some((e) => e.name === name)) {
+      throw new Error(`配置中不存在 qq/${name}`);
+    }
+    await ctx.onStatusUpdate(`正在连接 qq/${name}…`);
+  }
+
+  async stopEndpoint(name: string): Promise<boolean> {
+    return this.adapter.endpoints.has(name);
+  }
+}
+
+export function disposeQqEndpointProvision(): void {
+  if (activeStopFlow) {
+    activeStopFlow();
+    activeStopFlow = null;
+  }
+}

package/src/segment-mapper.ts

@@ -0,0 +1 @@
+export { toCanonicalSegments, fromCanonicalSegments } from 'zhin.js';

package/src/types.ts

@@ -36,6 +36,13 @@ export type QQEndpointConfig<
    * - `false`：保持纯文本
    */
   outboundMarkdown?: boolean | "auto";
+  /** 本 Endpoint AI 访问控制（见 docs/advanced/content-moderation.md） */
+  aiAccess?: {
+    mode?: 'open' | 'closed' | 'whitelist';
+    users?: string[];
+    groups?: string[];
+    denyMessage?: string;
+  };
 };
 
 export interface QQEndpoint<