@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

package/src/engine/utils/request-context.ts

@@ -1,60 +0,0 @@
-/**
- * Request-level context using AsyncLocalStorage.
- *
- * Provides ambient context (accountId, target openid, chat type, etc.)
- * throughout the request lifecycle without explicit parameter threading.
- *
- * Gateway establishes the scope around each inbound message via
- * `runWithRequestContext()`; any async code within that scope (including
- * AI agent calls and tool `execute` callbacks) can retrieve the current
- * request via `getRequestContext()` without racing with concurrent
- * inbound messages.
- *
- * This is a pure Node.js module with zero framework dependencies,
- * making it trivially portable between the built-in and standalone
- * versions of QQBot.
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-
-/** Context values available during one inbound message handling cycle. */
-interface RequestContext {
-  /** The account ID handling this request. */
-  accountId: string;
-  /**
-   * Fully qualified delivery target, e.g. `qqbot:c2c:<openid>` or
-   * `qqbot:group:<openid>`. This is what downstream code (e.g. the
-   * `qqbot_remind` tool building a cron job) uses verbatim.
-   */
-  target?: string;
-  /** The target openid (C2C) or group openid (group). */
-  targetId?: string;
-  /** Chat type of the originating event. */
-  chatType?: "c2c" | "group" | "guild" | "dm" | "channel";
-}
-
-const store = new AsyncLocalStorage<RequestContext>();
-
-/**
- * Execute an async function with request-scoped context.
- *
- * All code running within `fn` (including nested async calls) can
- * retrieve the context via `getRequestContext()`.
- *
- * @param ctx - The context to attach to this request.
- * @param fn - The async function to run within the context.
- * @returns The return value of `fn`.
- */
-export function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T {
-  return store.run(ctx, fn);
-}
-
-/**
- * Retrieve the current request context.
- *
- * Returns `undefined` when called outside of a `runWithRequestContext`
- * scope.
- */
-export function getRequestContext(): RequestContext | undefined {
-  return store.getStore();
-}

package/src/engine/utils/string-normalize.ts

@@ -1,91 +0,0 @@
-/**
- * String normalization and record-coercion helpers.
- *
- * These are self-contained re-implementations of the functions that
- * the plugin previously imported from `openclaw/plugin-sdk/text-runtime`
- * and `openclaw/plugin-sdk/text-runtime` (via record-coerce / string-coerce).
- *
- * core/ modules use these instead of importing plugin-sdk, keeping the
- * shared layer portable between the built-in and standalone versions.
- */
-
-// ---- String coercion ----
-
-/** Return the trimmed string or `null` when the value is not a non-empty string. */
-function normalizeNullableString(value: unknown): string | null {
-  if (typeof value !== "string") {
-    return null;
-  }
-  const trimmed = value.trim();
-  return trimmed ? trimmed : null;
-}
-
-/** Return the trimmed string or `undefined` when the value is not a non-empty string. */
-export function normalizeOptionalString(value: unknown): string | undefined {
-  return normalizeNullableString(value) ?? undefined;
-}
-
-/**
- * Stringify then normalize.  Accepts `string | number | boolean | bigint`.
- * Returns `undefined` for objects, arrays, null, and undefined.
- */
-export function normalizeStringifiedOptionalString(value: unknown): string | undefined {
-  if (typeof value === "string") {
-    return normalizeOptionalString(value);
-  }
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    return normalizeOptionalString(String(value));
-  }
-  return undefined;
-}
-
-/** Return the trimmed lowercase string or `undefined`. */
-export function normalizeOptionalLowercaseString(value: unknown): string | undefined {
-  return normalizeOptionalString(value)?.toLowerCase();
-}
-
-/** Return the trimmed lowercase string or `""`. */
-export function normalizeLowercaseStringOrEmpty(value: unknown): string {
-  return normalizeOptionalLowercaseString(value) ?? "";
-}
-
-// ---- Record coercion ----
-
-/** Coerce a value into a `Record<string, unknown>` or `undefined`. */
-export function asOptionalObjectRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
-}
-
-/** Read a string field from a record. */
-export function readStringField(
-  record: Record<string, unknown> | null | undefined,
-  key: string,
-): string | undefined {
-  const v = record?.[key];
-  return typeof v === "string" ? v : undefined;
-}
-
-// ---- Filename normalization ----
-
-/**
- * Normalize filenames into a UTF-8 form that the QQ Bot API accepts reliably.
- *
- * Decodes percent-escaped names, converts Unicode to NFC, and strips
- * ASCII control characters.
- */
-export function sanitizeFileName(name: string): string {
-  if (!name) {
-    return name;
-  }
-  let result = name.trim();
-  if (result.includes("%")) {
-    try {
-      result = decodeURIComponent(result);
-    } catch {
-      // Keep the raw value if it is not valid percent-encoding.
-    }
-  }
-  result = result.normalize("NFC");
-  result = result.replace(/\p{Cc}/gu, "");
-  return result;
-}

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

