@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

package/src/engine/config/resolve.test.ts

@@ -1,152 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  DEFAULT_ACCOUNT_ID,
-  listAccountIds,
-  resolveDefaultAccountId,
-  resolveAccountBase,
-} from "./resolve.js";
-
-describe("engine/config/resolve", () => {
-  it("returns empty list when no accounts configured", () => {
-    expect(listAccountIds({})).toEqual([]);
-  });
-
-  it("returns default when top-level appId is set", () => {
-    const cfg = {
-      channels: {
-        qqbot: { appId: "123456" },
-      },
-    };
-    expect(listAccountIds(cfg)).toEqual([DEFAULT_ACCOUNT_ID]);
-  });
-
-  it("lists named accounts", () => {
-    const cfg = {
-      channels: {
-        qqbot: {
-          accounts: {
-            bot2: { appId: "654321" },
-            bot3: { appId: "111222" },
-          },
-        },
-      },
-    };
-    const ids = listAccountIds(cfg);
-    expect(ids).toContain("bot2");
-    expect(ids).toContain("bot3");
-  });
-
-  it("resolves default account id to 'default' when top-level appId exists", () => {
-    const cfg = {
-      channels: {
-        qqbot: { appId: "123456" },
-      },
-    };
-    expect(resolveDefaultAccountId(cfg)).toBe(DEFAULT_ACCOUNT_ID);
-  });
-
-  it("honors configured defaultAccount", () => {
-    const cfg = {
-      channels: {
-        qqbot: {
-          defaultAccount: "bot2",
-          accounts: {
-            bot2: { appId: "654321" },
-          },
-        },
-      },
-    };
-    expect(resolveDefaultAccountId(cfg)).toBe("bot2");
-  });
-
-  it("falls back to first named account when no default configured", () => {
-    const cfg = {
-      channels: {
-        qqbot: {
-          accounts: {
-            mybot: { appId: "999999" },
-          },
-        },
-      },
-    };
-    expect(resolveDefaultAccountId(cfg)).toBe("mybot");
-  });
-
-  it("resolves base account info for default account", () => {
-    const cfg = {
-      channels: {
-        qqbot: {
-          appId: "123456",
-          name: "Test Bot",
-          systemPrompt: "You are helpful.",
-          markdownSupport: true,
-        },
-      },
-    };
-    const base = resolveAccountBase(cfg, DEFAULT_ACCOUNT_ID);
-    expect(base.accountId).toBe(DEFAULT_ACCOUNT_ID);
-    expect(base.appId).toBe("123456");
-    expect(base.name).toBe("Test Bot");
-    expect(base.systemPrompt).toBe("You are helpful.");
-    expect(base.markdownSupport).toBe(true);
-    expect(base.enabled).toBe(true);
-  });
-
-  it("resolves base account info for named account", () => {
-    const cfg = {
-      channels: {
-        qqbot: {
-          accounts: {
-            bot2: {
-              appId: "654321",
-              name: "Bot Two",
-              enabled: false,
-            },
-          },
-        },
-      },
-    };
-    const base = resolveAccountBase(cfg, "bot2");
-    expect(base.accountId).toBe("bot2");
-    expect(base.appId).toBe("654321");
-    expect(base.name).toBe("Bot Two");
-    expect(base.enabled).toBe(false);
-  });
-
-  it("uses configured defaultAccount when accountId is omitted", () => {
-    const cfg = {
-      channels: {
-        qqbot: {
-          defaultAccount: "bot2",
-          accounts: {
-            bot2: { appId: "654321" },
-          },
-        },
-      },
-    };
-    const base = resolveAccountBase(cfg);
-    expect(base.accountId).toBe("bot2");
-    expect(base.appId).toBe("654321");
-  });
-
-  it("preserves audioFormatPolicy on the config object", () => {
-    const cfg = {
-      channels: {
-        qqbot: {
-          appId: "123456",
-          audioFormatPolicy: {
-            sttDirectFormats: [".wav"],
-            uploadDirectFormats: [".mp3"],
-            transcodeEnabled: false,
-          },
-        },
-      },
-    };
-    const base = resolveAccountBase(cfg, DEFAULT_ACCOUNT_ID);
-    expect(base.config.audioFormatPolicy).toEqual({
-      sttDirectFormats: [".wav"],
-      uploadDirectFormats: [".mp3"],
-      transcodeEnabled: false,
-    });
-  });
-});

