@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/utils/payload.ts

@@ -0,0 +1,145 @@
+/**
+ * Structured payload parsing and encoding for QQ Bot messages.
+ *
+ * Handles `QQBOT_PAYLOAD:` (model-emitted structured payloads) and
+ * `QQBOT_CRON:` (persisted cron reminder payloads).
+ *
+ * Zero external dependencies.
+ */
+
+import type { ChatScope } from "../types.js";
+
+/** Structured reminder payload emitted by the model. */
+export interface CronReminderPayload {
+  type: "cron_reminder";
+  content: string;
+  targetType: ChatScope;
+  targetAddress: string;
+  originalMessageId?: string;
+}
+
+/** Structured media payload emitted by the model. */
+export interface MediaPayload {
+  type: "media";
+  mediaType: "image" | "audio" | "video" | "file";
+  source: "url" | "file";
+  path: string;
+  caption?: string;
+}
+
+type QQBotPayload = CronReminderPayload | MediaPayload;
+
+/** Result of parsing model output into a structured payload. */
+interface ParseResult {
+  isPayload: boolean;
+  payload?: QQBotPayload;
+  text?: string;
+  error?: string;
+}
+
+const PAYLOAD_PREFIX = "QQBOT_PAYLOAD:";
+const CRON_PREFIX = "QQBOT_CRON:";
+
+function formatErr(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** Parse model output that may start with the QQ Bot structured payload prefix. */
+export function parseQQBotPayload(text: string): ParseResult {
+  const trimmedText = text.trim();
+
+  if (!trimmedText.startsWith(PAYLOAD_PREFIX)) {
+    return { isPayload: false, text };
+  }
+
+  const jsonContent = trimmedText.slice(PAYLOAD_PREFIX.length).trim();
+
+  if (!jsonContent) {
+    return { isPayload: true, error: "Payload body is empty" };
+  }
+
+  try {
+    const payload = JSON.parse(jsonContent) as QQBotPayload;
+
+    if (!payload.type) {
+      return { isPayload: true, error: "Payload is missing the type field" };
+    }
+
+    if (payload.type === "cron_reminder") {
+      if (!payload.content || !payload.targetType || !payload.targetAddress) {
+        return {
+          isPayload: true,
+          error:
+            "cron_reminder payload is missing required fields (content, targetType, targetAddress)",
+        };
+      }
+    } else if (payload.type === "media") {
+      if (!payload.mediaType || !payload.source || !payload.path) {
+        return {
+          isPayload: true,
+          error: "media payload is missing required fields (mediaType, source, path)",
+        };
+      }
+    }
+
+    return { isPayload: true, payload };
+  } catch (e) {
+    return { isPayload: true, error: `Failed to parse JSON: ${formatErr(e)}` };
+  }
+}
+
+/** Encode a cron reminder payload into the stored cron-message format. */
+export function encodePayloadForCron(payload: CronReminderPayload): string {
+  const jsonString = JSON.stringify(payload);
+  const base64 = Buffer.from(jsonString, "utf-8").toString("base64");
+  return `${CRON_PREFIX}${base64}`;
+}
+
+/** Decode a stored cron payload. */
+export function decodeCronPayload(message: string): {
+  isCronPayload: boolean;
+  payload?: CronReminderPayload;
+  error?: string;
+} {
+  const trimmedMessage = message.trim();
+
+  if (!trimmedMessage.startsWith(CRON_PREFIX)) {
+    return { isCronPayload: false };
+  }
+
+  const base64Content = trimmedMessage.slice(CRON_PREFIX.length);
+
+  if (!base64Content) {
+    return { isCronPayload: true, error: "Cron payload body is empty" };
+  }
+
+  try {
+    const jsonString = Buffer.from(base64Content, "base64").toString("utf-8");
+    const payload = JSON.parse(jsonString) as CronReminderPayload;
+
+    if (payload.type !== "cron_reminder") {
+      return {
+        isCronPayload: true,
+        error: `Expected type cron_reminder but got ${String(payload.type)}`,
+      };
+    }
+
+    if (!payload.content || !payload.targetType || !payload.targetAddress) {
+      return { isCronPayload: true, error: "Cron payload is missing required fields" };
+    }
+
+    return { isCronPayload: true, payload };
+  } catch (e) {
+    return { isCronPayload: true, error: `Failed to decode cron payload: ${formatErr(e)}` };
+  }
+}
+
+/** Type guard for cron reminder payloads. */
+export function isCronReminderPayload(payload: QQBotPayload): payload is CronReminderPayload {
+  return payload.type === "cron_reminder";
+}
+
+/** Type guard for media payloads. */
+export function isMediaPayload(payload: QQBotPayload): payload is MediaPayload {
+  return payload.type === "media";
+}

package/src/engine/utils/platform-storage-laziness.test.ts

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const createdHomes: string[] = [];
+
+async function useMockHome(homeDir: string): Promise<void> {
+  vi.resetModules();
+  vi.doMock("node:os", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("node:os")>();
+    return {
+      ...actual,
+      default: { ...actual, homedir: () => homeDir },
+      homedir: () => homeDir,
+    };
+  });
+}
+
+function makeHome(): string {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "qqbot-home-"));
+  createdHomes.push(homeDir);
+  return homeDir;
+}
+
+describe("qqbot storage laziness", () => {
+  afterEach(() => {
+    vi.doUnmock("node:os");
+    vi.resetModules();
+    for (const home of createdHomes.splice(0)) {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  it("does not create ~/.openclaw/qqbot from module imports or read-only probes", async () => {
+    const homeDir = makeHome();
+    await useMockHome(homeDir);
+
+    const qqbotRoot = path.join(homeDir, ".openclaw", "qqbot");
+
+    const sessionStore = await import("../session/session-store.js");
+    await import("../session/known-users.js");
+    await import("../ref/store.js");
+    const { loadCredentialBackup } = await import("../config/credential-backup.js");
+
+    expect(loadCredentialBackup("default")).toBeNull();
+    expect(sessionStore.getAllSessions()).toEqual([]);
+    expect(sessionStore.cleanupExpiredSessions()).toBe(0);
+    expect(fs.existsSync(qqbotRoot)).toBe(false);
+  });
+
+  it("creates storage when qqbot persists runtime state", async () => {
+    const homeDir = makeHome();
+    await useMockHome(homeDir);
+
+    const qqbotRoot = path.join(homeDir, ".openclaw", "qqbot");
+    const { saveCredentialBackup } = await import("../config/credential-backup.js");
+
+    saveCredentialBackup("default", "123456", "secret");
+
+    expect(fs.existsSync(path.join(qqbotRoot, "data", "credential-backup-default.json"))).toBe(
+      true,
+    );
+  });
+});

package/src/engine/utils/platform.test.ts

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  getHomeDir,
+  resolveQQBotLocalMediaPath,
+  resolveQQBotPayloadLocalFilePath,
+} from "./platform.js";
+
+describe("qqbot local media path remapping", () => {
+  const createdPaths: string[] = [];
+
+  function createOpenClawTestRoot() {
+    const actualHome = getHomeDir();
+    const openclawDir = path.join(actualHome, ".openclaw");
+    fs.mkdirSync(openclawDir, { recursive: true });
+    const testRoot = fs.mkdtempSync(path.join(openclawDir, "qqbot-platform-test-"));
+    createdPaths.push(testRoot);
+    return { actualHome, testRootName: path.basename(testRoot) };
+  }
+
+  function createQqbotMediaFile(fileName: string) {
+    const { actualHome, testRootName } = createOpenClawTestRoot();
+    const mediaFile = path.join(
+      actualHome,
+      ".openclaw",
+      "media",
+      "qqbot",
+      "downloads",
+      testRootName,
+      fileName,
+    );
+    fs.mkdirSync(path.dirname(mediaFile), { recursive: true });
+    fs.writeFileSync(mediaFile, "image", "utf8");
+    createdPaths.push(path.dirname(mediaFile));
+    return { actualHome, testRootName, mediaFile };
+  }
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    for (const target of createdPaths.splice(0)) {
+      fs.rmSync(target, { recursive: true, force: true });
+    }
+  });
+
+  it("remaps missing workspace media paths to the real media directory", () => {
+    const { actualHome, testRootName, mediaFile } = createQqbotMediaFile("example.png");
+
+    const missingWorkspacePath = path.join(
+      actualHome,
+      ".openclaw",
+      "workspace",
+      "qqbot",
+      "downloads",
+      testRootName,
+      "example.png",
+    );
+
+    expect(resolveQQBotLocalMediaPath(missingWorkspacePath)).toBe(mediaFile);
+  });
+
+  it("leaves existing media paths unchanged", () => {
+    const { mediaFile } = createQqbotMediaFile("existing.png");
+
+    expect(resolveQQBotLocalMediaPath(mediaFile)).toBe(mediaFile);
+  });
+
+  it("blocks structured payload files outside QQ Bot storage", () => {
+    const outsideRoot = fs.mkdtempSync(path.join(os.tmpdir(), "qqbot-platform-outside-"));
+    createdPaths.push(outsideRoot);
+
+    const outsideFile = path.join(outsideRoot, "secret.txt");
+    fs.writeFileSync(outsideFile, "secret", "utf8");
+
+    expect(resolveQQBotPayloadLocalFilePath(outsideFile)).toBeNull();
+  });
+
+  it("blocks structured payload paths that escape QQ Bot media via '..'", () => {
+    const escapedPath = path.join(
+      getHomeDir(),
+      ".openclaw",
+      "media",
+      "qqbot",
+      "..",
+      "..",
+      "qqbot-escape.txt",
+    );
+
+    expect(resolveQQBotPayloadLocalFilePath(escapedPath)).toBeNull();
+  });
+
+  it("allows structured payload files inside the QQ Bot media directory", () => {
+    const { mediaFile } = createQqbotMediaFile("allowed.png");
+
+    expect(resolveQQBotPayloadLocalFilePath(mediaFile)).toBe(fs.realpathSync(mediaFile));
+  });
+
+  it("allows structured payload files inside sibling OpenClaw media subdirectories", () => {
+    // Core helpers such as `saveMediaBuffer(..., "outbound", ...)` place framework
+    // attachments under sibling directories of `media/qqbot/`. The plugin must
+    // trust the shared `~/.openclaw/media` root so auto-routed sends can access
+    // those files without the path-outside-storage guard firing.
+    const actualHome = getHomeDir();
+    const outboundDir = path.join(actualHome, ".openclaw", "media", "outbound");
+    fs.mkdirSync(outboundDir, { recursive: true });
+    const outboundFile = fs.mkdtempSync(path.join(outboundDir, "qqbot-outbound-"));
+    const mediaFile = path.join(outboundFile, "tts.mp3");
+    fs.writeFileSync(mediaFile, "audio", "utf8");
+    createdPaths.push(outboundFile);
+
+    expect(resolveQQBotPayloadLocalFilePath(mediaFile)).toBe(fs.realpathSync(mediaFile));
+  });
+
+  it("blocks structured payload files inside the QQ Bot data directory", () => {
+    const { actualHome, testRootName } = createOpenClawTestRoot();
+
+    const dataFile = path.join(
+      actualHome,
+      ".openclaw",
+      "qqbot",
+      "sessions",
+      testRootName,
+      "session.json",
+    );
+    fs.mkdirSync(path.dirname(dataFile), { recursive: true });
+    fs.writeFileSync(dataFile, "{}", "utf8");
+    createdPaths.push(path.dirname(dataFile));
+
+    expect(resolveQQBotPayloadLocalFilePath(dataFile)).toBeNull();
+  });
+
+  it("allows legacy workspace paths when they remap into QQ Bot media storage", () => {
+    const { actualHome, testRootName, mediaFile } = createQqbotMediaFile("legacy.png");
+
+    const missingWorkspacePath = path.join(
+      actualHome,
+      ".openclaw",
+      "workspace",
+      "qqbot",
+      "downloads",
+      testRootName,
+      "legacy.png",
+    );
+
+    expect(resolveQQBotPayloadLocalFilePath(missingWorkspacePath)).toBe(fs.realpathSync(mediaFile));
+  });
+});

