@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

package/src/engine/utils/payload.ts

@@ -1,145 +0,0 @@
-/**
- * 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

@@ -1,63 +0,0 @@
-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");
-
-    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(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

@@ -1,148 +0,0 @@
-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

@@ -1,343 +0,0 @@
-/**
- * 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;
-}