@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

package/src/engine/group/history.ts

@@ -1,321 +0,0 @@
-/**
- * Group history cache — buffer non-@ messages and inject them as context
- * the next time the bot is @-ed in the same group.
- *
- * Lifecycle (per group):
- *   1. `recordPendingHistoryEntry` — called for every non-@ message that
- *      should be remembered (the gate returns `skip_no_mention` /
- *      `drop_other_mention`).
- *   2. `buildPendingHistoryContext` — called when the bot IS @-ed; wraps
- *      the cached entries in context tags and prepends them to the
- *      current user message.
- *   3. `clearPendingHistory` — called after the reply has been attempted
- *      (success, timeout, or error) so the next @ starts fresh.
- *
- * The cache itself is a simple `Map<groupOpenid, HistoryEntry[]>` with an
- * LRU eviction policy both on the number of keys and on the per-key
- * length. No I/O, no external dependencies — the module is pure and
- * portable between the built-in and standalone plugin builds.
- */
-
-import type { RefAttachmentSummary } from "../ref/types.js";
-import { formatAttachmentTags } from "../utils/attachment-tags.js";
-import { parseFaceTags } from "../utils/text-parsing.js";
-import { stripMentionText, type RawMention } from "./mention.js";
-
-// Re-export so existing `from "group/history.js"` imports keep working.
-export { formatAttachmentTags } from "../utils/attachment-tags.js";
-
-// ───────────────────────────── Constants ─────────────────────────────
-
-/**
- * Tags wrapping history injected on the bot's current turn.
- *
- * Kept in English so downstream LLMs (which are multilingual but follow
- * instructions more reliably in English) parse the block structure
- * unambiguously, regardless of the user/bot conversation language.
- */
-const HISTORY_CTX_START = "[Chat messages since your last reply — CONTEXT ONLY]";
-const HISTORY_CTX_END = "[CURRENT MESSAGE — reply to this]";
-
-/** Tags wrapping merged sub-messages from the queue. */
-const MERGED_CTX_START = "[Merged earlier messages — CONTEXT ONLY]";
-const MERGED_CTX_END = "[CURRENT MESSAGE — reply using the context above]";
-
-/**
- * Upper bound on the number of concurrent group histories the cache will
- * retain. Prevents the Map from growing without bound in long-running
- * multi-group deployments. LRU-evict the least-recently-touched key once
- * this limit is exceeded.
- */
-const MAX_HISTORY_KEYS = 1000;
-
-// ───────────────────────────── Types ─────────────────────────────
-
-/**
- * Attachment descriptor used inside history entries.
- *
- * Aligned with `RefAttachmentSummary` so the three places that describe
- * attachments (group history cache, ref-index store, and the dynamic
- * context block on the current message) all share a single shape.
- */
-type AttachmentSummary = RefAttachmentSummary;
-
-/** Raw attachment fields carried in a QQ event (the union we actually read). */
-interface RawAttachment {
-  content_type: string;
-  filename?: string;
-  /** Pre-computed ASR transcription text provided by QQ's gateway. */
-  asr_refer_text?: string;
-  url?: string;
-}
-
-/** One cached history entry. */
-export interface HistoryEntry {
-  /** Display label for the sender (e.g. "Nick (OPENID)"). */
-  sender: string;
-  /** Message body already stripped / formatted for the AI. */
-  body: string;
-  timestamp?: number;
-  messageId?: string;
-  /** Rich-media attachments to render inline on @-activation. */
-  attachments?: AttachmentSummary[];
-}
-
-/** Parameters for {@link formatMessageContent}. */
-interface FormatMessageContentParams {
-  content: string;
-  /** Message channel — `stripMentionText` only fires for `"group"`. */
-  chatType?: string;
-  mentions?: RawMention[];
-  attachments?: RawAttachment[];
-}
-
-// ───────────────────────────── Content formatting ─────────────────────────────
-
-/** Map a raw QQ content-type string onto the normalized attachment type. */
-export function inferAttachmentType(contentType?: string): AttachmentSummary["type"] {
-  const ct = (contentType ?? "").toLowerCase();
-  if (ct.startsWith("image/")) {
-    return "image";
-  }
-  if (ct === "voice" || ct.startsWith("audio/") || ct.includes("silk") || ct.includes("amr")) {
-    return "voice";
-  }
-  if (ct.startsWith("video/")) {
-    return "video";
-  }
-  if (ct.startsWith("application/") || ct.startsWith("text/")) {
-    return "file";
-  }
-  return "unknown";
-}
-
-/**
- * Convert raw QQ-event attachments into `AttachmentSummary` entries.
- *
- * When `localPaths` is provided (from `ProcessedAttachments.attachmentLocalPaths`),
- * each summary is enriched with the local file path so that history context
- * renders the downloaded path instead of the ephemeral QQ CDN URL.
- *
- * Returns `undefined` (rather than `[]`) when no attachments are provided
- * so that callers can omit the field from their result objects.
- */
-export function toAttachmentSummaries(
-  attachments?: RawAttachment[],
-  localPaths?: Array<string | null>,
-): AttachmentSummary[] | undefined {
-  if (!attachments?.length) {
-    return undefined;
-  }
-  return attachments.map(
-    (att, i): AttachmentSummary => ({
-      type: inferAttachmentType(att.content_type),
-      filename: att.filename,
-      transcript: att.asr_refer_text || undefined,
-      localPath: localPaths?.[i] || undefined,
-      url: att.url || undefined,
-    }),
-  );
-}
-
-/**
- * Format one sub-message: emoji parsing → mention cleanup → attachment tags.
- *
- * Used for the merged-message path where several queued messages are
- * rendered together. `parseFaceTags` and `stripMentionText` are imported
- * directly — both are pure utilities inside the same engine and do not
- * warrant DI overhead.
- */
-export function formatMessageContent(params: FormatMessageContentParams): string {
-  let msgContent = parseFaceTags(params.content);
-
-  if (params.chatType === "group" && params.mentions?.length) {
-    msgContent = stripMentionText(msgContent, params.mentions);
-  }
-
-  if (params.attachments?.length) {
-    const attachmentDesc = formatAttachmentTags(toAttachmentSummaries(params.attachments));
-    if (attachmentDesc) {
-      msgContent = `${msgContent} ${attachmentDesc}`;
-    }
-  }
-
-  return msgContent;
-}
-
-// ───────────────────────────── Attachment tags ─────────────────────────────
-//
-// `formatAttachmentTags` lives in `utils/attachment-tags.ts` (the single
-// source of truth shared with the ref-index renderer). It is re-exported
-// from the top of this file so existing `from "group/history.js"` imports
-// continue to work.
-
-// ───────────────────────────── Internal LRU helpers ─────────────────────────────
-
-/**
- * LRU-evict the least-recently-inserted keys so the map never exceeds
- * `maxKeys`. Since `Map` iteration order is insertion order, removing
- * from the front gives us an LRU by insertion point.
- */
-function evictOldHistoryKeys<T>(
-  historyMap: Map<string, T[]>,
-  maxKeys: number = MAX_HISTORY_KEYS,
-): void {
-  if (historyMap.size <= maxKeys) {
-    return;
-  }
-  const keysToDelete = historyMap.size - maxKeys;
-  const iterator = historyMap.keys();
-  for (let i = 0; i < keysToDelete; i++) {
-    const key = iterator.next().value;
-    if (key !== undefined) {
-      historyMap.delete(key);
-    }
-  }
-}
-
-/**
- * Append one entry to a group's history. When the group's buffer exceeds
- * `limit`, the oldest entry is shifted off the front. The group's key is
- * re-inserted into the map so its LRU position is refreshed.
- */
-function appendHistoryEntry(params: {
-  historyMap: Map<string, HistoryEntry[]>;
-  historyKey: string;
-  entry: HistoryEntry;
-  limit: number;
-}): HistoryEntry[] {
-  const { historyMap, historyKey, entry, limit } = params;
-  if (limit <= 0) {
-    return [];
-  }
-
-  const history = historyMap.get(historyKey) ?? [];
-  history.push(entry);
-  while (history.length > limit) {
-    history.shift();
-  }
-  // Refresh insertion order so this key becomes the most recent.
-  if (historyMap.has(historyKey)) {
-    historyMap.delete(historyKey);
-  }
-  historyMap.set(historyKey, history);
-  evictOldHistoryKeys(historyMap);
-  return history;
-}
-
-// ───────────────────────────── Public API ─────────────────────────────
-
-/**
- * Record a non-@ message so it can be replayed on the next @-activation.
- *
- * No-op when `limit <= 0` (history disabled) or when `entry` is missing.
- * Returns the updated history list for the group.
- */
-export function recordPendingHistoryEntry(params: {
-  historyMap: Map<string, HistoryEntry[]>;
-  historyKey: string;
-  entry?: HistoryEntry | null;
-  limit: number;
-}): HistoryEntry[] {
-  if (!params.entry || params.limit <= 0) {
-    return [];
-  }
-  return appendHistoryEntry({
-    historyMap: params.historyMap,
-    historyKey: params.historyKey,
-    entry: params.entry,
-    limit: params.limit,
-  });
-}
-
-/**
- * Build the full user-message string when the bot is @-ed, prefixing the
- * buffered non-@ chatter for context.
- *
- * Returns `currentMessage` unchanged when no history exists, when the
- * limit is zero, or when the buffer is empty.
- */
-export function buildPendingHistoryContext(params: {
-  historyMap: Map<string, HistoryEntry[]>;
-  historyKey: string;
-  limit: number;
-  currentMessage: string;
-  formatEntry: (entry: HistoryEntry) => string;
-  lineBreak?: string;
-}): string {
-  if (params.limit <= 0) {
-    return params.currentMessage;
-  }
-
-  const entries = params.historyMap.get(params.historyKey) ?? [];
-  if (entries.length === 0) {
-    return params.currentMessage;
-  }
-
-  const lineBreak = params.lineBreak ?? "\n";
-  const historyText = entries.map(params.formatEntry).join(lineBreak);
-
-  return [HISTORY_CTX_START, historyText, "", HISTORY_CTX_END, params.currentMessage].join(
-    lineBreak,
-  );
-}
-
-/**
- * Wrap a batch of merged messages with begin/end tags and append the
- * current user turn at the bottom.
- *
- * When `precedingParts` is empty, `currentMessage` is returned unchanged.
- */
-export function buildMergedMessageContext(params: {
-  precedingParts: string[];
-  currentMessage: string;
-  lineBreak?: string;
-}): string {
-  const { precedingParts, currentMessage } = params;
-  if (precedingParts.length === 0) {
-    return currentMessage;
-  }
-
-  const lineBreak = params.lineBreak ?? "\n";
-  return [MERGED_CTX_START, precedingParts.join(lineBreak), MERGED_CTX_END, currentMessage].join(
-    lineBreak,
-  );
-}
-
-/**
- * Clear a group's pending history after a reply has been attempted.
- *
- * No-op when the feature is disabled (`limit <= 0`).
- */
-export function clearPendingHistory(params: {
-  historyMap: Map<string, HistoryEntry[]>;
-  historyKey: string;
-  limit: number;
-}): void {
-  if (params.limit <= 0) {
-    return;
-  }
-  params.historyMap.set(params.historyKey, []);
-}

