@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/commands/slash-command-auth.ts

@@ -0,0 +1,48 @@
+/**
+ * Pre-dispatch authorization for requireAuth slash commands.
+ *
+ * Unlike the access-stage's `resolveCommandAuthorized` (which permits
+ * `dm_policy_open` senders — i.e. anyone), this function requires the
+ * sender to appear in an **explicit non-wildcard** allowFrom list.
+ *
+ * Rationale: sensitive operations (log export, file deletion, approval
+ * config changes) must be gated behind a deliberate operator decision.
+ * A wide-open DM policy means "anyone can chat", not "anyone can run
+ * admin commands".
+ */
+
+import { createQQBotSenderMatcher, normalizeQQBotAllowFrom } from "../access/index.js";
+
+/**
+ * Determine whether `senderId` is authorized to execute `requireAuth`
+ * slash commands for the given account configuration.
+ *
+ * Authorization rules:
+ * - `allowFrom` not configured / empty / only `["*"]` → **false**
+ *   (wildcard means "open to everyone", not explicit authorization)
+ * - `allowFrom` contains at least one concrete entry AND sender
+ *   matches → **true**
+ * - Group messages use `groupAllowFrom` when present, falling back
+ *   to `allowFrom`.
+ */
+export function resolveSlashCommandAuth(params: {
+  senderId: string;
+  isGroup: boolean;
+  allowFrom?: Array<string | number>;
+  groupAllowFrom?: Array<string | number>;
+}): boolean {
+  const rawList =
+    params.isGroup && params.groupAllowFrom && params.groupAllowFrom.length > 0
+      ? params.groupAllowFrom
+      : params.allowFrom;
+
+  const normalized = normalizeQQBotAllowFrom(rawList);
+
+  // Require at least one explicit (non-wildcard) entry.
+  const hasExplicitEntry = normalized.some((entry) => entry !== "*");
+  if (!hasExplicitEntry) {
+    return false;
+  }
+
+  return createQQBotSenderMatcher(params.senderId)(normalized);
+}

package/src/engine/commands/slash-command-handler.ts

