@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

package/src/engine/gateway/stages/envelope-stage.test.ts

@@ -1,152 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { GroupMessageGateResult } from "../../group/message-gating.js";
-import type { ProcessedAttachments } from "../inbound-attachments.js";
-import type { InboundGroupInfo } from "../inbound-context.js";
-import {
-  buildDynamicCtx,
-  buildGroupSystemPrompt,
-  buildQuotePart,
-  classifyMedia,
-} from "./envelope-stage.js";
-
-function makeGate(): GroupMessageGateResult {
-  return { action: "pass", effectiveWasMentioned: true, shouldBypassMention: false };
-}
-
-function makeGroupInfo(partial: Partial<InboundGroupInfo["display"]> = {}): InboundGroupInfo {
-  return {
-    gate: makeGate(),
-    activation: "mention",
-    historyLimit: 50,
-    isMerged: false,
-    display: {
-      groupName: "G",
-      senderLabel: "S",
-      ...partial,
-    },
-  };
-}
-
-describe("envelope-stage", () => {
-  describe("buildQuotePart", () => {
-    it("returns empty string when no replyTo", () => {
-      expect(buildQuotePart(undefined)).toBe("");
-    });
-
-    it("wraps a quoted body in begin/end tags", () => {
-      const out = buildQuotePart({ id: "R1", body: "hello", isQuote: true });
-      expect(out).toContain("[Quoted message begins]");
-      expect(out).toContain("hello");
-      expect(out).toContain("[Quoted message ends]");
-    });
-
-    it("uses a fallback line when body is missing", () => {
-      const out = buildQuotePart({ id: "R1", isQuote: true });
-      expect(out).toContain("Original content unavailable");
-    });
-  });
-
-  describe("buildDynamicCtx", () => {
-    it("returns empty string when every list is empty", () => {
-      expect(
-        buildDynamicCtx({
-          imageUrls: [],
-          uniqueVoicePaths: [],
-          uniqueVoiceUrls: [],
-          uniqueVoiceAsrReferTexts: [],
-        }),
-      ).toBe("");
-    });
-
-    it("renders images / voice / asr when present", () => {
-      const out = buildDynamicCtx({
-        imageUrls: ["https://x/a.png", "https://x/b.png"],
-        uniqueVoicePaths: ["/tmp/v.wav"],
-        uniqueVoiceUrls: ["https://x/v.wav"],
-        uniqueVoiceAsrReferTexts: ["hi", "there"],
-      });
-      expect(out).toContain("- Images: https://x/a.png, https://x/b.png");
-      expect(out).toContain("- Voice: /tmp/v.wav, https://x/v.wav");
-      expect(out).toContain("- ASR: hi | there");
-      // Trailing blank line.
-      expect(out.endsWith("\n\n")).toBe(true);
-    });
-  });
-
-  describe("buildGroupSystemPrompt", () => {
-    it("returns undefined when no prompts exist", () => {
-      expect(buildGroupSystemPrompt("", undefined)).toBeUndefined();
-    });
-
-    it("joins accountSystemInstruction + introHint + behaviorPrompt", () => {
-      const out = buildGroupSystemPrompt(
-        "ACCOUNT",
-        makeGroupInfo({ introHint: "INTRO", behaviorPrompt: "BEHAVIOR" }),
-      );
-      expect(out).toBe("ACCOUNT\nINTRO\nBEHAVIOR");
-    });
-
-    it("skips undefined parts cleanly", () => {
-      const out = buildGroupSystemPrompt("", makeGroupInfo({ behaviorPrompt: "B" }));
-      expect(out).toBe("B");
-    });
-  });
-
-  describe("classifyMedia", () => {
-    const emptyProcessed: ProcessedAttachments = {
-      attachmentInfo: "",
-      imageUrls: [],
-      imageMediaTypes: [],
-      voiceAttachmentPaths: [],
-      voiceAttachmentUrls: [],
-      voiceAsrReferTexts: [],
-      voiceTranscripts: [],
-      voiceTranscriptSources: [],
-      attachmentLocalPaths: [],
-    };
-
-    it("separates local from remote image URLs", () => {
-      const out = classifyMedia({
-        ...emptyProcessed,
-        imageUrls: ["/tmp/a.png", "https://x/b.png", "http://x/c.png"],
-        imageMediaTypes: ["image/png", "image/jpeg", "image/gif"],
-      });
-      expect(out.localMediaPaths).toEqual(["/tmp/a.png"]);
-      expect(out.remoteMediaUrls).toEqual(["https://x/b.png", "http://x/c.png"]);
-      expect(out.remoteMediaTypes).toEqual(["image/jpeg", "image/gif"]);
-    });
-
-    it("defaults missing media type to image/png", () => {
-      // When `imageMediaTypes[i]` is undefined (shorter than imageUrls),
-      // the classifier substitutes a default.
-      const out = classifyMedia({
-        ...emptyProcessed,
-        imageUrls: ["https://x/a.png"],
-        imageMediaTypes: [],
-      });
-      expect(out.remoteMediaTypes).toEqual(["image/png"]);
-    });
-
-    it("dedupes voice paths and URLs", () => {
-      const out = classifyMedia({
-        ...emptyProcessed,
-        voiceAttachmentPaths: ["/a", "/a", "/b"],
-        voiceAttachmentUrls: ["u1", "u1"],
-        voiceAsrReferTexts: ["x", "", "x"],
-      });
-      expect(out.uniqueVoicePaths).toEqual(["/a", "/b"]);
-      expect(out.uniqueVoiceUrls).toEqual(["u1"]);
-      expect(out.uniqueVoiceAsrReferTexts).toEqual(["x"]);
-    });
-
-    it("flags ASR fallback when transcriptSources contains 'asr'", () => {
-      expect(
-        classifyMedia({ ...emptyProcessed, voiceTranscriptSources: ["stt", "asr"] })
-          .hasAsrReferFallback,
-      ).toBe(true);
-      expect(
-        classifyMedia({ ...emptyProcessed, voiceTranscriptSources: ["stt"] }).hasAsrReferFallback,
-      ).toBe(false);
-    });
-  });
-});