package/src/engine/config/resolve.ts

@@ -1,283 +0,0 @@
-/**
- * QQBot config resolution (pure logic layer).
- * QQBot 配置解析（纯逻辑层）。
- *
- * Resolves account IDs, default account selection, and base account
- * info from raw config objects. Secret/credential resolution is
- * intentionally left to the outer layer (src/bridge/config.ts) so that
- * this module stays framework-agnostic and self-contained.
- */
-
-import { getPlatformAdapter } from "../adapter/index.js";
-import {
-  asOptionalObjectRecord as asRecord,
-  normalizeOptionalLowercaseString,
-  normalizeStringifiedOptionalString,
-  readStringField as readString,
-} from "../utils/string-normalize.js";
-
-/**
- * Default account ID, used for the unnamed top-level account.
- * 默认账号 ID，用于顶层配置中未命名的账号。
- */
-export const DEFAULT_ACCOUNT_ID = "default";
-
-/**
- * Internal shape of the channels.qqbot config section.
- * channels.qqbot 配置节的内部结构。
- */
-interface QQBotChannelConfig {
-  appId?: unknown;
-  clientSecret?: unknown;
-  clientSecretFile?: string;
-  accounts?: Record<string, Record<string, unknown>>;
-  defaultAccount?: unknown;
-  [key: string]: unknown;
-}
-
-/**
- * Base account resolution result (without credentials).
- * 账号基础解析结果（不含凭证信息）。
- *
- * The outer config.ts layer extends this with clientSecret / secretSource.
- */
-interface ResolvedAccountBase {
-  accountId: string;
-  name?: string;
-  enabled: boolean;
-  appId: string;
-  systemPrompt?: string;
-  markdownSupport: boolean;
-  config: Record<string, unknown>;
-}
-
-function normalizeAppId(raw: unknown): string {
-  if (typeof raw === "string") {
-    return raw.trim();
-  }
-  if (typeof raw === "number") {
-    return String(raw);
-  }
-  return "";
-}
-
-function normalizeAccountConfig(
-  account: Record<string, unknown> | undefined,
-): Record<string, unknown> {
-  if (!account) {
-    return {};
-  }
-  const audioPolicy = asRecord(account.audioFormatPolicy);
-  return {
-    ...account,
-    ...(audioPolicy ? { audioFormatPolicy: { ...audioPolicy } } : {}),
-  };
-}
-
-function readQQBotSection(cfg: Record<string, unknown>): QQBotChannelConfig | undefined {
-  const channels = asRecord(cfg.channels);
-  return asRecord(channels?.qqbot) as QQBotChannelConfig | undefined;
-}
-
-/**
- * List all configured QQBot account IDs.
- * 列出所有已配置的 QQBot 账号 ID。
- */
-export function listAccountIds(cfg: Record<string, unknown>): string[] {
-  const ids = new Set<string>();
-  const qqbot = readQQBotSection(cfg);
-
-  if (qqbot?.appId || process.env.QQBOT_APP_ID) {
-    ids.add(DEFAULT_ACCOUNT_ID);
-  }
-
-  if (qqbot?.accounts) {
-    for (const accountId of Object.keys(qqbot.accounts)) {
-      if (qqbot.accounts[accountId]?.appId) {
-        ids.add(accountId);
-      }
-    }
-  }
-
-  return Array.from(ids);
-}
-
-/**
- * Resolve the default QQBot account ID.
- * 解析默认 QQBot 账号 ID（优先级：defaultAccount > 顶层 appId > 第一个命名账号）。
- */
-export function resolveDefaultAccountId(cfg: Record<string, unknown>): string {
-  const qqbot = readQQBotSection(cfg);
-  const configuredDefaultAccountId = normalizeOptionalLowercaseString(qqbot?.defaultAccount);
-  if (
-    configuredDefaultAccountId &&
-    (configuredDefaultAccountId === DEFAULT_ACCOUNT_ID ||
-      Boolean(qqbot?.accounts?.[configuredDefaultAccountId]?.appId))
-  ) {
-    return configuredDefaultAccountId;
-  }
-  if (qqbot?.appId || process.env.QQBOT_APP_ID) {
-    return DEFAULT_ACCOUNT_ID;
-  }
-  if (qqbot?.accounts) {
-    const ids = Object.keys(qqbot.accounts);
-    if (ids.length > 0) {
-      return ids[0];
-    }
-  }
-  return DEFAULT_ACCOUNT_ID;
-}
-
-/**
- * Resolve base account info (without credentials).
- * 解析账号基础信息（不含凭证）。
- *
- * Resolves everything except Secret/credential fields. The outer
- * config.ts layer calls this and adds Secret handling on top.
- */
-export function resolveAccountBase(
-  cfg: Record<string, unknown>,
-  accountId?: string | null,
-): ResolvedAccountBase {
-  const resolvedAccountId = accountId ?? resolveDefaultAccountId(cfg);
-  const qqbot = readQQBotSection(cfg);
-
-  let accountConfig: Record<string, unknown> = {};
-  let appId = "";
-
-  if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
-    accountConfig = normalizeAccountConfig(asRecord(qqbot));
-    appId = normalizeAppId(qqbot?.appId);
-  } else {
-    const account = qqbot?.accounts?.[resolvedAccountId];
-    accountConfig = normalizeAccountConfig(asRecord(account));
-    appId = normalizeAppId(asRecord(account)?.appId);
-  }
-
-  if (!appId && process.env.QQBOT_APP_ID && resolvedAccountId === DEFAULT_ACCOUNT_ID) {
-    appId = normalizeAppId(process.env.QQBOT_APP_ID);
-  }
-
-  return {
-    accountId: resolvedAccountId,
-    name: readString(accountConfig, "name"),
-    enabled: accountConfig.enabled !== false,
-    appId,
-    systemPrompt: readString(accountConfig, "systemPrompt"),
-    markdownSupport: accountConfig.markdownSupport !== false,
-    config: accountConfig,
-  };
-}
-
-// ---- Account config apply ----
-
-interface ApplyAccountInput {
-  appId?: string;
-  clientSecret?: string;
-  clientSecretFile?: string;
-  name?: string;
-}
-
-/** Apply account config updates into a raw config object. */
-export function applyAccountConfig(
-  cfg: Record<string, unknown>,
-  accountId: string,
-  input: ApplyAccountInput,
-): Record<string, unknown> {
-  const next = { ...cfg };
-  const channels = asRecord(cfg.channels) ?? {};
-  const existingQQBot = asRecord(channels.qqbot) ?? {};
-
-  if (accountId === DEFAULT_ACCOUNT_ID) {
-    const allowFrom = (existingQQBot.allowFrom as unknown[]) ?? ["*"];
-    next.channels = {
-      ...channels,
-      qqbot: {
-        ...existingQQBot,
-        enabled: true,
-        allowFrom,
-        ...(input.appId ? { appId: input.appId } : {}),
-        ...(input.clientSecret
-          ? { clientSecret: input.clientSecret, clientSecretFile: undefined }
-          : input.clientSecretFile
-            ? { clientSecretFile: input.clientSecretFile, clientSecret: undefined }
-            : {}),
-        ...(input.name ? { name: input.name } : {}),
-      },
-    };
-  } else {
-    const accounts = (existingQQBot.accounts ?? {}) as Record<string, Record<string, unknown>>;
-    const existingAccount = accounts[accountId] ?? {};
-    const allowFrom = (existingAccount.allowFrom as unknown[]) ?? ["*"];
-    next.channels = {
-      ...channels,
-      qqbot: {
-        ...existingQQBot,
-        enabled: true,
-        accounts: {
-          ...accounts,
-          [accountId]: {
-            ...existingAccount,
-            enabled: true,
-            allowFrom,
-            ...(input.appId ? { appId: input.appId } : {}),
-            ...(input.clientSecret
-              ? { clientSecret: input.clientSecret, clientSecretFile: undefined }
-              : input.clientSecretFile
-                ? { clientSecretFile: input.clientSecretFile, clientSecret: undefined }
-                : {}),
-            ...(input.name ? { name: input.name } : {}),
-          },
-        },
-      },
-    };
-  }
-
-  return next;
-}
-
-// ---- Account status helpers ----
-
-/** Resolved account shape expected by isAccountConfigured / describeAccount. */
-interface AccountSnapshot {
-  accountId: string;
-  name?: string;
-  enabled: boolean;
-  appId: string;
-  clientSecret?: string;
-  secretSource?: string;
-  config: Record<string, unknown> & {
-    clientSecret?: unknown;
-    clientSecretFile?: string;
-  };
-}
-
-/** Check whether a QQBot account has been fully configured. */
-export function isAccountConfigured(account: AccountSnapshot | undefined): boolean {
-  return Boolean(
-    account?.appId &&
-    (Boolean(account?.clientSecret) ||
-      getPlatformAdapter().hasConfiguredSecret(account?.config?.clientSecret) ||
-      Boolean(account?.config?.clientSecretFile?.trim())),
-  );
-}
-
-/** Build a summary description of an account. */
-export function describeAccount(account: AccountSnapshot | undefined) {
-  return {
-    accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
-    name: account?.name,
-    enabled: account?.enabled ?? false,
-    configured: isAccountConfigured(account),
-    tokenSource: account?.secretSource,
-  };
-}
-
-/** Normalize allowFrom entries into uppercase strings without the qqbot: prefix. */
-export function formatAllowFrom(allowFrom: Array<string | number> | undefined | null): string[] {
-  return (allowFrom ?? [])
-    .map((entry) => normalizeStringifiedOptionalString(entry))
-    .filter((entry): entry is string => Boolean(entry))
-    .map((entry) => entry.replace(/^qqbot:/i, ""))
-    .map((entry) => entry.toUpperCase());
-}