@@ -0,0 +1,146 @@
+/**
+ * Slash command handler — intercept slash commands before message queue.
+ *
+ * Extracted from gateway.ts to keep the gateway connection logic thin.
+ * Handles urgent commands, normal slash commands, and file delivery.
+ */
+
+import type { QueuedMessage } from "../gateway/message-queue.js";
+import type { GatewayAccount, EngineLogger } from "../gateway/types.js";
+import { sendDocument } from "../messaging/outbound.js";
+import {
+  sendText as senderSendText,
+  buildDeliveryTarget,
+  accountToCreds,
+} from "../messaging/sender.js";
+import { resolveSlashCommandAuth } from "./slash-command-auth.js";
+import { matchSlashCommand } from "./slash-commands-impl.js";
+import type { SlashCommandContext, QueueSnapshot } from "./slash-commands.js";
+
+// ============ Types ============
+
+export interface SlashCommandHandlerContext {
+  account: GatewayAccount;
+  log?: EngineLogger;
+  getMessagePeerId: (msg: QueuedMessage) => string;
+  getQueueSnapshot: (peerId: string) => QueueSnapshot;
+}
+
+// ============ Constants ============
+
+const URGENT_COMMANDS = ["/stop"];
+
+// ============ trySlashCommandOrEnqueue ============
+
+/**
+ * Check if the message is a slash command and handle it.
+ *
+ * @returns `true` if handled (command executed or enqueued as urgent),
+ *          `false` if the message should be queued for normal processing.
+ */
+export async function trySlashCommand(
+  msg: QueuedMessage,
+  ctx: SlashCommandHandlerContext,
+): Promise<"handled" | "urgent" | "enqueue"> {
+  const { account, log } = ctx;
+  const content = (msg.content ?? "").trim();
+
+  if (!content.startsWith("/")) {
+    return "enqueue";
+  }
+
+  // Urgent command detection — bypass queue and execute immediately.
+  const contentLower = content.toLowerCase();
+  const isUrgentCommand = URGENT_COMMANDS.some(
+    (cmd) => contentLower === cmd.toLowerCase() || contentLower.startsWith(cmd.toLowerCase() + " "),
+  );
+  if (isUrgentCommand) {
+    log?.info(`Urgent command detected: ${content.slice(0, 20)}`);
+    return "urgent";
+  }
+
+  // Normal slash command — try to match and execute.
+  const receivedAt = Date.now();
+  const peerId = ctx.getMessagePeerId(msg);
+  const cmdCtx: SlashCommandContext = {
+    type: msg.type,
+    senderId: msg.senderId,
+    senderName: msg.senderName,
+    messageId: msg.messageId,
+    eventTimestamp: msg.timestamp,
+    receivedAt,
+    rawContent: content,
+    args: "",
+    channelId: msg.channelId,
+    groupOpenid: msg.groupOpenid,
+    accountId: account.accountId,
+    appId: account.appId,
+    accountConfig: account.config,
+    commandAuthorized: resolveSlashCommandAuth({
+      senderId: msg.senderId,
+      isGroup: msg.type === "group" || msg.type === "guild",
+      allowFrom: account.config?.allowFrom,
+      groupAllowFrom: account.config?.groupAllowFrom,
+    }),
+    queueSnapshot: ctx.getQueueSnapshot(peerId),
+  };
+
+  try {
+    const reply = await matchSlashCommand(cmdCtx);
+    if (reply === null) {
+      return "enqueue";
+    }
+
+    log?.debug?.(`Slash command matched: ${content}`);
+
+    const isFileResult = typeof reply === "object" && reply !== null && "filePath" in reply;
+    const replyText = isFileResult ? (reply as { text: string }).text : reply;
+    const replyFile = isFileResult ? (reply as { filePath: string }).filePath : null;
+
+    // Send text reply.
+    if (msg.type === "c2c" || msg.type === "group" || msg.type === "dm" || msg.type === "guild") {
+      const slashTarget = buildDeliveryTarget(msg);
+      const slashCreds = accountToCreds(account);
+      await senderSendText(slashTarget, replyText, slashCreds, { msgId: msg.messageId });
+    }
+
+    // Send file attachment if present.
+    if (replyFile) {
+      try {
+        const targetType =
+          msg.type === "group"
+            ? "group"
+            : msg.type === "dm"
+              ? "dm"
+              : msg.type === "c2c"
+                ? "c2c"
+                : "channel";
+        const targetId =
+          msg.type === "group"
+            ? msg.groupOpenid || msg.senderId
+            : msg.type === "dm"
+              ? msg.guildId || msg.senderId
+              : msg.type === "c2c"
+                ? msg.senderId
+                : msg.channelId || msg.senderId;
+        await sendDocument(
+          {
+            targetType,
+            targetId,
+            account,
+            replyToId: msg.messageId,
+          },
+          replyFile,
+          { allowQQBotDataDownloads: true },
+        );
+      } catch (fileErr) {
+        log?.error(`Failed to send slash command file: ${String(fileErr)}`);
+      }
+    }
+
+    return "handled";
+  } catch (err) {
+    log?.error(`Slash command error: ${String(err)}`);
+    return "enqueue";
+  }
+}

package/src/engine/commands/slash-commands-impl.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+import { getFrameworkCommands } from "./slash-commands-impl.js";
+
+describe("QQBot framework slash commands", () => {
+  it("routes bot-approve through the auth-gated framework registry", () => {
+    expect(getFrameworkCommands().map((command) => command.name)).toContain("bot-approve");
+  });
+});

package/src/engine/commands/slash-commands-impl.ts

