@gakr-gakr/qqbot 0.1.0

package/src/engine/utils/log.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+
+function isQqbotDebugEnabled(): boolean {
+  const value = process.env.QQBOT_DEBUG;
+  if (typeof value !== "string") {
+    return false;
+  }
+  switch (value.trim().toLowerCase()) {
+    case "1":
+    case "on":
+    case "true":
+    case "yes":
+      return true;
+    default:
+      return false;
+  }
+}
+
+const isDebug = () => isQqbotDebugEnabled();
+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.ts

@@ -0,0 +1,177 @@
+/**
+ * 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.ts

@@ -0,0 +1,157 @@
+/**
+ * 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);
+}
+
+function normalizeBase64ForCompare(value: string): string {
+  return value.replace(/=+$/u, "").replace(/-/gu, "+").replace(/_/gu, "/");
+}
+
+function decodeStrictBase64Utf8(value: string): string {
+  const buffer = Buffer.from(value, "base64");
+  if (normalizeBase64ForCompare(buffer.toString("base64")) !== normalizeBase64ForCompare(value)) {
+    throw new Error("Cron payload body is not valid base64");
+  }
+  return buffer.toString("utf-8");
+}
+
+/** 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 = decodeStrictBase64Utf8(base64Content);
+    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.ts

@@ -0,0 +1,265 @@
+/**
+ * Cross-platform path and detection helpers for core/ modules.
+ *
+ * Provides home/data/media directory helpers, platform detection,
+ * silk-wasm availability checks — all without importing `autobot/plugin-sdk`.
+ * The temp-directory fallback is delegated to the PlatformAdapter.
+ */
+
+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 `~/.autobot/qqbot` without creating it. */
+export function getQQBotDataPath(...subPaths: string[]): string {
+  return path.join(getHomeDir(), ".autobot", "qqbot", ...subPaths);
+}
+
+/** Return a path under `~/.autobot/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 `~/.autobot/media/qqbot` without creating it.
+ *
+ * Unlike `getQQBotDataPath`, this lives under AutoBot'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(), ".autobot", "media", "qqbot", ...subPaths);
+}
+
+/** Return a path under `~/.autobot/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 `~/.autobot/media`, AutoBot's shared media root.
+ *
+ * This mirrors the directory that core's `buildMediaLocalRoots` exposes as an
+ * allowlisted location (see `autobot/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 getAutoBotMediaDir(): string {
+  return path.join(getHomeDir(), ".autobot", "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();
+}
+
+// ---- 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, ".autobot", "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 AutoBot's shared `~/.autobot/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 = [getAutoBotMediaDir(), 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;
+}