@gakr-gakr/qqbot 0.1.0

package/src/engine/ref/format-message-ref.ts

@@ -0,0 +1,142 @@
+/**
+ * Format a message_reference (from msg_elements[0]) into text for model context.
+ *
+ * This handles the cache-miss path: when a user quotes a message we haven't
+ * cached in the ref-index store, we fall back to the msg_elements[0] data
+ * pushed by the QQ platform.
+ *
+ * The heavy lifting (attachment download, STT, etc.) is delegated to an
+ * injected `AttachmentProcessor` so this module stays framework-agnostic.
+ */
+
+import type { EngineLogger } from "../types.js";
+import { parseFaceTags, buildAttachmentSummaries } from "../utils/text-parsing.js";
+import { formatRefEntryForAgent } from "./format-ref-entry.js";
+import type { RefAttachmentSummary } from "./types.js";
+
+// ============ Injected dependency ============
+
+/** Attachment download & voice transcription — injected from the outer layer. */
+export interface AttachmentProcessor {
+  processAttachments(
+    attachments:
+      | Array<{
+          content_type: string;
+          url: string;
+          filename?: string;
+          height?: number;
+          width?: number;
+          size?: number;
+          voice_wav_url?: string;
+          asr_refer_text?: string;
+        }>
+      | undefined,
+    ctx: { appId: string; peerId?: string; cfg: unknown; log?: EngineLogger },
+  ): Promise<{
+    attachmentInfo: string;
+    voiceTranscripts: string[];
+    voiceTranscriptSources: string[];
+    attachmentLocalPaths: Array<string | null>;
+  }>;
+
+  formatVoiceText(voiceTranscripts: string[]): string;
+}
+
+// ============ Public API ============
+
+/**
+ * Format a quoted message reference into human-readable text for model context.
+ *
+ * This mirrors the independent version's `formatMessageReferenceForAgent` —
+ * processing attachments (download + STT) and combining them with parsed text.
+ *
+ * @param ref - The msg_elements[0] data from the QQ push event.
+ * @param ctx - Context containing appId, peerId, config, and logger.
+ * @param processor - Injected attachment processor (download + voice transcription).
+ */
+export async function formatMessageReferenceForAgent(
+  ref:
+    | {
+        content?: string;
+        attachments?: Array<{
+          content_type: string;
+          url: string;
+          filename?: string;
+          height?: number;
+          width?: number;
+          size?: number;
+          voice_wav_url?: string;
+          asr_refer_text?: string;
+        }>;
+      }
+    | undefined,
+  ctx: {
+    appId: string;
+    peerId?: string;
+    cfg: unknown;
+    log?: EngineLogger;
+  },
+  processor: AttachmentProcessor,
+): Promise<string> {
+  if (!ref) {
+    return "";
+  }
+
+  // Process attachments (download images, transcribe voice, etc.)
+  const processed = await processor.processAttachments(ref.attachments, ctx);
+  const { attachmentInfo, voiceTranscripts, voiceTranscriptSources, attachmentLocalPaths } =
+    processed;
+
+  // Format voice transcript text
+  const voiceText = processor.formatVoiceText(voiceTranscripts);
+
+  // Parse QQ face tags into readable text
+  const parsedContent = parseFaceTags(ref.content ?? "");
+
+  // Combine text content with voice transcript and attachment info
+  const userContent = voiceText
+    ? (parsedContent.trim() ? `${parsedContent}\n${voiceText}` : voiceText) + attachmentInfo
+    : parsedContent + attachmentInfo;
+
+  // Build attachment summaries and inject voice transcripts
+  const attSummaries = buildAttachmentSummaries(
+    ref.attachments as Array<{
+      content_type: string;
+      url: string;
+      filename?: string;
+      voice_wav_url?: string;
+    }>,
+    attachmentLocalPaths,
+  );
+  if (attSummaries && voiceTranscripts.length > 0) {
+    let voiceIdx = 0;
+    for (const att of attSummaries) {
+      if (att.type === "voice" && voiceIdx < voiceTranscripts.length) {
+        att.transcript = voiceTranscripts[voiceIdx];
+        if (voiceIdx < voiceTranscriptSources.length) {
+          att.transcriptSource = voiceTranscriptSources[
+            voiceIdx
+          ] as RefAttachmentSummary["transcriptSource"];
+        }
+        voiceIdx++;
+      }
+    }
+  }
+
+  // Format using the same function as the cache-hit path
+  const refEntry = {
+    content: userContent.trim(),
+    senderId: "",
+    timestamp: Date.now(),
+    attachments: attSummaries,
+  };
+
+  const formattedAttachments = formatRefEntryForAgent(refEntry);
+  // If formatRefEntryForAgent already includes the content, use it directly.
+  // Otherwise combine manually.
+  if (formattedAttachments !== "[empty message]") {
+    return formattedAttachments;
+  }
+
+  return userContent.trim() || "";
+}

