@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.2

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

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

@@ -1,60 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { formatRefEntryForAgent } from "./format-ref-entry.js";
-import type { RefIndexEntry } from "./types.js";
-
-function makeEntry(overrides: Partial<RefIndexEntry> = {}): RefIndexEntry {
-  return {
-    content: "hello",
-    senderId: "user-1",
-    timestamp: 1,
-    ...overrides,
-  };
-}
-
-describe("engine/ref/format-ref-entry", () => {
-  it("formats text and attachment hints for model context", () => {
-    const formatted = formatRefEntryForAgent(
-      makeEntry({
-        content: "see these",
-        attachments: [
-          {
-            type: "image",
-            filename: "photo.png",
-            localPath: "/tmp/photo.png",
-          },
-          {
-            type: "voice",
-            transcript: "spoken words",
-            transcriptSource: "asr",
-            url: "https://example.test/voice.amr",
-          },
-          {
-            type: "file",
-            filename: "notes.txt",
-          },
-        ],
-      }),
-    );
-
-    expect(formatted).toBe(
-      'see these MEDIA:/tmp/photo.png MEDIA:https://example.test/voice.amr (transcript: "spoken words") [source: platform ASR] [file: notes.txt]',
-    );
-  });
-
-  it("keeps voice attachments visible when no transcript exists", () => {
-    expect(
-      formatRefEntryForAgent(
-        makeEntry({
-          content: "",
-          attachments: [{ type: "voice", localPath: "/tmp/voice.wav" }],
-        }),
-      ),
-    ).toBe("MEDIA:/tmp/voice.wav");
-  });
-
-  it("returns an explicit empty marker for blank entries", () => {
-    expect(formatRefEntryForAgent(makeEntry({ content: "  ", attachments: [] }))).toBe(
-      "[empty message]",
-    );
-  });
-});

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

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

@@ -1,208 +0,0 @@
-/**
- * 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 { 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();
-    fs.appendFileSync(getRefIndexFile(), JSON.stringify(line) + "\n", "utf-8");
-    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 tmpPath = refIndexFile + ".tmp";
-    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,
-        }),
-      );
-    }
-    fs.writeFileSync(tmpPath, lines.join("\n") + "\n", "utf-8");
-    fs.renameSync(tmpPath, refIndexFile);
-    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

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

@@ -1,137 +0,0 @@
-/**
- * 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 fs from "node:fs";
-import path from "node:path";
-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();
-    if (fs.existsSync(knownUsersFile)) {
-      const data = fs.readFileSync(knownUsersFile, "utf-8");
-      const users = JSON.parse(data) as KnownUser[];
-      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();
-    fs.writeFileSync(
-      getKnownUsersFile(),
-      JSON.stringify(Array.from(usersCache.values()), null, 2),
-      "utf-8",
-    );
-    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();
-}