@@ -0,0 +1,61 @@
+/**
+ * QQBot plugin-level slash command handler.
+ *
+ * Type definitions and the command registry/dispatcher are in
+ * `./slash-commands.ts`. Built-in command bodies live under `./builtin/`.
+ */
+
+import type { CommandsPort } from "../adapter/commands.port.js";
+import { debugLog } from "../utils/log.js";
+import { registerBuiltinSlashCommands } from "./builtin/register-all.js";
+import {
+  getFrameworkVersionString,
+  getPluginVersionString,
+  initSlashCommandDeps,
+} from "./builtin/state.js";
+import {
+  SlashCommandRegistry,
+  type SlashCommandContext,
+  type SlashCommandResult,
+  type QQBotFrameworkCommand,
+} from "./slash-commands.js";
+
+const registry = new SlashCommandRegistry();
+registerBuiltinSlashCommands(registry);
+
+/**
+ * Initialize command dependencies from the EngineAdapters.commands port.
+ * Called once by the bridge layer during startup.
+ */
+export function initCommands(port: CommandsPort): void {
+  initSlashCommandDeps(port);
+}
+
+/**
+ * Return all commands that require authorization, for registration with the
+ * framework via api.registerCommand() in registerFull().
+ */
+export function getFrameworkCommands(): QQBotFrameworkCommand[] {
+  return registry.getFrameworkCommands();
+}
+
+// Slash command entry point — delegates to core/ registry.
+
+/**
+ * Try to match and execute a plugin-level slash command.
+ *
+ * @returns A reply when matched, or null when the message should continue through normal routing.
+ */
+export async function matchSlashCommand(ctx: SlashCommandContext): Promise<SlashCommandResult> {
+  return registry.matchSlashCommand(ctx, { info: debugLog });
+}
+
+/** Return the plugin version for external callers. */
+export function getPluginVersion(): string {
+  return getPluginVersionString();
+}
+
+/** Return the framework version for external callers. */
+export function getFrameworkVersion(): string {
+  return getFrameworkVersionString();
+}

package/src/engine/commands/slash-commands.ts