package/src/engine/ref/format-ref-entry.ts

@@ -0,0 +1,27 @@
+/**
+ * Format a ref-index entry into text suitable for model context.
+ *
+ * Delegates all attachment rendering to the shared
+ * `utils/attachment-tags.ts::renderAttachmentTags` (with `mode: "ref"`)
+ * so the quoted-message preview and the current-message history use
+ * identical wording for identical attachment types.
+ */
+
+import { renderAttachmentTags } from "../utils/attachment-tags.js";
+import type { RefIndexEntry } from "./types.js";
+
+/** Format a ref-index entry into text suitable for model context. */
+export function formatRefEntryForAgent(entry: RefIndexEntry): string {
+  const parts: string[] = [];
+
+  if (entry.content.trim()) {
+    parts.push(entry.content);
+  }
+
+  const attachmentTags = renderAttachmentTags(entry.attachments, { mode: "ref" });
+  if (attachmentTags) {
+    parts.push(attachmentTags);
+  }
+
+  return parts.join(" ") || "[empty message]";
+}

package/src/engine/ref/store.ts

@@ -0,0 +1,211 @@
+/**
+ * Ref-index store — JSONL file-based store for message reference index.
+ *
+ * Migrated from src/ref-index-store.ts. Dependencies are only Node.js
+ * built-ins + log + platform (both zero plugin-sdk).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { appendRegularFileSync, replaceFileAtomicSync } from "autobot/plugin-sdk/security-runtime";
+import { formatErrorMessage } from "../utils/format.js";
+import { debugLog, debugError } from "../utils/log.js";
+import { getQQBotDataDir, getQQBotDataPath } from "../utils/platform.js";
+import type { RefIndexEntry } from "./types.js";
+
+// Re-export types and format function for convenience.
+export type { RefIndexEntry, RefAttachmentSummary } from "./types.js";
+export { formatRefEntryForAgent } from "./format-ref-entry.js";
+
+const MAX_ENTRIES = 50000;
+const TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const COMPACT_THRESHOLD_RATIO = 2;
+
+interface RefIndexLine {
+  k: string;
+  v: RefIndexEntry;
+  t: number;
+}
+
+let cache: Map<string, RefIndexEntry & { createdAt: number }> | null = null;
+let totalLinesOnDisk = 0;
+
+function getRefIndexFile(): string {
+  return path.join(getQQBotDataPath("data"), "ref-index.jsonl");
+}
+
+function loadFromFile(): Map<string, RefIndexEntry & { createdAt: number }> {
+  if (cache !== null) {
+    return cache;
+  }
+  cache = new Map();
+  totalLinesOnDisk = 0;
+
+  try {
+    const refIndexFile = getRefIndexFile();
+    if (!fs.existsSync(refIndexFile)) {
+      return cache;
+    }
+    const raw = fs.readFileSync(refIndexFile, "utf-8");
+    const lines = raw.split("\n");
+    const now = Date.now();
+    let expired = 0;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+      totalLinesOnDisk++;
+      try {
+        const entry = JSON.parse(trimmed) as RefIndexLine;
+        if (!entry.k || !entry.v || !entry.t) {
+          continue;
+        }
+        if (now - entry.t > TTL_MS) {
+          expired++;
+          continue;
+        }
+        cache.set(entry.k, { ...entry.v, createdAt: entry.t });
+      } catch {}
+    }
+    debugLog(
+      `[ref-index-store] Loaded ${cache.size} entries from ${totalLinesOnDisk} lines (${expired} expired)`,
+    );
+    if (shouldCompact()) {
+      compactFile();
+    }
+  } catch (err) {
+    debugError(`[ref-index-store] Failed to load: ${formatErrorMessage(err)}`);
+    cache = new Map();
+  }
+  return cache;
+}
+
+function ensureDir(): void {
+  getQQBotDataDir("data");
+}
+
+function appendLine(line: RefIndexLine): void {
+  try {
+    ensureDir();
+    appendRegularFileSync({ filePath: getRefIndexFile(), content: JSON.stringify(line) + "\n" });
+    totalLinesOnDisk++;
+  } catch (err) {
+    debugError(`[ref-index-store] Failed to append: ${formatErrorMessage(err)}`);
+  }
+}
+
+function shouldCompact(): boolean {
+  return (
+    !!cache && totalLinesOnDisk > cache.size * COMPACT_THRESHOLD_RATIO && totalLinesOnDisk > 1000
+  );
+}
+
+function compactFile(): void {
+  if (!cache) {
+    return;
+  }
+  const before = totalLinesOnDisk;
+  try {
+    ensureDir();
+    const refIndexFile = getRefIndexFile();
+    const lines: string[] = [];
+    for (const [key, entry] of cache) {
+      lines.push(
+        JSON.stringify({
+          k: key,
+          v: {
+            content: entry.content,
+            senderId: entry.senderId,
+            senderName: entry.senderName,
+            timestamp: entry.timestamp,
+            isBot: entry.isBot,
+            attachments: entry.attachments,
+          },
+          t: entry.createdAt,
+        }),
+      );
+    }
+    replaceFileAtomicSync({
+      filePath: refIndexFile,
+      content: `${lines.join("\n")}\n`,
+      tempPrefix: ".qqbot-ref-index",
+    });
+    totalLinesOnDisk = cache.size;
+    debugLog(`[ref-index-store] Compacted: ${before} lines → ${totalLinesOnDisk} lines`);
+  } catch (err) {
+    debugError(`[ref-index-store] Compact failed: ${formatErrorMessage(err)}`);
+  }
+}
+
+function evictIfNeeded(): void {
+  if (!cache || cache.size < MAX_ENTRIES) {
+    return;
+  }
+  const now = Date.now();
+  for (const [key, entry] of cache) {
+    if (now - entry.createdAt > TTL_MS) {
+      cache.delete(key);
+    }
+  }
+  if (cache.size >= MAX_ENTRIES) {
+    const sorted = [...cache.entries()].toSorted((a, b) => a[1].createdAt - b[1].createdAt);
+    const toRemove = sorted.slice(0, cache.size - MAX_ENTRIES + 1000);
+    for (const [key] of toRemove) {
+      cache.delete(key);
+    }
+    debugLog(`[ref-index-store] Evicted ${toRemove.length} oldest entries`);
+  }
+}
+
+/** Persist a refIdx mapping for one message. */
+export function setRefIndex(refIdx: string, entry: RefIndexEntry): void {
+  const store = loadFromFile();
+  evictIfNeeded();
+  const now = Date.now();
+  store.set(refIdx, { ...entry, createdAt: now });
+  appendLine({
+    k: refIdx,
+    v: {
+      content: entry.content,
+      senderId: entry.senderId,
+      senderName: entry.senderName,
+      timestamp: entry.timestamp,
+      isBot: entry.isBot,
+      attachments: entry.attachments,
+    },
+    t: now,
+  });
+  if (shouldCompact()) {
+    compactFile();
+  }
+}
+
+/** Look up one quoted message by refIdx. */
+export function getRefIndex(refIdx: string): RefIndexEntry | null {
+  const store = loadFromFile();
+  const entry = store.get(refIdx);
+  if (!entry) {
+    return null;
+  }
+  if (Date.now() - entry.createdAt > TTL_MS) {
+    store.delete(refIdx);
+    return null;
+  }
+  return {
+    content: entry.content,
+    senderId: entry.senderId,
+    senderName: entry.senderName,
+    timestamp: entry.timestamp,
+    isBot: entry.isBot,
+    attachments: entry.attachments,
+  };
+}
+
+/** Compact the store before process exit when needed. */
+export function flushRefIndex(): void {
+  if (cache && shouldCompact()) {
+    compactFile();
+  }
+}