@@ -1,104 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { resolveSTTConfig, transcribeAudio } from "./stt.js";
-
-describe("engine/utils/stt", () => {
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
-
-  it("resolves plugin STT config and falls back to provider credentials", () => {
-    const cfg = {
-      channels: {
-        qqbot: {
-          stt: {
-            provider: "openai",
-            baseUrl: "https://api.example.test/v1///",
-            model: "whisper-large",
-          },
-        },
-      },
-      models: {
-        providers: {
-          openai: {
-            apiKey: "provider-key",
-          },
-        },
-      },
-    };
-
-    expect(resolveSTTConfig(cfg)).toEqual({
-      baseUrl: "https://api.example.test/v1",
-      apiKey: "provider-key",
-      model: "whisper-large",
-    });
-  });
-
-  it("falls back to framework audio model config when plugin STT is disabled", () => {
-    const cfg = {
-      channels: { qqbot: { stt: { enabled: false, apiKey: "ignored" } } },
-      tools: {
-        media: {
-          audio: {
-            models: [{ provider: "local", baseUrl: "https://stt.example.test/", model: "sense" }],
-          },
-        },
-      },
-      models: {
-        providers: {
-          local: { apiKey: "local-key" },
-        },
-      },
-    };
-
-    expect(resolveSTTConfig(cfg)).toEqual({
-      baseUrl: "https://stt.example.test",
-      apiKey: "local-key",
-      model: "sense",
-    });
-  });
-
-  it("returns null when no usable STT credentials are configured", () => {
-    expect(resolveSTTConfig({ channels: { qqbot: { stt: { baseUrl: "https://x.test" } } } })).toBe(
-      null,
-    );
-    expect(resolveSTTConfig({})).toBe(null);
-  });
-
-  it("posts audio to OpenAI-compatible transcription endpoint", async () => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-qqbot-stt-"));
-    const audioPath = path.join(tmpDir, "voice.wav");
-    fs.writeFileSync(audioPath, Buffer.from([1, 2, 3, 4]));
-
-    const fetchMock = vi.fn(async () =>
-      Response.json({
-        text: "hello from audio",
-      }),
-    );
-    vi.stubGlobal("fetch", fetchMock);
-
-    const transcript = await transcribeAudio(audioPath, {
-      channels: {
-        qqbot: {
-          stt: {
-            baseUrl: "https://api.example.test/v1/",
-            apiKey: "secret",
-            model: "whisper-1",
-          },
-        },
-      },
-    });
-
-    expect(transcript).toBe("hello from audio");
-    expect(fetchMock).toHaveBeenCalledWith(
-      "https://api.example.test/v1/audio/transcriptions",
-      expect.objectContaining({
-        method: "POST",
-        headers: { Authorization: "Bearer secret" },
-        body: expect.any(FormData),
-      }),
-    );
-  });
-});

package/src/engine/utils/stt.ts

