@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

package/src/bridge/logger.ts

@@ -1,31 +0,0 @@
-/**
- * Bridge-layer logger — holds the framework logger injected at gateway startup.
- *
- * Bridge modules (approval, tools, etc.) use this instead of `console.log` or
- * engine's `debugLog` so that all logs flow through the OpenClaw log system.
- */
-
-interface BridgeLogger {
-  info: (msg: string) => void;
-  error: (msg: string) => void;
-  warn?: (msg: string) => void;
-  debug?: (msg: string) => void;
-}
-
-let _logger: BridgeLogger | null = null;
-
-/** Register the framework logger. Called once in startGateway(). */
-export function setBridgeLogger(logger: BridgeLogger): void {
-  _logger = logger;
-}
-
-/** Get the bridge logger. Falls back to console if not yet registered. */
-export function getBridgeLogger(): BridgeLogger {
-  return (
-    _logger ?? {
-      info: (msg) => console.log(msg),
-      error: (msg) => console.error(msg),
-      debug: (msg) => console.log(msg),
-    }
-  );
-}

package/src/bridge/narrowing.ts

@@ -1,31 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-import type { PluginRuntime } from "openclaw/plugin-sdk/core";
-import type { GatewayAccount } from "../engine/types.js";
-import type { ResolvedQQBotAccount } from "../types.js";
-
-/**
- * Map resolved plugin account to the engine gateway account shape (single assertion on nested config).
- */
-export function toGatewayAccount(account: ResolvedQQBotAccount): GatewayAccount {
-  return {
-    accountId: account.accountId,
-    appId: account.appId,
-    clientSecret: account.clientSecret,
-    markdownSupport: account.markdownSupport,
-    systemPrompt: account.systemPrompt,
-    config: account.config as GatewayAccount["config"],
-  };
-}
-
-/**
- * Persist OpenClaw config through the injected plugin runtime (typed entry point).
- */
-export async function writeOpenClawConfigThroughRuntime(
-  runtime: PluginRuntime,
-  cfg: OpenClawConfig,
-): Promise<void> {
-  await runtime.config.replaceConfigFile({
-    nextConfig: cfg,
-    afterWrite: { mode: "auto" },
-  });
-}

package/src/bridge/plugin-version.test.ts