package/src/engine/config/setup-logic.ts

@@ -1,84 +0,0 @@
-/**
- * QQBot setup business logic (pure layer).
- * QQBot setup 相关纯业务逻辑。
- *
- * Token parsing, input validation, and setup config application.
- * All functions are framework-agnostic and operate on plain objects.
- */
-
-import { applyAccountConfig } from "./resolve.js";
-import { DEFAULT_ACCOUNT_ID } from "./resolve.js";
-
-/** Parse an inline "appId:clientSecret" token string. */
-function parseInlineToken(token: string): { appId: string; clientSecret: string } | null {
-  const colonIdx = token.indexOf(":");
-  if (colonIdx <= 0 || colonIdx === token.length - 1) {
-    return null;
-  }
-
-  const appId = token.slice(0, colonIdx).trim();
-  const clientSecret = token.slice(colonIdx + 1).trim();
-  if (!appId || !clientSecret) {
-    return null;
-  }
-
-  return { appId, clientSecret };
-}
-
-interface SetupInput {
-  token?: string;
-  tokenFile?: string;
-  useEnv?: boolean;
-  name?: string;
-}
-
-/** Validate setup input for a QQBot account. Returns an error string or null. */
-export function validateSetupInput(accountId: string, input: SetupInput): string | null {
-  if (!input.token && !input.tokenFile && !input.useEnv) {
-    return "QQBot requires --token (format: appId:clientSecret) or --use-env";
-  }
-
-  if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
-    return "QQBot --use-env only supports the default account";
-  }
-
-  if (input.token && !parseInlineToken(input.token)) {
-    return "QQBot --token must be in appId:clientSecret format";
-  }
-
-  return null;
-}
-
-/** Apply setup input to account config. Returns updated config. */
-export function applySetupAccountConfig(
-  cfg: Record<string, unknown>,
-  accountId: string,
-  input: SetupInput,
-): Record<string, unknown> {
-  if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
-    return cfg;
-  }
-
-  let appId = "";
-  let clientSecret = "";
-
-  if (input.token) {
-    const parsed = parseInlineToken(input.token);
-    if (!parsed) {
-      return cfg;
-    }
-    appId = parsed.appId;
-    clientSecret = parsed.clientSecret;
-  }
-
-  if (!appId && !input.tokenFile && !input.useEnv) {
-    return cfg;
-  }
-
-  return applyAccountConfig(cfg, accountId, {
-    appId,
-    clientSecret,
-    clientSecretFile: input.tokenFile,
-    name: input.name,
-  });
-}

