@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/adapter/setup.ts

@@ -0,0 +1,55 @@
+/**
+ * Setup 工具动态加载（plugin-sdk/setup + plugin-sdk/setup-tools）
+ *
+ * 新版本 openclaw 有这些导出，旧版本可能缺失。
+ * 不可用时提供最小降级实现。
+ */
+import { createRequire } from 'node:module';
+
+const req = createRequire(__filename);
+
+let _setup: typeof import('openclaw/plugin-sdk/setup') | null | undefined;
+let _tools: typeof import('openclaw/plugin-sdk/setup-tools') | null | undefined;
+
+function loadSetup() {
+  if (_setup !== undefined) return _setup;
+  try { _setup = req('openclaw/plugin-sdk/setup'); } catch { _setup = null; }
+  return _setup;
+}
+
+function loadTools() {
+  if (_tools !== undefined) return _tools;
+  try { _tools = req('openclaw/plugin-sdk/setup-tools'); } catch { _tools = null; }
+  return _tools;
+}
+
+export type { ChannelSetupWizard } from 'openclaw/plugin-sdk/setup';
+
+export const DEFAULT_ACCOUNT_ID = 'default';
+
+export function createStandardChannelSetupStatus(
+  ...args: Parameters<NonNullable<typeof _setup>['createStandardChannelSetupStatus']>
+): ReturnType<NonNullable<typeof _setup>['createStandardChannelSetupStatus']> {
+  const mod = loadSetup();
+  if (mod) return mod.createStandardChannelSetupStatus(...args);
+  return {
+    channelLabel: args[0]?.channelLabel ?? 'QQ Bot',
+    configuredLabel: 'Configured',
+    unconfiguredLabel: 'Not configured',
+    resolveConfigured: () => false,
+  } as unknown as ReturnType<NonNullable<typeof _setup>['createStandardChannelSetupStatus']>;
+}
+
+export function setSetupChannelEnabled(
+  ...args: Parameters<NonNullable<typeof _setup>['setSetupChannelEnabled']>
+): void {
+  loadSetup()?.setSetupChannelEnabled?.(...args);
+}
+
+export function formatDocsLink(
+  ...args: Parameters<NonNullable<typeof _tools>['formatDocsLink']>
+): ReturnType<NonNullable<typeof _tools>['formatDocsLink']> {
+  const mod = loadTools();
+  if (mod) return mod.formatDocsLink(...args);
+  return (args[1] ? `${args[1]}: ${args[0]}` : args[0]) as ReturnType<NonNullable<typeof _tools>['formatDocsLink']>;
+}

package/src/adapter/webhook.ts