@@ -1,100 +0,0 @@
-/**
- * OpenAI-compatible STT (Speech-to-Text) configuration and transcription.
- *
- * Migrated from `src/stt.ts` — uses core/utils/string-normalize instead
- * of openclaw/plugin-sdk/text-runtime.
- */
-
-import * as fs from "node:fs";
-import path from "node:path";
-import {
-  normalizeOptionalString,
-  asOptionalObjectRecord as asRecord,
-  readStringField as readString,
-  sanitizeFileName,
-} from "./string-normalize.js";
-
-interface STTConfig {
-  baseUrl: string;
-  apiKey: string;
-  model: string;
-}
-
-/** Resolve the STT configuration from the nested config object. */
-export function resolveSTTConfig(cfg: Record<string, unknown>): STTConfig | null {
-  const channels = asRecord(cfg.channels);
-  const qqbot = asRecord(channels?.qqbot);
-  const channelStt = asRecord(qqbot?.stt);
-  const models = asRecord(cfg.models);
-  const providers = asRecord(models?.providers);
-
-  // Prefer plugin-specific STT config.
-  if (channelStt && channelStt.enabled !== false) {
-    const providerId = readString(channelStt, "provider") ?? "openai";
-    const providerCfg = asRecord(providers?.[providerId]);
-    const baseUrl = readString(channelStt, "baseUrl") ?? readString(providerCfg, "baseUrl");
-    const apiKey = readString(channelStt, "apiKey") ?? readString(providerCfg, "apiKey");
-    const model = readString(channelStt, "model") ?? "whisper-1";
-    if (baseUrl && apiKey) {
-      return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey, model };
-    }
-  }
-
-  // Fall back to framework-level audio model config.
-  const tools = asRecord(cfg.tools);
-  const media = asRecord(tools?.media);
-  const audio = asRecord(media?.audio);
-  const audioModels = audio?.models;
-  const audioModelEntry = Array.isArray(audioModels) ? asRecord(audioModels[0]) : undefined;
-  if (audioModelEntry) {
-    const providerId = readString(audioModelEntry, "provider") ?? "openai";
-    const providerCfg = asRecord(providers?.[providerId]);
-    const baseUrl = readString(audioModelEntry, "baseUrl") ?? readString(providerCfg, "baseUrl");
-    const apiKey = readString(audioModelEntry, "apiKey") ?? readString(providerCfg, "apiKey");
-    const model = readString(audioModelEntry, "model") ?? "whisper-1";
-    if (baseUrl && apiKey) {
-      return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey, model };
-    }
-  }
-
-  return null;
-}
-
-/** Send audio to an OpenAI-compatible STT endpoint and return the transcript. */
-export async function transcribeAudio(
-  audioPath: string,
-  cfg: Record<string, unknown>,
-): Promise<string | null> {
-  const sttCfg = resolveSTTConfig(cfg);
-  if (!sttCfg) {
-    return null;
-  }
-
-  const fileBuffer = fs.readFileSync(audioPath);
-  const fileName = sanitizeFileName(path.basename(audioPath));
-  const mime = fileName.endsWith(".wav")
-    ? "audio/wav"
-    : fileName.endsWith(".mp3")
-      ? "audio/mpeg"
-      : fileName.endsWith(".ogg")
-        ? "audio/ogg"
-        : "application/octet-stream";
-
-  const form = new FormData();
-  form.append("file", new Blob([fileBuffer], { type: mime }), fileName);
-  form.append("model", sttCfg.model);
-
-  const resp = await fetch(`${sttCfg.baseUrl}/audio/transcriptions`, {
-    method: "POST",
-    headers: { Authorization: `Bearer ${sttCfg.apiKey}` },
-    body: form,
-  });
-
-  if (!resp.ok) {
-    const detail = await resp.text().catch(() => "");
-    throw new Error(`STT failed (HTTP ${resp.status}): ${detail.slice(0, 300)}`);
-  }
-
-  const result = (await resp.json()) as { text?: string };
-  return normalizeOptionalString(result.text) ?? null;
-}

package/src/engine/utils/text-parsing.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { parseFaceTags } from "./text-parsing.js";
-
-describe("parseFaceTags", () => {
-  it("returns empty string when input is undefined", () => {
-    expect(parseFaceTags(undefined)).toBe("");
-  });
-
-  it("returns empty string when input is null", () => {
-    expect(parseFaceTags(null)).toBe("");
-  });
-
-  it("returns empty string when input is empty string", () => {
-    expect(parseFaceTags("")).toBe("");
-  });
-
-  it("skips oversized base64 ext payloads before decoding", () => {
-    const oversizedBase64 = "A".repeat(100_000);
-    const tag = `<faceType=1,faceId="1",ext="${oversizedBase64}">`;
-    const bufferFromSpy = vi.spyOn(Buffer, "from");
-
-    try {
-      expect(parseFaceTags(tag)).toBe("[Emoji: unknown emoji]");
-      expect(bufferFromSpy).not.toHaveBeenCalledWith(oversizedBase64, "base64");
-    } finally {
-      bufferFromSpy.mockRestore();
-    }
-  });
-});

package/src/engine/utils/text-parsing.ts