package/src/engine/engine-import-boundary.test.ts

@@ -1,73 +0,0 @@
-/**
- * Engine import boundary test.
- *
- * Ensures that engine/ sources only import from `openclaw/plugin-sdk/*`
- * and never reach into other openclaw internals directly.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-
-const ENGINE_DIR = path.resolve(import.meta.dirname);
-
-/** Recursively collect all non-test .ts files under a directory. */
-function walkSourceFiles(dir: string, files: string[] = []): string[] {
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name === "dist") {
-        continue;
-      }
-      walkSourceFiles(fullPath, files);
-      continue;
-    }
-    if (
-      entry.name.endsWith(".ts") &&
-      !entry.name.endsWith(".test.ts") &&
-      !entry.name.endsWith(".spec.ts")
-    ) {
-      files.push(fullPath);
-    }
-  }
-  return files;
-}
-
-/**
- * Extract all `openclaw/...` import specifiers from source text.
- * Matches: import ... from "openclaw/...", import("openclaw/...")
- */
-function findOpenclawImports(source: string): string[] {
-  return [
-    ...source.matchAll(/from\s+["'](openclaw\/[^"']+)["']/g),
-    ...source.matchAll(/import\(\s*["'](openclaw\/[^"']+)["']\s*\)/g),
-  ].map((match) => match[1]);
-}
-
-/** Check if an import specifier is an allowed openclaw/plugin-sdk subpath. */
-const ALLOWED_PREFIX = ["openclaw", "plugin-sdk"].join("/");
-function isAllowedImport(specifier: string): boolean {
-  return specifier.startsWith(ALLOWED_PREFIX);
-}
-
-describe("engine import boundary", () => {
-  it("only imports from openclaw/plugin-sdk, never from other openclaw internals", () => {
-    const sourceFiles = walkSourceFiles(ENGINE_DIR);
-    const offenders: Array<{ file: string; imports: string[] }> = [];
-
-    for (const file of sourceFiles) {
-      const source = fs.readFileSync(file, "utf8");
-      const openclawImports = findOpenclawImports(source);
-      const forbidden = openclawImports.filter((specifier) => !isAllowedImport(specifier));
-
-      if (forbidden.length > 0) {
-        offenders.push({
-          file: path.relative(ENGINE_DIR, file),
-          imports: forbidden,
-        });
-      }
-    }
-
-    expect(offenders).toEqual([]);
-  });
-});