package/src/engine/ref/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Ref-index types shared between both plugin versions.
+ *
+ * These types define the structure of quoted-message metadata
+ * persisted by the ref-index store.
+ */
+
+/** Summary stored for one quoted message. */
+export interface RefIndexEntry {
+  content: string;
+  senderId: string;
+  senderName?: string;
+  timestamp: number;
+  isBot?: boolean;
+  attachments?: RefAttachmentSummary[];
+}
+
+/** Attachment summary persisted alongside a ref index entry. */
+export interface RefAttachmentSummary {
+  type: "image" | "voice" | "video" | "file" | "unknown";
+  filename?: string;
+  contentType?: string;
+  transcript?: string;
+  transcriptSource?: "stt" | "asr" | "tts" | "fallback";
+  localPath?: string;
+  url?: string;
+}

package/src/engine/session/known-users.ts

@@ -0,0 +1,138 @@
+/**
+ * Known user tracking — JSON file-based store.
+ *
+ * Migrated from src/known-users.ts. Dependencies are only Node.js
+ * built-ins + log + platform (both zero plugin-sdk).
+ */
+
+import path from "node:path";
+import { privateFileStoreSync } from "autobot/plugin-sdk/security-runtime";
+import type { ChatScope } from "../types.js";
+import { formatErrorMessage } from "../utils/format.js";
+import { debugLog, debugError } from "../utils/log.js";
+import { getQQBotDataDir, getQQBotDataPath } from "../utils/platform.js";
+
+/** Persisted record for a user who has interacted with the bot. */
+interface KnownUser {
+  openid: string;
+  type: ChatScope;
+  nickname?: string;
+  groupOpenid?: string;
+  accountId: string;
+  firstSeenAt: number;
+  lastSeenAt: number;
+  interactionCount: number;
+}
+
+let usersCache: Map<string, KnownUser> | null = null;
+const SAVE_THROTTLE_MS = 5000;
+let saveTimer: ReturnType<typeof setTimeout> | null = null;
+let isDirty = false;
+
+function ensureDir(): void {
+  getQQBotDataDir("data");
+}
+
+function getKnownUsersFile(): string {
+  return path.join(getQQBotDataPath("data"), "known-users.json");
+}
+
+function makeUserKey(user: Partial<KnownUser>): string {
+  const base = `${user.accountId}:${user.type}:${user.openid}`;
+  return user.type === "group" && user.groupOpenid ? `${base}:${user.groupOpenid}` : base;
+}
+
+function loadUsersFromFile(): Map<string, KnownUser> {
+  if (usersCache !== null) {
+    return usersCache;
+  }
+  usersCache = new Map();
+  try {
+    const knownUsersFile = getKnownUsersFile();
+    const users = privateFileStoreSync(path.dirname(knownUsersFile)).readJsonIfExists<KnownUser[]>(
+      path.basename(knownUsersFile),
+    );
+    if (users) {
+      for (const user of users) {
+        usersCache.set(makeUserKey(user), user);
+      }
+      debugLog(`[known-users] Loaded ${usersCache.size} users`);
+    }
+  } catch (err) {
+    debugError(`[known-users] Failed to load users: ${formatErrorMessage(err)}`);
+    usersCache = new Map();
+  }
+  return usersCache;
+}
+
+function saveUsersToFile(): void {
+  if (!isDirty || saveTimer) {
+    return;
+  }
+  saveTimer = setTimeout(() => {
+    saveTimer = null;
+    doSaveUsersToFile();
+  }, SAVE_THROTTLE_MS);
+}
+
+function doSaveUsersToFile(): void {
+  if (!usersCache || !isDirty) {
+    return;
+  }
+  try {
+    ensureDir();
+    const filePath = getKnownUsersFile();
+    privateFileStoreSync(path.dirname(filePath)).writeJson(
+      path.basename(filePath),
+      Array.from(usersCache.values()),
+    );
+    isDirty = false;
+  } catch (err) {
+    debugError(`[known-users] Failed to save users: ${formatErrorMessage(err)}`);
+  }
+}
+
+/** Flush pending writes immediately, typically during shutdown. */
+export function flushKnownUsers(): void {
+  if (saveTimer) {
+    clearTimeout(saveTimer);
+    saveTimer = null;
+  }
+  doSaveUsersToFile();
+}
+
+/** Record a known user whenever a message is received. */
+export function recordKnownUser(user: {
+  openid: string;
+  type: ChatScope;
+  nickname?: string;
+  groupOpenid?: string;
+  accountId: string;
+}): void {
+  const cache = loadUsersFromFile();
+  const key = makeUserKey(user);
+  const now = Date.now();
+  const existing = cache.get(key);
+
+  if (existing) {
+    existing.lastSeenAt = now;
+    existing.interactionCount++;
+    if (user.nickname && user.nickname !== existing.nickname) {
+      existing.nickname = user.nickname;
+    }
+  } else {
+    cache.set(key, {
+      openid: user.openid,
+      type: user.type,
+      nickname: user.nickname,
+      groupOpenid: user.groupOpenid,
+      accountId: user.accountId,
+      firstSeenAt: now,
+      lastSeenAt: now,
+      interactionCount: 1,
+    });
+    debugLog(`[known-users] New user: ${user.openid} (${user.type})`);
+  }
+  isDirty = true;
+  saveUsersToFile();
+}