@@ -1,155 +0,0 @@
-/**
- * Text parsing utilities — zero external dependency.
- *
- * Contains pure functions for message text processing.
- */
-
-import type { RefAttachmentSummary } from "../ref/types.js";
-
-// ============ Internal markers ============
-
-const INTERNAL_MARKER_RE = /\[internal:?\s*[^\]]*\]|\[debug:?\s*[^\]]*\]|\[system:?\s*[^\]]*\]/gi;
-
-/** Remove internal markers like `[internal:...]`, `[debug:...]`, `[system:...]`. */
-export function filterInternalMarkers(text: string | undefined | null): string {
-  if (!text) {
-    return "";
-  }
-  return text.replace(INTERNAL_MARKER_RE, "").trim();
-}
-
-// ============ Ref indices ============
-
-/** QQ 引用（回复）消息类型常量。 */
-export const MSG_TYPE_QUOTE = 103;
-
-/**
- * Parse message_scene.ext to extract refMsgIdx and msgIdx.
- *
- * Supports both ext prefix formats:
- * - `ref_msg_idx=` / `msg_idx=` (platform native format)
- * - `refMsgIdx:` / `msgIdx:` (legacy internal format)
- *
- * When `messageType` equals `MSG_TYPE_QUOTE` (103) and `msgElements` is
- * provided, `msgElements[0].msg_idx` takes precedence over the ext-parsed
- * `refMsgIdx` value — the element-level index is more authoritative for
- * quote messages.
- */
-export function parseRefIndices(
-  ext?: string[],
-  messageType?: number,
-  msgElements?: Array<{ msg_idx?: string }>,
-): { refMsgIdx?: string; msgIdx?: string } {
-  let refMsgIdx: string | undefined;
-  let msgIdx: string | undefined;
-
-  if (ext && ext.length > 0) {
-    for (const item of ext) {
-      if (typeof item !== "string") {
-        continue;
-      }
-      // Platform native format: ref_msg_idx= / msg_idx=
-      if (item.startsWith("ref_msg_idx=")) {
-        refMsgIdx = item.slice("ref_msg_idx=".length).trim();
-      } else if (item.startsWith("msg_idx=")) {
-        msgIdx = item.slice("msg_idx=".length).trim();
-      }
-      // Legacy internal format: refMsgIdx: / msgIdx:
-      else if (item.startsWith("refMsgIdx:")) {
-        refMsgIdx = item.slice("refMsgIdx:".length).trim();
-      } else if (item.startsWith("msgIdx:")) {
-        msgIdx = item.slice("msgIdx:".length).trim();
-      }
-    }
-  }
-
-  // For quote messages, msg_elements[0].msg_idx is more authoritative.
-  if (messageType === MSG_TYPE_QUOTE) {
-    const refElement = msgElements?.[0];
-    if (refElement?.msg_idx) {
-      refMsgIdx = refElement.msg_idx;
-    }
-  }
-
-  return { refMsgIdx, msgIdx };
-}
-
-// ============ Face tags ============
-
-const MAX_FACE_EXT_BYTES = 64 * 1024;
-
-/** Estimate Base64 decoded byte size (replaces plugin-sdk estimateBase64DecodedBytes). */
-function estimateBase64Size(base64: string): number {
-  const len = base64.length;
-  const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
-  return Math.ceil((len * 3) / 4) - padding;
-}
-
-/** Replace QQ face tags with readable text labels. */
-export function parseFaceTags(text: string | undefined | null): string {
-  if (!text) {
-    return "";
-  }
-
-  return text.replace(/<faceType=\d+,faceId="[^"]*",ext="([^"]*)">/g, (_match, ext: string) => {
-    try {
-      if (estimateBase64Size(ext) > MAX_FACE_EXT_BYTES) {
-        return "[Emoji: unknown emoji]";
-      }
-      const decoded = Buffer.from(ext, "base64").toString("utf-8");
-      const parsed = JSON.parse(decoded);
-      const faceName = parsed.text || "unknown emoji";
-      return `[Emoji: ${faceName}]`;
-    } catch {
-      return _match;
-    }
-  });
-}
-
-// ============ Attachment summaries ============
-
-/** Lowercase a string safely (replaces plugin-sdk normalizeLowercaseStringOrEmpty). */
-function lc(s: string | undefined | null): string {
-  return (s ?? "").toLowerCase();
-}
-
-/** Build attachment summaries for ref-index caching. */
-export function buildAttachmentSummaries(
-  attachments?: Array<{
-    content_type: string;
-    url: string;
-    filename?: string;
-    voice_wav_url?: string;
-  }>,
-  localPaths?: Array<string | null>,
-): RefAttachmentSummary[] | undefined {
-  if (!attachments || attachments.length === 0) {
-    return undefined;
-  }
-
-  return attachments.map((att, idx) => {
-    const ct = lc(att.content_type);
-    let type: RefAttachmentSummary["type"] = "unknown";
-    if (ct.startsWith("image/")) {
-      type = "image";
-    } else if (
-      ct === "voice" ||
-      ct.startsWith("audio/") ||
-      ct.includes("silk") ||
-      ct.includes("amr")
-    ) {
-      type = "voice";
-    } else if (ct.startsWith("video/")) {
-      type = "video";
-    } else if (ct.startsWith("application/") || ct.startsWith("text/")) {
-      type = "file";
-    }
-
-    return {
-      type,
-      filename: att.filename,
-      contentType: att.content_type,
-      localPath: localPaths?.[idx] ?? undefined,
-    };
-  });
-}

package/src/engine/utils/upload-cache.ts

@@ -1,96 +0,0 @@
-/**
- * Cache `file_info` values returned by the QQ Bot API so identical uploads can be reused
- * before the server-side TTL expires.
- */
-
-import * as crypto from "node:crypto";
-import type { ChatScope } from "../types.js";
-import { debugLog } from "./log.js";
-
-interface CacheEntry {
-  fileInfo: string;
-  fileUuid: string;
-  expiresAt: number;
-}
-
-const cache = new Map<string, CacheEntry>();
-const MAX_CACHE_SIZE = 500;
-
-/** Compute an MD5 hash used as part of the cache key. */
-export function computeFileHash(data: string | Buffer): string {
-  const content = typeof data === "string" ? data : data;
-  return crypto.createHash("md5").update(content).digest("hex");
-}
-
-/** Build the in-memory cache key. */
-function buildCacheKey(
-  contentHash: string,
-  scope: string,
-  targetId: string,
-  fileType: number,
-): string {
-  return `${contentHash}:${scope}:${targetId}:${fileType}`;
-}
-
-/** Look up a cached `file_info` value. */
-export function getCachedFileInfo(
-  contentHash: string,
-  scope: ChatScope,
-  targetId: string,
-  fileType: number,
-): string | null {
-  const key = buildCacheKey(contentHash, scope, targetId, fileType);
-  const entry = cache.get(key);
-
-  if (!entry) {
-    return null;
-  }
-
-  if (Date.now() >= entry.expiresAt) {
-    cache.delete(key);
-    return null;
-  }
-
-  debugLog(`[upload-cache] Cache HIT: key=${key.slice(0, 40)}..., fileUuid=${entry.fileUuid}`);
-  return entry.fileInfo;
-}
-
-/** Store an upload result in the cache. */
-export function setCachedFileInfo(
-  contentHash: string,
-  scope: ChatScope,
-  targetId: string,
-  fileType: number,
-  fileInfo: string,
-  fileUuid: string,
-  ttl: number,
-): void {
-  if (cache.size >= MAX_CACHE_SIZE) {
-    const now = Date.now();
-    for (const [k, v] of cache) {
-      if (now >= v.expiresAt) {
-        cache.delete(k);
-      }
-    }
-    if (cache.size >= MAX_CACHE_SIZE) {
-      const keys = Array.from(cache.keys());
-      for (let i = 0; i < keys.length / 2; i++) {
-        cache.delete(keys[i]);
-      }
-    }
-  }
-
-  const key = buildCacheKey(contentHash, scope, targetId, fileType);
-  const safetyMargin = 60;
-  const effectiveTtl = Math.max(ttl - safetyMargin, 10);
-
-  cache.set(key, {
-    fileInfo,
-    fileUuid,
-    expiresAt: Date.now() + effectiveTtl * 1000,
-  });
-
-  debugLog(
-    `[upload-cache] Cache SET: key=${key.slice(0, 40)}..., ttl=${effectiveTtl}s, uuid=${fileUuid}`,
-  );
-}

package/src/engine/utils/voice-text.ts

@@ -1,15 +0,0 @@
-/**
- * Voice transcript formatting utility.
- *
- * Zero external dependencies — pure string formatting.
- */
-
-/** Format voice transcripts into user-visible text. */
-export function formatVoiceText(transcripts: string[]): string {
-  if (transcripts.length === 0) {
-    return "";
-  }
-  return transcripts.length === 1
-    ? `[Voice message] ${transcripts[0]}`
-    : transcripts.map((t, i) => `[Voice ${i + 1}] ${t}`).join("\n");
-}