@gakr-gakr/qqbot 0.1.0

package/src/engine/utils/data-paths.ts

@@ -0,0 +1,38 @@
+/**
+ * Centralised filename helpers for persisted QQBot state.
+ *
+ * Every persistence module routes file paths through these helpers so the
+ * naming convention stays in sync and legacy migrations are handled
+ * consistently.
+ *
+ * Key design decisions:
+ * - Credential backup is keyed only by `accountId` because recovery runs
+ *   exactly when the appId is missing from config.
+ */
+
+import path from "node:path";
+import { getQQBotDataPath } from "./platform.js";
+
+/**
+ * Normalise an identifier so it is safe to embed in a filename.
+ * Keeps alphanumerics, dot, underscore, dash; everything else becomes `_`.
+ */
+function safeName(id: string): string {
+  return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+// ---- credential backup ----
+
+/**
+ * Per-accountId credential backup file. Not keyed by appId because the
+ * whole point of this file is to recover credentials when appId is
+ * missing from the live config.
+ */
+export function getCredentialBackupFile(accountId: string): string {
+  return path.join(getQQBotDataPath("data"), `credential-backup-${safeName(accountId)}.json`);
+}
+
+/** Legacy single-file credential backup (pre-multi-account-isolation). */
+export function getLegacyCredentialBackupFile(): string {
+  return path.join(getQQBotDataPath("data"), "credential-backup.json");
+}

package/src/engine/utils/diagnostics.ts

@@ -0,0 +1,93 @@
+/**
+ * Gateway startup diagnostics — extracted from utils/platform.ts.
+ *
+ * Depends on utils/platform.ts for detection functions, but no plugin-sdk.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { debugLog } from "./log.js";
+import {
+  getHomeDir,
+  getTempDir,
+  getQQBotDataDir,
+  isWindows,
+  checkSilkWasmAvailable,
+} from "./platform.js";
+
+interface DiagnosticReport {
+  platform: string;
+  arch: string;
+  nodeVersion: string;
+  homeDir: string;
+  tempDir: string;
+  dataDir: string;
+  silkWasm: boolean;
+  warnings: string[];
+}
+
+/**
+ * Run startup diagnostics and return an environment report.
+ * Called during gateway startup to log environment details and warnings.
+ */
+export async function runDiagnostics(): Promise<DiagnosticReport> {
+  const warnings: string[] = [];
+
+  const platform = `${process.platform} (${os.release()})`;
+  const arch = process.arch;
+  const nodeVersion = process.version;
+  const homeDir = getHomeDir();
+  const tempDir = getTempDir();
+  const dataDir = getQQBotDataDir();
+
+  const silkWasm = await checkSilkWasmAvailable();
+  if (!silkWasm) {
+    warnings.push(
+      "⚠️ silk-wasm is unavailable. QQ voice send/receive will not work. Ensure Node.js >= 16 and WASM support are available.",
+    );
+  }
+
+  try {
+    const testFile = path.join(dataDir, ".write-test");
+    fs.writeFileSync(testFile, "test");
+    fs.unlinkSync(testFile);
+  } catch {
+    warnings.push(`⚠️ Data directory is not writable: ${dataDir}. Check filesystem permissions.`);
+  }
+
+  if (isWindows()) {
+    if (/[\u4e00-\u9fa5]/.test(homeDir) || homeDir.includes(" ")) {
+      warnings.push(
+        `⚠️ Home directory contains Chinese characters or spaces: ${homeDir}. Some tools may fail. Consider setting QQBOT_DATA_DIR to an ASCII-only path.`,
+      );
+    }
+  }
+
+  const report: DiagnosticReport = {
+    platform,
+    arch,
+    nodeVersion,
+    homeDir,
+    tempDir,
+    dataDir,
+    silkWasm,
+    warnings,
+  };
+
+  debugLog("=== QQBot Environment Diagnostics ===");
+  debugLog(`  Platform: ${platform} (${arch})`);
+  debugLog(`  Node: ${nodeVersion}`);
+  debugLog(`  Home: ${homeDir}`);
+  debugLog(`  Data dir: ${dataDir}`);
+  debugLog(`  silk-wasm: ${silkWasm ? "available" : "unavailable"}`);
+  if (warnings.length > 0) {
+    debugLog("  --- Warnings ---");
+    for (const w of warnings) {
+      debugLog(`  ${w}`);
+    }
+  }
+  debugLog("======================");
+
+  return report;
+}

package/src/engine/utils/file-utils.ts

@@ -0,0 +1,215 @@
+import crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { mimeTypeFromFilePath } from "autobot/plugin-sdk/media-mime";
+import {
+  openLocalFileSafely,
+  readRegularFile,
+  statRegularFileSync,
+} from "autobot/plugin-sdk/security-runtime";
+import { getPlatformAdapter } from "../adapter/index.js";
+import type { SsrfPolicyConfig } from "../adapter/types.js";
+import { MediaFileType } from "../types.js";
+import { formatErrorMessage } from "./format.js";
+import { normalizeOptionalString } from "./string-normalize.js";
+
+/** Maximum file size accepted by the QQ Bot one-shot upload API (base64 direct). */
+export const MAX_UPLOAD_SIZE = 20 * 1024 * 1024;
+
+/** Absolute upper bound enforced on the chunked upload path (matches server policy). */
+const CHUNKED_UPLOAD_MAX_SIZE = 100 * 1024 * 1024;
+
+/** Threshold used to treat an upload as a large file (dispatch to chunked path). */
+export const LARGE_FILE_THRESHOLD = 5 * 1024 * 1024;
+
+/**
+ * Per-{@link MediaFileType} upload metadata: the QQ Open Platform size
+ * ceiling and the Chinese display name used in user-facing error messages.
+ *
+ * Keyed by the enum value so call sites read as
+ * `MEDIA_FILE_TYPE_INFO[MediaFileType.IMAGE].maxSize`, and adding a new
+ * type forces both fields to be supplied in a single place.
+ */
+const MEDIA_FILE_TYPE_INFO: Record<MediaFileType, { maxSize: number; name: string }> = {
+  [MediaFileType.IMAGE]: { maxSize: 30 * 1024 * 1024, name: "图片" },
+  [MediaFileType.VIDEO]: { maxSize: 100 * 1024 * 1024, name: "视频" },
+  [MediaFileType.VOICE]: { maxSize: 20 * 1024 * 1024, name: "语音" },
+  [MediaFileType.FILE]: { maxSize: 100 * 1024 * 1024, name: "文件" },
+};
+
+/** Return the Chinese display name for a media file type code. Defaults to "文件". */
+export function getFileTypeName(fileType: number): string {
+  return MEDIA_FILE_TYPE_INFO[fileType as MediaFileType]?.name ?? "文件";
+}
+
+/** Return the upload ceiling for a given media file type. Defaults to 100MB. */
+export function getMaxUploadSize(fileType: number): number {
+  return MEDIA_FILE_TYPE_INFO[fileType as MediaFileType]?.maxSize ?? CHUNKED_UPLOAD_MAX_SIZE;
+}
+
+const QQBOT_MEDIA_HOSTNAME_ALLOWLIST = [
+  // QQ rich media
+  "*.qpic.cn",
+  "*.qq.com",
+  "*.weiyun.com",
+  "*.qq.com.cn",
+
+  // QQ Bot
+  "*.ugcimg.cn",
+
+  // Tencent Cloud COS
+  "*.myqcloud.com",
+  "*.tencentcos.cn",
+  "*.tencentcos.com",
+];
+
+export const QQBOT_MEDIA_SSRF_POLICY: SsrfPolicyConfig = {
+  hostnameAllowlist: QQBOT_MEDIA_HOSTNAME_ALLOWLIST,
+  allowRfc2544BenchmarkRange: true,
+};
+
+/** Result of local file-size validation. */
+interface FileSizeCheckResult {
+  ok: boolean;
+  size: number;
+  error?: string;
+}
+
+/** Validate that a file is within the allowed upload size. */
+export function checkFileSize(filePath: string, maxSize = MAX_UPLOAD_SIZE): FileSizeCheckResult {
+  try {
+    const result = statRegularFileSync(filePath);
+    if (result.missing) {
+      throw Object.assign(new Error(`File not found: ${filePath}`), { code: "ENOENT" });
+    }
+    if (result.stat.size > maxSize) {
+      const sizeMB = (result.stat.size / (1024 * 1024)).toFixed(1);
+      const limitMB = (maxSize / (1024 * 1024)).toFixed(0);
+      return {
+        ok: false,
+        size: result.stat.size,
+        error: `File is too large (${sizeMB}MB); QQ Bot API limit is ${limitMB}MB`,
+      };
+    }
+    return { ok: true, size: result.stat.size };
+  } catch (err) {
+    return {
+      ok: false,
+      size: 0,
+      error: `Failed to read file metadata: ${formatErrorMessage(err)}`,
+    };
+  }
+}
+
+/** Read file contents asynchronously. */
+export async function readFileAsync(filePath: string): Promise<Buffer> {
+  return (await readRegularFile({ filePath })).buffer;
+}
+
+/** Check file readability asynchronously. */
+export async function fileExistsAsync(filePath: string): Promise<boolean> {
+  const opened = await openLocalFileSafely({ filePath }).catch(() => null);
+  if (!opened) {
+    return false;
+  }
+  try {
+    return true;
+  } catch {
+    return false;
+  } finally {
+    await opened.handle.close().catch(() => undefined);
+  }
+}
+
+/** Format a byte count into a human-readable size string. */
+export function formatFileSize(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes}B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/** Infer a MIME type from the file extension. */
+export function getMimeType(filePath: string): string {
+  return mimeTypeFromFilePath(filePath) ?? "application/octet-stream";
+}
+
+/** Extensions accepted as image uploads by the QQ Bot media pipeline. */
+const IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"]);
+
+/**
+ * Return the image MIME type for a local file path, or `null` if the
+ * extension is not in the supported image whitelist.
+ *
+ * Use this instead of `getMimeType` when the caller must enforce
+ * "image formats only" as a business rule (e.g. constructing a
+ * `data:image/...;base64,` URL).
+ */
+export function getImageMimeType(filePath: string): string | null {
+  const ext = path.extname(filePath).toLowerCase();
+  if (!IMAGE_EXTENSIONS.has(ext)) {
+    return null;
+  }
+  const mime = mimeTypeFromFilePath(filePath);
+  return mime?.startsWith("image/") ? mime : null;
+}
+
+/** Download a remote file into a local directory. */
+export async function downloadFile(
+  url: string,
+  destDir: string,
+  originalFilename?: string,
+): Promise<string | null> {
+  try {
+    let parsedUrl: URL;
+    try {
+      parsedUrl = new URL(url);
+    } catch {
+      return null;
+    }
+    if (parsedUrl.protocol !== "https:") {
+      return null;
+    }
+
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+
+    const fetched = await getPlatformAdapter().fetchMedia({
+      url: parsedUrl.toString(),
+      filePathHint: originalFilename,
+      ssrfPolicy: QQBOT_MEDIA_SSRF_POLICY,
+    });
+
+    let filename = normalizeOptionalString(originalFilename) ?? "";
+    if (!filename) {
+      filename =
+        (normalizeOptionalString(fetched.fileName) ?? path.basename(parsedUrl.pathname)) ||
+        "download";
+    }
+
+    const ts = Date.now();
+    const ext = path.extname(filename);
+    const base = path.basename(filename, ext) || "file";
+    const rand = crypto.randomBytes(3).toString("hex");
+    const safeFilename = `${base}_${ts}_${rand}${ext}`;
+
+    const destPath = path.join(destDir, safeFilename);
+    await fs.promises.writeFile(destPath, fetched.buffer);
+    return destPath;
+  } catch (err) {
+    console.error(
+      `[qqbot:downloadFile] FAILED url=${url.slice(0, 120)} error=${err instanceof Error ? err.message : String(err)}`,
+    );
+    if (err instanceof Error && err.stack) {
+      console.error(`[qqbot:downloadFile] stack=${err.stack.split("\n").slice(0, 3).join(" | ")}`);
+    }
+    if (err instanceof Error && err.cause) {
+      console.error(`[qqbot:downloadFile] cause=${formatErrorMessage(err.cause)}`);
+    }
+    return null;
+  }
+}

package/src/engine/utils/format.ts

@@ -0,0 +1,70 @@
+/**
+ * General formatting and string utilities.
+ * 通用格式化与字符串工具。
+ *
+ * Pure utility functions with zero external dependencies.
+ * Replaces `autobot/plugin-sdk/error-runtime` and `text-runtime`
+ * helpers for use inside engine/.
+ *
+ * NOTE: The framework `formatErrorMessage` also applies `redactSensitiveText()`
+ * for token masking. We intentionally omit that here — the framework's log
+ * pipeline handles redaction at a higher level.
+ */
+
+/**
+ * Format any error object into a readable string.
+ * 将任意错误对象格式化为可读字符串。
+ *
+ * Traverses the `.cause` chain for nested Error objects to include
+ * the full error context (e.g. network errors wrapped inside HTTP errors).
+ */
+export function formatErrorMessage(err: unknown): string {
+  if (err instanceof Error) {
+    let formatted = err.message || err.name || "Error";
+    let cause: unknown = err.cause;
+    const seen = new Set<unknown>([err]);
+    while (cause && !seen.has(cause)) {
+      seen.add(cause);
+      if (cause instanceof Error) {
+        if (cause.message) {
+          formatted += ` | ${cause.message}`;
+        }
+        cause = cause.cause;
+      } else if (typeof cause === "string") {
+        formatted += ` | ${cause}`;
+        break;
+      } else {
+        break;
+      }
+    }
+    return formatted;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  if (
+    err === null ||
+    err === undefined ||
+    typeof err === "number" ||
+    typeof err === "boolean" ||
+    typeof err === "bigint"
+  ) {
+    return String(err);
+  }
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return Object.prototype.toString.call(err);
+  }
+}
+
+/** Format a millisecond duration into a human-readable string (e.g. "5m 30s"). */
+export function formatDuration(durationMs: number): string {
+  const seconds = Math.round(durationMs / 1000);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const remainSeconds = seconds % 60;
+  return remainSeconds > 0 ? `${minutes}m ${remainSeconds}s` : `${minutes}m`;
+}

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

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