@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

package/src/engine/utils/image-size.ts

@@ -1,249 +0,0 @@
-/**
- * Image dimension helpers for QQ Bot markdown image syntax.
- *
- * QQ Bot markdown images use `![#widthpx #heightpx](url)`.
- */
-
-import { Buffer } from "node:buffer";
-import { getPlatformAdapter } from "../adapter/index.js";
-import type { SsrfPolicyConfig } from "../adapter/types.js";
-import { formatErrorMessage } from "./format.js";
-import { debugLog } from "./log.js";
-
-interface ImageSize {
-  width: number;
-  height: number;
-}
-
-/** Default dimensions used when probing fails. */
-const DEFAULT_IMAGE_SIZE: ImageSize = { width: 512, height: 512 };
-
-/**
- * Parse image dimensions from the PNG header.
- */
-function parsePngSize(buffer: Buffer): ImageSize | null {
-  // PNG signature: 89 50 4E 47 0D 0A 1A 0A
-  if (buffer.length < 24) {
-    return null;
-  }
-  if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4e || buffer[3] !== 0x47) {
-    return null;
-  }
-  // The IHDR chunk begins at byte 8, with width/height at 16..23.
-  const width = buffer.readUInt32BE(16);
-  const height = buffer.readUInt32BE(20);
-  return { width, height };
-}
-
-/** Parse image dimensions from JPEG SOF0/SOF2 markers. */
-function parseJpegSize(buffer: Buffer): ImageSize | null {
-  // JPEG signature: FF D8 FF
-  if (buffer.length < 4) {
-    return null;
-  }
-  if (buffer[0] !== 0xff || buffer[1] !== 0xd8) {
-    return null;
-  }
-
-  let offset = 2;
-  while (offset < buffer.length - 9) {
-    if (buffer[offset] !== 0xff) {
-      offset++;
-      continue;
-    }
-
-    const marker = buffer[offset + 1];
-    // SOF0 (0xC0) and SOF2 (0xC2) contain dimensions.
-    if (marker === 0xc0 || marker === 0xc2) {
-      // Layout: FF C0 length(2) precision(1) height(2) width(2)
-      if (offset + 9 <= buffer.length) {
-        const height = buffer.readUInt16BE(offset + 5);
-        const width = buffer.readUInt16BE(offset + 7);
-        return { width, height };
-      }
-    }
-
-    // Skip the current block.
-    if (offset + 3 < buffer.length) {
-      const blockLength = buffer.readUInt16BE(offset + 2);
-      offset += 2 + blockLength;
-    } else {
-      break;
-    }
-  }
-
-  return null;
-}
-
-/** Parse image dimensions from the GIF header. */
-function parseGifSize(buffer: Buffer): ImageSize | null {
-  if (buffer.length < 10) {
-    return null;
-  }
-  const signature = buffer.toString("ascii", 0, 6);
-  if (signature !== "GIF87a" && signature !== "GIF89a") {
-    return null;
-  }
-  const width = buffer.readUInt16LE(6);
-  const height = buffer.readUInt16LE(8);
-  return { width, height };
-}
-
-/** Parse image dimensions from WebP headers. */
-function parseWebpSize(buffer: Buffer): ImageSize | null {
-  if (buffer.length < 30) {
-    return null;
-  }
-
-  // Check the RIFF and WEBP signatures.
-  const riff = buffer.toString("ascii", 0, 4);
-  const webp = buffer.toString("ascii", 8, 12);
-  if (riff !== "RIFF" || webp !== "WEBP") {
-    return null;
-  }
-
-  const chunkType = buffer.toString("ascii", 12, 16);
-
-  // VP8 (lossy)
-  if (chunkType === "VP8 ") {
-    // The VP8 frame header starts at byte 23 and uses the 9D 01 2A signature.
-    if (buffer.length >= 30 && buffer[23] === 0x9d && buffer[24] === 0x01 && buffer[25] === 0x2a) {
-      const width = buffer.readUInt16LE(26) & 0x3fff;
-      const height = buffer.readUInt16LE(28) & 0x3fff;
-      return { width, height };
-    }
-  }
-
-  // VP8L (lossless)
-  if (chunkType === "VP8L") {
-    // VP8L signature: 0x2F
-    if (buffer.length >= 25 && buffer[20] === 0x2f) {
-      const bits = buffer.readUInt32LE(21);
-      const width = (bits & 0x3fff) + 1;
-      const height = ((bits >> 14) & 0x3fff) + 1;
-      return { width, height };
-    }
-  }
-
-  // VP8X (extended format)
-  if (chunkType === "VP8X") {
-    if (buffer.length >= 30) {
-      // Width and height live at 24..26 and 27..29 as 24-bit little-endian values.
-      const width = (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16)) + 1;
-      const height = (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16)) + 1;
-      return { width, height };
-    }
-  }
-
-  return null;
-}
-
-/** Parse image dimensions from raw image bytes. */
-export function parseImageSize(buffer: Buffer): ImageSize | null {
-  // Try each supported image format in sequence.
-  return (
-    parsePngSize(buffer) ?? parseJpegSize(buffer) ?? parseGifSize(buffer) ?? parseWebpSize(buffer)
-  );
-}
-
-/**
- * SSRF policy for image-dimension probing.  Generic public-network-only blocking
- * (no hostname allowlist) because markdown image URLs can legitimately point to
- * any public host, not just QQ-owned CDNs.
- */
-const IMAGE_PROBE_SSRF_POLICY: SsrfPolicyConfig = {};
-
-/**
- * Fetch image dimensions from a public URL using only the first 64 KB.
- *
- * Uses {@link fetchRemoteMedia} with SSRF guard to block probes against
- * private/reserved/loopback/link-local/metadata destinations.
- */
-export async function getImageSizeFromUrl(
-  url: string,
-  timeoutMs = 5000,
-): Promise<ImageSize | null> {
-  try {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-
-    try {
-      const { buffer } = await getPlatformAdapter().fetchMedia({
-        url,
-        maxBytes: 65_536,
-        maxRedirects: 0,
-        ssrfPolicy: IMAGE_PROBE_SSRF_POLICY,
-        requestInit: {
-          signal: controller.signal,
-          headers: {
-            Range: "bytes=0-65535",
-            "User-Agent": "QQBot-Image-Size-Detector/1.0",
-          },
-        },
-      });
-
-      const size = parseImageSize(buffer);
-      if (size) {
-        debugLog(
-          `[image-size] Got size from URL: ${size.width}x${size.height} - ${url.slice(0, 60)}...`,
-        );
-      }
-      return size;
-    } finally {
-      clearTimeout(timeoutId);
-    }
-  } catch (err) {
-    debugLog(`[image-size] Error fetching ${url.slice(0, 60)}...: ${formatErrorMessage(err)}`);
-    return null;
-  }
-}
-
-/** Parse image dimensions from a Base64 data URL. */
-function getImageSizeFromDataUrl(dataUrl: string): ImageSize | null {
-  try {
-    // Format: data:image/png;base64,xxxxx
-    const matches = dataUrl.match(/^data:image\/[^;]+;base64,(.+)$/);
-    if (!matches) {
-      return null;
-    }
-
-    const base64Data = matches[1];
-    const buffer = Buffer.from(base64Data, "base64");
-
-    const size = parseImageSize(buffer);
-    if (size) {
-      debugLog(`[image-size] Got size from Base64: ${size.width}x${size.height}`);
-    }
-
-    return size;
-  } catch (err) {
-    debugLog(`[image-size] Error parsing Base64: ${formatErrorMessage(err)}`);
-    return null;
-  }
-}
-
-/**
- * Resolve image dimensions from either an HTTP URL or a Base64 data URL.
- */
-export async function getImageSize(source: string): Promise<ImageSize | null> {
-  if (source.startsWith("data:")) {
-    return getImageSizeFromDataUrl(source);
-  }
-
-  if (source.startsWith("http://") || source.startsWith("https://")) {
-    return getImageSizeFromUrl(source);
-  }
-
-  return null;
-}
-
-/** Format a markdown image with QQ Bot width/height annotations. */
-export function formatQQBotMarkdownImage(url: string, size: ImageSize | null): string {
-  const { width, height } = size ?? DEFAULT_IMAGE_SIZE;
-  return `![#${width}px #${height}px](${url})`;
-}
-
-/** Return true when markdown already contains QQ Bot size annotations. */
-export function hasQQBotImageSize(markdownImage: string): boolean {
-  return /!\[#\d+px\s+#\d+px\]/.test(markdownImage);
-}

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

@@ -1,28 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { debugLog, sanitizeDebugLogValue } from "./log.js";
-
-const originalDebug = process.env.QQBOT_DEBUG;
-
-afterEach(() => {
-  if (originalDebug === undefined) {
-    delete process.env.QQBOT_DEBUG;
-  } else {
-    process.env.QQBOT_DEBUG = originalDebug;
-  }
-  vi.restoreAllMocks();
-});
-
-describe("QQBot debug logging", () => {
-  it("neutralizes control characters in log values", () => {
-    expect(sanitizeDebugLogValue("before\nforged\r\tentry")).toBe("before forged entry");
-  });
-
-  it("sanitizes arguments before debug console output", () => {
-    process.env.QQBOT_DEBUG = "1";
-    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
-
-    debugLog("prefix", "line one\nline two");
-
-    expect(logSpy).toHaveBeenCalledWith("prefix line one line two");
-  });
-});

package/src/engine/utils/log.ts

@@ -1,61 +0,0 @@
-/**
- * QQBot debug logging utilities.
- * QQBot 调试日志工具。
- *
- * Only outputs when the QQBOT_DEBUG environment variable is set,
- * preventing user message content from leaking in production logs.
- *
- * Self-contained within engine/ — no framework SDK dependency.
- */
-
-const isDebug = () => !!process.env.QQBOT_DEBUG;
-const MAX_LOG_VALUE_CHARS = 4096;
-
-export function sanitizeDebugLogValue(value: unknown): string {
-  let text: string;
-  if (typeof value === "string") {
-    text = value;
-  } else if (value instanceof Error) {
-    text = value.stack || value.message;
-  } else {
-    try {
-      text = JSON.stringify(value) ?? String(value);
-    } catch {
-      text = String(value);
-    }
-  }
-
-  const sanitized = text
-    .replace(/\p{Cc}/gu, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-  if (sanitized.length <= MAX_LOG_VALUE_CHARS) {
-    return sanitized;
-  }
-  return `${sanitized.slice(0, MAX_LOG_VALUE_CHARS)}...`;
-}
-
-function formatDebugLogArgs(args: unknown[]): string {
-  return args.map(sanitizeDebugLogValue).join(" ");
-}
-
-/** Debug-level log; only outputs when QQBOT_DEBUG is enabled. */
-export function debugLog(...args: unknown[]): void {
-  if (isDebug()) {
-    console.log(formatDebugLogArgs(args).replace(/\n|\r/g, ""));
-  }
-}
-
-/** Debug-level warning; only outputs when QQBOT_DEBUG is enabled. */
-export function debugWarn(...args: unknown[]): void {
-  if (isDebug()) {
-    console.warn(formatDebugLogArgs(args).replace(/\n|\r/g, ""));
-  }
-}
-
-/** Debug-level error; only outputs when QQBOT_DEBUG is enabled. */
-export function debugError(...args: unknown[]): void {
-  if (isDebug()) {
-    console.error(formatDebugLogArgs(args).replace(/\n|\r/g, ""));
-  }
-}

package/src/engine/utils/media-tags.test.ts

@@ -1,32 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { FUZZY_MEDIA_TAG_REGEX, SELF_CLOSING_TAG_REGEX } from "./media-tags.js";
-
-describe("media-tags with HTML entities", () => {
-  it("extracts URL from entity-encoded fuzzy tag", () => {
-    const input = "<qqimg>https://example.com/a.png</qqimg>";
-    FUZZY_MEDIA_TAG_REGEX.lastIndex = 0;
-    const match = FUZZY_MEDIA_TAG_REGEX.exec(input);
-    expect(match?.[2]).toBe("https://example.com/a.png");
-  });
-
-  it("extracts URL from mixed entity+plain tag", () => {
-    const input = "&lt;qqimg&gt;https://example.com/b.png</qqimg>";
-    FUZZY_MEDIA_TAG_REGEX.lastIndex = 0;
-    const match = FUZZY_MEDIA_TAG_REGEX.exec(input);
-    expect(match?.[2]).toBe("https://example.com/b.png");
-  });
-
-  it("extracts file from entity-encoded self-closing tag", () => {
-    const input = '&lt;qqmedia file="https://example.com/c.zip" /&gt;';
-    SELF_CLOSING_TAG_REGEX.lastIndex = 0;
-    const match = SELF_CLOSING_TAG_REGEX.exec(input);
-    expect(match?.[2]).toBe("https://example.com/c.zip");
-  });
-
-  it("does not match invalid input", () => {
-    const input = "no tag here";
-    FUZZY_MEDIA_TAG_REGEX.lastIndex = 0;
-    const match = FUZZY_MEDIA_TAG_REGEX.exec(input);
-    expect(match).toBeNull();
-  });
-});

package/src/engine/utils/media-tags.ts

@@ -1,177 +0,0 @@
-/**
- * Media tag normalization for QQ Bot messages.
- *
- * Normalizes malformed `<qqimg>`, `<qqvoice>`, etc. tags emitted by
- * smaller models into canonical wrapped-tag format.
- *
- * Zero external dependencies.
- */
-
-/** Lowercase and trim a string, returning empty string for falsy input. */
-function lc(s: string): string {
-  return (s ?? "").toLowerCase().trim();
-}
-
-/** Expand `~` prefix to the process home directory. */
-function expandTilde(p: string): string {
-  if (!p) {
-    return p;
-  }
-  const home =
-    typeof process !== "undefined" ? (process.env.HOME ?? process.env.USERPROFILE) : undefined;
-  if (!home) {
-    return p;
-  }
-  if (p === "~") {
-    return home;
-  }
-  if (p.startsWith("~/") || p.startsWith("~\\")) {
-    return `${home}/${p.slice(2)}`;
-  }
-  return p;
-}
-
-// Canonical media tags. `qqmedia` is the generic auto-routing tag.
-const VALID_TAGS = ["qqimg", "qqvoice", "qqvideo", "qqfile", "qqmedia"] as const;
-
-// Lowercased aliases that should normalize to the canonical tag set.
-const TAG_ALIASES: Record<string, (typeof VALID_TAGS)[number]> = {
-  qq_img: "qqimg",
-  qqimage: "qqimg",
-  qq_image: "qqimg",
-  qqpic: "qqimg",
-  qq_pic: "qqimg",
-  qqpicture: "qqimg",
-  qq_picture: "qqimg",
-  qqphoto: "qqimg",
-  qq_photo: "qqimg",
-  img: "qqimg",
-  image: "qqimg",
-  pic: "qqimg",
-  picture: "qqimg",
-  photo: "qqimg",
-  qq_voice: "qqvoice",
-  qqaudio: "qqvoice",
-  qq_audio: "qqvoice",
-  voice: "qqvoice",
-  audio: "qqvoice",
-  qq_video: "qqvideo",
-  video: "qqvideo",
-  qq_file: "qqfile",
-  qqdoc: "qqfile",
-  qq_doc: "qqfile",
-  file: "qqfile",
-  doc: "qqfile",
-  document: "qqfile",
-  qq_media: "qqmedia",
-  media: "qqmedia",
-  attachment: "qqmedia",
-  attach: "qqmedia",
-  qqattachment: "qqmedia",
-  qq_attachment: "qqmedia",
-  qqsend: "qqmedia",
-  qq_send: "qqmedia",
-  send: "qqmedia",
-};
-
-const ALL_TAG_NAMES = [...VALID_TAGS, ...Object.keys(TAG_ALIASES)];
-ALL_TAG_NAMES.sort((a, b) => b.length - a.length);
-
-const TAG_NAME_PATTERN = ALL_TAG_NAMES.join("|");
-
-const LEFT_BRACKET = "(?:[<\uff1c\u003c]|&lt;)";
-const RIGHT_BRACKET = "(?:[>\uff1e\u003e]|&gt;)";
-
-/** Match self-closing media-tag syntax with file/src/path/url attributes. */
-export const SELF_CLOSING_TAG_REGEX = new RegExp(
-  "`?" +
-    LEFT_BRACKET +
-    "\\s*(" +
-    TAG_NAME_PATTERN +
-    ")" +
-    "(?:\\s+(?!file|src|path|url)[a-z_-]+\\s*=\\s*[\"']?[^\"'\\s\uff1c<>\uff1e>]*?[\"']?)*" +
-    "\\s+(?:file|src|path|url)\\s*=\\s*" +
-    "[\"']?" +
-    "([^\"'\\s>\uff1e]+?)" +
-    "[\"']?" +
-    "(?:\\s+[a-z_-]+\\s*=\\s*[\"']?[^\"'\\s\uff1c<>\uff1e>]*?[\"']?)*" +
-    "\\s*/?" +
-    "\\s*" +
-    RIGHT_BRACKET +
-    "`?",
-  "gi",
-);
-
-/** Match malformed wrapped media tags that should be normalized. */
-export const FUZZY_MEDIA_TAG_REGEX = new RegExp(
-  "`?" +
-    LEFT_BRACKET +
-    "\\s*(" +
-    TAG_NAME_PATTERN +
-    ")\\s*" +
-    RIGHT_BRACKET +
-    "[\"']?\\s*" +
-    "([^<\uff1c<\uff1e>\"'`]+?)" +
-    "\\s*[\"']?" +
-    LEFT_BRACKET +
-    "\\s*/?\\s*(?:" +
-    TAG_NAME_PATTERN +
-    ")\\s*" +
-    RIGHT_BRACKET +
-    "`?",
-  "gi",
-);
-
-/** Normalize a raw tag name into the canonical tag set. */
-function resolveTagName(raw: string): (typeof VALID_TAGS)[number] {
-  const lower = lc(raw);
-  if ((VALID_TAGS as readonly string[]).includes(lower)) {
-    return lower as (typeof VALID_TAGS)[number];
-  }
-  return TAG_ALIASES[lower] ?? "qqimg";
-}
-
-/** Match wrapped tags whose bodies need newline and tab cleanup. */
-const MULTILINE_TAG_CLEANUP = new RegExp(
-  "(" +
-    LEFT_BRACKET +
-    "\\s*(?:" +
-    TAG_NAME_PATTERN +
-    ")\\s*" +
-    RIGHT_BRACKET +
-    ")" +
-    "([\\s\\S]*?)" +
-    "(" +
-    LEFT_BRACKET +
-    "\\s*/?\\s*(?:" +
-    TAG_NAME_PATTERN +
-    ")\\s*" +
-    RIGHT_BRACKET +
-    ")",
-  "gi",
-);
-
-/** Normalize malformed media-tag output into canonical wrapped tags. */
-export function normalizeMediaTags(text: string): string {
-  const normalizeWrappedTag = (_match: string, rawTag: string, content: string): string => {
-    const tag = resolveTagName(rawTag);
-    const trimmed = content.trim();
-    if (!trimmed) {
-      return _match;
-    }
-    const expanded = expandTilde(trimmed);
-    return `<${tag}>${expanded}</${tag}>`;
-  };
-
-  let cleaned = text.replace(SELF_CLOSING_TAG_REGEX, normalizeWrappedTag);
-
-  cleaned = cleaned.replace(
-    MULTILINE_TAG_CLEANUP,
-    (_m, open: string, body: string, close: string) => {
-      const flat = body.replace(/[\r\n\t]+/g, " ").replace(/ {2,}/g, " ");
-      return open + flat + close;
-    },
-  );
-
-  return cleaned.replace(FUZZY_MEDIA_TAG_REGEX, normalizeWrappedTag);
-}

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

@@ -1,68 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  decodeCronPayload,
-  encodePayloadForCron,
-  isCronReminderPayload,
-  isMediaPayload,
-  parseQQBotPayload,
-  type CronReminderPayload,
-} from "./payload.js";
-
-describe("engine/utils/payload", () => {
-  it("returns original text for non-payload replies", () => {
-    const result = parseQQBotPayload("  plain reply  ");
-
-    expect(result).toEqual({ isPayload: false, text: "  plain reply  " });
-  });
-
-  it("parses a media payload", () => {
-    const result = parseQQBotPayload(
-      'QQBOT_PAYLOAD: {"type":"media","mediaType":"image","source":"url","path":"https://example.test/a.png","caption":"cap"}',
-    );
-
-    expect(result.isPayload).toBe(true);
-    expect(result.payload).toEqual({
-      type: "media",
-      mediaType: "image",
-      source: "url",
-      path: "https://example.test/a.png",
-      caption: "cap",
-    });
-    expect(result.payload && isMediaPayload(result.payload)).toBe(true);
-  });
-
-  it("rejects malformed or incomplete payloads", () => {
-    expect(parseQQBotPayload("QQBOT_PAYLOAD:").error).toBe("Payload body is empty");
-    expect(parseQQBotPayload("QQBOT_PAYLOAD: {bad json").error).toContain("Failed to parse JSON");
-    expect(parseQQBotPayload('QQBOT_PAYLOAD: {"type":"media","mediaType":"image"}').error).toBe(
-      "media payload is missing required fields (mediaType, source, path)",
-    );
-  });
-
-  it("round-trips cron reminder payloads through the stored format", () => {
-    const payload: CronReminderPayload = {
-      type: "cron_reminder",
-      content: "standup",
-      targetType: "group",
-      targetAddress: "group-openid",
-      originalMessageId: "msg-1",
-    };
-
-    const encoded = encodePayloadForCron(payload);
-    expect(encoded).toMatch(/^QQBOT_CRON:/);
-
-    const decoded = decodeCronPayload(encoded);
-    expect(decoded).toEqual({ isCronPayload: true, payload });
-    expect(decoded.payload && isCronReminderPayload(decoded.payload)).toBe(true);
-  });
-
-  it("reports cron decode errors without throwing", () => {
-    expect(decodeCronPayload("plain")).toEqual({ isCronPayload: false });
-    expect(decodeCronPayload("QQBOT_CRON:").error).toBe("Cron payload body is empty");
-
-    const wrongType = Buffer.from('{"type":"media"}', "utf-8").toString("base64");
-    expect(decodeCronPayload(`QQBOT_CRON:${wrongType}`).error).toBe(
-      "Expected type cron_reminder but got media",
-    );
-  });
-});