@@ -0,0 +1,248 @@
+/**
+ * PluginWebhookAdapter — 将 OpenClaw Gateway HTTP 路由适配为 SDK WebhookServerAdapter。
+ *
+ * 复用 openclaw/plugin-sdk/webhook-ingress 的 target registry、rate limiting 和
+ * resolveWebhookTargetWithAuthOrRejectSync 签名匹配，对齐旧版本插件行为。
+ *
+ * 多账号同路径：通过 resolveWebhookTargetWithAuthOrRejectSync 遍历 targets 做
+ * Ed25519 签名匹配，找到正确的 target 后调用其 SDK handler 处理事件。
+ */
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import type { WebhookServerAdapter, WebhookRequestHandler } from '@tencent-connect/qqbot-nodejs';
+import { verifyWebhookSignature } from '@tencent-connect/qqbot-nodejs/protocol';
+
+// ── 模块级共享状态 ──
+interface WebhookTarget {
+  path: string;
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  handler: WebhookRequestHandler;
+}
+const sharedTargets = new Map<string, WebhookTarget[]>();
+const _routeUnregisters = new Map<string, () => void>();
+
+export function createPluginWebhookAdapter(params: {
+  account: ResolvedQQBotAccount;
+  log: PluginLogger;
+}): WebhookServerAdapter {
+  let unregistered = false;
+  let storedPath = '';
+  const accountId = params.account.accountId;
+
+  return {
+    async listen(_port: number, path: string, handler: WebhookRequestHandler): Promise<void> {
+      const ingress = await import('openclaw/plugin-sdk/webhook-ingress').catch(() => null);
+      if (!ingress?.registerWebhookTargetWithPluginRoute) {
+        params.log.error('Webhook ingress not available');
+        return;
+      }
+
+      const webhookPath = storedPath = path && path !== '/' ? path : (params.account.config.webhook?.path ?? '/qqbot/webhook');
+
+      // 去重：reload 时避免同一 accountId 重复注册
+      const existing = sharedTargets.get(webhookPath);
+      if (existing) {
+        const dupIdx = existing.findIndex((t) => t.accountId === accountId);
+        if (dupIdx >= 0) {
+          existing[dupIdx] = { path: webhookPath, accountId, appId: params.account.appId, clientSecret: params.account.clientSecret, handler };
+          params.log.info(`Webhook target refreshed for ${accountId} on ${webhookPath}`);
+          return;
+        }
+      }
+
+      // 注册 target（框架管理 targetsByPath + 首次触发路由注册）
+      const target: WebhookTarget = {
+        path: webhookPath,
+        accountId,
+        appId: params.account.appId,
+        clientSecret: params.account.clientSecret,
+        handler,
+      };
+
+      const result = ingress.registerWebhookTargetWithPluginRoute({
+        targetsByPath: sharedTargets as any,
+        target,
+        route: {
+          auth: 'plugin',
+          match: 'exact',
+          pluginId: 'openclaw-qqbot',
+          source: 'qqbot-webhook',
+          accountId,
+          replaceExisting: true,
+          log: (msg: string) => params.log.info(msg),
+          handler: createSharedHandler(webhookPath, params.log),
+        },
+        onLastPathTargetRemoved: () => {
+          params.log.info(`Last webhook target removed from ${webhookPath}`);
+        },
+      });
+      _routeUnregisters.set(webhookPath, result.unregister);
+
+      params.log.info(`Webhook target added on ${webhookPath} (${sharedTargets.get(webhookPath)!.length} account(s))`);
+    },
+
+    close(): void {
+      if (unregistered) return;
+      unregistered = true;
+      if (storedPath) {
+        _routeUnregisters.get(storedPath)?.();
+        _routeUnregisters.delete(storedPath);
+      }
+    },
+  };
+}
+
+function createSharedHandler(path: string, log: PluginLogger) {
+  return async (req: any, res: any) => {
+    try {
+      const ingress = await import('openclaw/plugin-sdk/webhook-ingress').catch(() => null);
+
+      if (!ingress?.withResolvedWebhookRequestPipeline) {
+        await handleSimple(req, res, path, log);
+        return;
+      }
+
+      await ingress.withResolvedWebhookRequestPipeline({
+        req,
+        res,
+        targetsByPath: sharedTargets,
+        rateLimiter: ingress.createFixedWindowRateLimiter?.({
+          windowMs: 60_000, maxRequests: 600, maxTrackedKeys: 4096,
+        }),
+        inFlightLimiter: ingress.createWebhookInFlightLimiter?.({
+          maxInFlightPerKey: 8, maxTrackedKeys: 4096,
+        }),
+        requireJsonContentType: true,
+        handle: async ({ targets }) => {
+          const bodyResult = await ingress.readWebhookBodyOrReject({
+            req, res, maxBytes: 1_048_576, timeoutMs: 30_000,
+          });
+          if (!bodyResult.ok) {
+            log.warn?.(`[webhook] body rejected`);
+            return;
+          }
+
+          const rawBody = Buffer.from(bodyResult.value, 'utf-8');
+
+          let payload: any;
+          try { payload = JSON.parse(bodyResult.value); } catch (err) {
+            log.warn?.(`[webhook] invalid json: ${(err as Error).message}`);
+            res.statusCode = 400; res.end(JSON.stringify({ error: 'invalid json' })); return;
+          }
+
+          // op:13 → 用第一个 target 的 SDK handler（无需签名）
+          if (payload.op === 13) {
+            const t = targets[0];
+            if (!t) {
+              log.warn?.(`[webhook] op:13 no target on ${path}`);
+              res.statusCode = 500; res.end(JSON.stringify({ error: 'no target' })); return;
+            }
+            const h = resolveTargetHandler(path, t.accountId);
+            if (!h) {
+              log.warn?.(`[webhook] op:13 no handler for ${t.accountId}`);
+              res.statusCode = 500; res.end(JSON.stringify({ error: 'no handler' })); return;
+            }
+            await delegateToHandler(h, req, res, rawBody);
+            return;
+          }
+
+          // op:0 → 签名匹配 target → SDK handler 处理事件
+          const timestamp = getHeader(req, 'x-signature-timestamp') ?? '';
+          const signature = getHeader(req, 'x-signature-ed25519') ?? '';
+          if (!timestamp || !signature) {
+            log.warn?.(`[webhook] missing signature headers on ${req.url}`);
+            res.statusCode = 401; res.end(JSON.stringify({ error: 'missing signature' })); return;
+          }
+
+          const matched = ingress.resolveWebhookTargetWithAuthOrRejectSync({
+            targets, res,
+            isMatch: (t: any) => verifyWebhookSignature({
+              body: rawBody, timestamp, signature, botSecret: t.clientSecret as string,
+            }),
+            unauthorizedStatusCode: 401,
+            unauthorizedMessage: JSON.stringify({ error: 'invalid signature' }),
+          });
+          if (!matched) {
+            log.warn?.(`[webhook] signature mismatch on ${path} (${targets.length} target(s))`);
+            return;
+          }
+
+          const h = resolveTargetHandler(path, matched.accountId);
+          if (!h) {
+            log.error?.(`[webhook] no handler for matched target ${matched.accountId}`);
+            res.statusCode = 500; res.end(JSON.stringify({ error: 'no handler' })); return;
+          }
+          await delegateToHandler(h, req, res, rawBody);
+        },
+      });
+    } catch (err) {
+      log.error(`Webhook handler error: ${(err as Error).message}`);
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: 'internal error' }));
+      }
+    }
+  };
+}
+
+function resolveTargetHandler(path: string, accountId: string): WebhookRequestHandler | undefined {
+  return sharedTargets.get(path)?.find((t) => t.accountId === accountId)?.handler;
+}
+
+async function delegateToHandler(handler: WebhookRequestHandler, req: any, res: any, rawBody: Buffer) {
+  const headers: Record<string, string | string[]> = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    headers[k.toLowerCase()] = v as string | string[];
+  }
+  const resp = await handler({ body: rawBody, headers });
+  res.statusCode = resp.status;
+  if (resp.headers) {
+    for (const [k, v] of Object.entries(resp.headers)) res.setHeader(k, v as string);
+  }
+  res.end(resp.body);
+}
+
+async function handleSimple(req: any, res: any, path: string, log: PluginLogger) {
+  try {
+    const ct = String(req.headers['content-type'] ?? '');
+    if (!ct.includes('application/json')) { res.statusCode = 400; res.end(JSON.stringify({ error: 'unsupported content type' })); return; }
+
+    const chunks: Buffer[] = [];
+    let total = 0;
+    for await (const chunk of req) {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      total += buf.length;
+      if (total > 1_048_576) { res.statusCode = 413; res.end(JSON.stringify({ error: 'too large' })); return; }
+      chunks.push(buf);
+    }
+    const rawBody = Buffer.concat(chunks);
+    const entries = sharedTargets.get(path) ?? [];
+    for (const entry of entries) {
+      const resp = await entry.handler({ body: rawBody, headers: mapHeaders(req) });
+      if (resp.status < 400) {
+        res.statusCode = resp.status;
+        if (resp.headers) for (const [k, v] of Object.entries(resp.headers)) res.setHeader(k, v as string);
+        res.end(resp.body);
+        return;
+      }
+    }
+    res.statusCode = 401; res.end(JSON.stringify({ error: 'invalid signature' }));
+  } catch (err) {
+    log.error(`Webhook simple handler error: ${(err as Error).message}`);
+    if (!res.headersSent) { res.statusCode = 500; res.end(JSON.stringify({ error: 'internal error' })); }
+  }
+}
+
+function mapHeaders(req: any): Record<string, string | string[]> {
+  const h: Record<string, string | string[]> = {};
+  for (const [k, v] of Object.entries(req.headers ?? {})) h[k.toLowerCase()] = v as string | string[];
+  return h;
+}
+
+function getHeader(req: any, key: string): string | undefined {
+  const val = req.headers[key];
+  return Array.isArray(val) ? val[0] : val;
+}