package/src/engine/utils/platform.ts

@@ -0,0 +1,343 @@
+/**
+ * Cross-platform path and detection helpers for core/ modules.
+ *
+ * Provides home/data/media directory helpers, platform detection,
+ * ffmpeg/silk-wasm availability checks — all without importing
+ * `openclaw/plugin-sdk`. The temp-directory fallback is delegated
+ * to the PlatformAdapter.
+ */
+
+import { execFile } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getPlatformAdapter } from "../adapter/index.js";
+import { formatErrorMessage } from "./format.js";
+import { debugLog, debugWarn } from "./log.js";
+
+/**
+ * Resolve the current user's home directory safely across platforms.
+ *
+ * Priority:
+ * 1. `os.homedir()`
+ * 2. `$HOME` or `%USERPROFILE%`
+ * 3. PlatformAdapter.getTempDir() as a last resort
+ */
+export function getHomeDir(): string {
+  try {
+    const home = os.homedir();
+    if (home && fs.existsSync(home)) {
+      return home;
+    }
+  } catch {
+    /* fallback */
+  }
+
+  const envHome = process.env.HOME || process.env.USERPROFILE;
+  if (envHome && fs.existsSync(envHome)) {
+    return envHome;
+  }
+
+  return getPlatformAdapter().getTempDir();
+}
+
+/** Return a path under `~/.openclaw/qqbot` without creating it. */
+export function getQQBotDataPath(...subPaths: string[]): string {
+  return path.join(getHomeDir(), ".openclaw", "qqbot", ...subPaths);
+}
+
+/** Return a path under `~/.openclaw/qqbot`, creating it on demand. */
+export function getQQBotDataDir(...subPaths: string[]): string {
+  const dir = getQQBotDataPath(...subPaths);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Return a path under `~/.openclaw/media/qqbot` without creating it.
+ *
+ * Unlike `getQQBotDataPath`, this lives under OpenClaw's core media allowlist so
+ * downloaded images and audio can be accessed by framework media tooling.
+ */
+export function getQQBotMediaPath(...subPaths: string[]): string {
+  return path.join(getHomeDir(), ".openclaw", "media", "qqbot", ...subPaths);
+}
+
+/** Return a path under `~/.openclaw/media/qqbot`, creating it on demand. */
+export function getQQBotMediaDir(...subPaths: string[]): string {
+  const dir = getQQBotMediaPath(...subPaths);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Return `~/.openclaw/media`, OpenClaw's shared media root.
+ *
+ * This mirrors the directory that core's `buildMediaLocalRoots` exposes as an
+ * allowlisted location (see `openclaw/src/media/local-roots.ts`). Using it as a
+ * QQ Bot payload root lets the plugin trust framework-produced files that live
+ * in sibling subdirectories such as `outbound/` (written by
+ * `saveMediaBuffer(..., "outbound", ...)`) or `inbound/`, while still keeping
+ * the check anchored to a single, well-known directory.
+ */
+function getOpenClawMediaDir(): string {
+  return path.join(getHomeDir(), ".openclaw", "media");
+}
+
+// ---- Basic platform information ----
+
+type PlatformType = "darwin" | "linux" | "win32" | "other";
+
+export function getPlatform(): PlatformType {
+  const p = process.platform;
+  if (p === "darwin" || p === "linux" || p === "win32") {
+    return p;
+  }
+  return "other";
+}
+
+export function isWindows(): boolean {
+  return process.platform === "win32";
+}
+
+/** Return the preferred temporary directory. */
+export function getTempDir(): string {
+  return getPlatformAdapter().getTempDir();
+}
+
+// ---- ffmpeg detection ----
+
+let _ffmpegPath: string | null | undefined;
+let _ffmpegCheckPromise: Promise<string | null> | null = null;
+
+/** Detect ffmpeg and return an executable path when available. */
+export function detectFfmpeg(): Promise<string | null> {
+  if (_ffmpegPath !== undefined) {
+    return Promise.resolve(_ffmpegPath);
+  }
+  if (_ffmpegCheckPromise) {
+    return _ffmpegCheckPromise;
+  }
+
+  _ffmpegCheckPromise = (async () => {
+    const envPath = process.env.FFMPEG_PATH;
+    if (envPath) {
+      const ok = await testExecutable(envPath, ["-version"]);
+      if (ok) {
+        _ffmpegPath = envPath;
+        debugLog(`[platform] ffmpeg found via FFMPEG_PATH: ${envPath}`);
+        return _ffmpegPath;
+      }
+      debugWarn(`[platform] FFMPEG_PATH set but not working: ${envPath}`);
+    }
+
+    const cmd = isWindows() ? "ffmpeg.exe" : "ffmpeg";
+    const ok = await testExecutable(cmd, ["-version"]);
+    if (ok) {
+      _ffmpegPath = cmd;
+      debugLog(`[platform] ffmpeg detected in PATH`);
+      return _ffmpegPath;
+    }
+
+    const commonPaths = isWindows()
+      ? [
+          "C:\\ffmpeg\\bin\\ffmpeg.exe",
+          path.join(process.env.LOCALAPPDATA || "", "Programs", "ffmpeg", "bin", "ffmpeg.exe"),
+          path.join(process.env.ProgramFiles || "", "ffmpeg", "bin", "ffmpeg.exe"),
+        ]
+      : [
+          "/usr/local/bin/ffmpeg",
+          "/opt/homebrew/bin/ffmpeg",
+          "/usr/bin/ffmpeg",
+          "/snap/bin/ffmpeg",
+        ];
+
+    for (const p of commonPaths) {
+      if (p && fs.existsSync(p)) {
+        const works = await testExecutable(p, ["-version"]);
+        if (works) {
+          _ffmpegPath = p;
+          debugLog(`[platform] ffmpeg found at: ${p}`);
+          return _ffmpegPath;
+        }
+      }
+    }
+
+    _ffmpegPath = null;
+    return null;
+  })().finally(() => {
+    _ffmpegCheckPromise = null;
+  });
+
+  return _ffmpegCheckPromise;
+}
+
+/** Return true when an executable responds successfully to the given args. */
+function testExecutable(cmd: string, args: string[]): Promise<boolean> {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: 5000 }, (err) => {
+      resolve(!err);
+    });
+  });
+}
+
+// ---- silk-wasm detection ----
+
+let _silkWasmAvailable: boolean | null = null;
+
+/** Check whether silk-wasm can run in the current environment. */
+export async function checkSilkWasmAvailable(): Promise<boolean> {
+  if (_silkWasmAvailable !== null) {
+    return _silkWasmAvailable;
+  }
+  try {
+    const { isSilk } = await import("silk-wasm");
+    isSilk(new Uint8Array(0));
+    _silkWasmAvailable = true;
+    debugLog("[platform] silk-wasm: available");
+  } catch (err) {
+    _silkWasmAvailable = false;
+    debugWarn(`[platform] silk-wasm: NOT available (${formatErrorMessage(err)})`);
+  }
+  return _silkWasmAvailable;
+}
+
+// ---- Tilde expansion and path normalization ----
+
+/** Expand `~` to the current user's home directory. */
+function expandTilde(p: string): string {
+  if (!p) {
+    return p;
+  }
+  if (p === "~") {
+    return getHomeDir();
+  }
+  if (p.startsWith("~/") || p.startsWith("~\\")) {
+    return path.join(getHomeDir(), p.slice(2));
+  }
+  return p;
+}
+
+/** Normalize a user-provided path by trimming, stripping `file://`, and expanding `~`. */
+export function normalizePath(p: string): string {
+  let result = p.trim();
+  if (result.startsWith("file://")) {
+    result = result.slice("file://".length);
+    try {
+      result = decodeURIComponent(result);
+    } catch {
+      // Keep the raw string if decoding fails.
+    }
+  }
+  return expandTilde(result);
+}
+
+// ---- Local path detection ----
+
+/** Return true when the string looks like a local filesystem path rather than a URL. */
+export function isLocalPath(p: string): boolean {
+  if (!p) {
+    return false;
+  }
+  if (p.startsWith("file://")) {
+    return true;
+  }
+  if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) {
+    return true;
+  }
+  if (p.startsWith("/")) {
+    return true;
+  }
+  if (/^[a-zA-Z]:[\\/]/.test(p)) {
+    return true;
+  }
+  if (p.startsWith("\\\\")) {
+    return true;
+  }
+  if (p.startsWith("./") || p.startsWith("../")) {
+    return true;
+  }
+  if (p.startsWith(".\\") || p.startsWith("..\\")) {
+    return true;
+  }
+  return false;
+}
+
+// ---- QQBot media path resolution ----
+
+function isPathWithinRoot(candidate: string, root: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+/** Remap legacy or hallucinated QQ Bot local media paths to real files when possible. */
+export function resolveQQBotLocalMediaPath(p: string): string {
+  const normalized = normalizePath(p);
+  if (!isLocalPath(normalized) || fs.existsSync(normalized)) {
+    return normalized;
+  }
+
+  const homeDir = getHomeDir();
+  const mediaRoot = getQQBotMediaPath();
+  const dataRoot = getQQBotDataPath();
+  const workspaceRoot = path.join(homeDir, ".openclaw", "workspace", "qqbot");
+  const candidateRoots = [
+    { from: workspaceRoot, to: mediaRoot },
+    { from: dataRoot, to: mediaRoot },
+    { from: mediaRoot, to: dataRoot },
+  ];
+
+  for (const { from, to } of candidateRoots) {
+    if (!isPathWithinRoot(normalized, from)) {
+      continue;
+    }
+    const relative = path.relative(from, normalized);
+    const candidate = path.join(to, relative);
+    if (fs.existsSync(candidate)) {
+      debugWarn(`[platform] Remapped missing QQBot media path ${normalized} -> ${candidate}`);
+      return candidate;
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Resolve a structured-payload local file path and enforce that it stays within
+ * QQ Bot-owned storage roots.
+ */
+export function resolveQQBotPayloadLocalFilePath(p: string): string | null {
+  const candidate = resolveQQBotLocalMediaPath(p);
+  if (!candidate.trim()) {
+    return null;
+  }
+
+  const resolvedCandidate = path.resolve(candidate);
+  if (!fs.existsSync(resolvedCandidate)) {
+    return null;
+  }
+
+  const canonicalCandidate = fs.realpathSync(resolvedCandidate);
+  // Trust both the QQ Bot-owned subdirectory and OpenClaw's shared `~/.openclaw/media`
+  // root. Core helpers like `saveMediaBuffer(..., "outbound", ...)` place framework
+  // attachments under sibling directories (e.g. `media/outbound/`) that are already
+  // part of the core media allowlist; we mirror that so auto-routed sends work
+  // without leaving the plugin's trust boundary.
+  const allowedRoots = [getOpenClawMediaDir(), getQQBotMediaPath()];
+
+  for (const root of allowedRoots) {
+    const resolvedRoot = path.resolve(root);
+    const canonicalRoot = fs.existsSync(resolvedRoot)
+      ? fs.realpathSync(resolvedRoot)
+      : resolvedRoot;
+    if (isPathWithinRoot(canonicalCandidate, canonicalRoot)) {
+      return canonicalCandidate;
+    }
+  }
+
+  return null;
+}