@@ -1,146 +0,0 @@
-/**
- * Tests for `resolveQQBotPluginVersion`.
- *
- * These exercise the directory-walk lookup against controlled fixture
- * trees rather than the repo's real `package.json`, so the behaviour
- * is deterministic regardless of where the test runs.
- */
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { QQBOT_PLUGIN_VERSION_UNKNOWN, resolveQQBotPluginVersion } from "./plugin-version.js";
-
-/** Create a temp directory tree for an individual test and return its root. */
-function createTempTree(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), "qqbot-pkg-version-"));
-}
-
-function writeJson(file: string, data: unknown): void {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, JSON.stringify(data), "utf8");
-}
-
-function fakeEntryFileUrl(dir: string): string {
-  const entryPath = path.join(dir, "gateway.ts");
-  // File need not exist for `fileURLToPath` to work; the resolver
-  // only uses its *parent directory* as the walk start point.
-  return pathToFileURL(entryPath).href;
-}
-
-describe("resolveQQBotPluginVersion", () => {
-  let tempRoots: string[] = [];
-
-  beforeEach(() => {
-    tempRoots = [];
-  });
-
-  afterEach(() => {
-    for (const root of tempRoots) {
-      fs.rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  function newTree(): string {
-    const root = createTempTree();
-    tempRoots.push(root);
-    return root;
-  }
-
-  it("returns the version from the nearest matching package.json", () => {
-    const root = newTree();
-    const pluginDir = path.join(root, "extensions", "qqbot");
-    const bridgeDir = path.join(pluginDir, "src", "bridge");
-    writeJson(path.join(pluginDir, "package.json"), {
-      name: "@openclaw/qqbot",
-      version: "2026.4.16",
-    });
-    fs.mkdirSync(bridgeDir, { recursive: true });
-
-    const version = resolveQQBotPluginVersion(fakeEntryFileUrl(bridgeDir));
-
-    expect(version).toBe("2026.4.16");
-  });
-
-  it("skips package.json files whose name field does not match", () => {
-    const root = newTree();
-    // Parent package.json belongs to the framework, not the plugin.
-    writeJson(path.join(root, "package.json"), {
-      name: "openclaw",
-      version: "9.9.9",
-    });
-    const pluginDir = path.join(root, "extensions", "qqbot");
-    const bridgeDir = path.join(pluginDir, "src", "bridge");
-    writeJson(path.join(pluginDir, "package.json"), {
-      name: "@openclaw/qqbot",
-      version: "2026.4.16",
-    });
-    fs.mkdirSync(bridgeDir, { recursive: true });
-
-    const version = resolveQQBotPluginVersion(fakeEntryFileUrl(bridgeDir));
-
-    // Must stop at the plugin manifest, never bubble up to the framework one.
-    expect(version).toBe("2026.4.16");
-  });
-
-  it("ignores manifests with unrelated name and returns unknown when no match is found", () => {
-    const root = newTree();
-    // Only an unrelated manifest exists up the tree.
-    writeJson(path.join(root, "package.json"), {
-      name: "some-other-package",
-      version: "1.0.0",
-    });
-    const startDir = path.join(root, "extensions", "qqbot", "src", "bridge");
-    fs.mkdirSync(startDir, { recursive: true });
-
-    const version = resolveQQBotPluginVersion(fakeEntryFileUrl(startDir));
-
-    expect(version).toBe(QQBOT_PLUGIN_VERSION_UNKNOWN);
-  });
-
-  it("returns unknown when no package.json exists above the start directory", () => {
-    const root = newTree();
-    const startDir = path.join(root, "extensions", "qqbot", "src", "bridge");
-    fs.mkdirSync(startDir, { recursive: true });
-
-    const version = resolveQQBotPluginVersion(fakeEntryFileUrl(startDir));
-
-    expect(version).toBe(QQBOT_PLUGIN_VERSION_UNKNOWN);
-  });
-
-  it("returns unknown when the matching manifest lacks a version field", () => {
-    const root = newTree();
-    const pluginDir = path.join(root, "extensions", "qqbot");
-    const bridgeDir = path.join(pluginDir, "src", "bridge");
-    writeJson(path.join(pluginDir, "package.json"), {
-      name: "@openclaw/qqbot",
-      // version intentionally missing
-    });
-    fs.mkdirSync(bridgeDir, { recursive: true });
-
-    const version = resolveQQBotPluginVersion(fakeEntryFileUrl(bridgeDir));
-
-    expect(version).toBe(QQBOT_PLUGIN_VERSION_UNKNOWN);
-  });
-
-  it("tolerates a malformed package.json and keeps walking", () => {
-    const root = newTree();
-    const pluginDir = path.join(root, "extensions", "qqbot");
-    const bridgeDir = path.join(pluginDir, "src", "bridge");
-    // Broken manifest at the expected plugin location.
-    fs.mkdirSync(pluginDir, { recursive: true });
-    fs.writeFileSync(path.join(pluginDir, "package.json"), "{ not valid json", "utf8");
-    // Valid matching manifest higher up (unusual layout but still resolvable).
-    writeJson(path.join(root, "package.json"), {
-      name: "@openclaw/qqbot",
-      version: "2026.9.9",
-    });
-    fs.mkdirSync(bridgeDir, { recursive: true });
-
-    const version = resolveQQBotPluginVersion(fakeEntryFileUrl(bridgeDir));
-
-    expect(version).toBe("2026.9.9");
-  });
-});

package/src/bridge/plugin-version.ts

@@ -1,102 +0,0 @@
-/**
- * QQBot plugin version resolver.
- *
- * Reads the version field from this plugin's own `package.json` by
- * walking up the directory tree starting from `import.meta.url` of the
- * caller until a `package.json` whose `name` field matches the plugin
- * package id is located.
- *
- * Why not a hardcoded relative path?
- *   - The source file can live at different depths depending on whether
- *     we run from raw sources (`src/bridge/gateway.ts`) or a future
- *     compiled output. Hardcoding `"../../package.json"` breaks as soon
- *     as the source layout changes, which is what caused the previous
- *     `vunknown` regression.
- *   - A `name` guard prevents accidentally reading the parent
- *     `openclaw/package.json` (the framework root) when the plugin
- *     lives inside the monorepo.
- *
- * The lookup is performed only once per process at startup, so the
- * synchronous file I/O is negligible.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-/** `name` field in this plugin's `package.json`. */
-const QQBOT_PLUGIN_PKG_NAME = "@openclaw/qqbot";
-
-/** Sentinel used when the version cannot be resolved. */
-export const QQBOT_PLUGIN_VERSION_UNKNOWN = "unknown";
-
-/**
- * Resolve the QQBot plugin version from `package.json`.
- *
- * @param startUrl — pass `import.meta.url` from the call site so the
- *   lookup begins at the caller's file regardless of where this helper
- *   itself lives. Falls back to this module's own location when omitted.
- */
-export function resolveQQBotPluginVersion(startUrl?: string): string {
-  const entryUrl = startUrl ?? import.meta.url;
-  let dir: string;
-  try {
-    dir = path.dirname(fileURLToPath(entryUrl));
-  } catch {
-    return QQBOT_PLUGIN_VERSION_UNKNOWN;
-  }
-
-  const root = path.parse(dir).root;
-  while (dir && dir !== root) {
-    const candidate = path.join(dir, "package.json");
-    if (fs.existsSync(candidate)) {
-      const version = readQQBotVersionFromManifest(candidate);
-      if (version) {
-        return version;
-      }
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) {
-      break;
-    }
-    dir = parent;
-  }
-
-  return QQBOT_PLUGIN_VERSION_UNKNOWN;
-}
-
-/**
- * Read the `version` field from a `package.json` file and return it
- * only when the manifest describes the QQBot plugin itself.
- *
- * Returning `null` for mismatched or malformed manifests lets the
- * caller keep walking up the directory tree until the correct package
- * boundary is located.
- */
-function readQQBotVersionFromManifest(manifestPath: string): string | null {
-  let raw: string;
-  try {
-    raw = fs.readFileSync(manifestPath, "utf8");
-  } catch {
-    return null;
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return null;
-  }
-
-  if (!parsed || typeof parsed !== "object") {
-    return null;
-  }
-  const manifest = parsed as { name?: unknown; version?: unknown };
-  if (manifest.name !== QQBOT_PLUGIN_PKG_NAME) {
-    return null;
-  }
-  if (typeof manifest.version !== "string" || manifest.version.length === 0) {
-    return null;
-  }
-  return manifest.version;
-}

package/src/bridge/runtime.ts

@@ -1,25 +0,0 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk/core";
-import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
-import type { GatewayPluginRuntime } from "../engine/gateway/types.js";
-import { setOpenClawVersion } from "../engine/messaging/sender.js";
-
-// Single plugin runtime per process — concurrent multi-tenant qqbot runtimes are not supported.
-const { setRuntime: _setRuntime, getRuntime: getQQBotRuntime } =
-  createPluginRuntimeStore<PluginRuntime>({
-    pluginId: "qqbot",
-    errorMessage: "QQBot runtime not initialized",
-  });
-
-/** Set the QQBot runtime and inject the framework version into the User-Agent. */
-function setQQBotRuntime(runtime: PluginRuntime): void {
-  _setRuntime(runtime);
-  // Inject the framework version into the User-Agent string (same as standalone).
-  setOpenClawVersion(runtime.version);
-}
-
-export { getQQBotRuntime, setQQBotRuntime };
-
-/** Type-narrowed getter for engine/ modules that need GatewayPluginRuntime. */
-export function getQQBotRuntimeForEngine(): GatewayPluginRuntime {
-  return getQQBotRuntime() as GatewayPluginRuntime;
-}

package/src/bridge/sdk-adapter.ts

@@ -1,131 +0,0 @@
-/**
- * SDK adapter — binds engine port interfaces to the framework's shared
- * SDK implementations.
- *
- * This file lives in bridge/ (not engine/) because it imports from
- * `openclaw/plugin-sdk/*`. The engine layer stays zero-SDK-dependency;
- * only the bridge layer couples to the framework.
- */
-
-import {
-  implicitMentionKindWhen,
-  resolveInboundMentionDecision,
-} from "openclaw/plugin-sdk/channel-mention-gating";
-import {
-  buildPendingHistoryContextFromMap,
-  clearHistoryEntriesIfEnabled,
-  recordPendingHistoryEntryIfEnabled,
-  type HistoryEntry as SdkHistoryEntry,
-} from "openclaw/plugin-sdk/reply-history";
-import type { HistoryPort, HistoryEntryLike } from "../engine/adapter/history.port.js";
-import type {
-  MentionGatePort,
-  MentionGateDecision,
-  MentionFacts,
-  MentionPolicy,
-} from "../engine/adapter/mention-gate.port.js";
-
-// ============ History Adapter ============
-
-// Helper: cast engine Map to SDK Map. TypeScript Map is invariant on its
-// value type, but the shapes are structurally identical (HistoryEntryLike
-// ⊇ SdkHistoryEntry). The `as unknown as` double-cast is safe here.
-function asSdkMap<T>(map: Map<string, T[]>): Map<string, SdkHistoryEntry[]> {
-  return map as unknown as Map<string, SdkHistoryEntry[]>;
-}
-
-/**
- * History adapter backed by SDK `reply-history`.
- *
- * Delegates record/build/clear to the SDK's shared implementation so
- * the engine benefits from SDK improvements (e.g. future visibility
- * filtering) without code duplication.
- */
-export function createSdkHistoryAdapter(): HistoryPort {
-  return {
-    recordPendingHistoryEntry<T extends HistoryEntryLike>(params: {
-      historyMap: Map<string, T[]>;
-      historyKey: string;
-      entry?: T | null;
-      limit: number;
-    }): T[] {
-      return recordPendingHistoryEntryIfEnabled({
-        historyMap: asSdkMap(params.historyMap),
-        historyKey: params.historyKey,
-        entry: params.entry as SdkHistoryEntry | undefined,
-        limit: params.limit,
-      }) as T[];
-    },
-
-    buildPendingHistoryContext(params: {
-      historyMap: Map<string, HistoryEntryLike[]>;
-      historyKey: string;
-      limit: number;
-      currentMessage: string;
-      formatEntry: (entry: HistoryEntryLike) => string;
-      lineBreak?: string;
-    }): string {
-      return buildPendingHistoryContextFromMap({
-        historyMap: asSdkMap(params.historyMap),
-        historyKey: params.historyKey,
-        limit: params.limit,
-        currentMessage: params.currentMessage,
-        formatEntry: params.formatEntry as (entry: SdkHistoryEntry) => string,
-        lineBreak: params.lineBreak,
-      });
-    },
-
-    clearPendingHistory(params: {
-      historyMap: Map<string, HistoryEntryLike[]>;
-      historyKey: string;
-      limit: number;
-    }): void {
-      clearHistoryEntriesIfEnabled({
-        historyMap: asSdkMap(params.historyMap),
-        historyKey: params.historyKey,
-        limit: params.limit,
-      });
-    },
-  };
-}
-
-// ============ MentionGate Adapter ============
-
-/**
- * MentionGate adapter backed by SDK `channel-mention-gating`.
- *
- * Maps the engine's mention facts/policy to the SDK's
- * `resolveInboundMentionDecision` call, normalizing the implicit
- * mention boolean into the SDK's typed `ImplicitMentionKind[]`.
- */
-export function createSdkMentionGateAdapter(): MentionGatePort {
-  return {
-    resolveInboundMentionDecision(params: {
-      facts: MentionFacts;
-      policy: MentionPolicy;
-    }): MentionGateDecision {
-      const result = resolveInboundMentionDecision({
-        facts: {
-          canDetectMention: params.facts.canDetectMention,
-          wasMentioned: params.facts.wasMentioned,
-          hasAnyMention: params.facts.hasAnyMention,
-          implicitMentionKinds:
-            params.facts.implicitMentionKinds ?? implicitMentionKindWhen("reply_to_bot", false),
-        },
-        policy: {
-          isGroup: params.policy.isGroup,
-          requireMention: params.policy.requireMention,
-          allowTextCommands: params.policy.allowTextCommands,
-          hasControlCommand: params.policy.hasControlCommand,
-          commandAuthorized: params.policy.commandAuthorized,
-        },
-      });
-      return {
-        effectiveWasMentioned: result.effectiveWasMentioned,
-        shouldSkip: result.shouldSkip,
-        shouldBypassMention: result.shouldBypassMention,
-        implicitMention: result.implicitMention,
-      };
-    },
-  };
-}

package/src/bridge/setup/finalize.ts

@@ -1,144 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-import type { ChannelSetupWizard } from "openclaw/plugin-sdk/setup";
-import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
-import { formatDocsLink } from "openclaw/plugin-sdk/setup-tools";
-import { applyQQBotAccountConfig, resolveQQBotAccount } from "../config.js";
-
-type SetupPrompter = Parameters<NonNullable<ChannelSetupWizard["finalize"]>>[0]["prompter"];
-type SetupRuntime = Parameters<NonNullable<ChannelSetupWizard["finalize"]>>[0]["runtime"];
-
-function isQQBotAccountConfigured(cfg: OpenClawConfig, accountId: string): boolean {
-  const account = resolveQQBotAccount(cfg, accountId, { allowUnresolvedSecretRef: true });
-  return Boolean(account.appId && account.clientSecret);
-}
-
-async function linkViaQrCode(params: {
-  cfg: OpenClawConfig;
-  accountId: string;
-  prompter: SetupPrompter;
-  runtime: SetupRuntime;
-}): Promise<OpenClawConfig> {
-  try {
-    const { qrConnect } = await import("@tencent-connect/qqbot-connector");
-
-    const accounts: { appId: string; appSecret: string }[] = await qrConnect({
-      source: "openclaw",
-    });
-
-    if (accounts.length === 0) {
-      await params.prompter.note("未获取到任何 QQ Bot 账号信息。", "QQ Bot");
-      return params.cfg;
-    }
-
-    let next = params.cfg;
-
-    for (let i = 0; i < accounts.length; i++) {
-      const { appId, appSecret } = accounts[i];
-      // use current account id for first account, and use app id for subsequent accounts
-      const targetAccountId = i === 0 ? params.accountId : appId;
-
-      next = applyQQBotAccountConfig(next, targetAccountId, {
-        appId,
-        clientSecret: appSecret,
-      });
-    }
-
-    if (accounts.length === 1) {
-      params.runtime.log(`✔ QQ Bot 绑定成功！(AppID: ${accounts[0].appId})`);
-    } else {
-      const idList = accounts.map((a) => a.appId).join(", ");
-      params.runtime.log(`✔ ${accounts.length} 个 QQ Bot 绑定成功！(AppID: ${idList})`);
-    }
-
-    return next;
-  } catch (error) {
-    params.runtime.error(`QQ Bot 绑定失败: ${String(error)}`);
-    await params.prompter.note(
-      [
-        "绑定失败，您可以稍后手动配置。",
-        `文档: ${formatDocsLink("/channels/qqbot", "qqbot")}`,
-      ].join("\n"),
-      "QQ Bot",
-    );
-    return params.cfg;
-  }
-}
-
-async function linkViaManualInput(params: {
-  cfg: OpenClawConfig;
-  accountId: string;
-  prompter: SetupPrompter;
-}): Promise<OpenClawConfig> {
-  const appId = await params.prompter.text({
-    message: "请输入 QQ Bot AppID",
-    validate: (value: string) => (value.trim() ? undefined : "AppID 不能为空"),
-  });
-
-  const appSecret = await params.prompter.text({
-    message: "请输入 QQ Bot AppSecret",
-    validate: (value: string) => (value.trim() ? undefined : "AppSecret 不能为空"),
-  });
-
-  const next = applyQQBotAccountConfig(params.cfg, params.accountId, {
-    appId: appId.trim(),
-    clientSecret: appSecret.trim(),
-  });
-
-  await params.prompter.note("✔ QQ Bot 配置完成！", "QQ Bot");
-  return next;
-}
-
-export async function finalizeQQBotSetup(params: {
-  cfg: OpenClawConfig;
-  accountId: string;
-  forceAllowFrom: boolean;
-  prompter: SetupPrompter;
-  runtime: SetupRuntime;
-}): Promise<{ cfg: OpenClawConfig }> {
-  const accountId = params.accountId.trim() || DEFAULT_ACCOUNT_ID;
-  let next = params.cfg;
-
-  const configured = isQQBotAccountConfigured(next, accountId);
-
-  const mode = await params.prompter.select({
-    message: configured ? "QQ 已绑定，选择操作" : "选择 QQ 绑定方式",
-    options: [
-      {
-        value: "qr",
-        label: "扫码绑定（推荐）",
-        hint: "使用 QQ 扫描二维码自动完成绑定",
-      },
-      {
-        value: "manual",
-        label: "手动输入 QQ Bot AppID 和 AppSecret",
-        hint: "需到 QQ 开放平台 q.qq.com 查看",
-      },
-      {
-        value: "skip",
-        label: configured ? "保持当前配置" : "稍后配置",
-      },
-    ],
-  });
-
-  if (mode === "qr") {
-    next = await linkViaQrCode({
-      cfg: next,
-      accountId,
-      prompter: params.prompter,
-      runtime: params.runtime,
-    });
-  } else if (mode === "manual") {
-    next = await linkViaManualInput({
-      cfg: next,
-      accountId,
-      prompter: params.prompter,
-    });
-  } else if (!configured) {
-    await params.prompter.note(
-      ["您可以稍后运行以下命令重新选择 QQ Bot 进行配置：", "  openclaw channels add"].join("\n"),
-      "QQ Bot",
-    );
-  }
-
-  return { cfg: next };
-}

package/src/bridge/setup/surface.ts

@@ -1,34 +0,0 @@
-import {
-  createStandardChannelSetupStatus,
-  setSetupChannelEnabled,
-} from "openclaw/plugin-sdk/setup";
-import type { ChannelSetupWizard } from "openclaw/plugin-sdk/setup";
-import { isAccountConfigured } from "../../engine/config/resolve.js";
-import { listQQBotAccountIds, resolveQQBotAccount } from "../config.js";
-import { finalizeQQBotSetup } from "./finalize.js";
-
-const channel = "qqbot" as const;
-
-export const qqbotSetupWizard: ChannelSetupWizard = {
-  channel,
-  status: createStandardChannelSetupStatus({
-    channelLabel: "QQ Bot",
-    configuredLabel: "configured",
-    unconfiguredLabel: "needs AppID + AppSercet",
-    configuredHint: "configured",
-    unconfiguredHint: "needs AppID + AppSercet",
-    configuredScore: 1,
-    unconfiguredScore: 6,
-    resolveConfigured: ({ cfg, accountId }) =>
-      (accountId ? [accountId] : listQQBotAccountIds(cfg)).some((resolvedAccountId) => {
-        const account = resolveQQBotAccount(cfg, resolvedAccountId, {
-          allowUnresolvedSecretRef: true,
-        });
-        return isAccountConfigured(account as never);
-      }),
-  }),
-  credentials: [],
-  finalize: async ({ cfg, accountId, forceAllowFrom, prompter, runtime }) =>
-    await finalizeQQBotSetup({ cfg, accountId, forceAllowFrom, prompter, runtime }),
-  disable: (cfg) => setSetupChannelEnabled(cfg, channel, false),
-};