package/src/engine/gateway/stages/envelope-stage.ts

@@ -1,144 +0,0 @@
-/**
- * Envelope stage — render the Web UI body, the dynamic-context block,
- * the final group system prompt, and the media classification arrays.
- *
- * All logic here is presentation-layer glue: it combines fields built by
- * earlier stages into the display-friendly strings the outbound
- * dispatcher needs. No decisions / gating.
- */
-
-import type { ProcessedAttachments } from "../inbound-attachments.js";
-import type { InboundGroupInfo, InboundPipelineDeps, ReplyToInfo } from "../inbound-context.js";
-import type { QueuedMessage } from "../message-queue.js";
-
-// ─────────────────────────── Envelope body ───────────────────────────
-
-interface BuildBodyInput {
-  event: QueuedMessage;
-  deps: InboundPipelineDeps;
-  userContent: string;
-  isGroupChat: boolean;
-  imageUrls: string[];
-}
-
-/** Format the inbound envelope (Web UI body). */
-export function buildBody(input: BuildBodyInput): string {
-  const { event, deps, userContent, isGroupChat, imageUrls } = input;
-  const envelopeOptions = deps.runtime.channel.reply.resolveEnvelopeFormatOptions(deps.cfg);
-  return deps.runtime.channel.reply.formatInboundEnvelope({
-    channel: "qqbot",
-    from: event.senderName ?? event.senderId,
-    timestamp: new Date(event.timestamp).getTime(),
-    body: userContent,
-    chatType: isGroupChat ? "group" : "direct",
-    sender: { id: event.senderId, name: event.senderName },
-    envelope: envelopeOptions,
-    ...(imageUrls.length > 0 ? { imageUrls } : {}),
-  });
-}
-
-// ─────────────────────────── Quote / dynamic ctx ───────────────────────────
-
-/** Render the `[Quoted message begins]...[ends]` block (empty if no reply-to). */
-export function buildQuotePart(replyTo?: ReplyToInfo): string {
-  if (!replyTo) {
-    return "";
-  }
-  return replyTo.body
-    ? `[Quoted message begins]\n${replyTo.body}\n[Quoted message ends]\n`
-    : `[Quoted message begins]\nOriginal content unavailable\n[Quoted message ends]\n`;
-}
-
-interface BuildDynamicCtxInput {
-  imageUrls: string[];
-  uniqueVoicePaths: string[];
-  uniqueVoiceUrls: string[];
-  uniqueVoiceAsrReferTexts: string[];
-}
-
-/** Render the per-message dynamic metadata block (images / voice / ASR). */
-export function buildDynamicCtx(input: BuildDynamicCtxInput): string {
-  const lines: string[] = [];
-  if (input.imageUrls.length > 0) {
-    lines.push(`- Images: ${input.imageUrls.join(", ")}`);
-  }
-  if (input.uniqueVoicePaths.length > 0 || input.uniqueVoiceUrls.length > 0) {
-    lines.push(`- Voice: ${[...input.uniqueVoicePaths, ...input.uniqueVoiceUrls].join(", ")}`);
-  }
-  if (input.uniqueVoiceAsrReferTexts.length > 0) {
-    lines.push(`- ASR: ${input.uniqueVoiceAsrReferTexts.join(" | ")}`);
-  }
-  return lines.length > 0 ? lines.join("\n") + "\n\n" : "";
-}
-
-// ─────────────────────────── System prompt ───────────────────────────
-
-/** Combine account-level system prompt with group-specific prompts. */
-export function buildGroupSystemPrompt(
-  accountSystemInstruction: string,
-  groupInfo: InboundGroupInfo | undefined,
-): string | undefined {
-  const parts: string[] = [];
-  if (accountSystemInstruction) {
-    parts.push(accountSystemInstruction);
-  }
-  if (groupInfo?.display.introHint) {
-    parts.push(groupInfo.display.introHint);
-  }
-  if (groupInfo?.display.behaviorPrompt) {
-    parts.push(groupInfo.display.behaviorPrompt);
-  }
-  const combined = parts.filter(Boolean).join("\n");
-  return combined || undefined;
-}
-
-// ─────────────────────────── Media classification ───────────────────────────
-
-interface MediaClassification {
-  localMediaPaths: string[];
-  localMediaTypes: string[];
-  remoteMediaUrls: string[];
-  remoteMediaTypes: string[];
-  uniqueVoicePaths: string[];
-  uniqueVoiceUrls: string[];
-  uniqueVoiceAsrReferTexts: string[];
-  voiceMediaTypes: string[];
-  hasAsrReferFallback: boolean;
-  voiceTranscriptSources: string[];
-}
-
-/** Classify image URLs into local vs remote and de-duplicate voice arrays. */
-export function classifyMedia(processed: ProcessedAttachments): MediaClassification {
-  const localMediaPaths: string[] = [];
-  const localMediaTypes: string[] = [];
-  const remoteMediaUrls: string[] = [];
-  const remoteMediaTypes: string[] = [];
-  for (let i = 0; i < processed.imageUrls.length; i++) {
-    const u = processed.imageUrls[i];
-    const t = processed.imageMediaTypes[i] ?? "image/png";
-    if (u.startsWith("http://") || u.startsWith("https://")) {
-      remoteMediaUrls.push(u);
-      remoteMediaTypes.push(t);
-    } else {
-      localMediaPaths.push(u);
-      localMediaTypes.push(t);
-    }
-  }
-
-  const uniqueVoicePaths = [...new Set(processed.voiceAttachmentPaths)];
-  const uniqueVoiceUrls = [...new Set(processed.voiceAttachmentUrls)];
-  const voiceMediaTypes = [...uniqueVoicePaths, ...uniqueVoiceUrls].map(() => "audio/wav");
-
-  return {
-    localMediaPaths,
-    localMediaTypes,
-    remoteMediaUrls,
-    remoteMediaTypes,
-    uniqueVoicePaths,
-    uniqueVoiceUrls,
-    uniqueVoiceAsrReferTexts: [...new Set(processed.voiceAsrReferTexts)].filter(Boolean),
-    voiceMediaTypes,
-    hasAsrReferFallback: processed.voiceTranscriptSources.includes("asr"),
-    voiceTranscriptSources: processed.voiceTranscriptSources,
-  };
-}

