@gakr-gakr/qqbot 0.1.0

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

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

@@ -0,0 +1,91 @@
+/**
+ * String normalization and record-coercion helpers.
+ *
+ * These are self-contained re-implementations of the functions that
+ * the plugin previously imported from broad SDK text barrels
+ * and shared record/string coercion helpers.
+ *
+ * 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.ts

@@ -0,0 +1,103 @@
+/**
+ * OpenAI-compatible STT (Speech-to-Text) configuration and transcription.
+ *
+ * Migrated from `src/stt.ts` — uses core/utils/string-normalize instead
+ * of broad SDK text barrels.
+ */
+
+import * as fs from "node:fs";
+import path from "node:path";
+import { mimeTypeFromFilePath } from "autobot/plugin-sdk/media-mime";
+import { fetchWithSsrFGuard } from "autobot/plugin-sdk/ssrf-runtime";
+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 = mimeTypeFromFilePath(fileName) ?? "application/octet-stream";
+
+  const form = new FormData();
+  form.append("file", new Blob([fileBuffer], { type: mime }), fileName);
+  form.append("model", sttCfg.model);
+
+  const { response: resp, release } = await fetchWithSsrFGuard({
+    url: `${sttCfg.baseUrl}/audio/transcriptions`,
+    auditContext: "qqbot-stt",
+    init: {
+      method: "POST",
+      headers: { Authorization: `Bearer ${sttCfg.apiKey}` },
+      body: form,
+    },
+  });
+  try {
+    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;
+  } finally {
+    await release();
+  }
+}

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

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

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

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