@gakr-gakr/qqbot 0.1.0

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

@@ -0,0 +1,223 @@
+import type { HistoryPort } from "../../adapter/history.port.js";
+import type { QQBotInboundAccess } from "../../adapter/index.js";
+import type { MentionGatePort } from "../../adapter/mention-gate.port.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 type { GroupMessageGateResult } from "../../group/message-gating.js";
+import { getRefIndex } from "../../ref/store.js";
+import type { InboundContext, InboundGroupInfo, InboundPipelineDeps } from "../inbound-context.js";
+import { isMergedTurn, type QueuedMessage } from "../message-queue.js";
+
+interface GroupGatePass {
+  kind: "pass";
+  groupInfo: InboundGroupInfo;
+}
+
+interface GroupGateSkip {
+  kind: "skip";
+  groupInfo: InboundGroupInfo;
+  skipReason: NonNullable<InboundContext["skipReason"]>;
+}
+
+type GroupGateStageResult = GroupGatePass | GroupGateSkip;
+
+interface GroupGateStageInput {
+  event: QueuedMessage;
+  deps: InboundPipelineDeps;
+  accountId: string;
+  agentId?: string;
+  sessionKey: string;
+  userContent: string;
+  processedAttachments?: import("../inbound-attachments.js").ProcessedAttachments;
+  access: QQBotInboundAccess;
+}
+
+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>;
+
+  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;
+
+  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,
+  });
+
+  const activation = resolveGroupActivation({
+    cfg,
+    agentId: agentId ?? "default",
+    sessionKey,
+    configRequireMention: requireMention,
+    sessionStoreReader: deps.sessionStoreReader,
+  });
+
+  const content = (event.content ?? "").trim();
+  const isControlCommand = Boolean(deps.isControlCommand?.(content));
+  const commandAuthorized =
+    deps.allowTextCommands !== false && input.access.commandAccess.authorized;
+
+  const gate = resolveGateWithPort({
+    mentionGatePort: deps.adapters.mentionGate,
+    ignoreOtherMentions,
+    hasAnyMention: anyMention,
+    wasMentioned: explicitWasMentioned,
+    implicitMention,
+    allowTextCommands: deps.allowTextCommands !== false,
+    isControlCommand,
+    commandAuthorized,
+    requireMention: activation === "mention",
+  });
+
+  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,
+    },
+  };
+
+  if (gate.action === "pass") {
+    return { kind: "pass", groupInfo };
+  }
+
+  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 };
+}
+
+function resolveGateWithPort(params: {
+  mentionGatePort: MentionGatePort;
+  ignoreOtherMentions: boolean;
+  hasAnyMention: boolean;
+  wasMentioned: boolean;
+  implicitMention: boolean;
+  allowTextCommands: boolean;
+  isControlCommand: boolean;
+  commandAuthorized: boolean;
+  requireMention: boolean;
+}): GroupMessageGateResult {
+  if (
+    params.ignoreOtherMentions &&
+    params.hasAnyMention &&
+    !params.wasMentioned &&
+    !params.implicitMention
+  ) {
+    return {
+      action: "drop_other_mention",
+      effectiveWasMentioned: false,
+      shouldBypassMention: false,
+    };
+  }
+
+  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,
+    },
+  });
+
+  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,
+  };
+}
+
+function recordGroupHistory(params: {
+  historyMap: Map<string, HistoryEntry[]> | undefined;
+  groupOpenid: string;
+  historyLimit: number;
+  event: QueuedMessage;
+  userContent: string;
+  historyPort: HistoryPort;
+  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

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

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

@@ -0,0 +1,113 @@
+/**
+ * Quote stage — resolve the quoted-reply (`refMsgIdx`) if any.
+ *
+ * Three-level fallback mirrors the standalone build:
+ *   1. RefIndex cache hit → rich ReplyToInfo
+ *   2. `msg_elements[0]` present → re-process the quoted body
+ *   3. Otherwise → id-only placeholder so the pipeline still knows it's a reply
+ */
+
+import {
+  formatMessageReferenceForAgent,
+  type AttachmentProcessor,
+} from "../../ref/format-message-ref.js";
+import { formatRefEntryForAgent, getRefIndex } from "../../ref/store.js";
+import { MSG_TYPE_QUOTE } from "../../utils/text-parsing.js";
+import { formatVoiceText } from "../../utils/voice-text.js";
+import { processAttachments } from "../inbound-attachments.js";
+import type { InboundPipelineDeps, ReplyToInfo } from "../inbound-context.js";
+import type { QueuedMessage } from "../message-queue.js";
+
+/**
+ * Resolve the quote metadata for an inbound event.
+ *
+ * Returns `undefined` when the event is not a reply at all.
+ */
+export async function resolveQuote(
+  event: QueuedMessage,
+  deps: InboundPipelineDeps,
+): Promise<ReplyToInfo | undefined> {
+  if (!event.refMsgIdx) {
+    return undefined;
+  }
+
+  const { account, log } = deps;
+
+  // ---- Layer 1: cache hit ----
+  const refEntry = getRefIndex(event.refMsgIdx);
+  if (refEntry) {
+    log?.debug?.(
+      `Quote detected via refMsgIdx cache: refMsgIdx=${event.refMsgIdx}, sender=${refEntry.senderName ?? refEntry.senderId}`,
+    );
+    return {
+      id: event.refMsgIdx,
+      body: formatRefEntryForAgent(refEntry),
+      sender: refEntry.senderName ?? refEntry.senderId,
+      isQuote: true,
+    };
+  }
+
+  // ---- Layer 2: fall back to msg_elements[0] if this is a quote type ----
+  if (event.msgType === MSG_TYPE_QUOTE && event.msgElements?.[0]) {
+    try {
+      const refElement = event.msgElements[0];
+      const refData = {
+        content: refElement.content ?? "",
+        attachments: refElement.attachments,
+      };
+      const attachmentProcessor: AttachmentProcessor = {
+        processAttachments: async (atts, refCtx) => {
+          const result = await processAttachments(
+            atts as Array<{
+              content_type: string;
+              url: string;
+              filename?: string;
+              voice_wav_url?: string;
+              asr_refer_text?: string;
+            }>,
+            {
+              accountId: account.accountId,
+              cfg: refCtx.cfg,
+              audioConvert: deps.adapters.audioConvert,
+              log: refCtx.log,
+            },
+          );
+          return {
+            attachmentInfo: result.attachmentInfo,
+            voiceTranscripts: result.voiceTranscripts,
+            voiceTranscriptSources: result.voiceTranscriptSources,
+            attachmentLocalPaths: result.attachmentLocalPaths,
+          };
+        },
+        formatVoiceText: (transcripts) => formatVoiceText(transcripts),
+      };
+      const refPeerId =
+        event.type === "group" && event.groupOpenid ? event.groupOpenid : event.senderId;
+      const refBody = await formatMessageReferenceForAgent(
+        refData,
+        { appId: account.appId, peerId: refPeerId, cfg: account.config, log },
+        attachmentProcessor,
+      );
+      log?.debug?.(
+        `Quote detected via msg_elements[0] (cache miss): id=${event.refMsgIdx}, content="${(refBody ?? "").slice(0, 80)}..."`,
+      );
+      return {
+        id: event.refMsgIdx,
+        body: refBody || undefined,
+        isQuote: true,
+      };
+    } catch (refErr) {
+      log?.error(`Failed to format quoted message from msg_elements: ${String(refErr)}`);
+    }
+  } else {
+    log?.debug?.(
+      `Quote detected but no cache and msgType=${event.msgType}: refMsgIdx=${event.refMsgIdx}`,
+    );
+  }
+
+  // ---- Layer 3: id-only placeholder ----
+  return {
+    id: event.refMsgIdx,
+    isQuote: true,
+  };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * RefIdx persistence stage — writes the current message into the shared
+ * `refIndex` cache so future quote resolutions can find it.
+ *
+ * The stage also attaches voice transcripts (and their source) onto the
+ * cached attachment summaries so replies-to-this-message can render the
+ * original audio content inline instead of just a file handle.
+ *
+ * Pure data pipeline (no network I/O). Sync return value.
+ */
+
+import { setRefIndex } from "../../ref/store.js";
+import { buildAttachmentSummaries } from "../../utils/text-parsing.js";
+import type { ProcessedAttachments } from "../inbound-attachments.js";
+import type { QueuedMessage } from "../message-queue.js";
+
+/**
+ * Cache the current message under `msgIdx` (or the fallback `refIdx`
+ * returned by the typing-indicator call) so later quotes resolve.
+ *
+ * No-op when neither id is available.
+ */
+export function writeRefIndex(params: {
+  event: QueuedMessage;
+  parsedContent: string;
+  processed: ProcessedAttachments;
+  /** Optional refIdx returned by `InputNotify` — used when `msgIdx` is missing. */
+  inputNotifyRefIdx?: string;
+}): void {
+  const { event, parsedContent, processed, inputNotifyRefIdx } = params;
+
+  const currentMsgIdx = event.msgIdx ?? inputNotifyRefIdx;
+  if (!currentMsgIdx) {
+    return;
+  }
+
+  const attSummaries = buildAttachmentSummaries(event.attachments, processed.attachmentLocalPaths);
+  if (attSummaries && processed.voiceTranscripts.length > 0) {
+    let voiceIdx = 0;
+    for (const att of attSummaries) {
+      if (att.type === "voice" && voiceIdx < processed.voiceTranscripts.length) {
+        att.transcript = processed.voiceTranscripts[voiceIdx];
+        if (voiceIdx < processed.voiceTranscriptSources.length) {
+          att.transcriptSource = processed.voiceTranscriptSources[voiceIdx] as
+            | "stt"
+            | "asr"
+            | "tts"
+            | "fallback";
+        }
+        voiceIdx++;
+      }
+    }
+  }
+
+  setRefIndex(currentMsgIdx, {
+    content: parsedContent,
+    senderId: event.senderId,
+    senderName: event.senderName,
+    timestamp: new Date(event.timestamp).getTime(),
+    attachments: attSummaries,
+  });
+}

package/src/engine/gateway/stages/stub-contexts.ts

@@ -0,0 +1,77 @@
+import type { QQBotInboundAccess } from "../../adapter/index.js";
+import type { InboundContext, InboundGroupInfo } from "../inbound-context.js";
+import type { QueuedMessage } from "../message-queue.js";
+import type { TypingKeepAlive } from "../typing-keepalive.js";
+
+interface BaseStubFields {
+  event: QueuedMessage;
+  route: { sessionKey: string; accountId: string; agentId?: string };
+  isGroupChat: boolean;
+  peerId: string;
+  qualifiedTarget: string;
+  fromAddress: string;
+}
+
+function emptyInboundContext(fields: BaseStubFields): InboundContext {
+  return {
+    event: fields.event,
+    route: fields.route,
+    isGroupChat: fields.isGroupChat,
+    peerId: fields.peerId,
+    qualifiedTarget: fields.qualifiedTarget,
+    fromAddress: fields.fromAddress,
+    agentBody: "",
+    body: "",
+    groupSystemPrompt: undefined,
+    localMediaPaths: [],
+    localMediaTypes: [],
+    remoteMediaUrls: [],
+    uniqueVoicePaths: [],
+    uniqueVoiceUrls: [],
+    uniqueVoiceAsrReferTexts: [],
+    voiceMediaTypes: [],
+    hasAsrReferFallback: false,
+    voiceTranscriptSources: [],
+    replyTo: undefined,
+    commandAuthorized: false,
+    group: undefined,
+    blocked: false,
+    skipped: false,
+    typing: { keepAlive: null },
+    inputNotifyRefIdx: undefined,
+  };
+}
+
+export function buildBlockedInboundContext(
+  params: BaseStubFields & {
+    access: QQBotInboundAccess;
+  },
+): InboundContext {
+  return {
+    ...emptyInboundContext(params),
+    blocked: true,
+    blockReason: params.access.senderAccess.reasonCode,
+    blockReasonCode: params.access.senderAccess.reasonCode,
+    accessDecision: params.access.senderAccess.decision,
+  };
+}
+
+export function buildSkippedInboundContext(
+  params: BaseStubFields & {
+    group: InboundGroupInfo;
+    skipReason: NonNullable<InboundContext["skipReason"]>;
+    access: QQBotInboundAccess;
+    typing: { keepAlive: TypingKeepAlive | null };
+    inputNotifyRefIdx?: string;
+  },
+): InboundContext {
+  return {
+    ...emptyInboundContext(params),
+    group: params.group,
+    skipped: true,
+    skipReason: params.skipReason,
+    accessDecision: params.access.senderAccess.decision,
+    typing: params.typing,
+    inputNotifyRefIdx: params.inputNotifyRefIdx,
+  };
+}