package/src/engine/gateway/stages/group-gate-stage.ts

@@ -1,292 +0,0 @@
-/**
- * Group-gate stage — for `type === "group"` inbound events, decide
- * whether the message should pass to AI dispatch or be intercepted.
- *
- * Three possible outcomes:
- *   - `{ kind: "pass", groupInfo }` — continue the pipeline
- *   - `{ kind: "skip", groupInfo, skipReason }` — buffered to history
- *     (if applicable) and short-circuit
- *   - No group info at all — returned when the event isn't a group event
- *     (caller should treat as a straight pass-through)
- *
- * Consolidates the control-command auth check, session-store
- * activation override, mention detection, and the unified
- * {@link resolveGroupMessageGate} call. Delegates all pure logic to
- * existing `engine/group/*` modules so this stage remains a thin
- * orchestrator.
- */
-
-import { createQQBotSenderMatcher, normalizeQQBotAllowFrom } from "../../access/index.js";
-import { DEFAULT_GROUP_PROMPT, resolveGroupSettings } from "../../config/group.js";
-import { resolveGroupActivation } from "../../group/activation.js";
-import { toAttachmentSummaries, type HistoryEntry } from "../../group/history.js";
-import { detectWasMentioned, hasAnyMention, resolveImplicitMention } from "../../group/mention.js";
-import { getRefIndex } from "../../ref/store.js";
-import type { InboundGroupInfo, InboundPipelineDeps } from "../inbound-context.js";
-import { isMergedTurn, type QueuedMessage } from "../message-queue.js";
-
-// ─────────────────────────── Types ───────────────────────────
-
-interface GroupGatePass {
-  kind: "pass";
-  groupInfo: InboundGroupInfo;
-}
-
-interface GroupGateSkip {
-  kind: "skip";
-  groupInfo: InboundGroupInfo;
-  skipReason: NonNullable<import("../inbound-context.js").InboundContext["skipReason"]>;
-}
-
-type GroupGateStageResult = GroupGatePass | GroupGateSkip;
-
-interface GroupGateStageInput {
-  event: QueuedMessage;
-  deps: InboundPipelineDeps;
-  accountId: string;
-  agentId?: string;
-  sessionKey: string;
-  /** User-visible content (post-emoji-parse, post-mention-strip). */
-  userContent: string;
-  /** Already-processed attachments (downloaded). Available for history recording. */
-  processedAttachments?: import("../inbound-attachments.js").ProcessedAttachments;
-}
-
-// ─────────────────────────── Stage ───────────────────────────
-
-/**
- * Run the group-gate stage.
- *
- * Precondition: `event.type === "group"` && `event.groupOpenid` is set.
- * The caller (pipeline) enforces this; the stage doesn't re-check.
- *
- * On `skip` outcomes the stage records the message into the group's
- * history buffer when the skip reason is one that should preserve
- * context (drop / skip_no_mention), then returns. `block` skip
- * reasons do NOT write history — they are silent rejects.
- */
-export function runGroupGateStage(input: GroupGateStageInput): GroupGateStageResult {
-  const { event, deps, accountId, agentId, sessionKey, userContent, processedAttachments } = input;
-  const groupOpenid = event.groupOpenid!;
-  const cfg = (deps.cfg ?? {}) as Record<string, unknown>;
-
-  // ---- 1. One-pass config resolution ----
-  const settings = resolveGroupSettings({ cfg, groupOpenid, accountId, agentId });
-  const { historyLimit, requireMention, ignoreOtherMentions } = settings.config;
-  const behaviorPrompt = settings.config.prompt ?? DEFAULT_GROUP_PROMPT;
-  const groupName = settings.name;
-
-  // ---- 2. Mention detection (QQ-specific) ----
-  const explicitWasMentioned = detectWasMentioned({
-    eventType: event.eventType,
-    mentions: event.mentions as never,
-    content: event.content,
-    mentionPatterns: settings.mentionPatterns,
-  });
-  const anyMention = hasAnyMention({
-    mentions: event.mentions as never,
-    content: event.content,
-  });
-  const implicitMention = resolveImplicitMention({
-    refMsgIdx: event.refMsgIdx,
-    getRefEntry: (idx) => getRefIndex(idx) ?? null,
-  });
-
-  // ---- 3. Activation mode (session store > cfg) ----
-  const activation = resolveGroupActivation({
-    cfg,
-    agentId: agentId ?? "default",
-    sessionKey,
-    configRequireMention: requireMention,
-    sessionStoreReader: deps.sessionStoreReader,
-  });
-
-  // ---- 4. Command authorization (for bypass) ----
-  const content = (event.content ?? "").trim();
-  const isControlCommand = Boolean(deps.isControlCommand?.(content));
-  const commandAuthorized =
-    deps.allowTextCommands !== false && isSenderAllowedForCommands(event.senderId, deps);
-
-  // ---- 5. Gate evaluation ----
-  // Layer 1 (ignoreOtherMentions) is QQ-specific and handled by
-  // resolveGateWithPort. Layers 2+3 delegate to the SDK adapter.
-  const gate = resolveGateWithPort({
-    mentionGatePort: deps.adapters.mentionGate,
-    ignoreOtherMentions,
-    hasAnyMention: anyMention,
-    wasMentioned: explicitWasMentioned,
-    implicitMention,
-    allowTextCommands: deps.allowTextCommands !== false,
-    isControlCommand,
-    commandAuthorized,
-    requireMention: activation === "mention",
-  });
-
-  // ---- 6. Build InboundGroupInfo (shared by pass / skip paths) ----
-  const introHint = deps.resolveGroupIntroHint?.({
-    cfg,
-    accountId,
-    groupId: groupOpenid,
-  });
-  const senderLabel = event.senderName ? `${event.senderName} (${event.senderId})` : event.senderId;
-
-  const groupInfo: InboundGroupInfo = {
-    gate,
-    activation,
-    historyLimit,
-    isMerged: isMergedTurn(event),
-    mergedMessages: event.merge?.messages,
-    display: {
-      groupName,
-      senderLabel,
-      introHint,
-      behaviorPrompt,
-    },
-  };
-
-  // ---- 7. Decide pass vs skip ----
-  if (gate.action === "pass") {
-    return { kind: "pass", groupInfo };
-  }
-
-  // Skip path: record history for drop / skip_no_mention, silent for block.
-  if (gate.action === "drop_other_mention" || gate.action === "skip_no_mention") {
-    recordGroupHistory({
-      historyMap: deps.groupHistories,
-      groupOpenid,
-      historyLimit,
-      event,
-      userContent,
-      historyPort: deps.adapters.history,
-      localPaths: processedAttachments?.attachmentLocalPaths,
-    });
-  }
-
-  return { kind: "skip", groupInfo, skipReason: gate.action };
-}
-
-// ─────────────────────────── Internal helpers ───────────────────────────
-
-import type { HistoryPort } from "../../adapter/history.port.js";
-import type { MentionGatePort } from "../../adapter/mention-gate.port.js";
-import type { GroupMessageGateResult } from "../../group/message-gating.js";
-
-/**
- * Resolve the gate using the SDK MentionGatePort adapter.
- *
- * Layer 1 (ignoreOtherMentions) is QQ-specific and handled here.
- * Layers 2+3 delegate to the SDK's `resolveInboundMentionDecision`.
- */
-function resolveGateWithPort(params: {
-  mentionGatePort: MentionGatePort;
-  ignoreOtherMentions: boolean;
-  hasAnyMention: boolean;
-  wasMentioned: boolean;
-  implicitMention: boolean;
-  allowTextCommands: boolean;
-  isControlCommand: boolean;
-  commandAuthorized: boolean;
-  requireMention: boolean;
-}): GroupMessageGateResult {
-  // Layer 1: QQ-specific ignoreOtherMentions
-  if (
-    params.ignoreOtherMentions &&
-    params.hasAnyMention &&
-    !params.wasMentioned &&
-    !params.implicitMention
-  ) {
-    return {
-      action: "drop_other_mention",
-      effectiveWasMentioned: false,
-      shouldBypassMention: false,
-    };
-  }
-
-  // Layer 2+3: delegate to SDK mention gate (includes command bypass)
-  const decision = params.mentionGatePort.resolveInboundMentionDecision({
-    facts: {
-      canDetectMention: true,
-      wasMentioned: params.wasMentioned,
-      hasAnyMention: params.hasAnyMention,
-      implicitMentionKinds: params.implicitMention ? ["reply_to_bot"] : [],
-    },
-    policy: {
-      isGroup: true,
-      requireMention: params.requireMention,
-      allowTextCommands: params.allowTextCommands,
-      hasControlCommand: params.isControlCommand,
-      commandAuthorized: params.commandAuthorized,
-    },
-  });
-
-  // Map SDK's shouldBlock (unauthorized command) to our action
-  if (params.allowTextCommands && params.isControlCommand && !params.commandAuthorized) {
-    return {
-      action: "block_unauthorized_command",
-      effectiveWasMentioned: false,
-      shouldBypassMention: false,
-    };
-  }
-
-  if (decision.shouldSkip) {
-    return {
-      action: "skip_no_mention",
-      effectiveWasMentioned: decision.effectiveWasMentioned,
-      shouldBypassMention: decision.shouldBypassMention,
-    };
-  }
-
-  return {
-    action: "pass",
-    effectiveWasMentioned: decision.effectiveWasMentioned,
-    shouldBypassMention: decision.shouldBypassMention,
-  };
-}
-
-/**
- * Test whether the sender is on the DM `allowFrom` list.
- */
-function isSenderAllowedForCommands(senderId: string, deps: InboundPipelineDeps): boolean {
-  const raw = deps.account.config?.allowFrom;
-  if (!Array.isArray(raw) || raw.length === 0) {
-    return true;
-  }
-  const normalized = normalizeQQBotAllowFrom(raw);
-  return createQQBotSenderMatcher(senderId)(normalized);
-}
-
-function recordGroupHistory(params: {
-  historyMap: Map<string, HistoryEntry[]> | undefined;
-  groupOpenid: string;
-  historyLimit: number;
-  event: QueuedMessage;
-  userContent: string;
-  historyPort: HistoryPort;
-  /** Local paths from processAttachments — enriches history with downloaded file paths. */
-  localPaths?: Array<string | null>;
-}): void {
-  const { historyMap, groupOpenid, historyLimit, event, userContent, historyPort, localPaths } =
-    params;
-  if (!historyMap || historyLimit <= 0) {
-    return;
-  }
-
-  const senderForHistory = event.senderName
-    ? `${event.senderName} (${event.senderId})`
-    : event.senderId;
-
-  const entry: HistoryEntry = {
-    sender: senderForHistory,
-    body: userContent,
-    timestamp: new Date(event.timestamp).getTime(),
-    messageId: event.messageId,
-    attachments: toAttachmentSummaries(event.attachments, localPaths),
-  };
-
-  historyPort.recordPendingHistoryEntry({
-    historyMap,
-    historyKey: groupOpenid,
-    limit: historyLimit,
-    entry,
-  });
-}

package/src/engine/gateway/stages/index.ts

@@ -1,18 +0,0 @@
-/**
- * Inbound pipeline stages — each stage is a pure(-ish) function that
- * transforms a subset of the pipeline's state. The main `inbound-pipeline`
- * module composes them in order.
- *
- * Keeping every stage in its own file makes the pipeline's control flow
- * obvious and lets each piece be unit-tested against tiny input fixtures
- * without spinning up the full gateway.
- */
-
-export * from "./access-stage.js";
-export * from "./assembly-stage.js";
-export * from "./content-stage.js";
-export * from "./envelope-stage.js";
-export * from "./group-gate-stage.js";
-export * from "./quote-stage.js";
-export * from "./refidx-stage.js";
-export { buildSkippedInboundContext } from "./stub-contexts.js";