package/src/engine/gateway/codec.ts

@@ -1,47 +0,0 @@
-/**
- * Gateway message decoding utilities.
- *
- * Extracted from `gateway.ts` — handles the various data formats that
- * the QQ Bot WebSocket can deliver (string, Buffer, Buffer[], ArrayBuffer).
- *
- * Zero external dependencies beyond Node.js built-ins.
- */
-
-/**
- * Decode raw WebSocket `data` into a UTF-8 string.
- *
- * The QQ Bot gateway can send data as a plain string, a single Buffer,
- * an array of Buffer chunks, an ArrayBuffer, or a typed array view.
- */
-export function decodeGatewayMessageData(data: unknown): string {
-  if (typeof data === "string") {
-    return data;
-  }
-  if (Buffer.isBuffer(data)) {
-    return data.toString("utf8");
-  }
-  if (Array.isArray(data) && data.every((chunk) => Buffer.isBuffer(chunk))) {
-    return Buffer.concat(data).toString("utf8");
-  }
-  if (data instanceof ArrayBuffer) {
-    return Buffer.from(data).toString("utf8");
-  }
-  if (ArrayBuffer.isView(data)) {
-    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8");
-  }
-  return "";
-}
-
-/**
- * Read the optional `message_scene.ext` array from an event payload.
- *
- * Guild, C2C, and Group events may carry a `message_scene` object
- * with an `ext` string array used for ref-index parsing.
- */
-export function readOptionalMessageSceneExt(event: Record<string, unknown>): string[] | undefined {
-  if (!("message_scene" in event)) {
-    return undefined;
-  }
-  const scene = event.message_scene as { ext?: string[] } | undefined;
-  return scene?.ext;
-}