@@ -0,0 +1,199 @@
+/**
+ * Slash command registration and dispatch framework.
+ *
+ * This module provides the type definitions, command registry, and
+ * `matchSlashCommand` dispatcher that both plugin versions share.
+ *
+ * Concrete command implementations (e.g. `/bot-ping`, `/bot-logs`) are
+ * registered by the upper-layer bootstrap code, NOT defined here.
+ *
+ * Zero external dependencies.
+ */
+
+// ============ Types ============
+
+/** Slash command context (message metadata plus runtime state). */
+export interface SlashCommandContext {
+  /** Message type. */
+  type: "c2c" | "guild" | "dm" | "group";
+  /** Sender ID. */
+  senderId: string;
+  /** Sender display name. */
+  senderName?: string;
+  /** Message ID used for passive replies. */
+  messageId: string;
+  /** Event timestamp from QQ as an ISO string. */
+  eventTimestamp: string;
+  /** Local receipt timestamp in milliseconds. */
+  receivedAt: number;
+  /** Raw message content. */
+  rawContent: string;
+  /** Command arguments after stripping the command name. */
+  args: string;
+  /** Channel ID for guild messages. */
+  channelId?: string;
+  /** Group openid for group messages. */
+  groupOpenid?: string;
+  /** Account ID. */
+  accountId: string;
+  /** Bot App ID. */
+  appId: string;
+  /** Account config available to the command handler. */
+  accountConfig?: Record<string, unknown>;
+  /** Whether the sender is authorized per the allowFrom config. */
+  commandAuthorized: boolean;
+  /** Queue snapshot for the current sender. */
+  queueSnapshot: QueueSnapshot;
+}
+
+/** Queue status snapshot. */
+export interface QueueSnapshot {
+  totalPending: number;
+  activeUsers: number;
+  maxConcurrentUsers: number;
+  senderPending: number;
+}
+
+/** Slash command result: text, a text+file result, or null to skip handling. */
+export type SlashCommandResult = string | SlashCommandFileResult | null;
+
+/** Slash command result that sends text first and then a local file. */
+interface SlashCommandFileResult {
+  text: string;
+  /** Local file path to send. */
+  filePath: string;
+}
+
+/** Slash command definition. */
+interface SlashCommand {
+  /** Command name without the leading slash. */
+  name: string;
+  /** Short description. */
+  description: string;
+  /** Detailed usage text shown by `/command ?`. */
+  usage?: string;
+  /** When true, the command requires the sender to pass the allowFrom authorization check. */
+  requireAuth?: boolean;
+  /** When true, the command is only available in c2c (private) chat. Group invocations are rejected automatically. */
+  c2cOnly?: boolean;
+  /** Command handler. */
+  handler: (ctx: SlashCommandContext) => SlashCommandResult | Promise<SlashCommandResult>;
+}
+
+/** Framework command definition for commands that require authorization. */
+export interface QQBotFrameworkCommand {
+  name: string;
+  description: string;
+  usage?: string;
+  handler: (ctx: SlashCommandContext) => SlashCommandResult | Promise<SlashCommandResult>;
+}
+
+// ============ Command Registry ============
+
+/** Lowercase and trim a string. */
+function lc(s: string): string {
+  return (s ?? "").toLowerCase().trim();
+}
+
+/**
+ * Slash command registry.
+ *
+ * Maintains two maps:
+ * - `commands` — pre-dispatch commands (requireAuth: false)
+ * - `frameworkCommands` — auth-gated commands (requireAuth: true)
+ */
+export class SlashCommandRegistry {
+  private readonly commands = new Map<string, SlashCommand>();
+  private readonly frameworkCommands = new Map<string, SlashCommand>();
+
+  /** Register one command. */
+  register(cmd: SlashCommand): void {
+    const key = lc(cmd.name);
+    // Always register in the pre-dispatch map so QQ message-flow slash
+    // commands can match and execute directly (with requireAuth gating).
+    this.commands.set(key, cmd);
+    // Auth-gated commands are additionally exposed to the framework command
+    // surface (api.registerCommand) for CLI / control-plane invocation.
+    if (cmd.requireAuth) {
+      this.frameworkCommands.set(key, cmd);
+    }
+  }
+
+  /** Return all auth-gated commands for framework registration. */
+  getFrameworkCommands(): QQBotFrameworkCommand[] {
+    return Array.from(this.frameworkCommands.values()).map((cmd) => ({
+      name: cmd.name,
+      description: cmd.description,
+      usage: cmd.usage,
+      handler: cmd.handler,
+    }));
+  }
+
+  /** Return all pre-dispatch commands. */
+  getPreDispatchCommands(): Map<string, SlashCommand> {
+    return this.commands;
+  }
+
+  /** Return all registered commands (both maps) for help listing. */
+  getAllCommands(): Map<string, SlashCommand> {
+    const all = new Map<string, SlashCommand>();
+    for (const [k, v] of this.commands) {
+      all.set(k, v);
+    }
+    for (const [k, v] of this.frameworkCommands) {
+      all.set(k, v);
+    }
+    return all;
+  }
+
+  /**
+   * Try to match and execute a pre-dispatch slash command.
+   *
+   * @returns A reply when matched, or null when the message should continue
+   *          through normal routing.
+   */
+  async matchSlashCommand(
+    ctx: SlashCommandContext,
+    log?: { info?: (msg: string) => void },
+  ): Promise<SlashCommandResult> {
+    const content = ctx.rawContent.trim();
+    if (!content.startsWith("/")) {
+      return null;
+    }
+
+    const spaceIdx = content.indexOf(" ");
+    const cmdName = lc(spaceIdx === -1 ? content.slice(1) : content.slice(1, spaceIdx));
+    const args = spaceIdx === -1 ? "" : content.slice(spaceIdx + 1).trim();
+
+    const cmd = this.commands.get(cmdName);
+    if (!cmd) {
+      return null;
+    }
+
+    // Reject c2cOnly commands when invoked outside private chat.
+    if (cmd.c2cOnly && ctx.type !== "c2c") {
+      return `💡 请在私聊中使用此指令`;
+    }
+
+    // Gate sensitive commands behind the allowFrom authorization check.
+    if (cmd.requireAuth && !ctx.commandAuthorized) {
+      log?.info?.(
+        `[qqbot] Slash command /${cmd.name} rejected: sender ${ctx.senderId} is not authorized`,
+      );
+      const isGroup = ctx.type === "group" || ctx.type === "guild";
+      const configHint = isGroup ? "groupAllowFrom" : "allowFrom";
+      return `⛔ 权限不足：请先在 channels.qqbot.${configHint} 中配置明确的发送者列表后再使用 /${cmd.name}。`;
+    }
+
+    // `/command ?` returns usage help.
+    if (args === "?") {
+      if (cmd.usage) {
+        return `📖 /${cmd.name} 用法：\n\n${cmd.usage}`;
+      }
+      return `/${cmd.name} - ${cmd.description}`;
+    }
+
+    ctx.args = args;
+    return await cmd.handler(ctx);
+  }
+}