package/src/adapter/workspace.ts

@@ -0,0 +1,29 @@
+/**
+ * Agent workspace 目录解析（动态加载 plugin-sdk/health）
+ *
+ * 新版本 openclaw 有 openclaw/plugin-sdk/health 导出，
+ * 旧版本不可用时 fallback 到 QQ Bot media 目录。
+ */
+import { createRequire } from 'node:module';
+import { getQQBotMediaDir } from '../utils/platform.js';
+
+const req = createRequire(__filename);
+
+let health: {
+  resolveAgentWorkspaceDir: (cfg: any, agentId: string) => string;
+  resolveDefaultAgentId: (cfg: any) => string;
+} | null = null;
+
+export function resolveAgentWorkspace(cfg: any, agentId?: string): string {
+  if (!health) {
+    try {
+      health = req('openclaw/plugin-sdk/health') as typeof health;
+    } catch {
+      health = null;
+    }
+  }
+  if (health) {
+    return health.resolveAgentWorkspaceDir(cfg, agentId ?? health.resolveDefaultAgentId(cfg));
+  }
+  return getQQBotMediaDir();
+}

package/src/bot-instance.ts

@@ -0,0 +1,60 @@
+/**
+ * Bot 实例访问器
+ *
+ * 提供统一的方式获取当前活跃的 QQBot SDK 实例。
+ * 替代原 api.ts 的所有功能 — 消费者通过 getBotForAccount() 获取 bot，
+ * 然后使用 bot.api / bot.send() 等 SDK 原生能力。
+ */
+import os from 'node:os';
+import type { QQBot } from '@tencent-connect/qqbot-nodejs';
+import { getGateway } from './outbound/outbound-service.js';
+import { getPackageVersion } from './utils/pkg-version.js';
+
+
+const PLUGIN_VERSION = getPackageVersion();
+let _openclawVersion = 'unknown';
+
+export function setOpenClawVersion(version: string): void {
+  if (version) _openclawVersion = version;
+}
+
+export function getOpenClawVersion(): string {
+  return _openclawVersion;
+}
+
+export function buildUserAgent(suffix?: string): string {
+  const base = `QQBotPlugin/${PLUGIN_VERSION} (Node/${process.versions.node}; ${os.platform()}; OpenClaw/${_openclawVersion})`;
+  return suffix ? `${base} ${suffix}` : base;
+}
+
+// ── Bot 实例获取 ──
+
+/**
+ * 获取指定账户的 QQBot SDK 实例。
+ *
+ * @throws 如果该账户的 gateway 尚未启动
+ *
+ * @example
+ * ```ts
+ * const bot = getBotForAccount(accountId);
+ * await bot.send({ target, content: 'hello' });
+ * const guilds = await bot.api.get('/users/@me/guilds');
+ * const token = await bot.api.getToken();
+ * ```
+ */
+export function getBotForAccount(accountId: string): QQBot {
+  const gw = getGateway(accountId);
+  if (!gw) {
+    throw new Error(`[qqbot] Bot "${accountId}" not running — gateway not started`);
+  }
+  return gw.bot;
+}
+
+/**
+ * 尝试获取指定账户的 QQBot SDK 实例（不抛异常）。
+ * 返回 null 表示 gateway 尚未启动。
+ */
+export function tryGetBotForAccount(accountId: string): QQBot | null {
+  const gw = getGateway(accountId);
+  return gw?.bot ?? null;
+}