@jerryliang122/openclaw-qqbot 1.0.0

package/src/setup/login.ts

@@ -0,0 +1,197 @@
+/**
+ * QQ Bot QR 登录 — 两阶段接口适配
+ *
+ * 使用 @tencent-connect/qqbot-connector 的 startQrConnect 回调 API，
+ * 将扫码绑定流程拆分为 start / wait 两个阶段，对接 ChannelPlugin 的
+ * gateway.loginWithQrStart / loginWithQrWait。
+ */
+import { startQrConnect, type QrConnectCredentials } from '@tencent-connect/qqbot-connector';
+
+// ── 类型 ──
+
+export interface QrLoginStartResult {
+  qrDataUrl?: string;
+  message: string;
+}
+
+export interface QrLoginWaitResult {
+  connected: boolean;
+  message: string;
+  credentials?: QrConnectCredentials[];
+}
+
+// ── 挂起的登录会话 ──
+
+interface PendingSession {
+  /** 等待扫码结果的 Promise（onSuccess resolve, onFailure reject） */
+  credentialsPromise: Promise<QrConnectCredentials[]>;
+  /** 取消当前流程 */
+  dispose: () => void;
+}
+
+const pendingSessions = new Map<string, PendingSession>();
+
+// ── 启动 QR 登录 ──
+
+export function startQrLogin(accountId?: string, source = 'openclaw'): Promise<QrLoginStartResult> {
+  const key = accountId ?? 'default';
+
+  // 清理旧会话
+  pendingSessions.get(key)?.dispose();
+  pendingSessions.delete(key);
+
+  return new Promise((resolve) => {
+    let credentialsResolve: (creds: QrConnectCredentials[]) => void;
+    let credentialsReject: (err: Error) => void;
+
+    // 凭据 Promise — 在 onSuccess/onFailure 中 settle
+    const credentialsPromise = new Promise<QrConnectCredentials[]>((res, rej) => {
+      credentialsResolve = res;
+      credentialsReject = rej;
+    });
+
+    const dispose = startQrConnect(
+      {
+        onQrDisplayed(url) {
+          resolve({
+            qrDataUrl: url,
+            message: '请使用手机 QQ 扫描二维码完成绑定',
+          });
+        },
+        onSuccess: (creds) => credentialsResolve!(creds),
+        onFailure: (err) => credentialsReject!(err),
+      },
+      { displayQrCodeToConsole: true, source },
+    );
+
+    pendingSessions.set(key, { dispose, credentialsPromise });
+  });
+}
+
+// ── 等待扫码结果 ──
+
+export async function waitQrLogin(accountId?: string): Promise<QrLoginWaitResult> {
+  const key = accountId ?? 'default';
+  const session = pendingSessions.get(key);
+
+  if (!session) {
+    return { connected: false, message: '没有正在进行的登录会话，请先运行 login 命令。' };
+  }
+
+  try {
+    const credentials = await session.credentialsPromise;
+    pendingSessions.delete(key);
+
+    if (credentials.length === 0) {
+      return { connected: false, message: '未获取到 QQ Bot 凭据。' };
+    }
+
+    return {
+      connected: true,
+      message: `绑定成功！AppID: ${credentials.map((c) => c.appId).join(', ')}`,
+      credentials,
+    };
+  } catch (err) {
+    pendingSessions.delete(key);
+    return {
+      connected: false,
+      message: `绑定失败: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+// ── 主动取消 ──
+
+export function cancelQrLogin(accountId?: string): void {
+  const key = accountId ?? 'default';
+  pendingSessions.get(key)?.dispose();
+  pendingSessions.delete(key);
+}
+
+// ── 解析 channelInput (appId:clientSecret) ──
+
+export function parseChannelInput(channelInput?: string | null): { appId: string; clientSecret: string } | null {
+  if (!channelInput) return null;
+  const parts = channelInput.trim().split(':');
+  if (parts.length === 2 && parts[0] && parts[1]) {
+    return { appId: parts[0], clientSecret: parts[1] };
+  }
+  return null;
+}
+
+// ── auth.login 入口 ──
+
+export interface QqbotLoginParams {
+  cfg: Record<string, unknown>;
+  accountId?: string | null;
+  channelInput?: string | null;
+  verbose?: boolean;
+  /** 框架注入的 runtime（含 config 持久化 API） */
+  [key: string]: unknown;
+}
+
+/**
+ * auth.login 完整实现。
+ *
+ * 账号策略：
+ *   --account <id>  → 写入指定账户
+ *   channelInput     → 用 appId 作为账户键
+ *   QR 扫码         → 用扫码返回的 appId 作为新账户键
+ */
+export async function qqbotLogin({
+  cfg,
+  accountId,
+  channelInput,
+  verbose,
+  ...rest
+}: QqbotLoginParams): Promise<void> {
+  // 延迟导入，避免循环依赖
+  const { applyQQBotAccountConfig } = await import('../config.js');
+  const { persistAuthConfig } = await import('../adapter/resolve.js');
+  const { applyAccountDefaults } = await import('./finalize.js');
+  const { resolveAccountKey } = await import('./account-key.js');
+
+  const runtime: Record<string, unknown> = rest as any;
+  const resolvedId = accountId ? accountId.trim().toLowerCase() : null;
+
+  // 如果传了 appId:clientSecret，直接写入配置
+  const parsed = parseChannelInput(channelInput);
+  if (parsed) {
+    const key = resolveAccountKey(cfg as any, parsed.appId, resolvedId);
+    const result = applyQQBotAccountConfig(cfg as any, key, {
+      appId: parsed.appId,
+      clientSecret: parsed.clientSecret,
+    });
+    Object.assign(cfg, result);
+    // 对齐 setup：写入默认 streaming/dmPolicy
+    const withDefaults = applyAccountDefaults(cfg as any, key);
+    Object.assign(cfg, withDefaults);
+    await persistAuthConfig(runtime, cfg, 'restart');
+    if (verbose) console.log(`QQ Bot 已配置 (${key}) AppID: ${parsed.appId}`);
+    return;
+  }
+
+  // QR 扫码登录
+  const { qrDataUrl, message } = await startQrLogin(resolvedId || 'pending');
+  console.log(`\n${message}`);
+  if (qrDataUrl) console.log(`QR 链接: ${qrDataUrl}`);
+
+  const result = await waitQrLogin(resolvedId || 'pending');
+  if (!result.connected || !result.credentials) {
+    throw new Error(result.message);
+  }
+
+  for (const cred of result.credentials) {
+    const key = resolveAccountKey(cfg as any, cred.appId, resolvedId);
+    const next = applyQQBotAccountConfig(cfg as any, key, {
+      appId: cred.appId,
+      clientSecret: cred.appSecret,
+    });
+    Object.assign(cfg, next);
+    // 对齐 setup：写入默认 streaming/dmPolicy，扫码用户加入白名单
+    const withDefaults = applyAccountDefaults(cfg as any, key, cred.userOpenid);
+    Object.assign(cfg, withDefaults);
+  }
+  await persistAuthConfig(runtime, cfg, 'restart');
+  console.log(`QQ Bot 登录成功！`);
+}

package/src/setup/surface.ts

@@ -0,0 +1,40 @@
+/**
+ * OpenClaw setup 向导 — QQ Bot 配置界面
+ */
+import type { ChannelSetupWizard } from '../adapter/setup.js';
+import { createStandardChannelSetupStatus, setSetupChannelEnabled } from '../adapter/setup.js';
+import { listQQBotAccountIds, resolveQQBotAccount, resolveDefaultQQBotAccountId } from '../config.js';
+import { finalizeQQBotSetup } from './finalize.js';
+
+const CHANNEL = 'qqbot' as const;
+
+export const qqbotSetupWizard: ChannelSetupWizard = {
+  channel: CHANNEL,
+  status: createStandardChannelSetupStatus({
+    channelLabel: 'QQ Bot',
+    configuredLabel: 'configured',
+    unconfiguredLabel: 'needs AppID + AppSecret',
+    configuredHint: 'configured',
+    unconfiguredHint: 'needs AppID + AppSecret',
+    configuredScore: 1,
+    unconfiguredScore: 6,
+    resolveConfigured: ({ cfg, accountId }) =>
+      (accountId ? [accountId] : listQQBotAccountIds(cfg as any)).some((id) => {
+        const account = resolveQQBotAccount(cfg as any, id);
+        return Boolean(account.appId && account.clientSecret);
+      }),
+  }),
+  // 未配置时默认使用 default 账号，有账户时框架会提示选择
+  resolveAccountIdForConfigure: async ({ cfg, shouldPromptAccountIds, accountOverride, defaultAccountId }) => {
+    if (accountOverride) return accountOverride;
+    const ids = listQQBotAccountIds(cfg as any);
+    if (ids.length === 0) return 'default';
+    if (!shouldPromptAccountIds) return ids[0];
+    return defaultAccountId || resolveDefaultQQBotAccountId(cfg as any);
+  },
+  credentials: [],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  finalize: (async ({ cfg, accountId, prompter, runtime }: any) =>
+    finalizeQQBotSetup({ cfg, accountId, prompter: prompter as any, runtime: runtime as any })) as any,
+  disable: (cfg) => { setSetupChannelEnabled(cfg, CHANNEL, false); return cfg; },
+};

package/src/status-adapter.ts

@@ -0,0 +1,56 @@
+/**
+ * QQBot Status 适配器
+ *
+ * 账户状态探测、审计、快照构建
+ */
+
+import { DEFAULT_ACCOUNT_ID } from './config.js';
+import type { ResolvedQQBotAccount } from './types.js';
+
+/**
+ * 默认运行时状态
+ */
+function createDefaultChannelRuntimeState(accountId: string) {
+  return {
+    accountId,
+    running: false,
+    connected: false,
+    lastConnectedAt: null as number | null,
+    lastError: null as string | null,
+    lastInboundAt: null as number | null,
+    lastOutboundAt: null as number | null,
+  };
+}
+
+/**
+ * QQBot Status Adapter
+ */
+export const qqbotStatusAdapter = {
+  defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+
+  buildChannelSummary: ({ snapshot }: { snapshot: any }) => ({
+    configured: snapshot.configured ?? false,
+    tokenSource: snapshot.tokenSource ?? 'none',
+    running: snapshot.running ?? false,
+    connected: snapshot.connected ?? false,
+    lastConnectedAt: snapshot.lastConnectedAt ?? null,
+    lastError: snapshot.lastError ?? null,
+  }),
+
+  resolveAccountSnapshot: ({ account, runtime }: {
+    account?: ResolvedQQBotAccount;
+    runtime?: any;
+  }) => ({
+    accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
+    name: account?.name,
+    enabled: account?.enabled ?? false,
+    configured: Boolean(account?.appId && account?.clientSecret),
+    tokenSource: account?.secretSource,
+    running: Boolean(runtime?.running ?? false),
+    connected: Boolean(runtime?.connected ?? false),
+    lastConnectedAt: runtime?.lastConnectedAt ?? null,
+    lastError: runtime?.lastError ?? null,
+    lastInboundAt: runtime?.lastInboundAt ?? null,
+    lastOutboundAt: runtime?.lastOutboundAt ?? null,
+  }),
+};

package/src/tools/platform.ts

@@ -0,0 +1,149 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+import { listQQBotAccountIds } from '../config.js';
+import { getBotForAccount } from '../bot-instance.js';
+import { getRequestAccountId } from '../request-context.js';
+
+// ========== JSON Schema ==========
+
+const PlatformApiSchema = {
+  type: 'object',
+  properties: {
+    method: {
+      type: 'string',
+      description:
+        'HTTP 请求方法。可选值：GET, POST, PUT, PATCH, DELETE',
+      enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+    },
+    path: {
+      type: 'string',
+      description:
+        'API 路径（不含域名），占位符需替换为实际值。' +
+        '示例：/users/@me/guilds, /guilds/{guild_id}/channels, ' +
+        '/v2/groups/{group_id}/bot_state',
+    },
+    body: {
+      type: 'object',
+      description:
+        '请求体（JSON），用于 POST/PUT/PATCH 请求。' +
+        'GET/DELETE 请求不需要此参数。',
+    },
+    query: {
+      type: 'object',
+      description:
+        'URL 查询参数（键值对），会拼接到路径后面。' +
+        '如 { "limit": "100", "after": "0" } 会拼接为 ?limit=100&after=0',
+      additionalProperties: { type: 'string' },
+    },
+  },
+  required: ['method', 'path'],
+} as const;
+
+// ========== 工具函数 ==========
+
+function json(data: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+function validatePath(path: string): string | null {
+  if (!path.startsWith('/')) return "path 必须以 / 开头";
+  if (path.includes('..') || path.includes('//')) return "path 不允许包含 .. 或 //";
+  if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== '/') {
+    return 'path 包含非法字符';
+  }
+  return null;
+}
+
+// ========== 注册入口 ==========
+
+/**
+ * 注册 QQBot 平台统一 API 网关工具。
+ * 通过 SDK 的 bot.api 网关代理所有 QQ 开放平台 HTTP 接口 — 自动鉴权、重试、结构化错误。
+ *
+ * 覆盖范围：
+ *  - 频道（Guild/Channel/Member/Announce/Forum/Schedule）→ 见 qqbot-channel skill
+ *  - 群（Group/Member）→ 见 qqbot-group skill
+ */
+export function registerPlatformTool(api: OpenClawPluginApi): void {
+  const cfg = api.config;
+  if (!cfg) return;
+
+  const accountIds = listQQBotAccountIds(cfg);
+  if (accountIds.length === 0) return;
+
+  api.registerTool(
+    {
+      name: 'qqbot_platform_api',
+      label: 'QQBot Platform API Gateway',
+      description:
+        'QQ 开放平台统一 HTTP API 网关，自动填充鉴权 Token。' +
+        '常用接口速查：' +
+        '【频道】GET /users/@me/guilds | /guilds/{guild_id}/channels | /channels/{channel_id} | ' +
+        '【群】GET /v2/groups/{group_id}/bot_state | /v2/groups/{group_id}/members/{member_id} | /v2/groups/{group_id}/info。' +
+        '更多接口和参数详情请阅读 qqbot-channel 和 qqbot-group skill。',
+      parameters: PlatformApiSchema,
+      async execute(_toolCallId, params) {
+        const p = params as {
+          method: string;
+          path: string;
+          body?: Record<string, unknown>;
+          query?: Record<string, string>;
+        };
+
+        if (!p.method) return json({ error: 'method 为必填参数' });
+        if (!p.path) return json({ error: 'path 为必填参数' });
+
+        const method = p.method.toUpperCase();
+        if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+          return json({ error: `不支持的 HTTP 方法: ${method}` });
+        }
+
+        const pathError = validatePath(p.path);
+        if (pathError) return json({ error: pathError });
+
+        const accountId = getRequestAccountId();
+        if (!accountId) {
+          return json({ error: '无法获取当前请求的账号信息，此工具仅支持在消息会话中使用' });
+        }
+
+        try {
+          const bot = getBotForAccount(accountId);
+          const apiGateway = bot.api;
+
+          let data: unknown;
+          switch (method) {
+            case 'GET':
+              data = await apiGateway.get(p.path, p.query);
+              break;
+            case 'POST':
+              data = await apiGateway.post(p.path, p.body);
+              break;
+            case 'PUT':
+              data = await apiGateway.put(p.path, p.body);
+              break;
+            case 'PATCH':
+              data = await apiGateway.patch(p.path, p.body);
+              break;
+            case 'DELETE':
+              data = await apiGateway.delete(p.path);
+              break;
+          }
+
+          return json(data);
+        } catch (err: unknown) {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          const apiErr = err as { httpStatus?: number; bizCode?: number; path?: string };
+          return json({
+            error: errMsg,
+            status: apiErr.httpStatus,
+            code: apiErr.bizCode,
+            path: p.path,
+          });
+        }
+      },
+    },
+    { name: 'qqbot_platform_api' },
+  );
+}