package/src/engine/config/credential-backup.test.ts

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getCredentialBackupFile, getLegacyCredentialBackupFile } from "../utils/data-paths.js";
+import { loadCredentialBackup, saveCredentialBackup } from "./credential-backup.js";
+
+/**
+ * These tests write to `~/.openclaw/qqbot/data` under a test-specific
+ * accountId prefix and clean up after themselves. Mirrors the approach
+ * used by `platform.test.ts` in the same package.
+ */
+describe("engine/config/credential-backup", () => {
+  const acct = `test-cb-${process.pid}-${Date.now()}`;
+  const legacyPath = getLegacyCredentialBackupFile();
+  let legacyBackup: string | null = null;
+
+  beforeEach(() => {
+    // Preserve any legacy backup that might happen to live in the user's
+    // real home so we can restore it after the test.
+    legacyBackup = null;
+    if (fs.existsSync(legacyPath)) {
+      legacyBackup = fs.readFileSync(legacyPath, "utf8");
+      fs.unlinkSync(legacyPath);
+    }
+  });
+
+  afterEach(() => {
+    try {
+      fs.unlinkSync(getCredentialBackupFile(acct));
+    } catch {
+      /* ignore */
+    }
+    if (fs.existsSync(legacyPath)) {
+      fs.unlinkSync(legacyPath);
+    }
+    if (legacyBackup != null) {
+      fs.writeFileSync(legacyPath, legacyBackup);
+    }
+  });
+
+  it("round-trips a credential snapshot", () => {
+    saveCredentialBackup(acct, "app-1", "secret-1");
+    const loaded = loadCredentialBackup(acct);
+    expect(loaded?.appId).toBe("app-1");
+    expect(loaded?.clientSecret).toBe("secret-1");
+    expect(loaded?.accountId).toBe(acct);
+    expect(fs.existsSync(getCredentialBackupFile(acct))).toBe(true);
+  });
+
+  it("returns null when no backup exists", () => {
+    expect(loadCredentialBackup(acct)).toBeNull();
+  });
+
+  it("returns null when legacy backup belongs to a different accountId", () => {
+    fs.writeFileSync(
+      legacyPath,
+      JSON.stringify({
+        accountId: "other-acct",
+        appId: "app-old",
+        clientSecret: "secret-old",
+        savedAt: new Date().toISOString(),
+      }),
+    );
+    expect(loadCredentialBackup(acct)).toBeNull();
+  });
+
+  it("migrates legacy single-file backup to per-account path on load", () => {
+    fs.writeFileSync(
+      legacyPath,
+      JSON.stringify({
+        accountId: acct,
+        appId: "app-1",
+        clientSecret: "secret-1",
+        savedAt: new Date().toISOString(),
+      }),
+    );
+
+    const loaded = loadCredentialBackup(acct);
+    expect(loaded?.appId).toBe("app-1");
+    expect(fs.existsSync(legacyPath)).toBe(false);
+    expect(fs.existsSync(getCredentialBackupFile(acct))).toBe(true);
+  });
+
+  it("ignores empty appId/clientSecret on save", () => {
+    saveCredentialBackup(acct, "", "secret");
+    saveCredentialBackup(acct, "app", "");
+    expect(fs.existsSync(getCredentialBackupFile(acct))).toBe(false);
+  });
+});