package/src/engine/group/mention.test.ts

@@ -1,141 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  detectWasMentioned,
-  hasAnyMention,
-  resolveImplicitMention,
-  stripMentionText,
-} from "./mention.js";
-
-describe("engine/group/mention", () => {
-  describe("detectWasMentioned", () => {
-    it("returns true when mentions contains is_you", () => {
-      expect(detectWasMentioned({ mentions: [{ is_you: true }] })).toBe(true);
-    });
-
-    it("returns true for GROUP_AT_MESSAGE_CREATE even without mentions", () => {
-      expect(detectWasMentioned({ eventType: "GROUP_AT_MESSAGE_CREATE" })).toBe(true);
-    });
-
-    it("matches by mentionPatterns regex", () => {
-      expect(
-        detectWasMentioned({ content: "@xiaoke help me", mentionPatterns: ["^@xiaoke"] }),
-      ).toBe(true);
-    });
-
-    it("returns false when no signal matches", () => {
-      expect(
-        detectWasMentioned({
-          eventType: "GROUP_MESSAGE_CREATE",
-          mentions: [{ member_openid: "USER1" }],
-          content: "hello",
-          mentionPatterns: ["^@bot"],
-        }),
-      ).toBe(false);
-    });
-
-    it("ignores invalid regex patterns gracefully", () => {
-      // "[" is an invalid regex; should not throw.
-      expect(detectWasMentioned({ content: "hi", mentionPatterns: ["[", "@bot"] })).toBe(false);
-    });
-
-    it("matches case-insensitively", () => {
-      expect(detectWasMentioned({ content: "Hello @Bot", mentionPatterns: ["@bot"] })).toBe(true);
-    });
-
-    it("skips empty patterns", () => {
-      expect(detectWasMentioned({ content: "hi", mentionPatterns: ["", "  "] })).toBe(false);
-    });
-
-    it("returns false when everything is empty", () => {
-      expect(detectWasMentioned({})).toBe(false);
-    });
-  });
-
-  describe("hasAnyMention", () => {
-    it("detects mentions array", () => {
-      expect(hasAnyMention({ mentions: [{ member_openid: "X" }] })).toBe(true);
-    });
-
-    it("detects mention tags in text", () => {
-      expect(hasAnyMention({ content: "hi <@ABC123>" })).toBe(true);
-      expect(hasAnyMention({ content: "hi <@!ABC123>" })).toBe(true);
-    });
-
-    it("returns false when nothing mentioned", () => {
-      expect(hasAnyMention({ content: "just a normal message" })).toBe(false);
-      expect(hasAnyMention({})).toBe(false);
-    });
-  });
-
-  describe("stripMentionText", () => {
-    it("removes self-mention tag", () => {
-      expect(stripMentionText("<@BOTID> hello", [{ member_openid: "BOTID", is_you: true }])).toBe(
-        "hello",
-      );
-    });
-
-    it("replaces other-user tag with @nickname", () => {
-      expect(stripMentionText("hi <@USER1>", [{ member_openid: "USER1", nickname: "Alice" }])).toBe(
-        "hi @Alice",
-      );
-    });
-
-    it("falls back to username when nickname missing", () => {
-      expect(stripMentionText("hi <@USER1>", [{ member_openid: "USER1", username: "alice" }])).toBe(
-        "hi @alice",
-      );
-    });
-
-    it("leaves unknown mentions untouched", () => {
-      // No display name, so the tag cannot be prettified — keep raw.
-      expect(stripMentionText("hi <@USER1>", [{ member_openid: "USER1" }])).toBe("hi <@USER1>");
-    });
-
-    it("handles <@!openid> variant", () => {
-      expect(stripMentionText("hi <@!USER1>", [{ member_openid: "USER1", nickname: "A" }])).toBe(
-        "hi @A",
-      );
-    });
-
-    it("returns the original text when no mentions array is provided", () => {
-      expect(stripMentionText("hi <@X>", [])).toBe("hi <@X>");
-      expect(stripMentionText("hi <@X>")).toBe("hi <@X>");
-    });
-
-    it("escapes regex meta-characters in openid", () => {
-      // Defensive: even if QQ ever sends openids with unusual characters,
-      // the function should not explode nor produce a bogus regex.
-      expect(stripMentionText("see <@A.B+C>", [{ member_openid: "A.B+C", nickname: "X" }])).toBe(
-        "see @X",
-      );
-    });
-  });
-
-  describe("resolveImplicitMention", () => {
-    it("returns false when refMsgIdx is missing", () => {
-      expect(resolveImplicitMention({ getRefEntry: () => null })).toBe(false);
-    });
-
-    it("returns true when the referenced entry is a bot message", () => {
-      expect(
-        resolveImplicitMention({
-          refMsgIdx: "R1",
-          getRefEntry: (id) => (id === "R1" ? { isBot: true } : null),
-        }),
-      ).toBe(true);
-    });
-
-    it("returns false when ref entry exists but is not a bot", () => {
-      expect(
-        resolveImplicitMention({
-          refMsgIdx: "R1",
-          getRefEntry: () => ({ isBot: false }),
-        }),
-      ).toBe(false);
-    });
-
-    it("returns false when ref entry is missing", () => {
-      expect(resolveImplicitMention({ refMsgIdx: "R1", getRefEntry: () => null })).toBe(false);
-    });
-  });
-});