package/src/engine/config/credential-backup.ts

@@ -0,0 +1,107 @@
+/**
+ * Credential backup & recovery.
+ * 凭证暂存与恢复。
+ *
+ * Solves the "hot-upgrade interrupted, appId/secret vanished from
+ * openclaw.json" failure mode.
+ *
+ * Mechanics:
+ *   - After each successful gateway start we snapshot the currently
+ *     resolved `appId` / `clientSecret` to a per-account backup file.
+ *   - During plugin startup, if the live config has an empty appId or
+ *     secret, the gateway consults the backup and restores the values
+ *     via the config mutation API.
+ *   - Backups live under `~/.openclaw/qqbot/data/` so they survive
+ *     plugin directory replacement.
+ *
+ * Safety notes:
+ *   - Only restore when credentials are **actually empty** — never
+ *     overwrite a user's intentional config change.
+ *   - Atomic write (temp file + rename) to avoid torn files.
+ *   - Per-account file: `credential-backup-<accountId>.json`. We do
+ *     **not** also key by appId because recovery happens precisely
+ *     when appId is unknown.
+ *   - Legacy single `credential-backup.json` is migrated automatically
+ *     when the stored accountId matches the caller.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getCredentialBackupFile, getLegacyCredentialBackupFile } from "../utils/data-paths.js";
+
+interface CredentialBackup {
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  savedAt: string;
+}
+
+/** Persist a credential snapshot (called once gateway reaches READY). */
+export function saveCredentialBackup(accountId: string, appId: string, clientSecret: string): void {
+  if (!appId || !clientSecret) {
+    return;
+  }
+  try {
+    const backupPath = getCredentialBackupFile(accountId);
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    const data: CredentialBackup = {
+      accountId,
+      appId,
+      clientSecret,
+      savedAt: new Date().toISOString(),
+    };
+    const tmpPath = `${backupPath}.tmp`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    fs.renameSync(tmpPath, backupPath);
+  } catch {
+    /* best-effort — ignore */
+  }
+}
+
+/**
+ * Load a credential snapshot for `accountId`.
+ *
+ * Consults the new per-account file first; falls back to the legacy
+ * global backup file and migrates it when the embedded `accountId`
+ * matches the request. Returns `null` when no usable backup exists.
+ */
+export function loadCredentialBackup(accountId?: string): CredentialBackup | null {
+  try {
+    if (accountId) {
+      const newPath = getCredentialBackupFile(accountId);
+      if (fs.existsSync(newPath)) {
+        const data = JSON.parse(fs.readFileSync(newPath, "utf8")) as CredentialBackup;
+        if (data?.appId && data.clientSecret) {
+          return data;
+        }
+      }
+    }
+
+    const legacy = getLegacyCredentialBackupFile();
+    if (fs.existsSync(legacy)) {
+      const data = JSON.parse(fs.readFileSync(legacy, "utf8")) as CredentialBackup;
+      if (!data?.appId || !data?.clientSecret) {
+        return null;
+      }
+      if (accountId && data.accountId !== accountId) {
+        return null;
+      }
+      if (data.accountId) {
+        try {
+          const backupPath = getCredentialBackupFile(data.accountId);
+          fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+          const tmpPath = `${backupPath}.tmp`;
+          fs.writeFileSync(tmpPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+          fs.renameSync(tmpPath, backupPath);
+          fs.unlinkSync(legacy);
+        } catch {
+          /* ignore migration errors */
+        }
+      }
+      return data;
+    }
+  } catch {
+    /* corrupt file — ignore */
+  }
+  return null;
+}