package/src/engine/group/mention.ts

@@ -1,197 +0,0 @@
-/**
- * QQBot group @mention detection and text normalization.
- *
- * Pure functions extracted from the standalone build (`openclaw-qqbot/src/
- * channel.ts::detectWasMentioned` / `stripMentionText`) plus the helper
- * `hasAnyMention` that previously lived inline in `gateway.ts` and the
- * `resolveImplicitMention` predicate that decides whether a quoted-reply
- * should count as an implicit @bot.
- *
- * Keeping these helpers together makes it easier to test the group gating
- * pipeline and lets both the built-in and standalone builds share a
- * single mention-detection implementation.
- */
-
-// ============ Types ============
-
-/**
- * Raw mention entry shape used across QQ Bot group events.
- *
- * QQ's `mentions` array uses slightly different field names on different
- * event types (the bot's self-mention comes as `is_you: true`; user IDs
- * can appear in any of `member_openid` / `id` / `user_openid`). This type
- * captures the union so callers don't have to worry about which variant.
- */
-export interface RawMention {
-  /** Whether this mention targets the bot itself. */
-  is_you?: boolean;
-  /** Whether the mention target is another bot. */
-  bot?: boolean;
-  /** Member openid in group chats. */
-  member_openid?: string;
-  /** Event-level id (guild context). */
-  id?: string;
-  /** User openid (C2C context). */
-  user_openid?: string;
-  /** Display name. */
-  nickname?: string;
-  /** Alternative display name. */
-  username?: string;
-  /** @all / @single scope (QQ guild events). */
-  scope?: "all" | "single";
-}
-
-/** Input for {@link detectWasMentioned}. */
-interface DetectWasMentionedInput {
-  /**
-   * Raw event type. `"GROUP_AT_MESSAGE_CREATE"` unambiguously identifies
-   * that the bot was @-ed, even when the mentions array is empty.
-   */
-  eventType?: string;
-  mentions?: RawMention[];
-  /** Raw message content — used as a regex fallback via `mentionPatterns`. */
-  content?: string;
-  /**
-   * Regex patterns matched against `content` when neither `mentions.is_you`
-   * nor `eventType` prove a bot mention. Invalid patterns are ignored.
-   */
-  mentionPatterns?: string[];
-}
-
-/** Input for {@link hasAnyMention}. */
-interface HasAnyMentionInput {
-  mentions?: RawMention[];
-  content?: string;
-}
-
-// ============ Constants ============
-
-/** Regex detecting `<@openid>` / `<@!openid>` mention tags in raw content. */
-const MENTION_TAG_RE = /<@!?\w+>/;
-
-// ============ Public API ============
-
-/**
- * Detect whether the inbound message explicitly targets the bot.
- *
- * Priority order:
- *   1. `mentions[].is_you === true`           (most reliable)
- *   2. `eventType === "GROUP_AT_MESSAGE_CREATE"` (QQ-level @bot event)
- *   3. regex match on any of `mentionPatterns` (fallback, e.g. "@bot-name")
- *
- * Returns `false` for direct messages or when no signal is found.
- */
-export function detectWasMentioned(input: DetectWasMentionedInput): boolean {
-  const { eventType, mentions, content, mentionPatterns } = input;
-
-  if (mentions?.some((m) => m.is_you)) {
-    return true;
-  }
-
-  if (eventType === "GROUP_AT_MESSAGE_CREATE") {
-    return true;
-  }
-
-  if (mentionPatterns?.length && content) {
-    for (const pattern of mentionPatterns) {
-      if (!pattern) {
-        continue;
-      }
-      try {
-        if (new RegExp(pattern, "i").test(content)) {
-          return true;
-        }
-      } catch {
-        // Invalid regex — skip silently; bad patterns must not crash the pipeline.
-      }
-    }
-  }
-
-  return false;
-}
-
-/**
- * Report whether the message contains **any** @mention (not necessarily @bot).
- *
- * Used by the gating layer to decide whether to bypass mention requirements
- * for control commands. A control command like `/stop` that also @-s another
- * user should NOT bypass the mention gate — the `@other-user` prefix is a
- * strong signal that the command wasn't addressed to the bot.
- */
-export function hasAnyMention(input: HasAnyMentionInput): boolean {
-  if (input.mentions && input.mentions.length > 0) {
-    return true;
-  }
-  if (input.content && MENTION_TAG_RE.test(input.content)) {
-    return true;
-  }
-  return false;
-}
-
-/**
- * Clean up `<@openid>` mention tags in raw QQ group content.
- *
- * - For the bot's own mention (`is_you === true`): the tag is removed
- *   outright so prompts don't contain visible `<@BOTID>` garbage.
- * - For other mentioned users: the tag is replaced with `@nickname` (or
- *   `@username`) for readability. Entries without a display name are left
- *   as-is (rare in practice).
- *
- * Returns the original text unchanged when `text` or `mentions` is empty.
- */
-export function stripMentionText(text: string, mentions?: RawMention[]): string {
-  if (!text || !mentions?.length) {
-    return text;
-  }
-  let cleaned = text;
-  for (const m of mentions) {
-    const openid = m.member_openid ?? m.id ?? m.user_openid;
-    if (!openid) {
-      continue;
-    }
-    // RegExp: match both `<@openid>` and `<@!openid>` variants.
-    const tagRe = new RegExp(`<@!?${escapeRegex(openid)}>`, "g");
-    if (m.is_you) {
-      cleaned = cleaned.replace(tagRe, "").trim();
-    } else {
-      const displayName = m.nickname ?? m.username;
-      if (displayName) {
-        cleaned = cleaned.replace(tagRe, `@${displayName}`);
-      }
-    }
-  }
-  return cleaned;
-}
-
-// ============ Internal helpers ============
-
-/** Escape characters that carry regex meaning. */
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-// ============ Implicit mention (quoted bot message) ============
-
-/**
- * Decide whether a quoted-reply should count as an implicit @bot.
- *
- * When the user quotes an earlier bot message, we treat the new message
- * as if it @-ed the bot, even without a literal mention. This lives in
- * the mention module (rather than with activation) because semantically
- * it answers the same question as `detectWasMentioned`:
- * "was the bot addressed by this message?".
- *
- * The `getRefEntry` callback is injected so this function does not
- * depend on the ref-index store implementation — any lookup that
- * returns `{ isBot?: boolean }` works.
- */
-export function resolveImplicitMention(params: {
-  refMsgIdx?: string;
-  getRefEntry: (idx: string) => { isBot?: boolean } | null;
-}): boolean {
-  if (!params.refMsgIdx) {
-    return false;
-  }
-  const refEntry = params.getRefEntry(params.refMsgIdx);
-  return refEntry?.isBot === true;
-}